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

@@ -54,11 +54,15 @@ module.exports = __toCommonJS(src_exports);
 var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
 function createMinipimClient(opts) {
   const headers = {
-    "x-organization-id": opts.organizationId,
+    // Conditional rather than relying on openapi-fetch to drop the undefined.
+    // It does (mergeHeaders skips undefined values), so this is belt-and-braces
+    // for the type, not a behaviour change — but it keeps the intent local
+    // instead of depending on a transitive dependency's merge semantics.
+    ...opts.organizationId ? { "x-organization-id": opts.organizationId } : {},
     ...opts.headers ?? {}
   };
   if (opts.apiKey) headers["Authorization"] = `Bearer ${opts.apiKey}`;
-  if (opts.userId) headers["x-pim-user-id"] = opts.userId;
+  if (opts.userId) headers["x-user-id"] = opts.userId;
   return (0, import_openapi_fetch.default)({
     baseUrl: opts.baseUrl.replace(/\/$/, ""),
     fetch: opts.fetch,

package/dist/index.d.cts

@@ -18,11 +18,16 @@ interface CreateMinipimClientOptions {
      */
     baseUrl: string;
     /**
-     * Tenant the client speaks for. Required — every authenticated endpoint
-     * needs `x-organization-id`. API keys identify the principal, not the
-     * tenant.
+     * Tenant the client speaks for, sent as `x-organization-id`.
+     *
+     * Optional when `apiKey` is set: an API key carries its own tenant, and the
+     * server resolves the org from the key row and ignores this header entirely
+     * (see the api-key auth provider — it returns the key's `organizationId`,
+     * and the auth plugin short-circuits before it ever reads the header).
+     *
+     * Required for session/`header`-mode auth, where the caller asserts the org.
      */
-    organizationId: string;
+    organizationId?: string;
     /**
      * Bearer API key (e.g. `pim_abc123…`). Issue one in the admin under
      * /api-keys. If you're running in dev with `PIM_AUTH=header`, omit this
@@ -30,8 +35,10 @@ interface CreateMinipimClientOptions {
      */
     apiKey?: string;
     /**
-     * Dev-only header (`x-pim-user-id`). Only set when the deployment is in
-     * `header` auth mode. Ignored in `jwt` / `clerk` deployments.
+     * Dev-only header (`x-user-id`). Only set when the deployment is in `header`
+     * auth mode, where it must be paired with `organizationId`. Ignored in
+     * `jwt` / `clerk` deployments. The instance falls back to its own
+     * `defaultUserSubject` when this is absent.
      */
     userId?: string;
     /**

package/dist/index.d.ts

@@ -18,11 +18,16 @@ interface CreateMinipimClientOptions {
      */
     baseUrl: string;
     /**
-     * Tenant the client speaks for. Required — every authenticated endpoint
-     * needs `x-organization-id`. API keys identify the principal, not the
-     * tenant.
+     * Tenant the client speaks for, sent as `x-organization-id`.
+     *
+     * Optional when `apiKey` is set: an API key carries its own tenant, and the
+     * server resolves the org from the key row and ignores this header entirely
+     * (see the api-key auth provider — it returns the key's `organizationId`,
+     * and the auth plugin short-circuits before it ever reads the header).
+     *
+     * Required for session/`header`-mode auth, where the caller asserts the org.
      */
-    organizationId: string;
+    organizationId?: string;
     /**
      * Bearer API key (e.g. `pim_abc123…`). Issue one in the admin under
      * /api-keys. If you're running in dev with `PIM_AUTH=header`, omit this
@@ -30,8 +35,10 @@ interface CreateMinipimClientOptions {
      */
     apiKey?: string;
     /**
-     * Dev-only header (`x-pim-user-id`). Only set when the deployment is in
-     * `header` auth mode. Ignored in `jwt` / `clerk` deployments.
+     * Dev-only header (`x-user-id`). Only set when the deployment is in `header`
+     * auth mode, where it must be paired with `organizationId`. Ignored in
+     * `jwt` / `clerk` deployments. The instance falls back to its own
+     * `defaultUserSubject` when this is absent.
      */
     userId?: string;
     /**

package/dist/index.js

@@ -2,11 +2,15 @@
 import createClient from "openapi-fetch";
 function createMinipimClient(opts) {
   const headers = {
-    "x-organization-id": opts.organizationId,
+    // Conditional rather than relying on openapi-fetch to drop the undefined.
+    // It does (mergeHeaders skips undefined values), so this is belt-and-braces
+    // for the type, not a behaviour change — but it keeps the intent local
+    // instead of depending on a transitive dependency's merge semantics.
+    ...opts.organizationId ? { "x-organization-id": opts.organizationId } : {},
     ...opts.headers ?? {}
   };
   if (opts.apiKey) headers["Authorization"] = `Bearer ${opts.apiKey}`;
-  if (opts.userId) headers["x-pim-user-id"] = opts.userId;
+  if (opts.userId) headers["x-user-id"] = opts.userId;
   return createClient({
     baseUrl: opts.baseUrl.replace(/\/$/, ""),
     fetch: opts.fetch,