@zolve/offers 0.3.1 → 0.3.2

package/README.md

@@ -16,12 +16,11 @@ const decision = decide(doc, { placement: 'cart', cart, visitorId, at: new Date(
 
 // Cobrança: o preço de cada linha aceita (com offerId), conferindo as condições de novo com o carrinho real.
 const priced = price(doc, { cart, visitorId, at });
-// priced.lines[i]: { status: 'ok', unitPrice, compareAtPrice } | { status: 'ineligible', reason }
+// priced.lines[i]: { status: 'ok', unitPrice, compareAtPrice, discountedQuantity } | { status: 'ineligible', reason }
 ```
 
-`unitPrice` é por unidade e vale para a **quantidade toda** da linha (duas unidades da oferta custam duas vezes o
-preço da oferta), como a function de desconto do app sempre cobrou (`appliesToEachItem`). `compareAtPrice` é o preço da
-loja no documento, quando maior que o da oferta (o mesmo do `decide`).
+`unitPrice` é por unidade e vale para `discountedQuantity` unidades da linha (0.3.2); o resto da linha vai a preço
+cheio. `compareAtPrice` é o preço da loja no documento, quando maior que o da oferta (o mesmo do `decide`).
 
 `offerKind(doc, offer)` (0.2.0) dá o tipo e a direção de uma oferta cadastrada sem carrinho, com os gatilhos de
 `cart_has_any` no papel do carrinho escolhido: é o que o editor do Commerce OS mostra.
@@ -60,9 +59,8 @@ o `decide` deu ao visitante.
   `visitorId`, `holdout` é sempre `false`.
 - **Só o que a cliente escolheu** é gatilho, subtotal, vaga extra e combo, no `decide` e na reconferência do `price`:
   linha de oferta aceita não sustenta outra. A exceção é a **linha de troca** (`offerId` + `replacedItem` de uma oferta
-  `replace` do documento, item trocado do mesmo produto): é o que a cliente leva no lugar do que escolheu e conta como
-  escolhida para as **outras** ofertas. Para a própria troca vale o item trocado, nunca a linha dela (não se sustenta
-  com o próprio preço). O `replacedItem` fora de `doc.items` é reconhecido pelo `storeProductId` da linha (a troca é no
+  `replace` do documento, item trocado do mesmo produto), que desde a 0.3.2 conta como o **item trocado** para todas as
+  ofertas (ver abaixo). O `replacedItem` fora de `doc.items` é reconhecido pelo `storeProductId` da linha (a troca é no
   mesmo produto da loja). Só conta como escolhida a troca cuja oferta `replace` está ligada (com a variante do
   teste do visitante), dentro da validade no `at` e de tipo que o pacote conhece; senão é linha de oferta comum e não
   sustenta outra oferta.
@@ -75,13 +73,50 @@ o `decide` deu ao visitante.
   ordem do documento, em que a oferta é elegível; nenhuma elegível, a primeira. Linha recusada ainda ocupa a vaga no
   `decide` (a ponte pode cobrá-la cheia); id que o documento não tem não ocupa vaga.
 - **Vitrine e cobrança concordam**: para o mesmo documento e carrinho, toda oferta que o `decide` mostra e a cliente
-  aceita sai `ok` no `price`, ao preço mostrado (é um teste de propriedade do pacote). Para isso a linha acrescentada leva o
+  aceita (e, desde a 0.3.2, toda combinação delas, com troca, vaga extra e combo) sai `ok` no `price`, ao preço
+  mostrado (é um teste de propriedade do pacote). Para isso a linha acrescentada leva o
   `placement` da `DecidedOffer`: com o id em duas posições e sem ele, a regra acima pode atribuir a linha à outra
   posição.
 - **`visitorId` no `price`**: a ponte manda sempre o mesmo `visitorId` (e as mesmas `assignments`) do `decide`. Sem
   ele o `price` não sorteia teste nem confere o grupo de fora geral: cobra o documento sem variante, e quem estava no
   grupo de fora leva a oferta.
 
+## Um carrinho só e quantidade com teto (0.3.2)
+
+- **O carrinho de antes da troca**, no `decide` e no `price`: a linha de troca válida volta a ser o item trocado
+  (`replacedItem`), com a quantidade da linha, como linha escolhida, para **tudo**: gatilho, `cart_has_none`, subtotal,
+  vaga extra, combo e contagem de vagas, da própria troca e das outras ofertas. A linha de troca em si ocupa a vaga da
+  posição dela. Assim o `price` vê exatamente o carrinho que o `decide` viu: a troca LP → 90 não fecha a vaga extra
+  presa à LP, o cross-sell com gatilho na Intense 30 segue valendo depois da troca 30 → 90, e a troca de R$ 199 não
+  destrava o brinde de R$ 250 (no subtotal entra o item trocado, não o novo). Substitui a regra da 0.3.1 ("a linha de
+  troca conta como o produto que a cliente leva").
+- **Subtotal pelo preço do documento**: toda linha escolhida de item listado em `doc.items` entra no subtotal pelo
+  preço do documento; o `unitPrice` da linha só vale para item fora dele (0 sem nenhum dos dois). O item trocado já
+  saiu do carrinho e o pacote não sabe o preço da linha que sumiu: com o preço do documento, as duas chamadas somam
+  igual. Item trocado **fora** do documento conta 0 no subtotal depois da troca (a compilação deve listar os itens que
+  uma troca pode tirar). O `unitPrice` segue sendo teto do preço da linha de oferta.
+- **Troca só na posição dela**: a linha é troca quando a oferta `replace` com aquele `offerId` é a da posição da linha
+  (o `placement` dela, ou a atribuída pela regra de posição abaixo), ligada, na validade, de tipo conhecido, do mesmo
+  item, e o `replacedItem` é do mesmo produto. O mesmo id como `add` em `cart` e `replace` em `product_page`: a linha
+  de `cart` com `replacedItem` forjado é `add` e não sustenta outra oferta.
+- **Alvo da troca sem depender da ordem**: com mais de uma linha escolhida do mesmo produto, o `replaces` é a de menor
+  duração no catálogo e, no empate (ou sem duração), a de menor chave de item (`source:variantId`). Linha que já é
+  troca não é alvo de outra troca.
+- **`maxQuantity`** (campo opcional da oferta, inteiro ≥ 1): quantas unidades da linha levam o preço da oferta.
+  Ausente: **1** quando o preço da oferta dá 0 (brinde), a linha toda nos outros casos. O `price` devolve
+  `discountedQuantity` por linha `ok`; a ponte aplica o desconto só nessas unidades (na Shopify, o desconto de linha
+  com quantidade limitada) e o resto vai a preço cheio. `maxQuantity` que não é inteiro ≥ 1 torna a oferta
+  `unsupported_offer`. Como a 0.3.2 cobra diferente da 0.3.1 com o mesmo documento (o brinde passa a valer uma
+  unidade mesmo sem o campo), o formato subiu para **`schemaVersion` 2**: uma ponte ainda na 0.3.1 recebe
+  `unsupported_schema` e não cobra, em vez de dar o desconto na linha toda.
+- **Linha validada**: `quantity` inteiro ≥ 1 e `unitPrice` (se vier) centavos inteiros ≥ 0. Linha fora disso não é
+  gatilho nem entra no subtotal; a linha de oferta volta `invalid_line`. O pacote nunca devolve `NaN`, negativo ou
+  fração; preço de oferta com valor que não é inteiro também é `unsupported_offer`.
+- **`decisionId`** = sha1 da versão, posição, visitante, carrinho (cada linha com item, quantidade, `unitPrice`,
+  `offerId`, `placement`, `replacedItem`, `storeProductId`, `gift`, sem a ordem) e da **resposta inteira** (cada oferta
+  com preço, alvo da troca, conteúdo e vaga; apresentação, combo, teste, `holdout`). Mesma pergunta e mesma resposta =
+  mesmo id; resposta diferente, outro id. Os ids mudam em relação à 0.3.1.
+
 Motivos de `ineligible`: `unknown_offer`, `inactive`, `item_mismatch`, `not_started`, `expired`, `trigger_missing`,
 `subtotal_out_of_range`, `unsupported_schema` e, desde a 0.3.1:
 
@@ -92,6 +127,7 @@ Motivos de `ineligible`: `unknown_offer`, `inactive`, `item_mismatch`, `not_star
 | `no_slot` | A posição já tem as vagas tomadas por ofertas de prioridade maior, ou a oferta/item já vale em outra linha |
 | `unsupported_offer` | Condição, preço ou ação de tipo que o pacote não conhece (o `decide` também não mostra) |
 | `invalid_instant` | Oferta com validade e `at` (ou a validade) ilegível |
+| `invalid_line` (0.3.2) | Linha com `quantity` que não é inteiro ≥ 1 ou `unitPrice` que não é centavo inteiro ≥ 0 |
 
 Documento com `schemaVersion` maior que `SUPPORTED_SCHEMA_VERSION` não é decidido nem precificado: a resposta vem com
 `status: 'unsupported_schema'` (e toda linha do `price` inelegível com esse motivo). Atualize o pacote.

package/dist/assess.d.ts

@@ -4,13 +4,15 @@ import type { SlotClaim } from './slots.js';
 import type { Offer, OfferDocument } from './types.js';
 /**
  * A avaliação das linhas de oferta do carrinho, a mesma no `decide` (as vagas já tomadas) e no `price` (a cobrança).
- * O `input` é só o que as duas chamadas têm em comum: carrinho, instante, visitante e atribuições.
+ * O `input` é só o que as duas chamadas têm em comum: carrinho, instante, visitante e atribuições. `placed` é a oferta
+ * do documento a que cada linha de oferta foi atribuída (a regra de posição), e `isSwap` sai dela.
  */
 export interface Assessor {
     doc: OfferDocument;
     items: ItemIndex;
     input: PriceInput;
     isSwap: SwapCheck;
+    placed: Map<number, Offer>;
 }
 /** Uma linha de oferta avaliada: a posição a que ela foi atribuída e, se passou, a oferta que disputa a vaga. */
 export interface Assessed {
@@ -22,6 +24,10 @@ export interface Assessed {
 export declare const refused: (index: number, offerId: string, reason: IneligibleReason) => PricedLine;
 /** O portão da oferta em si, sem carrinho: tipo que o pacote conhece, ligada e dentro da validade. */
 export declare function offerGate(offer: Offer, at: string): IneligibleReason | null;
+/**
+ * Duas passadas: primeiro as trocas que a própria linha define (o id numa posição só, ou a posição da linha); com elas,
+ * a posição de cada linha de oferta; daí as trocas de fato (`replace` na posição atribuída), que valem para tudo.
+ */
 export declare function assessor(doc: OfferDocument, items: ItemIndex, input: PriceInput): Assessor;
 /** Toda linha com `offerId`, brinde ou não, na ordem do carrinho: é linha de oferta, e disputa a vaga da posição dela. */
 export declare function assessOfferLines(ctx: Assessor): Assessed[];

package/dist/assess.js

@@ -1,8 +1,8 @@
-import { isSameProductSwap, itemKey, replacedLine, viewCart } from './cart.js';
-import { conditionsFailure, isSupportedOffer, validityFailure } from './conditions.js';
+import { isSameProductSwap, isValidLine, itemKey, viewCart } from './cart.js';
+import { conditionsFailure, isSellable, isSupportedOffer, validityFailure } from './conditions.js';
 import { applyVariant } from './effective.js';
 import { assignExperiment } from './experiments.js';
-import { compareAtPrice, offerUnitPrice } from './money.js';
+import { compareAtPrice, discountedQuantity, offerUnitPrice } from './money.js';
 export const refused = (index, offerId, reason) => ({ index, offerId, status: 'ineligible', reason });
 /** A oferta do documento como o visitante a vê: com a variante do teste da posição dela. */
 function liveOffer(doc, found, input) {
@@ -17,48 +17,60 @@ export function offerGate(offer, at) {
     return validityFailure(offer, at);
 }
 /**
- * Linha de troca: uma oferta `replace` do documento com aquele id e aquele item, que passa no portão (com a variante
- * do visitante e o `at`), e o item trocado do mesmo produto. Forjar os campos só rende o que o caminho legítimo daria;
- * a troca desligada, vencida ou de tipo desconhecido é linha de oferta comum, e não sustenta outra oferta.
+ * Troca viva: a oferta (a da posição da linha) é `replace` daquele item, passa no portão com a variante do visitante e
+ * o `at`, e a linha é válida e diz que trocou um item do mesmo produto. Forjar os campos só rende o que o caminho
+ * legítimo daria; a troca desligada, vencida, de tipo desconhecido ou de outra posição é linha de oferta comum.
  */
-function swapCheck(doc, items, input) {
-    const isLiveReplace = (offer, line) => offer.id === line.offerId && offer.action === 'replace' && itemKey(offer.item) === itemKey(line.item) && offerGate(liveOffer(doc, offer, input), input.at) === null;
-    return (line) => line.offerId !== undefined && isSameProductSwap(items, line) && doc.offers.some((offer) => isLiveReplace(offer, line));
+function isLiveSwap(ctx, offer, line) {
+    if (offer.action !== 'replace' || itemKey(offer.item) !== itemKey(line.item))
+        return false;
+    if (!isValidLine(line) || !isSameProductSwap(ctx.items, line))
+        return false;
+    return offerGate(liveOffer(ctx.doc, offer, ctx.input), ctx.input.at) === null;
 }
-export function assessor(doc, items, input) {
-    return { doc, items, input, isSwap: swapCheck(doc, items, input) };
+/** As ofertas que podem valer para a linha: a da posição dela, quando o id está lá; senão todas com o id. */
+function lineOptions(doc, line) {
+    const same = doc.offers.filter((offer) => offer.id === line.offerId);
+    const declared = same.filter((offer) => offer.placement === line.placement);
+    return declared.length > 0 ? declared : same;
+}
+/** As posições do carrinho que são troca, calculadas uma vez (o sorteio do teste não roda a cada linha). */
+function swapSet(cart, offerOf, isSwap) {
+    const swaps = new Set(cart.flatMap((line, index) => {
+        const offer = line.offerId ? offerOf(line, index) : undefined;
+        return offer && isSwap(offer, line) ? [index] : [];
+    }));
+    return (index) => swaps.has(index);
 }
 /**
- * O carrinho como no instante em que a oferta apareceu: só o que a cliente escolheu (com as linhas de troca), sem a
- * própria linha e, no `replace`, com o item trocado de volta no lugar. Nulo quando o `replace` não diz o que trocou,
- * ou diz um item que não é o mesmo produto.
+ * O carrinho como no instante em que a oferta apareceu, o de antes da troca: só o que a cliente escolheu (as trocas
+ * de volta ao item trocado), sem a própria linha no `add` e, no `replace`, com ela de volta ao item trocado. Nulo
+ * quando o `replace` não diz o que trocou, ou diz um item que não é o mesmo produto.
  */
 function recheckView(ctx, offer, index) {
     const line = ctx.input.cart[index];
-    const others = ctx.input.cart.filter((_, position) => position !== index);
     if (offer.action === 'add')
-        return viewCart(ctx.items, others, ctx.isSwap);
-    const replaced = replacedLine(line);
-    if (!replaced || !isSameProductSwap(ctx.items, line))
+        return viewCart(ctx.items, ctx.input.cart, ctx.isSwap, index);
+    if (!isSameProductSwap(ctx.items, line))
         return null;
-    return viewCart(ctx.items, [...others, replaced], ctx.isSwap);
+    return viewCart(ctx.items, ctx.input.cart, (position) => position === index || ctx.isSwap(position));
 }
 function lineFailure(ctx, offer, index) {
     const line = ctx.input.cart[index];
-    if (!isSupportedOffer(offer))
-        return 'unsupported_offer';
-    if (!offer.active)
-        return 'inactive';
+    if (!isValidLine(line))
+        return 'invalid_line';
+    const gate = offerGate(offer, ctx.input.at);
+    if (gate === 'unsupported_offer' || gate === 'inactive')
+        return gate;
     const item = ctx.items.get(itemKey(offer.item));
     if (!item)
         return 'unknown_offer';
     if (itemKey(line.item) !== itemKey(offer.item))
         return 'item_mismatch';
-    if (!item.available || item.price <= 0)
+    if (!isSellable(item))
         return 'unavailable';
-    const validity = validityFailure(offer, ctx.input.at);
-    if (validity)
-        return validity;
+    if (gate)
+        return gate;
     const view = recheckView(ctx, offer, index);
     if (!view)
         return 'trigger_missing';
@@ -74,26 +86,56 @@ function assessOffer(ctx, found, index) {
     if (reason)
         return { priced: refused(index, offerId, reason), claim: null, placement: found.placement };
     const storePrice = ctx.items.get(itemKey(offer.item)).price;
-    const unitPrice = Math.min(offerUnitPrice(offer.price, storePrice), line.unitPrice ?? storePrice);
-    const priced = { index, offerId, status: 'ok', unitPrice, compareAtPrice: compareAtPrice(storePrice, unitPrice) };
+    const offerPrice = offerUnitPrice(offer.price, storePrice);
+    const unitPrice = Math.min(offerPrice, line.unitPrice ?? storePrice);
+    const priced = {
+        index,
+        offerId,
+        status: 'ok',
+        unitPrice,
+        compareAtPrice: compareAtPrice(storePrice, unitPrice),
+        discountedQuantity: discountedQuantity(line.quantity, offer.maxQuantity, offerPrice),
+    };
     return { priced, claim: { index, offer, order: ctx.doc.offers.indexOf(found) }, placement: found.placement };
 }
 /**
  * A atribuição de posição de uma linha de oferta, a única do pacote. O id repetido em duas posições (oferta migrada do
  * app) desempata pela posição da linha. Sem ela (ou com uma que não tem o id), vale a primeira posição, na ordem do
  * documento, em que a oferta é elegível; nenhuma elegível, a primeira. Id que o documento não tem não fica em posição.
+ * A elegibilidade desse desempate é medida com as trocas cuja posição a linha já define (`declared`).
  */
-function assessLine(ctx, line, index) {
-    const offerId = line.offerId;
-    const same = ctx.doc.offers.filter((offer) => offer.id === offerId);
-    const declared = same.filter((offer) => offer.placement === line.placement);
-    const options = declared.length > 0 ? declared : same;
-    if (options.length === 0)
-        return { priced: refused(index, offerId, 'unknown_offer'), claim: null, placement: null };
-    const results = options.map((offer) => assessOffer(ctx, offer, index));
-    return results.find((result) => result.claim !== null) ?? results[0];
+function placeLines(declared) {
+    const placed = new Map();
+    declared.input.cart.forEach((line, index) => {
+        const options = line.offerId ? lineOptions(declared.doc, line) : [];
+        const pick = options.length > 1 ? options.find((offer) => assessOffer(declared, offer, index).claim !== null) : undefined;
+        const offer = pick ?? options[0];
+        if (offer)
+            placed.set(index, offer);
+    });
+    return placed;
+}
+/**
+ * Duas passadas: primeiro as trocas que a própria linha define (o id numa posição só, ou a posição da linha); com elas,
+ * a posição de cada linha de oferta; daí as trocas de fato (`replace` na posição atribuída), que valem para tudo.
+ */
+export function assessor(doc, items, input) {
+    const base = { doc, items, input };
+    const declaredOffer = (line) => {
+        const options = lineOptions(doc, line);
+        return options.length === 1 ? options[0] : undefined;
+    };
+    const declaredSwap = swapSet(input.cart, declaredOffer, (offer, line) => isLiveSwap(base, offer, line));
+    const placed = placeLines({ ...base, isSwap: declaredSwap, placed: new Map() });
+    const isSwap = swapSet(input.cart, (_, index) => placed.get(index), (offer, line) => isLiveSwap(base, offer, line));
+    return { ...base, isSwap, placed };
 }
 /** Toda linha com `offerId`, brinde ou não, na ordem do carrinho: é linha de oferta, e disputa a vaga da posição dela. */
 export function assessOfferLines(ctx) {
-    return ctx.input.cart.flatMap((line, index) => (line.offerId ? [assessLine(ctx, line, index)] : []));
+    return ctx.input.cart.flatMap((line, index) => {
+        if (!line.offerId)
+            return [];
+        const offer = ctx.placed.get(index);
+        return [offer ? assessOffer(ctx, offer, index) : { priced: refused(index, line.offerId, 'unknown_offer'), claim: null, placement: null }];
+    });
 }

package/dist/cart.d.ts

@@ -8,13 +8,16 @@ export interface ResolvedLine {
     storeProductId: string | null;
     catalogProductIds: string[];
     durationDays: number | null;
+    /** Linha de troca vista como o item que ela trocou (o carrinho de antes da troca): não é alvo de outra troca. */
+    swapped: boolean;
 }
 /**
- * O carrinho do ponto de vista do motor. O gatilho e o subtotal são só o que a cliente escolheu: brinde e linha de
- * oferta aceita ficam fora, senão a oferta aceita vira gatilho da próxima ("a fila que não acaba", app ADR 0006) ou
- * sustenta o subtotal da outra. A exceção é a **linha de troca** (`replace`): ela é o produto que a cliente leva no
- * lugar do que escolheu, e conta como escolhida para as outras ofertas. `keys` é o carrinho inteiro: não se oferece o
- * que ela já tem, venha de onde vier.
+ * O carrinho do ponto de vista do motor, **o de antes da troca**, o mesmo no `decide` e no `price` (pacote 0.3.2).
+ * O gatilho, o subtotal, a vaga extra e o combo são só o que a cliente escolheu: brinde e linha de oferta aceita ficam
+ * fora, senão a oferta aceita vira gatilho da próxima ("a fila que não acaba", app ADR 0006) ou sustenta o subtotal da
+ * outra. A **linha de troca** (`replace`) volta a ser o item trocado, com a quantidade dela: a vitrine decidiu com ele
+ * no carrinho, e a cobrança confere o mesmo carrinho. Linha com quantidade ou preço inválido não conta. `keys` é o
+ * carrinho inteiro, com o item trocado: não se oferece o que ela tem (ou acabou de trocar), venha de onde vier.
  */
 export interface CartView {
     chosen: ResolvedLine[];
@@ -24,14 +27,17 @@ export interface CartView {
 }
 export type ItemIndex = Map<string, OfferItem>;
 export declare function indexItems(doc: OfferDocument): ItemIndex;
-export declare function resolveLine(items: ItemIndex, line: CartLine): ResolvedLine;
+export declare function resolveLine(items: ItemIndex, line: CartLine, swapped?: boolean): ResolvedLine;
+/** Quantidade inteira ≥ 1 e, se vier, preço em centavos inteiros ≥ 0. A linha fora disso não é gatilho nem é cobrada. */
+export declare function isValidLine(line: CartLine): boolean;
 /** O item que a troca tirou, como linha; fora do documento, ele é do produto da loja da linha (a troca é no mesmo produto). */
 export declare function replacedLine(line: CartLine): CartLine | null;
 /** A linha diz que trocou um item do mesmo produto pelo ofertado. Só a forma: se a troca ainda vale é o `price` que diz. */
 export declare function isSameProductSwap(items: ItemIndex, line: CartLine): boolean;
-/** A linha é de troca (`assess.ts`): conta como escolhida. */
-export type SwapCheck = (line: CartLine) => boolean;
-export declare function viewCart(items: ItemIndex, lines: CartLine[], isSwap: SwapCheck): CartView;
+/** A linha nesta posição do carrinho é uma troca válida (`assess.ts`): no carrinho de antes, ela é o item trocado. */
+export type SwapCheck = (index: number) => boolean;
+/** `omit`: a posição da linha que fica de fora (a própria linha de oferta, na reconferência dela). */
+export declare function viewCart(items: ItemIndex, cart: CartLine[], isSwap: SwapCheck, omit?: number): CartView;
 export declare function lineMatches(match: ProductMatch, line: ResolvedLine): boolean;
 export declare function anyLineMatches(match: ProductMatch, lines: ResolvedLine[]): boolean;
 /**

package/dist/cart.js

@@ -2,7 +2,7 @@ export const itemKey = (ref) => `${ref.source}:${ref.variantId}`;
 export function indexItems(doc) {
     return new Map(doc.items.map((item) => [itemKey(item), item]));
 }
-export function resolveLine(items, line) {
+export function resolveLine(items, line, swapped = false) {
     const key = itemKey(line.item);
     const item = items.get(key);
     return {
@@ -11,10 +11,21 @@ export function resolveLine(items, line) {
         storeProductId: item?.storeProductId ?? line.storeProductId ?? null,
         catalogProductIds: item?.catalogProductIds ?? [],
         durationDays: item?.durationDays ?? null,
+        swapped,
     };
 }
+const isCents = (value) => Number.isSafeInteger(value) && value >= 0;
+/** Quantidade inteira ≥ 1 e, se vier, preço em centavos inteiros ≥ 0. A linha fora disso não é gatilho nem é cobrada. */
+export function isValidLine(line) {
+    return Number.isSafeInteger(line.quantity) && line.quantity >= 1 && (line.unitPrice === undefined || isCents(line.unitPrice));
+}
+/**
+ * Valor da linha no subtotal: o preço do **documento** quando o item está nele, o `unitPrice` da linha só quando não
+ * está (0 sem nenhum dos dois). O item trocado não tem linha no carrinho de depois; com o preço do documento para todo
+ * item listado, o `decide` (antes) e o `price` (depois) somam o mesmo.
+ */
 function lineTotal(items, line) {
-    const unit = line.unitPrice ?? items.get(itemKey(line.item))?.price ?? 0;
+    const unit = items.get(itemKey(line.item))?.price ?? line.unitPrice ?? 0;
     return unit * line.quantity;
 }
 /** O item que a troca tirou, como linha; fora do documento, ele é do produto da loja da linha (a troca é no mesmo produto). */
@@ -29,14 +40,28 @@ export function isSameProductSwap(items, line) {
     const replaced = replacedLine(line);
     return replaced !== null && sameProduct(resolveLine(items, replaced), resolveLine(items, line));
 }
-export function viewCart(items, lines, isSwap) {
-    const resolved = lines.map((line) => resolveLine(items, line));
-    const chosen = resolved.filter(({ line }) => !line.gift && (!line.offerId || isSwap(line)));
-    return {
-        chosen,
-        keys: new Set(resolved.map(({ key }) => key)),
-        subtotal: chosen.reduce((sum, { line }) => sum + lineTotal(items, line), 0),
-    };
+/** A linha como o carrinho de antes da troca a vê: escolhida, trocada (o item que saiu) ou fora (oferta, brinde, inválida). */
+function chosenAs(items, line, swap) {
+    if (line.gift || !isValidLine(line))
+        return null;
+    const replaced = swap ? replacedLine(line) : null;
+    if (replaced)
+        return resolveLine(items, replaced, true);
+    return line.offerId ? null : resolveLine(items, line);
+}
+/** `omit`: a posição da linha que fica de fora (a própria linha de oferta, na reconferência dela). */
+export function viewCart(items, cart, isSwap, omit = -1) {
+    const chosen = [];
+    const keys = new Set();
+    cart.forEach((line, index) => {
+        keys.add(itemKey(line.item));
+        const seen = index === omit ? null : chosenAs(items, line, isSwap(index));
+        if (seen)
+            chosen.push(seen);
+        if (seen?.swapped)
+            keys.add(seen.key);
+    });
+    return { chosen, keys, subtotal: chosen.reduce((sum, { line }) => sum + lineTotal(items, line), 0) };
 }
 export function lineMatches(match, line) {
     if (match.items?.some((ref) => itemKey(ref) === line.key))

package/dist/conditions.d.ts

@@ -1,6 +1,6 @@
 import { type CartView } from './cart.js';
 import type { IneligibleReason } from './io.js';
-import type { Offer, OfferCondition } from './types.js';
+import type { Offer, OfferCondition, OfferItem } from './types.js';
 /** `excluded` só existe no `decide`: o "produto que esconde" esconde a oferta, mas não desfaz a já aceita (app ADR 0025). */
 export type GateFailure = IneligibleReason | 'excluded';
 /**
@@ -8,6 +8,8 @@ export type GateFailure = IneligibleReason | 'excluded';
  * pode trazer um tipo que este não sabe avaliar: a oferta não vale, em vez de passar ou cobrar `NaN`.
  */
 export declare function isSupportedOffer(offer: Offer): boolean;
+/** Item vendável pela oferta: disponível e com preço da loja em centavos > 0 (sem ele a compilação grava 0, e a oferta sairia de graça). */
+export declare const isSellable: (item: OfferItem | undefined) => item is OfferItem;
 /** Validade: início inclusivo, fim exclusivo. Com validade, um instante ilegível (o `at` ou a própria validade) não vale. */
 export declare function validityFailure(offer: Offer, at: string): 'not_started' | 'expired' | 'invalid_instant' | null;
 /**

package/dist/conditions.js

@@ -7,8 +7,11 @@ const ACTIONS = new Set(['add', 'replace']);
  * pode trazer um tipo que este não sabe avaliar: a oferta não vale, em vez de passar ou cobrar `NaN`.
  */
 export function isSupportedOffer(offer) {
-    return isKnownPrice(offer.price) && ACTIONS.has(offer.action) && offer.conditions.every((condition) => CONDITION_TYPES.has(condition.type));
+    const quantity = offer.maxQuantity === undefined || (Number.isSafeInteger(offer.maxQuantity) && offer.maxQuantity >= 1);
+    return quantity && isKnownPrice(offer.price) && ACTIONS.has(offer.action) && offer.conditions.every((condition) => CONDITION_TYPES.has(condition.type));
 }
+/** Item vendável pela oferta: disponível e com preço da loja em centavos > 0 (sem ele a compilação grava 0, e a oferta sairia de graça). */
+export const isSellable = (item) => item !== undefined && item.available && Number.isSafeInteger(item.price) && item.price > 0;
 /** Validade: início inclusivo, fim exclusivo. Com validade, um instante ilegível (o `at` ou a própria validade) não vale. */
 export function validityFailure(offer, at) {
     if (offer.validFrom === undefined && offer.validUntil === undefined)

package/dist/decide.js

@@ -1,6 +1,6 @@
 import { assessOfferLines, assessor, offerGate } from './assess.js';
 import { anyLineMatches, indexItems, itemKey, resolveLine, viewCart } from './cart.js';
-import { conditionsFailure } from './conditions.js';
+import { conditionsFailure, isSellable } from './conditions.js';
 import { placementOffers } from './effective.js';
 import { assignExperiment, inHoldout } from './experiments.js';
 import { classify } from './kind.js';
@@ -17,17 +17,23 @@ function openSlots(ctx) {
     const taken = ctx.accepted.filter((assessed) => assessed.placement === ctx.placement.key).length;
     return Math.max(0, slotsFor(ctx.placement, ctx.view) - taken);
 }
-/** Item vendável pela oferta: disponível e com preço da loja (sem ele a compilação grava 0, e a oferta sairia de graça). */
-const sellable = (item) => item !== undefined && item.available && item.price > 0;
+/**
+ * O tipo pela linha escolhida do mesmo produto. A troca só mira linha escolhida de fato: a que já é troca (vista como o
+ * item que saiu) não tem linha no carrinho para a ponte trocar de novo.
+ */
+function classifyOffer(ctx, offer) {
+    const pool = offer.action === 'replace' ? ctx.view.chosen.filter((line) => !line.swapped) : ctx.view.chosen;
+    return classify(resolveLine(ctx.items, { item: offer.item, quantity: 1 }), pool);
+}
 function candidate(ctx, offer) {
     if (offerGate(offer, ctx.at))
         return null;
     const item = ctx.items.get(itemKey(offer.item));
-    if (!sellable(item) || ctx.view.keys.has(itemKey(offer.item)))
+    if (!isSellable(item) || ctx.view.keys.has(itemKey(offer.item)))
         return null;
     if (conditionsFailure(offer.conditions, ctx.view, 'decide'))
         return null;
-    const classification = classify(resolveLine(ctx.items, { item: offer.item, quantity: 1 }), ctx.view.chosen);
+    const classification = classifyOffer(ctx, offer);
     if (offer.action === 'replace' && !classification.target)
         return null;
     return { offer, item, classification };
@@ -54,23 +60,26 @@ function groupingFor(ctx) {
     const groupings = ctx.variant?.groupings ?? ctx.placement.groupings ?? [];
     return groupings.find((grouping) => anyLineMatches(grouping.when, ctx.view.chosen))?.presentation ?? null;
 }
+/** A linha com tudo o que muda a decisão (troca, posição, produto, preço), sem depender da ordem do carrinho. */
+function lineKey(line) {
+    const replaced = line.replacedItem ? itemKey(line.replacedItem) : '';
+    return JSON.stringify([itemKey(line.item), line.quantity, line.unitPrice ?? null, line.offerId ?? '', line.placement ?? '', replaced, line.storeProductId ?? '', line.gift ? 1 : 0]);
+}
 /**
- * Mesmo documento, carrinho, visitante e resposta = mesmo id (ADR-0083 §1, princípio 3). O instante não entra: duas
+ * Mesma pergunta e mesma resposta = mesmo id (ADR-0083 §1, princípio 3); resposta diferente, outro (pacote 0.3.2: o
+ * hash leva a resposta inteira, com preço, alvo da troca e conteúdo de cada oferta). O instante não entra: duas
  * perguntas iguais seguidas são a mesma decisão. A ordem das linhas também não.
  */
-function decisionIdOf(input, version, offerIds, experiments) {
-    const cart = input.cart
-        .map((line) => [itemKey(line.item), line.quantity, line.offerId ?? '', line.gift ? 1 : 0].join('*'))
-        .sort();
-    const canonical = JSON.stringify([version, input.placement, input.visitorId ?? '', cart, offerIds, experiments]);
-    return `dec_${sha1Hex(canonical).slice(0, 24)}`;
+function withDecisionId(input, version, answer) {
+    const cart = input.cart.map(lineKey).sort();
+    const decisionId = `dec_${sha1Hex(JSON.stringify([version, input.placement, input.visitorId ?? '', cart, answer])).slice(0, 24)}`;
+    return { ...answer, decisionId, offers: answer.offers.map((offer) => ({ ...offer, decisionId })) };
 }
-function toDecided(ctx, pick, slot, decisionId) {
+function toDecided(ctx, pick, slot) {
     const { offer, item, classification } = pick;
     const price = offerUnitPrice(offer.price, item.price);
     return {
         offerId: offer.id,
-        decisionId,
         placement: ctx.placement.key,
         slot,
         kind: classification.kind,
@@ -95,8 +104,7 @@ function placementPresentation(ctx) {
  * grupo de fora geral responde vazio com `holdout: true`.
  */
 function emptyDecision(doc, input, status, holdout = false) {
-    const decisionId = decisionIdOf(input, doc.version, [], []);
-    return { status, version: doc.version, placement: input.placement, decisionId, offers: [], presentation: null, grouping: null, experiments: [], holdout };
+    return withDecisionId(input, doc.version, { status, version: doc.version, placement: input.placement, offers: [], presentation: null, grouping: null, experiments: [], holdout });
 }
 /**
  * As ofertas que valem para esta posição e este carrinho, com preço, tipo calculado e o teste sorteado. Respeita
@@ -118,16 +126,14 @@ export function decide(doc, input) {
     const ctx = { doc, items, view, accepted: assessOfferLines(assess), placement, variant: assignment?.variant ?? null, at: input.at };
     const picks = pickOffers(ctx);
     const experiments = assignment ? [{ key: assignment.experiment.key, variant: assignment.variant.key }] : [];
-    const decisionId = decisionIdOf(input, doc.version, picks.map((pick) => pick.offer.id), experiments);
-    return {
+    return withDecisionId(input, doc.version, {
         status: 'ok',
         version: doc.version,
         placement: placement.key,
-        decisionId,
-        offers: picks.map((pick, index) => toDecided(ctx, pick, index + 1, decisionId)),
+        offers: picks.map((pick, index) => toDecided(ctx, pick, index + 1)),
         presentation: placementPresentation(ctx),
         grouping: groupingFor(ctx),
         experiments,
         holdout: false,
-    };
+    });
 }

package/dist/io.d.ts

@@ -2,8 +2,13 @@ import type { Cents, ItemRef, OfferAction, OfferContent } from './types.js';
 /** Uma linha do carrinho como a ponte a vê. */
 export interface CartLine {
     item: ItemRef;
+    /** Inteiro ≥ 1; fora disso a linha não é gatilho nem entra no subtotal, e a linha de oferta volta `invalid_line`. */
     quantity: number;
-    /** O que a loja cobra por unidade agora; sem ele vale o preço do item no documento (0 se ele não estiver lá). */
+    /**
+     * O que a loja cobra por unidade agora (centavos inteiros ≥ 0; fora disso, como `quantity`). Teto do preço da linha
+     * de oferta. No subtotal só vale para item **fora** do documento: o item listado conta pelo preço do documento, o
+     * mesmo que o item trocado (que já saiu do carrinho) tem, para o `decide` e o `price` somarem igual.
+     */
     unitPrice?: Cents;
     /**
      * Produto da loja da linha, para o item que o documento não lista (o produto que a cliente escolheu). Na linha de
@@ -15,9 +20,10 @@ export interface CartLine {
     /** A posição de onde a oferta aceita veio (o `placement` da `DecidedOffer`); desempata o id repetido em duas posições. */
     placement?: string;
     /**
-     * Na ação `replace`: o item que a oferta trocou. `price()` confere a condição da própria troca como se ele ainda
-     * estivesse lá; para as outras ofertas, a linha de troca conta como o produto que a cliente leva (gatilho, subtotal,
-     * vaga extra, combo).
+     * Na ação `replace`: o item que a oferta trocou. O motor avalia o **carrinho de antes da troca** (pacote 0.3.2): para
+     * todas as ofertas, a própria e as outras, a linha de troca volta a ser este item, com a quantidade dela (gatilho,
+     * `cart_has_none`, subtotal pelo preço do documento, vaga extra, combo). A linha em si ocupa a vaga da posição dela.
+     * Só é troca quando a oferta `replace` com o `offerId` está na posição da linha (a dela, ou a da regra de posição).
      */
     replacedItem?: ItemRef;
     /** Brinde: não é escolha da cliente nem entra no subtotal. Com `offerId`, segue linha de oferta e ocupa a vaga. */
@@ -57,7 +63,10 @@ export interface DecidedOffer {
     pricePerDay: Cents | null;
     currency: string;
     action: OfferAction;
-    /** O item que a cliente leva e a oferta troca, na ação `replace`. */
+    /**
+     * O item que a cliente leva e a oferta troca, na ação `replace`: a linha escolhida do mesmo produto (nunca uma que já
+     * é troca) de menor duração, e no empate a de menor chave de item, sem depender da ordem das linhas.
+     */
     replaces: ItemRef | null;
     content: OfferContent;
     presentation: string | null;
@@ -68,7 +77,11 @@ export interface Decision {
     status: ResultStatus;
     version: number;
     placement: string;
-    /** Mesmo documento, carrinho, visitante e resposta = mesmo id. Sai também sem oferta (para o `exposed`). */
+    /**
+     * sha1 da versão, posição, visitante, carrinho (sem ordem) e da **resposta inteira** (ofertas com preço, alvo da
+     * troca, conteúdo; apresentação, combo, teste): mesma pergunta e mesma resposta = mesmo id; resposta diferente, outro.
+     * Sai também sem oferta (para o `exposed`).
+     */
     decisionId: string;
     offers: DecidedOffer[];
     /** Apresentação padrão da posição (já com a variante do teste). */
@@ -105,13 +118,17 @@ export type IneligibleReason = 'unknown_offer' | 'inactive' | 'item_mismatch' |
 /** O `at` (ou a validade da oferta) não é um instante legível, e a oferta tem validade. */
  | 'invalid_instant'
 /** O documento é de um formato mais novo que o pacote: toda linha volta com este motivo. */
- | 'unsupported_schema';
+ | 'unsupported_schema'
+/** A linha tem `quantity` que não é inteiro ≥ 1, ou `unitPrice` que não é centavo inteiro ≥ 0 (pacote 0.3.2). */
+ | 'invalid_line';
 export type PricedLine = {
     index: number;
     offerId: string;
     status: 'ok';
     unitPrice: Cents;
     compareAtPrice: Cents | null;
+    /** Quantas unidades da linha levam o `unitPrice` (o `maxQuantity` da oferta); o resto vai a preço cheio. */
+    discountedQuantity: number;
 } | {
     index: number;
     offerId: string;

package/dist/kind.d.ts

@@ -9,7 +9,8 @@ export interface Classification {
 }
 /**
  * Tipo calculado, nunca cadastrado (ADR-0083 §3; a mesma regra do `offerKindExpr` da análise): upsell quando o carrinho
- * escolhido já tem o mesmo produto, cross-sell quando é outro. A direção sai da duração no catálogo.
+ * escolhido já tem o mesmo produto, cross-sell quando é outro. A direção sai da duração no catálogo. Com mais de uma
+ * linha do mesmo produto, o alvo (o que a `replace` troca) é a de menor duração, e no empate a de menor chave de item.
  */
 export declare function classify(offered: ResolvedLine, chosen: ResolvedLine[]): Classification;
 /**

package/dist/kind.js

@@ -6,12 +6,20 @@ function directionOf(offered, target) {
         return null;
     return offered.durationDays > target.durationDays ? 'up' : 'down';
 }
+/** Menor duração primeiro (sem duração por último), depois a chave do item: o alvo não depende da ordem das linhas. */
+function byTarget(a, b) {
+    const byDuration = (a.durationDays ?? Number.MAX_SAFE_INTEGER) - (b.durationDays ?? Number.MAX_SAFE_INTEGER);
+    if (byDuration !== 0)
+        return byDuration;
+    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+}
 /**
  * Tipo calculado, nunca cadastrado (ADR-0083 §3; a mesma regra do `offerKindExpr` da análise): upsell quando o carrinho
- * escolhido já tem o mesmo produto, cross-sell quando é outro. A direção sai da duração no catálogo.
+ * escolhido já tem o mesmo produto, cross-sell quando é outro. A direção sai da duração no catálogo. Com mais de uma
+ * linha do mesmo produto, o alvo (o que a `replace` troca) é a de menor duração, e no empate a de menor chave de item.
  */
 export function classify(offered, chosen) {
-    const target = chosen.find((line) => sameProduct(offered, line)) ?? null;
+    const target = chosen.filter((line) => sameProduct(offered, line)).sort(byTarget)[0] ?? null;
     if (!target)
         return { kind: 'cross_sell', direction: null, target: null };
     return { kind: 'upsell', direction: directionOf(offered, target), target };
@@ -22,8 +30,8 @@ function triggerLines(items, offer) {
     const matches = offer.conditions.flatMap((condition) => (condition.type === 'cart_has_any' ? [condition.match] : []));
     return matches.flatMap((match) => [
         ...(match.items ?? []).map((item) => resolveLine(items, { item, quantity: 1 })),
-        ...(match.storeProductIds ?? []).map((id) => ({ line: BLANK_LINE, key: '', storeProductId: id, catalogProductIds: [], durationDays: null })),
-        ...(match.catalogProductIds ?? []).map((id) => ({ line: BLANK_LINE, key: '', storeProductId: null, catalogProductIds: [id], durationDays: null })),
+        ...(match.storeProductIds ?? []).map((id) => ({ line: BLANK_LINE, key: '', storeProductId: id, catalogProductIds: [], durationDays: null, swapped: false })),
+        ...(match.catalogProductIds ?? []).map((id) => ({ line: BLANK_LINE, key: '', storeProductId: null, catalogProductIds: [id], durationDays: null, swapped: false })),
     ]);
 }
 /**

package/dist/money.d.ts

@@ -1,6 +1,11 @@
 import type { Cents, OfferPrice } from './types.js';
-/** O preço é de um tipo que o pacote sabe calcular, com número no campo do valor. */
+/** O preço é de um tipo que o pacote sabe calcular, com inteiro no campo do valor (centavos; pontos-base até 100%). */
 export declare function isKnownPrice(price: OfferPrice): boolean;
+/**
+ * Quantas unidades da linha levam o preço da oferta: o `maxQuantity` da oferta; sem ele, **1** quando a oferta sai de
+ * graça (brinde) e a linha toda nos outros casos. O resto da linha vai a preço cheio.
+ */
+export declare function discountedQuantity(quantity: number, maxQuantity: number | undefined, offerPrice: Cents): number;
 /**
  * Preço da oferta por unidade, a partir do preço da loja. O desconto percentual é arredondado meio para cima (15% de
  * 79,90 = 11,985 → 11,99, cobra 67,91). A oferta é **teto**, nunca acréscimo: o resultado fica entre 0 e o preço da

package/dist/money.js

@@ -2,14 +2,23 @@
 function divideHalfUp(numerator, denominator) {
     return Math.floor((2 * numerator + denominator) / (2 * denominator));
 }
-/** O preço é de um tipo que o pacote sabe calcular, com número no campo do valor. */
+const isWhole = (value, max = Number.MAX_SAFE_INTEGER) => Number.isSafeInteger(value) && value >= 0 && value <= max;
+/** O preço é de um tipo que o pacote sabe calcular, com inteiro no campo do valor (centavos; pontos-base até 100%). */
 export function isKnownPrice(price) {
     if (price.type === 'percent_off')
-        return Number.isFinite(price.basisPoints);
+        return isWhole(price.basisPoints, 10_000);
     if (price.type === 'fixed' || price.type === 'amount_off')
-        return Number.isFinite(price.amount);
+        return isWhole(price.amount);
     return false;
 }
+/**
+ * Quantas unidades da linha levam o preço da oferta: o `maxQuantity` da oferta; sem ele, **1** quando a oferta sai de
+ * graça (brinde) e a linha toda nos outros casos. O resto da linha vai a preço cheio.
+ */
+export function discountedQuantity(quantity, maxQuantity, offerPrice) {
+    const cap = maxQuantity ?? (offerPrice === 0 ? 1 : quantity);
+    return Math.min(quantity, cap);
+}
 /**
  * Preço da oferta por unidade, a partir do preço da loja. O desconto percentual é arredondado meio para cima (15% de
  * 79,90 = 11,985 → 11,99, cobra 67,91). A oferta é **teto**, nunca acréscimo: o resultado fica entre 0 e o preço da

package/dist/price.d.ts

@@ -3,8 +3,9 @@ import type { OfferDocument } from './types.js';
 /**
  * O preço de cada linha de oferta aceita, **conferindo as condições de novo** com o carrinho real (ADR-0083 §1,
  * princípio 2, e §6). Linha que perdeu a condição volta `ineligible` com o motivo, e a ponte escolhe remover ou cobrar
- * o preço cheio. A reconferência usa só o que a cliente escolheu (linha de oferta não sustenta outra; a de troca conta
- * como o produto que ela leva) e as vagas da posição, na ordem de prioridade. Documento de formato mais novo que o
+ * o preço cheio. A reconferência usa o carrinho de antes da troca, o mesmo do `decide` (linha de oferta não sustenta
+ * outra; a de troca volta a ser o item trocado) e as vagas da posição, na ordem de prioridade. Cada linha `ok` diz em
+ * `discountedQuantity` quantas unidades levam o preço da oferta (`maxQuantity`); o resto vai a preço cheio. Documento de formato mais novo que o
  * pacote não é precificado: toda linha volta `unsupported_schema`; visitante do grupo de fora geral, `holdout`. A
  * variante do teste é sorteada de novo pelo visitante (com as mesmas `assignments`), a mesma que o `decide` deu. O
  * "produto que esconde" (`cart_has_none`) não é conferido aqui: esconder não desfaz a oferta já aceita (app ADR 0025).

package/dist/price.js

@@ -16,8 +16,9 @@ function refuseAll(cart, reason) {
 /**
  * O preço de cada linha de oferta aceita, **conferindo as condições de novo** com o carrinho real (ADR-0083 §1,
  * princípio 2, e §6). Linha que perdeu a condição volta `ineligible` com o motivo, e a ponte escolhe remover ou cobrar
- * o preço cheio. A reconferência usa só o que a cliente escolheu (linha de oferta não sustenta outra; a de troca conta
- * como o produto que ela leva) e as vagas da posição, na ordem de prioridade. Documento de formato mais novo que o
+ * o preço cheio. A reconferência usa o carrinho de antes da troca, o mesmo do `decide` (linha de oferta não sustenta
+ * outra; a de troca volta a ser o item trocado) e as vagas da posição, na ordem de prioridade. Cada linha `ok` diz em
+ * `discountedQuantity` quantas unidades levam o preço da oferta (`maxQuantity`); o resto vai a preço cheio. Documento de formato mais novo que o
  * pacote não é precificado: toda linha volta `unsupported_schema`; visitante do grupo de fora geral, `holdout`. A
  * variante do teste é sorteada de novo pelo visitante (com as mesmas `assignments`), a mesma que o `decide` deu. O
  * "produto que esconde" (`cart_has_none`) não é conferido aqui: esconder não desfaz a oferta já aceita (app ADR 0025).

package/dist/schema-version.d.ts

@@ -4,5 +4,6 @@
  * precificado: a resposta diz `unsupported_schema` e a ponte sabe que precisa atualizar o pacote, em vez de cobrar
  * com uma regra que não conhece.
  */
-export declare const SUPPORTED_SCHEMA_VERSION = 1;
+/** 2 = pacote 0.3.2: brinde vale 1 unidade por padrão e `maxQuantity` limita as unidades com desconto. */
+export declare const SUPPORTED_SCHEMA_VERSION = 2;
 export declare function isSupportedSchema(schemaVersion: number): boolean;

package/dist/schema-version.js

@@ -4,7 +4,8 @@
  * precificado: a resposta diz `unsupported_schema` e a ponte sabe que precisa atualizar o pacote, em vez de cobrar
  * com uma regra que não conhece.
  */
-export const SUPPORTED_SCHEMA_VERSION = 1;
+/** 2 = pacote 0.3.2: brinde vale 1 unidade por padrão e `maxQuantity` limita as unidades com desconto. */
+export const SUPPORTED_SCHEMA_VERSION = 2;
 export function isSupportedSchema(schemaVersion) {
     return Number.isInteger(schemaVersion) && schemaVersion >= 1 && schemaVersion <= SUPPORTED_SCHEMA_VERSION;
 }

package/dist/types.d.ts

@@ -82,6 +82,12 @@ export interface Offer {
     /** Nome do visual que a ponte implementa; sem ele vale o da posição. */
     presentation?: string;
     conditions: OfferCondition[];
+    /**
+     * Quantas unidades da linha levam o preço da oferta (inteiro ≥ 1, pacote 0.3.2); o resto vai a preço cheio. Ausente:
+     * **1** quando o preço da oferta dá 0 (brinde), a linha toda nos outros casos. O `price` devolve a conta em
+     * `discountedQuantity`.
+     */
+    maxQuantity?: number;
     /** Instantes ISO com offset; início inclusivo, fim exclusivo. */
     validFrom?: string;
     validUntil?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zolve/offers",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Motor de ofertas headless (ADR-0083): tipos do documento publicado, decide() e price(), sorteio A/B do PostHog. Sem dependências de runtime, para caber numa Shopify Function",
   "type": "module",
   "sideEffects": false,