@callimacus/thamyr-core 4.8.3 → 4.10.0

package/dist/types/index.d.ts

@@ -333,6 +333,7 @@ interface TDataShape {
 type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
 type Options$1<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = 'fields'> = OmitKeys<RequestOptions<TResponse, TResponseStyle, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & ([TData] extends [never] ? unknown : Omit<TData, 'url'>);
 
+type LanguageCode = 'aa' | 'ab' | 'ae' | 'af' | 'ak' | 'am' | 'an' | 'ar' | 'as' | 'av' | 'ay' | 'az' | 'ba' | 'be' | 'bg' | 'bi' | 'bm' | 'bn' | 'bo' | 'br' | 'bs' | 'ca' | 'ce' | 'ch' | 'co' | 'cr' | 'cs' | 'cu' | 'cv' | 'cy' | 'da' | 'de' | 'dv' | 'dz' | 'ee' | 'el' | 'en' | 'eo' | 'es' | 'et' | 'eu' | 'fa' | 'ff' | 'fi' | 'fj' | 'fo' | 'fr' | 'fy' | 'ga' | 'gd' | 'gl' | 'gn' | 'gu' | 'gv' | 'ha' | 'he' | 'hi' | 'ho' | 'hr' | 'ht' | 'hu' | 'hy' | 'hz' | 'ia' | 'id' | 'ie' | 'ig' | 'ii' | 'ik' | 'io' | 'is' | 'it' | 'iu' | 'ja' | 'jv' | 'ka' | 'kg' | 'ki' | 'kj' | 'kk' | 'kl' | 'km' | 'kn' | 'ko' | 'kr' | 'ks' | 'ku' | 'kv' | 'kw' | 'ky' | 'la' | 'lb' | 'lg' | 'li' | 'ln' | 'lo' | 'lt' | 'lu' | 'lv' | 'mg' | 'mh' | 'mi' | 'mk' | 'ml' | 'mn' | 'mr' | 'ms' | 'mt' | 'my' | 'na' | 'nb' | 'nd' | 'ne' | 'ng' | 'nl' | 'nn' | 'no' | 'nr' | 'nv' | 'ny' | 'oc' | 'oj' | 'om' | 'or' | 'os' | 'pa' | 'pi' | 'pl' | 'ps' | 'pt' | 'qu' | 'rm' | 'rn' | 'ro' | 'ru' | 'rw' | 'sa' | 'sc' | 'sd' | 'se' | 'sg' | 'si' | 'sk' | 'sl' | 'sm' | 'sn' | 'so' | 'sq' | 'sr' | 'ss' | 'st' | 'su' | 'sv' | 'sw' | 'ta' | 'te' | 'tg' | 'th' | 'ti' | 'tk' | 'tl' | 'tn' | 'to' | 'tr' | 'ts' | 'tt' | 'tw' | 'ty' | 'ug' | 'uk' | 'ur' | 'uz' | 've' | 'vi' | 'vo' | 'wa' | 'wo' | 'xh' | 'yi' | 'yo' | 'za' | 'zh' | 'zu';
 type ChapterStatus$1 = 1 | 2 | 3 | 4;
 type GalleryMode$1 = 'masonry' | 'carousel';
 type SlInputEvent = {
@@ -426,6 +427,21 @@ type TopicContentsPage = {
     offset: number;
     limit: number;
 };
+type DocumentIndexEntry = {
+    /**
+     * The page path, `/map/{language}/{slug}` — what a link to the document points at
+     */
+    path: string;
+    slug: string;
+    /**
+     * The meta title, or the document name when none is set
+     */
+    title: string;
+    /**
+     * The meta description, when set
+     */
+    description?: string;
+};
 type RecommendationsResponse = {
     directRecommendations: Array<ProductMatch>;
     inverseRecommendations: Array<ProductMatch>;
@@ -462,6 +478,44 @@ type WhisperPayload = {
     generated_at: number;
     ttl_ms: number;
 };
+type SkesisItemPage = {
+    /**
+     * The canonical page path, `/map/{locale}/{slug}/{id}`, as the sitemap lists it
+     */
+    path: string;
+    /**
+     * The catalogue locale the item is read in, as the engine spells it (e.g. `en-IT`)
+     */
+    locale: string;
+    kind: string;
+    /**
+     * The URL segment the site publishes the item's kind under
+     */
+    slug: string;
+    /**
+     * The item's title, or its id when it has none
+     */
+    title: string;
+    /**
+     * The item's description, as plain text
+     */
+    description?: string;
+    /**
+     * The URL of the item's first image
+     */
+    image?: string;
+    /**
+     * The item as stored, for a page that shows more than the crawler is served
+     */
+    item: {
+        id: string;
+        kind: string;
+        locale: string;
+        fields: {
+            [key: string]: unknown;
+        };
+    };
+};
 type ProductMatch = {
     match?: {
         id: string;
@@ -793,6 +847,19 @@ type ChapterOutput = {
     };
     references?: Array<string>;
     blocks?: Array<BlockOutput>;
+    /**
+     * The blocks this round will show, in page order, sent as soon as the page is decided and before their contents are ready, so a storefront can hold their places. A block whose contents find nothing is still dropped: `blocks` is the page; the outline is the shape it is expected to take. Sent only when the round asked for it (`context.outline`).
+     */
+    outline?: Array<{
+        /**
+         * The block's key, as its block will carry it.
+         */
+        key: string;
+        /**
+         * The block's type, as its block will carry it (`custom:<type>`).
+         */
+        type: string;
+    }>;
     status: ChapterStatus$1;
 };
 type CreateRoundContextOutput = {
@@ -825,6 +892,10 @@ type CreateRoundContextOutput = {
      * The page title, carried in a delivered interaction's envelope.
      */
     title?: string;
+    /**
+     * 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;
     [key: string]: unknown;
 };
 type CustomBlockOutput = {
@@ -967,7 +1038,7 @@ type LocalizedEpArtworkOutput = {
     type: 'ep';
 };
 type SlDocumentOutput = {
-    language: string;
+    language: LanguageCode;
     type: 'content' | 'image' | 'video';
     name: string;
     backgroundKnowledge: boolean;
@@ -2678,6 +2749,26 @@ type ContentGetDocumentByPathResponses = {
      */
     200: SlDocumentOutput;
 };
+type ContentListDocumentsErrors = {
+    /**
+     * Validation error
+     */
+    400: unknown;
+    /**
+     * Missing or invalid access token
+     */
+    401: unknown;
+    /**
+     * The caller is not permitted to perform this operation
+     */
+    403: PinaxForbidden;
+};
+type ContentListDocumentsResponses = {
+    /**
+     * Success
+     */
+    200: Array<DocumentIndexEntry>;
+};
 type StoriesGetSharedErrors = {
     /**
      * Validation error
@@ -2956,6 +3047,37 @@ type SkesisRelatedResponses = {
      */
     200: SkesisRelatedResponse;
 };
+type SkesisGetItemByPathErrors = {
+    /**
+     * Validation error
+     */
+    400: unknown;
+    /**
+     * 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 item
+     */
+    404: PublicError;
+    /**
+     * Skesis engine unavailable (rate cap, upstream failure, or not configured); retry later
+     */
+    502: {
+        error: string;
+        errorId: string;
+    };
+};
+type SkesisGetItemByPathResponses = {
+    /**
+     * Success
+     */
+    200: SkesisItemPage;
+};
 
 type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options$1<TData, ThrowOnError, TResponse> & {
     /**
@@ -3033,6 +3155,14 @@ declare class Content extends HeyApiClient {
     getDocumentByPath<ThrowOnError extends boolean = false>(parameters: {
         path: string;
     }, options?: Options<never, ThrowOnError>): RequestResult<ContentGetDocumentByPathResponses, ContentGetDocumentByPathErrors, ThrowOnError>;
+    /**
+     * List the published documents in a language
+     *
+     * The entries of the per-language index at `/map/{language}`: every approved, published document with a slug, newest first, each with the path of its page and the title a link to it should carry. A language with no published document lists nothing, it is not a 404.
+     */
+    listDocuments<ThrowOnError extends boolean = false>(parameters: {
+        language: string;
+    }, options?: Options<never, ThrowOnError>): RequestResult<ContentListDocumentsResponses, ContentListDocumentsErrors, ThrowOnError>;
 }
 declare class Stories extends HeyApiClient {
     /**
@@ -3153,6 +3283,14 @@ declare class Skesis extends HeyApiClient {
         anchorId: string;
         locale?: string;
     }, options?: Options<never, ThrowOnError>): RequestResult<SkesisRelatedResponses, SkesisRelatedErrors, ThrowOnError>;
+    /**
+     * Get a catalogue item page by its path
+     *
+     * Resolves a `/map/{locale}/{slug}/{id}` path from the sitemap to what the crawler is served there: a visible item of a kind the site publishes as pages, in that locale. Pass the path as the browser shows it (`location.pathname`). A document wins a path both could name, so resolve a `/map/` path with `content.getDocumentByPath` first and with this read on its 404. A path that names no such item is a 404, not a 400.
+     */
+    getItemByPath<ThrowOnError extends boolean = false>(parameters: {
+        path: string;
+    }, options?: Options<never, ThrowOnError>): RequestResult<SkesisGetItemByPathResponses, SkesisGetItemByPathErrors, ThrowOnError>;
 }
 declare class CallimacusApi extends HeyApiClient {
     static readonly __registry: HeyApiRegistry<CallimacusApi>;
@@ -3802,6 +3940,90 @@ declare function addToCartResultOf(block: {
  */
 declare function applyBlockPatch(chapter: Chapter, patch: BlockPatch): Chapter;
 
+type ContractClient = Client;
+/**
+What a contract call rejects with under `{throwOnError: true}`.
+
+- `status` is the HTTP status of the failed response, `undefined` when no response arrived (network or
+  CORS failure). It can be 2xx when the response arrived but its body could not be parsed or validated.
+- `body` is the parsed error body the server sent — `{error, errorId}` on the public API, a string for
+  non-JSON bodies, `{}` for an empty body — or, when no response arrived, the underlying `TypeError`
+  (also exposed as `cause`).
+
+Aborting a call through its `signal` is not a failure of the call: the abort reason is rethrown as is. The
+request signal decides, and it does so whether the abort landed before or after the response headers arrived.
+*/
+declare class ThamyrHttpError extends Error {
+    readonly status: number | undefined;
+    readonly body: unknown;
+    readonly response: Response | undefined;
+    readonly request: Request | undefined;
+    constructor(body: unknown, response?: Response, request?: Request);
+}
+/**
+Client for the generated {@link CallimacusApi}: the client id doubles as bearer token and x-sl-access-token.
+Calls made with `{throwOnError: true}` (per call, or through `setConfig`) reject with a
+{@link ThamyrHttpError}; the envelope's `error` stays the parsed body, as documented.
+*/
+declare function createContractClient(config: {
+    endpoint: string;
+    accessToken: string;
+    /**
+    Send cookies cross-origin (the old axios `withCredentials`).
+    */
+    withCredentials?: boolean;
+}): ContractClient;
+
+/**
+ What a `/map/…` pathname names: the index of a language, or one of its documents.
+ */
+type MapPath = {
+    language: string;
+    slug?: string;
+};
+/**
+ Parses a `/map/{language}` or `/map/{language}/{slug}` pathname the way the
+ server does: the leading slash is optional, the slug may contain slashes, and
+ a trailing slash after the language still means the index. Anything else —
+ another route, a bare `/map` — is `undefined`. Pass `location.pathname`, not
+ the full URL: a query string or a hash would end up in the slug.
+ */
+declare function parseMapPath(pathname: string): MapPath | undefined;
+/**
+ What a `/map/…` pathname shows: one document, the per-language index, or one
+ catalogue item (`language` is then the catalogue locale, `slug` the kind's
+ slug and the item id).
+ */
+type MapPage = {
+    kind: 'document';
+    language: string;
+    slug: string;
+    document: SLDocument;
+} | {
+    kind: 'index';
+    language: string;
+    entries: DocumentIndexEntry[];
+} | {
+    kind: 'item';
+    language: string;
+    slug: string;
+    itemPage: SkesisItemPage;
+};
+/**
+ Resolves what to show at a `/map/…` pathname: the document at
+ `/map/{language}/{slug}`, the entries of the per-language index at
+ `/map/{language}` — the same list the crawler is served, newest first — or the
+ catalogue item at `/map/{locale}/{kind-slug}/{id}`. A document wins a path both
+ could name, as it does in the server render.
+ @param api - A `Thamyr` instance, or the React package's `thamyrApi`.
+ @param pathname - `location.pathname`.
+ @returns `undefined` when the pathname is not a `/map/` path or names no
+ published document, so the caller renders its own not-found. Any other
+ failure (network, a 5xx, an SDK not initialized) rejects — with a
+ `ThamyrHttpError` when a response arrived.
+ */
+declare function resolveMapPage(api: Pick<CallimacusApi, 'content' | 'skesis'>, pathname: string): Promise<MapPage | undefined>;
+
 /**
  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
@@ -4016,39 +4238,5 @@ declare function transformImageUrl(cdnUrl: string, edits: ImageEdits): string;
  */
 declare function randomUuid(): string;
 
-type ContractClient = Client;
-/**
-What a contract call rejects with under `{throwOnError: true}`.
-
-- `status` is the HTTP status of the failed response, `undefined` when no response arrived (network or
-  CORS failure). It can be 2xx when the response arrived but its body could not be parsed or validated.
-- `body` is the parsed error body the server sent — `{error, errorId}` on the public API, a string for
-  non-JSON bodies, `{}` for an empty body — or, when no response arrived, the underlying `TypeError`
-  (also exposed as `cause`).
-
-Aborting a call through its `signal` is not a failure of the call: the abort reason is rethrown as is. The
-request signal decides, and it does so whether the abort landed before or after the response headers arrived.
-*/
-declare class ThamyrHttpError extends Error {
-    readonly status: number | undefined;
-    readonly body: unknown;
-    readonly response: Response | undefined;
-    readonly request: Request | undefined;
-    constructor(body: unknown, response?: Response, request?: Request);
-}
-/**
-Client for the generated {@link CallimacusApi}: the client id doubles as bearer token and x-sl-access-token.
-Calls made with `{throwOnError: true}` (per call, or through `setConfig`) reject with a
-{@link ThamyrHttpError}; the envelope's `error` stays the parsed body, as documented.
-*/
-declare function createContractClient(config: {
-    endpoint: string;
-    accessToken: string;
-    /**
-    Send cookies cross-origin (the old axios `withCredentials`).
-    */
-    withCredentials?: boolean;
-}): ContractClient;
-
-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, randomUuid, receptorsOf, shouldRetryHandshake, transformImageUrl };
-export type { Action, ActionType, AddToCartResult, BCProduct, Basket, Block, BlockPatch, BoundingBox, CallimacusErrorMessage, Chapter, ClientInfo, ConnectRejection, ConnectionStatusCallback, ContractClient, CustomBlock, DeliverResult, 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 };
+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 };