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

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

@@ -0,0 +1,191 @@
+---
+title: "PaymentWebhookEndpoint"
+sidebar_label: "PaymentWebhookEndpoint"
+sidebar_position: 28
+---
+
+# PaymentWebhookEndpoint
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "token": "token",
+  "company": "company",
+  "provider": "wave",
+  "secret": "secret",
+  "active": true,
+  "createdAt": "createdAt"
+}
+```
+
+</details>
+
+
+- [1. Property `token`](#token)
+- [2. Property `company`](#company)
+- [3. Property `provider`](#provider)
+- [4. Property `secret`](#secret)
+- [5. Property `active`](#active)
+- [6. Property `createdAt`](#createdAt)
+  - [6.1. Property `firestore-timestamp`](#createdAt_anyOf_i0)
+    - [6.1.1. Property `_seconds`](#createdAt_anyOf_i0__seconds)
+    - [6.1.2. Property `_nanoseconds`](#createdAt_anyOf_i0__nanoseconds)
+  - [6.2. Property `item 1`](#createdAt_anyOf_i1)
+
+|                           |                                        |
+| ------------------------- | -------------------------------------- |
+| **Type**                  | `object`                               |
+| **Required**              | No                                     |
+| **Additional properties** | Not allowed                            |
+| **Defined in**            | #/definitions/payment-webhook-endpoint |
+
+**Description:** PaymentWebhookEndpoint (GH#41). Collection: payment_webhook_endpoints/\{token\}. Top-level, not tenant-scoped. Provisioned by superadmin; used by the backend to verify inbound payment webhooks from Wave and Jeko. The delivery log collection (raw webhook payloads + verification outcomes) is tracked in GH#41 — shape TBD.
+
+| Property                   | Pattern | Type             | Deprecated | Definition | Title/Description                                                                                            |
+| -------------------------- | ------- | ---------------- | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
+| + [token](#token )         | No      | string           | No         | -          | (Immutable) base64url-encoded 24-byte random token. Also the Firestore document ID and the URL path segment. |
+| + [company](#company )     | No      | string           | No         | -          | (Immutable) Company slug (e.g. gerko_studios). Identifies the tenant that owns this endpoint.                |
+| + [provider](#provider )   | No      | enum (of string) | No         | -          | (Immutable) Payment provider whose webhooks this endpoint accepts.                                           |
+| + [secret](#secret )       | No      | string           | No         | -          | Webhook signing secret for HMAC verification. Backend-only — never returned to dashboard or mobile clients.  |
+| + [active](#active )       | No      | boolean          | No         | -          | Whether this endpoint is currently active. Inactive endpoints reject incoming webhooks.                      |
+| - [createdAt](#createdAt ) | No      | Combination      | No         | -          | (Read-only) When this endpoint was provisioned.                                                              |
+
+## <a name="token"></a>1. Property `token`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) base64url-encoded 24-byte random token. Also the Firestore document ID and the URL path segment.
+
+:::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="company"></a>2. Property `company`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) Company slug (e.g. gerko_studios). Identifies the tenant that owns this endpoint.
+
+:::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**     | `enum (of string)` |
+| **Required** | Yes                |
+
+**Description:** (Immutable) Payment provider whose webhooks this endpoint accepts.
+
+Must be one of:
+* "wave"
+* "jeko"
+
+:::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="secret"></a>4. Property `secret`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Webhook signing secret for HMAC verification. Backend-only — never returned to dashboard or mobile clients.
+
+:::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
+Provider-specific webhook signing secret. Used to verify HMAC-SHA256 signatures on inbound payloads. Never expose to clients.
+:::
+
+## <a name="active"></a>5. Property `active`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `boolean` |
+| **Required** | Yes       |
+
+**Description:** Whether this endpoint is currently active. Inactive endpoints reject incoming webhooks.
+
+## <a name="createdAt"></a>6. Property `createdAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) When this endpoint was provisioned.
+
+| Any of(Option)                             |
+| ------------------------------------------ |
+| [firestore-timestamp](#createdAt_anyOf_i0) |
+| [item 1](#createdAt_anyOf_i1)              |
+
+### <a name="createdAt_anyOf_i0"></a>6.1. Property `firestore-timestamp`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | No                                |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
+
+| Property                                            | Pattern | Type    | Deprecated | Definition | Title/Description |
+| --------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#createdAt_anyOf_i0__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#createdAt_anyOf_i0__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+#### <a name="createdAt_anyOf_i0__seconds"></a>6.1.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+#### <a name="createdAt_anyOf_i0__nanoseconds"></a>6.1.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="createdAt_anyOf_i1"></a>6.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **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
+
+:::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: 23
+sidebar_position: 29
 ---
 
 # Sale
@@ -77,20 +77,20 @@ sidebar_position: 23
 
 **Description:** Sale/Purchase model (D06). Collection: companies/\{companyId\}/purchases/\{purchaseId\}. Code alias: SalesService. [Deprecated path: customers/\{custId\}/purchases/\{purchaseId\} — migrate to company-wide path per MIG-04/IG-5]
 
-| Property                         | Pattern | Type           | Deprecated | Definition                           | Title/Description                                                                                                       |
-| -------------------------------- | ------- | -------------- | ---------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| - [id](#id )                     | No      | string or null | No         | -                                    | (Read-only) Firestore document ID. Note: optional in current schema — some legacy docs may lack this field.             |
-| - [companyId](#companyId )       | No      | string or null | No         | -                                    | (Immutable) FK → Company document ID. Note: optional in current schema — should be required (see ID consistency audit). |
-| - [customerId](#customerId )     | No      | string or null | No         | -                                    | FK → Customer.id (Firestore doc ID).                                                                                    |
-| - [customerName](#customerName ) | No      | string or null | No         | -                                    | (Denormalized) From Customer.name at write time.                                                                        |
-| - [amount](#amount )             | No      | number or null | No         | -                                    | -                                                                                                                       |
-| - [items](#items )               | No      | array or null  | No         | -                                    | Line items. Reuses Order item schema.                                                                                   |
-| - [imageUrl](#imageUrl )         | No      | string or null | No         | -                                    | -                                                                                                                       |
-| - [notes](#notes )               | No      | string or null | No         | -                                    | -                                                                                                                       |
-| - [orderId](#orderId )           | No      | string or null | No         | -                                    | FK → Order.id. Link to associated Order document.                                                                       |
-| - [bookingId](#bookingId )       | No      | string or null | No         | -                                    | FK → Booking.id. Link to associated Booking document (IG-12).                                                           |
-| + [purchaseDate](#purchaseDate ) | No      | object         | No         | In #/definitions/firestore-timestamp | Firestore Timestamp serialized representation                                                                           |
-| - [createdAt](#createdAt )       | No      | Combination    | No         | -                                    | (Read-only) Server-generated creation timestamp.                                                                        |
+| Property                         | Pattern | Type           | Deprecated | Definition                           | Title/Description                                                                                                                                  |
+| -------------------------------- | ------- | -------------- | ---------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| - [id](#id )                     | No      | string or null | No         | -                                    | (Read-only) Firestore document ID. Note: optional in current schema — some legacy docs may lack this field.                                        |
+| - [companyId](#companyId )       | No      | string or null | No         | -                                    | (Immutable) FK → Company document ID. Note: optional in current schema — should be required (see ID consistency audit).                            |
+| - [customerId](#customerId )     | No      | string or null | No         | -                                    | FK → Customer.id (Firestore doc ID).                                                                                                               |
+| - [customerName](#customerName ) | No      | string or null | No         | -                                    | (Denormalized) From Customer.name at write time.                                                                                                   |
+| - [amount](#amount )             | No      | number or null | No         | -                                    | -                                                                                                                                                  |
+| - [items](#items )               | No      | array or null  | No         | -                                    | Line items. Reuses Order item schema.                                                                                                              |
+| - [imageUrl](#imageUrl )         | No      | string or null | No         | -                                    | -                                                                                                                                                  |
+| - [notes](#notes )               | No      | string or null | No         | -                                    | -                                                                                                                                                  |
+| - [orderId](#orderId )           | No      | string or null | No         | -                                    | FK → Order.id. Link to associated Order document.                                                                                                  |
+| - [bookingId](#bookingId )       | No      | string or null | No         | -                                    | FK → Booking.id. Link to associated Booking document (IG-12).                                                                                      |
+| + [purchaseDate](#purchaseDate ) | No      | object         | No         | In #/definitions/firestore-timestamp | Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
+| - [createdAt](#createdAt )       | No      | Combination    | No         | -                                    | (Read-only) Server-generated creation timestamp.                                                                                                   |
 
 ## <a name="id"></a>1. Property `id`
 
@@ -459,7 +459,7 @@ Set at creation only. This field cannot be modified after the document is create
 | **Additional properties** | Not allowed                       |
 | **Defined in**            | #/definitions/firestore-timestamp |
 
-**Description:** Firestore Timestamp serialized representation
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
 
 | Property                                      | Pattern | Type    | Deprecated | Definition | Title/Description |
 | --------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
@@ -514,7 +514,7 @@ Set at creation only. This field cannot be modified after the document is create
 | **Additional properties** | Not allowed                   |
 | **Same definition as**    | [purchaseDate](#purchaseDate) |
 
-**Description:** Firestore Timestamp serialized representation
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
 
 ### <a name="createdAt_anyOf_i1"></a>12.2. Property `item 1`
 
@@ -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-27 at 15:51:05 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +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: 25
+sidebar_position: 31
 ---
 
 # 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-27 at 15:51:05 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000

package/data/docs/models/site.md

@@ -1,7 +1,7 @@
 ---
 title: "Site"
 sidebar_label: "Site"
-sidebar_position: 24
+sidebar_position: 30
 ---
 
 # 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-27 at 15:51:05 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +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: 27
+sidebar_position: 33
 ---
 
 # StocktakeItem
@@ -363,7 +363,7 @@ Read-time hint snapshot of the counter's display name (GH#29 §3 / Q10).
 | **Additional properties** | Not allowed                       |
 | **Defined in**            | #/definitions/firestore-timestamp |
 
-**Description:** Firestore Timestamp serialized representation
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
 
 | Property                                            | Pattern | Type    | Deprecated | Definition | Title/Description |
 | --------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
@@ -487,7 +487,7 @@ Read-time hint snapshot of the verifier's display name (GH#29 §3 / Q10).
 | **Additional properties** | Not allowed                               |
 | **Same definition as**    | [countedAt_anyOf_i0](#countedAt_anyOf_i0) |
 
-**Description:** Firestore Timestamp serialized representation
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
 
 ### <a name="verifiedAt_anyOf_i1"></a>16.2. Property `item 1`
 
@@ -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-27 at 15:51:05 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000

package/data/docs/models/stocktake.md

@@ -1,7 +1,7 @@
 ---
 title: "Stocktake"
 sidebar_label: "Stocktake"
-sidebar_position: 26
+sidebar_position: 32
 ---
 
 # Stocktake
@@ -462,7 +462,7 @@ Server-derived = sum of (item.delta × item.costPerUnit) across COUNTED items, i
 | **Additional properties** | Not allowed                     |
 | **Same definition as**    | [stocktakeDate](#stocktakeDate) |
 
-**Description:** Firestore Timestamp serialized representation
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
 
 ### <a name="completedAt_anyOf_i1"></a>15.2. Property `item 1`
 
@@ -503,7 +503,7 @@ Server-set on transition to COMPLETED. Distinct from stocktakeDate (the period c
 | **Additional properties** | Not allowed                     |
 | **Same definition as**    | [stocktakeDate](#stocktakeDate) |
 
-**Description:** Firestore Timestamp serialized representation
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
 
 ### <a name="createdAt_anyOf_i1"></a>16.2. Property `item 1`
 
@@ -632,7 +632,7 @@ Read-time hint snapshot of the completer's display name (GH#29 §3 / Q10).
 | **Additional properties** | Not allowed                     |
 | **Same definition as**    | [stocktakeDate](#stocktakeDate) |
 
-**Description:** Firestore Timestamp serialized representation
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
 
 ### <a name="updatedAt_anyOf_i1"></a>21.2. Property `item 1`
 
@@ -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-27 at 15:51:05 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +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: 28
+sidebar_position: 34
 ---
 
 # Ticket
@@ -208,7 +208,7 @@ Must be one of:
 | **Additional properties** | Not allowed                       |
 | **Defined in**            | #/definitions/firestore-timestamp |
 
-**Description:** Firestore Timestamp serialized representation
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
 
 | Property                                         | Pattern | Type    | Deprecated | Definition | Title/Description |
 | ------------------------------------------------ | ------- | ------- | ---------- | ---------- | ----------------- |
@@ -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-27 at 15:51:05 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +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

@@ -0,0 +1,249 @@
+---
+title: "User"
+sidebar_label: "User"
+sidebar_position: 35
+---
+
+# User
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "id": null,
+  "displayName": null,
+  "email": null,
+  "phoneE164": null,
+  "companyId": null,
+  "role": null,
+  "isActive": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `displayName`](#displayName)
+- [3. Property `email`](#email)
+- [4. Property `phoneE164`](#phoneE164)
+- [5. Property `companyId`](#companyId)
+- [6. Property `role`](#role)
+- [7. Property `isActive`](#isActive)
+- [8. Property `createdAt`](#createdAt)
+  - [8.1. Property `firestore-timestamp`](#createdAt_anyOf_i0)
+    - [8.1.1. Property `_seconds`](#createdAt_anyOf_i0__seconds)
+    - [8.1.2. Property `_nanoseconds`](#createdAt_anyOf_i0__nanoseconds)
+  - [8.2. Property `item 1`](#createdAt_anyOf_i1)
+- [9. Property `updatedAt`](#updatedAt)
+  - [9.1. Property `firestore-timestamp`](#updatedAt_anyOf_i0)
+  - [9.2. Property `item 1`](#updatedAt_anyOf_i1)
+
+|                           |                    |
+| ------------------------- | ------------------ |
+| **Type**                  | `object`           |
+| **Required**              | No                 |
+| **Additional properties** | Not allowed        |
+| **Defined in**            | #/definitions/user |
+
+**Description:** User / staff account. Collection: users/\{uid\}. Document ID is always the Firebase Auth UID (decision #27). phoneE164 is the canonical E.164 phone field for OTP lookup. Legacy phone-keyed documents must be migrated to uid-keyed docs with phoneE164 set.
+
+| Property                       | Pattern | Type            | Deprecated | Definition | Title/Description                                                                                                                    |
+| ------------------------------ | ------- | --------------- | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| - [id](#id )                   | No      | string or null  | No         | -          | (Read-only) Firebase Auth UID. Matches the Firestore document ID.                                                                    |
+| - [displayName](#displayName ) | No      | string or null  | No         | -          | User display name from Firebase Auth or manually set.                                                                                |
+| - [email](#email )             | No      | string or null  | No         | -          | Email address. Present for email/Google auth users.                                                                                  |
+| - [phoneE164](#phoneE164 )     | No      | string or null  | No         | -          | E.164-normalized phone number (e.g. +2250777471485). Canonical phone identity field; used for WhatsApp OTP lookup via indexed query. |
+| - [companyId](#companyId )     | No      | string or null  | No         | -          | (Immutable) FK → Company document ID. Present for staff accounts scoped to a company.                                                |
+| - [role](#role )               | No      | string or null  | No         | -          | Staff role within the company (e.g. admin, manager, staff). Application-defined.                                                     |
+| - [isActive](#isActive )       | No      | boolean or null | No         | -          | Whether this user account is active. Inactive accounts are denied access.                                                            |
+| - [createdAt](#createdAt )     | No      | Combination     | No         | -          | (Read-only) When the user document was created.                                                                                      |
+| - [updatedAt](#updatedAt )     | No      | Combination     | No         | -          | (Read-only) When the user document was last updated.                                                                                 |
+
+## <a name="id"></a>1. Property `id`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only) Firebase Auth UID. Matches the Firestore document ID.
+
+:::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="displayName"></a>2. Property `displayName`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** User display name from Firebase Auth or manually set.
+
+## <a name="email"></a>3. Property `email`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** Email address. Present for email/Google auth users.
+
+## <a name="phoneE164"></a>4. Property `phoneE164`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** E.164-normalized phone number (e.g. +2250777471485). Canonical phone identity field; used for WhatsApp OTP lookup via indexed query.
+
+:::note
+E.164 format with leading + (e.g. +2250777471485). Canonical phone identity field (decision #27). Distinct from wa_id (Meta conversation key). Server must normalize at write time: 8-digit CI local → prepend +225.
+:::
+
+:::tip When to set
+Set when the user authenticated via phone (WhatsApp OTP) or when a staff member's phone is known. Required for WhatsApp OTP lookup — add a Firestore composite index on phoneE164.
+:::
+
+## <a name="companyId"></a>5. Property `companyId`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Immutable) FK → Company document ID. Present for staff accounts scoped to a company.
+
+:::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="role"></a>6. Property `role`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** Staff role within the company (e.g. admin, manager, staff). Application-defined.
+
+## <a name="isActive"></a>7. Property `isActive`
+
+|              |                   |
+| ------------ | ----------------- |
+| **Type**     | `boolean or null` |
+| **Required** | No                |
+
+**Description:** Whether this user account is active. Inactive accounts are denied access.
+
+## <a name="createdAt"></a>8. Property `createdAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) When the user document was created.
+
+| Any of(Option)                             |
+| ------------------------------------------ |
+| [firestore-timestamp](#createdAt_anyOf_i0) |
+| [item 1](#createdAt_anyOf_i1)              |
+
+### <a name="createdAt_anyOf_i0"></a>8.1. Property `firestore-timestamp`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | No                                |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
+
+| Property                                            | Pattern | Type    | Deprecated | Definition | Title/Description |
+| --------------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#createdAt_anyOf_i0__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#createdAt_anyOf_i0__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+#### <a name="createdAt_anyOf_i0__seconds"></a>8.1.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+#### <a name="createdAt_anyOf_i0__nanoseconds"></a>8.1.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="createdAt_anyOf_i1"></a>8.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+:::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="updatedAt"></a>9. Property `updatedAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) When the user document was last updated.
+
+| Any of(Option)                             |
+| ------------------------------------------ |
+| [firestore-timestamp](#updatedAt_anyOf_i0) |
+| [item 1](#updatedAt_anyOf_i1)              |
+
+### <a name="updatedAt_anyOf_i0"></a>9.1. Property `firestore-timestamp`
+
+|                           |                                           |
+| ------------------------- | ----------------------------------------- |
+| **Type**                  | `object`                                  |
+| **Required**              | No                                        |
+| **Additional properties** | Not allowed                               |
+| **Same definition as**    | [createdAt_anyOf_i0](#createdAt_anyOf_i0) |
+
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
+
+### <a name="updatedAt_anyOf_i1"></a>9.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **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
+
+:::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.
+:::