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

package/data/static/llms.txt

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

package/data/static/openapi.yaml

@@ -204,6 +204,30 @@ components:
       - ARCHIVED
       description: Lifecycle status for a Site (D41). Drives whether the site is reachable
         and whether analytics/payments flow.
+    StocktakeFrequency:
+      type: string
+      enum:
+      - DAILY
+      - WEEKLY
+      - MONTHLY
+      - AD_HOC
+      description: Recurrence cadence of a Stocktake session (GH#29 §4).
+    StocktakeItemStatus:
+      type: string
+      enum:
+      - PENDING
+      - COUNTED
+      - VERIFIED
+      - ADJUSTED
+      description: Per-line workflow status inside a Stocktake (GH#29 §4, audit Q21).
+    StocktakeStatus:
+      type: string
+      enum:
+      - PENDING
+      - IN_PROGRESS
+      - COMPLETED
+      - CANCELLED
+      description: Lifecycle status of a Stocktake session (GH#29 §3, §4).
     TicketStatus:
       type: string
       enum:
@@ -3895,6 +3919,337 @@ components:
       description: Write payload for partial update (PATCH) of a SitePayment document.
         All fields optional. Fields marked `readOnly` or `x-immutable` must not be
         sent.
+    Stocktake:
+      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. Tenant scope.
+        stocktakeNumber:
+          type: string
+          description: Human-readable session number, e.g. "STK-2026-001". Embedded
+            as `referenceNumber` on the StockMovement rows the session emits, so the
+            ledger remains traceable to the originating stocktake.
+        stocktakeDate:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: Effective date of the count. Distinct from createdAt; can be
+            backdated.
+          x-note: The date the count is FOR. Can be backdated (stocktakeDate < createdAt)
+            — analytics buckets by stocktakeDate for "what period was counted" and
+            by completedAt for "when adjustments hit the ledger" (GH#29 Q24).
+        warehouseId:
+          description: FK → Warehouse document ID. Null = whole-company stocktake
+            (no warehouse partition).
+          anyOf:
+          - type: string
+          - type: 'null'
+        frequency:
+          anyOf:
+          - $ref: '#/components/schemas/StocktakeFrequency'
+          - type: 'null'
+          description: Recurrence cadence. Optional — leave unset for ad-hoc sessions,
+            or set to indicate this stocktake is part of a recurring schedule.
+          x-note: Optional today (dashboard does not currently track recurrence).
+            Frequency is a property of the record, not a separate type — a daily stocktake
+            is a Stocktake with frequency=DAILY, not a distinct DailyStocktake model.
+            If the session was emitted from a recurring schedule, set Stocktake.scheduledStocktakeId;
+            ad-hoc sessions leave it null.
+          x-see:
+            issues:
+            - gh#29
+        scheduledStocktakeId:
+          description: FK to a recurring stocktake schedule, if this session was emitted
+            from one. Null for ad-hoc sessions.
+          anyOf:
+          - type: string
+          - type: 'null'
+        status:
+          $ref: '#/components/schemas/StocktakeStatus'
+          description: Lifecycle status. Transitions PENDING → IN_PROGRESS → COMPLETED
+            are server-owned (GH#29 §3 / Q25).
+          x-note: PENDING = session created, no items counted yet. IN_PROGRESS = at
+            least one item has been counted. COMPLETED = all items counted and the
+            session was closed; on this transition the server emits one StockMovement(type=INVENTORY)
+            per non-zero delta. CANCELLED = session abandoned without applying adjustments.
+            Status transitions PENDING → IN_PROGRESS → COMPLETED are server-owned
+            (Q25) — clients PATCH item status; the server transitions session status
+            to avoid the concurrent-edit race documented in stockService.ts:1671.
+          x-see:
+            issues:
+            - gh#29
+          x-when: Server-managed. Clients write item updates; the trigger transitions
+            session status.
+        adjustmentsApplied:
+          type: boolean
+          x-note: Records whether the COMPLETED transition actually mutated stock
+            or was record-only. The dashboard's completeInventory(applyAdjustments)
+            flag was not persisted; this field closes that gap (GH#29 audit Q22).
+          description: True if completing the session actually emitted StockMovement
+            adjustments. False for record-only counts.
+        notes:
+          description: Free-text session-level notes.
+          anyOf:
+          - type: string
+          - type: 'null'
+        totalItemsCount:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          x-note: Server-derived. Recomputed by trigger on each StocktakeItem write;
+            not safe to write client-side under concurrent edits (GH#29 audit Q23).
+          description: (Read-only) Total number of StocktakeItem rows under this session.
+        totalDiscrepancies:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          readOnly: true
+          x-note: Server-derived = sum of |item.delta| across COUNTED items. Updated
+            by trigger.
+          description: (Read-only) Sum of absolute deltas across counted items.
+        totalDeltaValue:
+          type: number
+          readOnly: true
+          x-note: Server-derived = sum of (item.delta × item.costPerUnit) across COUNTED
+            items, in XOF integer minor units (D18). Updated by trigger.
+          description: (Read-only) Net valuation impact of the count, in XOF integer
+            minor units.
+        startedAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: When the counting session physically opened. Typically equal
+            to createdAt for ad-hoc sessions.
+        completedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          x-note: Server-set on transition to COMPLETED. Distinct from stocktakeDate
+            (the period counted) — analytics buckets by completedAt to answer "when
+            did the ledger hit?".
+          description: (Read-only) When the session transitioned to COMPLETED.
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User UID who created the session.
+        createdByName:
+          type: string
+          denormalized: true
+          x-note: Read-time hint snapshot of the creator's display name (GH#29 §3
+            / Q10).
+          description: (Denormalized) Snapshot of the creator's display name at session
+            creation.
+        completedBy:
+          readOnly: true
+          description: (Read-only) FK → User UID who completed the session, set by
+            server on COMPLETED.
+          anyOf:
+          - type: string
+          - type: 'null'
+        completedByName:
+          denormalized: true
+          x-note: Read-time hint snapshot of the completer's display name (GH#29 §3
+            / Q10).
+          description: (Denormalized) Snapshot of the completer's display name.
+          anyOf:
+          - type: string
+          - type: 'null'
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+      required:
+      - companyId
+      - stocktakeNumber
+      - stocktakeDate
+      - status
+      - adjustmentsApplied
+      - totalItemsCount
+      - totalDiscrepancies
+      - totalDeltaValue
+      - startedAt
+      - createdBy
+      - createdByName
+      additionalProperties: false
+      description: 'Stocktake (GH#29 §4). Collection: companies/{companyId}/stocktakes/{stocktakeId}.
+        A recorded session of physically counting all SKUs at a point in time. Replaces
+        the dashboard''s Inventory model; items live in a sub-collection (replaces
+        InventoryItem[] embedded array); InventoryEvolution is dropped — derivable
+        from the sub-collection. Status transitions and aggregate fields (totalItemsCount/Discrepancies/totalDeltaValue)
+        are server-owned per GH#29 §3.'
+    StocktakeCreate:
+      allOf:
+      - $ref: '#/components/schemas/Stocktake'
+      description: Write payload for creating a new Stocktake document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - stocktakeNumber
+      - stocktakeDate
+      - status
+      - adjustmentsApplied
+      - startedAt
+      - createdBy
+      - createdByName
+    StocktakeUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Stocktake'
+      description: Write payload for partial update (PATCH) of a Stocktake document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    StocktakeItem:
+      type: object
+      properties:
+        stockItemId:
+          type: string
+          description: FK → StockItem document ID. Doubles as the item document ID.
+        stockItemName:
+          type: string
+          denormalized: true
+          x-note: Read-time hint snapshot of StockItem.name. Authoritative value lives
+            at the StockItem record; do not refresh on rename — the historical name
+            at session time is what the auditor wrote (GH#29 §3 / Q10).
+          description: (Denormalized) Snapshot of StockItem.name at session time.
+        theoreticalQuantity:
+          type: number
+          x-immutable: true
+          description: (Immutable) System belief at session start, snapshotted when
+            this item row was created.
+        actualQuantity:
+          description: Physical count entered by the counter. Null until counted;
+            set when the line moves to status COUNTED.
+          anyOf:
+          - type: number
+          - type: 'null'
+        delta:
+          type: number
+          readOnly: true
+          x-note: Server-derived = actualQuantity − theoreticalQuantity. Recomputed
+            on every actualQuantity write; null/zero before counting.
+          description: (Read-only) Signed difference between actual and theoretical.
+            Drives the StockMovement(type=INVENTORY) emitted on session COMPLETED.
+        unit:
+          type: string
+          x-immutable: true
+          description: (Immutable) Snapshot of StockItem.unit at session start. Locks
+            the unit against later catalog changes.
+        costPerUnit:
+          type: number
+          x-immutable: true
+          x-note: Snapshot at session time — locks valuation against future cost changes.
+            Lock to XOF integer minor units per D18 (GH#29 Q16).
+          description: (Immutable) Snapshot of StockItem.costPerUnit at session start,
+            in XOF integer minor units.
+        totalValue:
+          type: number
+          readOnly: true
+          x-note: Server-derived = actualQuantity × costPerUnit. Recomputed when actualQuantity
+            is written.
+          description: (Read-only) Per-line valuation in XOF integer minor units.
+        status:
+          $ref: '#/components/schemas/StocktakeItemStatus'
+          description: Per-line workflow status. Server transitions ADJUSTED on parent
+            COMPLETED.
+          x-note: PENDING = line not yet counted. COUNTED = a counter recorded actualQuantity.
+            VERIFIED = a second pair of eyes signed off (verifiedBy fields populated;
+            Q21 — kept nullable until tenants opt into stricter QA via policy). ADJUSTED
+            = the resulting StockMovement was emitted (server-set on Stocktake.status
+            → COMPLETED).
+          x-see:
+            issues:
+            - gh#29
+        notes:
+          description: Optional per-line note from the counter (e.g. "damaged carton,
+            3 unsellable").
+          anyOf:
+          - type: string
+          - type: 'null'
+        countedBy:
+          description: UID of the staff member who entered actualQuantity.
+          anyOf:
+          - type: string
+          - type: 'null'
+        countedByName:
+          denormalized: true
+          x-note: Read-time hint snapshot of the counter's display name (GH#29 §3
+            / Q10).
+          description: (Denormalized) Snapshot of the counter's display name at count
+            time.
+          anyOf:
+          - type: string
+          - type: 'null'
+        countedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: When the line was counted.
+        verifiedBy:
+          description: UID of a second staff member who verified the count. Nullable
+            per GH#29 Q21.
+          anyOf:
+          - type: string
+          - type: 'null'
+        verifiedByName:
+          denormalized: true
+          x-note: Read-time hint snapshot of the verifier's display name (GH#29 §3
+            / Q10).
+          description: (Denormalized) Snapshot of the verifier's display name.
+          anyOf:
+          - type: string
+          - type: 'null'
+        verifiedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: When the line was verified, if a second-eye flow was used.
+      required:
+      - stockItemId
+      - stockItemName
+      - theoreticalQuantity
+      - delta
+      - unit
+      - costPerUnit
+      - totalValue
+      - status
+      additionalProperties: false
+      description: 'StocktakeItem (GH#29 §4). Sub-collection path: companies/{companyId}/stocktakes/{stocktakeId}/items/{stockItemId}.
+        Replaces the embedded `InventoryItem[]` array on the dashboard model. Server
+        emits one StockMovement(type=INVENTORY) per non-zero delta when the parent
+        Stocktake transitions to COMPLETED.'
+    StocktakeItemCreate:
+      allOf:
+      - $ref: '#/components/schemas/StocktakeItem'
+      description: Write payload for creating a new StocktakeItem document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - stockItemId
+      - stockItemName
+      - theoreticalQuantity
+      - unit
+      - costPerUnit
+      - status
+    StocktakeItemUpdate:
+      allOf:
+      - $ref: '#/components/schemas/StocktakeItem'
+      description: Write payload for partial update (PATCH) of a StocktakeItem document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
     Ticket:
       type: object
       properties: