sinfactura-types 1.10.576 → 1.10.577

package/dist/cjs/kitRecipe.js

@@ -7,14 +7,24 @@
  * products of the store, and how many of each, make up one unit. It never
  * carries a price, a tax rate or a stock figure, and saving one moves no stock.
  *
- * ⚠️ Kit SALES do not exist yet. While a product holds an `active` recipe it is
- * refused as a new or increased sale line on every channel (counter, storefront,
- * service, marketplace) with the shared `409 PRODUCT_NOT_AVAILABLE`, with stock
- * control on or off, and it cannot be linked to or reactivated on MercadoLibre.
- * Retiring the recipe makes it an ordinary product again.
+ * A kit with an `active` recipe sells only on the channels in
+ * `KIT_SALE_CHANNELS`. There the order keeps ONE priced line for the kit, while
+ * the sale consumes the recipe's components from stock, and the line freezes the
+ * recipe it consumed (`OrderLine.kit`). Cancelling or returning that line gives
+ * back exactly the frozen components, whatever the recipe says later. Every
+ * other channel (storefront, service, marketplace, quote conversion) refuses an
+ * active kit with the shared `409 PRODUCT_NOT_AVAILABLE`, with stock control on
+ * or off, and it cannot be linked to or reactivated on MercadoLibre. Retiring
+ * the recipe makes it an ordinary product again.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KIT_COMPONENT_MAX_QUANTITY = exports.KIT_RECIPE_MAX_COMPONENTS = void 0;
+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. Only the counter
+ * (the operator basket and `POST /orders`, which the app's POS and the mobile
+ * app share) does today.
+ */
+exports.KIT_SALE_CHANNELS = ['counter'];
 /**
  * Most components one recipe names. A save commits the kit, its new revision and
  * every component's usage row in ONE transaction, so this is bounded by

package/dist/cjs/order.js

@@ -251,6 +251,11 @@ exports.orderFulfilmentProgress = orderFulfilmentProgress;
  *   `mode: 'deposit-refund'`, see `OrderDepositRefundRequest`. Nothing was
  *   written. `DEPOSIT_ALREADY_REFUNDED`'s `data` carries
  *   `OrderDepositRefundManualData` when the refund on the ledger was non-cash.
+ * - `KIT_RECIPE_CHANGED` · 409 — a counter sale of a kit whose recipe was
+ *   saved again or retired after the sale read it; `productIds` names the kits.
+ *   Nothing was written; re-read the basket and retry.
+ * - `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.
  *
  * Shipment refusals (`mode: 'shipment' | 'shipment-void'`), nothing written on
  * any of them:
@@ -359,4 +364,8 @@ exports.ORDER_ERROR_CODES = [
     // `POST /orders { mode: 'deposit-refund' }` — see `OrderDepositRefundRequest`.
     'DEPOSIT_NOT_FOUND',
     'DEPOSIT_ALREADY_REFUNDED',
+    // 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.
+    'ORDER_HAS_KIT_LINES',
 ];

package/dist/kitRecipe.d.ts

@@ -6,12 +6,22 @@
  * products of the store, and how many of each, make up one unit. It never
  * carries a price, a tax rate or a stock figure, and saving one moves no stock.
  *
- * ⚠️ Kit SALES do not exist yet. While a product holds an `active` recipe it is
- * refused as a new or increased sale line on every channel (counter, storefront,
- * service, marketplace) with the shared `409 PRODUCT_NOT_AVAILABLE`, with stock
- * control on or off, and it cannot be linked to or reactivated on MercadoLibre.
- * Retiring the recipe makes it an ordinary product again.
+ * A kit with an `active` recipe sells only on the channels in
+ * `KIT_SALE_CHANNELS`. There the order keeps ONE priced line for the kit, while
+ * the sale consumes the recipe's components from stock, and the line freezes the
+ * recipe it consumed (`OrderLine.kit`). Cancelling or returning that line gives
+ * back exactly the frozen components, whatever the recipe says later. Every
+ * other channel (storefront, service, marketplace, quote conversion) refuses an
+ * active kit with the shared `409 PRODUCT_NOT_AVAILABLE`, with stock control on
+ * or off, and it cannot be linked to or reactivated on MercadoLibre. Retiring
+ * the recipe makes it an ordinary product again.
  */
+/**
+ * The channels that sell a kit by consuming its components. Only the counter
+ * (the operator basket and `POST /orders`, which the app's POS and the mobile
+ * app share) does today.
+ */
+export declare const KIT_SALE_CHANNELS: readonly ["counter"];
 /**
  * Most components one recipe names. A save commits the kit, its new revision and
  * every component's usage row in ONE transaction, so this is bounded by
@@ -22,13 +32,19 @@ export declare const KIT_RECIPE_MAX_COMPONENTS = 30;
 export declare const KIT_COMPONENT_MAX_QUANTITY = 1000000;
 declare global {
     /**
-     * - `active` — the product is a kit and is sold nowhere until kit sales exist.
+     * - `active` — the product is a kit, sold only on `KIT_SALE_CHANNELS`.
      * - `retired` — the recipe was withdrawn; the product is an ordinary product
      *   again. Its revisions stay readable.
      */
     type KitRecipeStatus = 'active' | 'retired';
-    /** Whether the kit can be sold. Only `unsupported` exists today. */
-    type KitSaleSupport = 'unsupported';
+    /**
+     * Where an active kit can be sold.
+     *
+     * - `channels` — on the channels `KitRecipeDetail.saleChannels` names, and
+     *   refused on every other one.
+     * - `unsupported` — nowhere. Answered for a retired recipe.
+     */
+    type KitSaleSupport = 'channels' | 'unsupported';
     /**
      * `Product.kitRecipe` — where the product's recipe stands. Server-owned: only
      * `POST /catalog/kits` writes it, and `POST /products` drops it. Absent means
@@ -80,6 +96,34 @@ declare global {
         /** The kit's newest revision, to send as `expectedRevision`. */
         currentRevision: number;
         saleSupport: KitSaleSupport;
+        /** The channels that sell this kit. Empty when `saleSupport` is `unsupported`. */
+        saleChannels: SaleChannel[];
+    }
+    /**
+     * One component a kit line consumed, frozen on the order line at create.
+     */
+    interface OrderLineKitComponent {
+        productId: string;
+        /** Units consumed per kit unit, as the recipe said at the sale. */
+        quantity: number;
+        /**
+         * One unit's cost in the ORDER's currency, converted at the order's frozen
+         * rate. Absent when the component had no usable cost at the sale. The kit
+         * line's `cost` is the sum of these times `quantity`.
+         */
+        cost?: number;
+    }
+    /**
+     * `OrderLine.kit` — the recipe a kit line consumed, frozen at the sale.
+     * Server-owned and operator-only: only an order create on a kit sale channel
+     * writes it, a client-sent `kit` is dropped, and every shopper-facing copy
+     * omits it. Cancelling or returning the line reverses these components, never
+     * the kit's current recipe.
+     */
+    interface OrderLineKit {
+        /** The recipe revision the sale consumed. */
+        revision: number;
+        components: OrderLineKitComponent[];
     }
     /**
      * `POST /catalog/kits` `mode: 'save'` — writes a new active revision holding

package/dist/kitRecipe.js

@@ -6,12 +6,22 @@
  * products of the store, and how many of each, make up one unit. It never
  * carries a price, a tax rate or a stock figure, and saving one moves no stock.
  *
- * ⚠️ Kit SALES do not exist yet. While a product holds an `active` recipe it is
- * refused as a new or increased sale line on every channel (counter, storefront,
- * service, marketplace) with the shared `409 PRODUCT_NOT_AVAILABLE`, with stock
- * control on or off, and it cannot be linked to or reactivated on MercadoLibre.
- * Retiring the recipe makes it an ordinary product again.
+ * A kit with an `active` recipe sells only on the channels in
+ * `KIT_SALE_CHANNELS`. There the order keeps ONE priced line for the kit, while
+ * the sale consumes the recipe's components from stock, and the line freezes the
+ * recipe it consumed (`OrderLine.kit`). Cancelling or returning that line gives
+ * back exactly the frozen components, whatever the recipe says later. Every
+ * other channel (storefront, service, marketplace, quote conversion) refuses an
+ * active kit with the shared `409 PRODUCT_NOT_AVAILABLE`, with stock control on
+ * or off, and it cannot be linked to or reactivated on MercadoLibre. Retiring
+ * the recipe makes it an ordinary product again.
  */
+/**
+ * The channels that sell a kit by consuming its components. Only the counter
+ * (the operator basket and `POST /orders`, which the app's POS and the mobile
+ * app share) does today.
+ */
+export const KIT_SALE_CHANNELS = ['counter'];
 /**
  * Most components one recipe names. A save commits the kit, its new revision and
  * every component's usage row in ONE transaction, so this is bounded by

package/dist/order.d.ts

@@ -282,6 +282,19 @@ declare global {
          * shipments existed, forward-only, never backfilled.
          */
         fulfilledQuantity?: number;
+        /**
+         * The kit recipe this line consumed — see `OrderLineKit`. Present only on a
+         * line that sold an active kit on a kit sale channel.
+         *
+         * ⚠️ **Server-owned and operator-only.** Only the order create that froze
+         * it keeps it (`stripServerOwnedLineFields`), and every shopper-facing
+         * copy drops it, since it carries each component's cost.
+         *
+         * ⚠️ A line is a kit line because it CARRIES this, never because its
+         * product is a kit today: a product sold before its recipe existed reverses
+         * its own stock.
+         */
+        kit?: OrderLineKit;
     }
     /**
      * A shipment's lifecycle. A void marks the SHIPMENT row `voided` (kept as
@@ -2292,6 +2305,11 @@ export declare const orderFulfilmentProgress: (order: OrderFulfilmentProgressInp
  *   `mode: 'deposit-refund'`, see `OrderDepositRefundRequest`. Nothing was
  *   written. `DEPOSIT_ALREADY_REFUNDED`'s `data` carries
  *   `OrderDepositRefundManualData` when the refund on the ledger was non-cash.
+ * - `KIT_RECIPE_CHANGED` · 409 — a counter sale of a kit whose recipe was
+ *   saved again or retired after the sale read it; `productIds` names the kits.
+ *   Nothing was written; re-read the basket and retry.
+ * - `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.
  *
  * Shipment refusals (`mode: 'shipment' | 'shipment-void'`), nothing written on
  * any of them:
@@ -2335,6 +2353,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"];
+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 type OrderErrorCode = (typeof ORDER_ERROR_CODES)[number];
 export {};

package/dist/order.js

@@ -244,6 +244,11 @@ export const orderFulfilmentProgress = (order) => {
  *   `mode: 'deposit-refund'`, see `OrderDepositRefundRequest`. Nothing was
  *   written. `DEPOSIT_ALREADY_REFUNDED`'s `data` carries
  *   `OrderDepositRefundManualData` when the refund on the ledger was non-cash.
+ * - `KIT_RECIPE_CHANGED` · 409 — a counter sale of a kit whose recipe was
+ *   saved again or retired after the sale read it; `productIds` names the kits.
+ *   Nothing was written; re-read the basket and retry.
+ * - `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.
  *
  * Shipment refusals (`mode: 'shipment' | 'shipment-void'`), nothing written on
  * any of them:
@@ -352,4 +357,8 @@ export const ORDER_ERROR_CODES = [
     // `POST /orders { mode: 'deposit-refund' }` — see `OrderDepositRefundRequest`.
     'DEPOSIT_NOT_FOUND',
     'DEPOSIT_ALREADY_REFUNDED',
+    // 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.
+    'ORDER_HAS_KIT_LINES',
 ];

package/dist/product.d.ts

@@ -670,12 +670,14 @@ declare global {
          * Where this product's kit recipe stands. Server-owned: only
          * `POST /catalog/kits` writes it, and `POST /products` drops it.
          *
-         * `status: 'active'` makes the product a kit, and a kit is sold nowhere
-         * yet: a new or increased sale line is refused `409 PRODUCT_NOT_AVAILABLE`
-         * on every channel, with stock control on or off, and it cannot be linked to
-         * or reactivated on MercadoLibre. Its own price, tax rate, `limit` and
-         * stock are kept untouched. `retired`, or absent, is an ordinary product.
-         * Operator-only: never in a shopper projection.
+         * `status: 'active'` makes the product a kit. A kit sells only on
+         * `KIT_SALE_CHANNELS`, where the sale prices it as one line and consumes its
+         * components from stock instead of its own `stock`. Every other channel
+         * refuses a new or increased sale line `409 PRODUCT_NOT_AVAILABLE`, with
+         * stock control on or off, and it cannot be linked to or reactivated on
+         * MercadoLibre. Its own price, tax rate and `limit` still apply to the
+         * kit line. `retired`, or absent, is an ordinary product. Operator-only:
+         * never in a shopper projection.
          */
         kitRecipe?: ProductKitRecipePointer;
         model?: string;

package/package.json

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