@ingenx-io/valets-schema-mcp-server 0.2.5 → 0.2.7

package/data/docs/models/whatsapp-outbound-lifecycle-event.md

@@ -1,7 +1,7 @@
 ---
 title: "WhatsappOutboundLifecycleEvent"
 sidebar_label: "WhatsappOutboundLifecycleEvent"
-sidebar_position: 33
+sidebar_position: 39
 ---
 
 # WhatsappOutboundLifecycleEvent
@@ -303,7 +303,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 **Description:** (Read-only) Raw Meta error object(s).
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:51 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:57:29 +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/docs/models/whatsapp-outbound-message.md

@@ -1,7 +1,7 @@
 ---
 title: "WhatsappOutboundMessage"
 sidebar_label: "WhatsappOutboundMessage"
-sidebar_position: 34
+sidebar_position: 40
 ---
 
 # WhatsappOutboundMessage
@@ -83,26 +83,26 @@ sidebar_position: 34
 
 **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.
 
-| Property                       | Pattern | Type             | Deprecated | Definition                               | Title/Description                                                                                                                       |
-| ------------------------------ | ------- | ---------------- | ---------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| - [id](#id )                   | No      | string or null   | No         | -                                        | (Read-only) Firestore document ID — auto-generated at enqueue time.                                                                     |
-| + [to](#to )                   | No      | string           | No         | -                                        | (Immutable) Recipient phone number in E.164 format. Must match the inbound \`from\` for the same conversation.                          |
-| + [waba](#waba )               | No      | enum (of string) | No         | In #/definitions/waba-label              | (Immutable) WABA that will send the message. Mirrors inbound \`waba\`.                                                                  |
-| + [wabaId](#wabaId )           | No      | string           | No         | -                                        | (Immutable) Meta WABA ID. Mirrors inbound \`wabaId\`.                                                                                   |
-| + [kind](#kind )               | No      | enum (of string) | No         | In #/definitions/outbound-message-format | (Immutable) Message format: \`text\` or \`template\`. Set \`text\` xor \`template\` to match.                                           |
-| - [text](#text )               | No      | string or null   | No         | -                                        | Free-form message body. Present only when kind=text.                                                                                    |
-| - [template](#template )       | No      | object or null   | No         | -                                        | Template send payload. Present only when kind=template.                                                                                 |
-| - [purpose](#purpose )         | No      | Combination      | No         | -                                        | Business purpose (otp \| review_request \| adhoc \| conversational). Optional.                                                          |
-| - [orderUuid](#orderUuid )     | No      | string or null   | No         | -                                        | Order reference. Present on review_request messages.                                                                                    |
-| + [sentBy](#sentBy )           | No      | object           | No         | -                                        | (Immutable) Dashboard actor who enqueued the message.                                                                                   |
-| + [createdAt](#createdAt )     | No      | object           | No         | In #/definitions/firestore-timestamp     | (Immutable) Enqueue timestamp, set by the dashboard at create.                                                                          |
-| + [status](#status )           | No      | enum (of string) | No         | In #/definitions/outbound-message-status | Delivery status. Created as \`queued\` by the dashboard; updated in place by the backend.                                               |
-| - [wamid](#wamid )             | No      | string or null   | No         | -                                        | (Read-only) WhatsApp message ID returned by Meta once the backend sends. Absent while queued or on failure.                             |
-| - [error](#error )             | No      | string or null   | No         | -                                        | (Read-only) Human-readable failure reason. Present on status=failed. Raw Meta error detail lives in the lifecycle_events subcollection. |
-| - [sentAt](#sentAt )           | No      | Combination      | No         | -                                        | (Read-only) When the backend sent the message to Meta.                                                                                  |
-| - [deliveredAt](#deliveredAt ) | No      | Combination      | No         | -                                        | (Read-only) When Meta reported delivery.                                                                                                |
-| - [readAt](#readAt )           | No      | Combination      | No         | -                                        | (Read-only) When Meta reported the recipient read the message.                                                                          |
-| - [failedAt](#failedAt )       | No      | Combination      | No         | -                                        | (Read-only) When the send failed.                                                                                                       |
+| Property                       | Pattern | Type             | Deprecated | Definition                               | Title/Description                                                                                                                                                              |
+| ------------------------------ | ------- | ---------------- | ---------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| - [id](#id )                   | No      | string or null   | No         | -                                        | (Read-only) Firestore document ID — auto-generated at enqueue time.                                                                                                            |
+| + [to](#to )                   | No      | string           | No         | -                                        | (Immutable) Recipient Meta wa_id — digits only, no leading + (e.g. 22577471485). Equal to the inbound \`from\` for the same conversation. NOT literal E.164; see x-note (#54). |
+| + [waba](#waba )               | No      | enum (of string) | No         | In #/definitions/waba-label              | (Immutable) WABA that will send the message. Mirrors inbound \`waba\`.                                                                                                         |
+| + [wabaId](#wabaId )           | No      | string           | No         | -                                        | (Immutable) Meta WABA ID. Mirrors inbound \`wabaId\`.                                                                                                                          |
+| + [kind](#kind )               | No      | enum (of string) | No         | In #/definitions/outbound-message-format | (Immutable) Message format: \`text\` or \`template\`. Set \`text\` xor \`template\` to match.                                                                                  |
+| - [text](#text )               | No      | string or null   | No         | -                                        | Free-form message body. Present only when kind=text.                                                                                                                           |
+| - [template](#template )       | No      | object or null   | No         | -                                        | Template send payload. Present only when kind=template.                                                                                                                        |
+| - [purpose](#purpose )         | No      | Combination      | No         | -                                        | Business purpose (otp \| review_request \| adhoc \| conversational). Optional.                                                                                                 |
+| - [orderUuid](#orderUuid )     | No      | string or null   | No         | -                                        | Order reference. Present on review_request messages.                                                                                                                           |
+| + [sentBy](#sentBy )           | No      | object           | No         | -                                        | (Immutable) Dashboard actor who enqueued the message.                                                                                                                          |
+| + [createdAt](#createdAt )     | No      | object           | No         | In #/definitions/firestore-timestamp     | (Immutable) Enqueue timestamp, set by the dashboard at create.                                                                                                                 |
+| + [status](#status )           | No      | enum (of string) | No         | In #/definitions/outbound-message-status | Delivery status. Created as \`queued\` by the dashboard; updated in place by the backend.                                                                                      |
+| - [wamid](#wamid )             | No      | string or null   | No         | -                                        | (Read-only) WhatsApp message ID returned by Meta once the backend sends. Absent while queued or on failure.                                                                    |
+| - [error](#error )             | No      | string or null   | No         | -                                        | (Read-only) Human-readable failure reason. Present on status=failed. Raw Meta error detail lives in the lifecycle_events subcollection.                                        |
+| - [sentAt](#sentAt )           | No      | Combination      | No         | -                                        | (Read-only) When the backend sent the message to Meta.                                                                                                                         |
+| - [deliveredAt](#deliveredAt ) | No      | Combination      | No         | -                                        | (Read-only) When Meta reported delivery.                                                                                                                                       |
+| - [readAt](#readAt )           | No      | Combination      | No         | -                                        | (Read-only) When Meta reported the recipient read the message.                                                                                                                 |
+| - [failedAt](#failedAt )       | No      | Combination      | No         | -                                        | (Read-only) When the send failed.                                                                                                                                              |
 
 ## <a name="id"></a>1. Property `id`
 
@@ -124,12 +124,20 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Type**     | `string` |
 | **Required** | Yes      |
 
-**Description:** (Immutable) Recipient phone number in E.164 format. Must match the inbound `from` for the same conversation.
+**Description:** (Immutable) Recipient Meta wa_id — digits only, no leading + (e.g. 22577471485). Equal to the inbound `from` for the same conversation. NOT literal E.164; see x-note (#54).
 
 :::info Immutable
 Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
 :::
 
+:::note
+This is the Meta wa_id (digits only, no leading +), NOT a literal E.164 string. Meta normalizes phone numbers in non-obvious ways (e.g. +2250777471485 → wa_id 22577471485, dropping the trunk zero). The only reliable source is Meta's contacts[].wa_id from the send response — do not derive from E.164 by stripping + alone. The dashboard conversational sends and the whatsapp-server OTP path both use the wa_id form. Confirmed in prod: ING-368.
+:::
+
+:::tip When to set
+Set at enqueue time to the recipient's Meta wa_id. Use inbound WhatsappInboundMessage.from (also wa_id) as the join key for the conversation thread.
+:::
+
 ## <a name="waba"></a>3. Property `waba`
 
 |                |                          |
@@ -148,6 +156,10 @@ Must be one of:
 Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
 :::
 
+:::note
+cmz = "IngenX - Chez Miss Zahoui", phone number ID 446424085225188, used for chez_miss_zahoui_* companies. val = "IngenX - Valets", phone number ID 425582173979125, used for all other companies. Templates are approved at WABA level — if cmz and val share a WABA ID, all templates are available to both. Routing logic: functions/src/orders/order.ts#isSender2Company. See messaging/whatsapp-platform-constraints (#50).
+:::
+
 ## <a name="wabaId"></a>4. Property `wabaId`
 
 |              |          |
@@ -424,6 +436,10 @@ Dashboard must create with `queued`. The backend owns every transition after (se
 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.
 :::
 
+:::note
+Useful for audit and dedup. Does NOT enable reply-threading for template messages — Meta silently ignores context.message_id on templates. Threading only works for kind=text within the 24-hour service window (#50).
+:::
+
 ## <a name="error"></a>14. Property `error`
 
 |              |                  |
@@ -582,7 +598,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Required** | No     |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:51 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:57:29 +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/docs/models/whatsapp-template.md

@@ -1,7 +1,7 @@
 ---
 title: "WhatsappTemplate"
 sidebar_label: "WhatsappTemplate"
-sidebar_position: 35
+sidebar_position: 41
 ---
 
 # WhatsappTemplate
@@ -99,6 +99,10 @@ Must be one of:
 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.
 :::
 
+:::note
+cmz = "IngenX - Chez Miss Zahoui", phone number ID 446424085225188, used for chez_miss_zahoui_* companies. val = "IngenX - Valets", phone number ID 425582173979125, used for all other companies. Templates are approved at WABA level — if cmz and val share a WABA ID, all templates are available to both. Routing logic: functions/src/orders/order.ts#isSender2Company. See messaging/whatsapp-platform-constraints (#50).
+:::
+
 ## <a name="wabaId"></a>3. Property `wabaId`
 
 |              |          |
@@ -287,7 +291,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 **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-30 at 12:42:51 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:57:29 +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

@@ -22,6 +22,10 @@ Values: ACTIVE, STALE, ON_HOLD, ESCALATED
 Booking lifecycle status. COMPLETED_MIXED = some sessions completed, others cancelled/no-show.
 Values: PENDING, CONFIRMED, COMPLETED, CANCELLED, CANCELLATION_REQUESTED, COMPLETED_MIXED
 
+### ContractStatus
+Lifecycle status of a Contract. DRAFT = not yet signed. ACTIVE = in force. COMPLETED = all milestones paid and obligations met. TERMINATED = ended early by either party.
+Values: DRAFT, ACTIVE, COMPLETED, TERMINATED
+
 ### CustomerPaymentStatus
 Customer payment lifecycle status (D22). Tracks allocation progress of received payments.
 Values: PENDING, CONFIRMED, PARTIALLY_APPLIED, FULLY_APPLIED, REFUNDED, CANCELLED
@@ -42,6 +46,10 @@ Values: web, mobile, pwa, app-store, play-store, other
 Ticketed event lifecycle (D32). Mobile-only today; Dashboard in Wave 4.
 Values: DRAFT, ACTIVE, CANCELLED, COMPLETED
 
+### ExpensePaymentStatus
+Payment status of an Expense. Stored enum — OVERDUE is not stored, it is derived at read time from dueDate (#13).
+Values: PENDING, PARTIALLY_PAID, PAID, FAILED
+
 ### FulfillmentStatus
 Delivery/fulfillment lifecycle (D34). Optional — null for in-person orders.
 Values: PREPARING, PARTIALLY_SHIPPED, SHIPPED, IN_TRANSIT, DELIVERED, PICKED_UP
@@ -50,6 +58,10 @@ Values: PREPARING, PARTIALLY_SHIPPED, SHIPPED, IN_TRANSIT, DELIVERED, PICKED_UP
 Loyalty point transaction type (D07). SCREAMING_SNAKE past tense.
 Values: EARNED, REDEEMED, ADJUSTED, EXPIRED, BONUS, REFUND
 
+### MilestoneStatus
+Status of a ContractMilestone (#17). PENDING = created, not yet invoiced. INVOICED = invoice issued, awaiting payment. PAID = payment received.
+Values: PENDING, INVOICED, PAID
+
 ### NotificationChannel
 Delivery channel of a NotificationRecord (GH#48).
 Values: email, whatsapp, sms, push
@@ -79,8 +91,8 @@ Outbound WhatsApp message delivery status. Lifecycle: queued → sent → delive
 Values: queued, sent, delivered, read, failed
 
 ### PaymentMethod
-Unified payment method set with African + global methods (D02).
-Values: CASH, CREDIT_CARD, ORANGE_MONEY, WAVE, MTN_MONEY, MOOV_MONEY, BANK_TRANSFER, PAYPAL, STRIPE, OTHER
+Unified payment method set with African + global methods (D02). Note: the metrics writer historically emits "OM" instead of "ORANGE_MONEY" as a paymentsByMethod map key — treat OM as deprecated; canonical value is ORANGE_MONEY (#21).
+Values: CASH, CREDIT_CARD, ORANGE_MONEY, WAVE, MTN_MONEY, MOOV_MONEY, BANK_TRANSFER, PAYPAL, STRIPE, OTHER, OM
 
 ### PaymentProofStatus
 Payment proof review status. Used by Order and Booking payment proof workflows.
@@ -123,7 +135,7 @@ Event ticket status (D32). VALID = active and unused.
 Values: VALID, USED, CANCELLED
 
 ### WabaLabel
-Human-readable WABA label identifying which Meta business number received the message (GH#36).
+WABA label identifying which Meta Business Account sent/received the message. cmz = Chez Miss Zahoui sender; val = Valets sender. See WhatsApp platform constraints doc (#50).
 Values: cmz, val
 
 ### WhatsappButtonSubType
@@ -361,7 +373,7 @@ Example:
 ```
 
 ### App
-Fields: 14 (6 required)
+Fields: 14 (5 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -369,7 +381,7 @@ Fields: 14 (6 required)
 | companyId | string | yes | (Immutable) FK → Company document ID. Scopes all app sub-collections. |
 | name | string | yes | Human-readable app name shown in dashboards. |
 | description | ['string', 'null'] | no | Optional freeform description. |
-| status | AppStatus | yes | Lifecycle status (D41/D44). Clients filter by ACTIVE. |
+| status | any | no | Lifecycle status (D41/D44). Optional pending backfill of pre-existing records (#26) — treat absent as ACTIVE. Clients filter by ACTIVE. |
 | deploymentLinks | array<object> | yes | Ordered list of deployment URLs (web, mobile, PWA, store links). |
 | deploymentLinks[].label | string | yes | Human-readable label shown in dashboards (e.g. "Production", "Staging"). |
 | deploymentLinks[].url | string | yes | Absolute URL or store link. |
@@ -642,6 +654,48 @@ Example:
 }
 ```
 
+### Contract
+Fields: 15 (8 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| payeeId | string | yes | (Immutable) FK → Payee document ID. Full Payee model tracked in #20. |
+| title | string | yes | Contract title or reference name shown in dashboards. |
+| description | ['string', 'null'] | no | Optional freeform description of the contract scope. |
+| status | ContractStatus | yes | Contract lifecycle status (#14). Query by ACTIVE — do not use an isActive boolean. |
+| currency | string | yes | Currency code. Locked to XOF (#18). Multi-currency support requires a deliberate schema version bump. |
+| totalAmount | number | yes | Total contract value (XOF). |
+| startDate | string | yes | Contract start date (ISO 8601 YYYY-MM-DD). |
+| endDate | ['string', 'null'] | no | Contract end date (ISO 8601 YYYY-MM-DD). Absent for open-ended contracts. |
+| milestones | ['array', 'null'] | no | Ordered list of payment milestones. Embedded in the contract document (#17). |
+| notes | ['string', 'null'] | no | Optional internal notes. |
+| createdBy | string | yes | (Immutable) FK → User/staff UID who created the contract. |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "payeeId": "pay_ref123",
+  "title": "title",
+  "description": null,
+  "status": "status",
+  "currency": "XOF",
+  "totalAmount": 45000,
+  "startDate": "2026-02-15",
+  "endDate": null,
+  "milestones": null,
+  "notes": null,
+  "createdBy": "staff_k0f1",
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
 ### Customer
 Fields: 17 (4 required)
 
@@ -700,7 +754,7 @@ Fields: 17 (12 required)
 | amount | number | yes |  |
 | currency | string | yes | Currency code. Locked to XOF (West African CFA franc) for now. |
 | paymentDate | FirestoreTimestamp | yes | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
-| paymentMethod | PaymentMethod | yes | Unified payment method set with African + global methods (D02). |
+| paymentMethod | PaymentMethod | yes | Unified payment method set with African + global methods (D02). Note: the metrics writer historically emits "OM" instead of "ORANGE_MONEY" as a paymentsByMethod map key — treat OM as deprecated; canonical value is ORANGE_MONEY (#21). |
 | referenceNumber | string | yes | Unique payment reference (receipt number, transaction ID, etc.). |
 | allocatedAmount | number | yes | (Read-only) Total amount allocated to bookings/orders/purchases via allocations. Server-calculated. |
 | unappliedAmount | number | yes | (Read-only) Remaining unallocated amount (amount - allocatedAmount). Server-calculated. |
@@ -816,6 +870,52 @@ Example:
 }
 ```
 
+### Expense
+Fields: 17 (6 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| title | string | yes | Human-readable expense title (e.g. "Loyer mars 2026", "Facture EAU"). |
+| description | ['string', 'null'] | no | Optional longer description or notes. |
+| amount | number | yes | Total expense amount (XOF). |
+| currency | string | yes | Currency code. Locked to XOF. |
+| dueDate | any | no | When the expense is due. Used to compute OVERDUE state at read time (not stored in paymentStatus). |
+| paymentStatus | ExpensePaymentStatus | yes | Current payment status. OVERDUE is never stored — derive from dueDate at read time (#13). |
+| amountDue | ['number', 'null'] | no | Amount still owed. Authoritative when no OutboundPaymentAllocation records exist for this expense. |
+| amountPaid | ['number', 'null'] | no | Amount paid to date (simple tracking, no allocations). |
+| allocatedAmount | ['number', 'null'] | no | (Read-only) Total amount allocated via OutboundPaymentAllocation records. Authoritative when allocations exist. |
+| balance | ['number', 'null'] | no | (Read-only) Remaining balance: amount minus allocatedAmount. Authoritative when OutboundPaymentAllocation records exist. |
+| paidDate | any | no | When the expense was fully settled (paymentStatus = PAID). Null otherwise. |
+| paymentReference | ['string', 'null'] | no | Most recent payment transaction reference. Overwritten on each payment; not a full history. |
+| createdBy | string | yes | (Immutable) FK → User/staff UID who created this expense record. |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated last-update timestamp. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "title": "title",
+  "description": null,
+  "amount": 45000,
+  "currency": "XOF",
+  "dueDate": "dueDate",
+  "paymentStatus": "paymentStatus",
+  "amountDue": null,
+  "amountPaid": null,
+  "allocatedAmount": null,
+  "balance": null,
+  "paidDate": "pai_ref123",
+  "paymentReference": null,
+  "createdBy": "staff_k0f1",
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
 ### LoyaltyConfig
 Fields: 11 (2 required)
 
@@ -1104,7 +1204,7 @@ Fields: 31 (26 required)
 | staleOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders that have been in an incomplete status beyond the stale threshold. |
 | staleBookingsCount | ['integer', 'null'] | no | (Read-only, Optional) Bookings that have been in an incomplete status beyond the stale threshold. |
 | onHoldOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders currently in an on-hold state. |
-| paymentsByMethod | ['object', 'null'] | no | (Read-only, Optional) Map of PaymentMethod → total amount for the current day. Empty map {} until first payment. |
+| paymentsByMethod | ['object', 'null'] | no | (Read-only, Optional) Payment breakdown by method for the day. Keys are PaymentMethod values (or legacy short code OM). Value is { total: XOF amount, count: number of payments }. |
 | computedForDay | string | yes | (Read-only) YYYY-MM-DD string indicating which day these metrics reflect. Used to detect day boundaries and trigger midnight resets. |
 | generatedAt | FirestoreTimestamp | yes | (Read-only) Server timestamp of the last metrics write. |
 | date | string | yes | (Read-only) YYYY-MM-DD document ID repeated as a field. Identifies the day this snapshot covers. |
@@ -1281,7 +1381,7 @@ Example:
 ```
 
 ### Order
-Fields: 48 (8 required)
+Fields: 49 (8 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -1290,12 +1390,13 @@ Fields: 48 (8 required)
 | companyId | string | yes | (Immutable) FK → Company document ID. Scopes all queries. |
 | appId | ['string', 'null'] | no | (Immutable, Optional) FK → App document ID (D43 / ADR-003, renamed from siteId per D44). null = company-wide. |
 | orderNumber | string | yes | (Read-only) Server-generated order number. |
+| followUpUrl | ['string', 'null'] | no | Optional URL for receipt QR code / post-order follow-up. Canonical casing: followUpUrl (#6). |
 | status | OrderStatus | yes | Core lifecycle status (D34, MIG-11). See OrderStatus enum for the legacy value migration mapping. |
 | paymentStatus | any | no | Payment lifecycle (D34). Null until payment is initiated. |
 | fulfillmentStatus | any | no | Delivery/fulfillment lifecycle (D34). |
 | returnStatus | any | no | Return/exchange lifecycle (D34). Null until a return or exchange is initiated. |
 | deliveryType | any | no | Fulfillment channel for this order (ON_SITE, PICK_UP, DELIVERY). |
-| paymentMethod | any | no | Unified payment method set with African + global methods (D02). |
+| paymentMethod | any | no | Unified payment method set with African + global methods (D02). Note: the metrics writer historically emits "OM" instead of "ORANGE_MONEY" as a paymentsByMethod map key — treat OM as deprecated; canonical value is ORANGE_MONEY (#21). |
 | invoiceId | ['string', 'null'] | no | FK → Invoice document ID. |
 | customerId | ['string', 'null'] | no | FK → Customer.id (Firestore doc ID). Used to resolve customer details. |
 | customerName | ['string', 'null'] | no | (Denormalized) From Customer.name at write time. |
@@ -1342,6 +1443,7 @@ Example:
   "companyId": "comp_xyz789",
   "appId": null,
   "orderNumber": "ORD-2026-0042",
+  "followUpUrl": null,
   "status": "status",
   "paymentStatus": "paymentStatus",
   "fulfillmentStatus": "fulfillmentStatus",
@@ -1424,6 +1526,136 @@ Example:
 }
 ```
 
+### OutboundPayment
+Fields: 13 (7 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| payeeId | string | yes | (Immutable) FK → Payee document ID. Full Payee model tracked in #20. |
+| contractId | ['string', 'null'] | no | (Immutable, Optional) FK → Contract document ID. Absent for ad-hoc payments outside a formal contract. |
+| amount | number | yes | Amount paid (XOF). |
+| currency | string | yes | Currency code. Locked to XOF — consistent with Contract and CustomerPayment. |
+| method | PaymentMethod | yes | Payment method used (e.g. BANK_TRANSFER, MOBILE_MONEY, CHECK). |
+| reference | ['string', 'null'] | no | Optional payment reference — bank transaction number, check number, Wave ref, etc. |
+| paidAt | FirestoreTimestamp | yes | When the payment was made. |
+| notes | ['string', 'null'] | no | Optional internal notes. |
+| createdBy | string | yes | (Immutable) FK → User/staff UID who recorded the payment. |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "payeeId": "pay_ref123",
+  "contractId": null,
+  "amount": 45000,
+  "currency": "XOF",
+  "method": "method",
+  "reference": null,
+  "paidAt": "pai_ref123",
+  "notes": null,
+  "createdBy": "staff_k0f1",
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
+### OutboundPaymentAllocation
+Fields: 7 (4 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| outboundPaymentId | string | yes | (Immutable) FK → OutboundPayment document ID (parent). |
+| expenseId | string | yes | (Immutable) FK → Expense document ID. Full Expense model tracked in #20. |
+| companyId | string | yes | (Immutable) FK → Company document ID. Denormalized for collection-group queries. |
+| amount | number | yes | Amount of this payment allocated to the referenced expense (XOF). |
+| notes | ['string', 'null'] | no | Optional notes about this allocation. |
+| allocatedAt | any | no | (Read-only) When this allocation was recorded. |
+
+Example:
+```json
+{
+  "id": null,
+  "outboundPaymentId": "out_ref123",
+  "expenseId": "exp_ref123",
+  "companyId": "comp_xyz789",
+  "amount": 45000,
+  "notes": null,
+  "allocatedAt": "allocatedAt"
+}
+```
+
+### PaymentWebhookDelivery
+Fields: 15 (13 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| company | string | yes | (Immutable) Company document ID (e.g. "gerko_studios"). Resolved from the matched endpoint at delivery time. |
+| provider | string | yes | Payment provider that sent this webhook (e.g. "jeko", "wave"). |
+| eventType | string | yes | Provider-defined event type. Observed: "transaction.payment". Full set per provider TBD (#42). |
+| status | string | yes | Processing outcome. Observed values: "success" | "error". |
+| verified | string | yes | Signature verification result. Observed: "verified". Other values (e.g. "unverified", "error") may exist but are unconfirmed. |
+| endpointStatus | string | yes | Endpoint resolution result. Observed: "matched". Other values unconfirmed (#42). |
+| processed | boolean | yes | Whether this delivery has been reconciled to the AppPayment ledger. |
+| reference | string | yes | Provider transaction ID (= payload.id). Canonical dedup key. |
+| amount | number | yes | Payment amount, denormalized from payload.amount.amount (XOF). |
+| currency | string | yes | Currency code, denormalized from payload.amount.currency (e.g. "XOF"). |
+| payload | object | yes | Full parsed provider payload. Shape varies by provider. Contains PII (customer phone). See x-note for retention policy status. |
+| rawBody | string | yes | Verbatim raw request body — used for HMAC-SHA256 verification. Contains PII. |
+| headers | ['object', 'null'] | no | Incoming HTTP headers. Includes provider signature header and Sentry trace. Sensitive. |
+| receivedAt | FirestoreTimestamp | yes | When the webhook delivery was received by the backend. |
+
+Example:
+```json
+{
+  "id": null,
+  "company": "company",
+  "provider": "pro_ref123",
+  "eventType": "eventType",
+  "status": "status",
+  "verified": "verified",
+  "endpointStatus": "endpointStatus",
+  "processed": true,
+  "reference": "reference",
+  "amount": 45000,
+  "currency": "XOF",
+  "payload": {},
+  "rawBody": "rawBody",
+  "headers": null,
+  "receivedAt": "receivedAt"
+}
+```
+
+### PaymentWebhookEndpoint
+Fields: 6 (5 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| token | string | yes | (Immutable) base64url-encoded 24-byte random token. Also the Firestore document ID and the URL path segment. |
+| company | string | yes | (Immutable) Company slug (e.g. gerko_studios). Identifies the tenant that owns this endpoint. |
+| provider | enum(2) | yes | (Immutable) Payment provider whose webhooks this endpoint accepts. |
+| secret | string | yes | Webhook signing secret for HMAC verification. Backend-only — never returned to dashboard or mobile clients. |
+| active | boolean | yes | Whether this endpoint is currently active. Inactive endpoints reject incoming webhooks. |
+| createdAt | any | no | (Read-only) When this endpoint was provisioned. |
+
+Example:
+```json
+{
+  "token": "token",
+  "company": "company",
+  "provider": "wave",
+  "secret": "secret",
+  "active": true,
+  "createdAt": "createdAt"
+}
+```
+
 ### Sale
 Fields: 12 (1 required)
 
@@ -1792,7 +2024,7 @@ Fields: 18 (7 required)
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | 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. |
+| to | string | yes | (Immutable) Recipient Meta wa_id — digits only, no leading + (e.g. 22577471485). Equal to the inbound `from` for the same conversation. NOT literal E.164; see x-note (#54). |
 | waba | WabaLabel | yes | (Immutable) WABA that will send the message. Mirrors inbound `waba`. |
 | wabaId | string | yes | (Immutable) Meta WABA ID. Mirrors inbound `wabaId`. |
 | kind | OutboundMessageFormat | yes | (Immutable) Message format: `text` or `template`. Set `text` xor `template` to match. |