@fayz-ai/shop 0.9.0 → 0.11.0

package/dist/rules/attributes.d.ts

@@ -0,0 +1,64 @@
+import { Registry } from '@fayz-ai/core';
+import type { RegistryMeta } from '@fayz-ai/core';
+import type { RuleOperator } from './rule-types';
+export declare const RULE_ATTRIBUTE_FIELD_TYPES: readonly ["text", "number", "boolean"];
+export type RuleAttributeFieldType = (typeof RULE_ATTRIBUTE_FIELD_TYPES)[number];
+/**
+ * One vocabulary row.
+ *
+ * `path` locates the value in the evaluation context built from the cart
+ * snapshot. Paths under `items.` are ITEM-scoped: they evaluate per cart line
+ * (scoping target/buy rules to lines; for eligibility, "some line matches").
+ * Every other path is CART-scoped, walked from the snapshot root. A context
+ * provider's attributes resolve by KEY from the provided context instead.
+ *
+ * `value_source` names the id list an admin form offers as values
+ * ('products', 'categories', …) — a UI hint, never an evaluation input.
+ */
+export interface RuleAttribute {
+    key: string;
+    path: string;
+    label: string;
+    fieldType: RuleAttributeFieldType;
+    /** Where an admin form fetches candidate values. Null = free entry. */
+    valueSource?: string | null;
+    /** The operators this attribute supports — a subset of the 7. */
+    operators: readonly RuleOperator[];
+}
+/** Prefix that marks an attribute path as item-scoped. */
+export declare const ITEM_PATH_PREFIX = "items.";
+/**
+ * The core vocabulary — what every Fayz-backed store starts with, mirrored as
+ * the plg_shop_rule_attributes seed rows in migration 0032.
+ */
+export declare const CORE_RULE_ATTRIBUTES: readonly RuleAttribute[];
+export declare const ruleAttributeRegistry: Registry<RuleAttribute>;
+/** Idempotent — mirrors registerStorefrontBlocks: consumers call before reads. */
+export declare function registerCoreRuleAttributes(): void;
+export interface RegisterRuleAttributeOptions {
+    meta?: RegistryMeta;
+    /** Re-registering an existing key is an error unless the caller owns it
+     *  (module re-evaluation under HMR re-registers the same declaration). */
+    replace?: boolean;
+}
+/**
+ * Widen the vocabulary with one attribute. Duplicate keys are an I2 hard
+ * error naming the taken set — two providers silently fighting over one key
+ * would make rules mean different things on different renders.
+ */
+export declare function registerRuleAttribute(attribute: RuleAttribute, options?: RegisterRuleAttributeOptions): void;
+/** The attribute for a key, or an I2 hard error naming the valid set — the
+ *  only lookup the evaluator and the validators may use. */
+export declare function resolveRuleAttribute(key: string): RuleAttribute;
+export declare function hasRuleAttribute(key: string): boolean;
+/** Every attribute key, sorted — the valid set I2 errors name. */
+export declare function listRuleAttributeKeys(): string[];
+/** Every vocabulary row, sorted by key — what describeStore publishes and the
+ *  admin promotion form renders itself from. */
+export declare function listRuleAttributes(): RuleAttribute[];
+/** True when the attribute evaluates per cart line. */
+export declare function isItemScopedAttribute(attribute: RuleAttribute): boolean;
+/** Test seam — suites that widen the vocabulary must not leak into the next.
+ *  Core attributes re-register on the next read. */
+export declare function clearRuleAttributes(): void;
+//# sourceMappingURL=attributes.d.ts.map

package/dist/rules/attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../src/rules/attributes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAqBhD,eAAO,MAAM,0BAA0B,wCAAyC,CAAA;AAChF,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAA;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,sBAAsB,CAAA;IACjC,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,iEAAiE;IACjE,SAAS,EAAE,SAAS,YAAY,EAAE,CAAA;CACnC;AAKD,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,WAAW,CAAA;AAExC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,aAAa,EAyExD,CAAA;AAOD,eAAO,MAAM,qBAAqB,yBAA+C,CAAA;AAIjF,kFAAkF;AAClF,wBAAgB,0BAA0B,IAAI,IAAI,CAUjD;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB;8EAC0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,GAAE,4BAAiC,GAAG,IAAI,CA6BhH;AAED;4DAC4D;AAC5D,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAO/D;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAGhD;AAED;gDACgD;AAChD,wBAAgB,kBAAkB,IAAI,aAAa,EAAE,CAMpD;AAED,uDAAuD;AACvD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,CAEvE;AAED;oDACoD;AACpD,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C"}

package/dist/rules/context.d.ts

@@ -0,0 +1,43 @@
+import { Registry } from '@fayz-ai/core';
+import type { RegistryMeta } from '@fayz-ai/core';
+import type { RuleAttribute } from './attributes';
+import type { RuleCartSnapshot } from './rule-types';
+/** What a provider contributes: one context value per declared attribute key.
+ *  A value may be a scalar of the declared field type or an array of them
+ *  (e.g. customer tags); null/undefined mean "no value" and are dropped. */
+export type RuleContext = Record<string, unknown>;
+export interface RuleContextAttributeInput extends Omit<RuleAttribute, 'path'> {
+    /** Optional — context attributes resolve by KEY from the provided context,
+     *  so the path is display metadata only. Defaults to `context.<key>`. */
+    path?: string;
+}
+export interface RuleContextProvider {
+    /** Attributes this provider contributes — registered into the vocabulary. */
+    attributes: readonly RuleContextAttributeInput[];
+    /** Compute the context values for one evaluation. Pure of side effects. */
+    resolve(cart: RuleCartSnapshot): Promise<RuleContext> | RuleContext;
+}
+export declare const ruleContextRegistry: Registry<RuleContextProvider>;
+/**
+ * Register a context provider. Its attributes enter the vocabulary
+ * immediately (duplicate keys are the I2 hard error registerRuleAttribute
+ * throws), so discovery and evaluation can never disagree about what exists.
+ */
+export declare function defineRuleContextProvider(id: string, provider: RuleContextProvider, meta?: RegistryMeta): void;
+/**
+ * Validate one provider's resolved context against its declaration (I2):
+ * unknown keys name the declared set; wrong-typed values name the expected
+ * type. Returns only the declared, typed, non-null entries.
+ */
+export declare function validateRuleContextResult(id: string, provider: RuleContextProvider, result: RuleContext): RuleContext;
+/**
+ * Run every registered provider against the cart and merge the validated
+ * results into one context record, keyed by attribute key — the `context`
+ * input of computePromotionActions. Key collisions cannot happen here: the
+ * vocabulary registry already refused the second registration.
+ */
+export declare function buildRuleContext(cart: RuleCartSnapshot): Promise<RuleContext>;
+/** Test seam. Clearing providers does not un-register their vocabulary rows —
+ *  pair with clearRuleAttributes() in suite teardown. */
+export declare function clearRuleContextProviders(): void;
+//# sourceMappingURL=context.d.ts.map

package/dist/rules/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/rules/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEjD,OAAO,KAAK,EAAE,aAAa,EAA0B,MAAM,cAAc,CAAA;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AA0BpD;;4EAE4E;AAC5E,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEjD,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC;IAC5E;6EACyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,UAAU,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAChD,2EAA2E;IAC3E,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAAA;CACpE;AAED,eAAO,MAAM,mBAAmB,+BAAmD,CAAA;AAEnF;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,mBAAmB,EAC7B,IAAI,GAAE,YAAiB,GACtB,IAAI,CAiBN;AAQD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,EAAE,WAAW,GAAG,WAAW,CAwBrH;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAOnF;AAED;yDACyD;AACzD,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/rules/evaluator.d.ts

@@ -0,0 +1,37 @@
+import type { RuleContext } from './context';
+import type { ComputeAction, Promotion, PromotionRule, RuleCartSnapshot } from './rule-types';
+export interface EvaluateOptions {
+    /** Extra attribute values, keyed by attribute KEY — the validated output of
+     *  buildRuleContext (context providers). Wins over snapshot resolution. */
+    context?: RuleContext;
+    /** ISO timestamp the date-window gates compare against. Default: now. */
+    now?: string;
+}
+/** One rule against a flat value list. Values are OR; `ne` is a negative and
+ *  therefore holds only when NO value equals any rule value. */
+export declare function matchRuleValues(rule: PromotionRule, values: unknown[]): boolean;
+/** ALL rules match (AND). Empty/absent = match. */
+export declare function rulesMatchCart(rules: PromotionRule[] | undefined, cart: RuleCartSnapshot, context?: RuleContext): boolean;
+export type PromotionGateReason = 'inactive' | 'not_started' | 'expired' | 'usage_limit' | 'code_not_entered' | 'rules_not_matched';
+/**
+ * Why a promotion does NOT fire against this cart, or null when it does.
+ * Shared by the evaluator and the coupon-surface adapter so a rejected code
+ * reports the same machine-readable reason everywhere.
+ */
+export declare function promotionGateReason(promotion: Promotion, cart: RuleCartSnapshot, options?: EvaluateOptions): PromotionGateReason | null;
+/** Split `total` across weights, in cents, largest-remainder — the parts sum
+ *  to exactly `total` so a spread discount never loses or invents a cent. */
+export declare function splitProportionally(total: number, weights: number[]): number[];
+/** Deterministic evaluation order: buyget first, specific before generic, id
+ *  as the final tiebreak. Exported so the SQL mirror's ORDER BY has a named
+ *  TS counterpart to test against. */
+export declare function orderPromotions(promotions: Promotion[]): Promotion[];
+/**
+ * Evaluate promotions against a cart snapshot → the ordered compute-actions
+ * the cart applies. Pure and deterministic (inject `now` for date gates).
+ */
+export declare function computePromotionActions(cart: RuleCartSnapshot, promotions: Promotion[], options?: EvaluateOptions): ComputeAction[];
+/** Total item+shipping discount an action list carries — the preview number a
+ *  cart shows. Free items carry no amount (they enter the cart at price 0). */
+export declare function actionsDiscountTotal(actions: ComputeAction[]): number;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/rules/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/rules/evaluator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAK5C,OAAO,KAAK,EAEV,aAAa,EACb,SAAS,EACT,aAAa,EAEb,gBAAgB,EAEjB,MAAM,cAAc,CAAA;AAkCrB,MAAM,WAAW,eAAe;IAC9B;+EAC2E;IAC3E,OAAO,CAAC,EAAE,WAAW,CAAA;IACrB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AA4DD;gEACgE;AAChE,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAgB/E;AAoBD,mDAAmD;AACnD,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAE7H;AASD,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,aAAa,GACb,SAAS,GACT,aAAa,GACb,kBAAkB,GAClB,mBAAmB,CAAA;AAEvB;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,eAAoB,GAC5B,mBAAmB,GAAG,IAAI,CAe5B;AAQD;6EAC6E;AAC7E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAgB9E;AAoJD;;sCAEsC;AACtC,wBAAgB,eAAe,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAQpE;AAID;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,GAAE,eAAoB,GAC5B,aAAa,EAAE,CAYjB;AAED;+EAC+E;AAC/E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAIrE"}

package/dist/rules/index.d.ts

@@ -0,0 +1,13 @@
+export { RULE_OPERATORS, APPLICATION_METHOD_TYPES, APPLICATION_METHOD_TARGET_TYPES, APPLICATION_METHOD_ALLOCATIONS, PROMOTION_TYPES, PROMOTION_STATUSES, cartSubtotal, roundCents, } from './rule-types';
+export type { RuleOperator, RuleValue, PromotionRule, ApplicationMethod, ApplicationMethodType, ApplicationMethodTargetType, ApplicationMethodAllocation, Promotion, PromotionType, PromotionStatus, Campaign, RuleCartItem, RuleCartSnapshot, ComputeAction, AddItemDiscountAction, AddShippingDiscountAction, AddFreeItemAction, } from './rule-types';
+export { RULE_ATTRIBUTE_FIELD_TYPES, CORE_RULE_ATTRIBUTES, ITEM_PATH_PREFIX, ruleAttributeRegistry, registerCoreRuleAttributes, registerRuleAttribute, resolveRuleAttribute, hasRuleAttribute, listRuleAttributeKeys, listRuleAttributes, isItemScopedAttribute, clearRuleAttributes, } from './attributes';
+export type { RuleAttribute, RuleAttributeFieldType, RegisterRuleAttributeOptions } from './attributes';
+export { ruleContextRegistry, defineRuleContextProvider, validateRuleContextResult, buildRuleContext, clearRuleContextProviders, } from './context';
+export type { RuleContext, RuleContextProvider, RuleContextAttributeInput } from './context';
+export { computePromotionActions, promotionGateReason, rulesMatchCart, matchRuleValues, orderPromotions, splitProportionally, actionsDiscountTotal, } from './evaluator';
+export type { EvaluateOptions, PromotionGateReason } from './evaluator';
+export { rankPrices, selectPrice } from './prices';
+export type { PriceCandidate, RankPricesOptions } from './prices';
+export { discountToPromotion, storefrontDiscountToPromotion, previewCouponPercent, } from './adapter';
+export type { StorefrontPercentCode, CouponPreview } from './adapter';
+//# sourceMappingURL=index.d.ts.map

package/dist/rules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,+BAA+B,EAC/B,8BAA8B,EAC9B,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,UAAU,GACX,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,YAAY,EACZ,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,2BAA2B,EAC3B,2BAA2B,EAC3B,SAAS,EACT,aAAa,EACb,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAA;AAEvG,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAA;AAE5F,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEvE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAClD,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAEjE,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA"}

package/dist/rules/prices.d.ts

@@ -0,0 +1,25 @@
+import type { RuleContext } from './context';
+import type { PromotionRule, RuleCartSnapshot } from './rule-types';
+/** One candidate price for a purchasable. `rules` guard applicability;
+ *  `priceListId` marks an override list (a price list always outranks a
+ *  bare price, however many rules the bare price carries). */
+export interface PriceCandidate {
+    id: string;
+    amount: number;
+    priceListId?: string | null;
+    rules?: PromotionRule[];
+}
+export interface RankPricesOptions {
+    /** Context-provider values, keyed by attribute key (see buildRuleContext). */
+    context?: RuleContext;
+}
+/**
+ * The applicable candidates, most-precedent first:
+ * price_list first, rules_count DESC, amount ASC, id as a stable tiebreak.
+ * A candidate whose rules do not ALL match is not in the answer at all —
+ * matched_count = rules_count, never partial credit.
+ */
+export declare function rankPrices(candidates: PriceCandidate[], cart: RuleCartSnapshot, options?: RankPricesOptions): PriceCandidate[];
+/** The winning price, or null when no candidate's rules all match. */
+export declare function selectPrice(candidates: PriceCandidate[], cart: RuleCartSnapshot, options?: RankPricesOptions): PriceCandidate | null;
+//# sourceMappingURL=prices.d.ts.map

package/dist/rules/prices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prices.d.ts","sourceRoot":"","sources":["../../src/rules/prices.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAsBnE;;8DAE8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,KAAK,CAAC,EAAE,aAAa,EAAE,CAAA;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,WAAW,CAAA;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,cAAc,EAAE,EAC5B,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,iBAAsB,GAC9B,cAAc,EAAE,CAYlB;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CACzB,UAAU,EAAE,cAAc,EAAE,EAC5B,IAAI,EAAE,gBAAgB,EACtB,OAAO,GAAE,iBAAsB,GAC9B,cAAc,GAAG,IAAI,CAEvB"}

package/dist/rules/rule-types.d.ts

@@ -0,0 +1,160 @@
+/** The 7 rule operators. This is the closed set — widening it is a model
+ *  change (TS union + DB CHECK + SQL evaluator), not an insert. */
+export declare const RULE_OPERATORS: readonly ["gte", "lte", "gt", "lt", "eq", "ne", "in"];
+export type RuleOperator = (typeof RULE_OPERATORS)[number];
+/** A rule value is a JSON scalar. The DB stores each in its own
+ *  plg_shop_rule_values row (values-in-a-child-table, per the model). */
+export type RuleValue = string | number | boolean;
+/**
+ * One rule: `attribute` names a row of the rule_attribute VOCABULARY (I9 —
+ * never a free-form dotted path; an unknown attribute is an I2 hard error
+ * naming the valid set), `operator` is one of the 7, `values` is the child
+ * list (a single-element list for scalar operators).
+ */
+export interface PromotionRule {
+    attribute: string;
+    operator: RuleOperator;
+    values: RuleValue[];
+}
+export declare const APPLICATION_METHOD_TYPES: readonly ["percentage", "fixed"];
+export type ApplicationMethodType = (typeof APPLICATION_METHOD_TYPES)[number];
+export declare const APPLICATION_METHOD_TARGET_TYPES: readonly ["order", "items", "shipping"];
+export type ApplicationMethodTargetType = (typeof APPLICATION_METHOD_TARGET_TYPES)[number];
+export declare const APPLICATION_METHOD_ALLOCATIONS: readonly ["each", "across", "once"];
+export type ApplicationMethodAllocation = (typeof APPLICATION_METHOD_ALLOCATIONS)[number];
+/**
+ * HOW an eligible promotion applies. The six numbers + two rule sets that make
+ * buy-N-pay-M pure data:
+ *
+ *  - `type` percentage (value = percentage points) or fixed (value = amount).
+ *  - `targetType` order (spread across all items) | items | shipping.
+ *  - `allocation` (items only):
+ *      each   — per unit of each eligible line, `maxQuantity` units per line;
+ *      across — one amount over the eligible subtotal, split proportionally;
+ *      once   — one unit of the cheapest eligible line, once.
+ *  - `buyRulesMinQuantity` + `buyRules` — what must be in the cart, and how
+ *    many, for the promotion to fire (buyget). The promotion applies
+ *    floor(matched buy quantity / buyRulesMinQuantity) times.
+ *  - `applyToQuantity` — how many target units each firing discounts.
+ *  - `targetRules` — which items the discount lands on. A buyget whose target
+ *    is not in the cart but is pinned to one product id emits addFreeItem.
+ */
+export interface ApplicationMethod {
+    type: ApplicationMethodType;
+    value: number;
+    targetType: ApplicationMethodTargetType;
+    allocation?: ApplicationMethodAllocation;
+    /** Unit cap: per line for `each`; total discounted/free units for buyget. */
+    maxQuantity?: number | null;
+    /** Buyget: target units discounted per firing. */
+    applyToQuantity?: number | null;
+    /** Buyget: matched buy quantity required per firing. Null/absent = standard. */
+    buyRulesMinQuantity?: number | null;
+    /** What gets discounted (the `target` pivot). Absent = every item. */
+    targetRules?: PromotionRule[];
+    /** What must be bought (the `buy` pivot). Item-scoped attributes only. */
+    buyRules?: PromotionRule[];
+}
+export declare const PROMOTION_TYPES: readonly ["standard", "buyget"];
+export type PromotionType = (typeof PROMOTION_TYPES)[number];
+export declare const PROMOTION_STATUSES: readonly ["draft", "active", "inactive"];
+export type PromotionStatus = (typeof PROMOTION_STATUSES)[number];
+/**
+ * A promotion: eligibility rules (the `eligibility` pivot) + one application
+ * method. `code` promotions fire only when the shopper entered the code
+ * (cart.codes); `isAutomatic` promotions fire whenever eligible.
+ */
+export interface Promotion {
+    id: string;
+    /** Coupon code. Null/absent = automatic-only. Matched case-insensitively. */
+    code?: string | null;
+    isAutomatic?: boolean;
+    /** Derivable (buyRulesMinQuantity ⇒ buyget) but stored for the admin UI. */
+    type?: PromotionType;
+    status?: PromotionStatus;
+    campaignId?: string | null;
+    /** Does this promotion apply at all? (the `eligibility` pivot). AND across
+     *  rules; a rule's values are OR. Absent/empty = always eligible. */
+    rules?: PromotionRule[];
+    applicationMethod: ApplicationMethod;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    usageLimit?: number | null;
+    timesUsed?: number;
+}
+/** A campaign groups promotions for reporting/budgets. Parent row only in M6;
+ *  budget enforcement is a later milestone. */
+export interface Campaign {
+    id: string;
+    name: string;
+    startsAt?: string | null;
+    endsAt?: string | null;
+}
+/** One cart line as the engine sees it. Prices are authoritative-catalog
+ *  prices; the engine never trusts a client-computed total. */
+export interface RuleCartItem {
+    /** Line identity actions refer back to. Defaults to productId. */
+    id?: string;
+    productId: string;
+    quantity: number;
+    unitPrice: number;
+    categoryId?: string | null;
+    collectionId?: string | null;
+}
+/**
+ * The evaluation input. Serializable on purpose: the SAME snapshot shape is
+ * the TS evaluator's input and the SQL function's `p_cart` jsonb, so the
+ * preview a shopper sees and the revalidation place_order runs read one
+ * contract.
+ */
+export interface RuleCartSnapshot {
+    items: RuleCartItem[];
+    /** Quoted shipping — what a shipping-target promotion discounts. */
+    shippingTotal?: number | null;
+    /** Shipping region/zone identifier (the shipping.region attribute). */
+    region?: string | null;
+    customer?: {
+        email?: string | null;
+        tags?: string[];
+    };
+    /** Promotion codes the shopper entered (the code attribute; case-insensitive). */
+    codes?: string[];
+    currency?: string;
+}
+/** Discount one cart line by an absolute amount (already allocation-resolved). */
+export interface AddItemDiscountAction {
+    action: 'addItemDiscount';
+    promotionId: string;
+    code?: string | null;
+    itemId: string;
+    amount: number;
+}
+/** Discount the shipping total by an absolute amount. */
+export interface AddShippingDiscountAction {
+    action: 'addShippingDiscount';
+    promotionId: string;
+    code?: string | null;
+    amount: number;
+}
+/** Add `quantity` free units of a product the buyget promotion grants but the
+ *  cart does not contain. The cart applies it by adding the line at price 0. */
+export interface AddFreeItemAction {
+    action: 'addFreeItem';
+    promotionId: string;
+    code?: string | null;
+    productId: string;
+    quantity: number;
+}
+/**
+ * The ordered action list computePromotionActions returns. Deterministic:
+ * buyget promotions first (they consume target units), then by specificity
+ * (total rules count DESC), then id — so replaying the same cart against the
+ * same promotions always yields byte-identical actions.
+ */
+export type ComputeAction = AddItemDiscountAction | AddShippingDiscountAction | AddFreeItemAction;
+/** Sum of a cart's line totals, cents-rounded — the number `cart.subtotal`
+ *  rules compare against. */
+export declare function cartSubtotal(cart: RuleCartSnapshot): number;
+/** Cents rounding, the house money convention (commerce.ts round2). */
+export declare function roundCents(value: number): number;
+//# sourceMappingURL=rule-types.d.ts.map

package/dist/rules/rule-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-types.d.ts","sourceRoot":"","sources":["../../src/rules/rule-types.ts"],"names":[],"mappings":"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"}

package/dist/rules.js

@@ -0,0 +1,22 @@
+import { rulesMatchCart } from './chunk-3GERSY5F.js';
+export { APPLICATION_METHOD_ALLOCATIONS, APPLICATION_METHOD_TARGET_TYPES, APPLICATION_METHOD_TYPES, CORE_RULE_ATTRIBUTES, ITEM_PATH_PREFIX, PROMOTION_STATUSES, PROMOTION_TYPES, RULE_ATTRIBUTE_FIELD_TYPES, RULE_OPERATORS, actionsDiscountTotal, buildRuleContext, cartSubtotal, clearRuleAttributes, clearRuleContextProviders, computePromotionActions, defineRuleContextProvider, discountToPromotion, hasRuleAttribute, isItemScopedAttribute, listRuleAttributeKeys, listRuleAttributes, matchRuleValues, orderPromotions, previewCouponPercent, promotionGateReason, registerCoreRuleAttributes, registerRuleAttribute, resolveRuleAttribute, roundCents, ruleAttributeRegistry, ruleContextRegistry, rulesMatchCart, splitProportionally, storefrontDiscountToPromotion, validateRuleContextResult } from './chunk-3GERSY5F.js';
+
+// src/rules/prices.ts
+function rankPrices(candidates, cart, options = {}) {
+  const context = options.context ?? {};
+  return candidates.filter((candidate) => rulesMatchCart(candidate.rules, cart, context)).sort((a, b) => {
+    const list = Number(b.priceListId != null) - Number(a.priceListId != null);
+    if (list !== 0) return list;
+    const specificity = (b.rules?.length ?? 0) - (a.rules?.length ?? 0);
+    if (specificity !== 0) return specificity;
+    if (a.amount !== b.amount) return a.amount - b.amount;
+    return a.id.localeCompare(b.id);
+  });
+}
+function selectPrice(candidates, cart, options = {}) {
+  return rankPrices(candidates, cart, options)[0] ?? null;
+}
+
+export { rankPrices, selectPrice };
+//# sourceMappingURL=rules.js.map
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/rules/prices.ts"],"names":[],"mappings":";;;;AA6CO,SAAS,UAAA,CACd,UAAA,EACA,IAAA,EACA,OAAA,GAA6B,EAAC,EACZ;AAClB,EAAA,MAAM,OAAA,GAAU,OAAA,CAAQ,OAAA,IAAW,EAAC;AACpC,EAAA,OAAO,UAAA,CACJ,MAAA,CAAO,CAAC,SAAA,KAAc,eAAe,SAAA,CAAU,KAAA,EAAO,IAAA,EAAM,OAAO,CAAC,CAAA,CACpE,IAAA,CAAK,CAAC,GAAG,CAAA,KAAM;AACd,IAAA,MAAM,IAAA,GAAO,OAAO,CAAA,CAAE,WAAA,IAAe,IAAI,CAAA,GAAI,MAAA,CAAO,CAAA,CAAE,WAAA,IAAe,IAAI,CAAA;AACzE,IAAA,IAAI,IAAA,KAAS,GAAG,OAAO,IAAA;AACvB,IAAA,MAAM,eAAe,CAAA,CAAE,KAAA,EAAO,UAAU,CAAA,KAAM,CAAA,CAAE,OAAO,MAAA,IAAU,CAAA,CAAA;AACjE,IAAA,IAAI,WAAA,KAAgB,GAAG,OAAO,WAAA;AAC9B,IAAA,IAAI,EAAE,MAAA,KAAW,CAAA,CAAE,QAAQ,OAAO,CAAA,CAAE,SAAS,CAAA,CAAE,MAAA;AAC/C,IAAA,OAAO,CAAA,CAAE,EAAA,CAAG,aAAA,CAAc,CAAA,CAAE,EAAE,CAAA;AAAA,EAChC,CAAC,CAAA;AACL;AAGO,SAAS,WAAA,CACd,UAAA,EACA,IAAA,EACA,OAAA,GAA6B,EAAC,EACP;AACvB,EAAA,OAAO,WAAW,UAAA,EAAY,IAAA,EAAM,OAAO,CAAA,CAAE,CAAC,CAAA,IAAK,IAAA;AACrD","file":"rules.js","sourcesContent":["import { rulesMatchCart } from './evaluator'\nimport type { RuleContext } from './context'\nimport type { PromotionRule, RuleCartSnapshot } from './rule-types'\n\n// ---------------------------------------------------------------------------\n// Price precedence by rules_count specificity (spine §3 L2) — Medusa's\n// pricing trick (pricing/src/repositories/pricing.ts:228-295), adopted\n// because it makes precedence DERIVABLE FROM THE DATA ALONE:\n//\n//   a price applies iff matched_count = rules_count,\n//   ranked price_list first, rules_count DESC, amount ASC.\n//\n// \"Applies iff matched_count = rules_count\" is simply \"ALL of its rules\n// match\" — rulesMatchCart. Because the ranking is a pure function of the\n// candidate rows, an agent adding \"VIP customers in Brazil buying more than\n// 10 units get this price\" never reasons about precedence: more rules = more\n// specific = wins; ties resolve to the cheaper price, which is the promise a\n// shopper was shown somewhere.\n//\n// Same rule model, same vocabulary, same evaluator — this is what \"ONE rule\n// engine\" (I8) buys: prices, promotions and shipping share matching\n// semantics, so a rule means the same thing wherever it appears.\n// ---------------------------------------------------------------------------\n\n/** One candidate price for a purchasable. `rules` guard applicability;\n *  `priceListId` marks an override list (a price list always outranks a\n *  bare price, however many rules the bare price carries). */\nexport interface PriceCandidate {\n  id: string\n  amount: number\n  priceListId?: string | null\n  rules?: PromotionRule[]\n}\n\nexport interface RankPricesOptions {\n  /** Context-provider values, keyed by attribute key (see buildRuleContext). */\n  context?: RuleContext\n}\n\n/**\n * The applicable candidates, most-precedent first:\n * price_list first, rules_count DESC, amount ASC, id as a stable tiebreak.\n * A candidate whose rules do not ALL match is not in the answer at all —\n * matched_count = rules_count, never partial credit.\n */\nexport function rankPrices(\n  candidates: PriceCandidate[],\n  cart: RuleCartSnapshot,\n  options: RankPricesOptions = {},\n): PriceCandidate[] {\n  const context = options.context ?? {}\n  return candidates\n    .filter((candidate) => rulesMatchCart(candidate.rules, cart, context))\n    .sort((a, b) => {\n      const list = Number(b.priceListId != null) - Number(a.priceListId != null)\n      if (list !== 0) return list\n      const specificity = (b.rules?.length ?? 0) - (a.rules?.length ?? 0)\n      if (specificity !== 0) return specificity\n      if (a.amount !== b.amount) return a.amount - b.amount\n      return a.id.localeCompare(b.id)\n    })\n}\n\n/** The winning price, or null when no candidate's rules all match. */\nexport function selectPrice(\n  candidates: PriceCandidate[],\n  cart: RuleCartSnapshot,\n  options: RankPricesOptions = {},\n): PriceCandidate | null {\n  return rankPrices(candidates, cart, options)[0] ?? null\n}\n"]}

package/dist/runtime.d.ts

@@ -1,5 +1,2 @@
-import type { ShopProvider } from './provider';
-export declare function getShopProvider(): ShopProvider;
-export declare function setShopProvider(nextProvider: ShopProvider): void;
-export declare function resetShopProvider(): void;
+export * from './lib/runtime';
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAM9C,wBAAgB,eAAe,IAAI,YAAY,CAI9C;AAED,wBAAgB,eAAe,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAEhE;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAEA,cAAc,eAAe,CAAA"}

package/dist/runtime.js

@@ -1,5 +1,7 @@
-export { getShopProvider, resetShopProvider, setShopProvider } from './chunk-IYQHKMLB.js';
-import './chunk-SVTCJ6HP.js';
-import './chunk-CTKZ6O2J.js';
+export { getShopProvider, resetShopProvider, setShopProvider } from './chunk-2WACO2TG.js';
+import './chunk-U6HV3LVP.js';
+import './chunk-IKNGCRUM.js';
+import './chunk-NWW3WJ7Y.js';
+import './chunk-3GERSY5F.js';
 //# sourceMappingURL=runtime.js.map
 //# sourceMappingURL=runtime.js.map

package/dist/shipping/label-provider.d.ts

@@ -0,0 +1,43 @@
+import type { ShippingLabel, ShippingLabelOption } from '../types';
+export interface ShippingLabelProvider {
+    /** Connector slug — the id `plg_connections.connector_id` carries. */
+    id: string;
+    /** How the merchant knows them ("Melhor Envio"). Shown in the panel. */
+    label: string;
+    /** Services and prices for one order. Free, repeatable, spends nothing. */
+    quote(orderId: string): Promise<{
+        options: ShippingLabelOption[];
+        label: ShippingLabel | null;
+    }>;
+    /** SPENDS the merchant's balance. Idempotent per order by contract. */
+    buy(orderId: string, serviceId: number): Promise<ShippingLabel>;
+    /** The label PDF, as many times as the merchant needs it. */
+    print(orderId: string): Promise<string | null>;
+    /** What the carrier says now. */
+    track(orderId: string): Promise<ShippingLabel['tracking']>;
+}
+export declare function registerShippingLabelProvider(provider: ShippingLabelProvider): void;
+export declare function listShippingLabelProviders(): ShippingLabelProvider[];
+/** Test seam — the registry is module state, and a test that registers a fake
+ *  must not leak it into the next one. */
+export declare function resetShippingLabelProviders(): void;
+export interface ResolveShippingLabelOptions {
+    /** Connector ids the store has ACTIVE, in the order the panel lists them. */
+    connected: readonly string[];
+    /**
+     * The merchant's explicit choice, when they made one.
+     *
+     * `''` (empty, not undefined) is a decision too — "I print labels myself" —
+     * and it must beat every connected carrier, exactly as the payment provider
+     * setting treats "confirmo à mão".
+     */
+    preferred?: string | null;
+}
+/**
+ * Which carrier issues this store's labels — or nobody.
+ *
+ * Null is a first-class answer and the common one: most stores dispatch by hand,
+ * and the panel must show them the manual path without a dead button beside it.
+ */
+export declare function resolveShippingLabelProvider(options: ResolveShippingLabelOptions): ShippingLabelProvider | null;
+//# sourceMappingURL=label-provider.d.ts.map

package/dist/shipping/label-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-provider.d.ts","sourceRoot":"","sources":["../../src/shipping/label-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAiBlE,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAA;IACV,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;QAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;KAAE,CAAC,CAAA;IAChG,uEAAuE;IACvE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC/D,6DAA6D;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC9C,iCAAiC;IACjC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAAA;CAC3D;AAID,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAEnF;AAED,wBAAgB,0BAA0B,IAAI,qBAAqB,EAAE,CAEpE;AAED;0CAC0C;AAC1C,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED,MAAM,WAAW,2BAA2B;IAC1C,6EAA6E;IAC7E,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,2BAA2B,GACnC,qBAAqB,GAAG,IAAI,CAkB9B"}