@minipim/sdk 0.4.1 → 0.6.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/index.cjs

@@ -80,9 +80,7 @@ async function* paginate(client, path, opts = {}) {
       params: { query: { ...opts.query ?? {}, limit: pageSize, offset } }
     });
     if (error || !data) {
-      throw new Error(
-        `paginate ${path} failed at offset ${offset} (HTTP ${response?.status})`
-      );
+      throw new Error(`paginate ${path} failed at offset ${offset} (HTTP ${response?.status})`);
     }
     if (Array.isArray(data)) {
       for (const item of data) yield item;

package/dist/index.d.cts

@@ -77,9 +77,13 @@ type MinipimClient = Client<paths>;
 declare function createMinipimClient(opts: CreateMinipimClientOptions): MinipimClient;
 
 /**
- * Generic pagination helper. Every MiniPim list endpoint returns
- * `{ data, limit, offset, hasMore }`; this walks the pages so consumers
- * don't hand-roll the `hasMore` loop. Yields one item at a time.
+ * Generic pagination helper. MiniPim list endpoints return
+ * `{ data, limit, offset }`, and **only `/v1/products` also returns
+ * `hasMore`** — so this walks the pages by trusting `hasMore` when it is
+ * present and falling back to a short-page check when it isn't. That is the
+ * whole reason to use this instead of a hand-rolled `while (hasMore)` loop,
+ * which reads exactly one page from every other endpoint and stops. Yields
+ * one item at a time.
  *
  * Typed loosely on purpose — openapi-fetch's per-path generics don't
  * compose into a single reusable signature without a lot of conditional-

package/dist/index.d.ts

@@ -77,9 +77,13 @@ type MinipimClient = Client<paths>;
 declare function createMinipimClient(opts: CreateMinipimClientOptions): MinipimClient;
 
 /**
- * Generic pagination helper. Every MiniPim list endpoint returns
- * `{ data, limit, offset, hasMore }`; this walks the pages so consumers
- * don't hand-roll the `hasMore` loop. Yields one item at a time.
+ * Generic pagination helper. MiniPim list endpoints return
+ * `{ data, limit, offset }`, and **only `/v1/products` also returns
+ * `hasMore`** — so this walks the pages by trusting `hasMore` when it is
+ * present and falling back to a short-page check when it isn't. That is the
+ * whole reason to use this instead of a hand-rolled `while (hasMore)` loop,
+ * which reads exactly one page from every other endpoint and stops. Yields
+ * one item at a time.
  *
  * Typed loosely on purpose — openapi-fetch's per-path generics don't
  * compose into a single reusable signature without a lot of conditional-

package/dist/index.js

@@ -28,9 +28,7 @@ async function* paginate(client, path, opts = {}) {
       params: { query: { ...opts.query ?? {}, limit: pageSize, offset } }
     });
     if (error || !data) {
-      throw new Error(
-        `paginate ${path} failed at offset ${offset} (HTTP ${response?.status})`
-      );
+      throw new Error(`paginate ${path} failed at offset ${offset} (HTTP ${response?.status})`);
     }
     if (Array.isArray(data)) {
       for (const item of data) yield item;