@asstio-dev/storefront 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# `@asstio-dev/storefront`
+
+Typed client for the [Asstio Storefront API](../../docs/superpowers/specs/2026-09-10-storefront-design.md).
+The types are **generated** from the OpenAPI document committed at
+`tests/Storefront.Api.Tests/Snapshots/openapi-v1.json`, which is the contract: it only changes in a
+deliberate commit, so a change here always shows up in a diff.
+
+```bash
+npm install @asstio-dev/storefront
+```
+
+```ts
+import { createStorefrontClient, filterQuery } from "@asstio-dev/storefront";
+
+// Your key: process.env.STOREFRONT_SITE_KEY on a server, import.meta.env.VITE_… in a bundler.
+declare const STOREFRONT_SITE_KEY: string;
+
+const storefront = createStorefrontClient({
+  baseUrl: "https://api.storefront.asstio.com",
+  siteKey: STOREFRONT_SITE_KEY, // publishable in the browser, secret only on the server
+  market: "se",
+  acceptLanguage: "sv-SE",
+});
+
+const { data, error } = await storefront.GET("/v1/products", {
+  params: {
+    query: {
+      q: "parfym",
+      page: 1,
+      pageSize: 24,
+      sort: "price_asc",
+      filter: filterQuery({ brand: ["dior", "chanel"], price: "100-500", size: undefined }),
+    },
+  },
+});
+
+if (error) throw new Error(`${error.code}: ${error.detail ?? ""}`);
+console.log(data.total, data.items, data.warnings);
+```
+
+```ts
+// A product with many variants comes back with variants: null and a variantCount; page them:
+const { data: page } = await storefront.GET("/v1/products/{slugOrId}/variants", {
+  params: { path: { slugOrId: "manadslins" }, query: { filter: { power: "-1.00" } } },
+});
+// page.options[].values[].available drives cascading dropdowns: a value reached through the cascade is
+// available, but honour the flag for hand-built URLs or restored state, which can select an unavailable one.
+```
+
+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.
+
+## Headers
+
+Every call the client makes carries these; you never set them by hand.
+
+| Header | Required | Meaning |
+| --- | --- | --- |
+| `X-Site-Key` | yes | Which shop, and with which visibility. `sfk_pub_…` publishable (safe in a browser bundle), `sfk_prv_…` preview (draft content), `sfk_sec_…` secret — **server-side only**: a secret key sent from a page is rejected with `SECRET_KEY_FROM_BROWSER`. |
+| `X-Market` | no | Market code, e.g. `se`. Omit for the site's default market. An unknown one is `MARKET_UNKNOWN`. |
+| `Accept-Language` | no | BCP-47 tag. Omit to use the market's language. |
+
+The client sets all three, so `params.header` is optional at every call site even though the contract marks
+`X-Site-Key` required.
+
+## Errors
+
+Every failure is `application/problem+json` with a stable machine-readable `code`; branch on `code`,
+never on `title` or on the status alone.
+
+```jsonc
+{
+  "type": "https://docs.asstio.com/storefront/errors#PRODUCT_NOT_FOUND",
+  "title": "PRODUCT_NOT_FOUND",
+  "status": 404,
+  "detail": "No product 'x' on this market.",
+  "code": "PRODUCT_NOT_FOUND"      // the only stable field; `retryAfterSeconds` is added on RATE_LIMITED
+}
+```
+
+It is `StorefrontProblem` in the schema, so `error.code` and `error.retryAfterSeconds` are typed — no cast:
+
+```ts
+if (error?.code === "RATE_LIMITED") await sleep((error.retryAfterSeconds ?? 10) * 1000);
+```
+
+Every operation documents `400`, `401`, `403`, `404`, `429` and `503`; the entity 404s (`PRODUCT_NOT_FOUND`,
+`COLLECTION_NOT_FOUND`) are called out on the operations that raise them.
+
+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`.
+
+`SITE_REGISTRY_WARMING` and `INDEX_UNAVAILABLE` are retries, not bugs in your call.
+
+## Warnings
+
+A request that was *almost* right still answers 200 and says so in `warnings[]`, so a listing page never
+goes blank because of a bad query string:
+
+| `code` | What happened |
+| --- | --- |
+| `SORT_UNKNOWN` | The `sort` value is not one this site offers; the default sort was used. |
+| `COLLECTION_UNKNOWN` | The named collection does not exist; it was not applied. |
+| `FILTER_IGNORED` | A `filter[…]` key is not facetable here; that filter was dropped. |
+| `QUERY_TRUNCATED` | `q` was longer than 200 characters; the results are for the shortened term. |
+
+## Query parameters
+
+`q`, `page`, `pageSize`, `sort` and `filter` are all in the contract, so they are typed and autocompleted.
+`filter` is a `deepObject`: `{ brand: "dior,chanel" }` goes out as `filter[brand]=dior,chanel`, which is the
+form the API reads. `filterQuery()` is a thin helper that joins multi-select values and drops `undefined` ones.
+
+`/v1/sitemap` takes `type` (`product` | `collection`), `since` (ISO-8601, inclusive), `page` and `pageSize`
+(max 1000, default 500).
+
+## Caching
+
+Read responses carry an `ETag` and `Vary: X-Site-Key, X-Market, Accept-Language` — the answer depends on
+all three, so a shared cache must key on all three. Send the ETag back as `If-None-Match` and a matching
+request answers `304 Not Modified` with no body:
+
+```ts
+const first = await storefront.GET("/v1/site", {});
+const etag = first.response.headers.get("ETag")!;
+const again = await storefront.GET("/v1/site", { headers: { "If-None-Match": etag } });
+// again.response.status === 304
+```
+
+Errors are never stored (`Cache-Control: no-store`) and never carry an ETag.
+
+## Development
+
+```bash
+npm install
+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.

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { type Client } from "openapi-fetch";
+import type { paths } from "./schema";
+export type { paths, components } from "./schema";
+/**
+ * The API requires X-Site-Key on every call, so the generated types demand `params.header` at every call site —
+ * but this client sets all three headers itself. These map the generated paths to the same operations with the
+ * header block optional: the contract stays honest, and the caller does not repeat the key on every request.
+ */
+type HeadersOptional<Params> = Omit<Params, "header"> & (Params extends {
+    header: infer H;
+} ? {
+    header?: Partial<H>;
+} : {
+    header?: never;
+});
+export type StorefrontPaths = {
+    [Path in keyof paths]: {
+        [Method in keyof paths[Path]]: paths[Path][Method] extends {
+            parameters: infer Params;
+        } ? Omit<paths[Path][Method], "parameters"> & {
+            parameters: HeadersOptional<Params>;
+        } : paths[Path][Method];
+    };
+};
+export interface StorefrontClientOptions {
+    /** e.g. https://api.storefront.asstio.com */
+    baseUrl: string;
+    /** publishable (browser), preview (draft mode) or secret (server only) site key */
+    siteKey: string;
+    /** market code, e.g. "se"; omit for the site's default market */
+    market?: string;
+    /** BCP-47 tag; omit to use the market's language */
+    acceptLanguage?: string;
+    fetch?: typeof fetch;
+}
+/** Thin typed client: every call carries X-Site-Key / X-Market / Accept-Language. Works in browsers and on the server. */
+export declare function createStorefrontClient(opts: StorefrontClientOptions): Client<StorefrontPaths>;
+/** The `filter` query parameter of a listing call: one facet key to one value, as the generated types spell it. */
+export type FilterSelection = NonNullable<NonNullable<paths["/v1/products"]["get"]["parameters"]["query"]>["filter"]>;
+/**
+ * Collapse a facet selection into the typed `filter` object: several values for one facet are comma-separated,
+ * and `undefined` facets drop out — so an unchecked checkbox needs no special case at the call site.
+ * `{ brand: ["dior", "chanel"], price: "100-500", size: undefined }` → `{ brand: "dior,chanel", price: "100-500" }`.
+ * 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;

package/dist/index.js

@@ -0,0 +1,34 @@
+import createClient from "openapi-fetch";
+/** Thin typed client: every call carries X-Site-Key / X-Market / Accept-Language. Works in browsers and on the server. */
+export function createStorefrontClient(opts) {
+    const client = createClient({ baseUrl: opts.baseUrl.replace(/\/$/, ""), fetch: opts.fetch });
+    const headers = {
+        onRequest({ request }) {
+            request.headers.set("X-Site-Key", opts.siteKey);
+            if (opts.market)
+                request.headers.set("X-Market", opts.market);
+            if (opts.acceptLanguage)
+                request.headers.set("Accept-Language", opts.acceptLanguage);
+            return request;
+        },
+    };
+    client.use(headers);
+    // The cast is the whole point of the type above: at runtime the middleware has already supplied the headers the
+    // generated types insist on.
+    return client;
+}
+/**
+ * Collapse a facet selection into the typed `filter` object: several values for one facet are comma-separated,
+ * and `undefined` facets drop out — so an unchecked checkbox needs no special case at the call site.
+ * `{ brand: ["dior", "chanel"], price: "100-500", size: undefined }` → `{ brand: "dior,chanel", price: "100-500" }`.
+ * The client sends it as `filter[brand]=dior,chanel` (deepObject), which is what the API reads.
+ */
+export function filterQuery(selection) {
+    const out = {};
+    for (const [key, value] of Object.entries(selection)) {
+        if (value === undefined)
+            continue;
+        out[key] = Array.isArray(value) ? value.join(",") : value;
+    }
+    return out;
+}