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

package/data/static/openapi.yaml

@@ -51,6 +51,16 @@ components:
       - COMPLETED_MIXED
       description: Booking lifecycle status. COMPLETED_MIXED = some sessions completed,
         others cancelled/no-show.
+    ContractStatus:
+      type: string
+      enum:
+      - DRAFT
+      - ACTIVE
+      - COMPLETED
+      - TERMINATED
+      description: Lifecycle status of a Contract. DRAFT = not yet signed. ACTIVE
+        = in force. COMPLETED = all milestones paid and obligations met. TERMINATED
+        = ended early by either party.
     CustomerPaymentStatus:
       type: string
       enum:
@@ -120,6 +130,14 @@ components:
       - BONUS
       - REFUND
       description: Loyalty point transaction type (D07). SCREAMING_SNAKE past tense.
+    MilestoneStatus:
+      type: string
+      enum:
+      - PENDING
+      - INVOICED
+      - PAID
+      description: Status of a ContractMilestone (#17). PENDING = created, not yet
+        invoiced. INVOICED = invoice issued, awaiting payment. PAID = payment received.
     NotificationChannel:
       type: string
       enum:
@@ -309,8 +327,9 @@ components:
       enum:
       - cmz
       - val
-      description: Human-readable WABA label identifying which Meta business number
-        received the message (GH#36).
+      description: WABA label identifying which Meta Business Account sent/received
+        the message. cmz = Chez Miss Zahoui sender; val = Valets sender. See WhatsApp
+        platform constraints doc (#50).
     WhatsappButtonSubType:
       type: string
       enum:
@@ -1022,18 +1041,22 @@ components:
           - 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.
+          anyOf:
+          - $ref: '#/components/schemas/AppStatus'
+          - type: 'null'
+          x-note: Real Firestore documents may be missing this field on pre-backfill
+            records (#26). Treat absent as ACTIVE. A backfill script will populate
+            status=ACTIVE on all existing documents; once confirmed, this field will
+            be promoted to required.
+          x-when: Written by operators via dashboard or by server triggers (expiration).
+            Clients must not use server-side `where(status == ACTIVE)` until backfill
+            is complete — filter client-side instead, treating absent as ACTIVE.
+          description: Lifecycle status (D41/D44). Optional pending backfill of pre-existing
+            records (#26) — treat absent as ACTIVE. Clients filter by ACTIVE.
           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:
@@ -1154,7 +1177,6 @@ components:
       required:
       - companyId
       - name
-      - status
       - deploymentLinks
       - createdBy
       - analyticsEnabled
@@ -1172,7 +1194,6 @@ components:
       required:
       - companyId
       - name
-      - status
       - deploymentLinks
       - createdBy
       - analyticsEnabled
@@ -1882,6 +1903,156 @@ components:
       description: 'BookingVersion model (D18). Collection: companies/{companyId}/bookings/{bookingId}/versions/{versionId}.
         Server-owned audit trail written by Firebase trigger on every Booking mutation.
         Captures writes from all clients.'
+    Contract:
+      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.
+        payeeId:
+          type: string
+          x-immutable: true
+          description: '(Immutable) FK → Payee document ID. Full Payee model tracked
+            in #20.'
+        title:
+          type: string
+          description: Contract title or reference name shown in dashboards.
+        description:
+          description: Optional freeform description of the contract scope.
+          type:
+          - string
+          - 'null'
+        status:
+          $ref: '#/components/schemas/ContractStatus'
+          description: Contract lifecycle status (#14). Query by ACTIVE — do not use
+            an isActive boolean.
+        currency:
+          type: string
+          const: XOF
+          description: Currency code. Locked to XOF (#18). Multi-currency support
+            requires a deliberate schema version bump.
+        totalAmount:
+          type: number
+          description: Total contract value (XOF).
+        startDate:
+          type: string
+          description: Contract start date (ISO 8601 YYYY-MM-DD).
+        endDate:
+          description: Contract end date (ISO 8601 YYYY-MM-DD). Absent for open-ended
+            contracts.
+          type:
+          - string
+          - 'null'
+        milestones:
+          description: Ordered list of payment milestones. Embedded in the contract
+            document (#17).
+          type:
+          - array
+          - 'null'
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+                description: Client-generated milestone ID (UUID or slug). Unique
+                  within the contract.
+              title:
+                type: string
+                description: Milestone description or deliverable name.
+              amount:
+                type: number
+                description: Amount due at this milestone (XOF).
+              dueDate:
+                description: ISO 8601 date string (YYYY-MM-DD) when the milestone
+                  is due. OVERDUE is derived at read time from dueDate — not stored.
+                type: string
+              status:
+                $ref: '#/components/schemas/MilestoneStatus'
+                x-note: Existing Firestore documents may have lowercase values (pending,
+                  invoiced, paid) from before this enum was introduced (#17). Normalize
+                  on read or via migration script.
+                description: Milestone payment status (#17). OVERDUE is derived at
+                  read time from dueDate, not stored.
+              invoicedAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: When the invoice was issued for this milestone.
+              paidAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: When payment was received for this milestone.
+              notes:
+                description: Optional notes for this milestone.
+                type: string
+            required:
+            - id
+            - title
+            - amount
+            - status
+            additionalProperties: false
+            description: ContractMilestone — embedded sub-object on Contract (#17).
+              Not a separate collection.
+        notes:
+          description: Optional internal notes.
+          type:
+          - string
+          - 'null'
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created the contract.
+        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.
+      required:
+      - companyId
+      - payeeId
+      - title
+      - status
+      - currency
+      - totalAmount
+      - startDate
+      - createdBy
+      additionalProperties: false
+      description: 'Contract model (GH#14/#17/#18). Collection: companies/{companyId}/contracts/{contractId}.
+        Service/supplier contract between a company and a Payee. No isActive field
+        — query by status. Currency locked to XOF. Milestones use MilestoneStatus
+        enum (no stored OVERDUE).'
+    ContractCreate:
+      allOf:
+      - $ref: '#/components/schemas/Contract'
+      description: Write payload for creating a new Contract document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - payeeId
+      - title
+      - status
+      - currency
+      - totalAmount
+      - startDate
+      - createdBy
+    ContractUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Contract'
+      description: Write payload for partial update (PATCH) of a Contract document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
     Customer:
       type: object
       properties:
@@ -3781,6 +3952,17 @@ components:
           type: string
           readOnly: true
           description: (Read-only) Server-generated order number.
+        followUpUrl:
+          x-note: Standardized casing is followUpUrl (not followUpURL). Mobile legacy
+            code reads both casings for backward compat but writes followUpUrl going
+            forward (#6).
+          x-when: 'Used by mobile to generate QR codes on printed receipts. If absent,
+            the mobile app derives a deterministic fallback: https://zahoui.web.app/reviews?orderNumber={orderNumber}.'
+          description: 'Optional URL for receipt QR code / post-order follow-up. Canonical
+            casing: followUpUrl (#6).'
+          type:
+          - string
+          - 'null'
         status:
           $ref: '#/components/schemas/OrderStatus'
           description: Core lifecycle status (D34, MIG-11). See OrderStatus enum for
@@ -4315,6 +4497,235 @@ components:
       description: Write payload for partial update (PATCH) of a OrderItem document.
         All fields optional. Fields marked `readOnly` or `x-immutable` must not be
         sent.
+    OutboundPayment:
+      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.
+        payeeId:
+          type: string
+          x-immutable: true
+          description: '(Immutable) FK → Payee document ID. Full Payee model tracked
+            in #20.'
+        contractId:
+          x-immutable: true
+          description: (Immutable, Optional) FK → Contract document ID. Absent for
+            ad-hoc payments outside a formal contract.
+          type:
+          - string
+          - 'null'
+        amount:
+          type: number
+          description: Amount paid (XOF).
+        currency:
+          type: string
+          const: XOF
+          description: Currency code. Locked to XOF — consistent with Contract and
+            CustomerPayment.
+        method:
+          $ref: '#/components/schemas/PaymentMethod'
+          description: Payment method used (e.g. BANK_TRANSFER, MOBILE_MONEY, CHECK).
+        reference:
+          description: Optional payment reference — bank transaction number, check
+            number, Wave ref, etc.
+          type:
+          - string
+          - 'null'
+        paidAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: When the payment was made.
+        notes:
+          description: Optional internal notes.
+          type:
+          - string
+          - 'null'
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who recorded the payment.
+        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.
+      required:
+      - companyId
+      - payeeId
+      - amount
+      - currency
+      - method
+      - paidAt
+      - createdBy
+      additionalProperties: false
+      description: 'OutboundPayment (GH#15). Collection: companies/{companyId}/outboundPayments/{paymentId}.
+        Single outbound transfer to a Payee. Canonical name chosen over SupplierPayment/VendorPayment
+        — direction-based, agnostic of payee type. Currency locked to XOF.'
+    OutboundPaymentCreate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPayment'
+      description: Write payload for creating a new OutboundPayment document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - payeeId
+      - amount
+      - currency
+      - method
+      - paidAt
+      - createdBy
+    OutboundPaymentUpdate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPayment'
+      description: Write payload for partial update (PATCH) of a OutboundPayment document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    OutboundPaymentAllocation:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        outboundPaymentId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → OutboundPayment document ID (parent).
+        expenseId:
+          type: string
+          x-immutable: true
+          description: '(Immutable) FK → Expense document ID. Full Expense model tracked
+            in #20.'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Denormalized for collection-group
+            queries.
+        amount:
+          type: number
+          description: Amount of this payment allocated to the referenced expense
+            (XOF).
+        notes:
+          description: Optional notes about this allocation.
+          type:
+          - string
+          - 'null'
+        allocatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When this allocation was recorded.
+      required:
+      - outboundPaymentId
+      - expenseId
+      - companyId
+      - amount
+      additionalProperties: false
+      description: 'OutboundPaymentAllocation (GH#15). Subcollection: companies/{companyId}/outboundPayments/{paymentId}/allocations/{allocationId}.
+        Links an OutboundPayment to an Expense. Supports partial and multi-expense
+        allocations.'
+    OutboundPaymentAllocationCreate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPaymentAllocation'
+      description: Write payload for creating a new OutboundPaymentAllocation document.
+        Fields marked `readOnly` are server-set and must not be included. Fields marked
+        `x-immutable` may be set once at creation.
+      required:
+      - outboundPaymentId
+      - expenseId
+      - companyId
+      - amount
+    OutboundPaymentAllocationUpdate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPaymentAllocation'
+      description: Write payload for partial update (PATCH) of a OutboundPaymentAllocation
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
+    PaymentWebhookEndpoint:
+      type: object
+      properties:
+        token:
+          type: string
+          x-immutable: true
+          description: (Immutable) base64url-encoded 24-byte random token. Also the
+            Firestore document ID and the URL path segment.
+        company:
+          type: string
+          x-immutable: true
+          description: (Immutable) Company slug (e.g. gerko_studios). Identifies the
+            tenant that owns this endpoint.
+        provider:
+          type: string
+          enum:
+          - wave
+          - jeko
+          x-immutable: true
+          description: (Immutable) Payment provider whose webhooks this endpoint accepts.
+        secret:
+          type: string
+          x-note: Provider-specific webhook signing secret. Used to verify HMAC-SHA256
+            signatures on inbound payloads. Never expose to clients.
+          readOnly: true
+          description: Webhook signing secret for HMAC verification. Backend-only
+            — never returned to dashboard or mobile clients.
+        active:
+          type: boolean
+          description: Whether this endpoint is currently active. Inactive endpoints
+            reject incoming webhooks.
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When this endpoint was provisioned.
+      required:
+      - token
+      - company
+      - provider
+      - secret
+      - active
+      additionalProperties: false
+      x-internal: true
+      description: 'PaymentWebhookEndpoint (GH#41). Collection: payment_webhook_endpoints/{token}.
+        Top-level, not tenant-scoped. Provisioned by superadmin; used by the backend
+        to verify inbound payment webhooks from Wave and Jeko. The delivery log collection
+        (raw webhook payloads + verification outcomes) is tracked in GH#41 — shape
+        TBD.'
+    PaymentWebhookEndpointCreate:
+      allOf:
+      - $ref: '#/components/schemas/PaymentWebhookEndpoint'
+      description: Write payload for creating a new PaymentWebhookEndpoint document.
+        Fields marked `readOnly` are server-set and must not be included. Fields marked
+        `x-immutable` may be set once at creation.
+      required:
+      - token
+      - company
+      - provider
+      - active
+    PaymentWebhookEndpointUpdate:
+      allOf:
+      - $ref: '#/components/schemas/PaymentWebhookEndpoint'
+      description: Write payload for partial update (PATCH) of a PaymentWebhookEndpoint
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
     Sale:
       type: object
       properties:
@@ -5213,6 +5624,12 @@ components:
             received the message.
         waba:
           $ref: '#/components/schemas/WabaLabel'
+          x-note: 'cmz = "IngenX - Chez Miss Zahoui", phone number ID 446424085225188,
+            used for chez_miss_zahoui_* companies. val = "IngenX - Valets", phone
+            number ID 425582173979125, used for all other companies. Templates are
+            approved at WABA level — if cmz and val share a WABA ID, all templates
+            are available to both. Routing logic: functions/src/orders/order.ts#isSender2Company.
+            See messaging/whatsapp-platform-constraints (#50).'
           description: (Immutable) Human-readable WABA label (cmz | val). See WabaLabel
             enum.
           x-immutable: true
@@ -5415,10 +5832,26 @@ components:
         to:
           type: string
           x-immutable: true
-          description: (Immutable) Recipient phone number in E.164 format. Must match
-            the inbound `from` for the same conversation.
+          x-note: 'This is the Meta wa_id (digits only, no leading +), NOT a literal
+            E.164 string. Meta normalizes phone numbers in non-obvious ways (e.g.
+            +2250777471485 → wa_id 22577471485, dropping the trunk zero). The only
+            reliable source is Meta''s contacts[].wa_id from the send response — do
+            not derive from E.164 by stripping + alone. The dashboard conversational
+            sends and the whatsapp-server OTP path both use the wa_id form. Confirmed
+            in prod: ING-368.'
+          x-when: Set at enqueue time to the recipient's Meta wa_id. Use inbound WhatsappInboundMessage.from
+            (also wa_id) as the join key for the conversation thread.
+          description: (Immutable) Recipient Meta wa_id — digits only, no leading
+            + (e.g. 22577471485). Equal to the inbound `from` for the same conversation.
+            NOT literal E.164; see x-note (#54).
         waba:
           $ref: '#/components/schemas/WabaLabel'
+          x-note: 'cmz = "IngenX - Chez Miss Zahoui", phone number ID 446424085225188,
+            used for chez_miss_zahoui_* companies. val = "IngenX - Valets", phone
+            number ID 425582173979125, used for all other companies. Templates are
+            approved at WABA level — if cmz and val share a WABA ID, all templates
+            are available to both. Routing logic: functions/src/orders/order.ts#isSender2Company.
+            See messaging/whatsapp-platform-constraints (#50).'
           description: (Immutable) WABA that will send the message. Mirrors inbound
             `waba`.
           x-immutable: true
@@ -5504,6 +5937,9 @@ components:
             after (sent → delivered → read, or failed).
         wamid:
           readOnly: true
+          x-note: Useful for audit and dedup. Does NOT enable reply-threading for
+            template messages — Meta silently ignores context.message_id on templates.
+            Threading only works for kind=text within the 24-hour service window (#50).
           description: (Read-only) WhatsApp message ID returned by Meta once the backend
             sends. Absent while queued or on failure.
           type:
@@ -5583,6 +6019,12 @@ components:
           - 'null'
         waba:
           $ref: '#/components/schemas/WabaLabel'
+          x-note: 'cmz = "IngenX - Chez Miss Zahoui", phone number ID 446424085225188,
+            used for chez_miss_zahoui_* companies. val = "IngenX - Valets", phone
+            number ID 425582173979125, used for all other companies. Templates are
+            approved at WABA level — if cmz and val share a WABA ID, all templates
+            are available to both. Routing logic: functions/src/orders/order.ts#isSender2Company.
+            See messaging/whatsapp-platform-constraints (#50).'
           description: (Read-only) WABA label this template is approved on. Templates
             are WABA-scoped. Mirrors WhatsappOutboundMessage.waba.
           readOnly: true