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

package/data/static/llms.txt

@@ -4,12 +4,16 @@
 > Source of truth: Zod schemas in packages/schema/src/
 > All Firestore documents are scoped under companies/{companyId}/
 
-> Generated: 2026-04-06
+> Generated: 2026-04-18
 
 ---
 
 ## Enums
 
+### AttentionStatus
+Operational attention status for Order and Booking (D39). Controls home-page queue assignment. Server-owned — set via triggers or callable fn only.
+Values: ACTIVE, STALE, ON_HOLD, ESCALATED
+
 ### BookingStatus
 Booking lifecycle status. COMPLETED_MIXED = some sessions completed, others cancelled/no-show.
 Values: PENDING, CONFIRMED, COMPLETED, CANCELLED, CANCELLATION_REQUESTED, COMPLETED_MIXED
@@ -26,6 +30,10 @@ Values: BOOKING, ORDER, PURCHASE
 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.
 Values: ON_SITE, PICK_UP, DELIVERY
 
+### DeploymentLinkType
+Category of a Site deployment link (D41). Used for UI icon/labelling and deep-link handling.
+Values: web, mobile, pwa, app-store, play-store, other
+
 ### EventStatus
 Ticketed event lifecycle (D32). Mobile-only today; Dashboard in Wave 4.
 Values: DRAFT, ACTIVE, CANCELLED, COMPLETED
@@ -54,6 +62,10 @@ Values: PENDING, APPROVED, REJECTED
 Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking.
 Values: PENDING, PAID, PARTIALLY_PAID, FAILED, REFUND_PROCESSING, REFUNDED, PARTIALLY_REFUNDED
 
+### PendingIssue
+Specific detected conditions on an Order or Booking requiring human action (D39). Stored as an array — multiple issues can be active simultaneously. Server-owned.
+Values: 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
+
 ### ReturnStatus
 Post-sale return/exchange lifecycle (D34). Optional — null until return or exchange initiated.
 Values: RETURN_REQUESTED, RETURN_PROCESSING, RETURNED, EXCHANGE_REQUESTED, EXCHANGE_PROCESSING, EXCHANGE_COMPLETED
@@ -62,6 +74,10 @@ Values: RETURN_REQUESTED, RETURN_PROCESSING, RETURNED, EXCHANGE_REQUESTED, EXCHA
 Per-date/per-slot booking session status (D19). Dashboard is sole writer; Mobile is read-only.
 Values: PENDING, CONFIRMED, CANCELLATION_REQUESTED, COMPLETED, NO_SHOW, CANCELLED
 
+### SiteStatus
+Lifecycle status for a Site (D41). Drives whether the site is reachable and whether analytics/payments flow.
+Values: ACTIVE, INACTIVE, EXPIRED, ARCHIVED
+
 ### TicketStatus
 Event ticket status (D32). VALID = active and unused.
 Values: VALID, USED, CANCELLED
@@ -70,6 +86,224 @@ Values: VALID, USED, CANCELLED
 
 ## Models
 
+### AllowedUser
+Fields: 9 (8 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID = contact identifier (email or E.164 phone), URL-escaped. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| siteId | string | yes | (Immutable) FK → Site document ID (D40 sub-tenant scope). |
+| contact | string | yes | Email or E.164 phone number. Canonical identifier for this user within the site. |
+| tier | string | yes | Access tier. Free string per site (ING-304 open question — tier values are site-specific today). |
+| amount | number | yes | Amount paid. Generalized from amount_xof per D40 decision. |
+| currency | string | yes | Currency code (ISO 4217). Defaults to XOF for legacy SR-Single parity. |
+| transactionId | string | yes | Payment provider transaction ID (e.g. Wave). |
+| paidAt | FirestoreTimestamp | yes | RFC3339Nano UTC when payment was completed. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "siteId": "sit_ref123",
+  "contact": "contact",
+  "tier": "Gold",
+  "amount": 45000,
+  "currency": "XOF",
+  "transactionId": "tra_ref123",
+  "paidAt": "pai_ref123"
+}
+```
+
+### AnalyticsBackfill
+Fields: 12 (10 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| siteId | string | yes | (Immutable) FK → Site document ID (D40). |
+| status | enum(5) | yes | Run status. |
+| from | string | yes | (Immutable) Inclusive start date (`YYYY-MM-DD`, UTC). |
+| to | string | yes | (Immutable) Inclusive end date (`YYYY-MM-DD`, UTC). |
+| dryRun | boolean | yes | (Immutable) When true, rollup writes are skipped — only source counts are returned for diffing. |
+| processedDates | array<string> | yes | Ordered list of `YYYY-MM-DD` dates already processed by this run. |
+| errors | array<object> | yes | Per-date errors collected during the run. |
+| errors[].date | string | yes | `YYYY-MM-DD` date that failed. |
+| errors[].message | string | yes | Error message captured at failure. |
+| errors[].at | FirestoreTimestamp | yes | When the error occurred. |
+| triggeredBy | string | yes | (Immutable) UID of the admin who triggered the backfill. |
+| startedAt | FirestoreTimestamp | yes | (Read-only) When the run actually started. |
+| completedAt | any | no | (Read-only) When the run reached a terminal status. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "siteId": "sit_ref123",
+  "status": "pending",
+  "from": "from",
+  "to": "to",
+  "dryRun": true,
+  "processedDates": [
+    "example"
+  ],
+  "errors": [
+    {
+      "date": "2026-02-15",
+      "message": "message",
+      "at": "at"
+    }
+  ],
+  "triggeredBy": "triggeredBy",
+  "startedAt": "startedAt",
+  "completedAt": "completedAt"
+}
+```
+
+### AnalyticsDaily
+Fields: 16 (14 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| totalEvents | integer | yes | Total event count within the bucket. |
+| pageViews | integer | yes | Count of `page_view` + `screen_view` events. |
+| sessions | integer | yes | Distinct session count within the bucket (by `sessionId`). |
+| uniqueUsers | integer | yes | Distinct identified `userId` count. Anonymous sessions (userId=null) are excluded. |
+| anonymousSessions | integer | yes | Distinct session count where `userId` was null for the entire session. |
+| orders | integer | yes | Count of `order_submitted` events (or Order documents scoped to this site, D43) within the bucket. |
+| paymentsCompleted | integer | yes | Count of `payment_completed` events within the bucket. |
+| paymentsFailed | integer | yes | Count of `payment_failed` events within the bucket. |
+| errors | integer | yes | Count of `error_occurred` + `exception_caught` events within the bucket. |
+| eventCounts | record<string,integer> | yes | Per-event-name counts — key is the event name (canonical or custom), value is the count within the bucket. |
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID = `YYYY-MM-DD`. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| siteId | string | yes | (Immutable) FK → Site document ID (D40). |
+| date | string | yes | (Immutable) `YYYY-MM-DD` UTC — matches document ID. |
+| computedAt | FirestoreTimestamp | yes | (Read-only) When this rollup was last (re)computed. Updated on every set/merge. |
+| sourceEventCount | ['integer', 'null'] | no | (Read-only, Optional) Total source events scanned when producing this rollup. Useful for dry-run diffing. |
+
+Example:
+```json
+{
+  "totalEvents": 0,
+  "pageViews": 0,
+  "sessions": 0,
+  "uniqueUsers": 0,
+  "anonymousSessions": 0,
+  "orders": 0,
+  "paymentsCompleted": 0,
+  "paymentsFailed": 0,
+  "errors": 0,
+  "eventCounts": {},
+  "id": null,
+  "companyId": "comp_xyz789",
+  "siteId": "sit_ref123",
+  "date": "2026-02-15",
+  "computedAt": "computedAt",
+  "sourceEventCount": null
+}
+```
+
+### AnalyticsEvent
+Fields: 12 (10 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID. Equal to eventId. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| siteId | string | yes | (Immutable) FK → Site document ID (D40 sub-tenant scope). |
+| eventId | string | yes | (Immutable) Client-generated UUID. Matches document ID. |
+| eventName | string | yes | Event name. Free string; canonical vocabulary is encouraged (see CANONICAL_ANALYTICS_EVENT_NAMES). |
+| timestamp | string | yes | Client-side ISO 8601 — "when it happened on device". Can diverge from serverTimestamp for queued offline events. |
+| serverTimestamp | FirestoreTimestamp | yes | (Read-only) Firestore serverTimestamp() — authoritative for ordering. |
+| sessionId | string | yes | 30-minute rolling session identifier. |
+| userId | any | yes | Stable user ID if identified; explicitly null (not omitted) for anonymous sessions — simplifies querying. |
+| properties | object | yes | Free-form event-specific payload. Contract is at the event-name level. PII posture: follow-up issue pending. |
+| context | object | yes | Environment context at event time (nested per D40). |
+| context.url | string | no | Full URL at event time. |
+| context.origin | string | no | Protocol + host. |
+| context.hostname | string | no | Hostname only — useful for deployment identification. |
+| context.page | string | no | Current route/pathname. |
+| context.title | string | no | Page title. |
+| context.referrer | string | no | Referrer URL. |
+| context.deviceType | enum(3) | no |  |
+| context.platform | string | no | OS/platform string. |
+| context.screenWidth | integer | no | Viewport width (flattened from screen.width). |
+| context.screenHeight | integer | no | Viewport height (flattened from screen.height). |
+| context.appVersion | string | no | Consuming app version. |
+| context.online | boolean | no | Connectivity state at event time. |
+| context.locale | string | no | User locale. |
+| context.timezone | string | no | IANA timezone. |
+| context.utm | any | no | UTM parameters; null when not a campaign-landed session. |
+| userTraits | ['object', 'null'] | no | Optional — included only when includeUserTraits: true on the write. PII posture: follow-up issue pending. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "siteId": "sit_ref123",
+  "eventId": "eve_ref123",
+  "eventName": "eventName",
+  "timestamp": "timestamp",
+  "serverTimestamp": "serverTimestamp",
+  "sessionId": "ses_ref123",
+  "userId": "use_ref123",
+  "properties": {},
+  "context": {},
+  "userTraits": null
+}
+```
+
+### AnalyticsHourly
+Fields: 17 (15 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| totalEvents | integer | yes | Total event count within the bucket. |
+| pageViews | integer | yes | Count of `page_view` + `screen_view` events. |
+| sessions | integer | yes | Distinct session count within the bucket (by `sessionId`). |
+| uniqueUsers | integer | yes | Distinct identified `userId` count. Anonymous sessions (userId=null) are excluded. |
+| anonymousSessions | integer | yes | Distinct session count where `userId` was null for the entire session. |
+| orders | integer | yes | Count of `order_submitted` events (or Order documents scoped to this site, D43) within the bucket. |
+| paymentsCompleted | integer | yes | Count of `payment_completed` events within the bucket. |
+| paymentsFailed | integer | yes | Count of `payment_failed` events within the bucket. |
+| errors | integer | yes | Count of `error_occurred` + `exception_caught` events within the bucket. |
+| eventCounts | record<string,integer> | yes | Per-event-name counts — key is the event name (canonical or custom), value is the count within the bucket. |
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID = `YYYY-MM-DD-HH`. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| siteId | string | yes | (Immutable) FK → Site document ID (D40). |
+| date | string | yes | (Immutable) `YYYY-MM-DD` UTC for the bucket day. |
+| hour | integer | yes | (Immutable) UTC hour of day, 0–23. |
+| computedAt | FirestoreTimestamp | yes | (Read-only) When this rollup was last (re)computed. |
+| sourceEventCount | ['integer', 'null'] | no | (Read-only, Optional) Total source events scanned when producing this rollup. |
+
+Example:
+```json
+{
+  "totalEvents": 0,
+  "pageViews": 0,
+  "sessions": 0,
+  "uniqueUsers": 0,
+  "anonymousSessions": 0,
+  "orders": 0,
+  "paymentsCompleted": 0,
+  "paymentsFailed": 0,
+  "errors": 0,
+  "eventCounts": {},
+  "id": null,
+  "companyId": "comp_xyz789",
+  "siteId": "sit_ref123",
+  "date": "2026-02-15",
+  "hour": 0,
+  "computedAt": "computedAt",
+  "sourceEventCount": null
+}
+```
+
 ### Booking
 Fields: 52 (7 required)
 
@@ -586,6 +820,48 @@ Example:
 }
 ```
 
+### MagicLinkRequest
+Fields: 15 (11 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID. 16-byte random hex. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| siteId | string | yes | (Immutable) FK → Site document ID (D40 sub-tenant scope). |
+| email | string | yes | Populated if identifier is email; empty string if phone. Mutually exclusive with phone per document. |
+| phone | string | yes | Populated if identifier is E.164 format (starts with +); empty string if email. |
+| ip | string | yes | Client IP from X-Forwarded-For or RemoteAddr. |
+| allowed | boolean | yes | Whether the user passed the access control check. |
+| link | string | yes | Magic-link URL — non-empty only when DEV_MODE=true; empty in production (audit integrity). |
+| tier | string | yes | Access tier selected by the user. Free string per site (ING-304 open question — tier values are site-specific today). |
+| authStatusReason | string | yes | Outcome reason code: whitelist | allowed_users | payment_redirect | payment_complete | not_allowed | redirected_to_payment. |
+| referredBy | string | yes | Contact identifier of the referrer, resolved from submitted referral_code; empty if none. |
+| requestedAt | FirestoreTimestamp | yes | RFC3339Nano UTC at request time. |
+| verifyReason | ['string', 'null'] | no | Verify outcome reason: mirrors authStatusReason on success, or link_expired | link_invalid | not_allowed. |
+| verified | ['boolean', 'null'] | no | Whether the verify attempt succeeded. |
+| verifiedAt | any | no | RFC3339Nano UTC at verify time. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "siteId": "sit_ref123",
+  "email": "amadou@example.com",
+  "phone": "+225 07 00 11 22",
+  "ip": "ip",
+  "allowed": true,
+  "link": "link",
+  "tier": "Gold",
+  "authStatusReason": "Customer request",
+  "referredBy": "referredBy",
+  "requestedAt": "requestedAt",
+  "verifyReason": null,
+  "verified": null,
+  "verifiedAt": "verifiedAt"
+}
+```
+
 ### MetricsCurrent
 Fields: 25 (25 required)
 
@@ -777,13 +1053,14 @@ Example:
 ```
 
 ### Order
-Fields: 47 (8 required)
+Fields: 48 (8 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | id | string | yes | (Read-only) Firestore document ID. Note: some models also have uid; see ID conventions. |
 | uid | string | yes | (Read-only) Entity UID. Often mirrors id. |
 | companyId | string | yes | (Immutable) FK → Company document ID. Scopes all queries. |
+| siteId | ['string', 'null'] | no | (Immutable, Optional) FK → Site document ID (D43 / ADR-003). null = company-wide. |
 | orderNumber | string | yes | (Read-only) Server-generated order number. |
 | status | OrderStatus | yes | Core lifecycle status (D34, MIG-11). See OrderStatus enum for the legacy value migration mapping. |
 | paymentStatus | any | no | Payment lifecycle (D34). Null until payment is initiated. |
@@ -835,6 +1112,7 @@ Example:
   "id": "bk_abc123def456",
   "uid": "user_u8x92kqm",
   "companyId": "comp_xyz789",
+  "siteId": null,
   "orderNumber": "ORD-2026-0042",
   "status": "status",
   "paymentStatus": "paymentStatus",
@@ -954,6 +1232,88 @@ Example:
 }
 ```
 
+### Site
+Fields: 14 (6 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. Scopes all site sub-collections. |
+| name | string | yes | Human-readable site name shown in dashboards. |
+| description | ['string', 'null'] | no | Optional freeform description. |
+| status | SiteStatus | yes | Lifecycle status (D41). Clients filter by ACTIVE. |
+| deploymentLinks | array<object> | yes | Ordered list of deployment URLs (web, mobile, PWA, store links). |
+| deploymentLinks[].label | string | yes | Human-readable label shown in dashboards (e.g. "Production", "Staging"). |
+| deploymentLinks[].url | string | yes | Absolute URL or store link. |
+| deploymentLinks[].type | DeploymentLinkType | yes | Link category — drives icon/handler selection. |
+| deploymentLinks[].isPrimary | boolean | no | If true, this link is used as the canonical deployment URL for the Site. |
+| expiresAt | any | no | Optional expiration timestamp. When set and elapsed, `isExpired` flips true and status typically moves to EXPIRED. |
+| isExpired | ['boolean', 'null'] | no | (Read-only) Derived — true when `expiresAt` is in the past. Maintained by server trigger. |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+| createdBy | string | yes | (Immutable) FK → User/staff UID who created the site. |
+| analyticsEnabled | boolean | yes | Feature flag — when false, clients should not emit analytics events for this site. |
+| lastAnalyticsSync | any | no | (Read-only) Last time the analytics rollup pipeline refreshed `cachedMetrics`. |
+| cachedMetrics | ['object', 'null'] | no | (Read-only, Denormalized) Cached metrics snapshot for quick dashboard rendering. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "name": "Amadou Diallo",
+  "description": null,
+  "status": "status",
+  "deploymentLinks": [
+    {
+      "label": "label",
+      "url": "https://storage.example.com/url.jpg",
+      "type": "phone"
+    }
+  ],
+  "expiresAt": "expiresAt",
+  "isExpired": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt",
+  "createdBy": "staff_k0f1",
+  "analyticsEnabled": true,
+  "lastAnalyticsSync": "lastAnalyticsSync",
+  "cachedMetrics": null
+}
+```
+
+### SitePayment
+Fields: 10 (9 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| siteId | string | yes | (Immutable) FK → Site document ID (D40 sub-tenant scope). |
+| contact | string | yes | Email or E.164 phone number. Matches AllowedUser.contact. |
+| sessionId | string | yes | Payment provider checkout session ID (e.g. Wave). Usable for dedup across dual writes. |
+| transactionId | string | yes | Payment provider transaction ID. |
+| tier | string | yes | Access tier. Free string per site (ING-304 open question). |
+| amount | number | yes | Amount paid. Generalized from amount_xof per D40 decision. |
+| currency | string | yes | Currency code (ISO 4217). Defaults to XOF for legacy SR-Single parity. |
+| paidAt | FirestoreTimestamp | yes | RFC3339Nano UTC when payment was completed. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "siteId": "sit_ref123",
+  "contact": "contact",
+  "sessionId": "ses_ref123",
+  "transactionId": "tra_ref123",
+  "tier": "Gold",
+  "amount": 45000,
+  "currency": "XOF",
+  "paidAt": "pai_ref123"
+}
+```
+
 ### Ticket
 Fields: 16 (6 required)