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

package/data/static/schemas.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "description": "@valets/schema \u2014 consolidated schema bundle",
-  "generated": "2026-05-16T00:20:07.691826+00:00",
+  "generated": "2026-05-27T13:06:59.435619+00:00",
   "schemas": {
     "allowed-user": {
       "type": "object",
@@ -4394,25 +4394,34 @@
         ]
       }
     },
-    "outbound-message-kind": {
+    "outbound-message-format": {
+      "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)."
+    },
+    "outbound-message-purpose": {
       "type": "string",
       "enum": [
         "otp",
         "review_request",
-        "adhoc"
+        "adhoc",
+        "conversational"
       ],
-      "description": "Outbound WhatsApp message kind. Strict enum \u2014 new kinds require a schema version bump (GH#38)."
+      "description": "Business purpose of an outbound WhatsApp message \u2014 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)."
     },
     "outbound-message-status": {
       "type": "string",
       "enum": [
-        "accepted",
+        "queued",
         "sent",
         "delivered",
         "read",
         "failed"
       ],
-      "description": "Outbound WhatsApp message delivery status. Lifecycle: accepted \u2192 sent \u2192 delivered \u2192 read, or accepted \u2192 failed. Updated in-place by Meta delivery callbacks (GH#38)."
+      "description": "Outbound WhatsApp message delivery status. Lifecycle: queued \u2192 sent \u2192 delivered \u2192 read, or queued \u2192 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)."
     },
     "payment-method": {
       "type": "string",
@@ -5556,6 +5565,14 @@
       ],
       "description": "Human-readable WABA label identifying which Meta business number received the message (GH#36)."
     },
+    "whatsapp-button-sub-type": {
+      "type": "string",
+      "enum": [
+        "url",
+        "quick_reply"
+      ],
+      "description": "Sub-type of a WhatsApp template button parameter. Set when WhatsappTemplateParameter.component === \"button\" \u2014 maps to Meta `components[].sub_type` (GH#46)."
+    },
     "whatsapp-inbound-message": {
       "type": "object",
       "properties": {
@@ -5704,30 +5721,138 @@
         "context": null
       }
     },
-    "whatsapp-outbound-message": {
+    "whatsapp-outbound-lifecycle-event": {
       "type": "object",
       "properties": {
         "id": {
           "readOnly": true,
-          "description": "(Read-only) Firestore document ID \u2014 wamid on success, generated UUID on failure.",
+          "description": "(Read-only) Firestore document ID, auto-generated.",
           "type": [
             "string",
             "null"
           ]
         },
-        "messageId": {
-          "type": "string",
-          "x-immutable": true,
-          "description": "(Immutable) WhatsApp message ID (wamid) on success; generated UUID on send failure."
+        "type": {
+          "anyOf": [
+            {
+              "type": "string",
+              "enum": [
+                "send_attempt",
+                "status_callback",
+                "error"
+              ]
+            },
+            {
+              "type": "string"
+            }
+          ],
+          "description": "(Read-only) Event type \u2014 send_attempt | status_callback | error | future string.",
+          "readOnly": true
+        },
+        "at": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "(Read-only) When the event was recorded server-side.",
+          "readOnly": true
+        },
+        "status": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/outbound-message-status"
+            },
+            {
+              "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": "\u26a0\ufe0f BACKEND-INTERNAL \u2014 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.",
+      "example": {
+        "id": null,
+        "type": "phone",
+        "at": "at",
+        "status": "status",
+        "wamid": null,
+        "phoneNumberId": null,
+        "contactWaId": null,
+        "metaRequest": "metaRequest",
+        "metaResponse": "metaResponse",
+        "errorCode": null,
+        "errorDetail": "errorDetail"
+      }
+    },
+    "whatsapp-outbound-message": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID \u2014 auto-generated at enqueue time.",
+          "type": [
+            "string",
+            "null"
+          ]
         },
         "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": "#/definitions/waba-label",
-          "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": {
@@ -5735,52 +5860,119 @@
           "x-immutable": true,
           "description": "(Immutable) Meta WABA ID. Mirrors inbound `wabaId`."
         },
-        "sentAt": {
-          "$ref": "#/definitions/firestore-timestamp",
-          "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": "#/definitions/outbound-message-kind",
-          "description": "(Immutable) Message kind.",
+          "$ref": "#/definitions/outbound-message-format",
+          "description": "(Immutable) Message format: `text` or `template`. Set `text` xor `template` to match.",
           "x-immutable": true
         },
-        "templateName": {
-          "type": "string",
-          "x-immutable": true,
-          "description": "(Immutable) WhatsApp template name used for the send."
+        "text": {
+          "x-when": "Set only when kind === \"text\" \u2014 the free-form message body.",
+          "description": "Free-form message body. Present only when kind=text.",
+          "type": [
+            "string",
+            "null"
+          ]
         },
-        "status": {
-          "$ref": "#/definitions/outbound-message-status",
-          "description": "Delivery status. Updated in-place by Meta delivery callbacks."
+        "template": {
+          "x-when": "Set only when kind === \"template\".",
+          "description": "Template send payload. Present only when kind=template.",
+          "type": [
+            "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
         },
-        "contactWaId": {
-          "description": "Normalized wa_id returned by Meta on success. May differ from `to`.",
+        "purpose": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/outbound-message-purpose"
+            },
+            {
+              "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": {
+          "x-immutable": true,
+          "description": "Order reference. Present on review_request messages.",
           "type": [
             "string",
             "null"
           ]
         },
-        "appId": {
-          "description": "Tenant appId when applicable.",
+        "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": "#/definitions/firestore-timestamp",
+          "description": "(Immutable) Enqueue timestamp, set by the dashboard at create.",
+          "x-immutable": true
+        },
+        "status": {
+          "$ref": "#/definitions/outbound-message-status",
+          "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 \u2192 delivered \u2192 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": [
             "string",
             "null"
           ]
         },
-        "orderUuid": {
-          "description": "Order reference. Present on review_request messages 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": [
             "string",
             "null"
           ]
         },
-        "statusUpdatedAt": {
+        "sentAt": {
           "anyOf": [
             {
               "$ref": "#/definitions/firestore-timestamp"
@@ -5789,58 +5981,211 @@
               "type": "null"
             }
           ],
-          "description": "Timestamp of the last status update from a Meta delivery callback."
+          "readOnly": true,
+          "description": "(Read-only) When the backend sent the message to Meta."
         },
-        "failureCode": {
-          "description": "Meta error code. Present on failed sends only.",
-          "type": [
-            "integer",
-            "null"
+        "deliveredAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
           ],
-          "minimum": -9007199254740991,
-          "maximum": 9007199254740991
+          "readOnly": true,
+          "description": "(Read-only) When Meta reported delivery."
         },
-        "failureErrors": {
-          "description": "Raw Meta error objects. Present on failed sends only.",
-          "type": [
-            "array",
-            "null"
+        "readAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) When Meta reported the recipient read the message."
+        },
+        "failedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
           ],
-          "items": {}
+          "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 \u2014 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 \u2014 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.",
       "example": {
         "id": null,
-        "messageId": "mes_ref123",
         "to": "to",
         "waba": "waba",
         "wabaId": "wab_ref123",
-        "sentAt": "sentAt",
-        "phoneNumberId": "pho_ref123",
         "kind": "kind",
-        "templateName": "templateName",
-        "status": "status",
-        "contactWaId": null,
-        "appId": null,
+        "text": null,
+        "template": null,
+        "purpose": "purpose",
         "orderUuid": null,
-        "statusUpdatedAt": "statusUpdatedAt",
-        "failureCode": null,
-        "failureErrors": null
+        "sentBy": {
+          "uid": "user_u8x92kqm"
+        },
+        "createdAt": "createdAt",
+        "status": "status",
+        "wamid": null,
+        "error": null,
+        "sentAt": "sentAt",
+        "deliveredAt": "deliveredAt",
+        "readAt": "readAt",
+        "failedAt": "failedAt"
+      }
+    },
+    "whatsapp-template": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID \u2014 composite `{waba}__{name}__{language}`.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "waba": {
+          "$ref": "#/definitions/waba-label",
+          "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": "#/definitions/whatsapp-template-status",
+          "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": "#/definitions/whatsapp-template-component",
+                "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": "#/definitions/whatsapp-button-sub-type",
+                "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) \u2014 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 \u2014 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.",
+      "example": {
+        "id": null,
+        "waba": "waba",
+        "wabaId": "wab_ref123",
+        "name": "Amadou Diallo",
+        "language": "language",
+        "category": "category",
+        "status": "status",
+        "parameters": [
+          {
+            "name": "Amadou Diallo",
+            "component": "component"
+          }
+        ],
+        "preview": "preview"
       }
     },
+    "whatsapp-template-component": {
+      "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)."
+    },
+    "whatsapp-template-status": {
+      "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)."
+    },
     "payment-summary": {
       "type": "object",
       "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingenx-io/valets-schema-mcp-server",
-  "version": "0.1.10",
+  "version": "0.2.1",
   "description": "MCP server exposing @valets/schema documentation to AI agents",
   "type": "module",
   "main": "index.js",

package/data/docs/enums/outbound-message-kind.md

@@ -1,23 +0,0 @@
----
-title: "OutboundMessageKind"
-sidebar_label: "OutboundMessageKind"
-sidebar_position: 11
----
-
-# OutboundMessageKind
-
-|                |                                     |
-| -------------- | ----------------------------------- |
-| **Type**       | `enum (of string)`                  |
-| **Required**   | No                                  |
-| **Defined in** | #/definitions/outbound-message-kind |
-
-**Description:** Outbound WhatsApp message kind. Strict enum — new kinds require a schema version bump (GH#38).
-
-Must be one of:
-* "otp"
-* "review_request"
-* "adhoc"
-
-----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-16 at 00:20:07 +0000