@asstio-dev/storefront 0.6.0 → 0.9.2

package/dist/checkout/server.js

@@ -0,0 +1,68 @@
+import { localProblem, retryAfterSeconds } from "./types.js";
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** `POST /v1/checkout`: creates the cart's attempt or converges on the live one (spec §5.3). Call it from a Server Action or route handler, never during render. */
+export async function startCheckout(client, cartToken, opts = {}) {
+    const { data, error, response } = await client.POST("/v1/checkout", {
+        body: { option: opts.option ?? null, returnOrigin: opts.returnOrigin ?? null },
+        headers: { "X-Cart-Token": cartToken },
+    });
+    const retryAfter = retryAfterSeconds(response);
+    if (error || !data)
+        return { ok: false, status: response.status, problem: (error ?? localProblem("SDK_EMPTY_ANSWER", "no body")), retryAfter };
+    return { ok: true, data, retryAfter };
+}
+/** The same `POST /v1/checkout`, retrying `CHECKOUT_IN_PROGRESS` per `Retry-After`, twice (spec §10.3) — or
+ * `retries` times; `{ retries: 0 }` is the single-attempt call to put behind `mountCheckout` *(plan review 3 #5)*.
+ * Never repeats a cart mutation: it only syncs. */
+export async function syncCheckout(client, cartToken, opts = {}, retry = {}) {
+    const sleep = retry.sleep ?? defaultSleep;
+    const retries = retry.retries ?? 2; // *(plan review 3 #5)*
+    let result = await startCheckout(client, cartToken, opts);
+    for (let attempt = 0; attempt < retries && !result.ok && result.problem.code === "CHECKOUT_IN_PROGRESS"; attempt++) {
+        await sleep((result.retryAfter ?? 1) * 1000);
+        result = await startCheckout(client, cartToken, opts);
+    }
+    return result;
+}
+/** `POST /v1/checkout/{attemptId}/complete`: the confirmation page's call; with the cart token the answer carries the order's access token (spec §8.3). */
+export async function completeCheckout(client, attemptId, cartToken) {
+    const { data, error, response } = await client.POST("/v1/checkout/{attemptId}/complete", {
+        params: { path: { attemptId } },
+        headers: cartToken ? { "X-Cart-Token": cartToken } : {},
+    });
+    if (error || !data)
+        return { ok: false, status: response.status, problem: (error ?? localProblem("SDK_EMPTY_ANSWER", "no body")), retryAfter: retryAfterSeconds(response) };
+    return { ok: true, data };
+}
+/** `GET /v1/checkout/{attemptId}`: the non-mutating status read the browser module polls with. */
+export async function getCheckoutStatus(client, attemptId, cartToken) {
+    const { data, error, response } = await client.GET("/v1/checkout/{attemptId}", { params: { path: { attemptId } }, headers: { "X-Cart-Token": cartToken } });
+    if (error || !data)
+        return { ok: false, status: response.status, problem: (error ?? localProblem("SDK_EMPTY_ANSWER", "no body")), retryAfter: retryAfterSeconds(response) };
+    return { ok: true, data };
+}
+/** `GET /v1/orders/{orderId}` with `X-Order-Token` — a header only, never a query string (spec §8.3). */
+export async function getOrder(client, orderId, token) {
+    const { data, error, response } = await client.GET("/v1/orders/{orderId}", { params: { path: { orderId } }, headers: { "X-Order-Token": token } });
+    if (error || !data)
+        return { ok: false, status: response.status, problem: (error ?? localProblem("SDK_EMPTY_ANSWER", "no body")) };
+    return { ok: true, data };
+}
+const FINAL = new Set(["completed", "pending", "declined", "expired"]);
+/** Polls `complete` with doubling backoff until the attempt has an order or is closed, or the timeout passes (the last answer is returned either way). */
+export async function awaitCompletion(complete, opts = {}) {
+    const first = opts.firstDelayMs ?? 1000;
+    const max = opts.maxDelayMs ?? 10_000;
+    const timeout = opts.timeoutMs ?? 120_000;
+    const sleep = opts.sleep ?? defaultSleep;
+    let delay = first;
+    let waited = 0;
+    let last = await complete();
+    while (last.ok && !FINAL.has(last.data.status) && waited + delay <= timeout) {
+        await sleep(delay);
+        waited += delay;
+        delay = Math.min(delay * 2, max);
+        last = await complete();
+    }
+    return last;
+}

package/dist/checkout/types.d.ts

@@ -0,0 +1,42 @@
+import type { components } from "../schema";
+export type CheckoutDto = components["schemas"]["CheckoutDto"];
+export type CheckoutStatusDto = components["schemas"]["CheckoutStatusDto"];
+export type CheckoutOrderRefDto = components["schemas"]["CheckoutOrderRefDto"];
+export type CheckoutWidgetDto = components["schemas"]["CheckoutWidgetDto"];
+export type OrderDto = components["schemas"]["OrderDto"];
+export type StartCheckoutRequest = components["schemas"]["StartCheckoutRequest"];
+/** The problem body; `cart` is the corrected cart on 409 CHECKOUT_CART_CHANGED (an extension, so it is typed loosely here). */
+export type StorefrontProblem = components["schemas"]["StorefrontProblem"] & {
+    cart?: unknown;
+};
+export type CheckoutResult = {
+    ok: true;
+    data: CheckoutDto;
+    retryAfter?: number;
+} | {
+    ok: false;
+    status: number;
+    problem: StorefrontProblem;
+    retryAfter?: number;
+};
+export type StatusResult = {
+    ok: true;
+    data: CheckoutStatusDto;
+} | {
+    ok: false;
+    status: number;
+    problem: StorefrontProblem;
+    retryAfter?: number;
+};
+export type OrderResult = {
+    ok: true;
+    data: OrderDto;
+} | {
+    ok: false;
+    status: number;
+    problem: StorefrontProblem;
+};
+/** `Retry-After` in seconds: a delay, or an HTTP-date turned into one; garbage is 1 s, absence is undefined. */
+export declare function retryAfterSeconds(response: Response, now?: () => number): number | undefined;
+/** A problem shaped like the API's, for failures that never reached it (a thrown fetch, a timeout). */
+export declare function localProblem(code: string, detail: string): StorefrontProblem;

package/dist/checkout/types.js

@@ -0,0 +1,17 @@
+/** `Retry-After` in seconds: a delay, or an HTTP-date turned into one; garbage is 1 s, absence is undefined. */
+export function retryAfterSeconds(response, now = Date.now) {
+    const raw = response.headers.get("Retry-After");
+    if (raw === null || raw === "")
+        return undefined;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds))
+        return Math.max(0, Math.ceil(seconds));
+    const date = Date.parse(raw);
+    if (Number.isFinite(date))
+        return Math.max(0, Math.ceil((date - now()) / 1000));
+    return 1;
+}
+/** A problem shaped like the API's, for failures that never reached it (a thrown fetch, a timeout). */
+export function localProblem(code, detail) {
+    return { type: "https://docs.asstio.com/storefront/errors#" + code, title: code, status: 0, detail, code };
+}

package/dist/index.d.ts

@@ -46,4 +46,8 @@ export type FilterSelection = NonNullable<NonNullable<paths["/v1/products"]["get
  */
 export declare function filterQuery(selection: Record<string, string | string[] | undefined>): FilterSelection;
 export { decodeFilterValues, encodeFilterValues } from "./filters.js";
-export { fileUrl, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, srcSet, videoSources, type MediaConfig, type MediaDescriptor, type PictureSources, type VideoSource, } from "./media.js";
+export { coverOffset, fileUrl, fillFactor, formatFactor, formatImage, imageRect, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, scaledSizes, srcSet, styleToCss, videoSources, type FormatFit, type FormattedImage, type MediaConfig, type MediaDescriptor, type MediaFormat, type PictureSources, type SlotSize, type VideoSource, } from "./media.js";
+export { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, startCheckout, syncCheckout, type CheckoutClient, type StartCheckoutOptions, type SyncRetryOptions, type AwaitCompletionOptions } from "./checkout/server.js";
+export { retryAfterSeconds, type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type CheckoutStatusDto, type CheckoutWidgetDto, type OrderDto, type OrderResult, type StatusResult, type StorefrontProblem } from "./checkout/types.js";
+export { mountCheckout, type CheckoutHandle, type MountOptions, type MinimalDocument, type MinimalElement, type MinimalScript } from "./checkout/browser.js";
+export { controllers, type CheckoutController, type ProviderWindow } from "./checkout/controllers.js";

package/dist/index.js

@@ -35,4 +35,8 @@ export function filterQuery(selection) {
     return out;
 }
 export { decodeFilterValues, encodeFilterValues } from "./filters.js";
-export { fileUrl, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, srcSet, videoSources, } from "./media.js";
+export { coverOffset, fileUrl, fillFactor, formatFactor, formatImage, imageRect, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, scaledSizes, srcSet, styleToCss, videoSources, } from "./media.js";
+export { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, startCheckout, syncCheckout } from "./checkout/server.js"; // SyncRetryOptions *(plan review 3 #5)*
+export { retryAfterSeconds } from "./checkout/types.js";
+export { mountCheckout } from "./checkout/browser.js";
+export { controllers } from "./checkout/controllers.js";

package/dist/media.d.ts

@@ -49,3 +49,83 @@ export declare function posterUrl(site: MediaConfig, d: MediaDescriptor, width:
 export declare function fileUrl(site: MediaConfig, d: MediaDescriptor): string;
 /** Every encoded rendition of a video, for `<source>` elements. Empty for anything that is not a video. */
 export declare function videoSources(site: MediaConfig, d: MediaDescriptor): VideoSource[];
+export type FormatFit = "contain" | "cover" | "natural";
+/** One slot size of the frontend's layout (F6): `{ media: "(min-width: 1080px)", size: "25vw" }`; the last entry
+ *  has no media condition. The SDK turns these into the `sizes` attribute. */
+export type SlotSize = {
+    media?: string;
+    size: string;
+};
+/**
+ * The image's drawn width as a fraction of the slot (spec §6 rule 4). `rBox` = format W/H, `rImg` = image w/h,
+ * `padding` a fraction of the box's width (contain only).
+ */
+export declare function fillFactor(fit: FormatFit, rBox: number, rImg: number, padding: number): number;
+/**
+ * Where a cover image sits (spec §3.3): the fractions `ox`/`oy` of the overflow placed before the box, so the
+ * focal point is as centred as possible without showing an edge. Visible fraction `v = min(rBox/rImg, rImg/rBox)`;
+ * along the overflowing axis `clamp((f − v/2) / (1 − v), 0, 1)`, the other axis 0.5. Unset focal ⇒ centre.
+ */
+export declare function coverOffset(focal: {
+    x: number | string;
+    y: number | string;
+} | null | undefined, rBox: number, rImg: number): {
+    ox: number;
+    oy: number;
+};
+/**
+ * The rectangle the image occupies, in percent of the box (spec §6 rule 3): `width = fill·100`,
+ * `height = fill·rBox/rImg·100`; contain centred (the padding inset is inside `fill`), cover placed by
+ * `coverOffset` (negative offsets; the box clips), natural the whole box (its box has the image's aspect).
+ * The `<img>` and the placeholder both use it.
+ */
+export declare function imageRect(fit: FormatFit, rBox: number, rImg: number, fill: number, offset: {
+    ox: number;
+    oy: number;
+}): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/** `fill` with 4 significant digits: a positive factor never rounds to 0 (review 2 #12). */
+export declare function formatFactor(fill: number): string;
+/** The `sizes` attribute: every slot's size scaled by `fill` with `calc()`, unchanged when `fill` is 1 (F10). */
+export declare function scaledSizes(slots: SlotSize[], fill: number): string;
+export type MediaFormat = components["schemas"]["MediaFormatDto"];
+export type FormattedImage = {
+    /** The format key actually used, after fallback ("default" when the site has no formats). */
+    format: string;
+    /** The effective fit, after `showWhole`. */
+    fit: FormatFit;
+    /** The aspect frame's style (camelCase CSS): the slot's only child in every fit. For natural it takes the
+     *  image's own aspect and has no colour. */
+    box: Record<string, string>;
+    /** The `<img>` style: the image's rectangle in the box. */
+    img: Record<string, string>;
+    /** The placeholder layer's style (e.g. a blurhash canvas): the same rectangle as `img`. */
+    placeholder: Record<string, string>;
+    sources: {
+        type: string;
+        srcSet: string;
+        sizes: string;
+    }[];
+    fallback: {
+        src: string;
+        srcSet: string;
+        sizes: string;
+        width: number;
+        height: number;
+    };
+};
+/**
+ * A complete, standards-conforming `<picture>` for one descriptor in one of the site's formats (spec 2026-09-23 §6).
+ * Render: your **slot** element (your className, may be a flex/grid item) → `box` (the slot's only child, in every
+ * fit) → the placeholder layer and `<picture>` with `sources` and an `<img>` carrying `fallback` and `img`.
+ * `slots` describes your layout's widths for the slot (F6); the SDK scales them into `sizes`.
+ */
+export declare function formatImage(site: MediaConfig, d: MediaDescriptor, formatKey: string, slots: SlotSize[]): FormattedImage;
+/** A camelCase style object as a `style` attribute value, for plain HTML and templating engines. Meant for
+ *  `formatImage` output, whose values are SDK-generated or a server-validated `#rrggbb`: it does not escape, so
+ *  do not pass it values of your own that could hold `"`, `;` or `<`. */
+export declare function styleToCss(style: Record<string, string>): string;

package/dist/media.js

@@ -112,3 +112,145 @@ export function videoSources(site, d) {
         name: v.name,
     }));
 }
+/**
+ * The image's drawn width as a fraction of the slot (spec §6 rule 4). `rBox` = format W/H, `rImg` = image w/h,
+ * `padding` a fraction of the box's width (contain only).
+ */
+export function fillFactor(fit, rBox, rImg, padding) {
+    if (fit === "natural")
+        return 1;
+    if (fit === "cover")
+        return Math.max(1, rImg / rBox);
+    return Math.min(1 - 2 * padding, (1 / rBox - 2 * padding) * rImg);
+}
+/**
+ * Where a cover image sits (spec §3.3): the fractions `ox`/`oy` of the overflow placed before the box, so the
+ * focal point is as centred as possible without showing an edge. Visible fraction `v = min(rBox/rImg, rImg/rBox)`;
+ * along the overflowing axis `clamp((f − v/2) / (1 − v), 0, 1)`, the other axis 0.5. Unset focal ⇒ centre.
+ */
+export function coverOffset(focal, rBox, rImg) {
+    const v = Math.min(rBox / rImg, rImg / rBox);
+    if (v >= 1)
+        return { ox: 0.5, oy: 0.5 };
+    const pos = (f) => Math.min(1, Math.max(0, (f - v / 2) / (1 - v)));
+    const fx = focal == null ? 0.5 : toNumber(focal.x);
+    const fy = focal == null ? 0.5 : toNumber(focal.y);
+    return rImg > rBox ? { ox: pos(fx), oy: 0.5 } : { ox: 0.5, oy: pos(fy) };
+}
+/**
+ * The rectangle the image occupies, in percent of the box (spec §6 rule 3): `width = fill·100`,
+ * `height = fill·rBox/rImg·100`; contain centred (the padding inset is inside `fill`), cover placed by
+ * `coverOffset` (negative offsets; the box clips), natural the whole box (its box has the image's aspect).
+ * The `<img>` and the placeholder both use it.
+ */
+export function imageRect(fit, rBox, rImg, fill, offset) {
+    if (fit === "natural")
+        return { left: 0, top: 0, width: 100, height: 100 };
+    const width = fill * 100;
+    const height = ((fill * rBox) / rImg) * 100;
+    if (fit === "contain")
+        return { left: (100 - width) / 2, top: (100 - height) / 2, width, height };
+    return { left: offset.ox * (100 - width), top: offset.oy * (100 - height), width, height };
+}
+/** `fill` with 4 significant digits: a positive factor never rounds to 0 (review 2 #12). */
+export function formatFactor(fill) {
+    return String(Number(fill.toPrecision(4)));
+}
+/** The `sizes` attribute: every slot's size scaled by `fill` with `calc()`, unchanged when `fill` is 1 (F10). */
+export function scaledSizes(slots, fill) {
+    if (slots.length === 0)
+        throw new MediaUrlError("formatImage: slots must not be empty");
+    return slots
+        .map((s) => {
+        const size = fill === 1 ? s.size : `calc(${s.size} * ${formatFactor(fill)})`;
+        return s.media ? `${s.media} ${size}` : size;
+    })
+        .join(", ");
+}
+const NATURAL = { aspect: null, fit: "natural", padding: 0, background: null };
+const pct = (v) => `${Number(v.toFixed(4))}%`;
+/** Rule 1: `formats[key] ?? formats.default ?? natural`. Own-property lookups: a key like "constructor" must fall
+ *  through to `default`/natural, never resolve on `Object.prototype`. */
+function resolveFormat(site, key) {
+    const formats = site.formats ?? null;
+    if (formats && Object.hasOwn(formats, key))
+        return { key, format: formats[key] };
+    if (formats && Object.hasOwn(formats, "default"))
+        return { key: "default", format: formats.default };
+    return { key: "default", format: NATURAL };
+}
+function parseAspect(aspect, key) {
+    const m = aspect == null ? null : /^(\d{1,3})\/(\d{1,3})$/.exec(aspect);
+    if (!m)
+        throw new MediaUrlError(`formatImage: format '${key}' aspect '${aspect}' is not "W/H"`);
+    return { w: Number(m[1]), h: Number(m[2]) };
+}
+/**
+ * A complete, standards-conforming `<picture>` for one descriptor in one of the site's formats (spec 2026-09-23 §6).
+ * Render: your **slot** element (your className, may be a flex/grid item) → `box` (the slot's only child, in every
+ * fit) → the placeholder layer and `<picture>` with `sources` and an `<img>` carrying `fallback` and `img`.
+ * `slots` describes your layout's widths for the slot (F6); the SDK scales them into `sizes`.
+ */
+export function formatImage(site, d, formatKey, slots) {
+    if (d.kind !== "image")
+        throw new MediaUrlError(`formatImage: kind '${d.kind}' is not an image`);
+    requireImage(d, "formatImage");
+    if (d.w == null || d.h == null)
+        throw new MediaUrlError(`formatImage: descriptor ${d.id} has no w/h`);
+    const w = toNumber(d.w);
+    const h = toNumber(d.h);
+    const { key, format } = resolveFormat(site, formatKey);
+    const rawFit = format.fit;
+    // An unknown fit falls back to natural (spec §8), so `FormattedImage.fit` is always a real FormatFit.
+    let fit = rawFit === "contain" || rawFit === "cover" ? rawFit : "natural";
+    if (fit === "cover" && d.showWhole)
+        fit = "contain";
+    // Natural gets a box too (spec §6 rule 3): the descriptor's own aspect, no colour, the image fills it.
+    const a = fit === "natural" ? { w, h } : parseAspect(format.aspect, key);
+    const rBox = a.w / a.h;
+    const rImg = w / h;
+    const padding = fit === "contain" ? toNumber(format.padding) : 0;
+    const fill = fillFactor(fit, rBox, rImg, padding);
+    const rect = imageRect(fit, rBox, rImg, fill, coverOffset(d.focal, rBox, rImg));
+    const bgClass = d.bg ?? "default";
+    const bg = fit !== "natural" && format.background
+        ? Object.hasOwn(format.background, bgClass)
+            ? format.background[bgClass]
+            : Object.hasOwn(format.background, "default")
+                ? format.background.default
+                : null
+        : null;
+    const box = {
+        display: "block", position: "relative", overflow: "hidden", width: "100%", height: "auto", aspectRatio: `${a.w} / ${a.h}`,
+        minHeight: "0", maxHeight: "none", padding: "0", border: "0", boxSizing: "content-box",
+        alignSelf: "flex-start", justifySelf: "stretch", flex: "none",
+        ...(bg ? { backgroundColor: bg } : {}),
+    };
+    const layer = {
+        position: "absolute", left: pct(rect.left), top: pct(rect.top), width: pct(rect.width), height: pct(rect.height),
+        display: "block", objectFit: "fill",
+        // A global `img { max-width: 100%; height: auto }` reset must not shrink a cover rectangle wider than the box.
+        maxWidth: "none", maxHeight: "none", minWidth: "0", minHeight: "0", margin: "0", padding: "0", border: "0",
+    };
+    const sizes = scaledSizes(slots, fill);
+    // Same rendition logic as pictureSources (sources except the last format, middle-width fallback src): delegate
+    // rather than duplicate it; formatImage keeps the real w/h it already validated for the fallback dimensions.
+    const p = pictureSources(site, d, sizes);
+    return {
+        format: key,
+        fit,
+        box,
+        img: layer,
+        placeholder: { ...layer },
+        sources: p.sources,
+        fallback: { src: p.img.src, srcSet: p.img.srcSet, sizes, width: w, height: h },
+    };
+}
+/** A camelCase style object as a `style` attribute value, for plain HTML and templating engines. Meant for
+ *  `formatImage` output, whose values are SDK-generated or a server-validated `#rrggbb`: it does not escape, so
+ *  do not pass it values of your own that could hold `"`, `;` or `<`. */
+export function styleToCss(style) {
+    return Object.entries(style)
+        .map(([k, v]) => `${k.replace(/[A-Z]/g, (c) => "-" + c.toLowerCase())}: ${v}`)
+        .join("; ");
+}