@ingenx-io/valets-schema-mcp-server 0.1.1 → 0.1.3

package/data/docs/index.md

@@ -0,0 +1,102 @@
+---
+title: "Overview"
+sidebar_label: "Overview"
+sidebar_position: 0
+slug: /
+---
+
+# @valets/schema Documentation
+
+Browsable documentation for the Valets canonical data model, auto-generated from **Zod schemas** via JSON Schema.
+
+## How this works
+
+```
+Zod (source of truth) → JSON Schema → json-schema-for-humans → This site
+```
+
+Developers own the Zod source in `packages/schema/src/`. When schemas change, this documentation regenerates automatically.
+
+## What's documented
+
+### Enums (14)
+
+Status enums that drive business logic across Order, Booking, Event, and Loyalty domains:
+
+| Enum | Values | Description |
+|------|--------|-------------|
+| [BookingStatus](enums/booking-status) | 6 values | Booking lifecycle status. COMPLETED_MIXED = some sessions completed, others cancelled/no-show. |
+| [CustomerPaymentStatus](enums/customer-payment-status) | 6 values | Customer payment lifecycle status (D22). Tracks allocation progress of received payments. |
+| [CustomerPaymentTargetType](enums/customer-payment-target-type) | 3 values | Target document type for customer payment allocation. |
+| [DeliveryType](enums/delivery-type) | 3 values | Fulfillment channel for an order. Determines whether the customer comes to the business (ON_SITE), collects their order themselves (PICK_UP), or receives a physical delivery (DELIVERY). Drives whether fulfillmentStatus is relevant. |
+| [EventStatus](enums/event-status) | 4 values | Ticketed event lifecycle (D32). Mobile-only today; Dashboard in Wave 4. |
+| [FulfillmentStatus](enums/fulfillment-status) | 6 values | Delivery/fulfillment lifecycle (D34). Optional — null for in-person orders. |
+| [LoyaltyTransactionType](enums/loyalty-transaction-type) | 6 values | Loyalty point transaction type (D07). SCREAMING_SNAKE past tense. |
+| [OrderStatus](enums/order-status) | 7 values | Core order lifecycle status (D03, D34). Universal across all business types. Replaces the Dashboard's legacy 20-value flat enum (MIG-11). |
+| [PaymentMethod](enums/payment-method) | 10 values | Unified payment method set with African + global methods (D02). |
+| [PaymentProofStatus](enums/payment-proof-status) | 3 values | Payment proof review status. Used by Order and Booking payment proof workflows. |
+| [PaymentStatus](enums/payment-status) | 7 values | Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking. |
+| [ReturnStatus](enums/return-status) | 6 values | Post-sale return/exchange lifecycle (D34). Optional — null until return or exchange initiated. |
+| [SessionStatus](enums/session-status) | 6 values | Per-date/per-slot booking session status (D19). Dashboard is sole writer; Mobile is read-only. |
+| [TicketStatus](enums/ticket-status) | 3 values | Event ticket status (D32). VALID = active and unused. |
+
+
+### Models (17)
+
+Core Firestore document schemas:
+
+| Model | Fields | Required | Description |
+|-------|--------|----------|-------------|
+| [Booking](models/booking) | 52 | 7 | — |
+| [BookingVersion](models/booking-version) | 9 | 6 | — |
+| [Customer](models/customer) | 17 | 4 | — |
+| [CustomerPayment](models/customer-payment) | 17 | 12 | — |
+| [CustomerPaymentAllocation](models/customer-payment-allocation) | 14 | 8 | — |
+| [Event](models/event) | 15 | 9 | — |
+| [LoyaltyConfig](models/loyalty-config) | 11 | 2 | — |
+| [LoyaltyReward](models/loyalty-reward) | 11 | 5 | — |
+| [LoyaltyStatus](models/loyalty-status) | 9 | 2 | — |
+| [LoyaltyTransaction](models/loyalty-transaction) | 16 | 4 | — |
+| [MetricsCurrent](models/metrics-current) | 25 | 25 | — |
+| [MetricsDaily](models/metrics-daily) | 26 | 26 | — |
+| [MetricsMonthly](models/metrics-monthly) | 26 | 26 | — |
+| [Order](models/order) | 47 | 8 | — |
+| [OrderItem](models/order-item) | 12 | 3 | — |
+| [Sale](models/sale) | 12 | 1 | — |
+| [Ticket](models/ticket) | 16 | 6 | — |
+
+
+
+## ⚗️ Proposed (Work In Progress)
+
+> These schemas are under review and **not yet part of `@valets/schema`**. Shape may change.
+
+
+| Model | Fields | Required | Description |
+|-------|--------|----------|-------------|
+| [PaymentSummary](proposed/models/payment-summary) | 10 | 9 | — |
+
+
+
+
+| Enum | Values | Description |
+|------|--------|-------------|
+| [AttentionStatus](proposed/enums/attention-status) | 4 values | Operational attention status for Order and Booking (D39). Controls home-page queue assignment. Server-owned — set via triggers or callable fn only. |
+| [PendingIssue](proposed/enums/pending-issue) | 11 values | Specific detected conditions on an Order or Booking requiring human action (D39). Stored as an array — multiple issues can be active simultaneously. Server-owned. |
+
+
+
+
+## Machine-friendly formats
+
+| Format | URL | Use case |
+|--------|-----|----------|
+| [schemas.json](/schemas.json) | `/schemas.json` | Consolidated JSON Schema bundle — programmatic access, tooling |
+| [llms.txt](/llms.txt) | `/llms.txt` | LLM-optimized summary — context injection for AI agents |
+| [openapi.yaml](/openapi.yaml) | `/openapi.yaml` | OpenAPI 3.1 spec — Postman, Swagger UI, codegen, CI validation |
+
+## Source
+
+- **Zod schemas**: `packages/schema/src/`
+- **JSON Schema output**: `packages/schema/json-schema/`
+- **Dart codegen output**: `packages/schema/dart/`

package/data/docs/models/booking-version.md

@@ -0,0 +1,295 @@
+---
+title: "BookingVersion"
+sidebar_label: "BookingVersion"
+sidebar_position: 2
+---
+
+# BookingVersion
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "id": "bk_abc123def456",
+  "bookingId": "boo_ref123",
+  "companyId": "comp_xyz789",
+  "changeType": "CREATE",
+  "changedAt": "changedAt",
+  "changedBy": null,
+  "changedByRole": "DASHBOARD",
+  "fieldsChanged": null,
+  "snapshot": {}
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `bookingId`](#bookingId)
+- [3. Property `companyId`](#companyId)
+- [4. Property `changeType`](#changeType)
+- [5. Property `changedAt`](#changedAt)
+  - [5.1. Property `_seconds`](#changedAt__seconds)
+  - [5.2. Property `_nanoseconds`](#changedAt__nanoseconds)
+- [6. Property `changedBy`](#changedBy)
+- [7. Property `changedByRole`](#changedByRole)
+- [8. Property `fieldsChanged`](#fieldsChanged)
+  - [8.1. fieldsChanged items](#fieldsChanged_items)
+- [9. Property `snapshot`](#snapshot)
+  - [9.1. Property `additionalProperties`](#snapshot_additionalProperties)
+
+|                           |                               |
+| ------------------------- | ----------------------------- |
+| **Type**                  | `object`                      |
+| **Required**              | No                            |
+| **Additional properties** | Not allowed                   |
+| **Defined in**            | #/definitions/booking-version |
+
+**Description:** BookingVersion model (D18). Collection: companies/\{companyId\}/bookings/\{bookingId\}/versions/\{versionId\}. Server-owned audit trail written by Firebase trigger on every Booking mutation. Captures writes from all clients.
+
+| Property                           | Pattern | Type                    | Deprecated | Definition                           | Title/Description                                                                                                                                                   |
+| ---------------------------------- | ------- | ----------------------- | ---------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| + [id](#id )                       | No      | string                  | No         | -                                    | (Read-only) Firestore document ID. Server-generated version record.                                                                                                 |
+| + [bookingId](#bookingId )         | No      | string                  | No         | -                                    | (Immutable) FK → Booking.id. Parent booking this version records.                                                                                                   |
+| + [companyId](#companyId )         | No      | string                  | No         | -                                    | (Immutable) FK → Company document ID. Denormalized for direct queries.                                                                                              |
+| + [changeType](#changeType )       | No      | enum (of string)        | No         | -                                    | (Immutable) What caused this version record: CREATE, UPDATE, or DELETE.                                                                                             |
+| + [changedAt](#changedAt )         | No      | object                  | No         | In #/definitions/firestore-timestamp | (Read-only) Timestamp of the write that created this version. Server-set.                                                                                           |
+| - [changedBy](#changedBy )         | No      | string or null          | No         | -                                    | (Immutable) FK → User/staff UID who made the change. Null for server-originated writes.                                                                             |
+| - [changedByRole](#changedByRole ) | No      | enum (of string)        | No         | -                                    | (Immutable) Which platform/context made the write: DASHBOARD, MOBILE, FIREBASE (trigger), CLI (migration script), or UNKNOWN. SCREAMING_SNAKE per D04.              |
+| - [fieldsChanged](#fieldsChanged ) | No      | array of string or null | No         | -                                    | (Immutable, Read-only) List of field paths that changed in this write. Populated by the Firebase trigger diff. Null for CREATE records.                             |
+| + [snapshot](#snapshot )           | No      | object                  | No         | -                                    | (Immutable, Read-only) Full snapshot of the Booking document immediately after the write. Untyped to avoid circular schema dependency — cast to Booking at runtime. |
+
+## <a name="id"></a>1. Property `id`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Firestore document ID. Server-generated version record.
+
+:::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="bookingId"></a>2. Property `bookingId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → Booking.id. Parent booking this version records.
+
+:::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="companyId"></a>3. Property `companyId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → Company document ID. Denormalized for direct queries.
+
+:::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="changeType"></a>4. Property `changeType`
+
+|              |                    |
+| ------------ | ------------------ |
+| **Type**     | `enum (of string)` |
+| **Required** | Yes                |
+
+**Description:** (Immutable) What caused this version record: CREATE, UPDATE, or DELETE.
+
+Must be one of:
+* "CREATE"
+* "UPDATE"
+* "DELETE"
+
+:::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.
+:::
+
+:::note
+DELETE versions are written when a booking is soft-deleted (CRDT _deleted flag). Hard deletes bypass this trail.
+:::
+
+## <a name="changedAt"></a>5. Property `changedAt`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | Yes                               |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** (Read-only) Timestamp of the write that created this version. Server-set.
+
+| Property                                   | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ------------------------------------------ | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#changedAt__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#changedAt__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+### <a name="changedAt__seconds"></a>5.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="changedAt__nanoseconds"></a>5.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+:::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="changedBy"></a>6. Property `changedBy`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Immutable) FK → User/staff UID who made the change. Null for server-originated writes.
+
+:::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.
+:::
+
+:::note
+Null when the write originated from a Firebase trigger, CLI script, or unknown source.
+:::
+
+## <a name="changedByRole"></a>7. Property `changedByRole`
+
+|              |                    |
+| ------------ | ------------------ |
+| **Type**     | `enum (of string)` |
+| **Required** | No                 |
+
+**Description:** (Immutable) Which platform/context made the write: DASHBOARD, MOBILE, FIREBASE (trigger), CLI (migration script), or UNKNOWN. SCREAMING_SNAKE per D04.
+
+Must be one of:
+* "DASHBOARD"
+* "MOBILE"
+* "FIREBASE"
+* "CLI"
+* "UNKNOWN"
+
+:::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.
+:::
+
+:::note
+Populated by the Firebase trigger from the write context. Helps distinguish client vs. server writes.
+:::
+
+## <a name="fieldsChanged"></a>8. Property `fieldsChanged`
+
+|              |                           |
+| ------------ | ------------------------- |
+| **Type**     | `array of string or null` |
+| **Required** | No                        |
+
+**Description:** (Immutable, Read-only) List of field paths that changed in this write. Populated by the Firebase trigger diff. Null for CREATE records.
+
+|                      | Array restrictions |
+| -------------------- | ------------------ |
+| **Min items**        | N/A                |
+| **Max items**        | N/A                |
+| **Items unicity**    | False              |
+| **Additional items** | False              |
+| **Tuple validation** | See below          |
+
+| Each item of this array must be             | Description |
+| ------------------------------------------- | ----------- |
+| [fieldsChanged items](#fieldsChanged_items) | -           |
+
+### <a name="fieldsChanged_items"></a>8.1. fieldsChanged items
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **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.
+:::
+
+:::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.
+:::
+
+:::note
+Dot-notation paths for nested fields (e.g. "bookingDates.0.status"). Populated by diff in Firebase trigger. Null for CREATE versions.
+:::
+
+## <a name="snapshot"></a>9. Property `snapshot`
+
+|                           |                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| **Type**                  | `object`                                                                              |
+| **Required**              | Yes                                                                                   |
+| **Additional properties** | [Each additional property must conform to the schema](#snapshot_additionalProperties) |
+
+**Description:** (Immutable, Read-only) Full snapshot of the Booking document immediately after the write. Untyped to avoid circular schema dependency — cast to Booking at runtime.
+
+| Property                              | Pattern | Type   | Deprecated | Definition | Title/Description |
+| ------------------------------------- | ------- | ------ | ---------- | ---------- | ----------------- |
+| - [](#snapshot_additionalProperties ) | No      | object | No         | -          | -                 |
+
+### <a name="snapshot_additionalProperties"></a>9.1. Property `additionalProperties`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `object`         |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +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.
+:::
+
+:::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.
+:::
+
+:::note
+Full Booking document at the time of write. Typed as a string-keyed record to avoid circular schema reference. Consumers cast to Booking at runtime.
+:::
+
+:::info See also
+**Decisions:** `D18`
+:::
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D18** | Firebase BookingVersion ownership |