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

package/data/docs/models/user.md

@@ -0,0 +1,249 @@
+---
+title: "User"
+sidebar_label: "User"
+sidebar_position: 31
+---
+
+# 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 12:42:51 +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: 29
+sidebar_position: 32
 ---
 
 # WhatsappInboundMessage
@@ -366,4 +366,4 @@ Do not include in write requests. This field is set exclusively by the server (F
 Specific value: `true`
 
 ----------------------------------------------------------------------------------------------------------------------------
-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 12:42:51 +0000

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

@@ -1,7 +1,7 @@
 ---
 title: "WhatsappOutboundLifecycleEvent"
 sidebar_label: "WhatsappOutboundLifecycleEvent"
-sidebar_position: 30
+sidebar_position: 33
 ---
 
 # 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-27 at 15:51:06 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:51 +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-outbound-message.md

@@ -1,7 +1,7 @@
 ---
 title: "WhatsappOutboundMessage"
 sidebar_label: "WhatsappOutboundMessage"
-sidebar_position: 31
+sidebar_position: 34
 ---
 
 # WhatsappOutboundMessage
@@ -461,7 +461,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Additional properties** | Not allowed             |
 | **Same definition as**    | [createdAt](#createdAt) |
 
-**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="sentAt_anyOf_i1"></a>15.2. Property `item 1`
 
@@ -498,7 +498,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Additional properties** | Not allowed             |
 | **Same definition as**    | [createdAt](#createdAt) |
 
-**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="deliveredAt_anyOf_i1"></a>16.2. Property `item 1`
 
@@ -535,7 +535,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Additional properties** | Not allowed             |
 | **Same definition as**    | [createdAt](#createdAt) |
 
-**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="readAt_anyOf_i1"></a>17.2. Property `item 1`
 
@@ -572,7 +572,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Additional properties** | Not allowed             |
 | **Same definition as**    | [createdAt](#createdAt) |
 
-**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="failedAt_anyOf_i1"></a>18.2. Property `item 1`
 
@@ -582,7 +582,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-27 at 15:51:06 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:51 +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-template.md

@@ -1,7 +1,7 @@
 ---
 title: "WhatsappTemplate"
 sidebar_label: "WhatsappTemplate"
-sidebar_position: 32
+sidebar_position: 35
 ---
 
 # WhatsappTemplate
@@ -287,7 +287,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 **Description:** (Read-only) Rendered preview text for display in the dashboard picker.
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-27 at 15:51:06 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:51 +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/static/cookbook.json

@@ -0,0 +1,150 @@
+{
+  "version": "1",
+  "recipes": [
+    {
+      "slug": "write-model-code",
+      "title": "Writing code that touches a model",
+      "summary": "How to look up a model's schema, identify field constraints, and avoid writing to server-set or immutable fields.",
+      "steps": [
+        {
+          "step": 1,
+          "tool": "schema_overview",
+          "args": {},
+          "note": "Start here to see all available models and enums. Identify the model(s) your code will read or write."
+        },
+        {
+          "step": 2,
+          "tool": "get_schema",
+          "args": { "name": "<model-name>" },
+          "note": "Fetch the full JSON Schema for the model. Inspect each field for constraint extensions: readOnly, x-immutable, deprecated, x-note, x-when."
+        },
+        {
+          "step": 3,
+          "tool": "get_openapi",
+          "args": { "component": "<ModelCreate>" },
+          "note": "Use the Create variant (PascalCase + 'Create', e.g. 'OrderCreate') to determine the correct write shape. readOnly and deprecated fields are excluded from required[] here."
+        },
+        {
+          "step": 4,
+          "tool": "get_openapi",
+          "args": { "component": "<ModelUpdate>" },
+          "note": "For PATCH operations use the Update variant. All fields become optional and readOnly / x-immutable fields are excluded entirely."
+        },
+        {
+          "step": 5,
+          "tool": "get_doc",
+          "args": { "slug": "models/<model-name>" },
+          "note": "Read the human-readable doc page for callout blocks: server-set warnings, immutable notices, deprecation alerts, and implementation tips."
+        }
+      ],
+      "field_constraint_cheatsheet": {
+        "readOnly: true": "Set by Firestore trigger or Admin SDK only — never write from client or backend application code.",
+        "x-immutable: true": "Set exactly once at document creation. Any subsequent write to this field is a bug.",
+        "deprecated: true": "Do not write in new code. Check x-replaced-by for the replacement field.",
+        "x-internal: true": "Backend-only collection — consumers must not depend on this model's shape."
+      },
+      "tips": [
+        "Field descriptions often contain '(GH#N)' or '(D-id)' references — use get_decision to trace rationale.",
+        "If a field is absent from ModelCreate, it is either readOnly (server-sets it) or deprecated.",
+        "Run get_schema on related enums (e.g. 'payment-status') to understand the allowed values for enum fields."
+      ]
+    },
+    {
+      "slug": "field-history",
+      "title": "Understanding a field's history or rationale",
+      "summary": "How to trace why a field exists, what decision or issue drove it, and whether it has been migrated or superseded.",
+      "steps": [
+        {
+          "step": 1,
+          "tool": "search_docs",
+          "args": { "query": "<fieldName>" },
+          "note": "Find every doc page that mentions the field. This surfaces the model page, any decision pages, and migration docs."
+        },
+        {
+          "step": 2,
+          "tool": "get_schema",
+          "args": { "name": "<model-name>" },
+          "note": "Read the field's 'description' value directly. It typically includes a GH# issue reference or a D-id decision reference."
+        },
+        {
+          "step": 3,
+          "tool": "list_decisions",
+          "args": {},
+          "note": "Scan all decisions for ones related to the model or field. Look at 'status': accepted decisions are live; superseded ones have been replaced."
+        },
+        {
+          "step": 4,
+          "tool": "get_decision",
+          "args": { "id": "<D-id>" },
+          "note": "Get full context: rationale, migration path, affected models, and implementation status."
+        },
+        {
+          "step": 5,
+          "tool": "get_doc",
+          "args": { "slug": "decisions/migrations" },
+          "note": "Check the migrations page for a changelog of field-level changes and the order in which they must be applied."
+        }
+      ],
+      "tips": [
+        "If a field has 'x-replaced-by', check that replacement field's schema and the decision that drove the change.",
+        "A decision with status 'pending' means the change is not yet live — do not depend on the new shape yet.",
+        "search_docs with the GH# (e.g. 'GH#48') will surface all docs that reference that issue."
+      ]
+    },
+    {
+      "slug": "whatsapp-conversation-display",
+      "title": "Displaying WhatsApp conversation history for an order",
+      "summary": "Current workaround for rendering a per-order WhatsApp thread using NotificationRecord documents. There is no dedicated WhatsApp conversation model yet; outbound messages are reconstructed from the notification audit log.",
+      "workaround_notice": "This is a temporary workaround (GH#48). NotificationRecord captures outbound messages only. Inbound customer replies are not stored in Firestore. A proper WhatsApp conversation model is a future concern.",
+      "steps": [
+        {
+          "step": 1,
+          "tool": "get_schema",
+          "args": { "name": "notification-record" },
+          "note": "Understand the full NotificationRecord shape. Note: every field is readOnly — this is a backend-written audit log, consumers read only."
+        },
+        {
+          "step": 2,
+          "tool": "get_doc",
+          "args": { "slug": "collections/firestore-paths" },
+          "note": "Review the two notification collection paths: company-wide (always written) and order-scoped (dual-write when relatedEntity.type === 'order')."
+        },
+        {
+          "step": 3,
+          "action": "query",
+          "collection": "companies/{companyId}/orders/{orderId}/notifications",
+          "filter": "type == 'whatsapp'",
+          "sort": "sentAt ASC",
+          "note": "Use the order-scoped subcollection for O(1) per-order lookup. Filter to type='whatsapp' to exclude email/sms/push records."
+        },
+        {
+          "step": 4,
+          "action": "render",
+          "fields": {
+            "message_content": "templateParams — filled-in template variable values at send time; reconstruct the message text without calling the Meta API.",
+            "delivery_status": "status — 'sent' | 'failed' | 'pending'",
+            "failure_reason": "error — present only when status === 'failed'",
+            "timestamp": "sentAt — Firestore Timestamp; convert to local time for display",
+            "meta_message_id": "wamid — WhatsApp message ID from Meta; use for deduplication if querying both collection paths"
+          },
+          "note": "All display fields are reconstructable from the NotificationRecord alone — no Meta API call needed."
+        },
+        {
+          "step": 5,
+          "action": "deduplicate",
+          "note": "If you query both companies/{cid}/notifications (filtered by relatedEntity.id === orderId) AND the order-scoped subcollection, deduplicate by 'id' — both paths write the same document ID."
+        }
+      ],
+      "related_models": {
+        "notification-record": "GH#48 — the model used in this workaround",
+        "whatsapp-outbound-message": "GH#43 — dashboard-initiated WhatsApp sends. Separate from backend-automated NotificationRecords but both appear in the conversation thread. Query this collection too for a complete view."
+      },
+      "tips": [
+        "notification-record covers ALL channels (email, whatsapp, sms, push). Always filter by type='whatsapp'.",
+        "metadata field may contain 'templateName', 'senderPhoneId', 'orderNumber' — useful for display headers.",
+        "The order-scoped subcollection only exists if at least one notification with relatedEntity.type='order' was sent. Check for its absence gracefully.",
+        "For a company-wide WhatsApp audit (not order-scoped), query companies/{cid}/notifications filtered by type='whatsapp'."
+      ]
+    }
+  ]
+}