@ingenx-io/valets-schema-mcp-server 0.1.4 → 0.1.6

package/data/static/llms.txt

@@ -4,7 +4,7 @@
 > Source of truth: Zod schemas in packages/schema/src/
 > All Firestore documents are scoped under companies/{companyId}/
 
-> Generated: 2026-04-18
+> Generated: 2026-05-05
 
 ---
 
@@ -30,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
@@ -70,6 +74,22 @@ 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
+
+### StocktakeFrequency
+Recurrence cadence of a Stocktake session (GH#29 §4).
+Values: DAILY, WEEKLY, MONTHLY, AD_HOC
+
+### StocktakeItemStatus
+Per-line workflow status inside a Stocktake (GH#29 §4, audit Q21).
+Values: PENDING, COUNTED, VERIFIED, ADJUSTED
+
+### StocktakeStatus
+Lifecycle status of a Stocktake session (GH#29 §3, §4).
+Values: PENDING, IN_PROGRESS, COMPLETED, CANCELLED
+
 ### TicketStatus
 Event ticket status (D32). VALID = active and unused.
 Values: VALID, USED, CANCELLED
@@ -108,6 +128,97 @@ Example:
 }
 ```
 
+### 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)
 
@@ -159,6 +270,52 @@ Example:
 }
 ```
 
+### 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)
 
@@ -908,13 +1065,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. |
@@ -966,6 +1124,7 @@ Example:
   "id": "bk_abc123def456",
   "uid": "user_u8x92kqm",
   "companyId": "comp_xyz789",
+  "siteId": null,
   "orderNumber": "ORD-2026-0042",
   "status": "status",
   "paymentStatus": "paymentStatus",
@@ -1085,6 +1244,56 @@ 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)
 
@@ -1117,6 +1326,104 @@ Example:
 }
 ```
 
+### Stocktake
+Fields: 21 (11 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. Tenant scope. |
+| stocktakeNumber | string | yes | Human-readable session number, e.g. "STK-2026-001". Embedded as `referenceNumber` on the StockMovement rows the session emits, so the ledger remains traceable to the originating stocktake. |
+| stocktakeDate | FirestoreTimestamp | yes | Effective date of the count. Distinct from createdAt; can be backdated. |
+| warehouseId | any | no | FK → Warehouse document ID. Null = whole-company stocktake (no warehouse partition). |
+| frequency | any | no | Recurrence cadence. Optional — leave unset for ad-hoc sessions, or set to indicate this stocktake is part of a recurring schedule. |
+| scheduledStocktakeId | any | no | FK to a recurring stocktake schedule, if this session was emitted from one. Null for ad-hoc sessions. |
+| status | StocktakeStatus | yes | Lifecycle status. Transitions PENDING → IN_PROGRESS → COMPLETED are server-owned (GH#29 §3 / Q25). |
+| adjustmentsApplied | boolean | yes | True if completing the session actually emitted StockMovement adjustments. False for record-only counts. |
+| notes | any | no | Free-text session-level notes. |
+| totalItemsCount | integer | yes | (Read-only) Total number of StocktakeItem rows under this session. |
+| totalDiscrepancies | integer | yes | (Read-only) Sum of absolute deltas across counted items. |
+| totalDeltaValue | number | yes | (Read-only) Net valuation impact of the count, in XOF integer minor units. |
+| startedAt | FirestoreTimestamp | yes | When the counting session physically opened. Typically equal to createdAt for ad-hoc sessions. |
+| completedAt | any | no | (Read-only) When the session transitioned to COMPLETED. |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| createdBy | string | yes | (Immutable) FK → User UID who created the session. |
+| createdByName | string | yes | (Denormalized) Snapshot of the creator's display name at session creation. |
+| completedBy | any | no | (Read-only) FK → User UID who completed the session, set by server on COMPLETED. |
+| completedByName | any | no | (Denormalized) Snapshot of the completer's display name. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+
+Example:
+```json
+{
+  "id": null,
+  "companyId": "comp_xyz789",
+  "stocktakeNumber": "stocktakeNumber",
+  "stocktakeDate": "stocktakeDate",
+  "warehouseId": "war_ref123",
+  "frequency": "frequency",
+  "scheduledStocktakeId": "sch_ref123",
+  "status": "status",
+  "adjustmentsApplied": true,
+  "notes": "VIP customer, handle with care",
+  "totalItemsCount": 2,
+  "totalDiscrepancies": 0,
+  "totalDeltaValue": 0,
+  "startedAt": "startedAt",
+  "completedAt": "completedAt",
+  "createdAt": "createdAt",
+  "createdBy": "staff_k0f1",
+  "createdByName": "Kofi Mensah",
+  "completedBy": "completedBy",
+  "completedByName": "completedByName",
+  "updatedAt": "updatedAt"
+}
+```
+
+### StocktakeItem
+Fields: 16 (8 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| stockItemId | string | yes | FK → StockItem document ID. Doubles as the item document ID. |
+| stockItemName | string | yes | (Denormalized) Snapshot of StockItem.name at session time. |
+| theoreticalQuantity | number | yes | (Immutable) System belief at session start, snapshotted when this item row was created. |
+| actualQuantity | any | no | Physical count entered by the counter. Null until counted; set when the line moves to status COUNTED. |
+| delta | number | yes | (Read-only) Signed difference between actual and theoretical. Drives the StockMovement(type=INVENTORY) emitted on session COMPLETED. |
+| unit | string | yes | (Immutable) Snapshot of StockItem.unit at session start. Locks the unit against later catalog changes. |
+| costPerUnit | number | yes | (Immutable) Snapshot of StockItem.costPerUnit at session start, in XOF integer minor units. |
+| totalValue | number | yes | (Read-only) Per-line valuation in XOF integer minor units. |
+| status | StocktakeItemStatus | yes | Per-line workflow status. Server transitions ADJUSTED on parent COMPLETED. |
+| notes | any | no | Optional per-line note from the counter (e.g. "damaged carton, 3 unsellable"). |
+| countedBy | any | no | UID of the staff member who entered actualQuantity. |
+| countedByName | any | no | (Denormalized) Snapshot of the counter's display name at count time. |
+| countedAt | any | no | When the line was counted. |
+| verifiedBy | any | no | UID of a second staff member who verified the count. Nullable per GH#29 Q21. |
+| verifiedByName | any | no | (Denormalized) Snapshot of the verifier's display name. |
+| verifiedAt | any | no | When the line was verified, if a second-eye flow was used. |
+
+Example:
+```json
+{
+  "stockItemId": "sto_ref123",
+  "stockItemName": "stockItemName",
+  "theoreticalQuantity": 2,
+  "actualQuantity": "actualQuantity",
+  "delta": 0,
+  "unit": "unit",
+  "costPerUnit": 15000,
+  "totalValue": 0,
+  "status": "status",
+  "notes": "VIP customer, handle with care",
+  "countedBy": "countedBy",
+  "countedByName": "countedByName",
+  "countedAt": "countedAt",
+  "verifiedBy": "verifiedBy",
+  "verifiedByName": "verifiedByName",
+  "verifiedAt": "verifiedAt"
+}
+```
+
 ### Ticket
 Fields: 16 (6 required)