@asstio-dev/storefront 0.1.0 → 0.3.0

package/README.md

@@ -9,6 +9,11 @@ deliberate commit, so a change here always shows up in a diff.
 npm install @asstio-dev/storefront
 ```
 
+Setting a shop up in the first place — the Asstio-side MCP calls, the API key kinds, CORS, the filter and
+price model — is one document: [`docs/PUBLIC_STOREFRONT_ONBOARDING.md`](../../docs/PUBLIC_STOREFRONT_ONBOARDING.md),
+served publicly at <https://api.storefront.asstio.com/docs/onboarding>. This file is only about using the
+package.
+
 ```ts
 import { createStorefrontClient, filterQuery } from "@asstio-dev/storefront";
 
@@ -50,6 +55,26 @@ 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
+```
+
 ## Headers
 
 Every call the client makes carries these; you never set them by hand.
@@ -132,12 +157,46 @@ Errors are never stored (`Cache-Control: no-store`) and never carry an ETag.
 
 ## Development
 
+From `sdk/typescript`:
+
 ```bash
-npm install
+npm ci
 npm run build     # regenerates src/schema.d.ts from the snapshot, compiles, then typechecks the examples
 npm run check     # fails if the committed schema.d.ts is stale, modified or untracked, or an example broke
 ```
 
 `src/schema.d.ts` is generated **and committed**: it is reviewed in pull requests exactly like the
-OpenAPI snapshot it comes from. After changing the API, regenerate the snapshot
-(`UPDATE_SNAPSHOTS=1 dotnet test --project tests/Storefront.Api.Tests`), then `npm run build` here.
+OpenAPI snapshot it comes from. After changing the public API, regenerate the snapshot from the repo
+root, then build and check the SDK:
+
+```bash
+UPDATE_SNAPSHOTS=1 dotnet test --project tests/Storefront.Api.Tests -- --filter-query "/*/*/OpenApiSnapshotTests/*"
+cd sdk/typescript
+npm ci
+npm run build
+npm run check
+```
+
+Review and commit `tests/Storefront.Api.Tests/Snapshots/openapi-v1.json` and
+`sdk/typescript/src/schema.d.ts` together. An API or worker implementation change that leaves the
+OpenAPI snapshot unchanged does not require a generated SDK change.
+
+## Publishing
+
+The SDK and backend share a release version. Do not edit the placeholder version in `package.json`
+and do not run `npm publish` locally. Pushing a repository tag such as `v1.2.3` runs
+`publish-npm.yml`, which derives version `1.2.3` from the tag, installs and checks the package, runs a
+publish dry run, and creates a pending staged package through npm trusted publishing. No long-lived
+`NPM_TOKEN` is used.
+
+The tag does not make the package public. A maintainer must inspect and approve it with npm 2FA, on
+the npm website under **Staged Packages** or with npm 11.19 or newer:
+
+```bash
+npm stage list @asstio-dev/storefront
+npm stage view <stage-id>
+npm stage approve <stage-id>
+```
+
+After approval, verify the registry version and a clean consumer install. The full API, worker, and
+npm release checklist is in [`docs/ops/deploy.md`](../../docs/ops/deploy.md).

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,
+    }));
+}