@zolve/offers 0.1.0 → 0.3.0

package/README.md

@@ -19,6 +19,32 @@ const priced = price(doc, { cart, visitorId, at });
 // priced.lines[i]: { status: 'ok', unitPrice } | { status: 'ineligible', reason }
 ```
 
+`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.
+
+`applyVariant(offer, variant)` (0.3.0) devolve a oferta como uma variante de teste a mostra (campo ausente na mudança
+fica como no documento; o conteúdo mescla). É a regra do `decide`/`price`, e a do "aplicar vencedor" no Commerce OS.
+
+## Testes A/B e entrada congelada (0.3.0)
+
+O `decide` devolve em `experiments` o teste e a variante em que o visitante caiu (`[{ key, variant }]`). A ponte guarda
+isso (atributo `_cos_exp` do carrinho/cookie) e manda de volta em `assignments`, no `decide` e no `price`:
+
+```ts
+decide(doc, { placement: 'cart', cart, visitorId, assignments: [{ key: 'trimag-preco', variant: 'barato' }], at });
+price(doc, { cart, visitorId, assignments, at });
+```
+
+- Teste sem congelar: o sorteio de sempre, pelo `visitorId`. As `assignments` não mudam nada (o sorteio é
+  determinístico e dá a mesma variante).
+- Teste com `entryFrozen: true`: o sorteio é o mesmo, mas só vale para quem traz a atribuição que ele dá. Quem não
+  traz (gente nova) fica fora do teste: vê o documento sem mudança e não é contado. A atribuição não escolhe a variante:
+  uma que o sorteio não confirma (outra variante, outro teste, visitante fora do rollout) é ignorada, então um cookie
+  forjado não leva ninguém à variante mais barata.
+- Pacote anterior à 0.3.0 ignora `entryFrozen` e segue pondo gente nova nas variantes. Não cobra errado (o preço da
+  variante é um que já aceitamos vender), por isso o campo **não** subiu o `schemaVersion`; só a medição perde o
+  congelamento até a ponte atualizar.
+
 `decide` respeita condições, item disponível e fora do carrinho, vagas (e a vaga condicional), prioridade, um teste A/B
 por posição (sorteio do PostHog, em duas etapas) e o grupo de fora geral. `price` devolve a mesma variante de teste que
 o `decide` deu ao visitante.

package/dist/decide.js

@@ -112,7 +112,7 @@ export function decide(doc, input) {
     const placement = doc.placements.find((candidatePlacement) => candidatePlacement.key === input.placement);
     if (!placement)
         return emptyDecision(doc, input, 'ok');
-    const assignment = assignExperiment(doc, placement.key, input.visitorId);
+    const assignment = assignExperiment(doc, placement.key, input);
     const items = indexItems(doc);
     const ctx = { doc, items, view: viewCart(items, input.cart), placement, variant: assignment?.variant ?? null, at: input.at };
     const picks = pickOffers(ctx);

package/dist/experiments.d.ts

@@ -1,3 +1,4 @@
+import type { ExperimentAssignment } from './io.js';
 import type { Experiment, ExperimentVariant, Holdout, OfferDocument } from './types.js';
 /**
  * O hash do PostHog (`calculate_hash` do `feature-flags` em Rust, `_hash` do Python): `sha1(prefixo + id + sal)`, os 60
@@ -15,10 +16,20 @@ export interface Assignment {
     experiment: Experiment;
     variant: ExperimentVariant;
 }
+/** Quem chega com o sorteio a fazer: o visitante e as atribuições que a ponte guardou dele. */
+interface Visitor {
+    visitorId?: string | undefined;
+    assignments?: ExperimentAssignment[] | undefined;
+}
 /**
  * Sorteio em duas etapas (ADR-0047, emenda de testes A/B): primeiro se o visitante entra no teste, depois em qual
  * variante, as duas com `sha1("<teste>.<visitante><sal>")` e sais diferentes (o do teste, e o do teste + `variant`,
  * como o PostHog) para as decisões não ficarem ligadas. Um teste por posição: vale o primeiro ativo. Visitante sem id
  * nunca entra; quem está no grupo de fora geral também não.
+ *
+ * Teste com a entrada congelada: o sorteio é o mesmo, mas só vale quando o visitante traz a atribuição que ele dá. A
+ * atribuição não escolhe a variante (um cookie forjado não leva ninguém à variante mais barata), só prova que o
+ * visitante já tinha entrado; quem não traz fica fora e vê o documento sem mudança.
  */
-export declare function assignExperiment(doc: OfferDocument, placement: string, visitorId: string | undefined): Assignment | null;
+export declare function assignExperiment(doc: OfferDocument, placement: string, { visitorId, assignments }: Visitor): Assignment | null;
+export {};

package/dist/experiments.js

@@ -36,8 +36,12 @@ export function inHoldout(holdout, visitorId) {
  * variante, as duas com `sha1("<teste>.<visitante><sal>")` e sais diferentes (o do teste, e o do teste + `variant`,
  * como o PostHog) para as decisões não ficarem ligadas. Um teste por posição: vale o primeiro ativo. Visitante sem id
  * nunca entra; quem está no grupo de fora geral também não.
+ *
+ * Teste com a entrada congelada: o sorteio é o mesmo, mas só vale quando o visitante traz a atribuição que ele dá. A
+ * atribuição não escolhe a variante (um cookie forjado não leva ninguém à variante mais barata), só prova que o
+ * visitante já tinha entrado; quem não traz fica fora e vê o documento sem mudança.
  */
-export function assignExperiment(doc, placement, visitorId) {
+export function assignExperiment(doc, placement, { visitorId, assignments = [] }) {
     if (!visitorId)
         return null;
     const experiment = doc.experiments.find((candidate) => candidate.active && candidate.placement === placement);
@@ -47,5 +51,8 @@ export function assignExperiment(doc, placement, visitorId) {
     if (!inRollout(experiment.percentage, hashBucket(`${experiment.key}.`, visitorId, salt)))
         return null;
     const variant = selectVariant(hashBucket(`${experiment.key}.`, visitorId, `${salt}variant`), experiment.variants);
-    return variant ? { experiment, variant } : null;
+    if (!variant)
+        return null;
+    const entered = assignments.some((brought) => brought.key === experiment.key && brought.variant === variant.key);
+    return !experiment.entryFrozen || entered ? { experiment, variant } : null;
 }

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export type * from './types.js';
 export type * from './io.js';
 export { decide } from './decide.js';
 export { price } from './price.js';
+export { offerKind } from './kind.js';
+export { applyVariant } from './effective.js';
 export { hashBucket, inRollout, selectVariant } from './experiments.js';
 export { compareAtPrice, offerUnitPrice, pricePerDay } from './money.js';
 export { SUPPORTED_SCHEMA_VERSION } from './schema-version.js';

package/dist/index.js

@@ -1,5 +1,7 @@
 export { decide } from './decide.js';
 export { price } from './price.js';
+export { offerKind } from './kind.js';
+export { applyVariant } from './effective.js';
 export { hashBucket, inRollout, selectVariant } from './experiments.js';
 export { compareAtPrice, offerUnitPrice, pricePerDay } from './money.js';
 export { SUPPORTED_SCHEMA_VERSION } from './schema-version.js';

package/dist/io.d.ts

@@ -21,9 +21,12 @@ export interface DecideInput {
     cart: CartLine[];
     /** Sem visitante não há sorteio: ele nunca entra em teste. */
     visitorId?: string;
+    /** As atribuições que a ponte guardou (o `experiments` de decisões anteriores): mantêm quem já entrou num teste congelado. */
+    assignments?: ExperimentAssignment[];
     /** Instante ISO com offset. O pacote nunca lê o relógio: a decisão é determinística. */
     at: string;
 }
+/** Teste e variante em que o visitante caiu: sai no `decide` e volta da ponte em `assignments`. */
 export interface ExperimentAssignment {
     key: string;
     variant: string;
@@ -71,6 +74,8 @@ export interface PriceInput {
     cart: CartLine[];
     /** O mesmo do `decide`: a variante do teste é sorteada de novo por ele. */
     visitorId?: string;
+    /** As mesmas do `decide`: sem elas, o teste congelado cobra o documento sem mudança. */
+    assignments?: ExperimentAssignment[];
     at: string;
 }
 export type IneligibleReason = 'unknown_offer' | 'inactive' | 'item_mismatch' | 'not_started' | 'expired' | 'trigger_missing' | 'subtotal_out_of_range'

package/dist/kind.d.ts

@@ -1,5 +1,6 @@
 import { type ResolvedLine } from './cart.js';
 import type { DecidedOfferKind } from './io.js';
+import type { Offer, OfferDocument } from './types.js';
 export interface Classification {
     kind: DecidedOfferKind;
     direction: 'up' | 'down' | null;
@@ -11,3 +12,11 @@ export interface Classification {
  * escolhido já tem o mesmo produto, cross-sell quando é outro. A direção sai da duração no catálogo.
  */
 export declare function classify(offered: ResolvedLine, chosen: ResolvedLine[]): Classification;
+/**
+ * O tipo de uma oferta cadastrada, sem carrinho (o editor e a tela, ADR-0083 §3): a mesma regra do `decide()` aplicada
+ * aos gatilhos das condições `cart_has_any`, como se fossem o carrinho escolhido. Nulo sem gatilho para comparar.
+ */
+export declare function offerKind(doc: OfferDocument, offer: Offer): {
+    kind: DecidedOfferKind;
+    direction: 'up' | 'down' | null;
+} | null;

package/dist/kind.js

@@ -1,4 +1,4 @@
-import { sameProduct } from './cart.js';
+import { indexItems, resolveLine, sameProduct } from './cart.js';
 function directionOf(offered, target) {
     if (offered.durationDays === null || target.durationDays === null)
         return null;
@@ -16,3 +16,25 @@ export function classify(offered, chosen) {
         return { kind: 'cross_sell', direction: null, target: null };
     return { kind: 'upsell', direction: directionOf(offered, target), target };
 }
+const BLANK_LINE = { item: { source: '', variantId: '' }, quantity: 1 };
+/** Os gatilhos de `cart_has_any` como linhas: item do documento, produto da loja ou produto do catálogo. */
+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 })),
+    ]);
+}
+/**
+ * O tipo de uma oferta cadastrada, sem carrinho (o editor e a tela, ADR-0083 §3): a mesma regra do `decide()` aplicada
+ * aos gatilhos das condições `cart_has_any`, como se fossem o carrinho escolhido. Nulo sem gatilho para comparar.
+ */
+export function offerKind(doc, offer) {
+    const items = indexItems(doc);
+    const triggers = triggerLines(items, offer);
+    if (triggers.length === 0)
+        return null;
+    const { kind, direction } = classify(resolveLine(items, { item: offer.item, quantity: 1 }), triggers);
+    return { kind, direction };
+}

package/dist/price.d.ts

@@ -4,7 +4,7 @@ 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. Documento de formato mais novo que o pacote não é precificado: toda linha volta `unsupported_schema`.
- * A variante do teste é sorteada de novo pelo visitante, a mesma que o `decide` deu. O "produto que
+ * 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).
  */
 export declare function price(doc: OfferDocument, input: PriceInput): PriceResult;

package/dist/price.js

@@ -48,7 +48,7 @@ function priceLine(ctx, line, index) {
     const found = findOffer(ctx.doc, line);
     if (!found)
         return { index, offerId, status: 'ineligible', reason: 'unknown_offer' };
-    const assignment = assignExperiment(ctx.doc, found.placement, ctx.input.visitorId);
+    const assignment = assignExperiment(ctx.doc, found.placement, ctx.input);
     const offer = applyVariant(found, assignment?.variant ?? null);
     const reason = lineFailure(ctx, offer, index);
     if (reason)
@@ -62,7 +62,7 @@ function priceLine(ctx, line, index) {
  * 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. Documento de formato mais novo que o pacote não é precificado: toda linha volta `unsupported_schema`.
- * A variante do teste é sorteada de novo pelo visitante, a mesma que o `decide` deu. O "produto que
+ * 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).
  */
 export function price(doc, input) {

package/dist/types.d.ts

@@ -131,6 +131,11 @@ export interface Experiment {
     percentage: number;
     /** Sal do sorteio; vazio = igual ao PostHog. */
     salt?: string;
+    /**
+     * Entrada congelada: só segue no teste quem traz a atribuição dele (`assignments` do `decide`/`price`) e o sorteio
+     * confirma; gente nova vê o documento sem mudança e não é contada. Pacote anterior à 0.3.0 ignora e segue sorteando.
+     */
+    entryFrozen?: true;
     variants: ExperimentVariant[];
 }
 /** Grupo de fora geral: quem cai nele não entra em teste nenhum. Nasce desligado. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zolve/offers",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "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,