@callimacus/thamyr-liquid 4.3.4

package/dist/types/index.d.ts

@@ -0,0 +1,201 @@
+/*!
+ * Copyright © 2025–2026 Solomei AI SRL. All rights reserved.
+ *
+ * Proprietary software, licensed for use by Callimacus customers only.
+ * See LICENSE.md for the full terms.
+ *
+ */
+import { CallimacusService } from '@callimacus/thamyr-core';
+
+/**
+ Headless Callimacus runtime for Shopify Liquid themes.
+
+ Mounts on `[data-callimacus]` elements, owns transport and round lifecycle,
+ and dispatches server blocks to theme-owned renderers registered on
+ `window.callimacusRenderers`. Creates no DOM of its own and ships no CSS.
+ On the mount element it maintains `data-callimacus-state` (see
+ {@link MountState}), `aria-busy`, a `data-callimacus-ready` marker, and the
+ {@link CallimacusHandle} at `element.callimacus`; after a successful round it
+ replaces the contents of `[data-callimacus-output]` — or, when that element
+ is missing, of the mount element itself (warned at mount time). The theme's
+ server-rendered markup survives every failure path.
+
+ @packageDocumentation
+ */
+
+/**
+ The values the runtime writes to `data-callimacus-state`. Themes key their
+ state CSS and copy off this attribute.
+ */
+type MountState = 'loading' | 'ready' | 'empty' | 'error' | 'design-mode';
+/**
+ The machine-readable grammar of {@link CallimacusError.code}: `timeout` and
+ `send_failed` from the round lifecycle, `cart_rejected` and
+ `cart_unreachable` from `ctx.addToCart`, `server_<code>` for errors relayed
+ from Callimacus.
+ */
+type CallimacusErrorCode = 'timeout' | 'send_failed' | 'cart_rejected' | 'cart_unreachable' | `server_${string}`;
+/**
+ Error surfaced by the runtime, both to `callimacus:error` listeners and from
+ `ctx.addToCart`. The original failure, when there is one, rides on `cause`.
+ */
+declare class CallimacusError extends Error {
+    readonly code: CallimacusErrorCode;
+    constructor(code: CallimacusErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+A Skesis price object; `amount` is in major units (313.6 is $313.60).
+*/
+type Price = {
+    amount?: number;
+    currency?: string;
+};
+type CatalogVariant = {
+    id?: string | number;
+    orderable?: boolean;
+} & Record<string, unknown>;
+/**
+A catalogue hit as Skesis returns it for a Shopify-connected project.
+*/
+type CatalogItem = {
+    fields?: {
+        title?: string;
+        'shopify-handle'?: string;
+        price?: Price | number;
+        images?: Array<{
+            url?: string;
+            alt?: string;
+        }>;
+        variantTree?: {
+            variants?: CatalogVariant[];
+        };
+    } & Record<string, unknown>;
+} & Record<string, unknown>;
+/**
+ The slice of a server block a renderer works with. Custom blocks arrive with
+ their type prefixed on the wire: a block saved as `giftGuide` is
+ `custom:giftGuide` here — register renderers with the prefixed name.
+ */
+type RenderableBlock = {
+    id: string;
+    type: string;
+    priority?: number;
+    data: unknown;
+};
+/**
+ The helpers handed to every renderer. Emits no markup — these package the
+ commerce plumbing that is easy to get wrong on Shopify. The object is frozen:
+ all renderers of a mount share it across rounds.
+ */
+type RendererContext = {
+    locale: string;
+    currency?: string;
+    /**
+    The parsed `[data-callimacus-settings]` JSON, `{}` when absent or invalid.
+    */
+    settings: Record<string, unknown>;
+    /**
+     Catalogue items in a block, whatever data key they arrived under. Every
+     returned item carries a non-empty `shopify-handle` — exactly what
+     `productUrl` needs.
+     */
+    picks(block: RenderableBlock): CatalogItem[];
+    /**
+     First non-empty string in a block's data, direct or under a `text` key —
+     Demosthenes/LLM copy.
+     */
+    text(block: RenderableBlock): string | undefined;
+    /**
+     Currency formatting for a Skesis price object or number. A price's own
+     `currency` wins over the storefront's presentment currency (the amount is
+     not converted, so the label must follow the data); returns `''` when
+     there is no numeric amount.
+     */
+    money(price: Price | number | undefined): string;
+    /**
+    Locale-correct storefront URL. Never build this by hand.
+    */
+    productUrl(item: CatalogItem): string | undefined;
+    /**
+    Shopify CDN transform. Returns a URL string, not an element.
+    */
+    imageUrl(item: CatalogItem, options?: {
+        width?: number;
+        index?: number;
+    }): string | undefined;
+    /**
+     Numeric id of the first orderable variant, for the AJAX cart — falling
+     back to the first variant when none is marked orderable.
+     */
+    variantId(item: CatalogItem): string | undefined;
+    /**
+     Native AJAX cart, executed inside the theme so the cart cookie and the
+     theme's own cart object stay authoritative. Resolves with the cart;
+     rejects with a {@link CallimacusError} — `cart_rejected` carrying
+     Shopify's own message, or `cart_unreachable` when the request itself
+     failed at the network level.
+     */
+    addToCart(variantId: string | number, quantity?: number): Promise<unknown>;
+};
+/**
+ One renderer: owns the markup for one block type. Return a Node, or
+ null/undefined to render nothing — a block whose renderer returns nothing is
+ simply absent from the page.
+ */
+type CallimacusRenderer = {
+    type: string;
+    render(block: RenderableBlock, context: RendererContext): Node | null | undefined;
+};
+/**
+ The handle placed on the mount element and emitted as the
+ `callimacus:mounted` event detail.
+ */
+type CallimacusHandle = {
+    ask(value: string): Promise<void>;
+    readonly ctx: RendererContext;
+    readonly state: string | undefined;
+};
+/**
+A mount element once the runtime has taken it over.
+*/
+type CallimacusHostElement = HTMLElement & {
+    callimacus?: CallimacusHandle;
+};
+/**
+ The transport surface the runtime needs — {@link CallimacusService}
+ satisfies it. Injectable so tests can drive rounds without a socket.
+ */
+type RoundTransport = Pick<CallimacusService, 'connect' | 'sendUserInteraction' | 'onServerResponse' | 'onError'>;
+type MountOptions = {
+    transport?: RoundTransport;
+    roundTimeoutMs?: number;
+};
+type MountConfig = {
+    clientId?: string;
+    endpoint: string;
+    language: string;
+    currency?: string;
+    rootUrl: string;
+    cartAddUrl: string;
+    settings: Record<string, unknown>;
+};
+/**
+ Builds the {@link RendererContext} for one mount. Exported for tests; hosts
+ receive it ready-made via `callimacus:mounted` and `root.callimacus.ctx`.
+ */
+declare function makeCtx(config: MountConfig): RendererContext;
+/**
+ Takes over one `[data-callimacus]` element. Idempotent: a root that is
+ already mounted is left alone, so calling it again after
+ `shopify:section:load` re-mounts only the reloaded section's fresh element.
+ A mount that fails degrades like every other failure — error state, event,
+ prefixed log — and never takes sibling mounts with it.
+ */
+declare function mount(root: CallimacusHostElement, options?: MountOptions): void;
+/**
+Mounts every `[data-callimacus]` element in scope not already mounted.
+*/
+declare function mountAll(scope: ParentNode, options?: MountOptions): void;
+
+export { CallimacusError, makeCtx, mount, mountAll };
+export type { CallimacusErrorCode, CallimacusHandle, CallimacusHostElement, CallimacusRenderer, CatalogItem, CatalogVariant, MountOptions, MountState, Price, RenderableBlock, RendererContext, RoundTransport };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@callimacus/thamyr-liquid",
+  "version": "4.3.4",
+  "private": false,
+  "description": "Headless Callimacus runtime for Shopify Liquid themes",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://docs.callimacus.ai/thamyr-sdk/shopify-liquid",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "jsdelivr": "dist/browser/callimacus-runtime.min.js",
+  "unpkg": "dist/browser/callimacus-runtime.min.js",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./browser": "./dist/browser/callimacus-runtime.min.js"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "CHANGELOG.core.md",
+    "MIGRATION.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "@callimacus:registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "prepack": "cp ../../MIGRATION.md ./MIGRATION.md && cp ../core/CHANGELOG.md ./CHANGELOG.core.md",
+    "build": "rollup -c --failAfterWarnings",
+    "dev": "rollup -c -w",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@callimacus/thamyr-core": "^4.3.4"
+  },
+  "devDependencies": {
+    "eslint-config-xo": "^4.0.1",
+    "jsdom": "^30.1.1",
+    "vitest": "^5.0.2"
+  }
+}