@rokt/dcui-orchestrator 1.2.1-rc.50 → 1.2.1-rc.52

package/dist/libraries/dcui-components/src/failure-codes.d.ts

@@ -6,3 +6,4 @@ export declare const FAILED_TO_MAP_STATIC_DATA = "FAILED_TO_MAP_STATIC_DATA";
 export declare const FAILED_SANITISING_HTML = "FAILED_SANITISING_HTML";
 export declare const UNRESOLVED_FORM_VALIDATION_TARGET = "UNRESOLVED_FORM_VALIDATION_TARGET";
 export declare const MISSING_LEAD_IDENTITY = "MISSING_LEAD_IDENTITY";
+export declare const UNSAFE_FORM_VALIDATION_PATTERN = "UNSAFE_FORM_VALIDATION_PATTERN";

package/dist/libraries/domain/src/models/form-state.d.ts

@@ -83,3 +83,88 @@ export interface FormFieldRef {
  * ActionButton (to gate dispatch) so both resolve entries identically.
  */
 export declare function resolveFormFieldRefs(formStates: FormStatesState, entries: string[]): FormFieldRef[];
+/**
+ * The longest `Pattern` a layout may register. A longer one is refused by
+ * {@link scanPattern}: the form-state reducer drops it at registration and
+ * {@link matchesPattern} treats it as non-blocking.
+ */
+export declare const MAX_PATTERN_LENGTH = 256;
+/**
+ * The longest value a `Pattern` validation tests, whatever the pattern. A
+ * longer value fails the validation with its message, untested. The rules of
+ * {@link scanPattern} bound the engine's work on a value of this length and
+ * on no other.
+ */
+export declare const MAX_PATTERN_VALUE_LENGTH = 512;
+/** Why {@link scanPattern} refused a pattern: the first rule it broke. */
+export type PatternRefusal = 'too-long' | 'backreference' | 'nested-quantifier' | 'repeated-alternation' | 'quantified-lookaround' | 'too-many-repetitions' | 'count-too-wide' | 'too-many-ways' | 'too-many-steps' | 'invalid';
+/** What {@link scanPattern} read: the verdict, with a refusal's reason. */
+export type PatternScan = {
+    safe: true;
+} | {
+    safe: false;
+    reason: PatternRefusal;
+};
+/**
+ * The walk behind {@link isSafePattern}: one pass over the pattern's syntax,
+ * with no reading of what the atoms match. Escapes and `[...]` classes are
+ * one token each, so a `(`, `|` or `*` inside them is literal. The rules are
+ * blunt by design: each refuses a shape that can backtrack past the value
+ * cap, and with it the safe patterns of the same shape. The check that reads
+ * a pattern's real cost belongs at publish time, in the service that stores
+ * the layout. Refused, in the order the rules are read:
+ *
+ * 1. a pattern longer than {@link MAX_PATTERN_LENGTH};
+ * 2. a backreference, `\1` or `\k<name>`;
+ * 3. a repeated group that holds a quantifier of its own, at any depth:
+ *    `(a+)+`, `(\d{3}-?)+`, `(a+){3}`. A `?` or a `{1}` on the group takes
+ *    it whole or not at all, so `(a+)?` is accepted. A fixed count is copies
+ *    of the group in sequence, so `(\d{4}[- ]?){3}` is accepted;
+ * 4. a repeated group that holds a `|`, at any depth: `(a|ab)+`. A fixed
+ *    count is copies here too, so `(?:a|ab){3}` is accepted;
+ * 5. a quantifier on a lookaround, inside one, or on a group that holds
+ *    one: `(?=a)+`, `(?=.*\d)`, `(?:(?=a)b){3}`;
+ * 6. more than {@link MAX_REPETITIONS} repetitions that can run on in the
+ *    whole pattern, or more than {@link MAX_ANCHORED_REPETITIONS} in one
+ *    anchored at `^`: `\w*\w*\w*-`, `^\w*\w*\w*\w*$`, where `^\w*\w*\w*$`
+ *    and `^[^\s@]+@[^\s@]+\.[^\s@]+$` are accepted;
+ * 7. a count past {@link MAX_PATTERN_VALUE_LENGTH}, on its own or multiplied
+ *    through the counts of the groups that hold it: `\w{513}`, `.{0,1000}`,
+ *    `(?:\b){999}`, `(?:(?:\b){512}){512}`;
+ * 8. {@link MAX_WAYS_STEPS} steps or more from the ways alone: each atom's
+ *    count, once per way of the atoms before it. Thirty `a?`, eight
+ *    `\d{1,9}`, `^(?:\d{1,9}){5}\w{467}$` and sixteen `a?` before `\w{495}$`
+ *    are refused, where a phone, card, IPv4 or optional-scheme URL pattern
+ *    is accepted;
+ * 9. {@link MAX_PATTERN_STEPS} steps or more from the ways and the runs
+ *    together: the same sum, each run multiplying the paths to the atoms
+ *    after it by the cap over the run's rank on its own path (its branch
+ *    and the branches of the groups that hold it, never a sibling `|`
+ *    alternative, so the branches of a `|` add up), and a pattern with no
+ *    `^` running from every position. Twelve `a?` before `\w*\w*$`,
+ *    `\w*\w*-`, `^\w*\w*\w{511}$` and `^\w*!|^` with nine `a?` before
+ *    `\w*\w*!` are refused, where `^\w*\w*\w*!`, `\S+@\S+` and `^\S+@\S+$`
+ *    are accepted;
+ * 10. a pattern RegExp rejects, as `(`.
+ *
+ * An accepted pattern is tested on a value of {@link MAX_PATTERN_VALUE_LENGTH}
+ * characters at most; {@link matchesPattern} fails a longer value untested.
+ */
+export declare function scanPattern(pattern: string): PatternScan;
+/**
+ * Whether a layout author's `Pattern` can be tested without hanging the
+ * plugin. The regular expression runs synchronously on the UI thread, inside
+ * a reducer, on every keystroke, and cannot be interrupted, so the only
+ * control is on the pattern's shape before it runs: the rules of
+ * {@link scanPattern}. A `pattern` that is no string is not refused, so a
+ * layout no schema checked still registers, but {@link matchesPattern}
+ * never compiles it.
+ */
+export declare function isSafePattern(pattern: string): boolean;
+/**
+ * Whether a validation may be registered on a field: every validation but a
+ * `Pattern` that {@link isSafePattern} refuses. Shared by the form-state
+ * reducer, which drops the refused ones, and the TextInput, which reports
+ * them, so the two never disagree on what was dropped.
+ */
+export declare function isSafeInputValidation(validation: InputValidation): boolean;

package/dist/modules/add-to-cart/src/actions/catalog-item.d.ts

@@ -8,4 +8,18 @@ export type CatalogItemResponse = {
     type: typeof CATALOG_ITEM_RESPONSE;
     payload: CatalogItemResponsePayload;
 };
-export type CatalogItemActions = CatalogItemResponse;
+export type CatalogItemExactResponsePayload = {
+    catalogItem: PluginCatalogItem;
+};
+/**
+ * Sets an exact-quantity item to its exact quantity, or to the offer capacity
+ * the other items leave when the exact quantity is above it. The quantity is
+ * read from the item's own rules and the cart in the saga, so a stale closure
+ * never sets another number, and the item cap does not apply to it.
+ */
+export declare const CATALOG_ITEM_EXACT_RESPONSE = "CATALOG_ITEM/EXACT_RESPONSE";
+export type CatalogItemExactResponse = {
+    type: typeof CATALOG_ITEM_EXACT_RESPONSE;
+    payload: CatalogItemExactResponsePayload;
+};
+export type CatalogItemActions = CatalogItemResponse | CatalogItemExactResponse;

package/dist/modules/add-to-cart/src/sagas/index.d.ts

@@ -2,6 +2,7 @@ import { GlobalGateway } from '../../../../libraries/module-connector/src/main';
 import { Log } from '../../../../libraries/domain/src/models';
 export declare const sagaActionTypes: {
     readonly CATALOG_ITEM_RESPONSE: "CATALOG_ITEM/RESPONSE";
+    readonly CATALOG_ITEM_EXACT_RESPONSE: "CATALOG_ITEM/EXACT_RESPONSE";
     readonly RAISE_METRIC: "GLOBAL/RAISE_METRIC";
     readonly PREPARE_SIGNAL: "GLOBAL/PREPARE_SIGNAL";
     readonly OFFER_ENGAGEMENT: "GLOBAL/OFFER_ENGAGEMENT";

package/dist/modules/add-to-cart/src/sagas/update-cart-item/sagas.d.ts

@@ -3,8 +3,9 @@ import { GlobalActions } from '../../../../../libraries/domain/src/behaviors';
 import { Log, PluginCartItem, PluginCatalogItem } from '../../../../../libraries/domain/src/models';
 import { GlobalGateway } from '../../../../../libraries/module-connector/src/main';
 import { Cart } from '@rokt/partner-integration';
-import { CatalogItemResponse } from '../../actions';
+import { CatalogItemExactResponse, CatalogItemResponse } from '../../actions';
 export declare function processPreselectedCatalogItems(logger: (log: Log) => void): Generator<SelectEffect | CallEffect | PutEffect, void, PluginCartItem | null | undefined>;
 export declare function processUpdateCartItem(gateway: GlobalGateway, logger: (log: Log) => void, action: CatalogItemResponse): Generator<SelectEffect | CallEffect | PutEffect, void, undefined | GlobalActions | string>;
+export declare function processSetExactCartItem(gateway: GlobalGateway, logger: (log: Log) => void, action: CatalogItemExactResponse): Generator<SelectEffect | CallEffect | PutEffect, void, unknown>;
 export declare function listenForUpdateCartItemPartnerMessage(gateway: GlobalGateway, logger: (log: Log) => void): Generator<TakeEffect | CallEffect | CancelledEffect | ChannelTakeEffect<Cart.V2.UpdateCartItemPartnerMessageBody>, void, Cart.V2.UpdateCartItemPartnerMessageBody>;
 export declare function processPartnerUpdateCartItem(message: Cart.V2.UpdateCartItemPartnerMessageBody): Generator<SelectEffect | PutEffect, void, PluginCatalogItem | string | number | null | undefined>;

package/dist/modules/add-to-cart/src/selectors/cart/selectors.d.ts

@@ -9,4 +9,36 @@ export declare function getCartItem(state: {
 }, cartItemId: string): PluginCartItem | null;
 export declare function getOfferCartItems(state: AppState): Array<PluginCartItem>;
 export declare function getOfferCartItemsQuantity(state: AppState): number;
+/**
+ * The offer limit the offer's catalog items carry: the cap on the total
+ * quantity across all the offer's cart items, read as the first positive
+ * whole number across the items, the given item's own attributes first
+ * (readOfferQuantityLimit). Undefined when no item carries one, so 0 and an
+ * absent key mean no additional offer limit.
+ */
+export declare function getOfferQuantityLimit(state: AppState, catalogItem?: Pick<PluginCatalogItem, 'copy'>): number | undefined;
+/**
+ * The cap on the total quantity across the offer's cart items: the smaller
+ * of the offer's existing maxTotalItemsQtyInOffer and the offer limit its
+ * items carry (getOfferQuantityLimit), or Infinity when neither is set. Both
+ * apply, in every path that adds to the offer.
+ */
+export declare function getOfferTotalCap(state: AppState, catalogItem?: Pick<PluginCatalogItem, 'copy'>): number;
+/**
+ * The quantity the ordinary update can still add to this item: the smaller
+ * of the offer capacity left under the offer cap (getOfferTotalCap) and the
+ * item's own cap less the quantity held. The own cap is the item's max,
+ * where it sets one, beside its existing per-item cap (getItemCap). An item
+ * with no max of its own keeps its existing cap alone, as before the rules.
+ * An exact item's own rules do not cap it, so the ordinary update keeps its
+ * existing cap alone for it, as before; the exact path bypasses that cap and
+ * the offer capacity bounds it (getCartItemApplicableCap).
+ */
 export declare function getCartItemMaxAddableQuantity(state: AppState, catalogItem: PluginCatalogItem): number;
+/**
+ * The cap this item's quantity can reach under its quantity rules beside the
+ * existing item and offer caps, the offer limit the items carry among them.
+ * With no static data the offer's existing cap is unbounded, so the item's
+ * own limit and cap, and an offer limit on the item itself, still apply.
+ */
+export declare function getCartItemApplicableCap(state: AppState, catalogItem: PluginCatalogItem): number;

package/dist/modules/add-to-cart/src/utils/index.d.ts

@@ -0,0 +1 @@
+export * from './quantity-rules';

package/dist/modules/add-to-cart/src/utils/quantity-rules/index.d.ts

@@ -0,0 +1 @@
+export * from './quantity-rules';

package/dist/modules/add-to-cart/src/utils/quantity-rules/quantity-rules.d.ts

@@ -0,0 +1,174 @@
+import { PluginCatalogItem } from '../../../../../libraries/domain/src/models';
+/**
+ * The keys under which the transport emits the quantity rules on a catalog
+ * item's `copy` map, each mapped to the name the plugin uses for it. The
+ * keys carry the `provider.` prefix every partner-supplied field on the map
+ * carries, and each names the quantity it bounds, beside the item's
+ * `maxItemCount` and the offer's `maxTotalItemsQtyInOffer`, so a layout
+ * reads a rule as `%^DATA.catalogItem.copy.provider.quantityLimit^%`. Each
+ * value is a whole number as a string, and a rule that does not apply to the
+ * item is absent or 0. The first four are the item's own rules
+ * (readQuantityRules). The offer limit is the offer's: the transport writes
+ * the offer-wide max on every item of the offer, and it caps the total
+ * quantity across all the offer's items (readOfferQuantityLimit). The
+ * boundary is this map alone: the rest of the plugin reads the rules by the
+ * names on the left.
+ */
+export declare const QUANTITY_RULE_KEYS: {
+    readonly max: "provider.quantityLimit";
+    readonly min: "provider.minimumQuantity";
+    readonly multiple: "provider.quantityMultiple";
+    readonly exact: "provider.exactQuantity";
+    readonly offerLimit: "provider.offerQuantityLimit";
+};
+export type QuantityRules = {
+    /**
+     * The per-item maximum: the max the item sets, or Infinity when it sets
+     * none, or 0, whatever other rules it carries. The transport supplies the
+     * max where one applies, so the plugin never defaults it, and an item
+     * without one is bounded by its existing per-item cap and the offer caps
+     * alone. Never null.
+     */
+    max: number;
+    /** The least quantity the item can hold besides 0; 0 when absent. */
+    min: number;
+    /** The step every quantity besides 0 is a multiple of; 1 when absent. */
+    multiple: number;
+    /**
+     * The only quantity the item can hold besides 0, or the offer capacity left
+     * by the other items when that is lower; absent when unset.
+     */
+    exact?: number;
+};
+export type ExactRules = QuantityRules & {
+    exact: number;
+};
+export type QuantityBounds = {
+    /**
+     * The item's existing per-item minimum, a floor under the rules; 0 when
+     * absent.
+     */
+    minItemCount: number;
+    /** The cap the item's own rules set, from getItemCap. */
+    itemCap: number;
+    /**
+     * The cap the quantity can reach under the offer capacity as well, from
+     * getApplicableCap, or a bound the caller sets in its place, at or below
+     * the item cap. Only the item cap overrides the minimum, so this cap admits
+     * nothing when it is below the first admitted multiple.
+     */
+    cap: number;
+};
+export type CapInputs = {
+    /** The item's existing per-item cap. */
+    maxItemCount?: number;
+    /**
+     * The offer's existing cap on the total quantity across its items,
+     * maxTotalItemsQtyInOffer; absent, or null as the offer may carry it, when
+     * the offer sets none.
+     */
+    offerCap?: number | null;
+    /**
+     * The offer limit the items carry (readOfferQuantityLimit), a second cap
+     * on the same total; absent when no item carries one. Both caps apply and
+     * the smaller wins (getOfferCap).
+     */
+    offerLimit?: number;
+    /** The offer's total quantity minus this item's own quantity. */
+    offerQuantityOfOthers: number;
+};
+/**
+ * Reads the item's four quantity rules from a catalog item's attributes,
+ * applying the effective defaults (no max, minimum 0, multiple 1, no exact
+ * quantity) so that an item with no rules behaves as the counter does today.
+ * A max that is absent or 0 reads as no max of its own, Infinity, whatever
+ * other rules the item carries: the transport supplies the max where one
+ * applies, so the plugin never defaults it, and the item's existing per-item
+ * cap and the offer caps alone bound it. The offer limit is the offer's and
+ * is not an item rule (readOfferQuantityLimit).
+ */
+export declare function readQuantityRules(catalogItem: Pick<PluginCatalogItem, 'copy'>): QuantityRules;
+/**
+ * The offer limit the items of an offer carry: the cap on the total quantity
+ * across all the offer's cart items, which the transport writes under the
+ * same key, with the same value, on every item of the offer. Read as the
+ * first positive whole number across the offer's catalog items, the item's
+ * own attributes first, so an item that lacks the key is still bounded by
+ * the limit its siblings carry. Undefined when no item carries one: the
+ * transport writes 0 for no additional offer limit, and 0, like an absent or
+ * malformed value, is no rule. It applies beside the offer's existing
+ * maxTotalItemsQtyInOffer, and the smaller wins (getOfferCap).
+ */
+export declare function readOfferQuantityLimit(catalogItems: ReadonlyArray<Pick<PluginCatalogItem, 'copy'>>, ownItem?: Pick<PluginCatalogItem, 'copy'>): number | undefined;
+/**
+ * Whether the item carries a rule beyond the effective defaults: a max of
+ * its own, a minimum, a multiple or an exact quantity. An item with no rule
+ * keeps today's behaviour under its existing cap and the offer caps alone.
+ * The offer limit is the offer's and makes no item a rule-carrying one.
+ */
+export declare function hasQuantityRules(rules: QuantityRules): boolean;
+export declare function isExactRules(rules: QuantityRules): rules is ExactRules;
+/**
+ * The cap the item's own rules set: the smaller of its max and its existing
+ * per-item cap. An item that sets no max, with or without other rules, has
+ * no max of its own, so its existing cap alone bounds it, as before the
+ * rules. An exact item has no own cap, because its exact quantity overrides
+ * its own limits; the offer capacity alone bounds it, in getApplicableCap.
+ * This cap alone overrides the minimum, and a quantity the cart already holds
+ * is corrected against it alone, because the offer capacity bounds additions
+ * and never cuts an existing quantity.
+ */
+export declare function getItemCap(rules: QuantityRules, maxItemCount: number | undefined): number;
+/**
+ * The cap on the total quantity across the offer's items: the smaller of the
+ * offer's existing maxTotalItemsQtyInOffer and the offer limit the items
+ * carry, each applying where it is set, or Infinity when neither is.
+ */
+export declare function getOfferCap(caps: Pick<CapInputs, 'offerCap' | 'offerLimit'>): number;
+/**
+ * The cap an item's quantity can reach: the smaller of its own cap and the
+ * offer capacity left by the other items under the offer cap (getOfferCap),
+ * or Infinity when none applies. An exact item has no own cap, so for it
+ * this is the offer capacity alone: an exact quantity above it is capped
+ * there.
+ */
+export declare function getApplicableCap(rules: QuantityRules, caps: CapInputs): number;
+/**
+ * The correction applied to a typed quantity when it is committed and to an
+ * existing quantity on the first render. Zero and anything that is not a
+ * positive number mean removal. Any positive quantity on an exact item becomes
+ * the exact quantity, or the cap when the exact quantity is above it, or
+ * removal when the cap admits nothing. Otherwise a positive quantity becomes
+ * the multiple at or below it, raised to the first admitted multiple when it
+ * is below that and cut to the last when it is above it, the item's own cap
+ * winning over the minimum when the two disagree. So with the default step a
+ * quantity below the minimum becomes the minimum and a quantity above the cap
+ * becomes the cap. The first multiple lies at or above the item's existing
+ * minimum too, so a correction never goes below that floor. A cap that admits
+ * nothing means removal.
+ */
+export declare function normalizeQuantity(rules: QuantityRules, bounds: QuantityBounds, quantity: number): number;
+/**
+ * The quantity the increment button selects from a normalized quantity: the
+ * next admitted multiple above it. From zero with a minimum of 3 and a
+ * multiple of 2 that is 4, and from 4 it is 6. At the last multiple under the
+ * cap it changes nothing, and the increment is disabled there, as it is from
+ * zero when the cap admits nothing. On an exact item it selects the exact
+ * quantity, or the cap below it, and changes nothing once the quantity is at
+ * or above that.
+ */
+export declare function plusStep(rules: QuantityRules, bounds: QuantityBounds, quantity: number): number;
+/**
+ * The quantity the decrement button selects from a normalized quantity: the
+ * previous multiple below it, or 0 when that multiple is below the first
+ * admitted one. From 4 with a minimum of 3 and a multiple of 2 it removes the
+ * item, because 2 is below the minimum. On an exact item any positive
+ * quantity goes to zero.
+ */
+export declare function minusStep(rules: QuantityRules, bounds: QuantityBounds, quantity: number): number;
+/**
+ * Whether the increment button is disabled: when no admitted multiple lies
+ * above the quantity under the cap, when no more of the item can be added to
+ * the offer, or once an exact item holds its quantity, or the cap below it.
+ */
+export declare function isIncrementDisabled(rules: QuantityRules, bounds: QuantityBounds, quantity: number, maxAddableQuantity: number): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokt/dcui-orchestrator",
-  "version": "1.2.1-rc.50",
+  "version": "1.2.1-rc.52",
   "description": "Rokt's DCUI rendering process",
   "main": "dist/index.cjs",
   "module": "dist/index.js",