@merchi/product-form-sdk 1.0.9

package/dist/helpers/buildJob.js

@@ -0,0 +1,190 @@
+import { OPTION_FIELD_TYPES } from './constants';
+import { groupFieldsOf, independentFieldsOf, isOptionQuantityGridProduct, productHasGroups, } from './product';
+export function selectionsToVariations(selections) {
+    return Object.entries(selections).map(([fieldId, sel]) => {
+        const variation = {
+            variationField: { id: Number(fieldId) },
+            value: sel.value,
+        };
+        if (sel.variationFiles?.length) {
+            variation.variationFiles = sel.variationFiles.map((file) => ({
+                id: file.id,
+            }));
+        }
+        // Prefer explicit option rows (colour-extract colour/value edits).
+        if (sel.selectedOptions?.length) {
+            variation.selectedOptions = sel.selectedOptions;
+        }
+        return variation;
+    });
+}
+/** Build the job JSON the API expects from provider/form state. */
+export function buildProductFormJob(state) {
+    const { product, quantity, selections, groups, optionQuantities } = state;
+    const independentVariations = selectionsToVariations(pickSelections(selections, independentFieldsOf(product)));
+    const job = {
+        product: { id: product?.id },
+        variations: independentVariations,
+    };
+    if (!productHasGroups(product)) {
+        return { ...job, quantity };
+    }
+    if (isOptionQuantityGridProduct(product) && optionQuantities) {
+        const groupField = groupFieldsOf(product)[0];
+        job.variationsGroups = (groupField.options || [])
+            .filter((opt) => opt?.id !== undefined)
+            .map((opt) => ({
+            quantity: optionQuantities[opt.id] ?? 0,
+            variations: [
+                {
+                    variationField: { id: groupField.id },
+                    value: String(opt.id),
+                },
+            ],
+        }))
+            .filter((group) => group.quantity > 0);
+        return job;
+    }
+    if (groups?.length) {
+        job.variationsGroups = groups
+            .filter((row) => row.quantity > 0)
+            .map((row) => ({
+            quantity: row.quantity,
+            variations: selectionsToVariations(pickSelections(row.selections, groupFieldsOf(product))),
+        }));
+    }
+    return job;
+}
+function pickSelections(selections, fields) {
+    const ids = new Set(fields.map((f) => f.id).filter((id) => id !== undefined));
+    const out = {};
+    for (const [key, sel] of Object.entries(selections)) {
+        const id = Number(key);
+        if (ids.has(id))
+            out[id] = sel;
+    }
+    return out;
+}
+function fieldIdOf(variation) {
+    const field = variation.variationField;
+    if (typeof field === 'number')
+        return field;
+    return field?.id;
+}
+function selectionFromVariation(variation, field) {
+    const value = variation.value != null ? String(variation.value) : '';
+    const selectedOptions = variation.selectedOptions || [];
+    const fromOptions = selectedOptions
+        .map((o) => o.id)
+        .filter((id) => id !== undefined);
+    const variationFiles = (variation.variationFiles || [])
+        .filter((file) => file?.id)
+        .map((file) => ({ id: file.id }));
+    if (fromOptions.length) {
+        return {
+            value: value || fromOptions.join(','),
+            selectedOptionIds: fromOptions,
+            selectedOptions,
+            variationFiles: variationFiles.length ? variationFiles : undefined,
+        };
+    }
+    if (field && OPTION_FIELD_TYPES.has(Number(field.fieldType)) && value) {
+        const ids = value
+            .split(',')
+            .map((part) => parseInt(part.trim(), 10))
+            .filter((n) => !Number.isNaN(n));
+        return {
+            value,
+            selectedOptionIds: ids,
+            variationFiles: variationFiles.length ? variationFiles : undefined,
+        };
+    }
+    return {
+        value,
+        selectedOptionIds: [],
+        variationFiles: variationFiles.length ? variationFiles : undefined,
+    };
+}
+function variationsToSelections(variations, fields) {
+    const byId = new Map(fields
+        .filter((f) => f.id !== undefined)
+        .map((f) => [f.id, f]));
+    const out = {};
+    for (const variation of variations || []) {
+        const id = fieldIdOf(variation);
+        if (id === undefined)
+            continue;
+        out[id] = selectionFromVariation(variation, byId.get(id));
+    }
+    return out;
+}
+/** Reverse of buildProductFormJob — hydrate provider state from a cart item / job. */
+export function jobToFormState(product, job) {
+    const minQty = Number(product.minOrderQuantity ?? product.minimum) || 1;
+    const independentFields = independentFieldsOf(product);
+    const groupFields = groupFieldsOf(product);
+    const selections = {
+        ...initialDefaultSelections(independentFields),
+        ...variationsToSelections(job?.variations, independentFields),
+    };
+    if (!productHasGroups(product)) {
+        return {
+            quantity: Number(job?.quantity) > 0 ? Number(job?.quantity) : minQty,
+            selections,
+            groups: [],
+            optionQuantities: {},
+        };
+    }
+    if (isOptionQuantityGridProduct(product)) {
+        const field = groupFields[0];
+        const optionQuantities = {};
+        for (const opt of field?.options || []) {
+            if (opt?.id !== undefined)
+                optionQuantities[opt.id] = 0;
+        }
+        for (const group of job?.variationsGroups || []) {
+            const variation = group.variations?.[0];
+            const optId = variation?.value != null ? Number(variation.value) : undefined;
+            if (optId !== undefined && !Number.isNaN(optId)) {
+                optionQuantities[optId] = Number(group.quantity) || 0;
+            }
+        }
+        return {
+            quantity: minQty,
+            selections,
+            groups: [],
+            optionQuantities,
+        };
+    }
+    const groups = (job?.variationsGroups || [])
+        .map((group) => ({
+        quantity: Number(group.quantity) > 0 ? Number(group.quantity) : minQty,
+        selections: {
+            ...initialDefaultSelections(groupFields),
+            ...variationsToSelections(group.variations, groupFields),
+        },
+    }))
+        .filter((row) => row.quantity > 0);
+    return {
+        quantity: minQty,
+        selections,
+        groups: groups.length
+            ? groups
+            : [{ quantity: minQty, selections: initialDefaultSelections(groupFields) }],
+        optionQuantities: {},
+    };
+}
+function initialDefaultSelections(fields) {
+    const out = {};
+    for (const f of fields) {
+        if (f?.id === undefined)
+            continue;
+        if (OPTION_FIELD_TYPES.has(Number(f.fieldType)) && f.fieldType !== 6) {
+            const opt = (f.options || []).find((o) => o?.isVisible !== false && o?.available !== false);
+            if (opt?.id !== undefined) {
+                out[f.id] = { value: String(opt.id), selectedOptionIds: [opt.id] };
+            }
+        }
+    }
+    return out;
+}

package/dist/helpers/constants.d.ts

@@ -0,0 +1,8 @@
+/** Selectable field types whose `value` is option ids (vs. free text/number). */
+export declare const OPTION_FIELD_TYPES: Set<number>;
+/** Colour Extract: image upload + runtime-generated colour options. */
+export declare const COLOUR_EXTRACT = 13;
+/** Area: height × width stored as millimetres (`"heightMm,widthMm"`). */
+export declare const AREA = 14;
+/** Field types that carry uploaded files on the variation. */
+export declare const FILE_FIELD_TYPES: Set<number>;

package/dist/helpers/constants.js

@@ -0,0 +1,8 @@
+/** Selectable field types whose `value` is option ids (vs. free text/number). */
+export const OPTION_FIELD_TYPES = new Set([2, 6, 7, 9, 11]);
+/** Colour Extract: image upload + runtime-generated colour options. */
+export const COLOUR_EXTRACT = 13;
+/** Area: height × width stored as millimetres (`"heightMm,widthMm"`). */
+export const AREA = 14;
+/** Field types that carry uploaded files on the variation. */
+export const FILE_FIELD_TYPES = new Set([3, COLOUR_EXTRACT]);

package/dist/helpers/format.d.ts

@@ -0,0 +1,4 @@
+/** Format a numeric amount as a currency string. */
+export declare function formatCurrency(amount: number, currency?: string): string;
+/** Build an absolute merchi.co URL from a relative path. */
+export declare function urlFor(path: string): string;

package/dist/helpers/format.js

@@ -0,0 +1,18 @@
+const MERCHI_BASE = 'https://merchi.co';
+/** Format a numeric amount as a currency string. */
+export function formatCurrency(amount, currency = 'USD') {
+    try {
+        return new Intl.NumberFormat(undefined, {
+            style: 'currency',
+            currency,
+        }).format(amount);
+    }
+    catch {
+        return `${currency} ${amount.toFixed(2)}`;
+    }
+}
+/** Build an absolute merchi.co URL from a relative path. */
+export function urlFor(path) {
+    const trimmed = path.startsWith('/') ? path.slice(1) : path;
+    return `${MERCHI_BASE}/${trimmed}`;
+}

package/dist/helpers/gridQuote.d.ts

@@ -0,0 +1,10 @@
+import { JobJson } from '../types/job';
+import { VariationsGroupJson } from '../types/variation';
+/** Find the quoted variationsGroup row for a grid option (single group field). */
+export declare function quoteGroupForOption(quote: JobJson | null | undefined, groupFieldId: number, optionId: number): VariationsGroupJson | undefined;
+export interface InventoryStatusText {
+    tone: 'ok' | 'warn' | 'error';
+    label: string;
+}
+/** Human-readable inventory pill text (mirrors @merchi/product-form). */
+export declare function inventoryStatusText(group: VariationsGroupJson | undefined, needsInventory: boolean): InventoryStatusText | null;

package/dist/helpers/gridQuote.js

@@ -0,0 +1,32 @@
+function variationFieldId(variationField) {
+    if (variationField === undefined || variationField === null)
+        return undefined;
+    if (typeof variationField === 'number')
+        return variationField;
+    if (typeof variationField === 'object')
+        return variationField.id;
+    return undefined;
+}
+/** Find the quoted variationsGroup row for a grid option (single group field). */
+export function quoteGroupForOption(quote, groupFieldId, optionId) {
+    if (!quote?.variationsGroups?.length)
+        return undefined;
+    const optionKey = String(optionId);
+    return quote.variationsGroups.find((group) => (group.variations || []).some((variation) => {
+        const fieldId = variationFieldId(variation.variationField);
+        return fieldId === groupFieldId && String(variation.value ?? '') === optionKey;
+    }));
+}
+/** Human-readable inventory pill text (mirrors @merchi/product-form). */
+export function inventoryStatusText(group, needsInventory) {
+    if (!needsInventory || !group)
+        return null;
+    if (group.inventorySufficient !== false) {
+        return { tone: 'ok', label: 'In stock' };
+    }
+    const count = group.inventoryCount ?? 0;
+    if (count > 0) {
+        return { tone: 'warn', label: `Insufficient stock (${count} in stock)` };
+    }
+    return { tone: 'error', label: 'Out of stock' };
+}

package/dist/helpers/product.d.ts

@@ -0,0 +1,7 @@
+import { ProductJson } from '../types/product';
+import { VariationFieldJson } from '../types/variation';
+export declare function groupFieldsOf(product: ProductJson): VariationFieldJson[];
+export declare function independentFieldsOf(product: ProductJson): VariationFieldJson[];
+export declare function productHasGroups(product: ProductJson): boolean;
+/** One group field with selectable options — use OptionQuantityGrid (per-option qty). */
+export declare function isOptionQuantityGridProduct(product: ProductJson): boolean;

package/dist/helpers/product.js

@@ -0,0 +1,27 @@
+import { OPTION_FIELD_TYPES } from './constants';
+export function groupFieldsOf(product) {
+    const fields = product
+        .groupVariationFields;
+    return Array.isArray(fields) ? fields : [];
+}
+export function independentFieldsOf(product) {
+    const fields = product
+        .independentVariationFields;
+    return Array.isArray(fields) ? fields : [];
+}
+export function productHasGroups(product) {
+    return groupFieldsOf(product).length > 0;
+}
+/** One group field with selectable options — use OptionQuantityGrid (per-option qty). */
+export function isOptionQuantityGridProduct(product) {
+    const groups = groupFieldsOf(product);
+    if (groups.length !== 1)
+        return false;
+    const field = groups[0];
+    if (field?.id === undefined)
+        return false;
+    const fieldType = Number(field.fieldType);
+    if (!OPTION_FIELD_TYPES.has(fieldType) || fieldType === 6)
+        return false;
+    return (field.options || []).some((o) => o?.id !== undefined);
+}

package/dist/helpers/serialize.d.ts

@@ -0,0 +1,9 @@
+import { JobJson } from '../types/job';
+import { VariationsGroupJson } from '../types/variation';
+/** Return a deep-ish copy of the job with variations/groups cleaned for the API:
+ * form-only fields removed, zero-quantity groups dropped, and each remaining
+ * group's quantity defaulted to 0 when missing. Does not mutate the input
+ * (unlike @merchi/product-form's in-place cleaner). */
+export declare function serializeJob(job: JobJson): JobJson;
+/** Keep only groups whose quantity is greater than zero. */
+export declare function nonEmptyGroups(groups: VariationsGroupJson[]): VariationsGroupJson[];

package/dist/helpers/serialize.js

@@ -0,0 +1,35 @@
+const FORM_ONLY_VARIATION_KEYS = ['id', 'variationArrayFieldId', 'json', 'groupId'];
+function cleanVariation(variation) {
+    const copy = { ...variation };
+    for (const key of FORM_ONLY_VARIATION_KEYS) {
+        delete copy[key];
+    }
+    return copy;
+}
+/** Return a deep-ish copy of the job with variations/groups cleaned for the API:
+ * form-only fields removed, zero-quantity groups dropped, and each remaining
+ * group's quantity defaulted to 0 when missing. Does not mutate the input
+ * (unlike @merchi/product-form's in-place cleaner). */
+export function serializeJob(job) {
+    const out = { ...job };
+    if (Array.isArray(job.variations)) {
+        out.variations = job.variations.map(cleanVariation);
+    }
+    if (Array.isArray(job.variationsGroups)) {
+        out.variationsGroups = nonEmptyGroups(job.variationsGroups.map((group) => {
+            const cleaned = {
+                ...group,
+                quantity: group.quantity ?? 0,
+            };
+            if (Array.isArray(group.variations)) {
+                cleaned.variations = group.variations.map(cleanVariation);
+            }
+            return cleaned;
+        }));
+    }
+    return out;
+}
+/** Keep only groups whose quantity is greater than zero. */
+export function nonEmptyGroups(groups) {
+    return groups.filter((g) => (g.quantity ?? 0) > 0);
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { SDK_VERSION, getProductFormSdkVersion } from './version';
+export type { OptionJson, VariationFieldJson, VariationJson, VariationsGroupJson } from './types/variation';
+export type { ProductJson } from './types/product';
+export type { JobJson, QuoteFields } from './types/job';
+export type { ProductFormProps, ProductFormComponent } from './types/form';
+export { serializeJob, nonEmptyGroups } from './helpers/serialize';
+export { formatCurrency, urlFor } from './helpers/format';
+export { productHasGroups, groupFieldsOf, independentFieldsOf, isOptionQuantityGridProduct, } from './helpers/product';
+export { buildProductFormJob, jobToFormState, selectionsToVariations, } from './helpers/buildJob';
+export type { GroupRow, HydratedProductFormState, ProductFormJobState, } from './helpers/buildJob';
+export { OPTION_FIELD_TYPES, COLOUR_EXTRACT, FILE_FIELD_TYPES, AREA, } from './helpers/constants';
+export { createPricing } from './runtime/pricing';
+export type { Pricing } from './runtime/pricing';
+export { createProductFormRuntime } from './runtime/runtime';
+export type { Actions, Helpers, ProductFormRuntime, ProductFormRuntimeConfig, } from './runtime/runtime';
+export { Section, Stack, Card, Heading, Text, Divider, Field, GroupRows, OptionQuantityGrid, ProductFormProvider, ProductFormShell, ProductFormActions, useProductForm, theme, } from './components';
+export type { ProductFormContextValue, ProductFormProviderProps, FieldSelection, SubmitAction, FooterAction, } from './components';

package/dist/index.js

@@ -0,0 +1,11 @@
+export { SDK_VERSION, getProductFormSdkVersion } from './version';
+export { serializeJob, nonEmptyGroups } from './helpers/serialize';
+export { formatCurrency, urlFor } from './helpers/format';
+export { productHasGroups, groupFieldsOf, independentFieldsOf, isOptionQuantityGridProduct, } from './helpers/product';
+export { buildProductFormJob, jobToFormState, selectionsToVariations, } from './helpers/buildJob';
+export { OPTION_FIELD_TYPES, COLOUR_EXTRACT, FILE_FIELD_TYPES, AREA, } from './helpers/constants';
+export { createPricing } from './runtime/pricing';
+export { createProductFormRuntime } from './runtime/runtime';
+// UI component kit — the building blocks AI-built forms compose. Form authors
+// import these from '@merchi/product-form-sdk' (the static gate allowlists it).
+export { Section, Stack, Card, Heading, Text, Divider, Field, GroupRows, OptionQuantityGrid, ProductFormProvider, ProductFormShell, ProductFormActions, useProductForm, theme, } from './components';

package/dist/runtime/clientPricing.d.ts

@@ -0,0 +1,31 @@
+import { JobJson } from '../types/job';
+interface FieldSelection {
+    selectedOptionIds?: number[];
+    value?: string | number | null;
+}
+interface Selections {
+    quantity?: number;
+    fieldValues: Record<number, FieldSelection>;
+    groups?: {
+        quantity: number;
+        fieldValues: Record<number, FieldSelection>;
+    }[];
+}
+interface PricingField {
+    id: number;
+    isSelectable: boolean;
+}
+export interface PricingRules {
+    fields: PricingField[];
+    groupFields: PricingField[];
+    hasGroups: boolean;
+}
+/** Convert a job's form values into the `Selections` shape estimateQuote needs.
+ * Ported from @merchi/product-form's selections helper so a custom form gets
+ * identical client-side pricing behaviour. */
+export declare function toSelections(job: JobJson, rules: PricingRules): Selections;
+/** Compute a quote entirely client-side from pricing rules and merge the pricing
+ * fields into the job. Returns the priced job, or null when client-side pricing
+ * is unsupported for these rules (caller then falls back to a server quote). */
+export declare function clientQuote(rules: PricingRules, job: JobJson): JobJson | null;
+export {};

package/dist/runtime/clientPricing.js

@@ -0,0 +1,70 @@
+import { pricing } from '@merchi/sdk';
+function parseOptionIds(value) {
+    if (value === undefined || value === null || value === '')
+        return [];
+    return String(value)
+        .split(',')
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => !isNaN(n));
+}
+function buildFieldValues(variations, selectableByField) {
+    const out = {};
+    for (const variation of variations || []) {
+        const field = variation && variation.variationField;
+        const fieldId = typeof field === 'object' && field !== null ? field.id : field;
+        if (fieldId === undefined || fieldId === null)
+            continue;
+        if (selectableByField[fieldId]) {
+            out[fieldId] = { selectedOptionIds: parseOptionIds(variation.value) };
+        }
+        else {
+            out[fieldId] = { value: variation.value ?? null };
+        }
+    }
+    return out;
+}
+/** Convert a job's form values into the `Selections` shape estimateQuote needs.
+ * Ported from @merchi/product-form's selections helper so a custom form gets
+ * identical client-side pricing behaviour. */
+export function toSelections(job, rules) {
+    const selectableByField = {};
+    for (const f of [...(rules.fields || []), ...(rules.groupFields || [])]) {
+        selectableByField[f.id] = f.isSelectable;
+    }
+    if (rules.hasGroups) {
+        return {
+            fieldValues: buildFieldValues(job.variations || [], selectableByField),
+            groups: (job.variationsGroups || []).map((g) => ({
+                quantity: g.quantity || 0,
+                fieldValues: buildFieldValues(g.variations || [], selectableByField),
+            })),
+        };
+    }
+    return {
+        quantity: job.quantity || 0,
+        fieldValues: buildFieldValues(job.variations || [], selectableByField),
+    };
+}
+/** Compute a quote entirely client-side from pricing rules and merge the pricing
+ * fields into the job. Returns the priced job, or null when client-side pricing
+ * is unsupported for these rules (caller then falls back to a server quote). */
+export function clientQuote(rules, job) {
+    const result = pricing.estimateQuote(rules, toSelections(job, rules));
+    if (!result || result.unsupported)
+        return null;
+    const next = {
+        ...job,
+        cost: result.cost,
+        costPerUnit: result.costPerUnit,
+        taxAmount: result.taxAmount,
+        totalCost: result.totalCost,
+        currency: result.currency,
+    };
+    if (Array.isArray(job.variationsGroups) && Array.isArray(result.groupCosts)) {
+        next.variationsGroups = job.variationsGroups.map((g, i) => ({
+            ...g,
+            groupCost: result.groupCosts[i],
+        }));
+    }
+    return next;
+}

package/dist/runtime/pricing.d.ts

@@ -0,0 +1,29 @@
+import { JobJson } from '../types/job';
+import { ProductJson } from '../types/product';
+export interface Pricing {
+    /** Request a quote for the given job; resolves to the job json with pricing
+     * fields (cost, totalCost, currency, ...) populated. Uses client-side
+     * calculation when the product supports it, else a server quote. */
+    getQuote: (job: JobJson) => Promise<JobJson>;
+    /** Eagerly fetch + cache the client-side pricing rules (no-op unless the
+     * product has clientSideCalculation). Safe to call fire-and-forget on mount so
+     * the first quote is instant. */
+    warm: () => void;
+}
+export interface PricingOptions {
+    /** The product being quoted. Its `id` is used as the default product on the
+     * job, and `clientSideCalculation` enables the local pricing path. */
+    product?: ProductJson;
+    /** Pre-fetched pricing rules; if omitted and client-side is enabled, the rules
+     * are lazily fetched from `products/{id}/pricing-rules/`. */
+    pricingRules?: unknown;
+}
+/** Build a pricing helper bound to a backend api url.
+ *
+ * When `product.clientSideCalculation` is set, getQuote computes the quote
+ * locally via @merchi/sdk's pricing engine (mirroring @merchi/product-form),
+ * fetching the product's pricing-rules bundle once and caching it. It falls back
+ * to a server quote (`Job.getQuote` → /specialised-order-estimate/) when
+ * client-side is disabled, the rules can't be loaded, or the rules are
+ * unsupported for the given selections. */
+export declare function createPricing(apiUrl: string, options?: PricingOptions): Pricing;

package/dist/runtime/pricing.js

@@ -0,0 +1,70 @@
+import { Merchi } from '@merchi/sdk';
+import { serializeJob } from '../helpers/serialize';
+import { clientQuote } from './clientPricing';
+/** Build a pricing helper bound to a backend api url.
+ *
+ * When `product.clientSideCalculation` is set, getQuote computes the quote
+ * locally via @merchi/sdk's pricing engine (mirroring @merchi/product-form),
+ * fetching the product's pricing-rules bundle once and caching it. It falls back
+ * to a server quote (`Job.getQuote` → /specialised-order-estimate/) when
+ * client-side is disabled, the rules can't be loaded, or the rules are
+ * unsupported for the given selections. */
+export function createPricing(apiUrl, options = {}) {
+    const { product, pricingRules: providedRules } = options;
+    const defaultProductId = product && product.id;
+    const merchi = new Merchi(undefined, undefined, undefined, undefined, apiUrl);
+    let rulesCache = providedRules || null;
+    let rulesFetchAttempted = false;
+    async function getRules() {
+        if (rulesCache)
+            return rulesCache;
+        if (rulesFetchAttempted || !product || product.id === undefined)
+            return null;
+        rulesFetchAttempted = true;
+        try {
+            const base = apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`;
+            const res = await fetch(`${base}products/${product.id}/pricing-rules/`, {
+                credentials: 'omit',
+            });
+            if (!res.ok)
+                return null;
+            rulesCache = (await res.json());
+            return rulesCache;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function serverQuote(job) {
+        const withProduct = job.product && job.product.id !== undefined
+            ? job
+            : { ...job, product: { id: defaultProductId } };
+        const cleaned = serializeJob(withProduct);
+        const merchiJob = new merchi.Job();
+        merchiJob.fromJson(cleaned, {
+            makeDirty: false,
+            arrayValueStrict: false,
+        });
+        const quoted = await merchiJob.getQuote();
+        return quoted.toJson();
+    }
+    return {
+        warm: () => {
+            if (product && product.clientSideCalculation) {
+                // fire-and-forget: populate the cache so the first quote is instant.
+                void getRules();
+            }
+        },
+        getQuote: async (job) => {
+            if (product && product.clientSideCalculation) {
+                const rules = await getRules();
+                if (rules) {
+                    const local = clientQuote(rules, job);
+                    if (local)
+                        return local;
+                }
+            }
+            return serverQuote(job);
+        },
+    };
+}

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,36 @@
+import { ProductJson } from '../types/product';
+import { JobJson } from '../types/job';
+import { Pricing } from './pricing';
+import { serializeJob, nonEmptyGroups } from '../helpers/serialize';
+import { formatCurrency, urlFor } from '../helpers/format';
+export interface Actions {
+    addToCart?: (job: JobJson) => void;
+    buyNow?: (job: JobJson) => void;
+    getQuote?: (job: JobJson) => void;
+}
+export interface Helpers {
+    serializeJob: typeof serializeJob;
+    nonEmptyGroups: typeof nonEmptyGroups;
+    formatCurrency: typeof formatCurrency;
+    urlFor: typeof urlFor;
+}
+export interface ProductFormRuntimeConfig {
+    apiUrl: string;
+    product: ProductJson;
+    /** Pre-fetched pricing rules (optional). When omitted and the product has
+     * clientSideCalculation set, the rules are fetched lazily on first quote. */
+    pricingRules?: unknown;
+    onAddToCart?: (job: JobJson) => void;
+    onBuyNow?: (job: JobJson) => void;
+    onGetQuote?: (job: JobJson) => void;
+}
+export interface ProductFormRuntime {
+    pricing: Pricing;
+    actions: Actions;
+    helpers: Helpers;
+}
+/** Build the runtime (pricing + actions + helpers) the embed passes into a
+ * custom form. Each action quotes the job first, then invokes the host callback
+ * (matching @merchi/product-form's provider behaviour). An action is omitted when
+ * its callback is not supplied. */
+export declare function createProductFormRuntime(config: ProductFormRuntimeConfig): ProductFormRuntime;

package/dist/runtime/runtime.js

@@ -0,0 +1,32 @@
+import { createPricing } from './pricing';
+import { serializeJob, nonEmptyGroups } from '../helpers/serialize';
+import { formatCurrency, urlFor } from '../helpers/format';
+/** Build the runtime (pricing + actions + helpers) the embed passes into a
+ * custom form. Each action quotes the job first, then invokes the host callback
+ * (matching @merchi/product-form's provider behaviour). An action is omitted when
+ * its callback is not supplied. */
+export function createProductFormRuntime(config) {
+    const pricing = createPricing(config.apiUrl, {
+        product: config.product,
+        pricingRules: config.pricingRules,
+    });
+    // Warm client-side pricing rules in the background so the first quote is
+    // instant (no-op for products without clientSideCalculation).
+    pricing.warm();
+    const helpers = { serializeJob, nonEmptyGroups, formatCurrency, urlFor };
+    const quoteThen = (cb) => cb
+        ? async (job) => {
+            const quoted = await pricing.getQuote(job);
+            if (!quoted.product) {
+                quoted.product = { id: config.product.id };
+            }
+            cb(quoted);
+        }
+        : undefined;
+    const actions = {
+        addToCart: quoteThen(config.onAddToCart),
+        buyNow: quoteThen(config.onBuyNow),
+        getQuote: quoteThen(config.onGetQuote),
+    };
+    return { pricing, actions, helpers };
+}