Communicable

trait:
  name: Communicable
  version: 1.0.0
  description: |
    Canonical communication trait that unifies multi-channel delivery, template governance,
    delivery policies, and threaded conversations derived from R20.1/R20.6 research. Provides
    orchestration-ready schemas for channels, messages, policies, and conversations with
    Preferenceable/Authable/Classifiable integration points.
  category: communication
  tags:
    - notification
    - messaging
    - template
    - delivery
    - conversation

parameters:
  - name: channelTypes
    type: string[]
    required: false
    default:
      - email
      - sms
      - push
      - in_app
      - webhook
    description: Channels enabled for the tenant (R20.1 Part 2.1 multi-channel taxonomy).
  - name: supportConversations
    type: boolean
    required: false
    default: true
    description: Toggle for threaded conversations in addition to standalone messages.

schema:
  channel_catalog:
    type: Channel[]
    required: true
    description: Provider configuration for each channel (SMTP/Twilio/FCM/Webhook).
    examples:
      [
        [
          {
            "id": "44444444-dddd-4ddd-8ddd-dddddddddddd",
            "name": "Primary Email (SMTP)",
            "type": "email",
          },
          {
            "id": "55555555-eeee-4eee-8eee-eeeeeeeeeeee",
            "name": "Twilio SMS",
            "type": "sms",
          },
          {
            "id": "66666666-ffff-4fff-8fff-ffffffffffff",
            "name": "FCM Push",
            "type": "push",
          },
          {
            "id": "77777777-0000-4000-8000-000000000000",
            "name": "Realtime In-App",
            "type": "in_app",
          },
        ],
      ]
    default: []
  template_catalog:
    type: Template[]
    required: true
    description: Localized template definitions with declared variables per R20.1 Part 2.3.
    examples:
      [
        [
          {
            "id": "88888888-1111-4111-8111-111111111111",
            "name": "Welcome Email",
            "channelType": "email",
            "subject": "Welcome to OODS Foundry, {{firstName}}!",
            "body": "Hi {{firstName}},\n\nThanks for joining {{workspaceName}}. Activate your account using {{activationLink}}.",
            "variables": ["firstName", "workspaceName", "activationLink"],
            "locale": "en-US",
          },
          {
            "id": "99999999-2222-4222-8222-222222222222",
            "name": "Password Reset Email",
            "channelType": "email",
            "subject": "Reset your OODS Foundry password",
            "body": "Hello {{firstName}},\n\nWe received a request to reset your password. Use this code: {{resetCode}}.",
            "variables": ["firstName", "resetCode"],
            "locale": "en-US",
          },
          {
            "id": "aaaaaaa1-3333-4333-8333-333333333333",
            "name": "In-App Notification",
            "channelType": "in_app",
            "subject": "New document shared with you",
            "body": '{{actorName}} shared "{{documentName}}" with you. Review it before {{dueDate}}.',
            "variables": ["actorName", "documentName", "dueDate"],
            "locale": "en-US",
          },
        ],
      ]
    default: []
  delivery_policies:
    type: DeliveryPolicy[]
    required: true
    description: Retry/throttle/quiet-hour policies (R20.1 Part 3 lifecycle).
    default: []
  messages:
    type: Message[]
    required: false
    description: Atomic message payloads queued for delivery (R20.6 Part 1.2 primitives).
    default: []
  conversations:
    type: Conversation[]
    required: false
    description: Multi-party threaded conversations with membership metadata (R20.6 Part 3.3).
    default: []
  message_statuses:
    type: MessageStatusEntry[]
    required: false
    description: Delivery state machine transitions (queued → sent → delivered → failed → retried → read).
    default: []

semantics:
  channel_catalog:
    semantic_type: communication.channels
    token_mapping: "--sys-communication-accent"
    ui_hints:
      component: ChannelGrid
      badges: channel_catalog[].type
  template_catalog:
    semantic_type: communication.templates
    token_mapping: "--sys-communication-muted"
    ui_hints:
      component: TemplateDrawer
      variableBadge: template_catalog[].variables
  delivery_policies:
    semantic_type: communication.delivery_policy
    token_mapping: "--sys-communication-accent"
    ui_hints:
      component: DeliveryPolicyCapsule
  messages:
    semantic_type: communication.messages
    token_mapping: "--sys-communication-success"
    ui_hints:
      component: MessageTimeline
  conversations:
    semantic_type: communication.conversations
    token_mapping: "--sys-communication-accent"
    ui_hints:
      component: ConversationViewer

view_extensions:
  list:
    - component: MessageStatusBadge
      position: before
      priority: 90
      props:
        statusesField: message_statuses
  detail:
    - component: CommunicationDetailPanel
      position: main
      priority: 80
      props:
        channelsField: channel_catalog
        templatesField: template_catalog
        policiesField: delivery_policies
        conversationsField: conversations
  form:
    - component: TemplatePicker
      position: main
      props:
        templatesField: template_catalog
        channelsField: channel_catalog

tokens:
  communication.card.bg: "var(--sys-surface-raised)"
  communication.card.border: "var(--sys-communication-muted)"
  communication.status.success: "var(--sys-communication-success)"
  communication.status.error: "var(--sys-communication-error)"

dependencies:
  # Communicable integrates with Preferenceable (channel prefs) and Authable (sender auth).
  # Classifiable is an optional enrichment (not yet defined in this system).
  - Preferenceable
  - Authable

metadata:
  created: "2025-11-20"
  owners:
    - notifications@oods.systems
  maturity: experimental
  accessibility:
    keyboard: ChannelGrid keeps linear tab stops and roving focus for template previews.
    screenreader: MessageEventTimeline announces delivery transitions with ARIA live updates per R20.6 guidance.
  regionsUsed:
    - list
    - detail
    - form
  references:
    - "R20.1 Canonical Notification Model"
    - "R20.6 Foundational Analysis of Modern Message and Communication Systems"