@minipim/sdk 0.5.0 → 0.7.0

package/README.md

@@ -126,7 +126,11 @@ for await (const p of paginate<Product>(pim, '/v1/products', { query: { status:
 const all = await collectAll<Product>(pim, '/v1/products');
 ```
 
-`paginate` manages `limit`/`offset`, honors the server's `hasMore`, and defaults to the 200-row max page size (override with `pageSize`). Pass `withTotal: true` in `query` if you need `total` — it adds one `COUNT(*)`, so leave it off on hot reads.
+`paginate` manages `limit`/`offset`, honors the server's `hasMore`, and defaults to the 200-row max page size (override with `pageSize`).
+
+`withTotal: true` is supported by **`/v1/products` only** — it adds one `COUNT(*)`, so leave it off on hot reads. Other list endpoints never return `total`, and as of v0.7.0 their types say so rather than declaring a field that was always `undefined`.
+
+Against API **0.14.0 and newer, `hasMore` is present and exact on every list endpoint** — the server reads one row past the page, so a final page that happens to be exactly full reports `false` instead of sending you after an empty one. Older deployments omitted `hasMore` everywhere except `/v1/products`; `paginate` keeps a short-page fallback for those, which is the whole reason not to hand-roll the loop.
 
 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.
 
@@ -167,6 +171,44 @@ await pim.GET('/v1/products', {
 
 Needs API **0.9.0+**. Check `GET /healthz`.
 
+## Tags
+
+Tags are **canonicalized on write**, so what you read back is not verbatim what you sent:
+
+```ts
+await pim.POST('/v1/content', { body: { /* … */ tags: ['Buying Guide', 'buying guide', 'FAQ!'] } });
+// stored, and returned as: ['buying-guide', 'faq']
+```
+
+Each tag is lower-cased, stripped of diacritics, has runs of non-alphanumerics collapsed to `-`, is trimmed of leading/trailing `-`, and is truncated to **60 characters**. Empties are dropped and duplicates removed (first occurrence wins), so **the array you get back can be shorter than the one you sent**. Note that the schema's `maxLength` is 80: two tags differing only past character 60 collapse into one.
+
+This is deliberate — it is what makes `Featured`, `featured` and `FEATURED` one tag rather than three. Filters are canonicalized identically, so you never have to pre-slugify one:
+
+```ts
+await pim.GET('/v1/content', { params: { query: { tag: 'Buying Guide' } } }); // matches buying-guide
+```
+
+`tag` is repeatable and ANDs: `{ tag: ['guide', 'seo'] }` returns only pages carrying both. `GET /v1/products/tags` and `GET /v1/content/tags` list the vocabulary actually in use, with counts — two **separate** vocabularies, since an editorial tag and a merchandising tag rarely mean the same thing.
+
+Documented in the field descriptions from API **0.14.1+**, and in these types from v0.7.0.
+
+## Uploading files
+
+`POST /v1/media` is `multipart/form-data`, not JSON. The file field is named `file`; everything else is optional and lets you attach the upload in the same request:
+
+```ts
+const form = new FormData();
+form.append('file', blob, 'sell-sheet.pdf');
+form.append('entityType', 'product');       // 'product' | 'variant' | 'content_page'
+form.append('entityId', productId);
+form.append('role', 'technical');           // hero | gallery | thumbnail | technical | lifestyle | swatch
+form.append('altText', JSON.stringify({ en_US: 'Sell sheet' })); // a JSON *string*, not an object
+```
+
+`altText` is parsed as JSON and parse failures are swallowed, so passing a real object silently stores no alt text. Send `JSON.stringify(...)`.
+
+Requires API **0.14.0+** to appear in the spec at all — before that this endpoint published no request body, so generated clients had nothing for it.
+
 ## 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,18 @@ 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, hasMore }`, where `hasMore` is always present and
+ * exact — the server fetches one row past the page to decide it, so a final
+ * page that is exactly full reports `false` instead of sending you after an
+ * empty one. Yields one item at a time.
+ *
+ * `hasMore` stays OPTIONAL in the type below, and the short-page fallback
+ * stays, deliberately: this client talks to whatever version the deployment is
+ * running, and API ≤ 0.13.0 omitted the field everywhere except
+ * `/v1/products`. Keeping the fallback means an older instance paginates
+ * correctly rather than reading one page and stopping — which is exactly the
+ * bug a hand-rolled `while (hasMore)` loop hit against those versions.
  *
  * 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,18 @@ 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, hasMore }`, where `hasMore` is always present and
+ * exact — the server fetches one row past the page to decide it, so a final
+ * page that is exactly full reports `false` instead of sending you after an
+ * empty one. Yields one item at a time.
+ *
+ * `hasMore` stays OPTIONAL in the type below, and the short-page fallback
+ * stays, deliberately: this client talks to whatever version the deployment is
+ * running, and API ≤ 0.13.0 omitted the field everywhere except
+ * `/v1/products`. Keeping the fallback means an older instance paginates
+ * correctly rather than reading one page and stopping — which is exactly the
+ * bug a hand-rolled `while (hasMore)` loop hit against those versions.
  *
  * 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;