@minipim/sdk 0.4.1 → 0.5.0

package/README.md

@@ -130,6 +130,43 @@ const all = await collectAll<Product>(pim, '/v1/products');
 
 Endpoints that return a **plain array** instead of the envelope (`/v1/categories` without `?limit=`, `/v1/attributes`, `/v1/products/{id}/variants`) are handled too (v0.3.0+): the array is treated as the one-and-only page, so `collectAll` works uniformly across every list endpoint.
 
+## Listing by category, and by price (v0.5.0+)
+
+Two things storefronts almost always need, and previously had to do in memory.
+
+**Category subtrees.** `categoryId` on its own is **self-only** — it matches products filed directly against that category. Catalogs commonly assign products to leaf categories, so a parent category can legitimately return an empty page. Add `includeDescendants` for the whole subtree:
+
+```ts
+// Everything anywhere under "Backdrops", in ONE paginated query.
+const { data } = await pim.GET('/v1/products', {
+  query: { categoryId, includeDescendants: true, limit: 50 },
+});
+```
+
+Don't fetch `/v1/categories`, resolve descendants yourself and issue one request per id — this is a single round trip and it paginates as one result set.
+
+**Sorting and filtering by price.** There is no `sortBy: 'price'`, because a catalog's price attribute code is its own data (`price`, `msrp`, `list_price`, …). Name it:
+
+```ts
+// Cheapest first
+await pim.GET('/v1/products', {
+  query: { sortBy: 'attribute', sortAttribute: 'price', sortDir: 'asc' },
+});
+
+// $10.00–$50.00 — money bounds are INTEGER CENTS
+await pim.GET('/v1/products', {
+  query: { filterAttribute: 'price', filterMin: 1000, filterMax: 5000 },
+});
+```
+
+- Works on `money`, `number` and `decimal` attributes. `measurement` is refused — its values carry a unit, so ordering raw amounts would rank 5 g above 2 kg.
+- For `money`, bounds and ordering use `amount_cents`. **`filterMin: 1000` is $10.00.** No currency conversion — mixed-currency catalogs compare by number.
+- The value read is the one at the **default scope** (no locale, no channel). Products with no value sort **last in both directions** and are excluded by either bound: no price, not a price of zero.
+- An unknown code, or one of a non-orderable type, is a **422 naming the problem**. It never degrades to name ordering, so you can't get a plausible page that isn't sorted the way you asked.
+- `sortAttribute` and `filterAttribute` are independent; set both for "cheapest first, within a budget".
+
+Needs API **0.9.0+**. Check `GET /healthz`.
+
 ## Attribute helpers
 
 Attribute values are `unknown` and keyed by `(locale, channel)`. List responses return the raw `{ code: [{ locale, channel, value }] }` shape (only product *detail* with `?locale=&channel=` returns a flat `resolvedAttributes`). The SDK ships the flatten + coercion helpers so you don't reimplement them:

package/dist/openapi.d.cts

@@ -1468,6 +1468,51 @@ interface paths {
          *     Iterate by reading `hasMore`. Pass `?withTotal=true` to add a `total`
          *     field (costs one COUNT query). Default `limit` is 50, **max 200**.
          *     Reconcile after downtime with `?updatedSince=<iso8601>`.
+         *
+         *     ### Filtering by category
+         *
+         *     `?categoryId=` is **self-only**: it matches products assigned directly to
+         *     that category and nothing filed beneath it. Many catalogs assign products
+         *     only to leaf categories, so a self-only filter on a parent legitimately
+         *     returns zero rows.
+         *
+         *     Add `?includeDescendants=true` to match the category **and its entire
+         *     subtree**, resolved server-side in a single query:
+         *
+         *     ```bash
+         *     # Every product anywhere under "Backdrops", paginated normally
+         *     curl 'https://api.minipim.com/v1/products?categoryId=8d2a1f3c-...&includeDescendants=true&limit=50'
+         *     ```
+         *
+         *     Prefer this over fetching the tree and issuing one request per descendant —
+         *     it is one round trip, and it paginates as a single result set.
+         *
+         *     ### Sorting and filtering by price (or any numeric attribute)
+         *
+         *     Price is not a column — it is an attribute, and its **code is per-organization
+         *     data**, so there is no `sortBy=price`. Name the attribute instead:
+         *
+         *     ```bash
+         *     # Cheapest first
+         *     curl '.../v1/products?sortBy=attribute&sortAttribute=price&sortDir=asc'
+         *
+         *     # Between $10.00 and $50.00 — bounds are INTEGER CENTS for money attributes
+         *     curl '.../v1/products?filterAttribute=price&filterMin=1000&filterMax=5000'
+         *     ```
+         *
+         *     - Works on `money`, `number` and `decimal` attributes. `measurement` is
+         *       refused: its values carry a unit, so ordering raw amounts would rank 5 g
+         *       above 2 kg.
+         *     - For `money`, bounds and ordering use `amount_cents`. **`filterMin=1000`
+         *       is $10.00.** No currency conversion happens — mixed-currency catalogs are
+         *       compared by number, so scope the query to one currency if that matters.
+         *     - The value read is the one at the **default scope** (no locale, no channel).
+         *       A product with no default-scope value sorts **last** in both directions and
+         *       is excluded by either bound — it has no price, rather than a price of zero.
+         *     - Unknown code, or a code of the wrong type, is a **422** naming the problem.
+         *       It never silently degrades to `name` ordering.
+         *     - `sortAttribute` and `filterAttribute` are independent; set both to the
+         *       same code for the usual "cheapest first, within a budget" query.
          */
         get: {
             parameters: {
@@ -1476,15 +1521,20 @@ interface paths {
                     q?: string;
                     familyId?: string;
                     categoryId?: string;
+                    includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     brand?: string;
                     tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
-                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
+                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance" | "attribute";
+                    sortAttribute?: string;
+                    filterAttribute?: string;
+                    filterMin?: number;
+                    filterMax?: number;
                     sortDir?: "asc" | "desc";
                     limit?: number;
                     offset?: number;
-                    withTotal?: boolean;
+                    withTotal?: boolean | ("true" | "false" | "1" | "0");
                     locale?: string;
                     channel?: string;
                 };
@@ -1662,11 +1712,16 @@ interface paths {
                     q?: string;
                     familyId?: string;
                     categoryId?: string;
+                    includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     brand?: string;
                     tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
-                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
+                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance" | "attribute";
+                    sortAttribute?: string;
+                    filterAttribute?: string;
+                    filterMin?: number;
+                    filterMax?: number;
                     sortDir?: "asc" | "desc";
                     locale?: string;
                     channel?: string;
@@ -3979,8 +4034,13 @@ interface paths {
          *     ```
          *
          *     To get a single category's full ancestor path, walk `parentId` upwards
-         *     client-side, or hit `GET /v1/categories/{id}` which returns the same row
-         *     shape with the resolved path included in `path`.
+         *     client-side — this endpoint returns the whole tree in one call, so no extra
+         *     requests are needed. (`GET /v1/categories/{id}` returns the same row shape
+         *     for one category; it does **not** resolve an ancestor path.)
+         *
+         *     To list the products under a category *including* its subtree, use
+         *     `GET /v1/products?categoryId=<id>&includeDescendants=true` rather than
+         *     resolving descendants here and issuing one request per id.
          *
          *     Returns the full tree by default. `?limit=` / `?offset=` are supported
          *     for large taxonomies (ordered by `position`); omit them to get everything.

package/dist/openapi.d.ts

@@ -1468,6 +1468,51 @@ interface paths {
          *     Iterate by reading `hasMore`. Pass `?withTotal=true` to add a `total`
          *     field (costs one COUNT query). Default `limit` is 50, **max 200**.
          *     Reconcile after downtime with `?updatedSince=<iso8601>`.
+         *
+         *     ### Filtering by category
+         *
+         *     `?categoryId=` is **self-only**: it matches products assigned directly to
+         *     that category and nothing filed beneath it. Many catalogs assign products
+         *     only to leaf categories, so a self-only filter on a parent legitimately
+         *     returns zero rows.
+         *
+         *     Add `?includeDescendants=true` to match the category **and its entire
+         *     subtree**, resolved server-side in a single query:
+         *
+         *     ```bash
+         *     # Every product anywhere under "Backdrops", paginated normally
+         *     curl 'https://api.minipim.com/v1/products?categoryId=8d2a1f3c-...&includeDescendants=true&limit=50'
+         *     ```
+         *
+         *     Prefer this over fetching the tree and issuing one request per descendant —
+         *     it is one round trip, and it paginates as a single result set.
+         *
+         *     ### Sorting and filtering by price (or any numeric attribute)
+         *
+         *     Price is not a column — it is an attribute, and its **code is per-organization
+         *     data**, so there is no `sortBy=price`. Name the attribute instead:
+         *
+         *     ```bash
+         *     # Cheapest first
+         *     curl '.../v1/products?sortBy=attribute&sortAttribute=price&sortDir=asc'
+         *
+         *     # Between $10.00 and $50.00 — bounds are INTEGER CENTS for money attributes
+         *     curl '.../v1/products?filterAttribute=price&filterMin=1000&filterMax=5000'
+         *     ```
+         *
+         *     - Works on `money`, `number` and `decimal` attributes. `measurement` is
+         *       refused: its values carry a unit, so ordering raw amounts would rank 5 g
+         *       above 2 kg.
+         *     - For `money`, bounds and ordering use `amount_cents`. **`filterMin=1000`
+         *       is $10.00.** No currency conversion happens — mixed-currency catalogs are
+         *       compared by number, so scope the query to one currency if that matters.
+         *     - The value read is the one at the **default scope** (no locale, no channel).
+         *       A product with no default-scope value sorts **last** in both directions and
+         *       is excluded by either bound — it has no price, rather than a price of zero.
+         *     - Unknown code, or a code of the wrong type, is a **422** naming the problem.
+         *       It never silently degrades to `name` ordering.
+         *     - `sortAttribute` and `filterAttribute` are independent; set both to the
+         *       same code for the usual "cheapest first, within a budget" query.
          */
         get: {
             parameters: {
@@ -1476,15 +1521,20 @@ interface paths {
                     q?: string;
                     familyId?: string;
                     categoryId?: string;
+                    includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     brand?: string;
                     tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
-                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
+                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance" | "attribute";
+                    sortAttribute?: string;
+                    filterAttribute?: string;
+                    filterMin?: number;
+                    filterMax?: number;
                     sortDir?: "asc" | "desc";
                     limit?: number;
                     offset?: number;
-                    withTotal?: boolean;
+                    withTotal?: boolean | ("true" | "false" | "1" | "0");
                     locale?: string;
                     channel?: string;
                 };
@@ -1662,11 +1712,16 @@ interface paths {
                     q?: string;
                     familyId?: string;
                     categoryId?: string;
+                    includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     brand?: string;
                     tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
-                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance";
+                    sortBy?: "name" | "slug" | "status" | "updatedAt" | "createdAt" | "relevance" | "attribute";
+                    sortAttribute?: string;
+                    filterAttribute?: string;
+                    filterMin?: number;
+                    filterMax?: number;
                     sortDir?: "asc" | "desc";
                     locale?: string;
                     channel?: string;
@@ -3979,8 +4034,13 @@ interface paths {
          *     ```
          *
          *     To get a single category's full ancestor path, walk `parentId` upwards
-         *     client-side, or hit `GET /v1/categories/{id}` which returns the same row
-         *     shape with the resolved path included in `path`.
+         *     client-side — this endpoint returns the whole tree in one call, so no extra
+         *     requests are needed. (`GET /v1/categories/{id}` returns the same row shape
+         *     for one category; it does **not** resolve an ancestor path.)
+         *
+         *     To list the products under a category *including* its subtree, use
+         *     `GET /v1/products?categoryId=<id>&includeDescendants=true` rather than
+         *     resolving descendants here and issuing one request per id.
          *
          *     Returns the full tree by default. `?limit=` / `?offset=` are supported
          *     for large taxonomies (ordered by `position`); omit them to get everything.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minipim/sdk",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Typed TypeScript client for the MiniPim API.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/Epic-Design-Labs/minipim",