@asstio-dev/storefront 0.5.0 → 0.6.0

package/README.md

@@ -190,7 +190,14 @@ goes blank because of a bad query string:
 
 `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.
+form the API reads. In a list, swatch or hierarchy filter `,` separates values, `\,` is a comma inside a value and
+`\\` a backslash — value keys are raw values, and an option such as `14,2` is the key `14,2`. Never join or split a
+filter parameter yourself: `encodeFilterValues(values)` builds one and `decodeFilterValues(param)` reads one (for
+the selected state of a URL you parse), for every facet alike. `filterQuery()` uses `encodeFilterValues` for
+multi-select arrays, passes a single string (a range `100-500`, a toggle `true`) as given and drops `undefined` ones.
+A range is `min-max`: either bound may be left out and either may be negative — `-10--2`, `-10-2`, `-10-` (at least
+−10), `--2` (at most −2) — and a leading dash with nothing before it keeps its meaning, `-500` is "at most 500". A
+range whose lower bound is above its upper bound is ignored with a warning.
 
 `/v1/sitemap` takes `type` (`product` | `collection`), `since` (ISO-8601, inclusive), `page` and `pageSize`
 (max 1000, default 500).

package/dist/filters.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The list grammar of a `filter[<key>]` parameter (list, swatch and hierarchy facets): `,` separates values, `\,` is a
+ * comma inside a value and `\\` a backslash. A value key is the raw value — an option such as "14,2" is the key "14,2" —
+ * so a frontend never joins or splits a filter parameter by hand: it builds and toggles filter URLs with these two, for
+ * every facet alike. Range (`min-max`) and toggle (`true`) parameters are single strings and need neither.
+ */
+export declare function encodeFilterValues(values: readonly string[]): string;
+/**
+ * The values a `filter[<key>]` parameter selects, read the way the API reads it: `\,` and `\\` unescaped, a backslash
+ * before anything else (or at the end) kept as it is, values trimmed, empty ones and repeats dropped.
+ */
+export declare function decodeFilterValues(param: string): string[];

package/dist/filters.js

@@ -0,0 +1,39 @@
+/**
+ * The list grammar of a `filter[<key>]` parameter (list, swatch and hierarchy facets): `,` separates values, `\,` is a
+ * comma inside a value and `\\` a backslash. A value key is the raw value — an option such as "14,2" is the key "14,2" —
+ * so a frontend never joins or splits a filter parameter by hand: it builds and toggles filter URLs with these two, for
+ * every facet alike. Range (`min-max`) and toggle (`true`) parameters are single strings and need neither.
+ */
+export function encodeFilterValues(values) {
+    return values.map((v) => v.replace(/\\/g, "\\\\").replace(/,/g, "\\,")).join(",");
+}
+/**
+ * The values a `filter[<key>]` parameter selects, read the way the API reads it: `\,` and `\\` unescaped, a backslash
+ * before anything else (or at the end) kept as it is, values trimmed, empty ones and repeats dropped.
+ */
+export function decodeFilterValues(param) {
+    const values = [];
+    let current = "";
+    const push = () => {
+        const value = current.trim();
+        current = "";
+        if (value.length > 0 && !values.includes(value))
+            values.push(value);
+    };
+    for (let i = 0; i < param.length; i++) {
+        const c = param[i];
+        const next = param[i + 1];
+        if (c === "\\" && (next === "," || next === "\\")) {
+            current += next;
+            i++;
+        }
+        else if (c === ",") {
+            push();
+        }
+        else {
+            current += c;
+        }
+    }
+    push();
+    return values;
+}

package/dist/index.d.ts

@@ -38,10 +38,12 @@ export declare function createStorefrontClient(opts: StorefrontClientOptions): C
 /** 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.
+ * Collapse a facet selection into the typed `filter` object: several values for one facet are encoded with
+ * `encodeFilterValues` (so a value containing a comma or a backslash survives), a single string is sent as given (a
+ * range "100-500", a toggle "true"), and `undefined` facets drop out — an unchecked checkbox needs no special case.
  * `{ 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;
+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";

package/dist/index.js

@@ -1,4 +1,5 @@
 import createClient from "openapi-fetch";
+import { encodeFilterValues } from "./filters.js";
 /** 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 });
@@ -18,8 +19,9 @@ export function createStorefrontClient(opts) {
     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.
+ * Collapse a facet selection into the typed `filter` object: several values for one facet are encoded with
+ * `encodeFilterValues` (so a value containing a comma or a backslash survives), a single string is sent as given (a
+ * range "100-500", a toggle "true"), and `undefined` facets drop out — an unchecked checkbox needs no special case.
  * `{ 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.
  */
@@ -28,8 +30,9 @@ export function filterQuery(selection) {
     for (const [key, value] of Object.entries(selection)) {
         if (value === undefined)
             continue;
-        out[key] = Array.isArray(value) ? value.join(",") : value;
+        out[key] = Array.isArray(value) ? encodeFilterValues(value) : value;
     }
     return out;
 }
+export { decodeFilterValues, encodeFilterValues } from "./filters.js";
 export { fileUrl, mediaHash, mediaUrl, MediaUrlError, pickWidth, pictureSources, posterUrl, srcSet, videoSources, } from "./media.js";

package/dist/schema.d.ts

@@ -370,6 +370,8 @@ export interface components {
             text: string;
         };
         FacetDto: {
+            collapsed: boolean;
+            help: null | string;
             key: string;
             label: string;
             match: string;
@@ -387,6 +389,7 @@ export interface components {
             children: components["schemas"]["FacetValueDto"][] | null;
             /** Format: int64 */
             count: number | string;
+            help: null | string;
             key: string;
             label: string;
             pinned: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asstio-dev/storefront",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Typed client for the Asstio Storefront API (generated from OpenAPI).",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
     "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) })\""
+    "smoke": "node --input-type=module -e \"import(\\\"./dist/index.js\\\").then(m => { for (const f of [\\\"createStorefrontClient\\\", \\\"filterQuery\\\", \\\"encodeFilterValues\\\", \\\"decodeFilterValues\\\", \\\"pictureSources\\\", \\\"mediaUrl\\\"]) if (typeof m[f] !== \\\"function\\\") throw new Error(\\\"missing export \\\" + f) })\""
   },
   "dependencies": {
     "openapi-fetch": "0.17.0"

package/src/schema.d.ts

@@ -370,6 +370,8 @@ export interface components {
             text: string;
         };
         FacetDto: {
+            collapsed: boolean;
+            help: null | string;
             key: string;
             label: string;
             match: string;
@@ -387,6 +389,7 @@ export interface components {
             children: components["schemas"]["FacetValueDto"][] | null;
             /** Format: int64 */
             count: number | string;
+            help: null | string;
             key: string;
             label: string;
             pinned: boolean;