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

package/data/docs/collections/firestore-paths.md

@@ -6,11 +6,11 @@ sidebar_position: 1
 
 # Firestore Collection Paths
 
-All collections are scoped under a company document.
+All collections are scoped under a company document. Per **D40**, a `sites/{siteId}/` sub-tenant scope sits below `companies/{companyId}/` for site-specific collections (ING-304). **D41** canonicalizes the Site document; **D42** adds the analytics rollup collections; **D43** adds optional `Order.siteId` for site attribution (per ADR-003).
 
 ```
 companies/{companyId}/
-├── orders/{orderId}
+├── orders/{orderId}                     ← Order.siteId? (D43 / ADR-003) attributes to a site
 ├── customers/{customerId}
 ├── bookings/{bookingId}
 │   └── sessions/{sessionId}
@@ -21,16 +21,69 @@ companies/{companyId}/
 ├── customerPayments/{paymentId}
 ├── paymentSummaries/{period}
 ├── loyaltyTransactions/{transactionId}
-└── loyaltyConfig (singleton document)
+├── loyaltyConfig (singleton document)
+└── sites/{siteId}                        ← D41 Site document (D40 sub-tenant root)
+    ├── magic_link_requests/{requestId}   ← 16-byte hex; auth audit log
+    ├── allowed_users/{contactId}         ← access allowlist; doc ID = email / E.164 phone (URL-escaped)
+    ├── payments/{paymentId}              ← SitePayment — immutable transaction ledger
+    ├── analytics_events/{eventId}        ← append-only product/behavior event stream
+    ├── analytics_daily/{YYYY-MM-DD}      ← D42 — idempotent daily rollup
+    ├── analytics_hourly/{YYYY-MM-DD-HH}  ← D42 — hourly rollup (scheduled CF)
+    └── analytics_backfills/{runId}       ← D42 — admin-triggered backfill run tracker
 ```
 
 ## Path conventions
 
 - All paths are **tenant-scoped** under `companies/{companyId}/`
+- Site-specific collections live under `companies/{companyId}/sites/{siteId}/` (D40)
 - Sub-collections (sessions, tickets) are nested under their parent
 - `loyaltyConfig` is a singleton document, not a collection
 - Document IDs are auto-generated Firestore IDs unless specified
 
+## D40 — Site sub-tenant scope
+
+Introduced for ING-304 (canonical Firestore models derived from the SR Single site reference). The site-scoped collections share one rationale: they belong to a *site* (a per-company product surface), not to the company as a whole. A company may host many sites.
+
+| Collection | Purpose | Write pattern |
+|---|---|---|
+| `magic_link_requests` | Authentication audit log — every access request | Two-stage PATCH (request → verify) |
+| `allowed_users` | Authoritative paid-access allowlist; referral-code resolution table | Upsert by contact ID |
+| `payments` | Immutable SitePayment ledger (distinct from `customerPayments`) | Append-only; dual-write (redirect + webhook) |
+| `analytics_events` | Product/behavior event stream (page views, funnel, forms, orders, identity, errors) | Append-only, immutable |
+
+Related follow-ups: [ING-340](https://linear.app/ingenx/issue/ING-340) (retention/TTL), [ING-341](https://linear.app/ingenx/issue/ING-341) (PII redaction convention).
+
+## D41 — Site document
+
+The Site document at `companies/{companyId}/sites/{siteId}` is the root of the site sub-tenant scope. It holds:
+
+- `name`, `description`, `status` (`SiteStatus`: ACTIVE / INACTIVE / EXPIRED / ARCHIVED)
+- `deploymentLinks[]` — ordered list of deployment URLs by `DeploymentLinkType` (web, mobile, pwa, app-store, play-store, other)
+- `expiresAt?` and derived `isExpired?`
+- `analyticsEnabled` feature flag; `lastAnalyticsSync` sentinel
+- `cachedMetrics?` — denormalized `SiteMetricsSummary` snapshot (authoritative counts live in `analytics_daily` / `analytics_hourly`)
+- Standard audit fields: `createdAt`, `updatedAt`, `createdBy`
+
+## D42 — Analytics rollups
+
+Per GH ticket IngenX-IO/valets-dashboard#199, rollups are written by a scheduled Cloud Function (Option B — hourly writer, idempotent set/merge). Admin-triggered backfills use an `onCall` function that records progress in `analytics_backfills/{runId}`.
+
+| Collection | Doc ID | Writer | Notes |
+|---|---|---|---|
+| `analytics_daily` | `YYYY-MM-DD` (UTC) | Scheduled CF + backfill | `computeRollup(companyId, siteId, date)` — idempotent set/merge; reruns overwrite |
+| `analytics_hourly` | `YYYY-MM-DD-HH` (UTC) | Scheduled CF (hourly) | Same writer, scoped to a single hour bucket |
+| `analytics_backfills` | auto | Admin `onCall` | Tracks `status`, `from`/`to`, `processedDates`, `errors`, `dryRun`, audit fields |
+
+Readers should fall back to the raw `analytics_events` collection for slices not yet covered by a rollup.
+
+## D43 — `Order.siteId` attribution (ADR-003)
+
+Orders live at the existing company-scoped path `companies/{companyId}/orders/{orderId}`. D43 adds an **optional** `siteId?: string` field — when set, the order is attributed to a specific site (enables site-scoped dashboards, analytics joins, and per-site revenue slices). When null or absent, the order is company-wide (legacy behavior).
+
+- **No migration.** Existing orders keep `siteId = null`.
+- **Composite index:** `(companyId, siteId, createdAt)` for per-site recency queries.
+- **Physical relocation** of Order under `sites/{siteId}/orders/` is explicitly deferred (ADR-004, not approved).
+
 ## Security rules pattern
 
 ```

package/data/docs/enums/attention-status.md

@@ -0,0 +1,24 @@
+---
+title: "AttentionStatus"
+sidebar_label: "AttentionStatus"
+sidebar_position: 1
+---
+
+# AttentionStatus
+
+|                |                                |
+| -------------- | ------------------------------ |
+| **Type**       | `enum (of string)`             |
+| **Required**   | No                             |
+| **Defined in** | #/definitions/attention-status |
+
+**Description:** Operational attention status for Order and Booking (D39). Controls home-page queue assignment. Server-owned — set via triggers or callable fn only.
+
+Must be one of:
+* "ACTIVE"
+* "STALE"
+* "ON_HOLD"
+* "ESCALATED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:54 +0000

package/data/docs/enums/booking-status.md

@@ -1,7 +1,7 @@
 ---
 title: "BookingStatus"
 sidebar_label: "BookingStatus"
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 # BookingStatus
@@ -23,4 +23,4 @@ Must be one of:
 * "COMPLETED_MIXED"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:54 +0000

package/data/docs/enums/customer-payment-status.md

@@ -1,7 +1,7 @@
 ---
 title: "CustomerPaymentStatus"
 sidebar_label: "CustomerPaymentStatus"
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # CustomerPaymentStatus
@@ -23,4 +23,4 @@ Must be one of:
 * "CANCELLED"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000

package/data/docs/enums/customer-payment-target-type.md

@@ -1,7 +1,7 @@
 ---
 title: "CustomerPaymentTargetType"
 sidebar_label: "CustomerPaymentTargetType"
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # CustomerPaymentTargetType
@@ -20,4 +20,4 @@ Must be one of:
 * "PURCHASE"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000

package/data/docs/enums/delivery-type.md

@@ -1,7 +1,7 @@
 ---
 title: "DeliveryType"
 sidebar_label: "DeliveryType"
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # DeliveryType
@@ -20,4 +20,4 @@ Must be one of:
 * "DELIVERY"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000

package/data/docs/enums/deployment-link-type.md

@@ -0,0 +1,26 @@
+---
+title: "DeploymentLinkType"
+sidebar_label: "DeploymentLinkType"
+sidebar_position: 6
+---
+
+# DeploymentLinkType
+
+|                |                                    |
+| -------------- | ---------------------------------- |
+| **Type**       | `enum (of string)`                 |
+| **Required**   | No                                 |
+| **Defined in** | #/definitions/deployment-link-type |
+
+**Description:** Category of a Site deployment link (D41). Used for UI icon/labelling and deep-link handling.
+
+Must be one of:
+* "web"
+* "mobile"
+* "pwa"
+* "app-store"
+* "play-store"
+* "other"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000

package/data/docs/enums/event-status.md

@@ -1,7 +1,7 @@
 ---
 title: "EventStatus"
 sidebar_label: "EventStatus"
-sidebar_position: 5
+sidebar_position: 7
 ---
 
 # EventStatus
@@ -21,7 +21,7 @@ Must be one of:
 * "COMPLETED"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000
 
 ## Related Decisions
 

package/data/docs/enums/fulfillment-status.md

@@ -1,7 +1,7 @@
 ---
 title: "FulfillmentStatus"
 sidebar_label: "FulfillmentStatus"
-sidebar_position: 6
+sidebar_position: 8
 ---
 
 # FulfillmentStatus
@@ -23,7 +23,7 @@ Must be one of:
 * "PICKED_UP"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000
 
 ## Related Decisions
 

package/data/docs/enums/loyalty-transaction-type.md

@@ -1,7 +1,7 @@
 ---
 title: "LoyaltyTransactionType"
 sidebar_label: "LoyaltyTransactionType"
-sidebar_position: 7
+sidebar_position: 9
 ---
 
 # LoyaltyTransactionType
@@ -23,7 +23,7 @@ Must be one of:
 * "REFUND"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000
 
 ## Related Decisions
 

package/data/docs/enums/order-status.md

@@ -1,7 +1,7 @@
 ---
 title: "OrderStatus"
 sidebar_label: "OrderStatus"
-sidebar_position: 8
+sidebar_position: 10
 ---
 
 # OrderStatus
@@ -24,7 +24,7 @@ Must be one of:
 * "EXPIRED"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000
 
 ## Related Decisions
 

package/data/docs/enums/payment-method.md

@@ -1,7 +1,7 @@
 ---
 title: "PaymentMethod"
 sidebar_label: "PaymentMethod"
-sidebar_position: 9
+sidebar_position: 11
 ---
 
 # PaymentMethod
@@ -27,7 +27,7 @@ Must be one of:
 * "OTHER"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000
 
 ## Related Decisions
 

package/data/docs/enums/payment-proof-status.md

@@ -1,7 +1,7 @@
 ---
 title: "PaymentProofStatus"
 sidebar_label: "PaymentProofStatus"
-sidebar_position: 10
+sidebar_position: 12
 ---
 
 # PaymentProofStatus
@@ -20,4 +20,4 @@ Must be one of:
 * "REJECTED"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000

package/data/docs/enums/payment-status.md

@@ -1,7 +1,7 @@
 ---
 title: "PaymentStatus"
 sidebar_label: "PaymentStatus"
-sidebar_position: 11
+sidebar_position: 13
 ---
 
 # PaymentStatus
@@ -24,7 +24,7 @@ Must be one of:
 * "PARTIALLY_REFUNDED"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000
 
 ## Related Decisions
 

package/data/docs/enums/pending-issue.md

@@ -0,0 +1,31 @@
+---
+title: "PendingIssue"
+sidebar_label: "PendingIssue"
+sidebar_position: 14
+---
+
+# PendingIssue
+
+|                |                             |
+| -------------- | --------------------------- |
+| **Type**       | `enum (of string)`          |
+| **Required**   | No                          |
+| **Defined in** | #/definitions/pending-issue |
+
+**Description:** Specific detected conditions on an Order or Booking requiring human action (D39). Stored as an array — multiple issues can be active simultaneously. Server-owned.
+
+Must be one of:
+* "PAYMENT_PROOF_PENDING"
+* "PAYMENT_PROOF_REJECTED"
+* "AMOUNT_DISCREPANCY"
+* "RETURN_UNRESOLVED"
+* "OVERDUE_DELIVERY"
+* "SESSION_OVERDUE"
+* "PAYMENT_INCOMPLETE"
+* "CANCELLATION_REQUESTED"
+* "UNREFUNDED_CANCELLATION"
+* "UPCOMING_UNPAID"
+* "NO_SHOW_UNRESOLVED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000

package/data/docs/enums/return-status.md

@@ -1,7 +1,7 @@
 ---
 title: "ReturnStatus"
 sidebar_label: "ReturnStatus"
-sidebar_position: 12
+sidebar_position: 15
 ---
 
 # ReturnStatus
@@ -23,7 +23,7 @@ Must be one of:
 * "EXCHANGE_COMPLETED"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000
 
 ## Related Decisions
 

package/data/docs/enums/session-status.md

@@ -1,7 +1,7 @@
 ---
 title: "SessionStatus"
 sidebar_label: "SessionStatus"
-sidebar_position: 13
+sidebar_position: 16
 ---
 
 # SessionStatus
@@ -23,7 +23,7 @@ Must be one of:
 * "CANCELLED"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000
 
 ## Related Decisions
 

package/data/docs/enums/site-status.md

@@ -0,0 +1,24 @@
+---
+title: "SiteStatus"
+sidebar_label: "SiteStatus"
+sidebar_position: 17
+---
+
+# SiteStatus
+
+|                |                           |
+| -------------- | ------------------------- |
+| **Type**       | `enum (of string)`        |
+| **Required**   | No                        |
+| **Defined in** | #/definitions/site-status |
+
+**Description:** Lifecycle status for a Site (D41). Drives whether the site is reachable and whether analytics/payments flow.
+
+Must be one of:
+* "ACTIVE"
+* "INACTIVE"
+* "EXPIRED"
+* "ARCHIVED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000

package/data/docs/enums/ticket-status.md

@@ -1,7 +1,7 @@
 ---
 title: "TicketStatus"
 sidebar_label: "TicketStatus"
-sidebar_position: 14
+sidebar_position: 18
 ---
 
 # TicketStatus
@@ -20,7 +20,7 @@ Must be one of:
 * "CANCELLED"
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-06 at 19:27:48 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 22:24:55 +0000
 
 ## Related Decisions
 

package/data/docs/index.md

@@ -19,16 +19,18 @@ Developers own the Zod source in `packages/schema/src/`. When schemas change, th
 
 ## What's documented
 
-### Enums (14)
+### Enums (18)
 
 Status enums that drive business logic across Order, Booking, Event, and Loyalty domains:
 
 | Enum | Values | Description |
 |------|--------|-------------|
+| [AttentionStatus](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. |
 | [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. |
+| [DeploymentLinkType](enums/deployment-link-type) | 6 values | Category of a Site deployment link (D41). Used for UI icon/labelling and deep-link handling. |
 | [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. |
@@ -36,17 +38,24 @@ Status enums that drive business logic across Order, Booking, Event, and Loyalty
 | [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. |
+| [PendingIssue](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. |
 | [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. |
+| [SiteStatus](enums/site-status) | 4 values | Lifecycle status for a Site (D41). Drives whether the site is reachable and whether analytics/payments flow. |
 | [TicketStatus](enums/ticket-status) | 3 values | Event ticket status (D32). VALID = active and unused. |
 
 
-### Models (17)
+### Models (25)
 
 Core Firestore document schemas:
 
 | Model | Fields | Required | Description |
 |-------|--------|----------|-------------|
+| [AllowedUser](models/allowed-user) | 9 | 8 | — |
+| [AnalyticsBackfill](models/analytics-backfill) | 12 | 10 | — |
+| [AnalyticsDaily](models/analytics-daily) | 16 | 14 | — |
+| [AnalyticsEvent](models/analytics-event) | 12 | 10 | — |
+| [AnalyticsHourly](models/analytics-hourly) | 17 | 15 | — |
 | [Booking](models/booking) | 52 | 7 | — |
 | [BookingVersion](models/booking-version) | 9 | 6 | — |
 | [Customer](models/customer) | 17 | 4 | — |
@@ -57,12 +66,15 @@ Core Firestore document schemas:
 | [LoyaltyReward](models/loyalty-reward) | 11 | 5 | — |
 | [LoyaltyStatus](models/loyalty-status) | 9 | 2 | — |
 | [LoyaltyTransaction](models/loyalty-transaction) | 16 | 4 | — |
+| [MagicLinkRequest](models/magic-link-request) | 15 | 11 | — |
 | [MetricsCurrent](models/metrics-current) | 25 | 25 | — |
 | [MetricsDaily](models/metrics-daily) | 26 | 26 | — |
 | [MetricsMonthly](models/metrics-monthly) | 26 | 26 | — |
-| [Order](models/order) | 47 | 8 | — |
+| [Order](models/order) | 48 | 8 | — |
 | [OrderItem](models/order-item) | 12 | 3 | — |
 | [Sale](models/sale) | 12 | 1 | — |
+| [Site](models/site) | 14 | 6 | — |
+| [SitePayment](models/site-payment) | 10 | 9 | — |
 | [Ticket](models/ticket) | 16 | 6 | — |