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

package/data/docs/models/payment-webhook-delivery.md

@@ -0,0 +1,321 @@
+---
+title: "PaymentWebhookDelivery"
+sidebar_label: "PaymentWebhookDelivery"
+sidebar_position: 29
+---
+
+# PaymentWebhookDelivery
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "id": null,
+  "company": "company",
+  "provider": "pro_ref123",
+  "eventType": "eventType",
+  "status": "status",
+  "verified": "verified",
+  "endpointStatus": "endpointStatus",
+  "processed": true,
+  "reference": "reference",
+  "amount": 45000,
+  "currency": "XOF",
+  "payload": {},
+  "rawBody": "rawBody",
+  "headers": null,
+  "receivedAt": "receivedAt"
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `company`](#company)
+- [3. Property `provider`](#provider)
+- [4. Property `eventType`](#eventType)
+- [5. Property `status`](#status)
+- [6. Property `verified`](#verified)
+- [7. Property `endpointStatus`](#endpointStatus)
+- [8. Property `processed`](#processed)
+- [9. Property `reference`](#reference)
+- [10. Property `amount`](#amount)
+- [11. Property `currency`](#currency)
+- [12. Property `payload`](#payload)
+  - [12.1. Property `additionalProperties`](#payload_additionalProperties)
+- [13. Property `rawBody`](#rawBody)
+- [14. Property `headers`](#headers)
+  - [14.1. Property `additionalProperties`](#headers_additionalProperties)
+- [15. Property `receivedAt`](#receivedAt)
+  - [15.1. Property `_seconds`](#receivedAt__seconds)
+  - [15.2. Property `_nanoseconds`](#receivedAt__nanoseconds)
+
+|                           |                                        |
+| ------------------------- | -------------------------------------- |
+| **Type**                  | `object`                               |
+| **Required**              | No                                     |
+| **Additional properties** | Not allowed                            |
+| **Defined in**            | #/definitions/payment-webhook-delivery |
+
+**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.
+
+| Property                             | Pattern | Type           | Deprecated | Definition                           | Title/Description                                                                                                              |
+| ------------------------------------ | ------- | -------------- | ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| - [id](#id )                         | No      | string or null | No         | -                                    | (Read-only) Firestore document ID, auto-generated.                                                                             |
+| + [company](#company )               | No      | string         | No         | -                                    | (Immutable) Company document ID (e.g. "gerko_studios"). Resolved from the matched endpoint at delivery time.                   |
+| + [provider](#provider )             | No      | string         | No         | -                                    | Payment provider that sent this webhook (e.g. "jeko", "wave").                                                                 |
+| + [eventType](#eventType )           | No      | string         | No         | -                                    | Provider-defined event type. Observed: "transaction.payment". Full set per provider TBD (#42).                                 |
+| + [status](#status )                 | No      | string         | No         | -                                    | Processing outcome. Observed values: "success" \| "error".                                                                     |
+| + [verified](#verified )             | No      | string         | No         | -                                    | Signature verification result. Observed: "verified". Other values (e.g. "unverified", "error") may exist but are unconfirmed.  |
+| + [endpointStatus](#endpointStatus ) | No      | string         | No         | -                                    | Endpoint resolution result. Observed: "matched". Other values unconfirmed (#42).                                               |
+| + [processed](#processed )           | No      | boolean        | No         | -                                    | Whether this delivery has been reconciled to the AppPayment ledger.                                                            |
+| + [reference](#reference )           | No      | string         | No         | -                                    | Provider transaction ID (= payload.id). Canonical dedup key.                                                                   |
+| + [amount](#amount )                 | No      | number         | No         | -                                    | Payment amount, denormalized from payload.amount.amount (XOF).                                                                 |
+| + [currency](#currency )             | No      | string         | No         | -                                    | Currency code, denormalized from payload.amount.currency (e.g. "XOF").                                                         |
+| + [payload](#payload )               | No      | object         | No         | -                                    | Full parsed provider payload. Shape varies by provider. Contains PII (customer phone). See x-note for retention policy status. |
+| + [rawBody](#rawBody )               | No      | string         | No         | -                                    | Verbatim raw request body — used for HMAC-SHA256 verification. Contains PII.                                                   |
+| - [headers](#headers )               | No      | object or null | No         | -                                    | Incoming HTTP headers. Includes provider signature header and Sentry trace. Sensitive.                                         |
+| + [receivedAt](#receivedAt )         | No      | object         | No         | In #/definitions/firestore-timestamp | When the webhook delivery was received by the backend.                                                                         |
+
+## <a name="id"></a>1. Property `id`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only) Firestore document ID, auto-generated.
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="company"></a>2. Property `company`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) Company document ID (e.g. "gerko_studios"). Resolved from the matched endpoint at delivery time.
+
+:::info Immutable
+Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
+:::
+
+## <a name="provider"></a>3. Property `provider`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Payment provider that sent this webhook (e.g. "jeko", "wave").
+
+:::note
+Observed value: "jeko". The inner payload.paymentMethod may differ (e.g. "wave") — provider here is the webhook sender, not the payment rail (#42).
+:::
+
+## <a name="eventType"></a>4. Property `eventType`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Provider-defined event type. Observed: "transaction.payment". Full set per provider TBD (#42).
+
+:::note
+Observed value: "transaction.payment". Jeko docs say "transaction.completed" — full set per provider unconfirmed (#42). Use z.string() to avoid rejecting unseen values.
+:::
+
+## <a name="status"></a>5. Property `status`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Processing outcome. Observed values: "success" | "error".
+
+:::note
+Observed values: "success", "error". Indicates whether the webhook was processed without errors.
+:::
+
+## <a name="verified"></a>6. Property `verified`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Signature verification result. Observed: "verified". Other values (e.g. "unverified", "error") may exist but are unconfirmed.
+
+:::note
+Observed value: "verified". Indicates HMAC-SHA256 signature verification result. Full set of failure values unconfirmed (#42).
+:::
+
+## <a name="endpointStatus"></a>7. Property `endpointStatus`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Endpoint resolution result. Observed: "matched". Other values unconfirmed (#42).
+
+:::note
+Observed value: "matched". Indicates whether the token resolved to a known PaymentWebhookEndpoint. Other values (e.g. "not_found", "inactive") unconfirmed (#42).
+:::
+
+## <a name="processed"></a>8. Property `processed`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `boolean` |
+| **Required** | Yes       |
+
+**Description:** Whether this delivery has been reconciled to the AppPayment ledger.
+
+:::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.
+:::
+
+## <a name="reference"></a>9. Property `reference`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Provider transaction ID (= payload.id). Canonical dedup key.
+
+:::note
+Equals payload.id (provider transaction ID). Used as dedup key — the backend checks this before processing (#42 ask 3).
+:::
+
+## <a name="amount"></a>10. Property `amount`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** Payment amount, denormalized from payload.amount.amount (XOF).
+
+## <a name="currency"></a>11. Property `currency`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Currency code, denormalized from payload.amount.currency (e.g. "XOF").
+
+## <a name="payload"></a>12. Property `payload`
+
+|                           |                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------ |
+| **Type**                  | `object`                                                                             |
+| **Required**              | Yes                                                                                  |
+| **Additional properties** | [Each additional property must conform to the schema](#payload_additionalProperties) |
+
+**Description:** Full parsed provider payload. Shape varies by provider. Contains PII (customer phone). See x-note for retention policy status.
+
+| Property                             | Pattern | Type   | Deprecated | Definition | Title/Description |
+| ------------------------------------ | ------- | ------ | ---------- | ---------- | ----------------- |
+| - [](#payload_additionalProperties ) | No      | object | No         | -          | -                 |
+
+### <a name="payload_additionalProperties"></a>12.1. Property `additionalProperties`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `object`         |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+:::note
+Parsed provider request body. Contains PII: counterpartIdentifier and counterpartLabel hold customer phone numbers. Retention/TTL policy TBD (#42 ask 5).
+:::
+
+## <a name="rawBody"></a>13. Property `rawBody`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Verbatim raw request body — used for HMAC-SHA256 verification. Contains PII.
+
+:::note
+Verbatim request body string used for HMAC-SHA256 signature verification. Contains same PII as payload. Retention/TTL policy TBD (#42 ask 5).
+:::
+
+## <a name="headers"></a>14. Property `headers`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `object or null` |
+| **Required** | No               |
+
+**Description:** Incoming HTTP headers. Includes provider signature header and Sentry trace. Sensitive.
+
+| Property                             | Pattern | Type   | Deprecated | Definition | Title/Description |
+| ------------------------------------ | ------- | ------ | ---------- | ---------- | ----------------- |
+| - [](#headers_additionalProperties ) | No      | string | No         | -          | -                 |
+
+### <a name="headers_additionalProperties"></a>14.1. Property `additionalProperties`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+:::note
+Request headers including provider signature (e.g. "jeko-signature") and tracing headers. Sensitive — do not expose to clients.
+:::
+
+## <a name="receivedAt"></a>15. Property `receivedAt`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | Yes                               |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** When the webhook delivery was received by the backend.
+
+| Property                                    | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#receivedAt__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#receivedAt__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+### <a name="receivedAt__seconds"></a>15.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="receivedAt__nanoseconds"></a>15.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:10 +0000

package/data/docs/models/payment-webhook-endpoint.md

@@ -1,7 +1,7 @@
 ---
 title: "PaymentWebhookEndpoint"
 sidebar_label: "PaymentWebhookEndpoint"
-sidebar_position: 28
+sidebar_position: 30
 ---
 
 # PaymentWebhookEndpoint
@@ -184,7 +184,7 @@ Provider-specific webhook signing secret. Used to verify HMAC-SHA256 signatures
 | **Required** | No     |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:10 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/sale.md

@@ -1,7 +1,7 @@
 ---
 title: "Sale"
 sidebar_label: "Sale"
-sidebar_position: 29
+sidebar_position: 31
 ---
 
 # Sale
@@ -524,7 +524,7 @@ Set at creation only. This field cannot be modified after the document is create
 | **Required** | No     |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:10 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/site-payment.md

@@ -1,7 +1,7 @@
 ---
 title: "SitePayment"
 sidebar_label: "SitePayment"
-sidebar_position: 31
+sidebar_position: 33
 ---
 
 # SitePayment
@@ -197,4 +197,4 @@ Set at creation only. This field cannot be modified after the document is create
 | **Maximum**  | ≤ 9007199254740991  |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:10 +0000

package/data/docs/models/site.md

@@ -1,7 +1,7 @@
 ---
 title: "Site"
 sidebar_label: "Site"
-sidebar_position: 30
+sidebar_position: 32
 ---
 
 # Site
@@ -546,7 +546,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 **Description:** Timestamp of the most recent analytics event seen for this site.
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:10 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/stocktake-item.md

@@ -1,7 +1,7 @@
 ---
 title: "StocktakeItem"
 sidebar_label: "StocktakeItem"
-sidebar_position: 33
+sidebar_position: 35
 ---
 
 # StocktakeItem
@@ -497,4 +497,4 @@ Read-time hint snapshot of the verifier's display name (GH#29 §3 / Q10).
 | **Required** | No     |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:11 +0000

package/data/docs/models/stocktake.md

@@ -1,7 +1,7 @@
 ---
 title: "Stocktake"
 sidebar_label: "Stocktake"
-sidebar_position: 32
+sidebar_position: 34
 ---
 
 # Stocktake
@@ -642,7 +642,7 @@ Read-time hint snapshot of the completer's display name (GH#29 §3 / Q10).
 | **Required** | No     |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:11 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/ticket.md

@@ -1,7 +1,7 @@
 ---
 title: "Ticket"
 sidebar_label: "Ticket"
-sidebar_position: 34
+sidebar_position: 36
 ---
 
 # Ticket
@@ -388,7 +388,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 **Description:** (Immutable) FK → User/staff UID who created this ticket.
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:11 +0000
 
 :::info Immutable
 Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.

package/data/docs/models/user.md

@@ -1,7 +1,7 @@
 ---
 title: "User"
 sidebar_label: "User"
-sidebar_position: 35
+sidebar_position: 37
 ---
 
 # User
@@ -242,7 +242,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Required** | No     |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:11 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/whatsapp-inbound-message.md

@@ -1,7 +1,7 @@
 ---
 title: "WhatsappInboundMessage"
 sidebar_label: "WhatsappInboundMessage"
-sidebar_position: 36
+sidebar_position: 38
 ---
 
 # WhatsappInboundMessage
@@ -23,7 +23,8 @@ sidebar_position: 36
   "mediaId": null,
   "caption": null,
   "storageUrl": null,
-  "context": null
+  "context": null,
+  "contactE164": null
 }
 ```
 
@@ -52,6 +53,7 @@ sidebar_position: 36
   - [13.1. Property `id`](#context_id)
   - [13.2. Property `from`](#context_from)
   - [13.3. Property `forwarded`](#context_forwarded)
+- [14. Property `contactE164`](#contactE164)
 
 |                           |                                        |
 | ------------------------- | -------------------------------------- |
@@ -62,21 +64,22 @@ sidebar_position: 36
 
 **Description:** WhatsappInboundMessage — inbound WhatsApp message persisted from Meta Cloud API webhook (GH#36). Collection: whatsapp_inbound_messages/\{docId\}. Top-level scope: company resolution happens post-ingestion.
 
-| Property                     | Pattern | Type             | Deprecated | Definition                           | Title/Description                                                                                                           |
-| ---------------------------- | ------- | ---------------- | ---------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
-| - [id](#id )                 | No      | string or null   | No         | -                                    | (Read-only) Firestore document ID — wamid from Meta Cloud API.                                                              |
-| + [wabaId](#wabaId )         | No      | string           | No         | -                                    | (Immutable) Meta WABA ID identifying which business number received the message.                                            |
-| + [waba](#waba )             | No      | enum (of string) | No         | In #/definitions/waba-label          | (Immutable) Human-readable WABA label (cmz \| val). See WabaLabel enum.                                                     |
-| + [messageId](#messageId )   | No      | string           | No         | -                                    | (Immutable) WhatsApp message ID (wamid) returned by Meta — mirrors the document ID.                                         |
-| + [from](#from )             | No      | string           | No         | -                                    | (Immutable) Sender phone number in E.164 format.                                                                            |
-| + [type](#type )             | No      | Combination      | No         | -                                    | (Immutable) Meta message type.                                                                                              |
-| + [timestamp](#timestamp )   | No      | object           | No         | In #/definitions/firestore-timestamp | (Immutable) Message timestamp as reported by Meta.                                                                          |
-| + [receivedAt](#receivedAt ) | No      | object           | No         | In #/definitions/firestore-timestamp | (Read-only) Server-side ingestion timestamp.                                                                                |
-| - [text](#text )             | No      | string or null   | No         | -                                    | Message body text. Present on type=text messages only.                                                                      |
-| - [mediaId](#mediaId )       | No      | string or null   | No         | -                                    | Meta media ID. Present on image, audio, video, document, sticker messages.                                                  |
-| - [caption](#caption )       | No      | string or null   | No         | -                                    | Media caption text. Present when the sender included a caption.                                                             |
-| - [storageUrl](#storageUrl ) | No      | string or null   | No         | -                                    | Durable Cloud Storage URL for the downloaded media binary. Present after the media has been fetched and stored server-side. |
-| - [context](#context )       | No      | object or null   | No         | -                                    | Reply/forward context. Present on replies and forwarded messages.                                                           |
+| Property                       | Pattern | Type             | Deprecated | Definition                           | Title/Description                                                                                                                                  |
+| ------------------------------ | ------- | ---------------- | ---------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| - [id](#id )                   | No      | string or null   | No         | -                                    | (Read-only) Firestore document ID — wamid from Meta Cloud API.                                                                                     |
+| + [wabaId](#wabaId )           | No      | string           | No         | -                                    | (Immutable) Meta WABA ID identifying which business number received the message.                                                                   |
+| + [waba](#waba )               | No      | enum (of string) | No         | In #/definitions/waba-label          | (Immutable) Human-readable WABA label (cmz \| val). See WabaLabel enum.                                                                            |
+| + [messageId](#messageId )     | No      | string           | No         | -                                    | (Immutable) WhatsApp message ID (wamid) returned by Meta — mirrors the document ID.                                                                |
+| + [from](#from )               | No      | string           | No         | -                                    | (Immutable) Sender phone number in E.164 format.                                                                                                   |
+| + [type](#type )               | No      | Combination      | No         | -                                    | (Immutable) Meta message type.                                                                                                                     |
+| + [timestamp](#timestamp )     | No      | object           | No         | In #/definitions/firestore-timestamp | (Immutable) Message timestamp as reported by Meta.                                                                                                 |
+| + [receivedAt](#receivedAt )   | No      | object           | No         | In #/definitions/firestore-timestamp | (Read-only) Server-side ingestion timestamp.                                                                                                       |
+| - [text](#text )               | No      | string or null   | No         | -                                    | Message body text. Present on type=text messages only.                                                                                             |
+| - [mediaId](#mediaId )         | No      | string or null   | No         | -                                    | Meta media ID. Present on image, audio, video, document, sticker messages.                                                                         |
+| - [caption](#caption )         | No      | string or null   | No         | -                                    | Media caption text. Present when the sender included a caption.                                                                                    |
+| - [storageUrl](#storageUrl )   | No      | string or null   | No         | -                                    | Durable Cloud Storage URL for the downloaded media binary. Present after the media has been fetched and stored server-side.                        |
+| - [context](#context )         | No      | object or null   | No         | -                                    | Reply/forward context. Present on replies and forwarded messages.                                                                                  |
+| - [contactE164](#contactE164 ) | No      | string or null   | No         | -                                    | (Read-only) E.164-normalized sender phone (e.g. +2250777471485). Canonical join key (#56). Populated by the backend; absent on pre-migration docs. |
 
 ## <a name="id"></a>1. Property `id`
 
@@ -369,5 +372,26 @@ Do not include in write requests. This field is set exclusively by the server (F
 
 Specific value: `true`
 
+## <a name="contactE164"></a>14. Property `contactE164`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only) E.164-normalized sender phone (e.g. +2250777471485). Canonical join key (#56). Populated by the backend; absent on pre-migration docs.
+
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:11 +0000
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+:::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).
+:::
+
+:::tip When to set
+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).
+:::

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

@@ -1,7 +1,7 @@
 ---
 title: "WhatsappOutboundLifecycleEvent"
 sidebar_label: "WhatsappOutboundLifecycleEvent"
-sidebar_position: 37
+sidebar_position: 39
 ---
 
 # WhatsappOutboundLifecycleEvent
@@ -303,7 +303,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 **Description:** (Read-only) Raw Meta error object(s).
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 14:38:11 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.