@callimacus/thamyr-core 4.3.4 → 4.4.0

package/dist/types/index.d.ts

@@ -403,6 +403,15 @@ type TopicSummary = {
     name: string;
     slug: string;
 };
+type PinaxForbidden = {
+    code: 'FORBIDDEN';
+    message: string;
+    retryable: false;
+    /**
+     * The scopes any one of which would have been accepted; empty when any principal would do
+     */
+    required: Array<string>;
+};
 type PublicError = {
     error: string;
 };
@@ -473,6 +482,64 @@ type ProductMatch = {
     };
     product: BcProductOutput;
 };
+type RiveManifestOutput = {
+    /**
+     * In file order; the first is the one the runtime opens by default.
+     */
+    artboards: Array<{
+        name: string;
+        animations: Array<string>;
+        stateMachines: Array<{
+            name: string;
+            inputs: Array<{
+                name: string;
+                type: 'boolean' | 'number' | 'trigger';
+            }>;
+        }>;
+        /**
+         * The view model the artboard is bound to in the editor.
+         */
+        viewModel?: string;
+    }>;
+    viewModels: Array<{
+        name: string;
+        instances: Array<string>;
+        properties: Array<{
+            name: string;
+            /**
+             * The runtime data type: string, number, boolean, color, enumType, trigger, and the nested kinds (list, viewModel, image, artboard) that no model sets.
+             */
+            type: string;
+            /**
+             * The options of an enumType property.
+             */
+            values?: Array<string>;
+        }>;
+    }>;
+    /**
+     * Named runs only: an unnamed run cannot be addressed.
+     */
+    textRuns: Array<{
+        artboard: string;
+        name: string;
+        /**
+         * The text the file ships with.
+         */
+        text: string;
+    }>;
+    events: Array<{
+        artboard: string;
+        name: string;
+        /**
+         * Set on an OpenUrl event.
+         */
+        url?: string;
+        properties: Array<{
+            name: string;
+            type: 'number' | 'boolean' | 'string';
+        }>;
+    }>;
+};
 type BcProductOutput = SetProductOutput | MasterProductWithVariationGroupOutput;
 type SetProductOutput = {
     type: {
@@ -660,11 +727,52 @@ type VariationAttributeOutput = {
         value: string;
     }>;
 };
+type BlockPatchOutput = {
+    storyId: string;
+    chapterId: string;
+    /**
+     * The block already on screen that changes.
+     */
+    blockId: string;
+    /**
+     * Where in `block.data` the animation sits: the rive content's `into`, else its id.
+     */
+    contentId: string;
+    /**
+     * View model properties to set, merged into `values`.
+     */
+    values: {
+        [key: string]: string | number | boolean;
+    };
+    /**
+     * State machine inputs to set, merged into `inputs`.
+     */
+    inputs: {
+        [key: string]: number | boolean;
+    };
+    /**
+     * Text runs to set, merged into `textRuns`.
+     */
+    textRuns: {
+        [key: string]: string;
+    };
+    /**
+     * Triggers to fire once, in order: `input:<name>` or `vm:<name>`.
+     */
+    fire: Array<string>;
+};
 type BlockOutput = LegacyBlockOutput | CustomBlockOutput;
 type ChapterOutput = {
     id: string;
     deleted: boolean;
     language?: string;
+    /**
+     * The language the round retrieves in: one the project publishes, which differs from `language` (the one it speaks) when the visitor writes in a language the project does not publish.
+     */
+    contentLanguage?: string;
+    /**
+     * The receptor labels the classifier assigned this round (the per-message classification — not the session intent).
+     */
     receptors?: Array<string>;
     /**
      * Deprecated alias of `receptors`.
@@ -716,9 +824,13 @@ type CustomBlockOutput = {
     priority?: number;
     metaJson?: unknown;
     /**
-     * Custom block type, always prefixed `custom:`.
+     * Custom block type, always prefixed `custom:`. A render hint — not unique across blocks.
      */
     type: `custom:${string}`;
+    /**
+     * The block's key — the identity to attribute, pin and link by. Absent only on rounds recorded before keys travelled.
+     */
+    key?: string;
     name?: string;
     data: unknown;
 };
@@ -923,6 +1035,13 @@ type SlDocumentSectionOutput = {
             [key: string]: unknown;
         };
     };
+} | {
+    id: string;
+    document: string;
+    type: 'rive';
+    content?: string;
+    url: string;
+    properties: RiveManifestOutput;
 } | {
     id: string;
     document: string;
@@ -1068,6 +1187,9 @@ type ThamyrResponse$1 = {
         storyId: string;
         success: boolean;
     };
+} | {
+    type: 'block-patch';
+    data: BlockPatchOutput;
 };
 type UserInteraction$1 = {
     type: 'get-story';
@@ -1108,6 +1230,13 @@ type UserInteraction$1 = {
         shareId: string;
         language?: string;
     };
+} | {
+    type: 'suggest';
+    payload: {
+        storyId?: string;
+        prefix?: string;
+        language?: string;
+    };
 };
 /**
  * Document representing a basket.
@@ -2394,6 +2523,10 @@ type ContentGetPageErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * Unknown page id (only `home` exists)
      */
@@ -2414,6 +2547,10 @@ type ContentListTopicsErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
 };
 type ContentListTopicsResponses = {
     /**
@@ -2430,6 +2567,10 @@ type ContentGetTopicContentsErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * No topic matches idOrSlug
      */
@@ -2450,6 +2591,10 @@ type ContentGetDocumentBySlugErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * No published document with this slug
      */
@@ -2470,6 +2615,10 @@ type ContentGetDocumentByGroupErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * No published document in this group
      */
@@ -2490,6 +2639,10 @@ type ContentGetDocumentByPathErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * Path did not resolve to a published document
      */
@@ -2510,6 +2663,10 @@ type StoriesGetSharedErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * Share not found
      */
@@ -2530,6 +2687,10 @@ type StoriesShareErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * Story not found
      */
@@ -2552,6 +2713,10 @@ type ProductsGetSimilarErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * Product not found or similar products unavailable
      */
@@ -2572,6 +2737,10 @@ type ProductsGetRecommendationsErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * Product not found or recommendations unavailable
      */
@@ -2593,9 +2762,9 @@ type WhisperGetLastErrors = {
      */
     401: unknown;
     /**
-     * Whisper preview is not enabled for this tenant
+     * The caller is not permitted to perform this operation; or Whisper preview is not enabled for this tenant
      */
-    403: PublicError;
+    403: PinaxForbidden | PublicError;
     /**
      * No whisper for this session yet
      */
@@ -2618,6 +2787,10 @@ type AnalyticsTrackEventErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
 };
 type AnalyticsTrackEventResponses = {
     /**
@@ -2634,6 +2807,10 @@ type CartGetCartErrors = {
      * No Salesforce shopper session could be resolved (typically a tenant without SFCC integration).
      */
     401: PublicError;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
 };
 type CartGetCartResponses = {
     /**
@@ -2650,6 +2827,10 @@ type CartAddItemToCartErrors = {
      * No Salesforce shopper session could be resolved (typically a tenant without SFCC integration).
      */
     401: PublicError;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
 };
 type CartAddItemToCartResponses = {
     /**
@@ -2666,6 +2847,10 @@ type CartRemoveItemFromCartErrors = {
      * No Salesforce shopper session could be resolved (typically a tenant without SFCC integration).
      */
     401: PublicError;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
 };
 type CartRemoveItemFromCartResponses = {
     /**
@@ -2682,6 +2867,10 @@ type CartUpdateProductQuantityErrors = {
      * No Salesforce shopper session could be resolved (typically a tenant without SFCC integration).
      */
     401: PublicError;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
 };
 type CartUpdateProductQuantityResponses = {
     /**
@@ -2698,6 +2887,10 @@ type SkesisSimilarErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * Skesis engine unavailable (rate cap, upstream failure, or not configured); retry later
      */
@@ -2721,6 +2914,10 @@ type SkesisRelatedErrors = {
      * Missing or invalid access token
      */
     401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
     /**
      * Skesis engine unavailable (rate cap, upstream failure, or not configured); retry later
      */
@@ -3008,6 +3205,15 @@ type Story = StoryOutput;
 Every `server-response` payload, exactly as the wire carries it.
 */
 type ThamyrResponse = ThamyrResponse$1;
+/**
+ A change to a block already on screen: an interaction the block's rive content
+ declares in `patchOn` re-set its animation in place. Apply it with `applyBlockPatch`.
+ */
+type BlockPatch = BlockPatchOutput;
+/**
+What a Rive animation exposes to be set: the `properties` of a `rive` document section.
+*/
+type RiveManifest = RiveManifestOutput;
 type Values<E> = E[keyof E];
 declare const ThamyrResponseType: {
     readonly ERROR: "error";
@@ -3016,6 +3222,7 @@ declare const ThamyrResponseType: {
     readonly STORY_RESET: "story-reset";
     readonly STORY_CREATED: "story-created";
     readonly STORY_SHARED: "story-shared";
+    readonly BLOCK_PATCH: "block-patch";
 };
 type ThamyrResponseType = Values<typeof ThamyrResponseType>;
 /**
@@ -3164,7 +3371,11 @@ declare enum UserInteractionType {
     /**
     Request to retrieve a story that has been shared
     */
-    GET_SHARED_STORY = "get-shared-story"
+    GET_SHARED_STORY = "get-shared-story",
+    /**
+    Prompt suggestions — a request/response exchange; send it through `suggest()`, not `sendUserInteraction`
+    */
+    SUGGEST = "suggest"
 }
 /**
 The contract payload for one interaction type.
@@ -3180,7 +3391,7 @@ type GetStoryPayload = PayloadOf<UserInteractionType.GET_STORY>;
  Payload for creating a new round. `context` is stripped and re-added by
  {@link InteractionPayloadMap}, which enriches every interaction with it.
  */
-type CreateRoundPayload = Omit<PayloadOf<UserInteractionType.CREATE_ROUND>, 'context'>;
+type CreateRoundPayload$1 = Omit<PayloadOf<UserInteractionType.CREATE_ROUND>, 'context'>;
 /**
 Payload for resetting a story to its initial state.
 */
@@ -3197,6 +3408,58 @@ type ShareStoryPayload = PayloadOf<UserInteractionType.SHARE_STORY>;
 Payload for retrieving a shared story.
 */
 type GetSharedStoryPayload = PayloadOf<UserInteractionType.GET_SHARED_STORY>;
+/**
+ Payload for prompt suggestions: the tenant's starter questions on an empty or
+ short prefix, autocomplete while the visitor types. Answered through the
+ socket acknowledgment, so it never appears among the story responses.
+ */
+type SuggestPayload = PayloadOf<UserInteractionType.SUGGEST>;
+/**
+What every round-creating helper accepts beside its own input: the story to continue, the language to compose in.
+*/
+type RoundOptions = Pick<CreateRoundPayload$1, 'storyId' | 'language'>;
+/**
+ The storefront's interaction registry — empty here, augmented by the storefront
+ with the ids the tenant declared in its configuration document (`interactions`).
+ Once augmented, `sendInteraction` accepts only those ids, each with its payload:
+
+ ```ts
+ declare module '@callimacus/thamyr-core' {
+   interface ThamyrInteractionMap {
+     'pick-size': {size: string};
+     reshuffle: undefined;
+   }
+ }
+ ```
+
+ Left empty, any id is accepted with an optional record payload.
+ */
+interface ThamyrInteractionMap {
+}
+type OpenRegistry = Record<string, Record<string, unknown> | undefined>;
+type InteractionRegistry = keyof ThamyrInteractionMap extends never ? OpenRegistry : ThamyrInteractionMap;
+/**
+An interaction id: any string until the registry is augmented, then exactly the declared ids.
+*/
+type InteractionId = Extract<keyof InteractionRegistry, string>;
+/**
+The payload the registry declares for an interaction.
+*/
+type InteractionPayload<I extends InteractionId> = InteractionRegistry[I];
+/**
+What an interaction round carries beside the interaction id.
+*/
+type InteractionOptions<I extends InteractionId = InteractionId> = RoundOptions & {
+    /**
+    The block the interaction belongs to (its key). A block whose `patchOn` names the interaction is patched in place when it is sent.
+    */
+    block?: string;
+    payload?: InteractionPayload<I>;
+    /**
+    A value the interaction carries (a chosen option, a list of them).
+    */
+    value?: string | string[];
+};
 type WithInteractionContext<T> = T & {
     context?: InteractionContext;
 };
@@ -3206,11 +3469,12 @@ type WithInteractionContext<T> = T & {
  */
 type InteractionPayloadMap = {
     [UserInteractionType.GET_STORY]: WithInteractionContext<GetStoryPayload>;
-    [UserInteractionType.CREATE_ROUND]: WithInteractionContext<CreateRoundPayload>;
+    [UserInteractionType.CREATE_ROUND]: WithInteractionContext<CreateRoundPayload$1>;
     [UserInteractionType.RESET_STORY]: WithInteractionContext<ResetStoryPayload>;
     [UserInteractionType.BACK_FROM_ROUND]: WithInteractionContext<BackFromRoundPayload>;
     [UserInteractionType.SHARE_STORY]: WithInteractionContext<ShareStoryPayload>;
     [UserInteractionType.GET_SHARED_STORY]: WithInteractionContext<GetSharedStoryPayload>;
+    [UserInteractionType.SUGGEST]: WithInteractionContext<SuggestPayload>;
 };
 /**
  Discriminated union type representing all possible user interactions.
@@ -3244,6 +3508,12 @@ declare enum CallimacusEvent {
     */
     ERROR = "error"
 }
+/**
+The acknowledgment of a `suggest` command. Empty when the tenant disabled suggestions or the request failed.
+*/
+type Suggestions = {
+    suggestions: string[];
+};
 
 /**
  Audio descriptor that a `tts` content item injects into a block's `data`.
@@ -3376,6 +3646,15 @@ declare class CallimacusService {
      @param payload - The properly typed payload for this interaction type
      */
     sendUserInteraction<T extends UserInteractionType>(type: T, payload: InteractionPayloadMap[T]): void;
+    /**
+     Prompt suggestions for the input box: the tenant's starter questions on an
+     empty or short prefix, autocomplete while the visitor types. A request/response
+     exchange through the socket acknowledgment — fail-open like the server: no
+     connection, a timeout or an error all resolve to no suggestions.
+     */
+    suggest(payload: SuggestPayload, options?: {
+        timeoutMs?: number;
+    }): Promise<Suggestions>;
     /**
      Collects information about the client's environment.
 
@@ -3414,6 +3693,83 @@ declare class CallimacusService {
 }
 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;
+
 /**
  Structured payload the server attaches to a refused handshake (SOL-1100):
  `code` is an HTTP-style status — 4xx is a deliberate refusal, 5xx means the
@@ -3573,5 +3929,5 @@ declare function createContractClient(config: {
     withCredentials?: boolean;
 }): ContractClient;
 
-export { CallimacusApi, CallimacusEvent, CallimacusService, ChapterStatus, ClientEvents, GalleryMode, MAX_HANDSHAKE_RETRIES, SLInputEventType, ServerEvents, ThamyrHttpError, ThamyrResponseType, UserInteractionType, callimacusService, classifyConnectError, createContractClient, extractTtsAudio, isCustomBlock, isMasterProduct, isSetProduct, logger, parseConnectRejection, randomUuid, shouldRetryHandshake, transformImageUrl };
-export type { BCProduct, Basket, Block, BoundingBox, CallimacusErrorMessage, Chapter, ClientInfo, ConnectRejection, ConnectionStatusCallback, ContractClient, CustomBlock, ErrorCallback, ErrorMessage, Gallery, GenericProduct, HomePage, Image, ImageEdits, ImageFormatEdit, ImageResizeEdit, InteractionContext, InteractionPayloadMap, LegacyBlock, LocalizedEPArtwork, LocalizedEPChapter, LogLevel, LoggerConfig, MasterProduct, MasterProductWithVariationGroup, OptionItem, ProductItem, ProductMatch, RecommendationsResponse, SLDocument, SLDocumentSection, SLInputEvent, ServerResponseCallback, SetProduct, SkesisItem, SkesisRelatedResponse, SkesisSimilarResponse, Story, ThamyrResponse, Topic, TopicContentsPage, TopicSummary, TtsAudio, UiElement, UiObserverConfig, UiSnapshot, UserInteraction, Variant, VariationAttribute, VariationGroup, Video, WhisperPayload };
+export { ADD_TO_CART_RESULT_BLOCK, CallimacusApi, CallimacusEvent, CallimacusService, ChapterStatus, ClientEvents, GalleryMode, LANDING_VALUE_MAX_LENGTH, MAX_HANDSHAKE_RETRIES, SLInputEventType, ServerEvents, ThamyrHttpError, ThamyrResponseType, UserInteractionType, addToCartResultOf, applyBlockPatch, blockKeyOf, callimacusService, classifyConnectError, createContractClient, extractTtsAudio, interactionRound, isCustomBlock, isMasterProduct, isSetProduct, landingRound, logger, parseConnectRejection, randomUuid, receptorsOf, shouldRetryHandshake, transformImageUrl };
+export type { AddToCartResult, BCProduct, Basket, Block, BlockPatch, BoundingBox, CallimacusErrorMessage, Chapter, ClientInfo, ConnectRejection, ConnectionStatusCallback, ContractClient, CustomBlock, ErrorCallback, ErrorMessage, Gallery, GenericProduct, HomePage, Image, ImageEdits, ImageFormatEdit, ImageResizeEdit, InteractionContext, InteractionId, InteractionOptions, InteractionPayload, InteractionPayloadMap, LegacyBlock, LocalizedEPArtwork, LocalizedEPChapter, LogLevel, LoggerConfig, MasterProduct, MasterProductWithVariationGroup, OptionItem, ProductItem, ProductMatch, RecommendationsResponse, RiveManifest, RoundOptions, SLDocument, SLDocumentSection, SLInputEvent, ServerResponseCallback, SetProduct, SkesisItem, SkesisRelatedResponse, SkesisSimilarResponse, Story, SuggestPayload, Suggestions, ThamyrInteractionMap, ThamyrResponse, Topic, TopicContentsPage, TopicSummary, TtsAudio, UiElement, UiObserverConfig, UiSnapshot, UserInteraction, Variant, VariationAttribute, VariationGroup, Video, WhisperPayload };