@callimacus/thamyr-core 4.12.0 → 4.13.1

package/dist/types/index.d.ts

@@ -478,6 +478,21 @@ type WhisperPayload = {
     generated_at: number;
     ttl_ms: number;
 };
+type ShopifyStorefrontSettings = {
+    /**
+     * The store’s primary domain: the host the Storefront API is called on.
+     */
+    domain: string | null;
+    storefrontToken: string | null;
+    sourceName: string | null;
+    /**
+     * Site locale → the buyer’s country (ISO 3166-1 alpha-2).
+     */
+    countries: {
+        [key: string]: string;
+    };
+    cartEnabled: boolean;
+};
 type SkesisItemPage = {
     /**
      * The canonical page path, `/map/{locale}/{slug}/{id}`, as the sitemap lists it
@@ -819,6 +834,30 @@ type BlockPatchOutput = {
      */
     fire: Array<string>;
 };
+type CartCommandOutput = {
+    storyId: string;
+    chapterId: string;
+    command: 'shopify-add';
+    /**
+     * The Shopify product variant to add.
+     */
+    variantId: string;
+    quantity: number;
+    item: {
+        /**
+         * The item the chat showed (`shopify:product:<gid>`).
+         */
+        id: string;
+        name: string;
+        /**
+         * The options that tell the variant apart, for the notice.
+         */
+        options: Array<{
+            name: string;
+            value: string;
+        }>;
+    };
+};
 type BlockOutput = LegacyBlockOutput | CustomBlockOutput;
 type ChapterOutput = {
     id: string;
@@ -896,6 +935,10 @@ type CreateRoundContextOutput = {
      * Ask for the round's `outline`: the blocks it will show, in page order, sent before their contents are ready. Without it, no outline is sent.
      */
     outline?: boolean;
+    /**
+     * The client runs a Shopify cart in the shopper's browser: the chat may then answer an add to the bag with a `cart-command`. Without it, an add to the bag shows the item's details.
+     */
+    shopifyCart?: boolean;
     [key: string]: unknown;
 };
 type CustomBlockOutput = {
@@ -1273,6 +1316,9 @@ type ThamyrResponse$1 = {
 } | {
     type: 'block-patch';
     data: BlockPatchOutput;
+} | {
+    type: 'cart-command';
+    data: CartCommandOutput;
 };
 type UserInteraction$1 = {
     type: 'get-story';
@@ -2993,6 +3039,30 @@ type CartUpdateProductQuantityResponses = {
      */
     200: Basket;
 };
+type ShopifyGetStorefrontSettingsErrors = {
+    /**
+     * Validation error
+     */
+    400: unknown;
+    /**
+     * Missing or invalid access token
+     */
+    401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
+    /**
+     * The project has no store connected from Studio
+     */
+    404: PublicError;
+};
+type ShopifyGetStorefrontSettingsResponses = {
+    /**
+     * Success
+     */
+    200: ShopifyStorefrontSettings;
+};
 type SkesisSimilarErrors = {
     /**
      * Validation error
@@ -3263,6 +3333,14 @@ declare class Cart extends HeyApiClient {
         quantity: number;
     }, options?: Options<never, ThrowOnError>): RequestResult<CartUpdateProductQuantityResponses, CartUpdateProductQuantityErrors, ThrowOnError>;
 }
+declare class Shopify extends HeyApiClient {
+    /**
+     * Get the Shopify cart settings
+     *
+     * The store’s primary domain, its storefront token and channel source name (null until the store is a sales channel), the buyer’s country for each site locale, and whether the cart is on. The cart is off on the site’s preview and once the store uninstalled the app. Not found while the project has no store connected: the SDK then keeps its own config.
+     */
+    getStorefrontSettings<ThrowOnError extends boolean = false>(options?: Options<never, ThrowOnError>): RequestResult<ShopifyGetStorefrontSettingsResponses, ShopifyGetStorefrontSettingsErrors, ThrowOnError>;
+}
 declare class Skesis extends HeyApiClient {
     /**
      * Similar items
@@ -3310,6 +3388,8 @@ declare class CallimacusApi extends HeyApiClient {
     get analytics(): Analytics;
     private _cart?;
     get cart(): Cart;
+    private _shopify?;
+    get shopify(): Shopify;
     private _skesis?;
     get skesis(): Skesis;
 }
@@ -3372,6 +3452,13 @@ type ThamyrResponse = ThamyrResponse$1;
  declares in `patchOn` re-set its animation in place. Apply it with `applyBlockPatch`.
  */
 type BlockPatch = BlockPatchOutput;
+/**
+ An add to the bag the chat asks the shopper's browser to make in its Shopify cart,
+ at most once: it comes only on the socket whose round asked for it, only to a client
+ that declared `context.shopifyCart`, and is never stored with the round, so a replay
+ never sends it again. Run it with the Shopify cart (`@callimacus/thamyr-react` does).
+ */
+type CartCommand = CartCommandOutput;
 /**
 What a Rive animation exposes to be set: the `properties` of a `rive` document section.
 */
@@ -3385,6 +3472,7 @@ declare const ThamyrResponseType: {
     readonly STORY_CREATED: "story-created";
     readonly STORY_SHARED: "story-shared";
     readonly BLOCK_PATCH: "block-patch";
+    readonly CART_COMMAND: "cart-command";
 };
 type ThamyrResponseType = Values<typeof ThamyrResponseType>;
 /**
@@ -3501,6 +3589,10 @@ type InteractionContext = {
     The page title, carried in a delivered interaction's envelope.
     */
     title?: string;
+    /**
+    The client runs a Shopify cart (`useShopifyCart`): a round that declares it may get the chat's add to the bag as a `cart-command`.
+    */
+    shopifyCart?: boolean;
 };
 type UiObserverConfig = {
     enabled?: boolean;
@@ -4148,6 +4240,248 @@ declare function deliverResultOf(block: {
     data?: unknown;
 }): DeliverResult | undefined;
 
+/**
+The Shopify settings a site passes at init (`shopify` in the init config).
+*/
+type ShopifyConfig = {
+    /**
+    The store's domain (its primary domain, or `brand.myshopify.com`): the cart calls the Storefront API there.
+    */
+    storeDomain: string;
+    /**
+    A public Storefront API token. Without one the cart uses Shopify's tokenless access.
+    */
+    storefrontToken?: string;
+    /**
+    The buyer's country (ISO 3166 alpha-2) when core names none for the site's locale.
+    */
+    country?: string;
+};
+/**
+What core's `GET /api/v3/shopify/storefront` answers once a store is connected.
+*/
+type ShopifyStorefront = {
+    domain: string | null;
+    storefrontToken: string | null;
+    sourceName: string | null;
+    /**
+    Site locale → the buyer's country, e.g. `{"it-IT": "IT", "en": "US"}`.
+    */
+    countries: Record<string, string>;
+    /**
+    Off on the site's preview, and once the store uninstalled the app.
+    */
+    cartEnabled: boolean;
+};
+/**
+The settings of the page: core's values where it has them, the init config's elsewhere.
+*/
+type ShopifySettings = {
+    cartEnabled: boolean;
+    storeDomain?: string;
+    /**
+    What the bag is stored under in the browser: the config's domain when the init config names one, core's otherwise. It stays the same when the store gets connected or core fails to answer, so the bag does not empty.
+    */
+    cartKey?: string;
+    storefrontToken?: string;
+    sourceName?: string;
+    countries: Record<string, string>;
+    /**
+    The config's country, for a locale `countries` does not name.
+    */
+    country?: string;
+};
+/**
+What one cart call runs with: the settings, with the buyer's country resolved for the site's current locale.
+*/
+type ShopifyCartSettings = Omit<ShopifySettings, 'countries'>;
+declare function mergeShopifySettings(storefront: ShopifyStorefront | undefined, config?: ShopifyConfig): ShopifySettings;
+/**
+Reads core's Shopify settings for the site and merges them over the init
+config. Never rejects: a 404 means no store is connected yet, and any other
+failure (network, a 5xx, a malformed body) also leaves the config in charge —
+core is not in the cart path, so its outage must not take the cart down. Read
+it once per page load: the answer is `private, no-store`.
+@param client - The contract client every `/api/v3` call goes through (`createContractClient`).
+@param config - The init config's `shopify`.
+*/
+declare function readShopifySettings(client: ContractClient, config?: ShopifyConfig): Promise<ShopifySettings>;
+/**
+The settings one cart call runs with: the buyer's country is the one core names for `locale`, else the config's.
+@param settings - What {@link readShopifySettings} resolved.
+@param locale - The site's current locale (`it-IT`, `en`).
+*/
+declare function cartSettingsFor(settings: ShopifySettings, locale: string | undefined): ShopifyCartSettings;
+
+/**
+The Storefront API version the cart is written against.
+*/
+declare const STOREFRONT_API_VERSION = "2026-10";
+type ShopifyMoney = {
+    amount: string;
+    currencyCode: string;
+};
+type ShopifyCartLine = {
+    id: string;
+    quantity: number;
+    merchandise: {
+        id: string;
+        title: string;
+        product: {
+            title: string;
+            handle: string;
+        };
+        image: {
+            url: string;
+            altText: string | null;
+        } | null;
+        price: ShopifyMoney;
+        selectedOptions: Array<{
+            name: string;
+            value: string;
+        }>;
+    };
+    cost: {
+        totalAmount: ShopifyMoney;
+    };
+};
+/**
+Shopify's refusal of a cart change (`CartUserError`): sold out, not published to the channel, a quantity rule.
+`message` is written for the shopper.
+*/
+type ShopifyUserError = {
+    code: string | null;
+    field: string[] | null;
+    message: string;
+};
+type ShopifyCart = {
+    id: string;
+    checkoutUrl: string;
+    totalQuantity: number;
+    cost: {
+        subtotalAmount: ShopifyMoney;
+        totalAmount: ShopifyMoney;
+    };
+    lines: ShopifyCartLine[];
+};
+/**
+What Shopify did other than asked (`CartWarning`), e.g. `MERCHANDISE_NOT_ENOUGH_STOCK`: it added what it had.
+*/
+type ShopifyCartWarning = {
+    code: string;
+    message: string;
+    target: string;
+};
+/**
+- `cart_disabled`: the cart is off (the site's preview, or the store uninstalled the app).
+- `cart_unavailable`: no store is set up, or the store refuses the call (its storefront password, a revoked token).
+- `invalid_input`: not a product variant id, or not a whole quantity.
+- `refused`: Shopify said no; its reasons are in `userErrors`. A sold-out add is refused too, with Shopify's warning as the message.
+- `no_cart`: nothing to change or check out.
+- `throttled`: Shopify is rate limiting (HTTP 430 or 429).
+- `busy`: another tab held the cart creation for too long.
+- `network`: no answer, or none in time.
+- `http`: any other failed status. `graphql`: the API answered errors only.
+*/
+type ShopifyCartErrorCode = 'cart_disabled' | 'cart_unavailable' | 'invalid_input' | 'refused' | 'no_cart' | 'throttled' | 'busy' | 'network' | 'http' | 'graphql';
+type ShopifyCartError = {
+    code: ShopifyCartErrorCode;
+    message: string;
+    /**
+    The HTTP status, when the store answered with one.
+    */
+    status?: number;
+    userErrors?: ShopifyUserError[];
+};
+/**
+What a cart method resolves, never rejects with. `data` is the cart (`undefined`:
+none yet), or the checkout URL for `checkout`. On `error`, `data` is the cart as
+it stands when Shopify sent it along (a refused add leaves it unchanged).
+`warnings` is always there, empty when Shopify had nothing to say.
+*/
+type ShopifyCartResult<T = ShopifyCart | undefined> = {
+    data: T;
+    error?: undefined;
+    warnings: ShopifyCartWarning[];
+} | {
+    data?: T;
+    error: ShopifyCartError;
+    warnings: ShopifyCartWarning[];
+};
+/**
+The slice of `localStorage` the cart uses.
+*/
+type CartStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/**
+Runs `task` while no other tab runs one under the same `name`; rejects when the lock is not granted in time.
+*/
+type CartLock = <T>(name: string, task: () => Promise<T>) => Promise<T>;
+type ShopifyCartClientOptions = {
+    /**
+    The store and the buyer, asked before every call: memoize what it fetches.
+    */
+    settings: () => Promise<ShopifyCartSettings>;
+    /**
+    Defaults to the global `fetch`.
+    */
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+    /**
+    Defaults to `localStorage`, or memory where the browser refuses it.
+    */
+    storage?: CartStorage;
+    /**
+    Defaults to `navigator.locks`, or a lease kept in `storage` where there is none.
+    */
+    lock?: CartLock;
+    /**
+    Sends the shopper to checkout. Defaults to `location.assign`.
+    */
+    navigate?: (url: string) => void;
+};
+type ShopifyCartClient = {
+    /**
+    The cart as Shopify has it now; `data: undefined` when there is none yet, and the store is not asked then.
+    */
+    getCart: () => Promise<ShopifyCartResult>;
+    /**
+    Adds `quantity` (default 1) of a variant (`gid://shopify/ProductVariant/<id>`, or the bare number); creates the cart on the first add.
+    */
+    addItem: (variantId: string, quantity?: number) => Promise<ShopifyCartResult>;
+    /**
+    Removes a line (`ShopifyCartLine.id`).
+    */
+    removeItem: (lineId: string) => Promise<ShopifyCartResult>;
+    /**
+    Sets a line's quantity; 0 removes it, as in Shopify.
+    */
+    updateQuantity: (lineId: string, quantity: number) => Promise<ShopifyCartResult>;
+    /**
+    Sends the shopper to Shopify's checkout for the cart, and resolves its URL. An empty cart goes nowhere (`no_cart`).
+    */
+    checkout: () => Promise<ShopifyCartResult<string>>;
+};
+/**
+Whether `variantId` is a Shopify product variant gid (`gid://shopify/ProductVariant/123`).
+*/
+declare const isVariantGid: (variantId: string) => boolean;
+/**
+The browser's storage, or one kept in memory where the browser refuses it. Pass the same one to every
+cart client of a page, so they share the cart id even where the browser keeps nothing.
+*/
+declare function createPageStorage(): CartStorage;
+/**
+The Shopify cart in the shopper's browser, on the Storefront API (version
+{@link STOREFRONT_API_VERSION}) of the store the settings name, tokenless
+until a storefront token exists. Every method resolves a
+{@link ShopifyCartResult} and never rejects.
+@example
+```ts
+const cart = createShopifyCart({settings: async () => ({cartEnabled: true, storeDomain: 'brand.com', country: 'IT'})});
+const {data, error, warnings} = await cart.addItem('gid://shopify/ProductVariant/123', 1);
+```
+*/
+declare function createShopifyCart(options: ShopifyCartClientOptions): ShopifyCartClient;
+
 /**
  Logger utility for Thamyr SDK
  Provides configurable logging that can be enabled/disabled to avoid console spam
@@ -4238,5 +4572,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, ServerEvents, ThamyrHttpError, ThamyrResponseType, UserInteractionType, actionOf, addToCartResultOf, applyBlockPatch, blockKeyOf, callimacusService, classifyConnectError, createContractClient, deliverResultOf, extractTtsAudio, fieldsOf, interactionRound, isCustomBlock, isMasterProduct, isSetProduct, landingRound, logger, parseConnectRejection, parseMapPath, randomUuid, receptorsOf, resolveMapPage, shouldRetryHandshake, transformImageUrl };
-export type { Action, ActionType, AddToCartResult, BCProduct, Basket, Block, BlockPatch, BoundingBox, CallimacusErrorMessage, 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, SkesisItem, SkesisItemPage, SkesisRelatedResponse, SkesisSimilarResponse, Story, SuggestPayload, Suggestions, ThamyrInteractionMap, ThamyrResponse, Topic, TopicContentsPage, TopicSummary, TtsAudio, UiElement, UiObserverConfig, UiSnapshot, UserInteraction, Variant, VariationAttribute, VariationGroup, Video, WhisperPayload };
+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, deliverResultOf, extractTtsAudio, fieldsOf, interactionRound, isCustomBlock, isMasterProduct, isSetProduct, isVariantGid, landingRound, logger, mergeShopifySettings, parseConnectRejection, parseMapPath, randomUuid, readShopifySettings, receptorsOf, resolveMapPage, shouldRetryHandshake, transformImageUrl };
+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 };