sinfactura-types 1.10.433 → 1.10.435

package/dist/cjs/cycleCount.js

@@ -127,6 +127,11 @@ exports.isOverCycleCountToleranceRule = isOverCycleCountToleranceRule;
  * - `CYCLE_COUNT_TOLERANCE_EXCEEDED` · 403 — a finalise with at least one
  *   over-tolerance line, from a caller who is neither ADMIN nor MANAGER. The
  *   session stays `open` and NO stock moved.
+ * - `CYCLE_COUNT_LINES_UNCOUNTED` · 409 — a finalise of a session with at least
+ *   one line carrying neither `countedAt` nor `skippedAt`; `data.productIds`
+ *   names those products. Any role, and checked BEFORE the tolerance gate, so a
+ *   caller gets this rather than the 403. The session stays `open` and NO stock
+ *   moved: count the lines, or skip them, and finalise again.
  * - `CYCLE_COUNT_ID_UNUSABLE` · 500 — the minted id is not a legal `stocktakeId`.
  *   Unreachable while the mint is `STK` + digits; published anyway because a
  *   consumer that leaves it unmapped would show an operator an internal sentence.
@@ -187,6 +192,9 @@ exports.CYCLE_COUNT_ERROR_CODES = [
     // `main` rather than in either PR's own gate.
     'CYCLE_COUNT_CONTENT_CONFLICT',
     'CYCLE_COUNT_TOLERANCE_EXCEEDED',
+    // Finalise refuses a line that is neither counted nor skipped rather than
+    // applying it as counted 0; `data.productIds` names the products.
+    'CYCLE_COUNT_LINES_UNCOUNTED',
     'CYCLE_COUNT_ID_UNUSABLE',
     'ROLE_FORBIDDEN',
     'VALIDATION_FAILED',

package/dist/cjs/serviceOrder.js

@@ -118,7 +118,13 @@ exports.SERVICE_TERMINAL_STATUSES = [
  * ⚠️ **`pending_receipt` is entered at intake and never re-entered.** It is
  * absent from every other row's list on purpose: equipment that has arrived
  * cannot un-arrive, and a ticket cannot be walked back to "not here yet" to
- * hide that it was received. That is the only new constraint this table adds.
+ * hide that it was received.
+ *
+ * ⚠️ **`on_site` is entered at intake, or from `pending_receipt` only.** The
+ * second edge is how an operator moves a visit ticket opened before `on_site`
+ * existed; nothing moves one automatically. Its only exit is `in_shop` — the
+ * technician bringing the equipment in. `returned`/`disposed` are unreachable
+ * from it because the shop never held what they would record handing back.
  *
  * ⚠️ **`returned` and `disposed` are NOT terminal, deliberately.** Custody is a
  * statement about physical fact, not a workflow, and the operator UI presents
@@ -130,7 +136,8 @@ exports.SERVICE_TERMINAL_STATUSES = [
  * about where someone else's property is.
  */
 exports.SERVICE_CUSTODY_TRANSITIONS = {
-    pending_receipt: ['in_shop'],
+    pending_receipt: ['in_shop', 'on_site'],
+    on_site: ['in_shop'],
     in_shop: ['returned', 'disposed'],
     returned: ['in_shop', 'disposed'],
     disposed: ['in_shop', 'returned'],

package/dist/cycleCount.d.ts

@@ -421,6 +421,11 @@ declare global {
         /**
          * What the operator physically counted.
          *
+         * ⚠️ Only meaningful once `countedAt` is set. A line with neither
+         * `countedAt` nor `skippedAt` is UNCOUNTED whatever this holds — a fresh
+         * `mode: 'start'` line carries `0` here — and finalise refuses the whole
+         * session `409 CYCLE_COUNT_LINES_UNCOUNTED` rather than read it as counted 0.
+         *
          * ⚠️ Still required on a SKIPPED line (`skippedAt` set), where it carries
          * no meaning: send `0`. Finalise, the tolerance gate and every variance
          * ignore it there — a skipped line is never read as "counted zero".
@@ -438,7 +443,13 @@ declare global {
         lotId?: string;
         /** Why the line differs. ⚠️ Never personal data — it rides into an un-scrubbed, TTL-less row. */
         note?: string;
-        /** Unix ms this line was captured. Its distance from `finalizedAt` is how stale `systemQuantity` is. */
+        /**
+         * Unix ms this line was captured. Its distance from `finalizedAt` is how stale `systemQuantity` is.
+         *
+         * ⚠️ It is also what marks the line COUNTED: a line with neither this nor
+         * `skippedAt` is uncounted, and finalise refuses the session
+         * `409 CYCLE_COUNT_LINES_UNCOUNTED` until every line has one or the other.
+         */
         countedAt?: number;
         /**
          * Unix ms the operator marked this line UNREACHABLE (a locked case, a
@@ -548,6 +559,11 @@ export declare const isOverCycleCountToleranceRule: (input: {
  * - `CYCLE_COUNT_TOLERANCE_EXCEEDED` · 403 — a finalise with at least one
  *   over-tolerance line, from a caller who is neither ADMIN nor MANAGER. The
  *   session stays `open` and NO stock moved.
+ * - `CYCLE_COUNT_LINES_UNCOUNTED` · 409 — a finalise of a session with at least
+ *   one line carrying neither `countedAt` nor `skippedAt`; `data.productIds`
+ *   names those products. Any role, and checked BEFORE the tolerance gate, so a
+ *   caller gets this rather than the 403. The session stays `open` and NO stock
+ *   moved: count the lines, or skip them, and finalise again.
  * - `CYCLE_COUNT_ID_UNUSABLE` · 500 — the minted id is not a legal `stocktakeId`.
  *   Unreachable while the mint is `STK` + digits; published anyway because a
  *   consumer that leaves it unmapped would show an operator an internal sentence.
@@ -595,5 +611,5 @@ export declare const isOverCycleCountToleranceRule: (input: {
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.
  */
-export declare const CYCLE_COUNT_ERROR_CODES: readonly ["CYCLE_COUNT_NOT_FOUND", "CYCLE_COUNT_NOT_OPEN", "CYCLE_COUNT_ILLEGAL_TRANSITION", "CYCLE_COUNT_VERSION_CONFLICT", "CYCLE_COUNT_CONTENT_CONFLICT", "CYCLE_COUNT_TOLERANCE_EXCEEDED", "CYCLE_COUNT_ID_UNUSABLE", "ROLE_FORBIDDEN", "VALIDATION_FAILED", "INVALID_CURSOR", "PRODUCT_NOT_FOUND", "STOCK_ADJUSTMENT_RACED", "CYCLE_COUNT_SCOPE_EMPTY", "CYCLE_COUNT_SCOPE_OVER_CAP", "CYCLE_COUNT_SCOPE_INCOMPLETE", "CYCLE_COUNT_SCOPE_CHANGED", "CYCLE_COUNT_START_KEY_REQUIRED", "CYCLE_COUNT_BASELINE_LOCKED", "CYCLE_COUNT_DEPOSITO_OVER_CAP", "WAREHOUSE_NOT_FOUND", "NO_PRIMARY_WAREHOUSE"];
+export declare const CYCLE_COUNT_ERROR_CODES: readonly ["CYCLE_COUNT_NOT_FOUND", "CYCLE_COUNT_NOT_OPEN", "CYCLE_COUNT_ILLEGAL_TRANSITION", "CYCLE_COUNT_VERSION_CONFLICT", "CYCLE_COUNT_CONTENT_CONFLICT", "CYCLE_COUNT_TOLERANCE_EXCEEDED", "CYCLE_COUNT_LINES_UNCOUNTED", "CYCLE_COUNT_ID_UNUSABLE", "ROLE_FORBIDDEN", "VALIDATION_FAILED", "INVALID_CURSOR", "PRODUCT_NOT_FOUND", "STOCK_ADJUSTMENT_RACED", "CYCLE_COUNT_SCOPE_EMPTY", "CYCLE_COUNT_SCOPE_OVER_CAP", "CYCLE_COUNT_SCOPE_INCOMPLETE", "CYCLE_COUNT_SCOPE_CHANGED", "CYCLE_COUNT_START_KEY_REQUIRED", "CYCLE_COUNT_BASELINE_LOCKED", "CYCLE_COUNT_DEPOSITO_OVER_CAP", "WAREHOUSE_NOT_FOUND", "NO_PRIMARY_WAREHOUSE"];
 export type CycleCountErrorCode = (typeof CYCLE_COUNT_ERROR_CODES)[number];

package/dist/cycleCount.js

@@ -122,6 +122,11 @@ export const isOverCycleCountToleranceRule = (input, tolerancePercent) => {
  * - `CYCLE_COUNT_TOLERANCE_EXCEEDED` · 403 — a finalise with at least one
  *   over-tolerance line, from a caller who is neither ADMIN nor MANAGER. The
  *   session stays `open` and NO stock moved.
+ * - `CYCLE_COUNT_LINES_UNCOUNTED` · 409 — a finalise of a session with at least
+ *   one line carrying neither `countedAt` nor `skippedAt`; `data.productIds`
+ *   names those products. Any role, and checked BEFORE the tolerance gate, so a
+ *   caller gets this rather than the 403. The session stays `open` and NO stock
+ *   moved: count the lines, or skip them, and finalise again.
  * - `CYCLE_COUNT_ID_UNUSABLE` · 500 — the minted id is not a legal `stocktakeId`.
  *   Unreachable while the mint is `STK` + digits; published anyway because a
  *   consumer that leaves it unmapped would show an operator an internal sentence.
@@ -182,6 +187,9 @@ export const CYCLE_COUNT_ERROR_CODES = [
     // `main` rather than in either PR's own gate.
     'CYCLE_COUNT_CONTENT_CONFLICT',
     'CYCLE_COUNT_TOLERANCE_EXCEEDED',
+    // Finalise refuses a line that is neither counted nor skipped rather than
+    // applying it as counted 0; `data.productIds` names the products.
+    'CYCLE_COUNT_LINES_UNCOUNTED',
     'CYCLE_COUNT_ID_UNUSABLE',
     'ROLE_FORBIDDEN',
     'VALIDATION_FAILED',

package/dist/serviceOrder.d.ts

@@ -132,8 +132,17 @@ declare global {
      * has not run yet. It is a starting state only: `equipmentReceived: false`
      * at intake is the one way to reach it, and NO transition leads back into
      * it, because equipment that has arrived cannot un-arrive.
+     *
+     * ⚠️ `on_site` means the work happens at the CUSTOMER's site and the shop
+     * never holds the equipment. Intake writes it for every ticket opened from a
+     * maintenance visit (`appointment`); a ticket opened before this state
+     * existed reaches it by the `pending_receipt → on_site` edit. It stays put
+     * through `ready → delivered` — the handover mints the order but records no
+     * handback, because nothing changed hands — and `abandoned_disposed` is
+     * refused, because the shop cannot dispose of property it never held. Its
+     * one exit is `in_shop`, for the technician bringing the equipment in.
      */
-    type ServiceCustody = 'pending_receipt' | 'in_shop' | 'returned' | 'disposed';
+    type ServiceCustody = 'pending_receipt' | 'on_site' | 'in_shop' | 'returned' | 'disposed';
     /** Operator-set urgency, used for Kanban ordering and SLA hints. */
     type ServicePriority = 'low' | 'normal' | 'high' | 'urgent';
     /**
@@ -745,10 +754,12 @@ declare global {
          * Custody of the customer's property, independent of `status`. This is
          * what answers "which cancelled orders still have equipment here?".
          *
-         * Two starting states, chosen at intake by `equipmentReceived`: the
-         * default `in_shop` (the customer handed the equipment over), and
-         * `pending_receipt` (the ticket was opened first — a phone booking, or a
-         * pickup that has not run). ⚠️ A `pending_receipt` row is NOT holding
+         * Three starting states. Without an `appointment`, `equipmentReceived`
+         * chooses between the default `in_shop` (the customer handed the
+         * equipment over) and `pending_receipt` (the ticket was opened first — a
+         * phone booking, or a pickup that has not run). A ticket opened from a
+         * maintenance visit starts `on_site`: the work is done where the
+         * equipment is. ⚠️ Neither `pending_receipt` nor `on_site` is holding
          * anything, so a report answering "what is on our shelves" must filter
          * to `in_shop` rather than to "not returned and not disposed".
          */
@@ -766,14 +777,16 @@ declare global {
          * than printing none.
          *
          * One field rather than `returnedAt` + `disposedAt`, because
-         * `custodyImpliedBy` moves custody on TWO terminals (`delivered` →
+         * the status machine moves custody on TWO terminals (`delivered` →
          * `returned`, `abandoned_disposed` → `disposed`) and disposing of
          * someone else's property is the event most likely to be disputed.
          * Paired with `custody` it answers both halves: which state the
          * property is in, and when it entered it.
          *
          * Server-written at all three custody writers — intake, the implied
-         * terminals, and the operator-set edit. Absent on rows written before
+         * terminals, and the operator-set edit. ⚠️ NOT re-stamped when an `on_site`
+         * ticket is delivered: custody does not move there, so the stamp keeps
+         * dating the last real move. Absent on rows written before
          * this shipped; forward-only, nothing backfills them, and a reader must
          * tolerate absence by printing no date. A backfill would be a fabricated
          * record of when someone's property changed hands.
@@ -918,10 +931,15 @@ declare global {
         dated: number;
         /** Promised completion / pickup date shown to the customer. */
         promisedAt?: number;
-        /** Unix ms the order reached `ready`. The unclaimed-equipment clock starts here. */
+        /**
+         * Unix ms the order reached `ready`. The unclaimed-equipment clock starts
+         * here — except on an `on_site` ticket, which has nothing on the shelf and
+         * is never unclaimed.
+         */
         readyAt?: number;
         /**
-         * Unix ms of each "your equipment is ready" notification. A list because
+         * Unix ms of each "your equipment is ready" notification (its on-site
+         * variant, for an `on_site` ticket, asks for no pickup). A list because
          * you notify more than once before an unclaimed device is disposed of.
          */
         notifiedAt?: number[];
@@ -969,9 +987,11 @@ declare global {
          * staff clicked «abrir orden» on a `RECURRING_VISIT`, and the booking
          * carries this ticket back as `Appointment.serviceOrderId`.
          *
-         * ⚠️ A ticket opened this way always starts `custody: 'pending_receipt'`:
-         * the equipment is still at the customer's site, and intake refuses
-         * `equipmentReceived: true` beside an `appointment`.
+         * ⚠️ A ticket opened this way starts `custody: 'on_site'`: the work is
+         * done at the customer's site, and intake refuses `equipmentReceived:
+         * true` beside an `appointment`. The on-site marker is that CUSTODY value,
+         * never this field — this link is removed when the visit is called off,
+         * while the ticket's custody stays what it was.
          *
          * ⚠️ **Live, not provenance.** A reschedule re-points all three fields at
          * the replacement booking; cancelling, skipping or a `NO_SHOW` REMOVES all
@@ -1084,14 +1104,17 @@ declare global {
     }
     /**
      * The `409` body of a refused CUSTODY move, with the custody states that ARE
-     * reachable — `SERVICE_CUSTODY_TRANSITIONS[current]`.
+     * reachable — `SERVICE_CUSTODY_TRANSITIONS[current]` for an edit; for a status
+     * refusal, only those of them from which that status would then succeed.
      *
      * - `CUSTODY_ILLEGAL_TRANSITION` — `mode: 'edit'` sent a `custody` the
      *   current one cannot move to.
-     * - `SERVICE_ORDER_CUSTODY_NOT_RECEIVED` — `mode: 'status'` asked for
-     *   `delivered` or `abandoned_disposed`, which move the customer's property,
-     *   while the equipment was never received (`pending_receipt`). Receive it
-     *   first; the status itself was not the problem.
+     * - `SERVICE_ORDER_CUSTODY_NOT_RECEIVED` — `mode: 'status'` asked for a
+     *   status the current custody cannot close into: `delivered` or
+     *   `abandoned_disposed` while the equipment was never received
+     *   (`pending_receipt`), or `abandoned_disposed` on an `on_site` ticket,
+     *   whose property the shop never held. Receive it first; the status itself
+     *   was not the problem. (`delivered` on `on_site` is NOT refused.)
      */
     interface ServiceOrderCustodyRefusal {
         error: 'CUSTODY_ILLEGAL_TRANSITION' | 'SERVICE_ORDER_CUSTODY_NOT_RECEIVED';
@@ -1166,7 +1189,13 @@ export declare const SERVICE_TERMINAL_STATUSES: readonly ["delivered", "cancelle
  * ⚠️ **`pending_receipt` is entered at intake and never re-entered.** It is
  * absent from every other row's list on purpose: equipment that has arrived
  * cannot un-arrive, and a ticket cannot be walked back to "not here yet" to
- * hide that it was received. That is the only new constraint this table adds.
+ * hide that it was received.
+ *
+ * ⚠️ **`on_site` is entered at intake, or from `pending_receipt` only.** The
+ * second edge is how an operator moves a visit ticket opened before `on_site`
+ * existed; nothing moves one automatically. Its only exit is `in_shop` — the
+ * technician bringing the equipment in. `returned`/`disposed` are unreachable
+ * from it because the shop never held what they would record handing back.
  *
  * ⚠️ **`returned` and `disposed` are NOT terminal, deliberately.** Custody is a
  * statement about physical fact, not a workflow, and the operator UI presents

package/dist/serviceOrder.js

@@ -115,7 +115,13 @@ export const SERVICE_TERMINAL_STATUSES = [
  * ⚠️ **`pending_receipt` is entered at intake and never re-entered.** It is
  * absent from every other row's list on purpose: equipment that has arrived
  * cannot un-arrive, and a ticket cannot be walked back to "not here yet" to
- * hide that it was received. That is the only new constraint this table adds.
+ * hide that it was received.
+ *
+ * ⚠️ **`on_site` is entered at intake, or from `pending_receipt` only.** The
+ * second edge is how an operator moves a visit ticket opened before `on_site`
+ * existed; nothing moves one automatically. Its only exit is `in_shop` — the
+ * technician bringing the equipment in. `returned`/`disposed` are unreachable
+ * from it because the shop never held what they would record handing back.
  *
  * ⚠️ **`returned` and `disposed` are NOT terminal, deliberately.** Custody is a
  * statement about physical fact, not a workflow, and the operator UI presents
@@ -127,7 +133,8 @@ export const SERVICE_TERMINAL_STATUSES = [
  * about where someone else's property is.
  */
 export const SERVICE_CUSTODY_TRANSITIONS = {
-    pending_receipt: ['in_shop'],
+    pending_receipt: ['in_shop', 'on_site'],
+    on_site: ['in_shop'],
     in_shop: ['returned', 'disposed'],
     returned: ['in_shop', 'disposed'],
     disposed: ['in_shop', 'returned'],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sinfactura-types",
-	"version": "1.10.433",
+	"version": "1.10.435",
 	"description": "Shared wire and entity contracts for the SINFACTURA platform.",
 	"type": "module",
 	"main": "dist/index.js",