@ingenx-io/valets-schema-mcp-server 0.2.6 → 0.2.8

package/data/static/openapi.yaml

@@ -109,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:
@@ -222,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:
@@ -2223,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.).
@@ -2520,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:
@@ -3006,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:
@@ -3022,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:
@@ -3063,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:
@@ -3108,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:
@@ -3255,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:
@@ -3271,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:
@@ -3312,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:
@@ -3357,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:
@@ -3423,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
@@ -3476,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'
@@ -3510,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:
@@ -3526,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:
@@ -3567,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:
@@ -3612,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:
@@ -3782,8 +3999,20 @@ components:
                     description: Recipient email address. Present for email notifications.
                     type: string
                   phone:
-                    description: Recipient phone number (E.164). Present for whatsapp/sms
-                      notifications.
+                    description: Recipient phone number as passed by the sender (may
+                      be raw wa_id or E.164). Present for whatsapp/sms notifications.
+                    type: string
+                  contactE164:
+                    readOnly: true
+                    x-note: Canonical E.164 phone, normalized from `phone` by the
+                      backend writer. Use this for joins and search, not the raw `phone`
+                      field (#56). Absent on pre-migration docs.
+                    x-when: Populated by Cloud Functions on every new NotificationRecord
+                      for whatsapp/sms channels. CI normalization applied (8→10-digit
+                      07/05/01 series).
+                    description: (Read-only) E.164-normalized phone (e.g. +2250777471485).
+                      Canonical join key across WhatsApp and notification collections
+                      (#56).
                     type: string
                   name:
                     description: Recipient display name.
@@ -3804,8 +4033,20 @@ components:
                     description: Recipient email address. Present for email notifications.
                     type: string
                   phone:
-                    description: Recipient phone number (E.164). Present for whatsapp/sms
-                      notifications.
+                    description: Recipient phone number as passed by the sender (may
+                      be raw wa_id or E.164). Present for whatsapp/sms notifications.
+                    type: string
+                  contactE164:
+                    readOnly: true
+                    x-note: Canonical E.164 phone, normalized from `phone` by the
+                      backend writer. Use this for joins and search, not the raw `phone`
+                      field (#56). Absent on pre-migration docs.
+                    x-when: Populated by Cloud Functions on every new NotificationRecord
+                      for whatsapp/sms channels. CI normalization applied (8→10-digit
+                      07/05/01 series).
+                    description: (Read-only) E.164-normalized phone (e.g. +2250777471485).
+                      Canonical join key across WhatsApp and notification collections
+                      (#56).
                     type: string
                   name:
                     description: Recipient display name.
@@ -3825,8 +4066,20 @@ components:
                     description: Recipient email address. Present for email notifications.
                     type: string
                   phone:
-                    description: Recipient phone number (E.164). Present for whatsapp/sms
-                      notifications.
+                    description: Recipient phone number as passed by the sender (may
+                      be raw wa_id or E.164). Present for whatsapp/sms notifications.
+                    type: string
+                  contactE164:
+                    readOnly: true
+                    x-note: Canonical E.164 phone, normalized from `phone` by the
+                      backend writer. Use this for joins and search, not the raw `phone`
+                      field (#56). Absent on pre-migration docs.
+                    x-when: Populated by Cloud Functions on every new NotificationRecord
+                      for whatsapp/sms channels. CI normalization applied (8→10-digit
+                      07/05/01 series).
+                    description: (Read-only) E.164-normalized phone (e.g. +2250777471485).
+                      Canonical join key across WhatsApp and notification collections
+                      (#56).
                     type: string
                   name:
                     description: Recipient display name.
@@ -4061,7 +4314,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:
@@ -4659,6 +4915,147 @@ components:
       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:
@@ -5710,6 +6107,22 @@ components:
               type: boolean
               const: true
           additionalProperties: false
+        contactE164:
+          readOnly: true
+          x-note: E.164-normalized form of `from` (wa_id). Canonical join key across
+            WhatsappInboundMessage, WhatsappOutboundMessage, and NotificationRecord.
+            Use this for conversation threading, search, and cross-collection joins
+            — not the raw `from` wa_id (#56).
+          x-when: 'Populated by whatsapp-server on every new inbound doc. Absent on
+            pre-#56 docs until the backfill migration runs. CI normalization: wa_id
+            22577471485 → +2250777471485 (insert trunk 0 after country code for 8-digit
+            numbers in the 07/05/01 series that predate the 2014 10-digit migration).'
+          description: (Read-only) E.164-normalized sender phone (e.g. +2250777471485).
+            Canonical join key (#56). Populated by the backend; absent on pre-migration
+            docs.
+          type:
+          - string
+          - 'null'
       required:
       - wabaId
       - waba
@@ -5929,6 +6342,22 @@ components:
           $ref: '#/components/schemas/FirestoreTimestamp'
           description: (Immutable) Enqueue timestamp, set by the dashboard at create.
           x-immutable: true
+        contactE164:
+          readOnly: true
+          x-note: E.164-normalized form of `to` (wa_id). Canonical join key across
+            WhatsappOutboundMessage, WhatsappInboundMessage, and NotificationRecord.
+            Use this for conversation threading, search, and cross-collection joins
+            — not the raw `to` wa_id (#56).
+          x-when: 'Populated by whatsapp-server on every new outbound doc. Absent
+            on pre-#56 docs until the backfill migration runs. CI normalization: wa_id
+            22577471485 → +2250777471485 (insert trunk 0 after country code for 8-digit
+            numbers in the 07/05/01 series that predate the 2014 10-digit migration).'
+          description: (Read-only) E.164-normalized recipient phone (e.g. +2250777471485).
+            Canonical join key (#56). Populated by the backend; absent on pre-migration
+            docs.
+          type:
+          - string
+          - 'null'
         status:
           $ref: '#/components/schemas/OutboundMessageStatus'
           description: Delivery status. Created as `queued` by the dashboard; updated