@ingenx-io/valets-schema-mcp-server 0.2.4 → 0.2.5

package/data/static/openapi.yaml

@@ -20,6 +20,16 @@ info:
 paths: {}
 components:
   schemas:
+    AppStatus:
+      type: string
+      enum:
+      - ACTIVE
+      - INACTIVE
+      - EXPIRED
+      - ARCHIVED
+      description: 'Lifecycle status for an App (formerly Site — renamed per decision
+        #40 / D44). Drives whether the app is reachable and whether analytics/payments
+        flow.'
     AttentionStatus:
       type: string
       enum:
@@ -345,7 +355,9 @@ components:
       - _seconds
       - _nanoseconds
       additionalProperties: false
-      description: Firestore Timestamp serialized representation
+      description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+        }. See types/firestore.ts for REST API v1 and client SDK serialization notes
+        (#10).'
     AllowedUser:
       type: object
       properties:
@@ -360,10 +372,11 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
-          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+          description: (Immutable) FK → App document ID (D40 sub-tenant scope, renamed
+            per D44).
         contact:
           type: string
           description: Email or E.164 phone number. Canonical identifier for this
@@ -388,7 +401,7 @@ components:
           description: RFC3339Nano UTC when payment was completed.
       required:
       - companyId
-      - siteId
+      - appId
       - contact
       - tier
       - amount
@@ -396,7 +409,7 @@ components:
       - transactionId
       - paidAt
       additionalProperties: false
-      description: 'AllowedUser model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/allowed_users/{contactId}.
+      description: 'AllowedUser model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/allowed_users/{contactId}.
         Authoritative paid-access allowlist. Upsert semantics — tier upgrades overwrite.
         Source of truth for access checks and referral code resolution.'
     AllowedUserCreate:
@@ -407,7 +420,7 @@ components:
         may be set once at creation.
       required:
       - companyId
-      - siteId
+      - appId
       - contact
       - tier
       - amount
@@ -433,7 +446,7 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
           description: (Immutable) FK → Site document ID (D40).
@@ -501,7 +514,7 @@ components:
           description: (Read-only) When the run reached a terminal status.
       required:
       - companyId
-      - siteId
+      - appId
       - status
       - from
       - to
@@ -511,7 +524,7 @@ components:
       - triggeredBy
       - startedAt
       additionalProperties: false
-      description: 'AnalyticsBackfill run (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_backfills/{runId}.
+      description: 'AnalyticsBackfill run (D42 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_backfills/{runId}.
         Tracks admin-triggered rollup backfill jobs; supports dry-run.'
     AnalyticsBackfillCreate:
       allOf:
@@ -521,7 +534,7 @@ components:
         may be set once at creation.
       required:
       - companyId
-      - siteId
+      - appId
       - status
       - from
       - to
@@ -607,7 +620,7 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
           description: (Immutable) FK → Site document ID (D40).
@@ -641,11 +654,11 @@ components:
       - errors
       - eventCounts
       - companyId
-      - siteId
+      - appId
       - date
       - computedAt
       additionalProperties: false
-      description: 'AnalyticsDaily rollup (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_daily/{YYYY-MM-DD}.
+      description: 'AnalyticsDaily rollup (D42 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_daily/{YYYY-MM-DD}.
         Idempotent set/merge — reruns overwrite. Fall back to raw analytics_events
         for uncovered slices.'
     AnalyticsDailyCreate:
@@ -666,7 +679,7 @@ components:
       - errors
       - eventCounts
       - companyId
-      - siteId
+      - appId
       - date
     AnalyticsDailyUpdate:
       allOf:
@@ -687,10 +700,11 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
-          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+          description: (Immutable) FK → App document ID (D40 sub-tenant scope, renamed
+            per D44).
         eventId:
           type: string
           x-immutable: true
@@ -806,7 +820,7 @@ components:
           additionalProperties: {}
       required:
       - companyId
-      - siteId
+      - appId
       - eventId
       - eventName
       - timestamp
@@ -816,7 +830,7 @@ components:
       - properties
       - context
       additionalProperties: false
-      description: 'AnalyticsEvent model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_events/{eventId}.
+      description: 'AnalyticsEvent model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_events/{eventId}.
         Append-only, immutable product/behavior event stream. Event names are free
         strings; canonical vocabulary in CANONICAL_ANALYTICS_EVENT_NAMES.'
     AnalyticsEventCreate:
@@ -827,7 +841,7 @@ components:
         may be set once at creation.
       required:
       - companyId
-      - siteId
+      - appId
       - eventId
       - eventName
       - timestamp
@@ -913,7 +927,7 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
           description: (Immutable) FK → Site document ID (D40).
@@ -952,12 +966,12 @@ components:
       - errors
       - eventCounts
       - companyId
-      - siteId
+      - appId
       - date
       - hour
       - computedAt
       additionalProperties: false
-      description: 'AnalyticsHourly rollup (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_hourly/{YYYY-MM-DD-HH}.
+      description: 'AnalyticsHourly rollup (D42 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_hourly/{YYYY-MM-DD-HH}.
         Scheduled-CF writer; idempotent set/merge.'
     AnalyticsHourlyCreate:
       allOf:
@@ -977,7 +991,7 @@ components:
       - errors
       - eventCounts
       - companyId
-      - siteId
+      - appId
       - date
       - hour
     AnalyticsHourlyUpdate:
@@ -986,6 +1000,265 @@ components:
       description: Write payload for partial update (PATCH) of a AnalyticsHourly document.
         All fields optional. Fields marked `readOnly` or `x-immutable` must not be
         sent.
+    App:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Scopes all app sub-collections.
+        name:
+          type: string
+          description: Human-readable app name shown in dashboards.
+        description:
+          description: Optional freeform description.
+          type:
+          - string
+          - 'null'
+        status:
+          $ref: '#/components/schemas/AppStatus'
+          description: Lifecycle status (D41/D44). Clients filter by ACTIVE.
+          x-note: ACTIVE = live and serving traffic. INACTIVE = intentionally disabled
+            by operators. EXPIRED = past expiresAt (derived when isExpired is true;
+            may also be stored explicitly). ARCHIVED = soft-deleted; retained for
+            audit but not listed by default.
+          x-see:
+            decisions:
+            - D41
+            - D44
+          x-when: Written by operators via dashboard or by server triggers (expiration).
+            Clients filter by ACTIVE.
+        deploymentLinks:
+          type: array
+          items:
+            type: object
+            properties:
+              label:
+                type: string
+                description: Human-readable label shown in dashboards (e.g. "Production",
+                  "Staging").
+              url:
+                type: string
+                description: Absolute URL or store link.
+              type:
+                $ref: '#/components/schemas/DeploymentLinkType'
+                description: Link category — drives icon/handler selection.
+                x-note: Lowercase by convention — deployment link types are display-oriented
+                  labels, not lifecycle states.
+                x-see:
+                  decisions:
+                  - D41
+              isPrimary:
+                description: If true, this link is used as the canonical deployment
+                  URL for the App.
+                type: boolean
+            required:
+            - label
+            - url
+            - type
+            additionalProperties: false
+            description: Deployment link entry embedded on App.deploymentLinks[] (D41).
+          description: Ordered list of deployment URLs (web, mobile, PWA, store links).
+        expiresAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: Optional expiration timestamp. When set and elapsed, `isExpired`
+            flips true and status typically moves to EXPIRED.
+        isExpired:
+          readOnly: true
+          description: (Read-only) Derived — true when `expiresAt` is in the past.
+            Maintained by server trigger.
+          type:
+          - boolean
+          - 'null'
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created the app.
+        analyticsEnabled:
+          type: boolean
+          description: Feature flag — when false, clients should not emit analytics
+            events for this app.
+        lastAnalyticsSync:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Last time the analytics rollup pipeline refreshed
+            `cachedMetrics`.
+        cachedMetrics:
+          readOnly: true
+          denormalized: true
+          x-note: Updated by the rollup pipeline (D42). Readers should treat this
+            as a hint; authoritative counts live in analytics_daily/analytics_hourly.
+          x-see:
+            decisions:
+            - D41
+            - D42
+          description: (Read-only, Denormalized) Cached metrics snapshot for quick
+            dashboard rendering.
+          type:
+          - object
+          - 'null'
+          properties:
+            totalEvents:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+              description: All-time event count cached on the App.
+            totalPageViews:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+              description: All-time `page_view` + `screen_view` count.
+            totalSessions:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+              description: All-time distinct session count.
+            totalOrders:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+              description: All-time order count attributed to this app (via `Order.appId`,
+                D43).
+            lastEventAt:
+              $ref: '#/components/schemas/FirestoreTimestamp'
+              description: Timestamp of the most recent analytics event seen for this
+                app.
+          required:
+          - totalEvents
+          - totalPageViews
+          - totalSessions
+          - totalOrders
+          additionalProperties: false
+      required:
+      - companyId
+      - name
+      - status
+      - deploymentLinks
+      - createdBy
+      - analyticsEnabled
+      additionalProperties: false
+      description: 'App model (D41 / ING-304). Collection: companies/{companyId}/apps/{appId}.
+        Per-company product surface. Sub-collections (magic_link_requests, allowed_users,
+        payments, analytics_events, analytics_daily, analytics_hourly, analytics_backfills)
+        live under this document per D40/D42.'
+    AppCreate:
+      allOf:
+      - $ref: '#/components/schemas/App'
+      description: Write payload for creating a new App document. Fields marked `readOnly`
+        are server-set and must not be included. Fields marked `x-immutable` may be
+        set once at creation.
+      required:
+      - companyId
+      - name
+      - status
+      - deploymentLinks
+      - createdBy
+      - analyticsEnabled
+    AppUpdate:
+      allOf:
+      - $ref: '#/components/schemas/App'
+      description: Write payload for partial update (PATCH) of a App document. All
+        fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
+    AppPayment:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        appId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → App document ID (D40 sub-tenant scope, renamed
+            from siteId per D44).
+        contact:
+          type: string
+          description: Email or E.164 phone number. Matches AllowedUser.contact.
+        sessionId:
+          type: string
+          description: Payment provider checkout session ID (e.g. Wave). Usable for
+            dedup across dual writes.
+        transactionId:
+          type: string
+          description: Payment provider transaction ID.
+        tier:
+          type: string
+          description: Access tier. Free string per app (ING-304 open question).
+        amount:
+          type: number
+          description: Amount paid. Generalized from amount_xof per D40 decision.
+        currency:
+          default: XOF
+          description: Currency code (ISO 4217). Defaults to XOF for legacy SR-Single
+            parity.
+          type: string
+        paidAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: RFC3339Nano UTC when payment was completed.
+      required:
+      - companyId
+      - appId
+      - contact
+      - sessionId
+      - transactionId
+      - tier
+      - amount
+      - currency
+      - paidAt
+      additionalProperties: false
+      description: 'AppPayment model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/payments/{paymentId}.
+        Immutable append-only transaction ledger. Distinct from AllowedUser (access
+        state) and CustomerPayment (D22 — customer-level billing).'
+    AppPaymentCreate:
+      allOf:
+      - $ref: '#/components/schemas/AppPayment'
+      description: Write payload for creating a new AppPayment document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - appId
+      - contact
+      - sessionId
+      - transactionId
+      - tier
+      - amount
+      - currency
+      - paidAt
+    AppPaymentUpdate:
+      allOf:
+      - $ref: '#/components/schemas/AppPayment'
+      description: Write payload for partial update (PATCH) of a AppPayment document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
     Booking:
       type: object
       properties:
@@ -1062,13 +1335,17 @@ components:
                       type: boolean
                     _deletedAt:
                       $ref: '#/components/schemas/FirestoreTimestamp'
-                      description: Firestore Timestamp serialized representation
+                      description: 'Firestore Timestamp — Admin SDK form: { _seconds,
+                        _nanoseconds }. See types/firestore.ts for REST API v1 and
+                        client SDK serialization notes (#10).'
                     _deletedBy:
                       description: FK → User/staff UID who soft-deleted this item.
                       type: string
                     _lastModifiedAt:
                       $ref: '#/components/schemas/FirestoreTimestamp'
-                      description: Firestore Timestamp serialized representation
+                      description: 'Firestore Timestamp — Admin SDK form: { _seconds,
+                        _nanoseconds }. See types/firestore.ts for REST API v1 and
+                        client SDK serialization notes (#10).'
                     _lastModifiedBy:
                       description: FK → User/staff UID who last modified this item.
                       type: string
@@ -1133,7 +1410,9 @@ components:
                   type: string
                 additionalProperties:
                   $ref: '#/components/schemas/FirestoreTimestamp'
-                  description: Firestore Timestamp serialized representation
+                  description: 'Firestore Timestamp — Admin SDK form: { _seconds,
+                    _nanoseconds }. See types/firestore.ts for REST API v1 and client
+                    SDK serialization notes (#10).'
               slotStatusUpdatedBy:
                 type: object
                 propertyNames:
@@ -1145,13 +1424,17 @@ components:
                 type: boolean
               _deletedAt:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               _deletedBy:
                 description: FK → User/staff UID who soft-deleted this item.
                 type: string
               _lastModifiedAt:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               _lastModifiedBy:
                 description: FK → User/staff UID who last modified this item.
                 type: string
@@ -1313,13 +1596,17 @@ components:
                 type: boolean
               _deletedAt:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               _deletedBy:
                 description: FK → User/staff UID who soft-deleted this item.
                 type: string
               _lastModifiedAt:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               _lastModifiedBy:
                 description: FK → User/staff UID who last modified this item.
                 type: string
@@ -1372,7 +1659,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         paymentProofUrl:
           description: URL to uploaded payment proof image/document.
           type:
@@ -1388,7 +1677,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         paymentProofAddedBy:
           description: FK → User/staff UID who uploaded the payment proof.
           type:
@@ -1403,7 +1694,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         paymentProofRejectionReason:
           type:
           - string
@@ -1426,7 +1719,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         cancelledByRole:
           type:
           - string
@@ -1633,7 +1928,9 @@ components:
             properties:
               timestamp:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               type:
                 type: string
                 description: Communication channel (e.g. phone, email, meeting).
@@ -1750,7 +2047,9 @@ components:
           description: Currency code. Locked to XOF (West African CFA franc) for now.
         paymentDate:
           $ref: '#/components/schemas/FirestoreTimestamp'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         paymentMethod:
           $ref: '#/components/schemas/PaymentMethod'
           description: Unified payment method set with African + global methods (D02).
@@ -1894,7 +2193,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         createdBy:
           type: string
           x-immutable: true
@@ -1967,12 +2268,16 @@ components:
           - 'null'
         startDate:
           $ref: '#/components/schemas/FirestoreTimestamp'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         endDate:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         status:
           $ref: '#/components/schemas/EventStatus'
           description: Event lifecycle status (D32). SCREAMING_SNAKE per D04. MIG-09
@@ -2417,10 +2722,11 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
-          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+          description: (Immutable) FK → App document ID (D40 sub-tenant scope, renamed
+            per D44).
         email:
           type: string
           description: Populated if identifier is email; empty string if phone. Mutually
@@ -2472,7 +2778,7 @@ components:
           description: RFC3339Nano UTC at verify time.
       required:
       - companyId
-      - siteId
+      - appId
       - email
       - phone
       - ip
@@ -2483,7 +2789,7 @@ components:
       - referredBy
       - requestedAt
       additionalProperties: false
-      description: 'MagicLinkRequest model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/magic_link_requests/{requestId}.
+      description: 'MagicLinkRequest model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/magic_link_requests/{requestId}.
         Authentication audit log — every request is logged regardless of outcome.
         Two-stage write: Log() then LogVerify().'
     MagicLinkRequestCreate:
@@ -2494,7 +2800,7 @@ components:
         may be set once at creation.
       required:
       - companyId
-      - siteId
+      - appId
       - email
       - phone
       - ip
@@ -2652,6 +2958,62 @@ components:
           readOnly: true
           description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
             Always full recalc.
+        escalatedOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an escalated state.
+            Present once the current aggregator rewrites the document.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleBookingsCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Bookings that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        onHoldOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an on-hold state.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        paymentsByMethod:
+          readOnly: true
+          x-note: Always {} until the first real payment is recorded. Present on all
+            tenants once rewritten by current aggregator (#8).
+          description: (Read-only, Optional) Map of PaymentMethod → total amount for
+            the current day. Empty map {} until first payment.
+          type:
+          - object
+          - 'null'
+          propertyNames:
+            type: string
+          additionalProperties:
+            type: number
         computedForDay:
           type: string
           readOnly: true
@@ -2845,6 +3207,62 @@ components:
           readOnly: true
           description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
             Always full recalc.
+        escalatedOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an escalated state.
+            Present once the current aggregator rewrites the document.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleBookingsCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Bookings that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        onHoldOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an on-hold state.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        paymentsByMethod:
+          readOnly: true
+          x-note: Always {} until the first real payment is recorded. Present on all
+            tenants once rewritten by current aggregator (#8).
+          description: (Read-only, Optional) Map of PaymentMethod → total amount for
+            the current day. Empty map {} until first payment.
+          type:
+          - object
+          - 'null'
+          propertyNames:
+            type: string
+          additionalProperties:
+            type: number
         computedForDay:
           type: string
           readOnly: true
@@ -3044,6 +3462,62 @@ components:
           readOnly: true
           description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
             Always full recalc.
+        escalatedOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an escalated state.
+            Present once the current aggregator rewrites the document.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleBookingsCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Bookings that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        onHoldOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an on-hold state.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        paymentsByMethod:
+          readOnly: true
+          x-note: Always {} until the first real payment is recorded. Present on all
+            tenants once rewritten by current aggregator (#8).
+          description: (Read-only, Optional) Map of PaymentMethod → total amount for
+            the current day. Empty map {} until first payment.
+          type:
+          - object
+          - 'null'
+          propertyNames:
+            type: string
+          additionalProperties:
+            type: number
         computedForDay:
           type: string
           readOnly: true
@@ -3263,9 +3737,11 @@ components:
       - createdAt
       additionalProperties: false
       description: 'NotificationRecord — backend-written, multi-channel notification
-        audit log (GH#48). Paths: companies/{cid}/notifications/{id} (always) and
-        companies/{cid}/orders/{oid}/notifications/{id} (dual-write when relatedEntity.type=order).
-        Consumers read only. Distinct from WhatsappOutboundMessage (GH#43).'
+        audit log (GH#48). Paths: companies/{cid}/notification_records/{id} (always)
+        and companies/{cid}/orders/{oid}/notification_records/{id} (dual-write when
+        relatedEntity.type=order). Consumers read only. Distinct from WhatsappOutboundMessage
+        (GH#43). Collection renamed from notifications → notification_records per
+        decision #55 (2026-05-30).'
     Order:
       type: object
       properties:
@@ -3282,20 +3758,22 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID. Scopes all queries.
-        siteId:
+        appId:
           x-immutable: true
-          x-note: 'D43 / ADR-003: optional site attribution. Absent/null means company-wide
-            (legacy). When set, the order is attributed to a specific site for analytics
-            and site-scoped dashboards. No migration — existing orders keep null.
-            Flat path; Order continues to live at `companies/{companyId}/orders/{orderId}`.'
+          x-note: 'D43 / ADR-003: optional app attribution (renamed from siteId per
+            D44). Absent/null means company-wide (legacy). When set, the order is
+            attributed to a specific app for analytics and app-scoped dashboards.
+            No migration — existing orders keep null. Flat path; Order continues to
+            live at `companies/{companyId}/orders/{orderId}`.'
           x-see:
             decisions:
             - D43
-          x-when: 'Set at order creation when the client knows which site the order
+            - D44
+          x-when: 'Set at order creation when the client knows which app the order
             originated from (e.g. SR Single, Lifesense). Leave null for legacy/company-wide
-            orders. Composite index: (companyId, siteId, createdAt).'
-          description: (Immutable, Optional) FK → Site document ID (D43 / ADR-003).
-            null = company-wide.
+            orders. Composite index: (companyId, appId, createdAt).'
+          description: (Immutable, Optional) FK → App document ID (D43 / ADR-003,
+            renamed from siteId per D44). null = company-wide.
           type:
           - string
           - 'null'
@@ -3485,7 +3963,9 @@ components:
           readOnly: true
         orderDate:
           $ref: '#/components/schemas/FirestoreTimestamp'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         PROCESSING_ON:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
@@ -3530,7 +4010,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         shippingCost:
           type:
           - number
@@ -3617,7 +4099,9 @@ components:
                 description: Payment method used (D02).
               paymentDate:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               referenceNumber:
                 description: Payment reference (receipt number, transaction ID, etc.).
                 type: string
@@ -3895,7 +4379,9 @@ components:
           - 'null'
         purchaseDate:
           $ref: '#/components/schemas/FirestoreTimestamp'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         createdAt:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
@@ -4631,6 +5117,86 @@ components:
       description: Write payload for partial update (PATCH) of a Ticket document.
         All fields optional. Fields marked `readOnly` or `x-immutable` must not be
         sent.
+    User:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firebase Auth UID. Matches the Firestore document
+            ID.
+          type:
+          - string
+          - 'null'
+        displayName:
+          description: User display name from Firebase Auth or manually set.
+          type:
+          - string
+          - 'null'
+        email:
+          description: Email address. Present for email/Google auth users.
+          type:
+          - string
+          - 'null'
+        phoneE164:
+          x-note: 'E.164 format with leading + (e.g. +2250777471485). Canonical phone
+            identity field (decision #27). Distinct from wa_id (Meta conversation
+            key). Server must normalize at write time: 8-digit CI local → prepend
+            +225.'
+          x-when: Set when the user authenticated via phone (WhatsApp OTP) or when
+            a staff member's phone is known. Required for WhatsApp OTP lookup — add
+            a Firestore composite index on phoneE164.
+          description: E.164-normalized phone number (e.g. +2250777471485). Canonical
+            phone identity field; used for WhatsApp OTP lookup via indexed query.
+          type:
+          - string
+          - 'null'
+        companyId:
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Present for staff accounts
+            scoped to a company.
+          type:
+          - string
+          - 'null'
+        role:
+          description: Staff role within the company (e.g. admin, manager, staff).
+            Application-defined.
+          type:
+          - string
+          - 'null'
+        isActive:
+          description: Whether this user account is active. Inactive accounts are
+            denied access.
+          type:
+          - boolean
+          - 'null'
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When the user document was created.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When the user document was last updated.
+      additionalProperties: false
+      description: 'User / staff account. Collection: users/{uid}. Document ID is
+        always the Firebase Auth UID (decision #27). phoneE164 is the canonical E.164
+        phone field for OTP lookup. Legacy phone-keyed documents must be migrated
+        to uid-keyed docs with phoneE164 set.'
+    UserCreate:
+      allOf:
+      - $ref: '#/components/schemas/User'
+      description: Write payload for creating a new User document. Fields marked `readOnly`
+        are server-set and must not be included. Fields marked `x-immutable` may be
+        set once at creation.
+    UserUpdate:
+      allOf:
+      - $ref: '#/components/schemas/User'
+      description: Write payload for partial update (PATCH) of a User document. All
+        fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
     WhatsappInboundMessage:
       type: object
       properties: