@asstio-dev/storefront 0.2.0 → 0.5.0

package/README.md

@@ -55,6 +55,80 @@ const { data: page } = await storefront.GET("/v1/products/{slugOrId}/variants",
 Every example in this file is compiled as part of `npm run check` — the source of them is
 [`examples/readme.ts`](examples/readme.ts), which also covers product lookup, ETag revalidation and crawling.
 
+### Images
+
+Products, cards, variants and cart lines carry **media descriptors**, never URLs. Combine a descriptor with the
+`media` block of `/v1/site` to build `src`, `srcset` and `<picture>` sources. The helpers only ever produce a URL
+the CDN actually serves: a width and a format the descriptor announces, and the descriptor's own `recipe`.
+
+```ts
+import { pictureSources, fileUrl } from "@asstio-dev/storefront";
+
+const { data: site } = await storefront.GET("/v1/site");
+const { data: product } = await storefront.GET("/v1/products/{slugOrId}", { params: { path: { slugOrId: "acuvue-oasys" } } });
+
+if (site && product?.image) {
+  const { sources, img } = pictureSources(site.media, product.image, "(min-width: 900px) 33vw, 100vw");
+  // <picture>{sources.map(s => <source {...s} />)}<img {...img} alt={product.image.alt["sv"] ?? product.name} /></picture>
+}
+for (const file of product?.files ?? []) console.log(file.filename, fileUrl(site!.media, file));
+// A variant with hasOwnImages: false inherits: variant.hasOwnImages ? variant.images : product.images
+```
+
+`videoSources` returns `[]` for anything that is not a video, while `mediaUrl`/`pictureSources`/`fileUrl`/`posterUrl`
+throw `MediaUrlError` when the descriptor cannot produce that URL — branch on `kind` before calling.
+
+### Product content
+
+`description` is **already sanitized** on the server: render `description.html` as-is — do not sanitize, escape or
+re-parse it — and use `description.text` wherever you need plain text (a meta description, a snippet, an
+`aria-label`). `shortDescription` is plain text. `brand.facet` is set when the brand shares a facet's source, so it
+can link straight to a filtered listing; when it is `null`, render `brand.label` as plain text and never guess a
+filter.
+
+`attributes[]` arrives ordered and labelled for display. Branch on `type` (`text` | `html` | `number` | `bool` |
+`list`): a list fills `values`, everything else fills `value`, and `html` fills `html` too — sanitized exactly like
+`description.html`.
+
+```ts
+if (product.description) render(product.description.html); // as-is: sanitized server-side
+for (const a of product.attributes) {
+  if (a.type === "html") render(a.html!);          // sanitized like description.html
+  else if (a.values) render(a.values.join(", "));  // type: "list"
+  else render(a.value!);                           // text | number | bool
+}
+```
+
+`facetKey` and `valueKeys` turn an attribute's values into filter links — `filter[facetKey]=valueKeys[i]`, aligned
+index-for-index with `values` (or carrying the single `value`'s key). `valueKeys` is absent entirely when any one
+value has no key of its own: a list is either fully linkable or not linkable at all.
+
+`related[]` holds groups of cards already resolved for this market, and `bundle.components[]` the cards a bundle is
+made of; both leave out anything that no longer exists or is not sold here.
+
+### Search-as-you-type and search-in-facet
+
+`/v1/search/suggest` answers three short lists for what the shopper has typed so far: up to 5 product cards
+(matched on the product name), 5 categories (each with the `path` to show above it) and 10 values from the facets
+whose panel is searchable. `q` is required and 1–100 characters — blank, missing or longer is a 400
+(`INVALID_QUERY`), not a truncation the way a listing's `q` is.
+
+`/v1/products/facets/{key}` is the search box inside one facet panel: the facet's values with the counts they have
+in the same `filter[…]` context the listing is showing, so a count is what selecting that value would leave. Send
+the panel's own filters with it, and omit `q` for the values as they are.
+
+```ts
+const { data: suggestions } = await storefront.GET("/v1/search/suggest", { params: { query: { q: typed } } });
+const { data: brands } = await storefront.GET("/v1/products/facets/{key}", {
+  params: { path: { key: "varumarke" }, query: { q: typed, filter: filterQuery({ kon: ["dam"] }) } },
+});
+```
+
+The endpoint reads the facet's **1000 most common values** and matches `q` against those — label contains,
+case-insensitively, or key prefix — returning at most 50. A facet with more distinct values than that is searched
+over its top 1000; no regular expression ever reaches the search index. `key` has to be a `list` or `swatch` facet:
+an unknown key is `FACET_NOT_FOUND` (404), and a range or toggle facet is `FACET_NOT_SEARCHABLE` (400).
+
 ## Headers
 
 Every call the client makes carries these; you never set them by hand.
@@ -95,7 +169,8 @@ Every operation documents `400`, `401`, `403`, `404`, `429` and `503`; the entit
 Codes you will meet: `SITE_KEY_MISSING`, `SITE_KEY_INVALID`, `SITE_INACTIVE`, `SECRET_KEY_FROM_BROWSER`,
 `SITE_REGISTRY_WARMING`, `MARKET_UNKNOWN`, `RATE_LIMITED` (with `retryAfterSeconds`, plus a `Retry-After`
 header), `PRODUCT_NOT_FOUND`, `COLLECTION_NOT_FOUND`, `INVALID_PAGE`, `INVALID_SINCE`, `INVALID_TYPE`,
-`INDEX_UNAVAILABLE` (retry — a preview index is being rebuilt), `NOT_FOUND`.
+`INDEX_UNAVAILABLE` (retry — a preview index is being rebuilt), `NOT_FOUND`, `INVALID_QUERY`,
+`FACET_NOT_FOUND`, `FACET_NOT_SEARCHABLE`.
 
 `SITE_REGISTRY_WARMING` and `INDEX_UNAVAILABLE` are retries, not bugs in your call.
 
@@ -120,6 +195,9 @@ form the API reads. `filterQuery()` is a thin helper that joins multi-select val
 `/v1/sitemap` takes `type` (`product` | `collection`), `since` (ISO-8601, inclusive), `page` and `pageSize`
 (max 1000, default 500).
 
+`/v1/search/suggest` takes `q` only, and `/v1/products/facets/{key}` takes `q` plus the same `filter` object as a
+listing — both are described under [Search-as-you-type and search-in-facet](#search-as-you-type-and-search-in-facet).
+
 ## Caching
 
 Read responses carry an `ETag` and `Vary: X-Site-Key, X-Market, Accept-Language` — the answer depends on

package/dist/index.d.ts

@@ -44,3 +44,4 @@ export type FilterSelection = NonNullable<NonNullable<paths["/v1/products"]["get
  * The client sends it as `filter[brand]=dior,chanel` (deepObject), which is what the API reads.
  */
 export declare function filterQuery(selection: Record<string, string | string[] | undefined>): FilterSelection;
+export { fileUrl, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, srcSet, videoSources, type MediaConfig, type MediaDescriptor, type PictureSources, type VideoSource, } from "./media.js";

package/dist/index.js

@@ -32,3 +32,4 @@ export function filterQuery(selection) {
     }
     return out;
 }
+export { fileUrl, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, srcSet, videoSources, } from "./media.js";

package/dist/media.d.ts

@@ -0,0 +1,51 @@
+import type { components } from "./schema";
+export type MediaDescriptor = components["schemas"]["MediaDescriptorDto"];
+export type MediaConfig = components["schemas"]["MediaDto"];
+export type PictureSources = {
+    sources: {
+        type: string;
+        srcSet: string;
+        sizes: string;
+    }[];
+    img: {
+        src: string;
+        srcSet: string;
+        sizes: string;
+        width?: number;
+        height?: number;
+    };
+};
+export type VideoSource = {
+    src: string;
+    type: string;
+    width: number;
+    height: number;
+    name: string;
+};
+/** A descriptor that cannot produce the URL asked for: wrong kind, a format or width it does not carry. */
+export declare class MediaUrlError extends Error {
+    constructor(message: string);
+}
+/** The descriptor id without its `sha256:` prefix — the `{hash}` of every template. */
+export declare function mediaHash(d: MediaDescriptor): string;
+/** The smallest rendition at or above `width`, else the largest — only ever a width the descriptor announces. */
+export declare function pickWidth(d: MediaDescriptor, width: number): number;
+/** One image URL. `format` defaults to the last one announced (jpg, or gif for an animated GIF). */
+export declare function mediaUrl(site: MediaConfig, d: MediaDescriptor, opts: {
+    width: number;
+    format?: string;
+}): string;
+/** `srcset` over every actual width of one format. */
+export declare function srcSet(site: MediaConfig, d: MediaDescriptor, format: string): string;
+/**
+ * Everything a `<picture>` needs: one `<source>` per format except the last (avif first, as the feed lists it),
+ * and the `<img>` in the last format with the middle width as `src`. One format ⇒ no sources, only the img (T15).
+ * `sizes` is mandatory — without it the browser picks the largest candidate.
+ */
+export declare function pictureSources(site: MediaConfig, d: MediaDescriptor, sizes: string): PictureSources;
+/** Poster (video, PDF, animated GIF): the poster template over `poster.widths`; always avif. */
+export declare function posterUrl(site: MediaConfig, d: MediaDescriptor, width: number): string;
+/** The download itself: the file template plus the sanitized filename the descriptor carries. */
+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[];

package/dist/media.js

@@ -0,0 +1,114 @@
+/** A descriptor that cannot produce the URL asked for: wrong kind, a format or width it does not carry. */
+export class MediaUrlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MediaUrlError";
+    }
+}
+const MIME = {
+    avif: "image/avif", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", png: "image/png",
+    mp4: "video/mp4", webm: "video/webm",
+};
+const mime = (format) => MIME[format] ?? `application/octet-stream`;
+// `w`/`h`/`widths`/etc. are typed `number | string` in schema.d.ts (OpenAPI `format: int32` round-trips as
+// either on the wire); every arithmetic/comparison use below normalizes through this first.
+const toNumber = (v) => (typeof v === "number" ? v : Number(v));
+/** The descriptor id without its `sha256:` prefix — the `{hash}` of every template. */
+export function mediaHash(d) {
+    if (!d.id.startsWith("sha256:") || d.id.length !== 71)
+        throw new MediaUrlError(`media id '${d.id}' is not a sha256: descriptor id`);
+    return d.id.slice(7);
+}
+function fill(site, template, vars) {
+    const base = site.baseUrl.replace(/\/$/, "");
+    const path = template.replace(/\{(\w+)\}/g, (_, key) => {
+        const v = vars[key];
+        if (v === undefined)
+            throw new MediaUrlError(`template '${template}' needs '${key}'`);
+        return String(v);
+    });
+    return base + path;
+}
+function requireImage(d, what) {
+    // Branch on kind, never on emptiness: a file descriptor has widths: [] and formats: [] by contract.
+    if (d.kind !== "image" && d.kind !== "video")
+        throw new MediaUrlError(`${what}: kind '${d.kind}' has no image renditions; use fileUrl or posterUrl`);
+    if (d.widths.length === 0 || d.formats.length === 0)
+        throw new MediaUrlError(`${what}: descriptor ${d.id} announces no renditions`);
+}
+function pick(widths, width) {
+    const sorted = widths.map(toNumber).sort((a, b) => a - b);
+    return sorted.find((w) => w >= width) ?? sorted[sorted.length - 1];
+}
+/** The smallest rendition at or above `width`, else the largest — only ever a width the descriptor announces. */
+export function pickWidth(d, width) {
+    requireImage(d, "pickWidth");
+    return pick(d.widths, width);
+}
+function requireFormat(d, format) {
+    const f = format ?? d.formats[d.formats.length - 1];
+    if (!d.formats.includes(f))
+        throw new MediaUrlError(`format '${f}' is not one of ${d.formats.join(", ")} for ${d.id}`);
+    return f;
+}
+/** One image URL. `format` defaults to the last one announced (jpg, or gif for an animated GIF). */
+export function mediaUrl(site, d, opts) {
+    requireImage(d, "mediaUrl");
+    const format = requireFormat(d, opts.format);
+    return fill(site, site.templates.image, { hash: mediaHash(d), recipe: d.recipe, width: pick(d.widths, opts.width), format });
+}
+/** `srcset` over every actual width of one format. */
+export function srcSet(site, d, format) {
+    requireImage(d, "srcSet");
+    const f = requireFormat(d, format);
+    return d.widths
+        .map(toNumber)
+        .sort((a, b) => a - b)
+        .map((w) => `${fill(site, site.templates.image, { hash: mediaHash(d), recipe: d.recipe, width: w, format: f })} ${w}w`)
+        .join(", ");
+}
+/**
+ * Everything a `<picture>` needs: one `<source>` per format except the last (avif first, as the feed lists it),
+ * and the `<img>` in the last format with the middle width as `src`. One format ⇒ no sources, only the img (T15).
+ * `sizes` is mandatory — without it the browser picks the largest candidate.
+ */
+export function pictureSources(site, d, sizes) {
+    requireImage(d, "pictureSources");
+    const formats = d.formats;
+    const last = formats[formats.length - 1];
+    const widths = d.widths.map(toNumber).sort((a, b) => a - b);
+    return {
+        sources: formats.slice(0, -1).map((f) => ({ type: mime(f), srcSet: srcSet(site, d, f), sizes })),
+        img: {
+            src: mediaUrl(site, d, { width: widths[Math.floor(widths.length / 2)], format: last }),
+            srcSet: srcSet(site, d, last),
+            sizes,
+            width: d.w == null ? undefined : toNumber(d.w),
+            height: d.h == null ? undefined : toNumber(d.h),
+        },
+    };
+}
+/** Poster (video, PDF, animated GIF): the poster template over `poster.widths`; always avif. */
+export function posterUrl(site, d, width) {
+    if (!d.poster || d.poster.widths.length === 0)
+        throw new MediaUrlError(`posterUrl: descriptor ${d.id} has no poster`);
+    return fill(site, site.templates.poster, { hash: mediaHash(d), recipe: d.recipe, width: pick(d.poster.widths, width) });
+}
+/** The download itself: the file template plus the sanitized filename the descriptor carries. */
+export function fileUrl(site, d) {
+    if (d.kind !== "file" || !d.filename)
+        throw new MediaUrlError(`fileUrl: descriptor ${d.id} is not a file`);
+    return fill(site, site.templates.file, { hash: mediaHash(d), recipe: d.recipe, filename: d.filename });
+}
+/** Every encoded rendition of a video, for `<source>` elements. Empty for anything that is not a video. */
+export function videoSources(site, d) {
+    if (d.kind !== "video" || !d.variants)
+        return [];
+    return d.variants.map((v) => ({
+        src: fill(site, site.templates.video, { hash: mediaHash(d), recipe: d.recipe, variant: v.name, format: v.format }),
+        type: mime(v.format),
+        width: toNumber(v.w),
+        height: toNumber(v.h),
+        name: v.name,
+    }));
+}

package/dist/schema.d.ts

@@ -153,6 +153,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/products/facets/{key}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Search within a facet: values whose label matches q, counted in this request's filter[...] context (spelled as on /products). Free text and collections are not applied. */
+        get: operations["SearchFacetValues"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/products/{slugOrId}": {
         parameters: {
             query?: never;
@@ -187,6 +204,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/search/suggest": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Search-as-you-type: products by name prefix, categories and facet values whose label starts with q. Market, assortment and language as /products. */
+        get: operations["Suggest"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/site": {
         parameters: {
             query?: never;
@@ -235,6 +269,27 @@ export interface components {
             label: string;
             value: string;
         };
+        AttributeDto: {
+            facetKey: null | string;
+            html: null | string;
+            key: string;
+            label: string;
+            type: string;
+            value: null | string;
+            valueKeys: string[] | null;
+            values: string[] | null;
+        };
+        BrandDto: {
+            facet: null | components["schemas"]["FacetLinkDto"];
+            label: string;
+        };
+        BundleComponentDto: {
+            product: components["schemas"]["ProductCardDto"];
+            quantity: string;
+        };
+        BundleDto: {
+            components: components["schemas"]["BundleComponentDto"][];
+        };
         CartDto: {
             currency: string;
             grandTotalInc: string;
@@ -249,11 +304,24 @@ export interface components {
         };
         CartLineDto: {
             id: string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
             price: components["schemas"]["PriceDto"];
-            productId: string;
+            product: components["schemas"]["CartLineProductDto"];
             /** Format: int32 */
             quantity: number | string;
             sku: string;
+            variant: components["schemas"]["CartLineVariantDto"];
+        };
+        CartLineProductDto: {
+            id: string;
+            name: string;
+            slug: string;
+        };
+        CartLineVariantDto: {
+            id: string;
+            selectedOptions: {
+                [key: string]: string;
+            };
         };
         CategoryNodeDto: {
             children: components["schemas"]["CategoryNodeDto"][];
@@ -297,6 +365,10 @@ export interface components {
             slug: string;
             url: string;
         };
+        DescriptionDto: {
+            html: string;
+            text: string;
+        };
         FacetDto: {
             key: string;
             label: string;
@@ -307,6 +379,10 @@ export interface components {
             type: string;
             values: components["schemas"]["FacetValueDto"][];
         };
+        FacetLinkDto: {
+            key: string;
+            valueKey: string;
+        };
         FacetValueDto: {
             children: components["schemas"]["FacetValueDto"][] | null;
             /** Format: int64 */
@@ -317,6 +393,10 @@ export interface components {
             selected: boolean;
             swatch: null | components["schemas"]["SwatchDto"];
         };
+        FacetValuesResponse: {
+            facet: string;
+            values: components["schemas"]["FacetValueDto"][];
+        };
         ListingResponse: {
             appliedFilters: components["schemas"]["AppliedFilterDto"][];
             facets: components["schemas"]["FacetDto"][];
@@ -339,6 +419,68 @@ export interface components {
             language: string;
             urlTemplate: string;
         };
+        MediaDescriptorDto: {
+            alt: {
+                [key: string]: string;
+            };
+            /** @description Passed through opaque, exactly as Purchase wrote it (spec 2026-09-18 §3); no fixed shape. */
+            attributes: null | {
+                [key: string]: unknown;
+            };
+            bg: null | string;
+            blurhash: null | string;
+            /** Format: int64 */
+            bytes: number | null | string;
+            caption: null | {
+                [key: string]: string;
+            };
+            color: null | string;
+            /** Format: int32 */
+            duration: number | null | string;
+            filename: null | string;
+            formats: string[];
+            /** Format: int32 */
+            h: number | null | string;
+            id: string;
+            kind: string;
+            /** Format: int32 */
+            order: number | string;
+            /** Format: int32 */
+            pages: number | null | string;
+            poster: null | components["schemas"]["MediaPosterDto"];
+            /** Format: int32 */
+            recipe: number | string;
+            role: string;
+            variants: components["schemas"]["MediaVideoVariantDto"][] | null;
+            view: null | string;
+            /** Format: int32 */
+            w: number | null | string;
+            widths: (number | string)[];
+        };
+        MediaDto: {
+            baseUrl: string;
+            templates: components["schemas"]["MediaTemplatesDto"];
+        };
+        MediaPosterDto: {
+            formats: string[];
+            widths: (number | string)[];
+        };
+        MediaTemplatesDto: {
+            file: string;
+            image: string;
+            poster: string;
+            video: string;
+        };
+        MediaVideoVariantDto: {
+            /** Format: int64 */
+            bytes: number | string;
+            format: string;
+            /** Format: int32 */
+            h: number | string;
+            name: string;
+            /** Format: int32 */
+            w: number | string;
+        };
         OptionDto: {
             name: string;
             values: string[];
@@ -351,12 +493,15 @@ export interface components {
             vatRate: string;
         };
         ProductCardDto: {
+            brand: null | components["schemas"]["BrandDto"];
             collections: string[];
             id: string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
             inStock: boolean;
             name: string;
             price: null | components["schemas"]["PriceDto"];
             priceVaries: boolean;
+            shortDescription: null | string;
             sku: string;
             slug: string;
             /** Format: date-time */
@@ -367,14 +512,23 @@ export interface components {
             alternateUrls: {
                 [key: string]: string;
             };
+            attributes: components["schemas"]["AttributeDto"][];
+            brand: null | components["schemas"]["BrandDto"];
+            bundle: null | components["schemas"]["BundleDto"];
             categories: components["schemas"]["CategoryRefDto"][];
             collections: components["schemas"]["CollectionRefDto"][];
+            description: null | components["schemas"]["DescriptionDto"];
+            files: components["schemas"]["MediaDescriptorDto"][];
             id: string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
+            images: components["schemas"]["MediaDescriptorDto"][];
             matchedVariantId: null | string;
             name: string;
             options: components["schemas"]["OptionDto"][];
             redirectTo: null | string;
+            related: components["schemas"]["RelatedGroupDto"][];
             seo: components["schemas"]["SeoDto"];
+            shortDescription: null | string;
             sku: string;
             slug: string;
             /** Format: date-time */
@@ -390,12 +544,18 @@ export interface components {
             min: string;
             mode: string;
             selected: null | components["schemas"]["RangeSelectionDto"];
+            step: null | string;
             unit: null | string;
         };
         RangeSelectionDto: {
             max: null | string;
             min: null | string;
         };
+        RelatedGroupDto: {
+            key: string;
+            label: string;
+            products: components["schemas"]["ProductCardDto"][];
+        };
         SeoDto: {
             description: null | string;
             title: string;
@@ -408,6 +568,7 @@ export interface components {
             configVersion: string;
             defaultMarket: string;
             markets: components["schemas"]["MarketDto"][];
+            media: components["schemas"]["MediaDto"];
             name: string;
             preview: boolean;
             urlPatterns: components["schemas"]["UrlPatternsDto"];
@@ -464,9 +625,25 @@ export interface components {
             /** @description Link to this code's documentation. */
             type?: string;
         };
+        SuggestCategoryDto: {
+            id: string;
+            name: string;
+            path: string[];
+        };
+        SuggestFacetValueDto: {
+            facet: string;
+            key: string;
+            label: string;
+        };
+        SuggestResponse: {
+            categories: components["schemas"]["SuggestCategoryDto"][];
+            facetValues: components["schemas"]["SuggestFacetValueDto"][];
+            products: components["schemas"]["ProductCardDto"][];
+            query: string;
+        };
         SwatchDto: {
             color: null | string;
-            imageUrl: null | string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
         };
         UpdateCartLineRequest: {
             /** Format: int32 */
@@ -477,7 +654,10 @@ export interface components {
             product: string;
         };
         VariantDto: {
+            hasOwnImages: boolean;
             id: string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
+            images: components["schemas"]["MediaDescriptorDto"][];
             inStock: boolean;
             price: null | components["schemas"]["PriceDto"];
             selectedOptions: {
@@ -1559,6 +1739,96 @@ export interface operations {
             };
         };
     };
+    SearchFacetValues: {
+        parameters: {
+            query?: {
+                /** @description Narrows to the values whose label contains q (case-insensitively) or whose key starts with it. Omit for the facet's values as they are. Matched against the 1000 most common values of the facet, in this API — at most 50 are returned. Present but blank is a 400 (INVALID_QUERY). */
+                q?: string;
+                /** @description The filter context the values are counted in, sent as filter[key]=value exactly as on /products: a count is what selecting that value would leave. This facet's own selection does not narrow it (the counts are disjunctive), and a key this site has no facet for is dropped silently. */
+                filter?: {
+                    [key: string]: string;
+                };
+            };
+            header: {
+                /** @description Publishable, preview or secret site key. Required on every request; secret keys are server-side only. */
+                "X-Site-Key": string;
+                /** @description Market code (e.g. "se"). Omit for the site's default market. */
+                "X-Market"?: string;
+                /** @description BCP-47 language tag. Omit to use the market's language. */
+                "Accept-Language"?: string;
+            };
+            path: {
+                key: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FacetValuesResponse"];
+                };
+            };
+            /** @description problem+json. MARKET_UNKNOWN (no such market on this site), INVALID_PAGE, or INVALID_QUERY (q present but blank, or longer than 100 characters), or FACET_NOT_SEARCHABLE (the facet exists but has no list of values to search in: a range, a toggle or a tree). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_KEY_MISSING or SITE_KEY_INVALID. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SECRET_KEY_FROM_BROWSER: a secret key was sent from a browser. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. FACET_NOT_FOUND, or SITE_INACTIVE when the site itself is not live. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. RATE_LIMITED; retryAfterSeconds and the Retry-After header say how long to wait. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_REGISTRY_WARMING or INDEX_UNAVAILABLE — retry, the request was not wrong. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+        };
+    };
     GetProduct: {
         parameters: {
             query?: never;
@@ -1734,6 +2004,90 @@ export interface operations {
             };
         };
     };
+    Suggest: {
+        parameters: {
+            query: {
+                /** @description What the shopper has typed so far, 1–100 characters. Blank, missing or longer is a 400 (INVALID_QUERY) — unlike a listing's q, which is truncated. */
+                q: string;
+            };
+            header: {
+                /** @description Publishable, preview or secret site key. Required on every request; secret keys are server-side only. */
+                "X-Site-Key": string;
+                /** @description Market code (e.g. "se"). Omit for the site's default market. */
+                "X-Market"?: string;
+                /** @description BCP-47 language tag. Omit to use the market's language. */
+                "Accept-Language"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestResponse"];
+                };
+            };
+            /** @description problem+json. MARKET_UNKNOWN (no such market on this site), INVALID_PAGE, or INVALID_QUERY (q missing, blank or longer than 100 characters). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_KEY_MISSING or SITE_KEY_INVALID. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SECRET_KEY_FROM_BROWSER: a secret key was sent from a browser. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_INACTIVE, or NOT_FOUND for an unrouted path. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. RATE_LIMITED; retryAfterSeconds and the Retry-After header say how long to wait. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_REGISTRY_WARMING or INDEX_UNAVAILABLE — retry, the request was not wrong. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+        };
+    };
     GetSite: {
         parameters: {
             query?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asstio-dev/storefront",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Typed client for the Asstio Storefront API (generated from OpenAPI).",
   "repository": {
     "type": "git",
@@ -17,14 +17,17 @@
   "scripts": {
     "generate": "openapi-typescript ../../tests/Storefront.Api.Tests/Snapshots/openapi-v1.json -o src/schema.d.ts",
     "typecheck-examples": "tsc -p tsconfig.examples.json",
-    "build": "npm run generate && tsc -p tsconfig.json && node -e \"require('node:fs').copyFileSync('src/schema.d.ts','dist/schema.d.ts')\" && npm run typecheck-examples",
-    "check": "npm run generate && npm run typecheck-examples && git diff --exit-code -- src/schema.d.ts && test -z \"$(git status --porcelain -- src/schema.d.ts)\""
+    "build": "npm run generate && tsc -p tsconfig.json && node -e \"require('node:fs').copyFileSync('src/schema.d.ts','dist/schema.d.ts')\" && npm run typecheck-examples && npm run smoke",
+    "test": "vitest run",
+    "check": "npm run generate && npm run typecheck-examples && npm test && git diff --exit-code -- src/schema.d.ts && test -z \"$(git status --porcelain -- src/schema.d.ts)\"",
+    "smoke": "node --input-type=module -e \"import(\\\"./dist/index.js\\\").then(m => { for (const f of [\\\"createStorefrontClient\\\", \\\"filterQuery\\\", \\\"pictureSources\\\", \\\"mediaUrl\\\"]) if (typeof m[f] !== \\\"function\\\") throw new Error(\\\"missing export \\\" + f) })\""
   },
   "dependencies": {
     "openapi-fetch": "0.17.0"
   },
   "devDependencies": {
     "openapi-typescript": "7.13.0",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "vitest": "3.2.7"
   }
 }

package/src/schema.d.ts

@@ -153,6 +153,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/products/facets/{key}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Search within a facet: values whose label matches q, counted in this request's filter[...] context (spelled as on /products). Free text and collections are not applied. */
+        get: operations["SearchFacetValues"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/products/{slugOrId}": {
         parameters: {
             query?: never;
@@ -187,6 +204,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/search/suggest": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Search-as-you-type: products by name prefix, categories and facet values whose label starts with q. Market, assortment and language as /products. */
+        get: operations["Suggest"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/site": {
         parameters: {
             query?: never;
@@ -235,6 +269,27 @@ export interface components {
             label: string;
             value: string;
         };
+        AttributeDto: {
+            facetKey: null | string;
+            html: null | string;
+            key: string;
+            label: string;
+            type: string;
+            value: null | string;
+            valueKeys: string[] | null;
+            values: string[] | null;
+        };
+        BrandDto: {
+            facet: null | components["schemas"]["FacetLinkDto"];
+            label: string;
+        };
+        BundleComponentDto: {
+            product: components["schemas"]["ProductCardDto"];
+            quantity: string;
+        };
+        BundleDto: {
+            components: components["schemas"]["BundleComponentDto"][];
+        };
         CartDto: {
             currency: string;
             grandTotalInc: string;
@@ -249,11 +304,24 @@ export interface components {
         };
         CartLineDto: {
             id: string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
             price: components["schemas"]["PriceDto"];
-            productId: string;
+            product: components["schemas"]["CartLineProductDto"];
             /** Format: int32 */
             quantity: number | string;
             sku: string;
+            variant: components["schemas"]["CartLineVariantDto"];
+        };
+        CartLineProductDto: {
+            id: string;
+            name: string;
+            slug: string;
+        };
+        CartLineVariantDto: {
+            id: string;
+            selectedOptions: {
+                [key: string]: string;
+            };
         };
         CategoryNodeDto: {
             children: components["schemas"]["CategoryNodeDto"][];
@@ -297,6 +365,10 @@ export interface components {
             slug: string;
             url: string;
         };
+        DescriptionDto: {
+            html: string;
+            text: string;
+        };
         FacetDto: {
             key: string;
             label: string;
@@ -307,6 +379,10 @@ export interface components {
             type: string;
             values: components["schemas"]["FacetValueDto"][];
         };
+        FacetLinkDto: {
+            key: string;
+            valueKey: string;
+        };
         FacetValueDto: {
             children: components["schemas"]["FacetValueDto"][] | null;
             /** Format: int64 */
@@ -317,6 +393,10 @@ export interface components {
             selected: boolean;
             swatch: null | components["schemas"]["SwatchDto"];
         };
+        FacetValuesResponse: {
+            facet: string;
+            values: components["schemas"]["FacetValueDto"][];
+        };
         ListingResponse: {
             appliedFilters: components["schemas"]["AppliedFilterDto"][];
             facets: components["schemas"]["FacetDto"][];
@@ -339,6 +419,68 @@ export interface components {
             language: string;
             urlTemplate: string;
         };
+        MediaDescriptorDto: {
+            alt: {
+                [key: string]: string;
+            };
+            /** @description Passed through opaque, exactly as Purchase wrote it (spec 2026-09-18 §3); no fixed shape. */
+            attributes: null | {
+                [key: string]: unknown;
+            };
+            bg: null | string;
+            blurhash: null | string;
+            /** Format: int64 */
+            bytes: number | null | string;
+            caption: null | {
+                [key: string]: string;
+            };
+            color: null | string;
+            /** Format: int32 */
+            duration: number | null | string;
+            filename: null | string;
+            formats: string[];
+            /** Format: int32 */
+            h: number | null | string;
+            id: string;
+            kind: string;
+            /** Format: int32 */
+            order: number | string;
+            /** Format: int32 */
+            pages: number | null | string;
+            poster: null | components["schemas"]["MediaPosterDto"];
+            /** Format: int32 */
+            recipe: number | string;
+            role: string;
+            variants: components["schemas"]["MediaVideoVariantDto"][] | null;
+            view: null | string;
+            /** Format: int32 */
+            w: number | null | string;
+            widths: (number | string)[];
+        };
+        MediaDto: {
+            baseUrl: string;
+            templates: components["schemas"]["MediaTemplatesDto"];
+        };
+        MediaPosterDto: {
+            formats: string[];
+            widths: (number | string)[];
+        };
+        MediaTemplatesDto: {
+            file: string;
+            image: string;
+            poster: string;
+            video: string;
+        };
+        MediaVideoVariantDto: {
+            /** Format: int64 */
+            bytes: number | string;
+            format: string;
+            /** Format: int32 */
+            h: number | string;
+            name: string;
+            /** Format: int32 */
+            w: number | string;
+        };
         OptionDto: {
             name: string;
             values: string[];
@@ -351,12 +493,15 @@ export interface components {
             vatRate: string;
         };
         ProductCardDto: {
+            brand: null | components["schemas"]["BrandDto"];
             collections: string[];
             id: string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
             inStock: boolean;
             name: string;
             price: null | components["schemas"]["PriceDto"];
             priceVaries: boolean;
+            shortDescription: null | string;
             sku: string;
             slug: string;
             /** Format: date-time */
@@ -367,14 +512,23 @@ export interface components {
             alternateUrls: {
                 [key: string]: string;
             };
+            attributes: components["schemas"]["AttributeDto"][];
+            brand: null | components["schemas"]["BrandDto"];
+            bundle: null | components["schemas"]["BundleDto"];
             categories: components["schemas"]["CategoryRefDto"][];
             collections: components["schemas"]["CollectionRefDto"][];
+            description: null | components["schemas"]["DescriptionDto"];
+            files: components["schemas"]["MediaDescriptorDto"][];
             id: string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
+            images: components["schemas"]["MediaDescriptorDto"][];
             matchedVariantId: null | string;
             name: string;
             options: components["schemas"]["OptionDto"][];
             redirectTo: null | string;
+            related: components["schemas"]["RelatedGroupDto"][];
             seo: components["schemas"]["SeoDto"];
+            shortDescription: null | string;
             sku: string;
             slug: string;
             /** Format: date-time */
@@ -390,12 +544,18 @@ export interface components {
             min: string;
             mode: string;
             selected: null | components["schemas"]["RangeSelectionDto"];
+            step: null | string;
             unit: null | string;
         };
         RangeSelectionDto: {
             max: null | string;
             min: null | string;
         };
+        RelatedGroupDto: {
+            key: string;
+            label: string;
+            products: components["schemas"]["ProductCardDto"][];
+        };
         SeoDto: {
             description: null | string;
             title: string;
@@ -408,6 +568,7 @@ export interface components {
             configVersion: string;
             defaultMarket: string;
             markets: components["schemas"]["MarketDto"][];
+            media: components["schemas"]["MediaDto"];
             name: string;
             preview: boolean;
             urlPatterns: components["schemas"]["UrlPatternsDto"];
@@ -464,9 +625,25 @@ export interface components {
             /** @description Link to this code's documentation. */
             type?: string;
         };
+        SuggestCategoryDto: {
+            id: string;
+            name: string;
+            path: string[];
+        };
+        SuggestFacetValueDto: {
+            facet: string;
+            key: string;
+            label: string;
+        };
+        SuggestResponse: {
+            categories: components["schemas"]["SuggestCategoryDto"][];
+            facetValues: components["schemas"]["SuggestFacetValueDto"][];
+            products: components["schemas"]["ProductCardDto"][];
+            query: string;
+        };
         SwatchDto: {
             color: null | string;
-            imageUrl: null | string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
         };
         UpdateCartLineRequest: {
             /** Format: int32 */
@@ -477,7 +654,10 @@ export interface components {
             product: string;
         };
         VariantDto: {
+            hasOwnImages: boolean;
             id: string;
+            image: null | components["schemas"]["MediaDescriptorDto"];
+            images: components["schemas"]["MediaDescriptorDto"][];
             inStock: boolean;
             price: null | components["schemas"]["PriceDto"];
             selectedOptions: {
@@ -1559,6 +1739,96 @@ export interface operations {
             };
         };
     };
+    SearchFacetValues: {
+        parameters: {
+            query?: {
+                /** @description Narrows to the values whose label contains q (case-insensitively) or whose key starts with it. Omit for the facet's values as they are. Matched against the 1000 most common values of the facet, in this API — at most 50 are returned. Present but blank is a 400 (INVALID_QUERY). */
+                q?: string;
+                /** @description The filter context the values are counted in, sent as filter[key]=value exactly as on /products: a count is what selecting that value would leave. This facet's own selection does not narrow it (the counts are disjunctive), and a key this site has no facet for is dropped silently. */
+                filter?: {
+                    [key: string]: string;
+                };
+            };
+            header: {
+                /** @description Publishable, preview or secret site key. Required on every request; secret keys are server-side only. */
+                "X-Site-Key": string;
+                /** @description Market code (e.g. "se"). Omit for the site's default market. */
+                "X-Market"?: string;
+                /** @description BCP-47 language tag. Omit to use the market's language. */
+                "Accept-Language"?: string;
+            };
+            path: {
+                key: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FacetValuesResponse"];
+                };
+            };
+            /** @description problem+json. MARKET_UNKNOWN (no such market on this site), INVALID_PAGE, or INVALID_QUERY (q present but blank, or longer than 100 characters), or FACET_NOT_SEARCHABLE (the facet exists but has no list of values to search in: a range, a toggle or a tree). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_KEY_MISSING or SITE_KEY_INVALID. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SECRET_KEY_FROM_BROWSER: a secret key was sent from a browser. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. FACET_NOT_FOUND, or SITE_INACTIVE when the site itself is not live. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. RATE_LIMITED; retryAfterSeconds and the Retry-After header say how long to wait. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_REGISTRY_WARMING or INDEX_UNAVAILABLE — retry, the request was not wrong. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+        };
+    };
     GetProduct: {
         parameters: {
             query?: never;
@@ -1734,6 +2004,90 @@ export interface operations {
             };
         };
     };
+    Suggest: {
+        parameters: {
+            query: {
+                /** @description What the shopper has typed so far, 1–100 characters. Blank, missing or longer is a 400 (INVALID_QUERY) — unlike a listing's q, which is truncated. */
+                q: string;
+            };
+            header: {
+                /** @description Publishable, preview or secret site key. Required on every request; secret keys are server-side only. */
+                "X-Site-Key": string;
+                /** @description Market code (e.g. "se"). Omit for the site's default market. */
+                "X-Market"?: string;
+                /** @description BCP-47 language tag. Omit to use the market's language. */
+                "Accept-Language"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SuggestResponse"];
+                };
+            };
+            /** @description problem+json. MARKET_UNKNOWN (no such market on this site), INVALID_PAGE, or INVALID_QUERY (q missing, blank or longer than 100 characters). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_KEY_MISSING or SITE_KEY_INVALID. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SECRET_KEY_FROM_BROWSER: a secret key was sent from a browser. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_INACTIVE, or NOT_FOUND for an unrouted path. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. RATE_LIMITED; retryAfterSeconds and the Retry-After header say how long to wait. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_REGISTRY_WARMING or INDEX_UNAVAILABLE — retry, the request was not wrong. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+        };
+    };
     GetSite: {
         parameters: {
             query?: never;