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

package/data/static/openapi.yaml

@@ -51,6 +51,16 @@ components:
       - COMPLETED_MIXED
       description: Booking lifecycle status. COMPLETED_MIXED = some sessions completed,
         others cancelled/no-show.
+    ContractStatus:
+      type: string
+      enum:
+      - DRAFT
+      - ACTIVE
+      - COMPLETED
+      - TERMINATED
+      description: 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.
     CustomerPaymentStatus:
       type: string
       enum:
@@ -99,6 +109,15 @@ components:
       - COMPLETED
       description: Ticketed event lifecycle (D32). Mobile-only today; Dashboard in
         Wave 4.
+    ExpensePaymentStatus:
+      type: string
+      enum:
+      - PENDING
+      - PARTIALLY_PAID
+      - PAID
+      - FAILED
+      description: Payment status of an Expense. Stored enum — OVERDUE is not stored,
+        it is derived at read time from dueDate (#13).
     FulfillmentStatus:
       type: string
       enum:
@@ -120,6 +139,14 @@ components:
       - BONUS
       - REFUND
       description: Loyalty point transaction type (D07). SCREAMING_SNAKE past tense.
+    MilestoneStatus:
+      type: string
+      enum:
+      - PENDING
+      - INVOICED
+      - PAID
+      description: Status of a ContractMilestone (#17). PENDING = created, not yet
+        invoiced. INVOICED = invoice issued, awaiting payment. PAID = payment received.
     NotificationChannel:
       type: string
       enum:
@@ -204,7 +231,11 @@ components:
       - PAYPAL
       - STRIPE
       - OTHER
-      description: Unified payment method set with African + global methods (D02).
+      - OM
+      description: '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).'
     PaymentProofStatus:
       type: string
       enum:
@@ -309,8 +340,9 @@ components:
       enum:
       - cmz
       - val
-      description: Human-readable WABA label identifying which Meta business number
-        received the message (GH#36).
+      description: 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).
     WhatsappButtonSubType:
       type: string
       enum:
@@ -1022,18 +1054,22 @@ components:
           - string
           - 'null'
         status:
-          $ref: '#/components/schemas/AppStatus'
-          description: Lifecycle status (D41/D44). Clients filter by ACTIVE.
-          x-note: ACTIVE = live and serving traffic. INACTIVE = intentionally disabled
-            by operators. EXPIRED = past expiresAt (derived when isExpired is true;
-            may also be stored explicitly). ARCHIVED = soft-deleted; retained for
-            audit but not listed by default.
+          anyOf:
+          - $ref: '#/components/schemas/AppStatus'
+          - type: 'null'
+          x-note: Real Firestore documents may be missing this field on pre-backfill
+            records (#26). Treat absent as ACTIVE. A backfill script will populate
+            status=ACTIVE on all existing documents; once confirmed, this field will
+            be promoted to required.
+          x-when: Written by operators via dashboard or by server triggers (expiration).
+            Clients must not use server-side `where(status == ACTIVE)` until backfill
+            is complete — filter client-side instead, treating absent as ACTIVE.
+          description: Lifecycle status (D41/D44). Optional pending backfill of pre-existing
+            records (#26) — treat absent as ACTIVE. Clients filter by ACTIVE.
           x-see:
             decisions:
             - D41
             - D44
-          x-when: Written by operators via dashboard or by server triggers (expiration).
-            Clients filter by ACTIVE.
         deploymentLinks:
           type: array
           items:
@@ -1154,7 +1190,6 @@ components:
       required:
       - companyId
       - name
-      - status
       - deploymentLinks
       - createdBy
       - analyticsEnabled
@@ -1172,7 +1207,6 @@ components:
       required:
       - companyId
       - name
-      - status
       - deploymentLinks
       - createdBy
       - analyticsEnabled
@@ -1882,6 +1916,156 @@ components:
       description: 'BookingVersion model (D18). Collection: companies/{companyId}/bookings/{bookingId}/versions/{versionId}.
         Server-owned audit trail written by Firebase trigger on every Booking mutation.
         Captures writes from all clients.'
+    Contract:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        payeeId:
+          type: string
+          x-immutable: true
+          description: '(Immutable) FK → Payee document ID. Full Payee model tracked
+            in #20.'
+        title:
+          type: string
+          description: Contract title or reference name shown in dashboards.
+        description:
+          description: Optional freeform description of the contract scope.
+          type:
+          - string
+          - 'null'
+        status:
+          $ref: '#/components/schemas/ContractStatus'
+          description: Contract lifecycle status (#14). Query by ACTIVE — do not use
+            an isActive boolean.
+        currency:
+          type: string
+          const: XOF
+          description: Currency code. Locked to XOF (#18). Multi-currency support
+            requires a deliberate schema version bump.
+        totalAmount:
+          type: number
+          description: Total contract value (XOF).
+        startDate:
+          type: string
+          description: Contract start date (ISO 8601 YYYY-MM-DD).
+        endDate:
+          description: Contract end date (ISO 8601 YYYY-MM-DD). Absent for open-ended
+            contracts.
+          type:
+          - string
+          - 'null'
+        milestones:
+          description: Ordered list of payment milestones. Embedded in the contract
+            document (#17).
+          type:
+          - array
+          - 'null'
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+                description: Client-generated milestone ID (UUID or slug). Unique
+                  within the contract.
+              title:
+                type: string
+                description: Milestone description or deliverable name.
+              amount:
+                type: number
+                description: Amount due at this milestone (XOF).
+              dueDate:
+                description: ISO 8601 date string (YYYY-MM-DD) when the milestone
+                  is due. OVERDUE is derived at read time from dueDate — not stored.
+                type: string
+              status:
+                $ref: '#/components/schemas/MilestoneStatus'
+                x-note: Existing Firestore documents may have lowercase values (pending,
+                  invoiced, paid) from before this enum was introduced (#17). Normalize
+                  on read or via migration script.
+                description: Milestone payment status (#17). OVERDUE is derived at
+                  read time from dueDate, not stored.
+              invoicedAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: When the invoice was issued for this milestone.
+              paidAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: When payment was received for this milestone.
+              notes:
+                description: Optional notes for this milestone.
+                type: string
+            required:
+            - id
+            - title
+            - amount
+            - status
+            additionalProperties: false
+            description: ContractMilestone — embedded sub-object on Contract (#17).
+              Not a separate collection.
+        notes:
+          description: Optional internal notes.
+          type:
+          - string
+          - 'null'
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created the contract.
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+      required:
+      - companyId
+      - payeeId
+      - title
+      - status
+      - currency
+      - totalAmount
+      - startDate
+      - createdBy
+      additionalProperties: false
+      description: 'Contract model (GH#14/#17/#18). Collection: companies/{companyId}/contracts/{contractId}.
+        Service/supplier contract between a company and a Payee. No isActive field
+        — query by status. Currency locked to XOF. Milestones use MilestoneStatus
+        enum (no stored OVERDUE).'
+    ContractCreate:
+      allOf:
+      - $ref: '#/components/schemas/Contract'
+      description: Write payload for creating a new Contract document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - payeeId
+      - title
+      - status
+      - currency
+      - totalAmount
+      - startDate
+      - createdBy
+    ContractUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Contract'
+      description: Write payload for partial update (PATCH) of a Contract document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
     Customer:
       type: object
       properties:
@@ -2052,7 +2236,10 @@ components:
             notes (#10).'
         paymentMethod:
           $ref: '#/components/schemas/PaymentMethod'
-          description: Unified payment method set with African + global methods (D02).
+          description: '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:
           type: string
           description: Unique payment reference (receipt number, transaction ID, etc.).
@@ -2349,6 +2536,146 @@ components:
       - $ref: '#/components/schemas/Event'
       description: Write payload for partial update (PATCH) of a Event document. All
         fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
+    Expense:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        title:
+          type: string
+          description: Human-readable expense title (e.g. "Loyer mars 2026", "Facture
+            EAU").
+        description:
+          description: Optional longer description or notes.
+          type:
+          - string
+          - 'null'
+        amount:
+          type: number
+          description: Total expense amount (XOF).
+        currency:
+          type: string
+          const: XOF
+          description: Currency code. Locked to XOF.
+        dueDate:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: When the expense is due. Used to compute OVERDUE state at read
+            time (not stored in paymentStatus).
+        paymentStatus:
+          $ref: '#/components/schemas/ExpensePaymentStatus'
+          x-note: 'OVERDUE is intentionally excluded — it is never stored in Firestore.
+            Compute it at read time: expense.paymentStatus !== PAID && expense.dueDate
+            < now() (#13). Helper: isExpenseOverdue(expense: Expense): boolean.'
+          description: Current payment status. OVERDUE is never stored — derive from
+            dueDate at read time (#13).
+        amountDue:
+          x-note: Authoritative for simple (non-allocation) expenses. Legacy field
+            maintained for backward compatibility when no OutboundPaymentAllocation
+            records exist (#12).
+          description: Amount still owed. Authoritative when no OutboundPaymentAllocation
+            records exist for this expense.
+          type:
+          - number
+          - 'null'
+        amountPaid:
+          description: Amount paid to date (simple tracking, no allocations).
+          type:
+          - number
+          - 'null'
+        allocatedAmount:
+          readOnly: true
+          x-note: Server-set — computed from OutboundPaymentAllocation records. Clients
+            must never write this field (#12).
+          description: (Read-only) Total amount allocated via OutboundPaymentAllocation
+            records. Authoritative when allocations exist.
+          type:
+          - number
+          - 'null'
+        balance:
+          readOnly: true
+          x-note: Server-set — computed as amount - allocatedAmount. Authoritative
+            remaining amount when allocations exist. Prefer this over amountDue when
+            OutboundPaymentAllocation records are present (#12).
+          description: '(Read-only) Remaining balance: amount minus allocatedAmount.
+            Authoritative when OutboundPaymentAllocation records exist.'
+          type:
+          - number
+          - 'null'
+        paidDate:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          x-when: Set when paymentStatus transitions to PAID (fully settled). Null
+            for partially paid or unpaid expenses. For multi-payment history, read
+            OutboundPaymentAllocation records (#19).
+          description: When the expense was fully settled (paymentStatus = PAID).
+            Null otherwise.
+        paymentReference:
+          x-note: Reference for the most recent payment transaction (check number,
+            wire ID, Wave ref, etc.). Overwritten on each payment. For full payment
+            history read OutboundPaymentAllocation records (#19).
+          description: Most recent payment transaction reference. Overwritten on each
+            payment; not a full history.
+          type:
+          - string
+          - 'null'
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created this expense record.
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated last-update timestamp.
+      required:
+      - companyId
+      - title
+      - amount
+      - currency
+      - paymentStatus
+      - createdBy
+      additionalProperties: false
+      description: 'Expense (GH#12/#13/#19 partial). Collection: companies/{companyId}/expenses/{expenseId}.
+        Dual balance tracking: amountPaid/amountDue for simple expenses; allocatedAmount/balance
+        (server-set) for allocation-settled expenses. OVERDUE excluded from stored
+        enum — derive at read time. Full domain (Payee FK, Contract FK) in #20.'
+    ExpenseCreate:
+      allOf:
+      - $ref: '#/components/schemas/Expense'
+      description: Write payload for creating a new Expense document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - title
+      - amount
+      - currency
+      - paymentStatus
+      - createdBy
+    ExpenseUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Expense'
+      description: Write payload for partial update (PATCH) of a Expense document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
     LoyaltyConfig:
       type: object
       properties:
@@ -2835,6 +3162,9 @@ components:
         orderCompletionRate30d:
           type: number
           readOnly: true
+          x-note: Firestore REST API v1 writes integerValue when the stored value
+            is whole (e.g. 0), doubleValue when fractional (e.g. 82.17). Admin SDK
+            smooths this to a JS number; REST clients must coerce the union (#11).
           description: (Read-only) Percentage of orders completed or delivered in
             the last 30 days. Always full recalc.
         todayPurchasesCount:
@@ -2851,11 +3181,16 @@ components:
         averagePurchaseAmount:
           type: number
           readOnly: true
+          x-note: Firestore REST API v1 writes integerValue when whole (e.g. 10070),
+            doubleValue when fractional (e.g. 10006.5). Admin SDK smooths this; REST
+            clients must coerce (#11).
           description: (Read-only) Average purchase value across last 200 purchases
             (rolling, not time-windowed).
         monthlyRevenue:
           type: number
           readOnly: true
+          x-note: Observed as integerValue on all sampled tenants (whole XOF amounts).
+            Will be doubleValue if fractional. REST clients must coerce (#11).
           description: (Read-only) Total purchase value in the current calendar month
             (UTC).
         monthlyPurchasesCount:
@@ -2892,6 +3227,8 @@ components:
         todayCollectedAmount:
           type: number
           readOnly: true
+          x-note: Observed as integerValue "0" on all sampled tenants. Will be doubleValue
+            if fractional payments occur. REST clients must coerce (#11).
           description: (Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT
             is today. Resets at midnight.
         todayRevenue:
@@ -2937,6 +3274,8 @@ components:
         averageRating:
           type: number
           readOnly: true
+          x-note: Observed as integerValue "0" on all tenants (no reviews yet). Will
+            be doubleValue once real ratings exist. REST clients must coerce (#11).
           description: (Read-only) Average rating from the last 200 reviews (rolling).
             Always full recalc.
         lowStockItemsCount:
@@ -3084,6 +3423,9 @@ components:
         orderCompletionRate30d:
           type: number
           readOnly: true
+          x-note: Firestore REST API v1 writes integerValue when the stored value
+            is whole (e.g. 0), doubleValue when fractional (e.g. 82.17). Admin SDK
+            smooths this to a JS number; REST clients must coerce the union (#11).
           description: (Read-only) Percentage of orders completed or delivered in
             the last 30 days. Always full recalc.
         todayPurchasesCount:
@@ -3100,11 +3442,16 @@ components:
         averagePurchaseAmount:
           type: number
           readOnly: true
+          x-note: Firestore REST API v1 writes integerValue when whole (e.g. 10070),
+            doubleValue when fractional (e.g. 10006.5). Admin SDK smooths this; REST
+            clients must coerce (#11).
           description: (Read-only) Average purchase value across last 200 purchases
             (rolling, not time-windowed).
         monthlyRevenue:
           type: number
           readOnly: true
+          x-note: Observed as integerValue on all sampled tenants (whole XOF amounts).
+            Will be doubleValue if fractional. REST clients must coerce (#11).
           description: (Read-only) Total purchase value in the current calendar month
             (UTC).
         monthlyPurchasesCount:
@@ -3141,6 +3488,8 @@ components:
         todayCollectedAmount:
           type: number
           readOnly: true
+          x-note: Observed as integerValue "0" on all sampled tenants. Will be doubleValue
+            if fractional payments occur. REST clients must coerce (#11).
           description: (Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT
             is today. Resets at midnight.
         todayRevenue:
@@ -3186,6 +3535,8 @@ components:
         averageRating:
           type: number
           readOnly: true
+          x-note: Observed as integerValue "0" on all tenants (no reviews yet). Will
+            be doubleValue once real ratings exist. REST clients must coerce (#11).
           description: (Read-only) Average rating from the last 200 reviews (rolling).
             Always full recalc.
         lowStockItemsCount:
@@ -3252,17 +3603,34 @@ components:
           maximum: 9007199254740991
         paymentsByMethod:
           readOnly: true
-          x-note: Always {} until the first real payment is recorded. Present on all
-            tenants once rewritten by current aggregator (#8).
-          description: (Read-only, Optional) Map of PaymentMethod → total amount for
-            the current day. Empty map {} until first payment.
+          x-note: Map keys use short codes in practice (OM, CASH, WAVE) — OM is a
+            non-canonical alias for ORANGE_MONEY emitted by the metrics writer (#21).
+            Value shape { total, count } differs from MetricsCurrent.paymentsByMethod
+            (bare number).
+          description: '(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 }.'
           type:
           - object
           - 'null'
           propertyNames:
             type: string
           additionalProperties:
-            type: number
+            type: object
+            properties:
+              total:
+                type: number
+                description: Sum of payment amounts for this method on the given day
+                  (XOF).
+              count:
+                type: integer
+                minimum: -9007199254740991
+                maximum: 9007199254740991
+                description: Number of payments using this method on the given day.
+            required:
+            - total
+            - count
+            additionalProperties: false
         computedForDay:
           type: string
           readOnly: true
@@ -3305,9 +3673,17 @@ components:
       - generatedAt
       - date
       additionalProperties: false
+      x-note: 'Zero-activity behavior (#9): the computeDailyCompanyMetrics cron (02:00
+        UTC) does NOT write a snapshot for days with no activity. A missing document
+        means either zero activity or the cron did not run — consumers cannot distinguish
+        the two from the absence alone. To detect cron gaps, compare the latest document
+        date with today; a gap larger than 1 day on an otherwise active tenant indicates
+        a cron failure. Observed: 3 of 4 zahoui tenants had gaps; bingerville (active)
+        had a document every day.'
       description: 'Daily metrics snapshot. Collection: companies/{companyId}/metrics_daily/{YYYY-MM-DD}.
         Same fields as MetricsCurrent plus `date`. Written by computeDailyCompanyMetrics
-        cron (02:00 UTC) and inline after full recalcs.'
+        cron (02:00 UTC) when the company had activity that day; zero-activity days
+        may produce no document (#9).'
     MetricsDailyCreate:
       allOf:
       - $ref: '#/components/schemas/MetricsDaily'
@@ -3339,6 +3715,9 @@ components:
         orderCompletionRate30d:
           type: number
           readOnly: true
+          x-note: Firestore REST API v1 writes integerValue when the stored value
+            is whole (e.g. 0), doubleValue when fractional (e.g. 82.17). Admin SDK
+            smooths this to a JS number; REST clients must coerce the union (#11).
           description: (Read-only) Percentage of orders completed or delivered in
             the last 30 days. Always full recalc.
         todayPurchasesCount:
@@ -3355,11 +3734,16 @@ components:
         averagePurchaseAmount:
           type: number
           readOnly: true
+          x-note: Firestore REST API v1 writes integerValue when whole (e.g. 10070),
+            doubleValue when fractional (e.g. 10006.5). Admin SDK smooths this; REST
+            clients must coerce (#11).
           description: (Read-only) Average purchase value across last 200 purchases
             (rolling, not time-windowed).
         monthlyRevenue:
           type: number
           readOnly: true
+          x-note: Observed as integerValue on all sampled tenants (whole XOF amounts).
+            Will be doubleValue if fractional. REST clients must coerce (#11).
           description: (Read-only) Total purchase value in the current calendar month
             (UTC).
         monthlyPurchasesCount:
@@ -3396,6 +3780,8 @@ components:
         todayCollectedAmount:
           type: number
           readOnly: true
+          x-note: Observed as integerValue "0" on all sampled tenants. Will be doubleValue
+            if fractional payments occur. REST clients must coerce (#11).
           description: (Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT
             is today. Resets at midnight.
         todayRevenue:
@@ -3441,6 +3827,8 @@ components:
         averageRating:
           type: number
           readOnly: true
+          x-note: Observed as integerValue "0" on all tenants (no reviews yet). Will
+            be doubleValue once real ratings exist. REST clients must coerce (#11).
           description: (Read-only) Average rating from the last 200 reviews (rolling).
             Always full recalc.
         lowStockItemsCount:
@@ -3781,6 +4169,17 @@ components:
           type: string
           readOnly: true
           description: (Read-only) Server-generated order number.
+        followUpUrl:
+          x-note: Standardized casing is followUpUrl (not followUpURL). Mobile legacy
+            code reads both casings for backward compat but writes followUpUrl going
+            forward (#6).
+          x-when: 'Used by mobile to generate QR codes on printed receipts. If absent,
+            the mobile app derives a deterministic fallback: https://zahoui.web.app/reviews?orderNumber={orderNumber}.'
+          description: 'Optional URL for receipt QR code / post-order follow-up. Canonical
+            casing: followUpUrl (#6).'
+          type:
+          - string
+          - 'null'
         status:
           $ref: '#/components/schemas/OrderStatus'
           description: Core lifecycle status (D34, MIG-11). See OrderStatus enum for
@@ -3879,7 +4278,10 @@ components:
           anyOf:
           - $ref: '#/components/schemas/PaymentMethod'
           - type: 'null'
-          description: Unified payment method set with African + global methods (D02).
+          description: '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:
           description: FK → Invoice document ID.
           type:
@@ -4315,6 +4717,376 @@ components:
       description: Write payload for partial update (PATCH) of a OrderItem document.
         All fields optional. Fields marked `readOnly` or `x-immutable` must not be
         sent.
+    OutboundPayment:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        payeeId:
+          type: string
+          x-immutable: true
+          description: '(Immutable) FK → Payee document ID. Full Payee model tracked
+            in #20.'
+        contractId:
+          x-immutable: true
+          description: (Immutable, Optional) FK → Contract document ID. Absent for
+            ad-hoc payments outside a formal contract.
+          type:
+          - string
+          - 'null'
+        amount:
+          type: number
+          description: Amount paid (XOF).
+        currency:
+          type: string
+          const: XOF
+          description: Currency code. Locked to XOF — consistent with Contract and
+            CustomerPayment.
+        method:
+          $ref: '#/components/schemas/PaymentMethod'
+          description: Payment method used (e.g. BANK_TRANSFER, MOBILE_MONEY, CHECK).
+        reference:
+          description: Optional payment reference — bank transaction number, check
+            number, Wave ref, etc.
+          type:
+          - string
+          - 'null'
+        paidAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: When the payment was made.
+        notes:
+          description: Optional internal notes.
+          type:
+          - string
+          - 'null'
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who recorded the payment.
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+      required:
+      - companyId
+      - payeeId
+      - amount
+      - currency
+      - method
+      - paidAt
+      - createdBy
+      additionalProperties: false
+      description: 'OutboundPayment (GH#15). Collection: companies/{companyId}/outboundPayments/{paymentId}.
+        Single outbound transfer to a Payee. Canonical name chosen over SupplierPayment/VendorPayment
+        — direction-based, agnostic of payee type. Currency locked to XOF.'
+    OutboundPaymentCreate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPayment'
+      description: Write payload for creating a new OutboundPayment document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - payeeId
+      - amount
+      - currency
+      - method
+      - paidAt
+      - createdBy
+    OutboundPaymentUpdate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPayment'
+      description: Write payload for partial update (PATCH) of a OutboundPayment document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    OutboundPaymentAllocation:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        outboundPaymentId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → OutboundPayment document ID (parent).
+        expenseId:
+          type: string
+          x-immutable: true
+          description: '(Immutable) FK → Expense document ID. Full Expense model tracked
+            in #20.'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Denormalized for collection-group
+            queries.
+        amount:
+          type: number
+          description: Amount of this payment allocated to the referenced expense
+            (XOF).
+        notes:
+          description: Optional notes about this allocation.
+          type:
+          - string
+          - 'null'
+        allocatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When this allocation was recorded.
+      required:
+      - outboundPaymentId
+      - expenseId
+      - companyId
+      - amount
+      additionalProperties: false
+      description: 'OutboundPaymentAllocation (GH#15). Subcollection: companies/{companyId}/outboundPayments/{paymentId}/allocations/{allocationId}.
+        Links an OutboundPayment to an Expense. Supports partial and multi-expense
+        allocations.'
+    OutboundPaymentAllocationCreate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPaymentAllocation'
+      description: Write payload for creating a new OutboundPaymentAllocation document.
+        Fields marked `readOnly` are server-set and must not be included. Fields marked
+        `x-immutable` may be set once at creation.
+      required:
+      - outboundPaymentId
+      - expenseId
+      - companyId
+      - amount
+    OutboundPaymentAllocationUpdate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPaymentAllocation'
+      description: Write payload for partial update (PATCH) of a OutboundPaymentAllocation
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
+    PaymentWebhookDelivery:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        company:
+          type: string
+          x-immutable: true
+          description: (Immutable) Company document ID (e.g. "gerko_studios"). Resolved
+            from the matched endpoint at delivery time.
+        provider:
+          type: string
+          x-note: 'Observed value: "jeko". The inner payload.paymentMethod may differ
+            (e.g. "wave") — provider here is the webhook sender, not the payment rail
+            (#42).'
+          description: Payment provider that sent this webhook (e.g. "jeko", "wave").
+        eventType:
+          type: string
+          x-note: 'Observed value: "transaction.payment". Jeko docs say "transaction.completed"
+            — full set per provider unconfirmed (#42). Use z.string() to avoid rejecting
+            unseen values.'
+          description: 'Provider-defined event type. Observed: "transaction.payment".
+            Full set per provider TBD (#42).'
+        status:
+          type: string
+          x-note: 'Observed values: "success", "error". Indicates whether the webhook
+            was processed without errors.'
+          description: 'Processing outcome. Observed values: "success" | "error".'
+        verified:
+          type: string
+          x-note: 'Observed value: "verified". Indicates HMAC-SHA256 signature verification
+            result. Full set of failure values unconfirmed (#42).'
+          description: 'Signature verification result. Observed: "verified". Other
+            values (e.g. "unverified", "error") may exist but are unconfirmed.'
+        endpointStatus:
+          type: string
+          x-note: 'Observed value: "matched". Indicates whether the token resolved
+            to a known PaymentWebhookEndpoint. Other values (e.g. "not_found", "inactive")
+            unconfirmed (#42).'
+          description: 'Endpoint resolution result. Observed: "matched". Other values
+            unconfirmed (#42).'
+        processed:
+          type: boolean
+          x-note: Set to true once the delivery has been reconciled to the AppPayment
+            ledger (companies/{cid}/apps/{appId}/payments). Back-reference FK not
+            stored on this doc — reconciliation is tracked on the AppPayment side.
+          description: Whether this delivery has been reconciled to the AppPayment
+            ledger.
+        reference:
+          type: string
+          x-note: Equals payload.id (provider transaction ID). Used as dedup key —
+            the backend checks this before processing (#42 ask 3).
+          description: Provider transaction ID (= payload.id). Canonical dedup key.
+        amount:
+          type: number
+          description: Payment amount, denormalized from payload.amount.amount (XOF).
+        currency:
+          type: string
+          description: Currency code, denormalized from payload.amount.currency (e.g.
+            "XOF").
+        payload:
+          type: object
+          propertyNames:
+            type: string
+          additionalProperties: {}
+          x-note: 'Parsed provider request body. Contains PII: counterpartIdentifier
+            and counterpartLabel hold customer phone numbers. Retention/TTL policy
+            TBD (#42 ask 5).'
+          description: Full parsed provider payload. Shape varies by provider. Contains
+            PII (customer phone). See x-note for retention policy status.
+        rawBody:
+          type: string
+          x-note: Verbatim request body string used for HMAC-SHA256 signature verification.
+            Contains same PII as payload. Retention/TTL policy TBD (#42 ask 5).
+          description: Verbatim raw request body — used for HMAC-SHA256 verification.
+            Contains PII.
+        headers:
+          x-note: Request headers including provider signature (e.g. "jeko-signature")
+            and tracing headers. Sensitive — do not expose to clients.
+          description: Incoming HTTP headers. Includes provider signature header and
+            Sentry trace. Sensitive.
+          type:
+          - object
+          - 'null'
+          propertyNames:
+            type: string
+          additionalProperties:
+            type: string
+        receivedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: When the webhook delivery was received by the backend.
+      required:
+      - company
+      - provider
+      - eventType
+      - status
+      - verified
+      - endpointStatus
+      - processed
+      - reference
+      - amount
+      - currency
+      - payload
+      - rawBody
+      - receivedAt
+      additionalProperties: false
+      x-internal: true
+      description: 'PaymentWebhookDelivery (GH#42). Collection: payment_webhooks/{deliveryId}
+        (top-level). One document per received provider callback. Contains raw payload
+        + verification outcome. x-internal: written/read only by backend; dashboard
+        reads via admin UI. PII in payload/rawBody — retention policy TBD.'
+    PaymentWebhookDeliveryCreate:
+      allOf:
+      - $ref: '#/components/schemas/PaymentWebhookDelivery'
+      description: Write payload for creating a new PaymentWebhookDelivery document.
+        Fields marked `readOnly` are server-set and must not be included. Fields marked
+        `x-immutable` may be set once at creation.
+      required:
+      - company
+      - provider
+      - eventType
+      - status
+      - verified
+      - endpointStatus
+      - processed
+      - reference
+      - amount
+      - currency
+      - payload
+      - rawBody
+      - receivedAt
+    PaymentWebhookDeliveryUpdate:
+      allOf:
+      - $ref: '#/components/schemas/PaymentWebhookDelivery'
+      description: Write payload for partial update (PATCH) of a PaymentWebhookDelivery
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
+    PaymentWebhookEndpoint:
+      type: object
+      properties:
+        token:
+          type: string
+          x-immutable: true
+          description: (Immutable) base64url-encoded 24-byte random token. Also the
+            Firestore document ID and the URL path segment.
+        company:
+          type: string
+          x-immutable: true
+          description: (Immutable) Company slug (e.g. gerko_studios). Identifies the
+            tenant that owns this endpoint.
+        provider:
+          type: string
+          enum:
+          - wave
+          - jeko
+          x-immutable: true
+          description: (Immutable) Payment provider whose webhooks this endpoint accepts.
+        secret:
+          type: string
+          x-note: Provider-specific webhook signing secret. Used to verify HMAC-SHA256
+            signatures on inbound payloads. Never expose to clients.
+          readOnly: true
+          description: Webhook signing secret for HMAC verification. Backend-only
+            — never returned to dashboard or mobile clients.
+        active:
+          type: boolean
+          description: Whether this endpoint is currently active. Inactive endpoints
+            reject incoming webhooks.
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When this endpoint was provisioned.
+      required:
+      - token
+      - company
+      - provider
+      - secret
+      - active
+      additionalProperties: false
+      x-internal: true
+      description: 'PaymentWebhookEndpoint (GH#41). Collection: payment_webhook_endpoints/{token}.
+        Top-level, not tenant-scoped. Provisioned by superadmin; used by the backend
+        to verify inbound payment webhooks from Wave and Jeko. The delivery log collection
+        (raw webhook payloads + verification outcomes) is tracked in GH#41 — shape
+        TBD.'
+    PaymentWebhookEndpointCreate:
+      allOf:
+      - $ref: '#/components/schemas/PaymentWebhookEndpoint'
+      description: Write payload for creating a new PaymentWebhookEndpoint document.
+        Fields marked `readOnly` are server-set and must not be included. Fields marked
+        `x-immutable` may be set once at creation.
+      required:
+      - token
+      - company
+      - provider
+      - active
+    PaymentWebhookEndpointUpdate:
+      allOf:
+      - $ref: '#/components/schemas/PaymentWebhookEndpoint'
+      description: Write payload for partial update (PATCH) of a PaymentWebhookEndpoint
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
     Sale:
       type: object
       properties:
@@ -5213,6 +5985,12 @@ components:
             received the message.
         waba:
           $ref: '#/components/schemas/WabaLabel'
+          x-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).'
           description: (Immutable) Human-readable WABA label (cmz | val). See WabaLabel
             enum.
           x-immutable: true
@@ -5415,10 +6193,26 @@ components:
         to:
           type: string
           x-immutable: true
-          description: (Immutable) Recipient phone number in E.164 format. Must match
-            the inbound `from` for the same conversation.
+          x-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.'
+          x-when: 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.
+          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).
         waba:
           $ref: '#/components/schemas/WabaLabel'
+          x-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).'
           description: (Immutable) WABA that will send the message. Mirrors inbound
             `waba`.
           x-immutable: true
@@ -5504,6 +6298,9 @@ components:
             after (sent → delivered → read, or failed).
         wamid:
           readOnly: true
+          x-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).
           description: (Read-only) WhatsApp message ID returned by Meta once the backend
             sends. Absent while queued or on failure.
           type:
@@ -5583,6 +6380,12 @@ components:
           - 'null'
         waba:
           $ref: '#/components/schemas/WabaLabel'
+          x-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).'
           description: (Read-only) WABA label this template is approved on. Templates
             are WABA-scoped. Mirrors WhatsappOutboundMessage.waba.
           readOnly: true