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

package/data/docs/models/whatsapp-template.md

@@ -0,0 +1,283 @@
+---
+title: "WhatsappTemplate"
+sidebar_label: "WhatsappTemplate"
+sidebar_position: 31
+---
+
+# WhatsappTemplate
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "id": null,
+  "waba": "waba",
+  "wabaId": "wab_ref123",
+  "name": "Amadou Diallo",
+  "language": "language",
+  "category": "category",
+  "status": "status",
+  "parameters": [
+    {
+      "name": "Amadou Diallo",
+      "component": "component"
+    }
+  ],
+  "preview": "preview"
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `waba`](#waba)
+- [3. Property `wabaId`](#wabaId)
+- [4. Property `name`](#name)
+- [5. Property `language`](#language)
+- [6. Property `category`](#category)
+- [7. Property `status`](#status)
+- [8. Property `parameters`](#parameters)
+  - [8.1. parameters items](#parameters_items)
+    - [8.1.1. Property `name`](#parameters_items_name)
+    - [8.1.2. Property `component`](#parameters_items_component)
+    - [8.1.3. Property `buttonIndex`](#parameters_items_buttonIndex)
+    - [8.1.4. Property `buttonSubType`](#parameters_items_buttonSubType)
+- [9. Property `preview`](#preview)
+
+|                           |                                 |
+| ------------------------- | ------------------------------- |
+| **Type**                  | `object`                        |
+| **Required**              | No                              |
+| **Additional properties** | Not allowed                     |
+| **Defined in**            | #/definitions/whatsapp-template |
+
+**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.
+
+| Property                     | Pattern | Type             | Deprecated | Definition                                | Title/Description                                                                                                                                                                                                                                                                 |
+| ---------------------------- | ------- | ---------------- | ---------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| - [id](#id )                 | No      | string or null   | No         | -                                         | (Read-only) Firestore document ID — composite \`\{waba\}__\{name\}__\{language\}\`.                                                                                                                                                                                                     |
+| + [waba](#waba )             | No      | enum (of string) | No         | In #/definitions/waba-label               | (Read-only) WABA label this template is approved on. Templates are WABA-scoped. Mirrors WhatsappOutboundMessage.waba.                                                                                                                                                             |
+| + [wabaId](#wabaId )         | No      | string           | No         | -                                         | (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](#name )             | No      | string           | No         | -                                         | (Read-only) Template name as registered with Meta.                                                                                                                                                                                                                                |
+| + [language](#language )     | No      | string           | No         | -                                         | (Read-only) Template language/locale code (e.g. "en", "fr").                                                                                                                                                                                                                      |
+| + [category](#category )     | No      | string           | No         | -                                         | (Read-only) Meta template category (e.g. MARKETING, UTILITY, AUTHENTICATION).                                                                                                                                                                                                     |
+| + [status](#status )         | No      | enum (of string) | No         | In #/definitions/whatsapp-template-status | (Read-only) Meta review status. Only APPROVED templates can be sent.                                                                                                                                                                                                              |
+| + [parameters](#parameters ) | No      | array of object  | No         | -                                         | (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](#preview )       | No      | string           | No         | -                                         | (Read-only) Rendered preview text for display in the dashboard picker.                                                                                                                                                                                                            |
+
+## <a name="id"></a>1. Property `id`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only) Firestore document ID — composite `\{waba\}__\{name\}__\{language\}`.
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="waba"></a>2. Property `waba`
+
+|                |                          |
+| -------------- | ------------------------ |
+| **Type**       | `enum (of string)`       |
+| **Required**   | Yes                      |
+| **Defined in** | #/definitions/waba-label |
+
+**Description:** (Read-only) WABA label this template is approved on. Templates are WABA-scoped. Mirrors WhatsappOutboundMessage.waba.
+
+Must be one of:
+* "cmz"
+* "val"
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="wabaId"></a>3. Property `wabaId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**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.
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="name"></a>4. Property `name`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Template name as registered with Meta.
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="language"></a>5. Property `language`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Template language/locale code (e.g. "en", "fr").
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="category"></a>6. Property `category`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Meta template category (e.g. MARKETING, UTILITY, AUTHENTICATION).
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="status"></a>7. Property `status`
+
+|                |                                        |
+| -------------- | -------------------------------------- |
+| **Type**       | `enum (of string)`                     |
+| **Required**   | Yes                                    |
+| **Defined in** | #/definitions/whatsapp-template-status |
+
+**Description:** (Read-only) Meta review status. Only APPROVED templates can be sent.
+
+Must be one of:
+* "APPROVED"
+* "PENDING"
+* "REJECTED"
+* "PAUSED"
+* "DISABLED"
+* "IN_APPEAL"
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="parameters"></a>8. Property `parameters`
+
+|              |                   |
+| ------------ | ----------------- |
+| **Type**     | `array of object` |
+| **Required** | Yes               |
+
+**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.
+
+|                      | Array restrictions |
+| -------------------- | ------------------ |
+| **Min items**        | N/A                |
+| **Max items**        | N/A                |
+| **Items unicity**    | False              |
+| **Additional items** | False              |
+| **Tuple validation** | See below          |
+
+| Each item of this array must be       | Description                                                            |
+| ------------------------------------- | ---------------------------------------------------------------------- |
+| [parameters items](#parameters_items) | Declared WhatsApp template parameter with component placement (GH#46). |
+
+### <a name="parameters_items"></a>8.1. parameters items
+
+|                           |             |
+| ------------------------- | ----------- |
+| **Type**                  | `object`    |
+| **Required**              | No          |
+| **Additional properties** | Not allowed |
+
+**Description:** Declared WhatsApp template parameter with component placement (GH#46).
+
+| Property                                            | Pattern | Type             | Deprecated | Definition                                   | Title/Description                                                                                        |
+| --------------------------------------------------- | ------- | ---------------- | ---------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| + [name](#parameters_items_name )                   | No      | string           | No         | -                                            | Parameter name/placeholder (e.g. "1"). Matches a key in WhatsappOutboundMessage.template.variables.      |
+| + [component](#parameters_items_component )         | No      | enum (of string) | No         | In #/definitions/whatsapp-template-component | Which template component this parameter targets: header \| body \| button.                               |
+| - [buttonIndex](#parameters_items_buttonIndex )     | No      | integer          | No         | -                                            | 0-based button position. Present only when component=button (Meta requires a string index at send time). |
+| - [buttonSubType](#parameters_items_buttonSubType ) | No      | enum (of string) | No         | In #/definitions/whatsapp-button-sub-type    | Button sub-type (url \| quick_reply). Present only when component=button.                                |
+
+#### <a name="parameters_items_name"></a>8.1.1. Property `name`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Parameter name/placeholder (e.g. "1"). Matches a key in WhatsappOutboundMessage.template.variables.
+
+#### <a name="parameters_items_component"></a>8.1.2. Property `component`
+
+|                |                                           |
+| -------------- | ----------------------------------------- |
+| **Type**       | `enum (of string)`                        |
+| **Required**   | Yes                                       |
+| **Defined in** | #/definitions/whatsapp-template-component |
+
+**Description:** Which template component this parameter targets: header | body | button.
+
+Must be one of:
+* "header"
+* "body"
+* "button"
+
+#### <a name="parameters_items_buttonIndex"></a>8.1.3. Property `buttonIndex`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | No        |
+
+**Description:** 0-based button position. Present only when component=button (Meta requires a string index at send time).
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+#### <a name="parameters_items_buttonSubType"></a>8.1.4. Property `buttonSubType`
+
+|                |                                        |
+| -------------- | -------------------------------------- |
+| **Type**       | `enum (of string)`                     |
+| **Required**   | No                                     |
+| **Defined in** | #/definitions/whatsapp-button-sub-type |
+
+**Description:** Button sub-type (url | quick_reply). Present only when component=button.
+
+Must be one of:
+* "url"
+* "quick_reply"
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="preview"></a>9. Property `preview`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Rendered preview text for display in the dashboard picker.
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-27 at 13:06:59 +0000
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::

package/data/static/llms.txt

@@ -4,7 +4,7 @@
 > Source of truth: Zod schemas in packages/schema/src/
 > All Firestore documents are scoped under companies/{companyId}/
 
-> Generated: 2026-05-16
+> Generated: 2026-05-27
 
 ---
 
@@ -50,13 +50,17 @@ Values: EARNED, REDEEMED, ADJUSTED, EXPIRED, BONUS, REFUND
 Core order lifecycle status (D03, D34). Universal across all business types. Replaces the Dashboard's legacy 20-value flat enum (MIG-11).
 Values: PENDING, CONFIRMED, PROCESSING, READY, COMPLETED, CANCELLED, EXPIRED
 
-### OutboundMessageKind
-Outbound WhatsApp message kind. Strict enum — new kinds require a schema version bump (GH#38).
-Values: otp, review_request, adhoc
+### OutboundMessageFormat
+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).
+Values: text, template
+
+### OutboundMessagePurpose
+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).
+Values: otp, review_request, adhoc, conversational
 
 ### OutboundMessageStatus
-Outbound WhatsApp message delivery status. Lifecycle: accepted → sent → delivered → read, or accepted → failed. Updated in-place by Meta delivery callbacks (GH#38).
-Values: accepted, sent, delivered, read, failed
+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).
+Values: queued, sent, delivered, read, failed
 
 ### PaymentMethod
 Unified payment method set with African + global methods (D02).
@@ -106,6 +110,18 @@ Values: VALID, USED, CANCELLED
 Human-readable WABA label identifying which Meta business number received the message (GH#36).
 Values: cmz, val
 
+### WhatsappButtonSubType
+Sub-type of a WhatsApp template button parameter. Set when WhatsappTemplateParameter.component === "button" — maps to Meta `components[].sub_type` (GH#46).
+Values: url, quick_reply
+
+### WhatsappTemplateComponent
+WhatsApp template component a parameter targets. Determines which Meta `components` entry the supplied value is placed in at send time (GH#46).
+Values: header, body, button
+
+### WhatsappTemplateStatus
+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).
+Values: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, IN_APPEAL
+
 ---
 
 ## Models
@@ -1518,47 +1534,128 @@ Example:
 }
 ```
 
+### WhatsappOutboundLifecycleEvent
+Fields: 11 (2 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| type | any | yes | (Read-only) Event type — send_attempt | status_callback | error | future string. |
+| at | FirestoreTimestamp | yes | (Read-only) When the event was recorded server-side. |
+| status | any | no | (Read-only) Resulting/observed status, when this event implies one. |
+| wamid | ['string', 'null'] | no | (Read-only) WhatsApp message ID, if known at this point in the lifecycle. |
+| phoneNumberId | ['string', 'null'] | no | (Read-only) Meta phone number ID (the specific line within the WABA) used for the attempt. |
+| contactWaId | ['string', 'null'] | no | (Read-only) Normalized wa_id returned by Meta. May differ from the recipient `to`. |
+| metaRequest | any | no | (Read-only) Raw outbound payload sent to the Meta Graph API. |
+| metaResponse | any | no | (Read-only) Raw Meta Graph API response. |
+| errorCode | ['integer', 'null'] | no | (Read-only) Meta error code. Present on failed attempts. |
+| errorDetail | any | no | (Read-only) Raw Meta error object(s). |
+
+Example:
+```json
+{
+  "id": null,
+  "type": "phone",
+  "at": "at",
+  "status": "status",
+  "wamid": null,
+  "phoneNumberId": null,
+  "contactWaId": null,
+  "metaRequest": "metaRequest",
+  "metaResponse": "metaResponse",
+  "errorCode": null,
+  "errorDetail": "errorDetail"
+}
+```
+
 ### WhatsappOutboundMessage
-Fields: 16 (9 required)
+Fields: 18 (7 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| id | ['string', 'null'] | no | (Read-only) Firestore document ID — wamid on success, generated UUID on failure. |
-| messageId | string | yes | (Immutable) WhatsApp message ID (wamid) on success; generated UUID on send failure. |
-| to | string | yes | (Immutable) Recipient phone number in E.164 format. Mirrors inbound `from`. |
-| waba | WabaLabel | yes | (Immutable) WABA that sent the message. Mirrors inbound `waba`. |
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID — auto-generated at enqueue time. |
+| to | string | yes | (Immutable) Recipient phone number in E.164 format. Must match the inbound `from` for the same conversation. |
+| waba | WabaLabel | yes | (Immutable) WABA that will send the message. Mirrors inbound `waba`. |
 | wabaId | string | yes | (Immutable) Meta WABA ID. Mirrors inbound `wabaId`. |
-| sentAt | FirestoreTimestamp | yes | (Read-only) Server-side send timestamp. Mirrors inbound `receivedAt`. |
-| phoneNumberId | string | yes | (Immutable) Meta phone number ID used for the send (specific line within the WABA). |
-| kind | OutboundMessageKind | yes | (Immutable) Message kind. |
-| templateName | string | yes | (Immutable) WhatsApp template name used for the send. |
-| status | OutboundMessageStatus | yes | Delivery status. Updated in-place by Meta delivery callbacks. |
-| contactWaId | ['string', 'null'] | no | Normalized wa_id returned by Meta on success. May differ from `to`. |
-| appId | ['string', 'null'] | no | Tenant appId when applicable. |
-| orderUuid | ['string', 'null'] | no | Order reference. Present on review_request messages only. |
-| statusUpdatedAt | any | no | Timestamp of the last status update from a Meta delivery callback. |
-| failureCode | ['integer', 'null'] | no | Meta error code. Present on failed sends only. |
-| failureErrors | ['array', 'null'] | no | Raw Meta error objects. Present on failed sends only. |
+| kind | OutboundMessageFormat | yes | (Immutable) Message format: `text` or `template`. Set `text` xor `template` to match. |
+| text | ['string', 'null'] | no | Free-form message body. Present only when kind=text. |
+| template | ['object', 'null'] | no | Template send payload. Present only when kind=template. |
+| purpose | any | no | Business purpose (otp | review_request | adhoc | conversational). Optional. |
+| orderUuid | ['string', 'null'] | no | Order reference. Present on review_request messages. |
+| sentBy | object | yes | (Immutable) Dashboard actor who enqueued the message. |
+| sentBy.uid | string | yes | Firebase Auth UID of the dashboard user who enqueued the message. |
+| sentBy.email | string | no | Email of the sender, if available. |
+| createdAt | FirestoreTimestamp | yes | (Immutable) Enqueue timestamp, set by the dashboard at create. |
+| status | OutboundMessageStatus | yes | Delivery status. Created as `queued` by the dashboard; updated in place by the backend. |
+| wamid | ['string', 'null'] | no | (Read-only) WhatsApp message ID returned by Meta once the backend sends. Absent while queued or on failure. |
+| error | ['string', 'null'] | no | (Read-only) Human-readable failure reason. Present on status=failed. Raw Meta error detail lives in the lifecycle_events subcollection. |
+| sentAt | any | no | (Read-only) When the backend sent the message to Meta. |
+| deliveredAt | any | no | (Read-only) When Meta reported delivery. |
+| readAt | any | no | (Read-only) When Meta reported the recipient read the message. |
+| failedAt | any | no | (Read-only) When the send failed. |
 
 Example:
 ```json
 {
   "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"
+}
+```
+
+### WhatsappTemplate
+Fields: 9 (8 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID — composite `{waba}__{name}__{language}`. |
+| waba | WabaLabel | yes | (Read-only) WABA label this template is approved on. Templates are WABA-scoped. Mirrors WhatsappOutboundMessage.waba. |
+| wabaId | string | yes | (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 | string | yes | (Read-only) Template name as registered with Meta. |
+| language | string | yes | (Read-only) Template language/locale code (e.g. "en", "fr"). |
+| category | string | yes | (Read-only) Meta template category (e.g. MARKETING, UTILITY, AUTHENTICATION). |
+| status | WhatsappTemplateStatus | yes | (Read-only) Meta review status. Only APPROVED templates can be sent. |
+| parameters | array<object> | yes | (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. |
+| parameters[].name | string | yes | Parameter name/placeholder (e.g. "1"). Matches a key in WhatsappOutboundMessage.template.variables. |
+| parameters[].component | WhatsappTemplateComponent | yes | Which template component this parameter targets: header | body | button. |
+| parameters[].buttonIndex | integer | no | 0-based button position. Present only when component=button (Meta requires a string index at send time). |
+| parameters[].buttonSubType | WhatsappButtonSubType | no | Button sub-type (url | quick_reply). Present only when component=button. |
+| preview | string | yes | (Read-only) Rendered preview text for display in the dashboard picker. |
+
+Example:
+```json
+{
+  "id": null,
+  "waba": "waba",
+  "wabaId": "wab_ref123",
+  "name": "Amadou Diallo",
+  "language": "language",
+  "category": "category",
+  "status": "status",
+  "parameters": [
+    {
+      "name": "Amadou Diallo",
+      "component": "component"
+    }
+  ],
+  "preview": "preview"
 }
 ```