sinfactura-types 1.10.615 → 1.10.617

package/dist/basket.d.ts

@@ -62,4 +62,18 @@ declare global {
         mergedCount: number;
     }
 }
+/**
+ * Domain refusals from POST /baskets: legacy replacement, named cart actions,
+ * and park/resume. Check GATING_ERROR_CODES separately for middleware and role
+ * refusals. GET /baskets and storefront-only refusals are outside this tuple.
+ *
+ * Coupon and promotion reasons are forwarded from evaluateCoupon and
+ * evaluatePromotion (stacks/services/coupons.ts and promotions.ts). Checkout's
+ * COUPON_EXHAUSTED_AT_CHECKOUT never reaches this write surface. Pricing
+ * forwards FX_CONVERSION_UNAVAILABLE from displayCurrencyRateRefusal through
+ * priceHandler.resolveLineStamp. The legacy loose body also reaches the shared
+ * foreign-index-key guard; its owned terminalId is validated before that guard.
+ */
+export declare const BASKET_ERROR_CODES: readonly ["VALIDATION_FAILED", "FOREIGN_INDEX_KEY_ATTRIBUTE", "CART_TARGET_REQUIRED", "CART_NOT_FOUND", "CART_NOT_PARKED", "CART_ALREADY_PARKED", "TERMINAL_INDEX_UNAVAILABLE", "PRODUCT_NOT_FOUND", "PRODUCT_COST_UNKNOWN", "UNIT_QUANTITY_NOT_WHOLE", "BASKET_VERSION_CONFLICT", "BASKET_LINE_LIMIT", "BASKET_SIZE_LIMIT", "UNKNOWN_LINE", "INVALID_PRICE", "LINE_DISCOUNT_NOT_ALLOWED", "LINE_DISCOUNT_EXCEEDS_MAX", "FX_CONVERSION_UNAVAILABLE", "COUPON_NOT_FOUND", "COUPON_NOT_ACTIVE", "COUPON_EXPIRED", "COUPON_EXHAUSTED", "COUPON_MIN_SUBTOTAL", "COUPON_REQUIRES_CUSTOMER", "COUPON_BUDGET_EXHAUSTED", "COUPON_RATE_LIMITED", "COUPON_CURRENCY_MISMATCH", "PROMOTION_NOT_FOUND", "PROMOTION_NOT_ACTIVE", "PROMOTION_NOT_STARTED", "PROMOTION_EXPIRED", "PROMOTION_NOT_CART_APPLICABLE"];
+export type BasketErrorCode = (typeof BASKET_ERROR_CODES)[number];
 export {};

package/dist/basket.js

@@ -1 +1,46 @@
-export {};
+/**
+ * Domain refusals from POST /baskets: legacy replacement, named cart actions,
+ * and park/resume. Check GATING_ERROR_CODES separately for middleware and role
+ * refusals. GET /baskets and storefront-only refusals are outside this tuple.
+ *
+ * Coupon and promotion reasons are forwarded from evaluateCoupon and
+ * evaluatePromotion (stacks/services/coupons.ts and promotions.ts). Checkout's
+ * COUPON_EXHAUSTED_AT_CHECKOUT never reaches this write surface. Pricing
+ * forwards FX_CONVERSION_UNAVAILABLE from displayCurrencyRateRefusal through
+ * priceHandler.resolveLineStamp. The legacy loose body also reaches the shared
+ * foreign-index-key guard; its owned terminalId is validated before that guard.
+ */
+export const BASKET_ERROR_CODES = [
+    'VALIDATION_FAILED',
+    'FOREIGN_INDEX_KEY_ATTRIBUTE',
+    'CART_TARGET_REQUIRED',
+    'CART_NOT_FOUND',
+    'CART_NOT_PARKED',
+    'CART_ALREADY_PARKED',
+    'TERMINAL_INDEX_UNAVAILABLE',
+    'PRODUCT_NOT_FOUND',
+    'PRODUCT_COST_UNKNOWN',
+    'UNIT_QUANTITY_NOT_WHOLE',
+    'BASKET_VERSION_CONFLICT',
+    'BASKET_LINE_LIMIT',
+    'BASKET_SIZE_LIMIT',
+    'UNKNOWN_LINE',
+    'INVALID_PRICE',
+    'LINE_DISCOUNT_NOT_ALLOWED',
+    'LINE_DISCOUNT_EXCEEDS_MAX',
+    'FX_CONVERSION_UNAVAILABLE',
+    'COUPON_NOT_FOUND',
+    'COUPON_NOT_ACTIVE',
+    'COUPON_EXPIRED',
+    'COUPON_EXHAUSTED',
+    'COUPON_MIN_SUBTOTAL',
+    'COUPON_REQUIRES_CUSTOMER',
+    'COUPON_BUDGET_EXHAUSTED',
+    'COUPON_RATE_LIMITED',
+    'COUPON_CURRENCY_MISMATCH',
+    'PROMOTION_NOT_FOUND',
+    'PROMOTION_NOT_ACTIVE',
+    'PROMOTION_NOT_STARTED',
+    'PROMOTION_EXPIRED',
+    'PROMOTION_NOT_CART_APPLICABLE',
+];

package/dist/cart.d.ts

@@ -750,10 +750,11 @@ declare global {
      * Constraints the type system cannot express, enforced in zod at the handler
      * and stated here because a `.d.ts` reader has no other way to learn them:
      * - `productId` matches `/^PROD\d{6,10}$/`; `lineId` matches `/^L\d{4,}$/`.
-     * - `quantity` is `min(0).max(1_000_000)` and is deliberately NOT an integer:
-     *   weight-priced products carry fractional quantities. The maximum is overflow
-     *   hygiene — an absurd quantity takes the running total to `Infinity` and dies
-     *   at the DynamoDB marshaller instead of at validation.
+     * - `quantity` is non-negative, at most `MAX_BASE_QUANTITY`, and exactly
+     *   representable with at most `BASE_QUANTITY_DECIMAL_PLACES` decimal places
+     *   (six). Weight-priced products may carry fractional base quantities;
+     *   products declared as `each` require whole quantities. Nothing is rounded:
+     *   `0.1 + 0.2` is refused as `VALIDATION_FAILED`; send the exact value `0.3`.
      * - `merge.items` is `min(1).max(50)`.
      */
     type CartActionRequest = CartActionAddLine | CartActionChangeQuantity | CartActionRemoveLine | CartActionClear | CartActionMerge | CartActionSaveLine | CartActionRestoreLine | CartActionRemoveSavedLine | CartActionApplyCoupon | CartActionRemoveCoupon | CartActionApplyPromotion | CartActionRemovePromotion | CartActionSetLineDiscount | CartActionResume;

package/dist/cjs/basket.js

@@ -1,2 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASKET_ERROR_CODES = void 0;
+/**
+ * Domain refusals from POST /baskets: legacy replacement, named cart actions,
+ * and park/resume. Check GATING_ERROR_CODES separately for middleware and role
+ * refusals. GET /baskets and storefront-only refusals are outside this tuple.
+ *
+ * Coupon and promotion reasons are forwarded from evaluateCoupon and
+ * evaluatePromotion (stacks/services/coupons.ts and promotions.ts). Checkout's
+ * COUPON_EXHAUSTED_AT_CHECKOUT never reaches this write surface. Pricing
+ * forwards FX_CONVERSION_UNAVAILABLE from displayCurrencyRateRefusal through
+ * priceHandler.resolveLineStamp. The legacy loose body also reaches the shared
+ * foreign-index-key guard; its owned terminalId is validated before that guard.
+ */
+exports.BASKET_ERROR_CODES = [
+    'VALIDATION_FAILED',
+    'FOREIGN_INDEX_KEY_ATTRIBUTE',
+    'CART_TARGET_REQUIRED',
+    'CART_NOT_FOUND',
+    'CART_NOT_PARKED',
+    'CART_ALREADY_PARKED',
+    'TERMINAL_INDEX_UNAVAILABLE',
+    'PRODUCT_NOT_FOUND',
+    'PRODUCT_COST_UNKNOWN',
+    'UNIT_QUANTITY_NOT_WHOLE',
+    'BASKET_VERSION_CONFLICT',
+    'BASKET_LINE_LIMIT',
+    'BASKET_SIZE_LIMIT',
+    'UNKNOWN_LINE',
+    'INVALID_PRICE',
+    'LINE_DISCOUNT_NOT_ALLOWED',
+    'LINE_DISCOUNT_EXCEEDS_MAX',
+    'FX_CONVERSION_UNAVAILABLE',
+    'COUPON_NOT_FOUND',
+    'COUPON_NOT_ACTIVE',
+    'COUPON_EXPIRED',
+    'COUPON_EXHAUSTED',
+    'COUPON_MIN_SUBTOTAL',
+    'COUPON_REQUIRES_CUSTOMER',
+    'COUPON_BUDGET_EXHAUSTED',
+    'COUPON_RATE_LIMITED',
+    'COUPON_CURRENCY_MISMATCH',
+    'PROMOTION_NOT_FOUND',
+    'PROMOTION_NOT_ACTIVE',
+    'PROMOTION_NOT_STARTED',
+    'PROMOTION_EXPIRED',
+    'PROMOTION_NOT_CART_APPLICABLE',
+];

package/dist/cjs/kitRecipe.js

@@ -1,4 +1,7 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KIT_COMPONENT_MAX_QUANTITY = exports.KIT_RECIPE_MAX_COMPONENTS = exports.KIT_SALE_CHANNELS = void 0;
+const product_ts_1 = require("./product.js");
 /**
  * Kit recipes — the components one ordinary product is assembled from.
  *
@@ -20,8 +23,6 @@
  * A shopper never sees the recipe: the storefront reads `Product.isKit` and the
  * kit's `stock`, which the shopper projection derives from its components.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KIT_COMPONENT_MAX_QUANTITY = exports.KIT_RECIPE_MAX_COMPONENTS = exports.KIT_SALE_CHANNELS = void 0;
 /**
  * The channels that sell a kit by consuming its components:
  *
@@ -38,4 +39,4 @@ exports.KIT_SALE_CHANNELS = ['counter', 'storefront'];
  */
 exports.KIT_RECIPE_MAX_COMPONENTS = 30;
 /** Largest quantity of one component per kit unit — the same ceiling an order line has. */
-exports.KIT_COMPONENT_MAX_QUANTITY = 1_000_000;
+exports.KIT_COMPONENT_MAX_QUANTITY = product_ts_1.MAX_BASE_QUANTITY;

package/dist/cjs/order.js

@@ -260,6 +260,13 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  * - `ORDER_HAS_KIT_LINES` · 409 — `mode: 'edit'` on an order holding a kit line
  *   (`CartLine.kit`). Cancel or return the order instead. Nothing was written.
  *
+ * Unit refusals: `UNIT_QUANTITY_NOT_WHOLE` · 400 on checkout, a quantity edit
+ * or a return of an `each` product (including frozen kit components);
+ * `UNIT_QUANTITY_UNREPRESENTABLE` · 400 when kit components cannot be
+ * represented exactly on checkout or return; `UNIT_REVISION_STALE` · 409 when
+ * the product's units changed between the read and the sale commit. Re-read
+ * current product units before retrying. Nothing was written.
+ *
  * Shipment refusals (`mode: 'shipment' | 'shipment-void'`), nothing written on
  * any of them:
  * - `SHIPMENT_QUANTITY_EXCEEDED` · 409 — a line would exceed its ordered
@@ -367,6 +374,10 @@ exports.ORDER_ERROR_CODES = [
     // `POST /orders { mode: 'deposit-refund' }` — see `OrderDepositRefundRequest`.
     'DEPOSIT_NOT_FOUND',
     'DEPOSIT_ALREADY_REFUNDED',
+    // Checkout/quantity edits and commit-time product-unit revision guards.
+    'UNIT_QUANTITY_NOT_WHOLE',
+    'UNIT_REVISION_STALE',
+    'UNIT_QUANTITY_UNREPRESENTABLE',
     // A kit's recipe changed or was retired between reading it and the sale's commit.
     'KIT_RECIPE_CHANGED',
     // `mode: 'edit'` on an order holding a kit line; cancel or return it instead.

package/dist/cjs/product.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PRODUCT_MEDIA_INVALID_REASONS = exports.MAX_PRODUCT_PICTURE_ALT_CHARS = exports.PRODUCT_UPSERT_ERROR_CODES = exports.PRODUCT_UPSERT_ROW_ERROR_CODES = exports.PRODUCT_UPSERT_ROW_CAP = exports.PUBLIC_PRODUCT_BY_SLUG_ERROR_CODES = exports.PRODUCT_PUBLISH_OVERDUE_AFTER_MS = exports.PRODUCT_PUBLISH_AT_MAX_AHEAD_MS = exports.PRODUCT_POST_ERROR_CODES = exports.PRODUCT_IDENTITY_ERROR_CODES = exports.PRODUCT_EXPORT_ERROR_CODES = exports.PRODUCT_CATALOG_EXPORT_COLUMNS = void 0;
+exports.PRODUCT_MEDIA_INVALID_REASONS = exports.MAX_PRODUCT_PICTURE_ALT_CHARS = exports.PRODUCT_UPSERT_ERROR_CODES = exports.PRODUCT_UPSERT_ROW_ERROR_CODES = exports.PRODUCT_UPSERT_ROW_CAP = exports.PUBLIC_PRODUCT_BY_SLUG_ERROR_CODES = exports.PRODUCT_PUBLISH_OVERDUE_AFTER_MS = exports.PRODUCT_PUBLISH_AT_MAX_AHEAD_MS = exports.PRODUCT_POST_ERROR_CODES = exports.PRODUCT_IDENTITY_ERROR_CODES = exports.PRODUCT_EXPORT_ERROR_CODES = exports.PRODUCT_CATALOG_EXPORT_COLUMNS = exports.MAX_BASE_QUANTITY = exports.BASE_QUANTITY_DECIMAL_PLACES = void 0;
+/** Maximum decimal places in a canonical base quantity; inputs are exact, never rounded. */
+exports.BASE_QUANTITY_DECIMAL_PLACES = 6;
+/** Absolute base-quantity input bound; signed adjustments admit the negative of this value. */
+exports.MAX_BASE_QUANTITY = 1_000_000;
 /**
  * The CSV header of `GET /products?mode=export`, in file order.
  *

package/dist/cjs/purchaseOrder.js

@@ -69,10 +69,25 @@ exports.PURCHASE_ORDER_STATUSES = [
  * (`stacks/services/ingressLevels.ts`), which the handler forwards verbatim, so
  * they never appear as literals in `_postStock.ts`.
  *
+ * The optional `Idempotency-Key` wrapper also refuses inline:
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — malformed key.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — key reused for another payload.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the original call is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — could not claim the key; retry.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — sealed after a throw or abandoned claim;
+ *   inspect what committed before retrying with a new key.
+ * `IDEMPOTENT_RESPONSE_NOT_CACHED` is a 2xx replay sentinel and is deliberately
+ * omitted from this refusal tuple.
+ *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.
  */
 exports.PURCHASE_ORDER_RECEIPT_ERROR_CODES = [
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'IDEMPOTENCY_KEY_FAILED',
     'PURCHASE_ORDER_NOT_FOUND',
     'INVALID_CURSOR',
     'ADMIN_REQUIRED',

package/dist/cjs/stock.js

@@ -104,10 +104,39 @@ exports.MAX_STOCK_ADJUSTMENT_NOTE_BYTES = 280;
  * - `OPENING_BALANCE_UNVERIFIABLE` · 409 — the product's ledger is too long to sum,
  *   so the opening balance cannot be checked and is not written.
  *
+ * - `WAREHOUSE_NOT_FOUND` · 404 / `WAREHOUSE_INACTIVE` · 409 and
+ *   `NO_PRIMARY_WAREHOUSE` · 409 — forwarded by the depósito resolver.
+ * - `UNIT_QUANTITY_UNREPRESENTABLE`, `UNIT_QUANTITY_NOT_WHOLE`,
+ *   `UNIT_FACTOR_INVALID` · 400 — base/purchase quantity normalization.
+ * - `UNIT_REVISION_STALE` · 409 — product units changed before commit.
+ * - `PURCHASE_RECEIPT_NOT_FOUND` · 404 — receipt-linked return has no receipt.
+ * - `PURCHASE_ORDER_LINE_NOT_FOUND`, `PURCHASE_RECEIPT_RETURN_EXCEEDS_RECEIVED`,
+ *   `PURCHASE_RECEIPT_WAREHOUSE_MISMATCH`, `PURCHASE_RECEIPT_VERSION_CONFLICT`
+ *   · 409 — receipt line, quantity, warehouse or concurrent return refusal.
+ *
+ * The optional `Idempotency-Key` wrapper also refuses inline:
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — malformed key.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — key reused for another payload.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the original call is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — could not claim the key; retry.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — sealed after a throw or abandoned claim;
+ *   inspect what committed before retrying with a new key.
+ * `IDEMPOTENT_RESPONSE_NOT_CACHED` is a 2xx replay sentinel and is deliberately
+ * omitted from this refusal tuple.
+ *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.
  */
 exports.STOCK_ADJUSTMENT_ERROR_CODES = [
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'IDEMPOTENCY_KEY_FAILED',
+    'WAREHOUSE_NOT_FOUND',
+    'WAREHOUSE_INACTIVE',
+    'NO_PRIMARY_WAREHOUSE',
+    'UNIT_REVISION_STALE',
     'PURCHASE_ORDER_LINE_NOT_FOUND',
     'PURCHASE_RECEIPT_NOT_FOUND',
     'PURCHASE_RECEIPT_RETURN_EXCEEDS_RECEIVED',

package/dist/kitRecipe.js

@@ -1,3 +1,4 @@
+import { MAX_BASE_QUANTITY } from "./product.js";
 /**
  * Kit recipes — the components one ordinary product is assembled from.
  *
@@ -35,4 +36,4 @@ export const KIT_SALE_CHANNELS = ['counter', 'storefront'];
  */
 export const KIT_RECIPE_MAX_COMPONENTS = 30;
 /** Largest quantity of one component per kit unit — the same ceiling an order line has. */
-export const KIT_COMPONENT_MAX_QUANTITY = 1_000_000;
+export const KIT_COMPONENT_MAX_QUANTITY = MAX_BASE_QUANTITY;

package/dist/order.d.ts

@@ -2360,6 +2360,13 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  * - `ORDER_HAS_KIT_LINES` · 409 — `mode: 'edit'` on an order holding a kit line
  *   (`CartLine.kit`). Cancel or return the order instead. Nothing was written.
  *
+ * Unit refusals: `UNIT_QUANTITY_NOT_WHOLE` · 400 on checkout, a quantity edit
+ * or a return of an `each` product (including frozen kit components);
+ * `UNIT_QUANTITY_UNREPRESENTABLE` · 400 when kit components cannot be
+ * represented exactly on checkout or return; `UNIT_REVISION_STALE` · 409 when
+ * the product's units changed between the read and the sale commit. Re-read
+ * current product units before retrying. Nothing was written.
+ *
  * Shipment refusals (`mode: 'shipment' | 'shipment-void'`), nothing written on
  * any of them:
  * - `SHIPMENT_QUANTITY_EXCEEDED` · 409 — a line would exceed its ordered
@@ -2402,6 +2409,6 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  * `SUBSCRIPTION_READONLY`) sit on the order CREATE leg only: an edit is not a new
  * order, so `bareOrderPostHandler` routes past `requireMetered` entirely.
  */
-export declare const ORDER_ERROR_CODES: readonly ["ORDER_COST_DENOMINATION_UNKNOWN", "SERVICE_ORDER_DELIVERY_MANAGED", "ORDER_NOT_FOUND", "ORDER_LOCKED", "ORDER_NOT_READY", "ORDER_DELIVERED_ANOTHER_DAY", "ORDER_DELIVERY_STATE_UNCHANGED", "ORDER_ILLEGAL_TRANSITION", "ORDER_VERSION_CONFLICT", "CUSTOMER_NOT_FOUND", "CUSTOMER_MERGED", "ORDER_HAS_NO_CUSTOMER", "CUSTOMER_ANONYMIZED", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "PAYMENT_SETTLED_ON_ANOTHER_ORDER", "ORDER_HAS_SHIPMENTS", "ORDER_HAS_RETURNS", "SHIPMENT_QUANTITY_EXCEEDED", "SHIPMENT_LINE_MISMATCH", "SHIPMENT_NOT_FOUND", "SHIPMENT_LIMIT_REACHED", "SHIPMENT_TOO_LARGE", "ORDER_FULFILMENT_EXTERNAL", "SHIPMENT_FAILED", "ADMIN_REQUIRED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENT_RESPONSE_NOT_CACHED", "ORDER_CANCELLATION_NOT_PROTECTED", "ORDER_CANCELLATION_COMMITTED", "ORDER_CANCELLATION_LOCKED", "ORDER_CANCELLATION_TOO_LARGE", "ORDER_CANCELLATION_FAILED", "SALE_LEDGER_RETRACTION_REFUSED", "SALE_LEDGER_ROW_NOT_OWNED", "PRODUCT_NOT_FOUND", "PRODUCT_SALE_LIMIT_EXCEEDED", "PRODUCT_SALE_LIMIT_INVALID", "DEPOSIT_SOURCE_NOT_ALLOWED", "DEPOSIT_CURRENCY_MISMATCH", "DEPOSIT_EXCEEDS_TOTAL", "DEPOSIT_FREEZE_REQUIRES_INVOICE", "DEPOSIT_FREEZE_INVOICE_PENDING", "DEPOSIT_CHARACTERIZATION_CONFLICT", "DEPOSIT_FREEZE_INVOICE_NOT_QUALIFYING", "DEPOSIT_INVOICED_ORDER_MUST_FREEZE", "DEPOSIT_REFERENCE_IS_LINKED_PAYMENT", "DEPOSIT_DUPLICATE_REFERENCE", "PAYMENT_REFERENCED_BY_DEPOSIT", "ORDER_HAS_UNREFUNDED_DEPOSIT", "DEPOSIT_NOT_FOUND", "DEPOSIT_ALREADY_REFUNDED", "KIT_RECIPE_CHANGED", "ORDER_HAS_KIT_LINES"];
+export declare const ORDER_ERROR_CODES: readonly ["ORDER_COST_DENOMINATION_UNKNOWN", "SERVICE_ORDER_DELIVERY_MANAGED", "ORDER_NOT_FOUND", "ORDER_LOCKED", "ORDER_NOT_READY", "ORDER_DELIVERED_ANOTHER_DAY", "ORDER_DELIVERY_STATE_UNCHANGED", "ORDER_ILLEGAL_TRANSITION", "ORDER_VERSION_CONFLICT", "CUSTOMER_NOT_FOUND", "CUSTOMER_MERGED", "ORDER_HAS_NO_CUSTOMER", "CUSTOMER_ANONYMIZED", "FX_CONVERSION_UNAVAILABLE", "ROLE_FORBIDDEN", "ORDER_CANCELLED", "PAYMENT_SETTLED_ON_ANOTHER_ORDER", "ORDER_HAS_SHIPMENTS", "ORDER_HAS_RETURNS", "SHIPMENT_QUANTITY_EXCEEDED", "SHIPMENT_LINE_MISMATCH", "SHIPMENT_NOT_FOUND", "SHIPMENT_LIMIT_REACHED", "SHIPMENT_TOO_LARGE", "ORDER_FULFILMENT_EXTERNAL", "SHIPMENT_FAILED", "ADMIN_REQUIRED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "IDEMPOTENT_RESPONSE_NOT_CACHED", "ORDER_CANCELLATION_NOT_PROTECTED", "ORDER_CANCELLATION_COMMITTED", "ORDER_CANCELLATION_LOCKED", "ORDER_CANCELLATION_TOO_LARGE", "ORDER_CANCELLATION_FAILED", "SALE_LEDGER_RETRACTION_REFUSED", "SALE_LEDGER_ROW_NOT_OWNED", "PRODUCT_NOT_FOUND", "PRODUCT_SALE_LIMIT_EXCEEDED", "PRODUCT_SALE_LIMIT_INVALID", "DEPOSIT_SOURCE_NOT_ALLOWED", "DEPOSIT_CURRENCY_MISMATCH", "DEPOSIT_EXCEEDS_TOTAL", "DEPOSIT_FREEZE_REQUIRES_INVOICE", "DEPOSIT_FREEZE_INVOICE_PENDING", "DEPOSIT_CHARACTERIZATION_CONFLICT", "DEPOSIT_FREEZE_INVOICE_NOT_QUALIFYING", "DEPOSIT_INVOICED_ORDER_MUST_FREEZE", "DEPOSIT_REFERENCE_IS_LINKED_PAYMENT", "DEPOSIT_DUPLICATE_REFERENCE", "PAYMENT_REFERENCED_BY_DEPOSIT", "ORDER_HAS_UNREFUNDED_DEPOSIT", "DEPOSIT_NOT_FOUND", "DEPOSIT_ALREADY_REFUNDED", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_REVISION_STALE", "UNIT_QUANTITY_UNREPRESENTABLE", "KIT_RECIPE_CHANGED", "ORDER_HAS_KIT_LINES"];
 export type OrderErrorCode = (typeof ORDER_ERROR_CODES)[number];
 export {};

package/dist/order.js

@@ -253,6 +253,13 @@ export const orderFulfilmentProgress = (order) => {
  * - `ORDER_HAS_KIT_LINES` · 409 — `mode: 'edit'` on an order holding a kit line
  *   (`CartLine.kit`). Cancel or return the order instead. Nothing was written.
  *
+ * Unit refusals: `UNIT_QUANTITY_NOT_WHOLE` · 400 on checkout, a quantity edit
+ * or a return of an `each` product (including frozen kit components);
+ * `UNIT_QUANTITY_UNREPRESENTABLE` · 400 when kit components cannot be
+ * represented exactly on checkout or return; `UNIT_REVISION_STALE` · 409 when
+ * the product's units changed between the read and the sale commit. Re-read
+ * current product units before retrying. Nothing was written.
+ *
  * Shipment refusals (`mode: 'shipment' | 'shipment-void'`), nothing written on
  * any of them:
  * - `SHIPMENT_QUANTITY_EXCEEDED` · 409 — a line would exceed its ordered
@@ -360,6 +367,10 @@ export const ORDER_ERROR_CODES = [
     // `POST /orders { mode: 'deposit-refund' }` — see `OrderDepositRefundRequest`.
     'DEPOSIT_NOT_FOUND',
     'DEPOSIT_ALREADY_REFUNDED',
+    // Checkout/quantity edits and commit-time product-unit revision guards.
+    'UNIT_QUANTITY_NOT_WHOLE',
+    'UNIT_REVISION_STALE',
+    'UNIT_QUANTITY_UNREPRESENTABLE',
     // A kit's recipe changed or was retired between reading it and the sale's commit.
     'KIT_RECIPE_CHANGED',
     // `mode: 'edit'` on an order holding a kit line; cancel or return it instead.

package/dist/product.d.ts

@@ -1,3 +1,7 @@
+/** Maximum decimal places in a canonical base quantity; inputs are exact, never rounded. */
+export declare const BASE_QUANTITY_DECIMAL_PLACES = 6;
+/** Absolute base-quantity input bound; signed adjustments admit the negative of this value. */
+export declare const MAX_BASE_QUANTITY = 1000000;
 declare global {
     type ProductUnitsErrorCode = 'UNIT_REVISION_STALE' | 'UNIT_FACTOR_INVALID' | 'UNIT_FACTOR_MISMATCH' | 'UNIT_INCOMPATIBLE_DIMENSION' | 'UNIT_QUANTITY_UNREPRESENTABLE' | 'UNIT_QUANTITY_NOT_WHOLE';
     type ProductUnit = 'each' | 'gram' | 'kilogram' | 'millilitre' | 'litre' | 'metre';

package/dist/product.js

@@ -1,3 +1,7 @@
+/** Maximum decimal places in a canonical base quantity; inputs are exact, never rounded. */
+export const BASE_QUANTITY_DECIMAL_PLACES = 6;
+/** Absolute base-quantity input bound; signed adjustments admit the negative of this value. */
+export const MAX_BASE_QUANTITY = 1_000_000;
 /**
  * The CSV header of `GET /products?mode=export`, in file order.
  *

package/dist/purchaseOrder.d.ts

@@ -215,9 +215,19 @@ declare global {
  * (`stacks/services/ingressLevels.ts`), which the handler forwards verbatim, so
  * they never appear as literals in `_postStock.ts`.
  *
+ * The optional `Idempotency-Key` wrapper also refuses inline:
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — malformed key.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — key reused for another payload.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the original call is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — could not claim the key; retry.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — sealed after a throw or abandoned claim;
+ *   inspect what committed before retrying with a new key.
+ * `IDEMPOTENT_RESPONSE_NOT_CACHED` is a 2xx replay sentinel and is deliberately
+ * omitted from this refusal tuple.
+ *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.
  */
-export declare const PURCHASE_ORDER_RECEIPT_ERROR_CODES: readonly ["PURCHASE_ORDER_NOT_FOUND", "INVALID_CURSOR", "ADMIN_REQUIRED", "PURCHASE_ORDER_NOT_SENT", "PURCHASE_ORDER_CLOSED", "PURCHASE_ORDER_ITEM_NOT_FOUND", "PURCHASE_ORDER_ITEM_PRODUCT_MISMATCH", "PURCHASE_ORDER_NOT_RECEIVABLE", "STOCK_INCOME_RACED", "PRODUCT_NOT_FOUND", "VALIDATION_FAILED", "UNIT_QUANTITY_UNREPRESENTABLE", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_FACTOR_INVALID", "UNIT_REVISION_STALE", "WAREHOUSE_NOT_FOUND", "WAREHOUSE_INACTIVE", "NO_PRIMARY_WAREHOUSE", "INVENTORY_LEVEL_VERSION_CONFLICT"];
+export declare const PURCHASE_ORDER_RECEIPT_ERROR_CODES: readonly ["INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "PURCHASE_ORDER_NOT_FOUND", "INVALID_CURSOR", "ADMIN_REQUIRED", "PURCHASE_ORDER_NOT_SENT", "PURCHASE_ORDER_CLOSED", "PURCHASE_ORDER_ITEM_NOT_FOUND", "PURCHASE_ORDER_ITEM_PRODUCT_MISMATCH", "PURCHASE_ORDER_NOT_RECEIVABLE", "STOCK_INCOME_RACED", "PRODUCT_NOT_FOUND", "VALIDATION_FAILED", "UNIT_QUANTITY_UNREPRESENTABLE", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_FACTOR_INVALID", "UNIT_REVISION_STALE", "WAREHOUSE_NOT_FOUND", "WAREHOUSE_INACTIVE", "NO_PRIMARY_WAREHOUSE", "INVENTORY_LEVEL_VERSION_CONFLICT"];
 export type PurchaseOrderReceiptErrorCode = (typeof PURCHASE_ORDER_RECEIPT_ERROR_CODES)[number];
 export {};

package/dist/purchaseOrder.js

@@ -66,10 +66,25 @@ export const PURCHASE_ORDER_STATUSES = [
  * (`stacks/services/ingressLevels.ts`), which the handler forwards verbatim, so
  * they never appear as literals in `_postStock.ts`.
  *
+ * The optional `Idempotency-Key` wrapper also refuses inline:
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — malformed key.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — key reused for another payload.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the original call is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — could not claim the key; retry.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — sealed after a throw or abandoned claim;
+ *   inspect what committed before retrying with a new key.
+ * `IDEMPOTENT_RESPONSE_NOT_CACHED` is a 2xx replay sentinel and is deliberately
+ * omitted from this refusal tuple.
+ *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.
  */
 export const PURCHASE_ORDER_RECEIPT_ERROR_CODES = [
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'IDEMPOTENCY_KEY_FAILED',
     'PURCHASE_ORDER_NOT_FOUND',
     'INVALID_CURSOR',
     'ADMIN_REQUIRED',

package/dist/stock.d.ts

@@ -639,9 +639,29 @@ declare global {
  * - `OPENING_BALANCE_UNVERIFIABLE` · 409 — the product's ledger is too long to sum,
  *   so the opening balance cannot be checked and is not written.
  *
+ * - `WAREHOUSE_NOT_FOUND` · 404 / `WAREHOUSE_INACTIVE` · 409 and
+ *   `NO_PRIMARY_WAREHOUSE` · 409 — forwarded by the depósito resolver.
+ * - `UNIT_QUANTITY_UNREPRESENTABLE`, `UNIT_QUANTITY_NOT_WHOLE`,
+ *   `UNIT_FACTOR_INVALID` · 400 — base/purchase quantity normalization.
+ * - `UNIT_REVISION_STALE` · 409 — product units changed before commit.
+ * - `PURCHASE_RECEIPT_NOT_FOUND` · 404 — receipt-linked return has no receipt.
+ * - `PURCHASE_ORDER_LINE_NOT_FOUND`, `PURCHASE_RECEIPT_RETURN_EXCEEDS_RECEIVED`,
+ *   `PURCHASE_RECEIPT_WAREHOUSE_MISMATCH`, `PURCHASE_RECEIPT_VERSION_CONFLICT`
+ *   · 409 — receipt line, quantity, warehouse or concurrent return refusal.
+ *
+ * The optional `Idempotency-Key` wrapper also refuses inline:
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — malformed key.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — key reused for another payload.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the original call is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — could not claim the key; retry.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — sealed after a throw or abandoned claim;
+ *   inspect what committed before retrying with a new key.
+ * `IDEMPOTENT_RESPONSE_NOT_CACHED` is a 2xx replay sentinel and is deliberately
+ * omitted from this refusal tuple.
+ *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.
  */
-export declare const STOCK_ADJUSTMENT_ERROR_CODES: readonly ["PURCHASE_ORDER_LINE_NOT_FOUND", "PURCHASE_RECEIPT_NOT_FOUND", "PURCHASE_RECEIPT_RETURN_EXCEEDS_RECEIVED", "PURCHASE_RECEIPT_VERSION_CONFLICT", "PURCHASE_RECEIPT_WAREHOUSE_MISMATCH", "UNIT_QUANTITY_UNREPRESENTABLE", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_FACTOR_INVALID", "ROLE_FORBIDDEN", "VALIDATION_FAILED", "STOCK_ADJUSTMENT_REASON_DIRECTION_MISMATCH", "PRODUCT_NOT_FOUND", "STOCK_ADJUSTMENT_RACED", "OPENING_BALANCE_EXISTS", "OPENING_BALANCE_QUANTITY_MISMATCH", "OPENING_BALANCE_UNVERIFIABLE"];
+export declare const STOCK_ADJUSTMENT_ERROR_CODES: readonly ["INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_KEY_REUSE", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_LOCK_CONTENTION", "IDEMPOTENCY_KEY_FAILED", "WAREHOUSE_NOT_FOUND", "WAREHOUSE_INACTIVE", "NO_PRIMARY_WAREHOUSE", "UNIT_REVISION_STALE", "PURCHASE_ORDER_LINE_NOT_FOUND", "PURCHASE_RECEIPT_NOT_FOUND", "PURCHASE_RECEIPT_RETURN_EXCEEDS_RECEIVED", "PURCHASE_RECEIPT_VERSION_CONFLICT", "PURCHASE_RECEIPT_WAREHOUSE_MISMATCH", "UNIT_QUANTITY_UNREPRESENTABLE", "UNIT_QUANTITY_NOT_WHOLE", "UNIT_FACTOR_INVALID", "ROLE_FORBIDDEN", "VALIDATION_FAILED", "STOCK_ADJUSTMENT_REASON_DIRECTION_MISMATCH", "PRODUCT_NOT_FOUND", "STOCK_ADJUSTMENT_RACED", "OPENING_BALANCE_EXISTS", "OPENING_BALANCE_QUANTITY_MISMATCH", "OPENING_BALANCE_UNVERIFIABLE"];
 export type StockAdjustmentErrorCode = (typeof STOCK_ADJUSTMENT_ERROR_CODES)[number];
 export {};

package/dist/stock.js

@@ -101,10 +101,39 @@ export const MAX_STOCK_ADJUSTMENT_NOTE_BYTES = 280;
  * - `OPENING_BALANCE_UNVERIFIABLE` · 409 — the product's ledger is too long to sum,
  *   so the opening balance cannot be checked and is not written.
  *
+ * - `WAREHOUSE_NOT_FOUND` · 404 / `WAREHOUSE_INACTIVE` · 409 and
+ *   `NO_PRIMARY_WAREHOUSE` · 409 — forwarded by the depósito resolver.
+ * - `UNIT_QUANTITY_UNREPRESENTABLE`, `UNIT_QUANTITY_NOT_WHOLE`,
+ *   `UNIT_FACTOR_INVALID` · 400 — base/purchase quantity normalization.
+ * - `UNIT_REVISION_STALE` · 409 — product units changed before commit.
+ * - `PURCHASE_RECEIPT_NOT_FOUND` · 404 — receipt-linked return has no receipt.
+ * - `PURCHASE_ORDER_LINE_NOT_FOUND`, `PURCHASE_RECEIPT_RETURN_EXCEEDS_RECEIVED`,
+ *   `PURCHASE_RECEIPT_WAREHOUSE_MISMATCH`, `PURCHASE_RECEIPT_VERSION_CONFLICT`
+ *   · 409 — receipt line, quantity, warehouse or concurrent return refusal.
+ *
+ * The optional `Idempotency-Key` wrapper also refuses inline:
+ * - `INVALID_IDEMPOTENCY_KEY` · 400 — malformed key.
+ * - `IDEMPOTENCY_KEY_REUSE` · 422 — key reused for another payload.
+ * - `IDEMPOTENCY_IN_PROGRESS` · 409 — the original call is still running.
+ * - `IDEMPOTENCY_LOCK_CONTENTION` · 409 — could not claim the key; retry.
+ * - `IDEMPOTENCY_KEY_FAILED` · 409 — sealed after a throw or abandoned claim;
+ *   inspect what committed before retrying with a new key.
+ * `IDEMPOTENT_RESPONSE_NOT_CACHED` is a 2xx replay sentinel and is deliberately
+ * omitted from this refusal tuple.
+ *
  * ⚠️ Cross-cutting refusals are NOT repeated here — check `GATING_ERROR_CODES`
  * as well.
  */
 export const STOCK_ADJUSTMENT_ERROR_CODES = [
+    'INVALID_IDEMPOTENCY_KEY',
+    'IDEMPOTENCY_KEY_REUSE',
+    'IDEMPOTENCY_IN_PROGRESS',
+    'IDEMPOTENCY_LOCK_CONTENTION',
+    'IDEMPOTENCY_KEY_FAILED',
+    'WAREHOUSE_NOT_FOUND',
+    'WAREHOUSE_INACTIVE',
+    'NO_PRIMARY_WAREHOUSE',
+    'UNIT_REVISION_STALE',
     'PURCHASE_ORDER_LINE_NOT_FOUND',
     'PURCHASE_RECEIPT_NOT_FOUND',
     'PURCHASE_RECEIPT_RETURN_EXCEEDS_RECEIVED',

package/dist/subscription.d.ts

@@ -575,7 +575,7 @@ declare global {
         tier: PlanTier;
         /** A tier with no `SK: PLAN` row is unpurchasable, whatever its features are. */
         hasTemplate: boolean;
-        /** `priceMonthlyCents === 0` on the template — exempt from the provider-identifier check. */
+        /** Neither cycle is charged (each price `0` or absent) — exempt from the provider-identifier check. */
         free: boolean;
         /**
          * Provider-identifier KEY NAMES the template is missing (e.g.

package/package.json

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