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

package/data/docs/models/ticket.md

@@ -0,0 +1,405 @@
+---
+title: "Ticket"
+sidebar_label: "Ticket"
+sidebar_position: 17
+---
+
+# Ticket
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "id": "bk_abc123def456",
+  "eventId": "eve_ref123",
+  "companyId": "comp_xyz789",
+  "customerId": null,
+  "customerName": null,
+  "customerEmail": null,
+  "customerPhone": null,
+  "status": "status",
+  "usedAt": "usedAt",
+  "usedBy": null,
+  "usedByName": null,
+  "price": null,
+  "notes": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt",
+  "createdBy": null
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `eventId`](#eventId)
+- [3. Property `companyId`](#companyId)
+- [4. Property `customerId`](#customerId)
+- [5. Property `customerName`](#customerName)
+- [6. Property `customerEmail`](#customerEmail)
+- [7. Property `customerPhone`](#customerPhone)
+- [8. Property `status`](#status)
+- [9. Property `usedAt`](#usedAt)
+  - [9.1. Property `firestore-timestamp`](#usedAt_anyOf_i0)
+    - [9.1.1. Property `_seconds`](#usedAt_anyOf_i0__seconds)
+    - [9.1.2. Property `_nanoseconds`](#usedAt_anyOf_i0__nanoseconds)
+  - [9.2. Property `item 1`](#usedAt_anyOf_i1)
+- [10. Property `usedBy`](#usedBy)
+- [11. Property `usedByName`](#usedByName)
+- [12. Property `price`](#price)
+- [13. Property `notes`](#notes)
+- [14. Property `createdAt`](#createdAt)
+  - [14.1. Property `_seconds`](#usedAt_anyOf_i0__seconds)
+  - [14.2. Property `_nanoseconds`](#usedAt_anyOf_i0__nanoseconds)
+- [15. Property `updatedAt`](#updatedAt)
+  - [15.1. Property `_seconds`](#usedAt_anyOf_i0__seconds)
+  - [15.2. Property `_nanoseconds`](#usedAt_anyOf_i0__nanoseconds)
+- [16. Property `createdBy`](#createdBy)
+
+|                           |                      |
+| ------------------------- | -------------------- |
+| **Type**                  | `object`             |
+| **Required**              | No                   |
+| **Additional properties** | Not allowed          |
+| **Defined in**            | #/definitions/ticket |
+
+**Description:** Ticket model (D32). Collection: companies/\{companyId\}/events/\{eventId\}/tickets/\{ticketId\}. Mobile-only today; Dashboard in Wave 4.
+
+| Property                           | Pattern | Type             | Deprecated | Definition                           | Title/Description                                                                                                      |
+| ---------------------------------- | ------- | ---------------- | ---------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| + [id](#id )                       | No      | string           | No         | -                                    | (Read-only) Firestore document ID. Note: Ticket does not have a uid field.                                             |
+| + [eventId](#eventId )             | No      | string           | No         | -                                    | (Immutable) FK → Event.id. Parent event this ticket belongs to. Set at creation.                                       |
+| + [companyId](#companyId )         | No      | string           | No         | -                                    | (Immutable, Denormalized) FK → Company document ID. Denormalized from parent Event for direct queries.                 |
+| - [customerId](#customerId )       | No      | string or null   | No         | -                                    | FK → Customer.id. Optional structured link to Customer document (D29). Added additively alongside denormalized fields. |
+| - [customerName](#customerName )   | No      | string or null   | No         | -                                    | (Denormalized) From Customer.name at write time.                                                                       |
+| - [customerEmail](#customerEmail ) | No      | string or null   | No         | -                                    | (Denormalized) From Customer.email at write time.                                                                      |
+| - [customerPhone](#customerPhone ) | No      | string or null   | No         | -                                    | (Denormalized) From Customer.phone at write time.                                                                      |
+| + [status](#status )               | No      | enum (of string) | No         | In #/definitions/ticket-status       | Ticket lifecycle (D32). SCREAMING_SNAKE per D04. MIG-10 migrates legacy lowercase values.                              |
+| - [usedAt](#usedAt )               | No      | Combination      | No         | -                                    | (Read-only) Timestamp when ticket was scanned/used. Set by scan operation.                                             |
+| - [usedBy](#usedBy )               | No      | string or null   | No         | -                                    | (Read-only) FK → User/staff UID who scanned the ticket.                                                                |
+| - [usedByName](#usedByName )       | No      | string or null   | No         | -                                    | (Read-only, Denormalized) From User display name at scan time.                                                         |
+| - [price](#price )                 | No      | number or null   | No         | -                                    | -                                                                                                                      |
+| - [notes](#notes )                 | No      | string or null   | No         | -                                    | -                                                                                                                      |
+| + [createdAt](#createdAt )         | No      | object           | No         | In #/definitions/firestore-timestamp | (Read-only) Server-generated creation timestamp.                                                                       |
+| + [updatedAt](#updatedAt )         | No      | object           | No         | In #/definitions/firestore-timestamp | (Read-only) Server-generated update timestamp.                                                                         |
+| - [createdBy](#createdBy )         | No      | string or null   | No         | -                                    | (Immutable) FK → User/staff UID who created this ticket.                                                               |
+
+## <a name="id"></a>1. Property `id`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Firestore document ID. Note: Ticket does not have a uid field.
+
+:::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="eventId"></a>2. Property `eventId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → Event.id. Parent event this ticket belongs to. Set at creation.
+
+:::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, Denormalized) FK → Company document ID. Denormalized from parent Event 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="customerId"></a>4. Property `customerId`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** FK → Customer.id. Optional structured link to Customer document (D29). Added additively alongside denormalized fields.
+
+:::note
+Added additively per D29. Denormalized customerName/email/phone are kept for backwards compatibility. Null on tickets created before D29 was applied.
+:::
+
+:::info See also
+**Decisions:** `D29`
+:::
+
+## <a name="customerName"></a>5. Property `customerName`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Denormalized) From Customer.name at write time.
+
+## <a name="customerEmail"></a>6. Property `customerEmail`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Denormalized) From Customer.email at write time.
+
+## <a name="customerPhone"></a>7. Property `customerPhone`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Denormalized) From Customer.phone at write time.
+
+## <a name="status"></a>8. Property `status`
+
+|                |                             |
+| -------------- | --------------------------- |
+| **Type**       | `enum (of string)`          |
+| **Required**   | Yes                         |
+| **Defined in** | #/definitions/ticket-status |
+
+**Description:** Ticket lifecycle (D32). SCREAMING_SNAKE per D04. MIG-10 migrates legacy lowercase values.
+
+Must be one of:
+* "VALID"
+* "USED"
+* "CANCELLED"
+
+## <a name="usedAt"></a>9. Property `usedAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) Timestamp when ticket was scanned/used. Set by scan operation.
+
+| Any of(Option)                          |
+| --------------------------------------- |
+| [firestore-timestamp](#usedAt_anyOf_i0) |
+| [item 1](#usedAt_anyOf_i1)              |
+
+### <a name="usedAt_anyOf_i0"></a>9.1. Property `firestore-timestamp`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | No                                |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** Firestore Timestamp serialized representation
+
+| Property                                         | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ------------------------------------------------ | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#usedAt_anyOf_i0__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#usedAt_anyOf_i0__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+#### <a name="usedAt_anyOf_i0__seconds"></a>9.1.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+#### <a name="usedAt_anyOf_i0__nanoseconds"></a>9.1.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="usedAt_anyOf_i1"></a>9.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="usedBy"></a>10. Property `usedBy`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only) FK → User/staff UID who scanned the ticket.
+
+:::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="usedByName"></a>11. Property `usedByName`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only, Denormalized) From User display name at scan time.
+
+:::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="price"></a>12. Property `price`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `number or null` |
+| **Required** | No               |
+
+## <a name="notes"></a>13. Property `notes`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+## <a name="createdAt"></a>14. Property `createdAt`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | Yes                               |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** (Read-only) Server-generated creation timestamp.
+
+| Property                                         | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ------------------------------------------------ | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#usedAt_anyOf_i0__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#usedAt_anyOf_i0__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+### <a name="usedAt_anyOf_i0__seconds"></a>14.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="usedAt_anyOf_i0__nanoseconds"></a>14.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="updatedAt"></a>15. Property `updatedAt`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | Yes                               |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** (Read-only) Server-generated update timestamp.
+
+| Property                                         | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ------------------------------------------------ | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#usedAt_anyOf_i0__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#usedAt_anyOf_i0__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+### <a name="usedAt_anyOf_i0__seconds"></a>15.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="usedAt_anyOf_i0__nanoseconds"></a>15.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="createdBy"></a>16. Property `createdBy`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**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-04-06 at 19:27:48 +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.
+:::
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D27** | Dashboard ticket scanning |
+| **D28** | Firebase Event/Ticket triggers |
+| **D29** | Ticket-to-customer linkage model |
+| **D30** | Ticket tiers/types support timing |
+| **D31** | LegacyTicketMapper deprecation gate |

package/data/docs/triggers/event-ticket-triggers.md

@@ -0,0 +1,204 @@
+---
+title: "Event & Ticket Triggers"
+sidebar_label: "Event & Ticket Triggers"
+sidebar_position: 2
+---
+
+# Event & Ticket Triggers
+
+> **Decision**: D28 (locked, deferred to Wave 4) — Add Firebase Event/Ticket triggers when Dashboard Event support (D26) is built. Not before — Events are Mobile-only today.
+> **Wave**: 4 — Feature Parity.
+> **Status**: Specified. **Do not implement until D26 (Dashboard Events) is in progress.**
+
+These triggers maintain denormalized counters on [`Event`](/models/event) documents and send notifications on ticket lifecycle changes.
+
+---
+
+## `onTicketCreate`
+
+Fires when a new [`Ticket`](/models/ticket) document is created.
+
+**Path**: `companies/{companyId}/events/{eventId}/tickets/{ticketId}`
+**Event**: `onCreate`
+
+### Behavior
+
+1. Atomically increment `Event.ticketsSold` on the parent event document.
+2. Check capacity: if `Event.maxTickets` is set and `ticketsSold >= maxTickets`, update `Event.status` to `COMPLETED` (sold out). This is an optimistic check — a secondary validation should run on ticket creation too.
+3. Send a confirmation notification to the customer (email/WhatsApp) if `Ticket.customerEmail` or `Ticket.customerPhone` is set.
+
+### Inputs
+
+```typescript
+interface TicketCreateEvent {
+  data: Ticket;                     // the new ticket document
+  params: {
+    companyId: string;
+    eventId: string;
+    ticketId: string;
+  };
+}
+```
+
+### Outputs
+
+**Write 1** — Increment counter on parent Event:
+
+```typescript
+// Atomic increment on: companies/{companyId}/events/{eventId}
+{
+  ticketsSold: FieldValue.increment(1),
+  updatedAt: FieldValue.serverTimestamp(),
+}
+```
+
+**Write 2** (conditional) — Mark event as sold out:
+
+```typescript
+// Only if ticketsSold >= maxTickets after increment
+{
+  status: 'COMPLETED',   // EventStatus.COMPLETED = sold out
+  updatedAt: FieldValue.serverTimestamp(),
+}
+```
+
+:::warning Capacity enforcement
+Firestore has no native "max documents" guard. The trigger is the enforcement layer. For high-concurrency events, also add a Firestore Security Rule that rejects ticket writes when `ticketsSold >= maxTickets` using the current document value.
+:::
+
+---
+
+## `onTicketUpdate`
+
+Fires when an existing [`Ticket`](/models/ticket) document is updated.
+
+**Path**: `companies/{companyId}/events/{eventId}/tickets/{ticketId}`
+**Event**: `onUpdate`
+
+### Behavior
+
+Compare `before.status` vs `after.status`:
+
+| Transition | Action |
+|---|---|
+| any → `USED` | Increment `Event.ticketsUsed`. Set `Ticket.usedAt` and `Ticket.usedBy` (if not already set by client). |
+| any → `CANCELLED` | Decrement `Event.ticketsSold`. If event was `COMPLETED` (sold out), revert to `ACTIVE`. |
+| `CANCELLED` → `VALID` | Increment `Event.ticketsSold` (re-activation). |
+| any other | No counter change. |
+
+### Inputs
+
+```typescript
+interface TicketUpdateEvent {
+  data: {
+    before: Ticket;                 // document state before the update
+    after: Ticket;                  // document state after the update
+  };
+  params: {
+    companyId: string;
+    eventId: string;
+    ticketId: string;
+  };
+}
+```
+
+### Outputs (status-dependent)
+
+**On → `USED`**:
+
+```typescript
+// Atomic update on Event
+{ ticketsUsed: FieldValue.increment(1), updatedAt: FieldValue.serverTimestamp() }
+
+// Patch usedAt on Ticket if client didn't set it
+{ usedAt: FieldValue.serverTimestamp() }
+```
+
+**On → `CANCELLED`**:
+
+```typescript
+// Atomic update on Event
+{ ticketsSold: FieldValue.increment(-1), updatedAt: FieldValue.serverTimestamp() }
+
+// Conditional: if event was COMPLETED (sold out), revert to ACTIVE
+{ status: 'ACTIVE', updatedAt: FieldValue.serverTimestamp() }
+```
+
+---
+
+## `onEventUpdate` (metrics)
+
+Fires when an [`Event`](/models/event) document is updated.
+
+**Path**: `companies/{companyId}/events/{eventId}`
+**Event**: `onUpdate`
+
+### Behavior
+
+This trigger handles notification side-effects of event-level status changes.
+
+| Status transition | Action |
+|---|---|
+| any → `CANCELLED` | Notify all ticket holders (customerEmail / customerPhone on each Ticket subcollection). Set `Ticket.status = CANCELLED` for all non-cancelled tickets. |
+| `DRAFT` → `ACTIVE` | Send event launch notification to opted-in customers (if notification list implemented). |
+
+:::info Scope for Wave 4
+The `CANCELLED` → notify-all-ticket-holders path is the critical one to implement. The `DRAFT → ACTIVE` notification is a nice-to-have.
+:::
+
+---
+
+## BookingVersion trigger (`onBookingWrite`)
+
+> **Decision**: D18 (locked) — Firebase owns server-side BookingVersion generation.
+> **Wave**: 3 — Server-Side Logic.
+
+Fires on any write to a [`Booking`](/models/booking) document.
+
+**Path**: `companies/{companyId}/bookings/{bookingId}`
+**Event**: `onWrite` (covers onCreate, onUpdate, onDelete)
+
+### Behavior
+
+1. Determine `changeType`: `CREATE` if `before` is null, `DELETE` if `after` is null, otherwise `UPDATE`.
+2. Compute `fieldsChanged` by diffing `before` and `after` document data (top-level keys for now; dot-notation for known nested objects like `bookingDates`).
+3. Write a new [`BookingVersion`](/models/booking-version) document to the `versions/` subcollection.
+
+### Inputs
+
+```typescript
+interface BookingWriteEvent {
+  data: {
+    before: Booking | null;         // null on CREATE
+    after: Booking | null;          // null on DELETE
+  };
+  params: {
+    companyId: string;
+    bookingId: string;
+  };
+}
+```
+
+### Output — Write 1: new BookingVersion document
+
+```typescript
+// Written to: companies/{companyId}/bookings/{bookingId}/versions/{auto-id}
+{
+  bookingId: params.bookingId,
+  companyId: params.companyId,
+  changeType: 'CREATE' | 'UPDATE' | 'DELETE',
+  changedAt: FieldValue.serverTimestamp(),
+  changedBy: context.auth?.uid ?? null,
+  changedByRole: detectRole(context),   // 'dashboard' | 'mobile' | 'firebase' | 'cli' | 'unknown'
+  fieldsChanged: computeDiff(before, after),   // null for CREATE
+  snapshot: after ?? before,            // full document snapshot
+}
+```
+
+:::note changedByRole detection
+`changedByRole` is inferred from the auth token claims in the write context:
+- `custom_claims.role === 'staff'` → `'dashboard'`
+- `custom_claims.role === 'mobile'` → `'mobile'`
+- No auth (Admin SDK) → `'firebase'` or `'cli'`
+- Otherwise → `'unknown'`
+:::