@callimacus/thamyr-core 4.18.0 → 4.20.0

package/dist/types/index.d.ts

@@ -920,6 +920,23 @@ type ChapterOutput = {
          */
         type: string;
     }>;
+    /**
+     * Blocks this round did not send because one of their contents failed. For the site's developer: log them, never render them. The reason stays server-side; `callimacus thamyr probe` shows it.
+     */
+    warnings?: Array<{
+        /**
+         * The key of the block that was not sent.
+         */
+        block: string;
+        /**
+         * The id of its content that failed.
+         */
+        content: string;
+        /**
+         * `shortfall`: the content found fewer items than its `minItems` and its `onShort` is `fail`. `error`: anything else threw.
+         */
+        cause: 'shortfall' | 'error';
+    }>;
     status: ChapterStatus$1;
 };
 type CreateRoundContextOutput = {
@@ -3935,6 +3952,94 @@ type TtsAudio = {
  */
 declare function extractTtsAudio(data: unknown): TtsAudio | undefined;
 
+type CreateRoundPayload = InteractionPayloadMap[UserInteractionType.CREATE_ROUND];
+/**
+The landing value blocks and conditions read (`{{input.value}}`); the server caps it at 200 characters.
+*/
+declare const LANDING_VALUE_MAX_LENGTH = 200;
+/**
+ The `create-round` payload that opens the landing page: a round with no message,
+ composed from the tenant's landing configuration.
+ @param value - Optional landing value — a page slug, a campaign, whatever the
+ tenant's landing blocks were written to read.
+ @param options - The story to continue and the language to compose in.
+ */
+declare function landingRound(value?: string, options?: RoundOptions): CreateRoundPayload;
+/**
+ The `create-round` payload for a declared interaction. Blocks answer it by
+ naming the id in their condition; the block key it carries lets a block whose
+ `patchOn` names the interaction be patched in place.
+ */
+declare function interactionRound<I extends InteractionId>(id: I, options?: InteractionOptions<I>): CreateRoundPayload;
+/**
+ The receptor labels the classifier assigned a round — the per-message
+ classification, not the session intent. Reads `receptors`, falling back to the
+ `intent` name servers used before the rename (kept one release as an alias).
+ */
+declare function receptorsOf(chapter: Pick<Chapter, 'receptors' | 'intent'>): string[];
+/**
+ A block's key — the identity everything attributes, pins and links by. `type`
+ is a render hint two blocks may share. Only custom blocks carry one, and only
+ on rounds recorded since keys travel on the wire.
+ */
+declare function blockKeyOf(block: Block): string | undefined;
+/**
+The block the flow emits when adding to cart needs the visitor to pick a size.
+*/
+declare const ADD_TO_CART_RESULT_BLOCK = "custom:addToCartResult";
+/**
+How an add-to-cart request resolved; the flow attaches it to every block of the round as `data.addToCart`.
+*/
+type AddToCartResult = {
+    status: 'resolved';
+    variantId: string;
+    productName: string;
+    size: string;
+} | {
+    status: 'size_selection_needed';
+    productSku: string;
+    productName: string;
+    availableSizes: Array<{
+        size: string;
+        variantId: string;
+        orderable: boolean;
+    }>;
+} | {
+    status: 'error';
+};
+/**
+The add-to-cart result a block carries, when the round resolved one.
+
+Every field is checked, not only the status: the block's data is whatever the round
+put there, and a half-written result would otherwise reach a caller as a complete one
+— with `undefined` where the type promises a string.
+*/
+declare function addToCartResultOf(block: {
+    data?: unknown;
+}): AddToCartResult | undefined;
+/**
+ The round with a `block-patch` applied, as the server stored it: `values`,
+ `inputs` and `textRuns` merged into the animation at `contentId` (a dotted path
+ into `block.data`), everything else left as it was. Returns `chapter` itself
+ when the patch is for another round, a block it does not show, or a place that
+ holds no animation, so a caller can tell nothing changed.
+
+ `fire` is not written: triggers play once, when the patch arrives, and
+ keeping them would replay them on every render and reload.
+ */
+declare function applyBlockPatch(chapter: Chapter, patch: BlockPatch): Chapter;
+/**
+ A block the round did not send because one of its contents failed: its key, the content's id, and
+ `shortfall` (fewer items than `minItems` under `onShort: "fail"`) or `error`. The reason stays
+ server-side; `callimacus thamyr probe` shows it.
+ */
+type RoundWarning = NonNullable<Chapter['warnings']>[number];
+/**
+ The round's warnings not reported yet. A round is re-sent on every streamed chunk, so each warning
+ arrives many times; `reported` remembers which were already handed on.
+ */
+declare function newRoundWarnings(chapter: Pick<Chapter, 'id' | 'warnings'>, reported: Set<string>): RoundWarning[];
+
 /**
  The error surface hosts subscribe to via `onError`: server `error`-channel
  messages plus terminal connection refusals. `reason` is present only on
@@ -3951,11 +4056,14 @@ type CallimacusErrorMessage = ErrorMessage;
 type ServerResponseCallback<T = ThamyrResponse> = (response: T) => void;
 type ConnectionStatusCallback = (isConnected: boolean) => void;
 type ErrorCallback = (error: CallimacusErrorMessage) => void;
+type WarningCallback = (warning: RoundWarning) => void;
 declare class CallimacusService {
     private socket?;
     private readonly serverResponseListeners;
     private readonly connectionStatusListeners;
     private readonly errorListeners;
+    private readonly warningListeners;
+    private readonly reportedWarnings;
     private uiObserver?;
     private uiObserverConfig;
     private handshakeRetryAttempts;
@@ -3989,6 +4097,11 @@ declare class CallimacusService {
      @param error - The error to notify listeners about
      */
     private notifyErrorListeners;
+    /**
+     Hands each new round warning to the warning listeners. With none registered, the SDK's logger
+     reports it, so a developer who turned the logger on still sees it.
+     */
+    private notifyWarningListeners;
     /**
      Retrieves the user's current geolocation coordinates.
 
@@ -4076,86 +4189,18 @@ declare class CallimacusService {
      @returns Unsubscribe function to remove the listener
      */
     onError(callback: ErrorCallback): () => void;
+    /**
+     Registers a callback for blocks a round did not send because one of their contents failed. Each
+     warning is delivered once, however often the round is re-sent. For the site's developer: log it or
+     forward it to monitoring; never render it. Registering one replaces the default logger warning.
+
+     @param callback - Function to call with each new warning
+     @returns Unsubscribe function to remove the listener
+     */
+    onWarning(callback: WarningCallback): () => void;
 }
 declare const callimacusService: CallimacusService;
 
-type CreateRoundPayload = InteractionPayloadMap[UserInteractionType.CREATE_ROUND];
-/**
-The landing value blocks and conditions read (`{{input.value}}`); the server caps it at 200 characters.
-*/
-declare const LANDING_VALUE_MAX_LENGTH = 200;
-/**
- The `create-round` payload that opens the landing page: a round with no message,
- composed from the tenant's landing configuration.
- @param value - Optional landing value — a page slug, a campaign, whatever the
- tenant's landing blocks were written to read.
- @param options - The story to continue and the language to compose in.
- */
-declare function landingRound(value?: string, options?: RoundOptions): CreateRoundPayload;
-/**
- The `create-round` payload for a declared interaction. Blocks answer it by
- naming the id in their condition; the block key it carries lets a block whose
- `patchOn` names the interaction be patched in place.
- */
-declare function interactionRound<I extends InteractionId>(id: I, options?: InteractionOptions<I>): CreateRoundPayload;
-/**
- The receptor labels the classifier assigned a round — the per-message
- classification, not the session intent. Reads `receptors`, falling back to the
- `intent` name servers used before the rename (kept one release as an alias).
- */
-declare function receptorsOf(chapter: Pick<Chapter, 'receptors' | 'intent'>): string[];
-/**
- A block's key — the identity everything attributes, pins and links by. `type`
- is a render hint two blocks may share. Only custom blocks carry one, and only
- on rounds recorded since keys travel on the wire.
- */
-declare function blockKeyOf(block: Block): string | undefined;
-/**
-The block the flow emits when adding to cart needs the visitor to pick a size.
-*/
-declare const ADD_TO_CART_RESULT_BLOCK = "custom:addToCartResult";
-/**
-How an add-to-cart request resolved; the flow attaches it to every block of the round as `data.addToCart`.
-*/
-type AddToCartResult = {
-    status: 'resolved';
-    variantId: string;
-    productName: string;
-    size: string;
-} | {
-    status: 'size_selection_needed';
-    productSku: string;
-    productName: string;
-    availableSizes: Array<{
-        size: string;
-        variantId: string;
-        orderable: boolean;
-    }>;
-} | {
-    status: 'error';
-};
-/**
-The add-to-cart result a block carries, when the round resolved one.
-
-Every field is checked, not only the status: the block's data is whatever the round
-put there, and a half-written result would otherwise reach a caller as a complete one
-— with `undefined` where the type promises a string.
-*/
-declare function addToCartResultOf(block: {
-    data?: unknown;
-}): AddToCartResult | undefined;
-/**
- The round with a `block-patch` applied, as the server stored it: `values`,
- `inputs` and `textRuns` merged into the animation at `contentId` (a dotted path
- into `block.data`), everything else left as it was. Returns `chapter` itself
- when the patch is for another round, a block it does not show, or a place that
- holds no animation, so a caller can tell nothing changed.
-
- `fire` is not written: triggers play once, when the patch arrives, and
- keeping them would replay them on every render and reload.
- */
-declare function applyBlockPatch(chapter: Chapter, patch: BlockPatch): Chapter;
-
 type ContractClient = Client;
 /**
 What a contract call rejects with under `{throwOnError: true}`.
@@ -4364,6 +4409,63 @@ declare function deliverResultOf(block: {
     data?: unknown;
 }): DeliverResult | undefined;
 
+/**
+What one of the chat's adds to the bag came to, for the chat to show: `added`, `refused` by the store
+(its own words in `message`: sold out, not available here), `unavailable` (the cart is off on this
+site, or the store refuses it), or `failed` (the store did not answer).
+*/
+type CartNotice = {
+    /**
+    The round that asked for it.
+    */
+    id: string;
+    outcome: 'added' | 'refused' | 'unavailable' | 'failed';
+    message: string;
+    item: CartCommand['item'];
+    quantity: number;
+};
+/**
+A cart's answer to one add, as the runner reads it: no `error` is an add, `warnings` say what the
+store did other than asked.
+*/
+type CartAddResult = {
+    error?: {
+        code: string;
+        message: string;
+    };
+    warnings?: ReadonlyArray<{
+        message: string;
+    }>;
+};
+/**
+The add a runtime runs a command with, in the cart it runs: the runner gives it the clamped quantity.
+*/
+type CartAdd = (quantity: number) => Promise<CartAddResult>;
+/**
+Where the runner keeps the rounds it ran: `localStorage` on a site, `sessionStorage` in the theme embed.
+*/
+type CartCommandStorage = Pick<Storage, 'getItem' | 'setItem'>;
+/**
+What running a command came to: the notice to show, and the error code a runtime may report.
+*/
+type CartCommandOutcome = {
+    notice: CartNotice;
+    code?: string;
+};
+/**
+The notice for one add of `item`, from the cart's answer: the chat's command and a tap on the
+option choice both show it.
+*/
+declare function cartNoticeOf(added: Pick<CartNotice, 'id' | 'item' | 'quantity'>, result: CartAddResult): CartNotice;
+/**
+The runner every runtime runs the chat's adds to the bag (`cart-command`) through: at most once per
+round, so a redelivered command or a reload adds nothing, and at most 10 of it. The runtime picks the
+cart for the command and checks its variant id: no add for a command means it is not run, and its
+round stays open. Where the storage is refused, the page remembers the rounds it ran. Never rejects
+for its own reasons; resolves nothing when the command was not run.
+*/
+declare function createCartCommandRunner(storage: () => CartCommandStorage): (command: CartCommand, add: CartAdd | undefined) => Promise<CartCommandOutcome | undefined>;
+
 /**
 The Shopify settings a site passes at init (`shopify` in the init config).
 */
@@ -4875,5 +4977,5 @@ declare function transformImageUrl(cdnUrl: string, edits: ImageEdits): string;
  */
 declare function randomUuid(): string;
 
-export { ACTION_TYPES, ADD_TO_CART_RESULT_BLOCK, CallimacusApi, CallimacusEvent, CallimacusService, ChapterStatus, ClientEvents, DELIVER_RESULT_BLOCK, GalleryMode, LANDING_VALUE_MAX_LENGTH, MAX_HANDSHAKE_RETRIES, SLInputEventType, STOREFRONT_API_VERSION, ServerEvents, ThamyrHttpError, ThamyrResponseType, UserInteractionType, actionOf, addToCartResultOf, applyBlockPatch, blockKeyOf, callimacusService, cartSettingsFor, classifyConnectError, createContractClient, createPageStorage, createShopifyCart, createWooCommerceCart, deliverResultOf, extractTtsAudio, fieldsOf, interactionRound, isCustomBlock, isMasterProduct, isSetProduct, isVariantGid, landingRound, leaseLock, logger, mergeShopifySettings, parseConnectRejection, parseMapPath, randomUuid, readShopifySettings, receptorsOf, resolveMapPage, shouldRetryHandshake, transformImageUrl, webLocks };
-export type { Action, ActionType, AddToCartResult, BCProduct, Basket, Block, BlockPatch, BoundingBox, CallimacusErrorMessage, CartCommand, CartLock, CartStorage, Chapter, ClientInfo, ConnectRejection, ConnectionStatusCallback, ContractClient, CustomBlock, DeliverResult, DocumentIndexEntry, ErrorCallback, ErrorMessage, Gallery, GenericProduct, HomePage, Image, ImageEdits, ImageFormatEdit, ImageResizeEdit, InteractionContext, InteractionId, InteractionOptions, InteractionPayload, InteractionPayloadMap, LegacyBlock, LocalizedEPArtwork, LocalizedEPChapter, LogLevel, LoggerConfig, MapPage, MapPath, MasterProduct, MasterProductWithVariationGroup, OptionItem, ProductItem, ProductMatch, RecommendationsResponse, RiveManifest, RoundOptions, SLDocument, SLDocumentSection, SLInputEvent, ServerResponseCallback, SetProduct, ShopifyCart, ShopifyCartClient, ShopifyCartClientOptions, ShopifyCartError, ShopifyCartErrorCode, ShopifyCartLine, ShopifyCartResult, ShopifyCartSettings, ShopifyCartWarning, ShopifyConfig, ShopifyMoney, ShopifySettings, ShopifyStorefront, ShopifyUserError, SkesisItem, SkesisItemPage, SkesisRelatedResponse, SkesisSimilarResponse, Story, SuggestPayload, Suggestions, ThamyrInteractionMap, ThamyrResponse, Topic, TopicContentsPage, TopicSummary, TtsAudio, UiElement, UiObserverConfig, UiSnapshot, UserInteraction, Variant, VariationAttribute, VariationGroup, Video, WhisperPayload, WooCommerceCart, WooCommerceCartClient, WooCommerceCartClientOptions, WooCommerceCartError, WooCommerceCartErrorCode, WooCommerceCartItem, WooCommerceCartResult, WooCommerceMoney, WooCommerceStart };
+export { ACTION_TYPES, ADD_TO_CART_RESULT_BLOCK, CallimacusApi, CallimacusEvent, CallimacusService, ChapterStatus, ClientEvents, DELIVER_RESULT_BLOCK, GalleryMode, LANDING_VALUE_MAX_LENGTH, MAX_HANDSHAKE_RETRIES, SLInputEventType, STOREFRONT_API_VERSION, ServerEvents, ThamyrHttpError, ThamyrResponseType, UserInteractionType, actionOf, addToCartResultOf, applyBlockPatch, blockKeyOf, callimacusService, cartNoticeOf, cartSettingsFor, classifyConnectError, createCartCommandRunner, createContractClient, createPageStorage, createShopifyCart, createWooCommerceCart, deliverResultOf, extractTtsAudio, fieldsOf, interactionRound, isCustomBlock, isMasterProduct, isSetProduct, isVariantGid, landingRound, leaseLock, logger, mergeShopifySettings, newRoundWarnings, parseConnectRejection, parseMapPath, randomUuid, readShopifySettings, receptorsOf, resolveMapPage, shouldRetryHandshake, transformImageUrl, webLocks };
+export type { Action, ActionType, AddToCartResult, BCProduct, Basket, Block, BlockPatch, BoundingBox, CallimacusErrorMessage, CartAdd, CartAddResult, CartCommand, CartCommandOutcome, CartCommandStorage, CartLock, CartNotice, CartStorage, Chapter, ClientInfo, ConnectRejection, ConnectionStatusCallback, ContractClient, CustomBlock, DeliverResult, DocumentIndexEntry, ErrorCallback, ErrorMessage, Gallery, GenericProduct, HomePage, Image, ImageEdits, ImageFormatEdit, ImageResizeEdit, InteractionContext, InteractionId, InteractionOptions, InteractionPayload, InteractionPayloadMap, LegacyBlock, LocalizedEPArtwork, LocalizedEPChapter, LogLevel, LoggerConfig, MapPage, MapPath, MasterProduct, MasterProductWithVariationGroup, OptionItem, ProductItem, ProductMatch, RecommendationsResponse, RiveManifest, RoundOptions, RoundWarning, SLDocument, SLDocumentSection, SLInputEvent, ServerResponseCallback, SetProduct, ShopifyCart, ShopifyCartClient, ShopifyCartClientOptions, ShopifyCartError, ShopifyCartErrorCode, ShopifyCartLine, ShopifyCartResult, ShopifyCartSettings, ShopifyCartWarning, ShopifyConfig, ShopifyMoney, ShopifySettings, ShopifyStorefront, ShopifyUserError, SkesisItem, SkesisItemPage, SkesisRelatedResponse, SkesisSimilarResponse, Story, SuggestPayload, Suggestions, ThamyrInteractionMap, ThamyrResponse, Topic, TopicContentsPage, TopicSummary, TtsAudio, UiElement, UiObserverConfig, UiSnapshot, UserInteraction, Variant, VariationAttribute, VariationGroup, Video, WarningCallback, WhisperPayload, WooCommerceCart, WooCommerceCartClient, WooCommerceCartClientOptions, WooCommerceCartError, WooCommerceCartErrorCode, WooCommerceCartItem, WooCommerceCartResult, WooCommerceMoney, WooCommerceStart };

package/dist/types/index.native.d.ts

@@ -918,6 +918,23 @@ type ChapterOutput = {
          */
         type: string;
     }>;
+    /**
+     * Blocks this round did not send because one of their contents failed. For the site's developer: log them, never render them. The reason stays server-side; `callimacus thamyr probe` shows it.
+     */
+    warnings?: Array<{
+        /**
+         * The key of the block that was not sent.
+         */
+        block: string;
+        /**
+         * The id of its content that failed.
+         */
+        content: string;
+        /**
+         * `shortfall`: the content found fewer items than its `minItems` and its `onShort` is `fail`. `error`: anything else threw.
+         */
+        cause: 'shortfall' | 'error';
+    }>;
     status: ChapterStatus$1;
 };
 type CreateRoundContextOutput = {
@@ -3933,6 +3950,94 @@ type TtsAudio = {
  */
 declare function extractTtsAudio(data: unknown): TtsAudio | undefined;
 
+type CreateRoundPayload = InteractionPayloadMap[UserInteractionType.CREATE_ROUND];
+/**
+The landing value blocks and conditions read (`{{input.value}}`); the server caps it at 200 characters.
+*/
+declare const LANDING_VALUE_MAX_LENGTH = 200;
+/**
+ The `create-round` payload that opens the landing page: a round with no message,
+ composed from the tenant's landing configuration.
+ @param value - Optional landing value — a page slug, a campaign, whatever the
+ tenant's landing blocks were written to read.
+ @param options - The story to continue and the language to compose in.
+ */
+declare function landingRound(value?: string, options?: RoundOptions): CreateRoundPayload;
+/**
+ The `create-round` payload for a declared interaction. Blocks answer it by
+ naming the id in their condition; the block key it carries lets a block whose
+ `patchOn` names the interaction be patched in place.
+ */
+declare function interactionRound<I extends InteractionId>(id: I, options?: InteractionOptions<I>): CreateRoundPayload;
+/**
+ The receptor labels the classifier assigned a round — the per-message
+ classification, not the session intent. Reads `receptors`, falling back to the
+ `intent` name servers used before the rename (kept one release as an alias).
+ */
+declare function receptorsOf(chapter: Pick<Chapter, 'receptors' | 'intent'>): string[];
+/**
+ A block's key — the identity everything attributes, pins and links by. `type`
+ is a render hint two blocks may share. Only custom blocks carry one, and only
+ on rounds recorded since keys travel on the wire.
+ */
+declare function blockKeyOf(block: Block): string | undefined;
+/**
+The block the flow emits when adding to cart needs the visitor to pick a size.
+*/
+declare const ADD_TO_CART_RESULT_BLOCK = "custom:addToCartResult";
+/**
+How an add-to-cart request resolved; the flow attaches it to every block of the round as `data.addToCart`.
+*/
+type AddToCartResult = {
+    status: 'resolved';
+    variantId: string;
+    productName: string;
+    size: string;
+} | {
+    status: 'size_selection_needed';
+    productSku: string;
+    productName: string;
+    availableSizes: Array<{
+        size: string;
+        variantId: string;
+        orderable: boolean;
+    }>;
+} | {
+    status: 'error';
+};
+/**
+The add-to-cart result a block carries, when the round resolved one.
+
+Every field is checked, not only the status: the block's data is whatever the round
+put there, and a half-written result would otherwise reach a caller as a complete one
+— with `undefined` where the type promises a string.
+*/
+declare function addToCartResultOf(block: {
+    data?: unknown;
+}): AddToCartResult | undefined;
+/**
+ The round with a `block-patch` applied, as the server stored it: `values`,
+ `inputs` and `textRuns` merged into the animation at `contentId` (a dotted path
+ into `block.data`), everything else left as it was. Returns `chapter` itself
+ when the patch is for another round, a block it does not show, or a place that
+ holds no animation, so a caller can tell nothing changed.
+
+ `fire` is not written: triggers play once, when the patch arrives, and
+ keeping them would replay them on every render and reload.
+ */
+declare function applyBlockPatch(chapter: Chapter, patch: BlockPatch): Chapter;
+/**
+ A block the round did not send because one of its contents failed: its key, the content's id, and
+ `shortfall` (fewer items than `minItems` under `onShort: "fail"`) or `error`. The reason stays
+ server-side; `callimacus thamyr probe` shows it.
+ */
+type RoundWarning = NonNullable<Chapter['warnings']>[number];
+/**
+ The round's warnings not reported yet. A round is re-sent on every streamed chunk, so each warning
+ arrives many times; `reported` remembers which were already handed on.
+ */
+declare function newRoundWarnings(chapter: Pick<Chapter, 'id' | 'warnings'>, reported: Set<string>): RoundWarning[];
+
 /**
  The error surface hosts subscribe to via `onError`: server `error`-channel
  messages plus terminal connection refusals. `reason` is present only on
@@ -3949,11 +4054,14 @@ type CallimacusErrorMessage = ErrorMessage;
 type ServerResponseCallback<T = ThamyrResponse> = (response: T) => void;
 type ConnectionStatusCallback = (isConnected: boolean) => void;
 type ErrorCallback = (error: CallimacusErrorMessage) => void;
+type WarningCallback = (warning: RoundWarning) => void;
 declare class CallimacusService {
     private socket?;
     private readonly serverResponseListeners;
     private readonly connectionStatusListeners;
     private readonly errorListeners;
+    private readonly warningListeners;
+    private readonly reportedWarnings;
     private uiObserver?;
     private uiObserverConfig;
     private handshakeRetryAttempts;
@@ -3987,6 +4095,11 @@ declare class CallimacusService {
      @param error - The error to notify listeners about
      */
     private notifyErrorListeners;
+    /**
+     Hands each new round warning to the warning listeners. With none registered, the SDK's logger
+     reports it, so a developer who turned the logger on still sees it.
+     */
+    private notifyWarningListeners;
     /**
      Retrieves the user's current geolocation coordinates.
 
@@ -4074,86 +4187,18 @@ declare class CallimacusService {
      @returns Unsubscribe function to remove the listener
      */
     onError(callback: ErrorCallback): () => void;
+    /**
+     Registers a callback for blocks a round did not send because one of their contents failed. Each
+     warning is delivered once, however often the round is re-sent. For the site's developer: log it or
+     forward it to monitoring; never render it. Registering one replaces the default logger warning.
+
+     @param callback - Function to call with each new warning
+     @returns Unsubscribe function to remove the listener
+     */
+    onWarning(callback: WarningCallback): () => void;
 }
 declare const callimacusService: CallimacusService;
 
-type CreateRoundPayload = InteractionPayloadMap[UserInteractionType.CREATE_ROUND];
-/**
-The landing value blocks and conditions read (`{{input.value}}`); the server caps it at 200 characters.
-*/
-declare const LANDING_VALUE_MAX_LENGTH = 200;
-/**
- The `create-round` payload that opens the landing page: a round with no message,
- composed from the tenant's landing configuration.
- @param value - Optional landing value — a page slug, a campaign, whatever the
- tenant's landing blocks were written to read.
- @param options - The story to continue and the language to compose in.
- */
-declare function landingRound(value?: string, options?: RoundOptions): CreateRoundPayload;
-/**
- The `create-round` payload for a declared interaction. Blocks answer it by
- naming the id in their condition; the block key it carries lets a block whose
- `patchOn` names the interaction be patched in place.
- */
-declare function interactionRound<I extends InteractionId>(id: I, options?: InteractionOptions<I>): CreateRoundPayload;
-/**
- The receptor labels the classifier assigned a round — the per-message
- classification, not the session intent. Reads `receptors`, falling back to the
- `intent` name servers used before the rename (kept one release as an alias).
- */
-declare function receptorsOf(chapter: Pick<Chapter, 'receptors' | 'intent'>): string[];
-/**
- A block's key — the identity everything attributes, pins and links by. `type`
- is a render hint two blocks may share. Only custom blocks carry one, and only
- on rounds recorded since keys travel on the wire.
- */
-declare function blockKeyOf(block: Block): string | undefined;
-/**
-The block the flow emits when adding to cart needs the visitor to pick a size.
-*/
-declare const ADD_TO_CART_RESULT_BLOCK = "custom:addToCartResult";
-/**
-How an add-to-cart request resolved; the flow attaches it to every block of the round as `data.addToCart`.
-*/
-type AddToCartResult = {
-    status: 'resolved';
-    variantId: string;
-    productName: string;
-    size: string;
-} | {
-    status: 'size_selection_needed';
-    productSku: string;
-    productName: string;
-    availableSizes: Array<{
-        size: string;
-        variantId: string;
-        orderable: boolean;
-    }>;
-} | {
-    status: 'error';
-};
-/**
-The add-to-cart result a block carries, when the round resolved one.
-
-Every field is checked, not only the status: the block's data is whatever the round
-put there, and a half-written result would otherwise reach a caller as a complete one
-— with `undefined` where the type promises a string.
-*/
-declare function addToCartResultOf(block: {
-    data?: unknown;
-}): AddToCartResult | undefined;
-/**
- The round with a `block-patch` applied, as the server stored it: `values`,
- `inputs` and `textRuns` merged into the animation at `contentId` (a dotted path
- into `block.data`), everything else left as it was. Returns `chapter` itself
- when the patch is for another round, a block it does not show, or a place that
- holds no animation, so a caller can tell nothing changed.
-
- `fire` is not written: triggers play once, when the patch arrives, and
- keeping them would replay them on every render and reload.
- */
-declare function applyBlockPatch(chapter: Chapter, patch: BlockPatch): Chapter;
-
 type ContractClient = Client;
 /**
 What a contract call rejects with under `{throwOnError: true}`.
@@ -4362,6 +4407,63 @@ declare function deliverResultOf(block: {
     data?: unknown;
 }): DeliverResult | undefined;
 
+/**
+What one of the chat's adds to the bag came to, for the chat to show: `added`, `refused` by the store
+(its own words in `message`: sold out, not available here), `unavailable` (the cart is off on this
+site, or the store refuses it), or `failed` (the store did not answer).
+*/
+type CartNotice = {
+    /**
+    The round that asked for it.
+    */
+    id: string;
+    outcome: 'added' | 'refused' | 'unavailable' | 'failed';
+    message: string;
+    item: CartCommand['item'];
+    quantity: number;
+};
+/**
+A cart's answer to one add, as the runner reads it: no `error` is an add, `warnings` say what the
+store did other than asked.
+*/
+type CartAddResult = {
+    error?: {
+        code: string;
+        message: string;
+    };
+    warnings?: ReadonlyArray<{
+        message: string;
+    }>;
+};
+/**
+The add a runtime runs a command with, in the cart it runs: the runner gives it the clamped quantity.
+*/
+type CartAdd = (quantity: number) => Promise<CartAddResult>;
+/**
+Where the runner keeps the rounds it ran: `localStorage` on a site, `sessionStorage` in the theme embed.
+*/
+type CartCommandStorage = Pick<Storage, 'getItem' | 'setItem'>;
+/**
+What running a command came to: the notice to show, and the error code a runtime may report.
+*/
+type CartCommandOutcome = {
+    notice: CartNotice;
+    code?: string;
+};
+/**
+The notice for one add of `item`, from the cart's answer: the chat's command and a tap on the
+option choice both show it.
+*/
+declare function cartNoticeOf(added: Pick<CartNotice, 'id' | 'item' | 'quantity'>, result: CartAddResult): CartNotice;
+/**
+The runner every runtime runs the chat's adds to the bag (`cart-command`) through: at most once per
+round, so a redelivered command or a reload adds nothing, and at most 10 of it. The runtime picks the
+cart for the command and checks its variant id: no add for a command means it is not run, and its
+round stays open. Where the storage is refused, the page remembers the rounds it ran. Never rejects
+for its own reasons; resolves nothing when the command was not run.
+*/
+declare function createCartCommandRunner(storage: () => CartCommandStorage): (command: CartCommand, add: CartAdd | undefined) => Promise<CartCommandOutcome | undefined>;
+
 /**
 The Shopify settings a site passes at init (`shopify` in the init config).
 */
@@ -4935,5 +5037,5 @@ declare function ensureIntentSessionId(): void;
 declare function clearIntentSessionId(): void;
 declare function setIntentSessionMaxAge(_seconds: number): void;
 
-export { ACTION_TYPES, ADD_TO_CART_RESULT_BLOCK, CallimacusApi, CallimacusEvent, CallimacusService, ChapterStatus, ClientEvents, DELIVER_RESULT_BLOCK, GalleryMode, LANDING_VALUE_MAX_LENGTH, MAX_HANDSHAKE_RETRIES, SLInputEventType, STOREFRONT_API_VERSION, ServerEvents, ThamyrHttpError, ThamyrResponseType, UserInteractionType, actionOf, addToCartResultOf, applyBlockPatch, blockKeyOf, callimacusService, cartSettingsFor, classifyConnectError, clearIntentSessionId, createContractClient, createPageStorage, createShopifyCart, createWooCommerceCart, deliverResultOf, ensureIntentSessionId, extractTtsAudio, fieldsOf, getIntentSessionId, initIntent, interactionRound, isCustomBlock, isMasterProduct, isSetProduct, isVariantGid, landingRound, leaseLock, logger, mergeShopifySettings, parseConnectRejection, parseMapPath, randomUuid, readShopifySettings, receptorsOf, resolveMapPage, setConsent, setDebug, setDebugPanel, setGeo, setIntentSessionMaxAge, shouldRetryHandshake, transformImageUrl, webLocks };
-export type { Action, ActionType, AddToCartResult, BCProduct, Basket, Block, BlockPatch, BoundingBox, CallimacusErrorMessage, CartCommand, CartLock, CartStorage, Chapter, ClientInfo, ConnectRejection, ConnectionStatusCallback, ContractClient, CustomBlock, DeliverResult, DocumentIndexEntry, ErrorCallback, ErrorMessage, Gallery, GenericProduct, HomePage, Image, ImageEdits, ImageFormatEdit, ImageResizeEdit, InitOptions, InteractionContext, InteractionId, InteractionOptions, InteractionPayload, InteractionPayloadMap, LegacyBlock, LocalizedEPArtwork, LocalizedEPChapter, LogLevel, LoggerConfig, MapPage, MapPath, MasterProduct, MasterProductWithVariationGroup, OptionItem, ProductItem, ProductMatch, RecommendationsResponse, RiveManifest, RoundOptions, SLDocument, SLDocumentSection, SLInputEvent, ServerResponseCallback, SetProduct, ShopifyCart, ShopifyCartClient, ShopifyCartClientOptions, ShopifyCartError, ShopifyCartErrorCode, ShopifyCartLine, ShopifyCartResult, ShopifyCartSettings, ShopifyCartWarning, ShopifyConfig, ShopifyMoney, ShopifySettings, ShopifyStorefront, ShopifyUserError, SkesisItem, SkesisItemPage, SkesisRelatedResponse, SkesisSimilarResponse, Story, SuggestPayload, Suggestions, ThamyrInteractionMap, ThamyrResponse, Topic, TopicContentsPage, TopicSummary, TtsAudio, UiElement, UiObserverConfig, UiSnapshot, UserInteraction, Variant, VariationAttribute, VariationGroup, Video, WhisperPayload, WooCommerceCart, WooCommerceCartClient, WooCommerceCartClientOptions, WooCommerceCartError, WooCommerceCartErrorCode, WooCommerceCartItem, WooCommerceCartResult, WooCommerceMoney, WooCommerceStart };
+export { ACTION_TYPES, ADD_TO_CART_RESULT_BLOCK, CallimacusApi, CallimacusEvent, CallimacusService, ChapterStatus, ClientEvents, DELIVER_RESULT_BLOCK, GalleryMode, LANDING_VALUE_MAX_LENGTH, MAX_HANDSHAKE_RETRIES, SLInputEventType, STOREFRONT_API_VERSION, ServerEvents, ThamyrHttpError, ThamyrResponseType, UserInteractionType, actionOf, addToCartResultOf, applyBlockPatch, blockKeyOf, callimacusService, cartNoticeOf, cartSettingsFor, classifyConnectError, clearIntentSessionId, createCartCommandRunner, createContractClient, createPageStorage, createShopifyCart, createWooCommerceCart, deliverResultOf, ensureIntentSessionId, extractTtsAudio, fieldsOf, getIntentSessionId, initIntent, interactionRound, isCustomBlock, isMasterProduct, isSetProduct, isVariantGid, landingRound, leaseLock, logger, mergeShopifySettings, newRoundWarnings, parseConnectRejection, parseMapPath, randomUuid, readShopifySettings, receptorsOf, resolveMapPage, setConsent, setDebug, setDebugPanel, setGeo, setIntentSessionMaxAge, shouldRetryHandshake, transformImageUrl, webLocks };
+export type { Action, ActionType, AddToCartResult, BCProduct, Basket, Block, BlockPatch, BoundingBox, CallimacusErrorMessage, CartAdd, CartAddResult, CartCommand, CartCommandOutcome, CartCommandStorage, CartLock, CartNotice, CartStorage, Chapter, ClientInfo, ConnectRejection, ConnectionStatusCallback, ContractClient, CustomBlock, DeliverResult, DocumentIndexEntry, ErrorCallback, ErrorMessage, Gallery, GenericProduct, HomePage, Image, ImageEdits, ImageFormatEdit, ImageResizeEdit, InitOptions, InteractionContext, InteractionId, InteractionOptions, InteractionPayload, InteractionPayloadMap, LegacyBlock, LocalizedEPArtwork, LocalizedEPChapter, LogLevel, LoggerConfig, MapPage, MapPath, MasterProduct, MasterProductWithVariationGroup, OptionItem, ProductItem, ProductMatch, RecommendationsResponse, RiveManifest, RoundOptions, RoundWarning, SLDocument, SLDocumentSection, SLInputEvent, ServerResponseCallback, SetProduct, ShopifyCart, ShopifyCartClient, ShopifyCartClientOptions, ShopifyCartError, ShopifyCartErrorCode, ShopifyCartLine, ShopifyCartResult, ShopifyCartSettings, ShopifyCartWarning, ShopifyConfig, ShopifyMoney, ShopifySettings, ShopifyStorefront, ShopifyUserError, SkesisItem, SkesisItemPage, SkesisRelatedResponse, SkesisSimilarResponse, Story, SuggestPayload, Suggestions, ThamyrInteractionMap, ThamyrResponse, Topic, TopicContentsPage, TopicSummary, TtsAudio, UiElement, UiObserverConfig, UiSnapshot, UserInteraction, Variant, VariationAttribute, VariationGroup, Video, WarningCallback, WhisperPayload, WooCommerceCart, WooCommerceCartClient, WooCommerceCartClientOptions, WooCommerceCartError, WooCommerceCartErrorCode, WooCommerceCartItem, WooCommerceCartResult, WooCommerceMoney, WooCommerceStart };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callimacus/thamyr-core",
-  "version": "4.18.0",
+  "version": "4.20.0",
   "private": false,
   "description": "Core package for Thamyr",
   "license": "SEE LICENSE IN LICENSE.md",