@rokt/dcui-orchestrator 1.2.1-rc.6 → 1.2.1-rc.61

package/dist/libraries/orchestrator/src/components/progress-indicator/types.d.ts

@@ -1,87 +1 @@
-import { ProgressIndicatorModel, WhenPredicate } from '@rokt/dcui-layout-schema';
-export interface StateProps {
-    /** The number of indicators */
-    numOfIndicators: number;
-    /** The currently active index. */
-    activeIndex: number;
-    /** The index of the indicator to start displaying from **/
-    startIndex: number;
-}
-export interface OwnProps {
-    /**
-     *  - `indicator`: The string content of the indicator.
-     *  - `styles`:
-     *    * `elements`:
-     *      * `own`:
-     *        - `container`
-     *        - `background`
-     *        - `border`
-     *        - `dimension`
-     *        - `flexChild`
-     *        - `spacing`
-     *      * `indicator`:
-     *        - `container`
-     *        - `background`
-     *        - `border`
-     *        - `dimension`
-     *        - `flexChild`
-     *        - `spacing`
-     *        - `text`
-     *      * `activeIndicator`:
-     *        - `container`
-     *        - `background`
-     *        - `border`
-     *        - `dimension`
-     *        - `flexChild`
-     *        - `spacing`
-     *        - `text`
-     *      * `seenIndicator`:
-     *        - `container`
-     *        - `background`
-     *        - `border`
-     *        - `dimension`
-     *        - `flexChild`
-     *        - `spacing`
-     *        - `text`
-     *    * `transitions`:
-     *      - `type`: 'Conditional'
-     *      - `transition`:
-     *        * `predicates`: WhenPredicate[]
-     *        * `duration`: number
-     *        * `value`:
-     *          * `own`:
-     *            - `container`
-     *            - `background`
-     *            - `border`
-     *            - `dimension`
-     *            - `flexChild`
-     *            - `spacing`
-     *          * `indicator`:
-     *            - `container`
-     *            - `background`
-     *            - `border`
-     *            - `dimension`
-     *            - `flexChild`
-     *            - `spacing`
-     *            - `text`
-     *          * `activeIndicator`:
-     *            - `container`
-     *            - `background`
-     *            - `border`
-     *            - `dimension`
-     *            - `flexChild`
-     *            - `spacing`
-     *            - `text`
-     *          * `seenIndicator`:
-     *            - `container`
-     *            - `background`
-     *            - `border`
-     *            - `dimension`
-     *            - `flexChild`
-     *            - `spacing`
-     *            - `text`
-     */
-    schema: ProgressIndicatorModel<WhenPredicate>;
-}
-export interface ProgressIndicatorProps extends OwnProps, StateProps {
-}
+export type { ProgressIndicatorProps, ProgressIndicatorStateProps as StateProps, ProgressIndicatorSchemaProps as OwnProps, } from '../../../../dcui-components/src/index';

package/dist/libraries/orchestrator/src/measurement/creative-measurement.d.ts

@@ -0,0 +1,54 @@
+import { RaiseSignal } from '../../../domain/src/behaviors';
+import { Impression, Viewed } from '../../../domain/src/models';
+export interface CreativeIdentity {
+    creativeInstanceGuid: string;
+    offerPositionIndex: number;
+}
+export interface PresentationIdentity extends CreativeIdentity {
+    sessionId: string;
+    revision: number;
+}
+export type Qualification = Pick<Viewed, 'supportedByBrowser' | 'inferred'>;
+type MeasurementStore = {
+    dispatch(action: RaiseSignal): void;
+};
+/** One registry per parent store/selection, never one per child session. */
+export declare function getContinuousMeasurement(store: MeasurementStore): CreativeMeasurement;
+/**
+ * Parent-owned creative signals. Layout/slot signals deliberately bypass this
+ * ledger. Registration is explicit: the disabled capability and ordinary layouts
+ * must never change their existing measurement just because a child exists.
+ */
+export declare class CreativeMeasurement {
+    private readonly emit;
+    private readonly creatives;
+    private readonly presentations;
+    private sessionId;
+    private highestRevision;
+    private occluded;
+    private readonly listeners;
+    constructor(emit: (action: RaiseSignal) => void);
+    /** A new served selection is a new lifetime; reopening the child is not. */
+    resetSelection(): void;
+    registerCreative(identity: CreativeIdentity, ownsViewability: boolean): void;
+    getEmbeddedPolicy(identity: CreativeIdentity): {
+        registered: boolean;
+        ownsViewability: boolean;
+        occluded: boolean;
+    };
+    subscribe(listener: () => void): () => void;
+    setOccluded(occluded: boolean): void;
+    /** Consumes only opted-in CREATIVE signals; false means use the legacy path. */
+    reportEmbedded(identity: CreativeIdentity, signal: Impression | Viewed): boolean;
+    /** Called after the child applied the snapshot, not when it was configured. */
+    acknowledge(identity: PresentationIdentity): boolean;
+    beginSession(sessionId: string): void;
+    endSession(): void;
+    reportExpanded(identity: PresentationIdentity, qualification?: Qualification): boolean;
+    private getCreative;
+    private matchesAcknowledged;
+    private render;
+    private qualify;
+    private notify;
+}
+export {};

package/dist/libraries/orchestrator/src/models/state/global-offer-data-state.d.ts

@@ -1,3 +1,9 @@
 export type GlobalOfferDataState = {
     [key: string]: unknown;
 };
+export type OfferStateCartItem = {
+    cartItemId: string;
+    quantity: number;
+};
+export declare function offerStateKey(position: number): string;
+export declare function readOfferStateCart(state: GlobalOfferDataState, position: number): Array<OfferStateCartItem>;

package/dist/libraries/orchestrator/src/models/state/module.d.ts

@@ -1,3 +1,4 @@
 export type ModuleState = {
     loadedModules: Array<string>;
+    cartListenerCounts: Record<number, number>;
 };

package/dist/libraries/orchestrator/src/reducers/progression/reducer.d.ts

@@ -1,5 +1,13 @@
 import { AnyAction } from '@reduxjs/toolkit';
 import { ProgressionState } from '../../models';
 export declare function makeInitialProgressionState(): null;
+/**
+ * A group size is usable only as a whole number from 1 up to the total count.
+ * The value comes from the layout's viewableItems, which the plugin does not
+ * re-check at runtime: a fraction below 1 makes totalCount / groupSize as
+ * large as the layout likes, and a fraction above 1 produces fractional offer
+ * indexes.
+ */
+export declare function isValidGroupSize(groupSize: number, totalCount: number): boolean;
 export declare function getNumberOfGroups(totalCount: number, groupSize: number): number;
 export declare function progressionReducer(state: ProgressionState | undefined, action: AnyAction): ProgressionState;

package/dist/libraries/orchestrator/src/sagas/child-layouts/continuous-child-host.d.ts

@@ -0,0 +1,15 @@
+import { ContinuousPresentationInput } from '../../../../domain/src/behaviors';
+import { ContinuousGatewayService } from '../../../../module-connector/src/main';
+import type { AppStore } from '../../store';
+import { PluginService } from '../../plugin-service';
+import { ContinuousChildCoordinator } from './continuous-child';
+export declare function isContinuousEngagement(action: unknown): boolean;
+/** Connect the coordinator to trusted selected slots and the existing module response path. */
+export declare function makeContinuousChildHost(store: Pick<AppStore, 'getState' | 'dispatch' | 'subscribe'>, service: PluginService, enabled?: boolean): {
+    gateway: ContinuousGatewayService | undefined;
+    coordinator: ContinuousChildCoordinator;
+    getSequence: (key: string, onRejected?: (reason: string) => void) => ContinuousPresentationInput[] | undefined;
+    transformAction(action: unknown): unknown;
+    observeAction(action: unknown): void;
+    close(): Promise<void>;
+};

package/dist/libraries/orchestrator/src/sagas/child-layouts/continuous-child.d.ts

@@ -0,0 +1,52 @@
+import { LinkOpenTarget } from '@rokt/dcui-layout-schema';
+import { ContinuousExposure, ContinuousPresentation, ContinuousPresentationInput } from '../../../../domain/src/behaviors';
+export interface ContinuousChildTransport {
+    send(name: string, payload: object): Promise<void>;
+    onEvent(name: string): {
+        subscribe(callback: (value: unknown) => void): {
+            unsubscribe(): void;
+        };
+    };
+    close(): Promise<void>;
+    onClose(): Promise<void>;
+}
+export interface ContinuousChildDependencies {
+    createChild(presentation: ContinuousPresentation): Promise<ContinuousChildTransport>;
+    getSequence(key: string): ContinuousPresentationInput[] | undefined;
+    getActivePosition(): number;
+    navigate(position: number): void;
+    respond(position: number, key: 'positive' | 'negative', openLinks?: LinkOpenTarget): Promise<void>;
+    dismiss(position: number, dismissalMethod?: string): Promise<void>;
+    onApplied?(presentation: ContinuousPresentation): void;
+    onExposure?(presentation: ContinuousPresentation, report: ContinuousExposure): void;
+    onOcclusion?(occluded: boolean): void;
+    onError?(error: Error): void;
+}
+export declare function compatibleContinuousSequence(sequence: ContinuousPresentationInput[]): boolean;
+/** One parent-owned session. Never rebinds the launching module's gateway. */
+export declare class ContinuousChildCoordinator {
+    private readonly dependencies;
+    private child?;
+    private sequence;
+    private current?;
+    private applied?;
+    private acknowledged;
+    private subscriptions;
+    private actionIds;
+    private busy;
+    private opening;
+    private ready;
+    private epoch;
+    private acknowledgementTimer?;
+    private key;
+    constructor(dependencies: ContinuousChildDependencies);
+    open(position: number, key: string): Promise<boolean>;
+    /** Called on authoritative parent progression changes. */
+    sync(): void;
+    private makePresentation;
+    private push;
+    private request;
+    private awaitAcknowledgement;
+    private reset;
+    close(): Promise<void>;
+}

package/dist/libraries/orchestrator/src/sagas/index.d.ts

@@ -1,4 +1,4 @@
 import { GlobalGatewayFactory } from '../../../module-connector/src/main';
 import { PluginService } from '../plugin-service';
 export * from './plugin';
-export declare function appSagas(pluginService: PluginService, gatewayFactory: GlobalGatewayFactory): Generator<import("redux-saga/effects").AllEffect<import("redux-saga/effects").ForkEffect<void> | Generator<import("redux-saga/effects").CallEffect | import("redux-saga/effects").TakeEffect, void, import("redux-saga").TakeableChannel<unknown> | undefined> | Generator<import("redux-saga/effects").CallEffect | import("redux-saga/effects").ActionChannelEffect | import("redux-saga/effects").ChannelTakeEffect<unknown>, void, import("redux-saga").TakeableChannel<unknown> | undefined>>, void, unknown>;
+export declare function appSagas(pluginService: PluginService, gatewayFactory: GlobalGatewayFactory, closeContinuous?: () => Promise<void>): Generator<import("redux-saga/effects").AllEffect<import("redux-saga/effects").ForkEffect<void> | Generator<import("redux-saga/effects").CallEffect | import("redux-saga/effects").TakeEffect, void, import("redux-saga").TakeableChannel<unknown> | undefined> | Generator<import("redux-saga/effects").CallEffect | import("redux-saga/effects").ActionChannelEffect | import("redux-saga/effects").ChannelTakeEffect<unknown>, void, import("redux-saga").TakeableChannel<unknown> | undefined>>, void, unknown>;

package/dist/libraries/orchestrator/src/sagas/offer-engagement/sagas.d.ts

@@ -3,9 +3,9 @@ import { PluginCreativeResponseOption } from '../../../../domain/src/models';
 import { CallEffect, PutEffect, SelectEffect, TakeEffect } from 'redux-saga/effects';
 import { ReportError, ClosePlugin, OfferEngagement } from '../../actions';
 import { ContextService, PartnerInteractionService } from '../../../../plugin-utils/src/index';
-import { WindowRef } from '../../../../layout-renderer-utils/src/index';
-type NextValues = WindowRef | CallEffect | null | undefined;
-type OfferCompletionResult = 'SUCCESS' | 'UNSPECIFIED' | 'ERROR' | 'EXPLICIT_DISMISSAL' | 'IMPLICIT_DISMISSAL' | 'END';
+import { HandleUnavailable, WindowRef } from '../../../../layout-renderer-utils/src/index';
+type NextValues = WindowRef | HandleUnavailable | CallEffect | null | undefined;
+type OfferCompletionResult = 'SUCCESS' | 'ERROR' | 'EXPLICIT_DISMISSAL' | 'IMPLICIT_DISMISSAL' | 'END';
 declare const handleUrlResponse: (args_0: PluginCreativeResponseOption, args_1: ContextService, args_2: import("@rokt/plugin").SenderReceiver, args_3: OfferEngagement) => Generator<TakeEffect | NextValues | PutEffect<RaiseSignal | ClosePlugin | ReportError>, OfferCompletionResult, NextValues>;
 export declare function processOfferResponse(dependencies: {
     context: ContextService;

package/dist/libraries/orchestrator/src/sagas/partner-cart-sync/sagas.d.ts

@@ -1,6 +1,6 @@
 import { CallEffect, ChannelTakeEffect, PutEffect, SelectEffect } from 'redux-saga/effects';
 import { Cart } from '@rokt/partner-integration';
 import { PartnerInteractionService } from '../../../../plugin-utils/src/index';
-import { SlotState } from '../../models';
-export declare function reconcilePartnerCartItem(message: Cart.V2.UpdateCartItemPartnerMessageBody): Generator<SelectEffect | PutEffect, void, SlotState>;
+import { AppState } from '../../models';
+export declare function reconcilePartnerCartItem(message: Cart.V2.UpdateCartItemPartnerMessageBody): Generator<SelectEffect | PutEffect, void, AppState>;
 export declare function listenForPartnerCartItemSync(partner: PartnerInteractionService): Generator<ChannelTakeEffect<Cart.V2.UpdateCartItemPartnerMessageBody> | CallEffect | PutEffect, void, Cart.V2.UpdateCartItemPartnerMessageBody>;

package/dist/libraries/orchestrator/src/sagas/progression/sagas.d.ts

@@ -1,11 +1,17 @@
 import { CallEffect, PutEffect, SelectEffect, TakeEffect } from 'redux-saga/effects';
-import { ProcessProgression, StateActions, UpdateActiveBreakpointAction } from '../../actions';
+import { InitialiseBreakpointAction, ProcessProgression, StateActions, UpdateActiveBreakpointAction } from '../../actions';
 import { CloseOnNegativeResponsePolicy } from '@rokt/dcui-layout-schema';
 type ProgressResult = {
     exists: boolean;
     isLastOffer: boolean;
 };
 type NextValues = ProgressResult | boolean | number | CloseOnNegativeResponsePolicy | undefined;
-export declare function updateGroupSize(action: UpdateActiveBreakpointAction): Generator<SelectEffect | PutEffect<StateActions>, void, Array<number> | undefined>;
+/**
+ * Sends the group size for the breakpoint the action names, on the first
+ * breakpoint read (INITIALISE_BREAKPOINT) and on every later change
+ * (UPDATE_ACTIVE_BREAKPOINT). The first read names no breakpoint when the
+ * channel reports none, and the reducer reads that as the default one.
+ */
+export declare function updateGroupSize(action: UpdateActiveBreakpointAction | InitialiseBreakpointAction): Generator<SelectEffect | PutEffect<StateActions>, void, Array<number> | undefined>;
 export declare function processProgress(action: ProcessProgression): Generator<SelectEffect | CallEffect | PutEffect | TakeEffect, void, NextValues>;
 export {};

package/dist/libraries/orchestrator/src/sagas/utils/distribution.d.ts

@@ -14,3 +14,24 @@ export type Distribution = {
 };
 export declare function getDistribution(layout: LayoutSchemaModel): Distribution | undefined;
 export declare function getDistributionViewableItems(distribution: Distribution | undefined): Array<number> | undefined;
+/**
+ * The layout's viewableItems entry for a breakpoint, made safe for the
+ * progression reducer: a value of at least 1 is rounded down to a whole
+ * number, so 2.5 keeps a group of 2, and anything else (a value below 1,
+ * a missing entry, a value that is not a finite number) becomes 1, the
+ * value the reducer already uses when a layout names no group size.
+ */
+export declare function normaliseGroupSize(value: number | undefined): number;
+/**
+ * True when normaliseGroupSize uses a value other than the one the layout
+ * configured, the case the plugin saga reports as INVALID_GROUP_SIZE. A
+ * missing entry is a layout that names no group size, not a changed one.
+ */
+export declare function isGroupSizeChanged(value: number | undefined): boolean;
+/**
+ * A normalised group size capped at the number of offers the placement
+ * holds: the reducer refuses a group larger than the placement, so one offer
+ * with viewableItems [2] at a breakpoint keeps a group of 1 instead of a
+ * null progression.
+ */
+export declare function capGroupSize(groupSize: number, slotSize: number): number;

package/dist/libraries/orchestrator/src/sagas/utils/index.d.ts

@@ -3,5 +3,8 @@ export { Distribution } from './distribution';
 declare const _default: {
     getDistribution(layout: import("@rokt/dcui-layout-schema").LayoutSchemaModel): distributionUtils.Distribution | undefined;
     getDistributionViewableItems(distribution: distributionUtils.Distribution | undefined): Array<number> | undefined;
+    normaliseGroupSize(value: number | undefined): number;
+    isGroupSizeChanged(value: number | undefined): boolean;
+    capGroupSize(groupSize: number, slotSize: number): number;
 };
 export default _default;

package/dist/libraries/orchestrator/src/selectors/global-offer-data-state/selectors.d.ts

@@ -1,7 +1,14 @@
-import { GlobalOfferDataState } from '../../models';
+import { GlobalOfferDataState, OfferStateCartItem } from '../../models';
 export declare function getTotalCartQty(state: {
     globalOfferDataState: GlobalOfferDataState;
 }): number;
 export declare function getOfferState(state: {
     globalOfferDataState: GlobalOfferDataState;
 }, position: number): unknown;
+/**
+ * The cart held for one position: what its module last published, with
+ * the partner updates retained while it was unmounted.
+ */
+export declare function getOfferStateCart(state: {
+    globalOfferDataState: GlobalOfferDataState;
+}, position: number): Array<OfferStateCartItem>;

package/dist/libraries/plugin-utils/src/plugin-service/display.d.ts

@@ -1,6 +1,7 @@
 import { DisplayInterface, PluginInterface } from '@rokt/plugin';
 import { EventChannel } from 'redux-saga';
 export type DisplayService = Pick<DisplayInterface, 'setDisplaySettings'> & {
+    scrollHostToViewportOffset?(viewportOffsetY: number): Promise<void>;
     activeBreakpointEventChannel?(breakpoints: Record<string, number>): EventChannel<string>;
 };
 export declare const makeDisplayService: (pluginInterface: Pick<PluginInterface, 'display'>) => DisplayService;

package/dist/libraries/saga-utils/src/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './catalog-translator';
+export * from './quantity-rules';
 export * from './stringify';
 export * from './take-in-sequence';
 export * from './take-one';

package/dist/libraries/saga-utils/src/utils/quantity-rules.d.ts

@@ -0,0 +1,184 @@
+import { PluginCatalogItem } from '../../../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 cap the ordinary update keeps for an item's quantity: the smaller of
+ * the applicable cap (getApplicableCap) and the item's existing per-item cap,
+ * which the ordinary update keeps for an exact item too (the exact path
+ * alone bypasses it). A quantity at or below it can be held, and an increase
+ * above it is refused, wherever a partner update is applied to a cart: the
+ * module's own update and the hold the orchestrator keeps for a module that
+ * is not mounted read this one cap, so the two never disagree on a quantity.
+ */
+export declare function getUpdateCap(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/dist/modules/add-to-cart/src/actions/cart.d.ts

@@ -1,4 +1,5 @@
 import { PluginCatalogItem } from '../../../../libraries/domain/src/models';
+import { CartState } from '../models';
 export type UpdateCartPayload = {
     catalogItem: PluginCatalogItem;
     quantity: number;
@@ -8,4 +9,9 @@ export type UpdateCart = {
     type: typeof UPDATE_CART;
     payload: UpdateCartPayload;
 };
-export type CartActions = UpdateCart;
+export declare const HYDRATE_RETAINED_CART = "CART/HYDRATE_RETAINED";
+export type HydrateRetainedCart = {
+    type: typeof HYDRATE_RETAINED_CART;
+    payload: CartState;
+};
+export type CartActions = UpdateCart | HydrateRetainedCart;

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/components/when-catalog-quantity/when-catalog-quantity.d.ts

@@ -3,7 +3,8 @@ import { LayoutSchemaModel, EqualityWhenCondition, OrderableWhenCondition } from
 export type QuantityCondition = EqualityWhenCondition | OrderableWhenCondition;
 export interface QuantityPredicate {
     condition: QuantityCondition;
-    value: number;
+    /** Fixed number or a numeric string resolved through the current data mapper. */
+    value: number | string;
 }
 export interface WhenCatalogQuantityModel {
     cartItemId: string;

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

@@ -1,4 +1,5 @@
 import { AnyAction } from '@reduxjs/toolkit';
 import { CartState, AppSettingsCartItemState } from '../../models';
-export declare function makeInitialCartState(cart: Array<AppSettingsCartItemState>): CartState;
+import { PluginCatalogItem } from '../../../../../libraries/domain/src/models';
+export declare function makeInitialCartState(cart: Array<AppSettingsCartItemState>, catalogItems?: Array<PluginCatalogItem>): CartState;
 export declare function cartReducer(state: CartState | undefined, action: AnyAction): CartState;

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";
@@ -26,4 +27,4 @@ export declare const sagaActionTypes: {
     readonly VALIDATE_FORM_FIELDS: "GLOBAL/VALIDATE_FORM_FIELDS";
     readonly REPORT_ERROR: "ERROR/REPORT";
 };
-export declare function appSagas(gateway: GlobalGateway, logger: (log: Log) => void): Generator<import("redux-saga/effects").AllEffect<import("redux-saga/effects").ForkEffect<void>>, void, unknown>;
+export declare function appSagas(gateway: GlobalGateway, logger: (log: Log) => void): Generator<import("redux-saga/effects").CallEffect<void> | import("redux-saga/effects").ForkEffect<never> | import("redux-saga/effects").AllEffect<import("redux-saga/effects").ForkEffect<void>>, void, unknown>;

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

@@ -1,10 +1,13 @@
-import { CallEffect, CancelledEffect, ChannelTakeEffect, PutEffect, SelectEffect, TakeEffect } from 'redux-saga/effects';
+import { EventChannel } from 'redux-saga';
+import { CallEffect, ChannelTakeEffect, PutEffect, SelectEffect, TakeEffect, FlushEffect, ForkEffect } from 'redux-saga/effects';
 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 listenForUpdateCartItemPartnerMessage(gateway: GlobalGateway, logger: (log: Log) => void): Generator<TakeEffect | CallEffect | CancelledEffect | ChannelTakeEffect<Cart.V2.UpdateCartItemPartnerMessageBody>, void, Cart.V2.UpdateCartItemPartnerMessageBody>;
+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, preparedChannel?: EventChannel<Cart.V2.UpdateCartItemPartnerMessageBody>): Generator<TakeEffect | CallEffect | PutEffect | SelectEffect | ChannelTakeEffect<Cart.V2.UpdateCartItemPartnerMessageBody>, void, Cart.V2.UpdateCartItemPartnerMessageBody>;
+export declare function initializePartnerCartSync(gateway: GlobalGateway, logger: (log: Log) => void): Generator<CallEffect | FlushEffect<Cart.V2.UpdateCartItemPartnerMessageBody> | ForkEffect, void, Array<Cart.V2.UpdateCartItemPartnerMessageBody>>;
 export declare function processPartnerUpdateCartItem(message: Cart.V2.UpdateCartItemPartnerMessageBody): Generator<SelectEffect | PutEffect, void, PluginCatalogItem | string | number | null | undefined>;