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

package/data/static/schemas.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "description": "@valets/schema \u2014 consolidated schema bundle",
-  "generated": "2026-05-30T13:38:45.949066+00:00",
+  "generated": "2026-05-30T14:38:11.260961+00:00",
   "schemas": {
     "allowed-user": {
       "type": "object",
@@ -2334,7 +2334,7 @@
         },
         "paymentMethod": {
           "$ref": "#/definitions/payment-method",
-          "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 \u2014 treat OM as deprecated; canonical value is ORANGE_MONEY (#21)."
         },
         "referenceNumber": {
           "type": "string",
@@ -2732,6 +2732,182 @@
       ],
       "description": "Ticketed event lifecycle (D32). Mobile-only today; Dashboard in Wave 4."
     },
+    "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 \u2192 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": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the expense is due. Used to compute OVERDUE state at read time (not stored in paymentStatus)."
+        },
+        "paymentStatus": {
+          "$ref": "#/definitions/expense-payment-status",
+          "x-note": "OVERDUE is intentionally excluded \u2014 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 \u2014 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 \u2014 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 \u2014 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": "#/definitions/firestore-timestamp"
+            },
+            {
+              "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 \u2192 User/staff UID who created this expense record."
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Server-generated creation timestamp."
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "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 \u2014 derive at read time. Full domain (Payee FK, Contract FK) in #20.",
+      "example": {
+        "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"
+      }
+    },
+    "expense-payment-status": {
+      "type": "string",
+      "enum": [
+        "PENDING",
+        "PARTIALLY_PAID",
+        "PAID",
+        "FAILED"
+      ],
+      "x-note": "OVERDUE is intentionally excluded \u2014 it is never stored in Firestore. Compute it at read time: expense.paymentStatus !== PAID && expense.dueDate < now() (#13). Helper: isExpenseOverdue(expense: Expense): boolean.",
+      "description": "Payment status of an Expense. Stored enum \u2014 OVERDUE is not stored, it is derived at read time from dueDate (#13)."
+    },
     "fulfillment-status": {
       "type": "string",
       "enum": [
@@ -3362,6 +3538,7 @@
         "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": {
@@ -3379,11 +3556,13 @@
         "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": {
@@ -3420,6 +3599,7 @@
         "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": {
@@ -3465,6 +3645,7 @@
         "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": {
@@ -3638,6 +3819,7 @@
         "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": {
@@ -3655,11 +3837,13 @@
         "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": {
@@ -3696,6 +3880,7 @@
         "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": {
@@ -3741,6 +3926,7 @@
         "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": {
@@ -3808,8 +3994,8 @@
         },
         "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 \u2192 total amount for the current day. Empty map {} until first payment.",
+          "x-note": "Map keys use short codes in practice (OM, CASH, WAVE) \u2014 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"
@@ -3818,7 +4004,24 @@
             "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": {
@@ -3866,7 +4069,8 @@
         "date"
       ],
       "additionalProperties": false,
-      "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.",
+      "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 \u2014 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) when the company had activity that day; zero-activity days may produce no document (#9).",
       "example": {
         "todayOrdersCount": 2,
         "pendingOrdersCount": 2,
@@ -3921,6 +4125,7 @@
         "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": {
@@ -3938,11 +4143,13 @@
         "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": {
@@ -3979,6 +4186,7 @@
         "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": {
@@ -4024,6 +4232,7 @@
         "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": {
@@ -4258,7 +4467,14 @@
                     "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\u219210-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": {
@@ -4286,7 +4502,14 @@
                     "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\u219210-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": {
@@ -4313,7 +4536,14 @@
                     "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\u219210-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": {
@@ -4668,7 +4898,7 @@
               "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 \u2014 treat OM as deprecated; canonical value is ORANGE_MONEY (#21)."
         },
         "invoiceId": {
           "description": "FK \u2192 Invoice document ID.",
@@ -5605,9 +5835,10 @@
         "BANK_TRANSFER",
         "PAYPAL",
         "STRIPE",
-        "OTHER"
+        "OTHER",
+        "OM"
       ],
-      "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 \u2014 treat OM as deprecated; canonical value is ORANGE_MONEY (#21)."
     },
     "payment-proof-status": {
       "type": "string",
@@ -5631,6 +5862,134 @@
       ],
       "description": "Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking."
     },
+    "payment-webhook-delivery": {
+      "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\") \u2014 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\" \u2014 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 \u2014 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 \u2014 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 \u2014 used for HMAC-SHA256 verification. Contains PII."
+        },
+        "headers": {
+          "x-note": "Request headers including provider signature (e.g. \"jeko-signature\") and tracing headers. Sensitive \u2014 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": "#/definitions/firestore-timestamp",
+          "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 \u2014 retention policy TBD.",
+      "example": {
+        "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"
+      }
+    },
     "payment-webhook-endpoint": {
       "type": "object",
       "properties": {
@@ -7023,6 +7382,16 @@
             }
           },
           "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 \u2014 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 \u2192 +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": [
@@ -7049,7 +7418,8 @@
         "mediaId": null,
         "caption": null,
         "storageUrl": null,
-        "context": null
+        "context": null,
+        "contactE164": null
       }
     },
     "whatsapp-outbound-lifecycle-event": {
@@ -7285,6 +7655,16 @@
           "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 \u2014 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 \u2192 +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": "#/definitions/outbound-message-status",
           "description": "Delivery status. Created as `queued` by the dashboard; updated in place by the backend.",
@@ -7381,6 +7761,7 @@
           "uid": "user_u8x92kqm"
         },
         "createdAt": "createdAt",
+        "contactE164": null,
         "status": "status",
         "wamid": null,
         "error": null,

package/package.json

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