@callimacus/thamyr-core 4.14.1 → 4.16.0

package/dist/types/index.d.ts

@@ -493,6 +493,20 @@ type ShopifyStorefrontSettings = {
     };
     cartEnabled: boolean;
 };
+type WooCommerceCart$1 = {
+    /**
+     * The site’s address: checkout opens there.
+     */
+    store: string;
+    /**
+     * The Store API root, `…/wp-json/wc/store/v1` (or `…/?rest_route=/wc/store/v1` on plain permalinks): append the route, e.g. `/cart/add-item`.
+     */
+    storeApi: string;
+    /**
+     * The `Cart-Token` header for the next cart call.
+     */
+    cartToken: string;
+};
 type SkesisItemPage = {
     /**
      * The canonical page path, `/map/{locale}/{slug}/{id}`, as the sitemap lists it
@@ -837,15 +851,18 @@ type BlockPatchOutput = {
 type CartCommandOutput = {
     storyId: string;
     chapterId: string;
-    command: 'shopify-add';
     /**
-     * The Shopify product variant to add.
+     * The cart that adds it: the Shopify cart, or the WooCommerce Store API cart.
+     */
+    command: 'shopify-add' | 'woocommerce-add';
+    /**
+     * What to add: a Shopify product variant gid for `shopify-add`, a WooCommerce product or variation id for `woocommerce-add`.
      */
     variantId: string;
     quantity: number;
     item: {
         /**
-         * The item the chat showed (`shopify:product:<gid>`).
+         * The item the chat showed (`shopify:product:<gid>`, `wordpress:product:<id>`).
          */
         id: string;
         name: string;
@@ -939,6 +956,10 @@ type CreateRoundContextOutput = {
      * 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;
+    /**
+     * The client runs a WooCommerce cart in the shopper's browser: the chat may then answer an add to the bag of the store's product with a `cart-command`. Without it, an add to the bag shows the item's details.
+     */
+    woocommerceCart?: boolean;
     [key: string]: unknown;
 };
 type CustomBlockOutput = {
@@ -1096,7 +1117,7 @@ type SlDocumentOutput = {
     publishedAt?: string | null;
     unpublishedAt?: string | null;
     authors?: Array<string>;
-    source?: 'backoffice' | 'api' | 'salesforce';
+    source?: 'backoffice' | 'api' | 'wordpress' | 'salesforce';
     slug?: string;
     documentGroupId: string;
     id: string;
@@ -1143,6 +1164,10 @@ type SlDocumentSectionOutput = {
             height: number;
         };
         poster?: string;
+        /**
+         * Length in seconds.
+         */
+        duration?: number;
         playerConfig?: {
             autoplay: boolean;
             muted: boolean;
@@ -1515,16 +1540,29 @@ type SkesisSimilarResponse = {
         item: SkesisItem;
     }>;
     /**
-     * Present only when the request set `explain: true`: what each stage of the pipeline decided, keyed by stage (search runs plan, route, retrieve, assess, relax and rank; the other pipelines a subset), plus `timings` in milliseconds. Decisions only — never what the engine was told.
+     * System callers only: how the engine ran this request. Nobody else gets the key.
      */
-    trace?: {
-        [key: string]: unknown;
+    diagnostic?: {
+        /**
+         * Present only when the request set `explain: true`: what each stage of the pipeline decided, keyed by stage (search runs retrieve, assess and rank; the other pipelines a subset), plus `timings` in milliseconds. Decisions only — never what the engine was told.
+         */
+        trace?: {
+            [key: string]: unknown;
+        };
     };
 };
 type SkesisRelatedResponse = {
     related: Array<{
         id: string;
         item: SkesisItem;
+        /**
+         * Which way the edge that surfaced the hit runs: `forward`, the anchor references the hit; `reverse`, the hit references the anchor. Under the fallback (`usedFallback`), relative to the neighbour whose edges were used.
+         */
+        direction: 'forward' | 'reverse';
+        /**
+         * The edge's relation as its source stored it, e.g. a commerce platform's recommendation type. Absent when the edge has none.
+         */
+        relation?: string;
     }>;
     siblingColors: Array<{
         id: string;
@@ -1532,10 +1570,15 @@ type SkesisRelatedResponse = {
     }>;
     usedFallback: boolean;
     /**
-     * Present only when the request set `explain: true`: what each stage of the pipeline decided, keyed by stage (search runs plan, route, retrieve, assess, relax and rank; the other pipelines a subset), plus `timings` in milliseconds. Decisions only — never what the engine was told.
+     * System callers only: how the engine ran this request. Nobody else gets the key.
      */
-    trace?: {
-        [key: string]: unknown;
+    diagnostic?: {
+        /**
+         * Present only when the request set `explain: true`: what each stage of the pipeline decided, keyed by stage (search runs retrieve, assess and rank; the other pipelines a subset), plus `timings` in milliseconds. Decisions only — never what the engine was told.
+         */
+        trace?: {
+            [key: string]: unknown;
+        };
     };
 };
 /**
@@ -3063,6 +3106,34 @@ type ShopifyGetStorefrontSettingsResponses = {
      */
     200: ShopifyStorefrontSettings;
 };
+type WoocommerceStartCartErrors = {
+    /**
+     * Validation error
+     */
+    400: unknown;
+    /**
+     * Missing or invalid access token
+     */
+    401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
+    /**
+     * No WordPress site with WooCommerce is connected to this project, or the request comes from the site’s preview
+     */
+    404: PublicError;
+    /**
+     * The store did not answer.
+     */
+    502: PublicError;
+};
+type WoocommerceStartCartResponses = {
+    /**
+     * Success
+     */
+    200: WooCommerceCart$1;
+};
 type SkesisSimilarErrors = {
     /**
      * Validation error
@@ -3341,6 +3412,14 @@ declare class Shopify extends HeyApiClient {
      */
     getStorefrontSettings<ThrowOnError extends boolean = false>(options?: Options<never, ThrowOnError>): RequestResult<ShopifyGetStorefrontSettingsResponses, ShopifyGetStorefrontSettingsErrors, ThrowOnError>;
 }
+declare class Woocommerce extends HeyApiClient {
+    /**
+     * Start a WooCommerce cart
+     *
+     * A new, empty cart on the WooCommerce store of the WordPress site connected to the project: the site’s address, the Store API root and the cart’s first token. Every cart call after this one goes from the browser to the store with the token, and each answer carries the token to send next. Not found while no WordPress site is connected, the site sends no cart token (no WooCommerce on it), or the request comes from the site’s preview, where the cart is off.
+     */
+    startCart<ThrowOnError extends boolean = false>(options?: Options<never, ThrowOnError>): RequestResult<WoocommerceStartCartResponses, WoocommerceStartCartErrors, ThrowOnError>;
+}
 declare class Skesis extends HeyApiClient {
     /**
      * Similar items
@@ -3390,6 +3469,8 @@ declare class CallimacusApi extends HeyApiClient {
     get cart(): Cart;
     private _shopify?;
     get shopify(): Shopify;
+    private _woocommerce?;
+    get woocommerce(): Woocommerce;
     private _skesis?;
     get skesis(): Skesis;
 }
@@ -3453,10 +3534,11 @@ type ThamyrResponse = ThamyrResponse$1;
  */
 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).
+ An add to the bag the chat asks the shopper's browser to make in its Shopify or
+ WooCommerce cart, at most once: it comes only on the socket whose round asked for it,
+ only to a client that declared `context.shopifyCart` or `context.woocommerceCart`, and
+ is never stored with the round, so a replay never sends it again. Run it with the cart
+ its `command` names (`@callimacus/thamyr-react` does).
  */
 type CartCommand = CartCommandOutput;
 /**
@@ -3593,6 +3675,10 @@ type InteractionContext = {
     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;
+    /**
+    The client runs a WooCommerce cart (`useWooCommerceCart`): a round that declares it may get the chat's add to the bag of the store's product as a `cart-command`.
+    */
+    woocommerceCart?: boolean;
 };
 type UiObserverConfig = {
     enabled?: boolean;
@@ -4466,6 +4552,24 @@ Whether `variantId` is a Shopify product variant gid (`gid://shopify/ProductVari
 */
 declare const isVariantGid: (variantId: string) => boolean;
 /**
+A lock kept in `storage` for browsers without Web Locks: a lease with an owner
+and an expiry, read back after a short pause so two tabs that wrote at once
+agree on the last writer. Bounded: a tab waits `waitMs` at most, and a lease a
+crashed tab left behind expires after `ttlMs`.
+@internal
+*/
+declare function leaseLock(storage: CartStorage, timing?: {
+    waitMs?: number;
+    ttlMs?: number;
+    retryMs?: number;
+    settleMs?: number;
+}): CartLock;
+/**
+The browser's Web Locks as a {@link CartLock}; undefined where there are none.
+@internal
+*/
+declare function webLocks(): CartLock | undefined;
+/**
 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.
 */
@@ -4483,6 +4587,166 @@ const {data, error, warnings} = await cart.addItem('gid://shopify/ProductVariant
 */
 declare function createShopifyCart(options: ShopifyCartClientOptions): ShopifyCartClient;
 
+/**
+Money as the Store API sends it: an integer string in the currency's minor unit, so `"1999"` with `currency_minor_unit: 2` is 19.99.
+*/
+type WooCommerceMoney = {
+    currency_code: string;
+    currency_minor_unit: number;
+    currency_symbol: string;
+};
+type WooCommerceCartItem = {
+    /**
+    The line's key: what `removeItem` and `updateQuantity` take.
+    */
+    key: string;
+    /**
+    The product, or the variation, the line holds.
+    */
+    id: number;
+    quantity: number;
+    name: string;
+    permalink: string;
+    images: Array<{
+        src: string;
+        thumbnail: string;
+        alt: string;
+    }>;
+    /**
+    The variation's attributes as the shopper reads them (`{attribute: 'Size', value: 'Medium'}`).
+    */
+    variation: Array<{
+        attribute: string;
+        value: string;
+    }>;
+    prices: WooCommerceMoney & {
+        price: string;
+        regular_price: string;
+        sale_price: string;
+    };
+    totals: WooCommerceMoney & {
+        line_subtotal: string;
+        line_total: string;
+    };
+};
+/**
+The cart as the Store API answers it (`/wc/store/v1/cart`), its fields WooCommerce's own; the ones a bag shows are typed.
+*/
+type WooCommerceCart = {
+    items: WooCommerceCartItem[];
+    items_count: number;
+    totals: WooCommerceMoney & {
+        total_items: string;
+        total_price: string;
+        total_tax: string;
+    };
+    /**
+    The store's notices on the cart as it stands: a line it no longer sells, a quantity it cut.
+    */
+    errors: Array<{
+        code: string;
+        message: string;
+    }>;
+};
+/**
+- `cart_unavailable`: no store is connected to the site's project, or the store refuses the call (a security plugin).
+- `invalid_input`: not a product id, or not a whole quantity.
+- `refused`: the store said no (sold out, not for sale, a line no longer there); its words are in `message`.
+- `no_cart`: nothing to change or check out.
+- `throttled`: the store is rate limiting (429).
+- `busy`: another tab held the cart's start for too long.
+- `network`: no answer, or none in time. The store answers a token it no longer accepts without CORS headers, so that reads as this too.
+- `http`: any other failed status.
+*/
+type WooCommerceCartErrorCode = 'cart_unavailable' | 'invalid_input' | 'refused' | 'no_cart' | 'throttled' | 'busy' | 'network' | 'http';
+type WooCommerceCartError = {
+    code: WooCommerceCartErrorCode;
+    message: string;
+    /**
+    The HTTP status, when the store answered with one.
+    */
+    status?: number;
+    /**
+    The store's own code for a refusal (`woocommerce_rest_product_out_of_stock`).
+    */
+    storeCode?: string;
+};
+/**
+What a cart method resolves, never rejects with. `data` is the cart (`undefined`: none yet), or
+the checkout URL for `checkout`. A refusal carries no cart: read it again with `getCart`.
+*/
+type WooCommerceCartResult<T = WooCommerceCart | undefined> = {
+    data: T;
+    error?: undefined;
+} | {
+    data?: undefined;
+    error: WooCommerceCartError;
+};
+/**
+What callimacus-core's `POST /api/v3/woocommerce/cart` answers: the site, its Store API root and a new cart's first token.
+*/
+type WooCommerceStart = {
+    store: string;
+    storeApi: string;
+    cartToken: string;
+};
+type WooCommerceCartClientOptions = {
+    /**
+    Starts a cart on the store through callimacus-core; undefined (or a rejection) when the project has no store connected.
+    */
+    start: () => Promise<WooCommerceStart | undefined>;
+    /**
+    Defaults to the global `fetch`.
+    */
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+    /**
+    Where the token is kept: `createPageStorage()`, shared by every cart client of the page.
+    */
+    storage: CartStorage;
+    /**
+    The lock the tabs start the cart under: `navigator.locks`, or `leaseLock(storage)` where there are none.
+    */
+    lock: CartLock;
+    /**
+    Sends the shopper to checkout. Defaults to `location.assign`.
+    */
+    navigate?: (url: string) => void;
+};
+type WooCommerceCartClient = {
+    /**
+    The cart as the store has it now; `data: undefined` when there is none yet, and the store is not asked then.
+    */
+    getCart: () => Promise<WooCommerceCartResult>;
+    /**
+    Adds `quantity` (default 1) of a product or a variation, by its WooCommerce id; starts the cart on the first add.
+    */
+    addItem: (productId: string | number, quantity?: number) => Promise<WooCommerceCartResult>;
+    /**
+    Removes a line (`WooCommerceCartItem.key`).
+    */
+    removeItem: (key: string) => Promise<WooCommerceCartResult>;
+    /**
+    Sets a line's quantity; 0 removes it.
+    */
+    updateQuantity: (key: string, quantity: number) => Promise<WooCommerceCartResult>;
+    /**
+    Sends the shopper to the store's checkout with the cart's lines, and resolves its URL. The cart moves to the
+    store: the bag here is empty after, whether or not the shopper buys. An empty cart goes nowhere (`no_cart`).
+    */
+    checkout: () => Promise<WooCommerceCartResult<string>>;
+};
+/**
+The WooCommerce cart in the shopper's browser, on the Store API of the store `start` names. Every method resolves
+a {@link WooCommerceCartResult} and never rejects.
+@example
+```ts
+const storage = createPageStorage();
+const cart = createWooCommerceCart({start: async () => startFromCore(), storage, lock: leaseLock(storage)});
+const {data, error} = await cart.addItem(201, 1);
+```
+*/
+declare function createWooCommerceCart(options: WooCommerceCartClientOptions): WooCommerceCartClient;
+
 /**
  Logger utility for Thamyr SDK
  Provides configurable logging that can be enabled/disabled to avoid console spam
@@ -4573,5 +4837,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, 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 };
+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 };