@sonic-commerce/storefront-types 0.26.1 → 0.27.0

package/README.md

@@ -74,6 +74,31 @@ and so on — alongside the raw `paths`, `components` and `operations` that
 import type { Cart, CartTotals, AddCartItemBody } from "@sonic-commerce/storefront-types";
 ```
 
+### Option filters
+
+`opt.<option>` keys are named after the store's options, so they are not in the
+typed query parameters. Spread them in — TypeScript does not check spread
+properties against the parameter list:
+
+```ts
+import type { ProductFilters } from "@sonic-commerce/storefront-types";
+
+const options = { "opt.size": "m,l", "opt.colour": "red" };
+
+const { data: filters } = await api.GET("/products/filters", {
+  params: { query: { ...options, "price[lte]": 18500 } },
+});
+const sidebar: ProductFilters | undefined = filters?.data;
+
+const { data: page } = await api.GET("/products", {
+  params: { query: { ...options, "price[lte]": 18500, sort: "price" } },
+});
+```
+
+Take keys from `ProductFilters` (`option.key`, `value.key`) rather than
+building them from labels. Counts are over the current result and `null` above
+5,000 matching products; see the API guide for the rules.
+
 ### One openapi-fetch quirk
 
 `openapi-fetch` (0.17.0, checked) drops properties typed as exactly `null` from

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 // Generated by scripts/build.mjs from app/openapi/public-api.json — do not edit.
-// Spec version 0.26.1, 54 named schemas.
+// Spec version 0.27.0, 58 named schemas.
 
 export type { paths, components, operations } from "./schema";
 import type { components } from "./schema";
@@ -36,8 +36,12 @@ export type PaymentMethod = components["schemas"]["PaymentMethod"];
 export type Product = components["schemas"]["Product"];
 export type ProductCategory = components["schemas"]["ProductCategory"];
 export type ProductCollection = components["schemas"]["ProductCollection"];
+export type ProductFilterOption = components["schemas"]["ProductFilterOption"];
+export type ProductFilterValue = components["schemas"]["ProductFilterValue"];
+export type ProductFilters = components["schemas"]["ProductFilters"];
 export type ProductListItem = components["schemas"]["ProductListItem"];
 export type ProductOption = components["schemas"]["ProductOption"];
+export type ProductPriceBand = components["schemas"]["ProductPriceBand"];
 export type ProductVariant = components["schemas"]["ProductVariant"];
 export type Region = components["schemas"]["Region"];
 export type RegionSummary = components["schemas"]["RegionSummary"];

package/dist/schema.d.ts

@@ -13,7 +13,7 @@ export interface paths {
         };
         /**
          * List products
-         * @description Filter, sort, search and expand. `price` sorts and filters resolve against the store's default currency, in minor units.
+         * @description Filter, sort, search and expand. Prices are in minor units, in `currency` or the store's default. A `price[...]` filter matches a product when one variant is priced in range — every bound against that one price, and on the same variant as any `opt.` filter. `sort=price` orders by the product's lowest price; products with no price in the currency come last in both directions.
          */
         get: {
             parameters: {
@@ -115,6 +115,110 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/products/filters": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Filters for a product listing
+         * @description What a filter sidebar shows for the listing the same query returns. Send the listing's filters, `q`, `currency` and `opt.` keys. Counts are taken over the current result: with `opt.size=m`, the other sizes count 0, and every value of a chosen option is listed so it can be widened. The price block ignores the price filter itself so the range can be widened too; its bands are round steps to snap a slider to. Above 5,000 matching products nothing is counted: `counted` is `false`, every count is `null`, and the option lists are store-wide.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description 1-based page number. */
+                    page?: number;
+                    /** @description Rows per page. Values above 100 are rejected, not clamped. */
+                    limit?: number;
+                    /** @description Free-text search term. */
+                    q?: string;
+                    /** @description ISO 4217 code to price against, e.g. `CAD`. Must be one the store supports. Defaults to the store's default currency. */
+                    currency?: string;
+                    /** @description Filter by category_id. A comma-separated list matches any value; the literal `null` matches rows where category_id is unset. */
+                    category_id?: string;
+                    /** @description Filter where category_id is not equal to the given value. */
+                    "category_id[ne]"?: string;
+                    /** @description Filter by collection_id. A comma-separated list matches any value; the literal `null` matches rows where collection_id is unset. */
+                    collection_id?: string;
+                    /** @description Filter where collection_id is not equal to the given value. */
+                    "collection_id[ne]"?: string;
+                    /** @description Filter by handle. A comma-separated list matches any value; the literal `null` matches rows where handle is unset. */
+                    handle?: string;
+                    /** @description Filter where handle is not equal to the given value. */
+                    "handle[ne]"?: string;
+                    /** @description Filter where handle is case-insensitive substring match the given value. */
+                    "handle[like]"?: string;
+                    /** @description Filter by tag. A comma-separated list matches any value; the literal `null` matches rows where tag is unset. */
+                    tag?: string;
+                    /** @description Filter where tag is not equal to the given value. */
+                    "tag[ne]"?: string;
+                    /** @description Filter by type. A comma-separated list matches any value; the literal `null` matches rows where type is unset. */
+                    type?: string;
+                    /** @description Filter where type is not equal to the given value. */
+                    "type[ne]"?: string;
+                    /** @description Filter by price. A comma-separated list matches any value; the literal `null` matches rows where price is unset. */
+                    price?: string;
+                    /** @description Filter where price is not equal to the given value. */
+                    "price[ne]"?: number;
+                    /** @description Filter where price is greater than the given value. */
+                    "price[gt]"?: number;
+                    /** @description Filter where price is greater than or equal to the given value. */
+                    "price[gte]"?: number;
+                    /** @description Filter where price is less than the given value. */
+                    "price[lt]"?: number;
+                    /** @description Filter where price is less than or equal to the given value. */
+                    "price[lte]"?: number;
+                    /** @description Filter by in_stock. A comma-separated list matches any value; the literal `null` matches rows where in_stock is unset. */
+                    in_stock?: string;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Success */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            data: components["schemas"]["ProductFilters"];
+                        };
+                    };
+                };
+                /** @description Invalid request — unknown parameter or bad value. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Rate limit exceeded. */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/products/search": {
         parameters: {
             query?: never;
@@ -3607,6 +3711,35 @@ export interface components {
                 image: string | null;
             };
         };
+        ProductFilters: {
+            total: number;
+            counted: boolean;
+            options: components["schemas"]["ProductFilterOption"][];
+            price: {
+                currency_code: string;
+                min: number;
+                max: number;
+                bands: components["schemas"]["ProductPriceBand"][];
+            } | null;
+            in_stock: {
+                count: number | null;
+            };
+        };
+        ProductFilterOption: {
+            key: string;
+            title: string;
+            values: components["schemas"]["ProductFilterValue"][];
+        };
+        ProductFilterValue: {
+            key: string;
+            value: string;
+            count: number | null;
+        };
+        ProductPriceBand: {
+            gte: number;
+            lt: number;
+            count: number | null;
+        };
         Category: {
             id: string;
             name?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonic-commerce/storefront-types",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "TypeScript types for the Sonic Commerce storefront API (/v1).",
   "keywords": ["sonic-commerce", "openapi", "types", "storefront"],
   "license": "UNLICENSED",