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

package/data/static/openapi.yaml

@@ -20,6 +20,16 @@ info:
 paths: {}
 components:
   schemas:
+    AttentionStatus:
+      type: string
+      enum:
+      - ACTIVE
+      - STALE
+      - ON_HOLD
+      - ESCALATED
+      description: Operational attention status for Order and Booking (D39). Controls
+        home-page queue assignment. Server-owned — set via triggers or callable fn
+        only.
     BookingStatus:
       type: string
       enum:
@@ -59,6 +69,17 @@ components:
         comes to the business (ON_SITE), collects their order themselves (PICK_UP),
         or receives a physical delivery (DELIVERY). Drives whether fulfillmentStatus
         is relevant.
+    DeploymentLinkType:
+      type: string
+      enum:
+      - web
+      - mobile
+      - pwa
+      - app-store
+      - play-store
+      - other
+      description: Category of a Site deployment link (D41). Used for UI icon/labelling
+        and deep-link handling.
     EventStatus:
       type: string
       enum:
@@ -135,6 +156,23 @@ components:
       - PARTIALLY_REFUNDED
       description: Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase,
         Booking.
+    PendingIssue:
+      type: string
+      enum:
+      - 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
+      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.
     ReturnStatus:
       type: string
       enum:
@@ -157,6 +195,15 @@ components:
       - CANCELLED
       description: Per-date/per-slot booking session status (D19). Dashboard is sole
         writer; Mobile is read-only.
+    SiteStatus:
+      type: string
+      enum:
+      - ACTIVE
+      - INACTIVE
+      - EXPIRED
+      - ARCHIVED
+      description: Lifecycle status for a Site (D41). Drives whether the site is reachable
+        and whether analytics/payments flow.
     TicketStatus:
       type: string
       enum:
@@ -180,6 +227,646 @@ components:
       - _nanoseconds
       additionalProperties: false
       description: Firestore Timestamp serialized representation
+    AllowedUser:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID = contact identifier (email
+            or E.164 phone), URL-escaped.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        siteId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+        contact:
+          type: string
+          description: Email or E.164 phone number. Canonical identifier for this
+            user within the site.
+        tier:
+          type: string
+          description: Access tier. Free string per site (ING-304 open question —
+            tier values are site-specific today).
+        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
+        transactionId:
+          type: string
+          description: Payment provider transaction ID (e.g. Wave).
+        paidAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: RFC3339Nano UTC when payment was completed.
+      required:
+      - companyId
+      - siteId
+      - contact
+      - tier
+      - amount
+      - currency
+      - transactionId
+      - paidAt
+      additionalProperties: false
+      description: 'AllowedUser model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/allowed_users/{contactId}.
+        Authoritative paid-access allowlist. Upsert semantics — tier upgrades overwrite.
+        Source of truth for access checks and referral code resolution.'
+    AllowedUserCreate:
+      allOf:
+      - $ref: '#/components/schemas/AllowedUser'
+      description: Write payload for creating a new AllowedUser document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - siteId
+      - contact
+      - tier
+      - amount
+      - currency
+      - transactionId
+      - paidAt
+    AllowedUserUpdate:
+      allOf:
+      - $ref: '#/components/schemas/AllowedUser'
+      description: Write payload for partial update (PATCH) of a AllowedUser document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    AnalyticsBackfill:
+      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.
+        siteId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Site document ID (D40).
+        status:
+          type: string
+          enum:
+          - pending
+          - running
+          - completed
+          - failed
+          - cancelled
+          description: Run status.
+        from:
+          type: string
+          x-immutable: true
+          description: (Immutable) Inclusive start date (`YYYY-MM-DD`, UTC).
+        to:
+          type: string
+          x-immutable: true
+          description: (Immutable) Inclusive end date (`YYYY-MM-DD`, UTC).
+        dryRun:
+          type: boolean
+          x-immutable: true
+          description: (Immutable) When true, rollup writes are skipped — only source
+            counts are returned for diffing.
+        processedDates:
+          type: array
+          items:
+            type: string
+          description: Ordered list of `YYYY-MM-DD` dates already processed by this
+            run.
+        errors:
+          type: array
+          items:
+            type: object
+            properties:
+              date:
+                type: string
+                description: '`YYYY-MM-DD` date that failed.'
+              message:
+                type: string
+                description: Error message captured at failure.
+              at:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: When the error occurred.
+            required:
+            - date
+            - message
+            - at
+            additionalProperties: false
+          description: Per-date errors collected during the run.
+        triggeredBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) UID of the admin who triggered the backfill.
+        startedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) When the run actually started.
+          readOnly: true
+        completedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When the run reached a terminal status.
+      required:
+      - companyId
+      - siteId
+      - status
+      - from
+      - to
+      - dryRun
+      - processedDates
+      - errors
+      - triggeredBy
+      - startedAt
+      additionalProperties: false
+      description: 'AnalyticsBackfill run (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_backfills/{runId}.
+        Tracks admin-triggered rollup backfill jobs; supports dry-run.'
+    AnalyticsBackfillCreate:
+      allOf:
+      - $ref: '#/components/schemas/AnalyticsBackfill'
+      description: Write payload for creating a new AnalyticsBackfill document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - siteId
+      - status
+      - from
+      - to
+      - dryRun
+      - processedDates
+      - errors
+      - triggeredBy
+    AnalyticsBackfillUpdate:
+      allOf:
+      - $ref: '#/components/schemas/AnalyticsBackfill'
+      description: Write payload for partial update (PATCH) of a AnalyticsBackfill
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
+    AnalyticsDaily:
+      type: object
+      properties:
+        totalEvents:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Total event count within the bucket.
+        pageViews:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `page_view` + `screen_view` events.
+        sessions:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Distinct session count within the bucket (by `sessionId`).
+        uniqueUsers:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Distinct identified `userId` count. Anonymous sessions (userId=null)
+            are excluded.
+        anonymousSessions:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Distinct session count where `userId` was null for the entire
+            session.
+        orders:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `order_submitted` events (or Order documents scoped
+            to this site, D43) within the bucket.
+        paymentsCompleted:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `payment_completed` events within the bucket.
+        paymentsFailed:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `payment_failed` events within the bucket.
+        errors:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `error_occurred` + `exception_caught` events within
+            the bucket.
+        eventCounts:
+          type: object
+          propertyNames:
+            type: string
+          additionalProperties:
+            type: integer
+            minimum: -9007199254740991
+            maximum: 9007199254740991
+          description: Per-event-name counts — key is the event name (canonical or
+            custom), value is the count within the bucket.
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID = `YYYY-MM-DD`.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        siteId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Site document ID (D40).
+        date:
+          type: string
+          x-immutable: true
+          description: (Immutable) `YYYY-MM-DD` UTC — matches document ID.
+        computedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) When this rollup was last (re)computed. Updated
+            on every set/merge.
+          readOnly: true
+        sourceEventCount:
+          readOnly: true
+          description: (Read-only, Optional) Total source events scanned when producing
+            this rollup. Useful for dry-run diffing.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+      required:
+      - totalEvents
+      - pageViews
+      - sessions
+      - uniqueUsers
+      - anonymousSessions
+      - orders
+      - paymentsCompleted
+      - paymentsFailed
+      - errors
+      - eventCounts
+      - companyId
+      - siteId
+      - date
+      - computedAt
+      additionalProperties: false
+      description: 'AnalyticsDaily rollup (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_daily/{YYYY-MM-DD}.
+        Idempotent set/merge — reruns overwrite. Fall back to raw analytics_events
+        for uncovered slices.'
+    AnalyticsDailyCreate:
+      allOf:
+      - $ref: '#/components/schemas/AnalyticsDaily'
+      description: Write payload for creating a new AnalyticsDaily document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - totalEvents
+      - pageViews
+      - sessions
+      - uniqueUsers
+      - anonymousSessions
+      - orders
+      - paymentsCompleted
+      - paymentsFailed
+      - errors
+      - eventCounts
+      - companyId
+      - siteId
+      - date
+    AnalyticsDailyUpdate:
+      allOf:
+      - $ref: '#/components/schemas/AnalyticsDaily'
+      description: Write payload for partial update (PATCH) of a AnalyticsDaily document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    AnalyticsEvent:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID. Equal to eventId.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        siteId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+        eventId:
+          type: string
+          x-immutable: true
+          description: (Immutable) Client-generated UUID. Matches document ID.
+        eventName:
+          type: string
+          description: Event name. Free string; canonical vocabulary is encouraged
+            (see CANONICAL_ANALYTICS_EVENT_NAMES).
+        timestamp:
+          type: string
+          description: Client-side ISO 8601 — "when it happened on device". Can diverge
+            from serverTimestamp for queued offline events.
+        serverTimestamp:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) Firestore serverTimestamp() — authoritative for
+            ordering.
+          readOnly: true
+        sessionId:
+          type: string
+          description: 30-minute rolling session identifier.
+        userId:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Stable user ID if identified; explicitly null (not omitted)
+            for anonymous sessions — simplifies querying.
+        properties:
+          type: object
+          propertyNames:
+            type: string
+          additionalProperties: {}
+          description: 'Free-form event-specific payload. Contract is at the event-name
+            level. PII posture: follow-up issue pending.'
+        context:
+          type: object
+          properties:
+            url:
+              description: Full URL at event time.
+              type: string
+            origin:
+              description: Protocol + host.
+              type: string
+            hostname:
+              description: Hostname only — useful for deployment identification.
+              type: string
+            page:
+              description: Current route/pathname.
+              type: string
+            title:
+              description: Page title.
+              type: string
+            referrer:
+              description: Referrer URL.
+              type: string
+            deviceType:
+              type: string
+              enum:
+              - mobile
+              - tablet
+              - desktop
+            platform:
+              description: OS/platform string.
+              type: string
+            screenWidth:
+              description: Viewport width (flattened from screen.width).
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+            screenHeight:
+              description: Viewport height (flattened from screen.height).
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+            appVersion:
+              description: Consuming app version.
+              type: string
+            online:
+              description: Connectivity state at event time.
+              type: boolean
+            locale:
+              description: User locale.
+              type: string
+            timezone:
+              description: IANA timezone.
+              type: string
+            utm:
+              description: UTM parameters; null when not a campaign-landed session.
+              anyOf:
+              - type: object
+                properties:
+                  source:
+                    type: string
+                  medium:
+                    type: string
+                  campaign:
+                    type: string
+                  term:
+                    type: string
+                  content:
+                    type: string
+                additionalProperties: false
+              - type: 'null'
+          additionalProperties: false
+          description: Environment context at event time (nested per D40).
+        userTraits:
+          description: 'Optional — included only when includeUserTraits: true on the
+            write. PII posture: follow-up issue pending.'
+          type:
+          - object
+          - 'null'
+          propertyNames:
+            type: string
+          additionalProperties: {}
+      required:
+      - companyId
+      - siteId
+      - eventId
+      - eventName
+      - timestamp
+      - serverTimestamp
+      - sessionId
+      - userId
+      - properties
+      - context
+      additionalProperties: false
+      description: 'AnalyticsEvent model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_events/{eventId}.
+        Append-only, immutable product/behavior event stream. Event names are free
+        strings; canonical vocabulary in CANONICAL_ANALYTICS_EVENT_NAMES.'
+    AnalyticsEventCreate:
+      allOf:
+      - $ref: '#/components/schemas/AnalyticsEvent'
+      description: Write payload for creating a new AnalyticsEvent document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - siteId
+      - eventId
+      - eventName
+      - timestamp
+      - sessionId
+      - userId
+      - properties
+      - context
+    AnalyticsEventUpdate:
+      allOf:
+      - $ref: '#/components/schemas/AnalyticsEvent'
+      description: Write payload for partial update (PATCH) of a AnalyticsEvent document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    AnalyticsHourly:
+      type: object
+      properties:
+        totalEvents:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Total event count within the bucket.
+        pageViews:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `page_view` + `screen_view` events.
+        sessions:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Distinct session count within the bucket (by `sessionId`).
+        uniqueUsers:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Distinct identified `userId` count. Anonymous sessions (userId=null)
+            are excluded.
+        anonymousSessions:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Distinct session count where `userId` was null for the entire
+            session.
+        orders:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `order_submitted` events (or Order documents scoped
+            to this site, D43) within the bucket.
+        paymentsCompleted:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `payment_completed` events within the bucket.
+        paymentsFailed:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `payment_failed` events within the bucket.
+        errors:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Count of `error_occurred` + `exception_caught` events within
+            the bucket.
+        eventCounts:
+          type: object
+          propertyNames:
+            type: string
+          additionalProperties:
+            type: integer
+            minimum: -9007199254740991
+            maximum: 9007199254740991
+          description: Per-event-name counts — key is the event name (canonical or
+            custom), value is the count within the bucket.
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID = `YYYY-MM-DD-HH`.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        siteId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Site document ID (D40).
+        date:
+          type: string
+          x-immutable: true
+          description: (Immutable) `YYYY-MM-DD` UTC for the bucket day.
+        hour:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          x-immutable: true
+          description: (Immutable) UTC hour of day, 0–23.
+        computedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: (Read-only) When this rollup was last (re)computed.
+          readOnly: true
+        sourceEventCount:
+          readOnly: true
+          description: (Read-only, Optional) Total source events scanned when producing
+            this rollup.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+      required:
+      - totalEvents
+      - pageViews
+      - sessions
+      - uniqueUsers
+      - anonymousSessions
+      - orders
+      - paymentsCompleted
+      - paymentsFailed
+      - errors
+      - eventCounts
+      - companyId
+      - siteId
+      - date
+      - hour
+      - computedAt
+      additionalProperties: false
+      description: 'AnalyticsHourly rollup (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_hourly/{YYYY-MM-DD-HH}.
+        Scheduled-CF writer; idempotent set/merge.'
+    AnalyticsHourlyCreate:
+      allOf:
+      - $ref: '#/components/schemas/AnalyticsHourly'
+      description: Write payload for creating a new AnalyticsHourly document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - totalEvents
+      - pageViews
+      - sessions
+      - uniqueUsers
+      - anonymousSessions
+      - orders
+      - paymentsCompleted
+      - paymentsFailed
+      - errors
+      - eventCounts
+      - companyId
+      - siteId
+      - date
+      - hour
+    AnalyticsHourlyUpdate:
+      allOf:
+      - $ref: '#/components/schemas/AnalyticsHourly'
+      description: Write payload for partial update (PATCH) of a AnalyticsHourly document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
     Booking:
       type: object
       properties:
@@ -1598,6 +2285,112 @@ components:
       description: Write payload for partial update (PATCH) of a LoyaltyTransaction
         document. All fields optional. Fields marked `readOnly` or `x-immutable` must
         not be sent.
+    MagicLinkRequest:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID. 16-byte random hex.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        siteId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+        email:
+          type: string
+          description: Populated if identifier is email; empty string if phone. Mutually
+            exclusive with phone per document.
+        phone:
+          type: string
+          description: Populated if identifier is E.164 format (starts with +); empty
+            string if email.
+        ip:
+          type: string
+          description: Client IP from X-Forwarded-For or RemoteAddr.
+        allowed:
+          type: boolean
+          description: Whether the user passed the access control check.
+        link:
+          type: string
+          description: Magic-link URL — non-empty only when DEV_MODE=true; empty in
+            production (audit integrity).
+        tier:
+          type: string
+          description: Access tier selected by the user. Free string per site (ING-304
+            open question — tier values are site-specific today).
+        authStatusReason:
+          type: string
+          description: 'Outcome reason code: whitelist | allowed_users | payment_redirect
+            | payment_complete | not_allowed | redirected_to_payment.'
+        referredBy:
+          type: string
+          description: Contact identifier of the referrer, resolved from submitted
+            referral_code; empty if none.
+        requestedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: RFC3339Nano UTC at request time.
+        verifyReason:
+          description: 'Verify outcome reason: mirrors authStatusReason on success,
+            or link_expired | link_invalid | not_allowed.'
+          type:
+          - string
+          - 'null'
+        verified:
+          description: Whether the verify attempt succeeded.
+          type:
+          - boolean
+          - 'null'
+        verifiedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: RFC3339Nano UTC at verify time.
+      required:
+      - companyId
+      - siteId
+      - email
+      - phone
+      - ip
+      - allowed
+      - link
+      - tier
+      - authStatusReason
+      - referredBy
+      - requestedAt
+      additionalProperties: false
+      description: 'MagicLinkRequest model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/magic_link_requests/{requestId}.
+        Authentication audit log — every request is logged regardless of outcome.
+        Two-stage write: Log() then LogVerify().'
+    MagicLinkRequestCreate:
+      allOf:
+      - $ref: '#/components/schemas/MagicLinkRequest'
+      description: Write payload for creating a new MagicLinkRequest document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - siteId
+      - email
+      - phone
+      - ip
+      - allowed
+      - link
+      - tier
+      - authStatusReason
+      - referredBy
+      - requestedAt
+    MagicLinkRequestUpdate:
+      allOf:
+      - $ref: '#/components/schemas/MagicLinkRequest'
+      description: Write payload for partial update (PATCH) of a MagicLinkRequest
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
     MetricsCurrent:
       type: object
       properties:
@@ -2205,6 +2998,23 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID. Scopes all queries.
+        siteId:
+          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-see:
+            decisions:
+            - D43
+          x-when: 'Set at order creation when the client knows which site 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.
+          type:
+          - string
+          - 'null'
         orderNumber:
           type: string
           readOnly: true
@@ -2827,6 +3637,264 @@ components:
       - $ref: '#/components/schemas/Sale'
       description: Write payload for partial update (PATCH) of a Sale document. All
         fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
+    Site:
+      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 site sub-collections.
+        name:
+          type: string
+          description: Human-readable site name shown in dashboards.
+        description:
+          description: Optional freeform description.
+          type:
+          - string
+          - 'null'
+        status:
+          $ref: '#/components/schemas/SiteStatus'
+          description: Lifecycle status (D41). 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
+          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 Site.
+                type: boolean
+            required:
+            - label
+            - url
+            - type
+            additionalProperties: false
+            description: Deployment link entry embedded on Site.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 site.
+        analyticsEnabled:
+          type: boolean
+          description: Feature flag — when false, clients should not emit analytics
+            events for this site.
+        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 Site.
+            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 site (via `Order.siteId`,
+                D43).
+            lastEventAt:
+              $ref: '#/components/schemas/FirestoreTimestamp'
+              description: Timestamp of the most recent analytics event seen for this
+                site.
+          required:
+          - totalEvents
+          - totalPageViews
+          - totalSessions
+          - totalOrders
+          additionalProperties: false
+      required:
+      - companyId
+      - name
+      - status
+      - deploymentLinks
+      - createdBy
+      - analyticsEnabled
+      additionalProperties: false
+      description: 'Site model (D41 / ING-304). Collection: companies/{companyId}/sites/{siteId}.
+        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.'
+    SiteCreate:
+      allOf:
+      - $ref: '#/components/schemas/Site'
+      description: Write payload for creating a new Site 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
+    SiteUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Site'
+      description: Write payload for partial update (PATCH) of a Site document. All
+        fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
+    SitePayment:
+      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.
+        siteId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+        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 site (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
+      - siteId
+      - contact
+      - sessionId
+      - transactionId
+      - tier
+      - amount
+      - currency
+      - paidAt
+      additionalProperties: false
+      description: 'SitePayment model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/payments/{paymentId}.
+        Immutable append-only transaction ledger. Distinct from AllowedUser (access
+        state) and CustomerPayment (D22 — customer-level billing).'
+    SitePaymentCreate:
+      allOf:
+      - $ref: '#/components/schemas/SitePayment'
+      description: Write payload for creating a new SitePayment document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - siteId
+      - contact
+      - sessionId
+      - transactionId
+      - tier
+      - amount
+      - currency
+      - paidAt
+    SitePaymentUpdate:
+      allOf:
+      - $ref: '#/components/schemas/SitePayment'
+      description: Write payload for partial update (PATCH) of a SitePayment document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
     Ticket:
       type: object
       properties: