@ingenx-io/valets-schema-mcp-server 0.1.10 → 0.2.1

package/data/static/openapi.yaml

@@ -122,25 +122,38 @@ components:
       - EXPIRED
       description: Core order lifecycle status (D03, D34). Universal across all business
         types. Replaces the Dashboard's legacy 20-value flat enum (MIG-11).
-    OutboundMessageKind:
+    OutboundMessageFormat:
+      type: string
+      enum:
+      - text
+      - template
+      description: Outbound WhatsApp message format. `text` is a free-form body (only
+        valid inside the 24h customer-care window); `template` is a pre-approved WhatsApp
+        template send. The backend is the authority on which is allowed (GH#43).
+    OutboundMessagePurpose:
       type: string
       enum:
       - otp
       - review_request
       - adhoc
-      description: Outbound WhatsApp message kind. Strict enum — new kinds require
-        a schema version bump (GH#38).
+      - conversational
+      description: Business purpose of an outbound WhatsApp message — orthogonal to
+        its format (see OutboundMessageFormat). `otp`/`review_request`/`adhoc` are
+        system-originated; `conversational` is a human agent reply from the dashboard
+        inbox. Optional signal carried for analytics/triggers (GH#43; supersedes the
+        GH#38 OutboundMessageKind).
     OutboundMessageStatus:
       type: string
       enum:
-      - accepted
+      - queued
       - sent
       - delivered
       - read
       - failed
-      description: 'Outbound WhatsApp message delivery status. Lifecycle: accepted
-        → sent → delivered → read, or accepted → failed. Updated in-place by Meta
-        delivery callbacks (GH#38).'
+      description: 'Outbound WhatsApp message delivery status. Lifecycle: queued →
+        sent → delivered → read, or queued → failed. The dashboard creates the message
+        with status `queued`; the whatsapp-server backend owns every transition after,
+        updating in place from Meta delivery callbacks (GH#43).'
     PaymentMethod:
       type: string
       enum:
@@ -261,6 +274,35 @@ components:
       - val
       description: Human-readable WABA label identifying which Meta business number
         received the message (GH#36).
+    WhatsappButtonSubType:
+      type: string
+      enum:
+      - url
+      - quick_reply
+      description: Sub-type of a WhatsApp template button parameter. Set when WhatsappTemplateParameter.component
+        === "button" — maps to Meta `components[].sub_type` (GH#46).
+    WhatsappTemplateComponent:
+      type: string
+      enum:
+      - header
+      - body
+      - button
+      description: WhatsApp template component a parameter targets. Determines which
+        Meta `components` entry the supplied value is placed in at send time (GH#46).
+    WhatsappTemplateStatus:
+      type: string
+      enum:
+      - APPROVED
+      - PENDING
+      - REJECTED
+      - PAUSED
+      - DISABLED
+      - IN_APPEAL
+      description: Meta review status of a WhatsApp message template, synced from
+        the WhatsApp Business API. Only APPROVED templates can be sent. The fuller
+        Meta status set is used deliberately (vs just APPROVED/PENDING/REJECTED) so
+        this enum has a distinct value signature from PaymentProofStatus in the JSON-Schema
+        $ref matcher (GH#43).
     FirestoreTimestamp:
       type: object
       properties:
@@ -4524,102 +4566,234 @@ components:
       description: Write payload for partial update (PATCH) of a WhatsappInboundMessage
         document. All fields optional. Fields marked `readOnly` or `x-immutable` must
         not be sent.
+    WhatsappOutboundLifecycleEvent:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        type:
+          anyOf:
+          - type: string
+            enum:
+            - send_attempt
+            - status_callback
+            - error
+          - type: string
+          description: (Read-only) Event type — send_attempt | status_callback | error
+            | future string.
+          readOnly: true
+        at:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) When the event was recorded server-side.
+          readOnly: true
+        status:
+          anyOf:
+          - $ref: '#/components/schemas/OutboundMessageStatus'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Resulting/observed status, when this event implies
+            one.
+        wamid:
+          readOnly: true
+          description: (Read-only) WhatsApp message ID, if known at this point in
+            the lifecycle.
+          type:
+          - string
+          - 'null'
+        phoneNumberId:
+          readOnly: true
+          description: (Read-only) Meta phone number ID (the specific line within
+            the WABA) used for the attempt.
+          type:
+          - string
+          - 'null'
+        contactWaId:
+          readOnly: true
+          description: (Read-only) Normalized wa_id returned by Meta. May differ from
+            the recipient `to`.
+          type:
+          - string
+          - 'null'
+        metaRequest:
+          readOnly: true
+          description: (Read-only) Raw outbound payload sent to the Meta Graph API.
+        metaResponse:
+          readOnly: true
+          description: (Read-only) Raw Meta Graph API response.
+        errorCode:
+          readOnly: true
+          description: (Read-only) Meta error code. Present on failed attempts.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        errorDetail:
+          readOnly: true
+          description: (Read-only) Raw Meta error object(s).
+      required:
+      - type
+      - at
+      additionalProperties: false
+      x-internal: true
+      description: '⚠️ BACKEND-INTERNAL — not a consumer contract. WhatsappOutboundLifecycleEvent:
+        append-only backend log for reconstituting an outbound message lifecycle (GH#43).
+        Collection: whatsapp_outbound_messages/{messageId}/lifecycle_events/{eventId}.
+        Written/read only by the whatsapp-server backend.'
     WhatsappOutboundMessage:
       type: object
       properties:
         id:
           readOnly: true
-          description: (Read-only) Firestore document ID — wamid on success, generated
-            UUID on failure.
+          description: (Read-only) Firestore document ID — auto-generated at enqueue
+            time.
           type:
           - string
           - 'null'
-        messageId:
-          type: string
-          x-immutable: true
-          description: (Immutable) WhatsApp message ID (wamid) on success; generated
-            UUID on send failure.
         to:
           type: string
           x-immutable: true
-          description: (Immutable) Recipient phone number in E.164 format. Mirrors
-            inbound `from`.
+          description: (Immutable) Recipient phone number in E.164 format. Must match
+            the inbound `from` for the same conversation.
         waba:
           $ref: '#/components/schemas/WabaLabel'
-          description: (Immutable) WABA that sent the message. Mirrors inbound `waba`.
+          description: (Immutable) WABA that will send the message. Mirrors inbound
+            `waba`.
           x-immutable: true
         wabaId:
           type: string
           x-immutable: true
           description: (Immutable) Meta WABA ID. Mirrors inbound `wabaId`.
-        sentAt:
-          $ref: '#/components/schemas/FirestoreTimestamp'
-          description: (Read-only) Server-side send timestamp. Mirrors inbound `receivedAt`.
-          readOnly: true
-        phoneNumberId:
-          type: string
-          x-immutable: true
-          description: (Immutable) Meta phone number ID used for the send (specific
-            line within the WABA).
         kind:
-          $ref: '#/components/schemas/OutboundMessageKind'
-          description: (Immutable) Message kind.
-          x-immutable: true
-        templateName:
-          type: string
+          $ref: '#/components/schemas/OutboundMessageFormat'
+          description: '(Immutable) Message format: `text` or `template`. Set `text`
+            xor `template` to match.'
           x-immutable: true
-          description: (Immutable) WhatsApp template name used for the send.
-        status:
-          $ref: '#/components/schemas/OutboundMessageStatus'
-          description: Delivery status. Updated in-place by Meta delivery callbacks.
-        contactWaId:
-          description: Normalized wa_id returned by Meta on success. May differ from
-            `to`.
+        text:
+          x-when: Set only when kind === "text" — the free-form message body.
+          description: Free-form message body. Present only when kind=text.
           type:
           - string
           - 'null'
-        appId:
-          description: Tenant appId when applicable.
+        template:
+          x-when: Set only when kind === "template".
+          description: Template send payload. Present only when kind=template.
           type:
-          - string
+          - object
           - 'null'
+          properties:
+            name:
+              type: string
+              description: WhatsApp template name (must exist and be APPROVED in whatsapp_templates).
+            language:
+              type: string
+              description: Template language/locale code (e.g. "en", "fr").
+            variables:
+              description: Template variable values, keyed by the variable name declared
+                on the template.
+              type: object
+              propertyNames:
+                type: string
+              additionalProperties:
+                type: string
+          required:
+          - name
+          - language
+          additionalProperties: false
+        purpose:
+          anyOf:
+          - $ref: '#/components/schemas/OutboundMessagePurpose'
+          - type: 'null'
+          x-immutable: true
+          x-note: Business purpose, orthogonal to `kind`. Carried for analytics/triggers;
+            defaults to conversational for dashboard agent replies.
+          description: Business purpose (otp | review_request | adhoc | conversational).
+            Optional.
         orderUuid:
-          description: Order reference. Present on review_request messages only.
+          x-immutable: true
+          description: Order reference. Present on review_request messages.
           type:
           - string
           - 'null'
-        statusUpdatedAt:
-          anyOf:
-          - $ref: '#/components/schemas/FirestoreTimestamp'
-          - type: 'null'
-          description: Timestamp of the last status update from a Meta delivery callback.
-        failureCode:
-          description: Meta error code. Present on failed sends only.
+        sentBy:
+          type: object
+          properties:
+            uid:
+              type: string
+              description: Firebase Auth UID of the dashboard user who enqueued the
+                message.
+            email:
+              description: Email of the sender, if available.
+              type: string
+          required:
+          - uid
+          additionalProperties: false
+          x-immutable: true
+          description: (Immutable) Dashboard actor who enqueued the message.
+        createdAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Immutable) Enqueue timestamp, set by the dashboard at create.
+          x-immutable: true
+        status:
+          $ref: '#/components/schemas/OutboundMessageStatus'
+          description: Delivery status. Created as `queued` by the dashboard; updated
+            in place by the backend.
+          x-note: Dashboard must create with `queued`. The backend owns every transition
+            after (sent → delivered → read, or failed).
+        wamid:
+          readOnly: true
+          description: (Read-only) WhatsApp message ID returned by Meta once the backend
+            sends. Absent while queued or on failure.
           type:
-          - integer
+          - string
           - 'null'
-          minimum: -9007199254740991
-          maximum: 9007199254740991
-        failureErrors:
-          description: Raw Meta error objects. Present on failed sends only.
+        error:
+          readOnly: true
+          description: (Read-only) Human-readable failure reason. Present on status=failed.
+            Raw Meta error detail lives in the lifecycle_events subcollection.
           type:
-          - array
+          - string
           - 'null'
-          items: {}
+        sentAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When the backend sent the message to Meta.
+        deliveredAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When Meta reported delivery.
+        readAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When Meta reported the recipient read the message.
+        failedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When the send failed.
       required:
-      - messageId
       - to
       - waba
       - wabaId
-      - sentAt
-      - phoneNumberId
       - kind
-      - templateName
+      - sentBy
+      - createdAt
       - status
       additionalProperties: false
-      description: 'WhatsappOutboundMessage — outbound WhatsApp message persisted
-        at send time (GH#38). Collection: whatsapp_outbound_messages/{docId}. Top-level
-        scope. Symmetric counterpart to WhatsappInboundMessage (GH#36).'
+      description: 'WhatsappOutboundMessage — Firestore-as-the-bus outbox doc (GH#43).
+        Collection: whatsapp_outbound_messages/{docId}. Top-level scope; mirrors WhatsappInboundMessage.
+        Dashboard enqueues `queued`; backend sends and owns the lifecycle.'
     WhatsappOutboundMessageCreate:
       allOf:
       - $ref: '#/components/schemas/WhatsappOutboundMessage'
@@ -4627,13 +4801,12 @@ components:
         Fields marked `readOnly` are server-set and must not be included. Fields marked
         `x-immutable` may be set once at creation.
       required:
-      - messageId
       - to
       - waba
       - wabaId
-      - phoneNumberId
       - kind
-      - templateName
+      - sentBy
+      - createdAt
       - status
     WhatsappOutboundMessageUpdate:
       allOf:
@@ -4641,6 +4814,96 @@ components:
       description: Write payload for partial update (PATCH) of a WhatsappOutboundMessage
         document. All fields optional. Fields marked `readOnly` or `x-immutable` must
         not be sent.
+    WhatsappTemplate:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID — composite `{waba}__{name}__{language}`.
+          type:
+          - string
+          - 'null'
+        waba:
+          $ref: '#/components/schemas/WabaLabel'
+          description: (Read-only) WABA label this template is approved on. Templates
+            are WABA-scoped. Mirrors WhatsappOutboundMessage.waba.
+          readOnly: true
+        wabaId:
+          type: string
+          readOnly: true
+          description: (Read-only) Meta WABA ID this template belongs to. The sender
+            must verify its phone number belongs to this WABA before using the template.
+        name:
+          type: string
+          readOnly: true
+          description: (Read-only) Template name as registered with Meta.
+        language:
+          type: string
+          readOnly: true
+          description: (Read-only) Template language/locale code (e.g. "en", "fr").
+        category:
+          type: string
+          readOnly: true
+          description: (Read-only) Meta template category (e.g. MARKETING, UTILITY,
+            AUTHENTICATION).
+        status:
+          $ref: '#/components/schemas/WhatsappTemplateStatus'
+          description: (Read-only) Meta review status. Only APPROVED templates can
+            be sent.
+          readOnly: true
+        parameters:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                description: Parameter name/placeholder (e.g. "1"). Matches a key
+                  in WhatsappOutboundMessage.template.variables.
+              component:
+                $ref: '#/components/schemas/WhatsappTemplateComponent'
+                description: 'Which template component this parameter targets: header
+                  | body | button.'
+              buttonIndex:
+                description: 0-based button position. Present only when component=button
+                  (Meta requires a string index at send time).
+                type: integer
+                minimum: -9007199254740991
+                maximum: 9007199254740991
+              buttonSubType:
+                $ref: '#/components/schemas/WhatsappButtonSubType'
+                description: Button sub-type (url | quick_reply). Present only when
+                  component=button.
+            required:
+            - name
+            - component
+            additionalProperties: false
+            description: Declared WhatsApp template parameter with component placement
+              (GH#46).
+          readOnly: true
+          description: (Read-only) Declared parameters with component placement. Supersedes
+            the flat `variables` list (GH#46) — lets the send group values into the
+            correct header/body/button components. A message supplies values keyed
+            by `name` via WhatsappOutboundMessage.template.variables.
+        preview:
+          type: string
+          readOnly: true
+          description: (Read-only) Rendered preview text for display in the dashboard
+            picker.
+      required:
+      - waba
+      - wabaId
+      - name
+      - language
+      - category
+      - status
+      - parameters
+      - preview
+      additionalProperties: false
+      description: 'WhatsappTemplate — Meta-approved template synced from the WhatsApp
+        Business API (GH#43; parameter placement GH#46). Collection: whatsapp_templates/{docId},
+        doc ID `{waba}__{name}__{language}`. WABA-scoped; backend-synced; dashboard
+        reads only.'
     PaymentSummary:
       type: object
       properties: