@minipim/sdk 0.6.0 → 0.8.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,72 @@ 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.
+
+## Ordering a content archive (API 0.19.0+)
+
+`GET /v1/content` defaults to `updatedAt` descending — the order things were last *edited*, which is rarely the order an archive should read in. Sort by `publishedAt`, which imports preserve from the source system:
+
+```ts
+const { data } = await pim.GET('/v1/content', {
+  params: { query: { sortBy: 'publishedAt', sortDir: 'desc', limit: 20 } },
+});
+```
+
+Pages with no `publishedAt` sort **last in both directions** — an undated page is unscheduled, not newest. `sortBy` also accepts `updatedAt`, `createdAt` and `title`.
+
+`categoryId` behaves exactly like it does on products: **self-only** unless you add `includeDescendants: true`. Content gets filed against leaf categories too, so filtering by a parent section returns an empty page without it.
+
+## 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, so passing a real object rather than a string stores no alt text. Send `JSON.stringify(...)`.
+
+That case no longer fails silently. From API **0.21.0** a malformed `altText` still lets the upload succeed — it never fails the request — but the response says what it ignored:
+
+```ts
+const { data } = await pim.POST('/v1/media', { body: form as never });
+if (data?.warnings?.length) console.warn(data.warnings);
+// ["altText was not valid JSON and no alt text was stored; expected an object keyed by locale, …"]
+```
+
+`warnings` is absent when there is nothing to report, so a clean upload's response is unchanged.
+
+**You do not have to get the content type right.** From API **0.21.0** the leading bytes are sniffed whenever you send `application/octet-stream` or no type at all — so a PNG whose filename lost its extension uploads as a PNG. If a specific declared type contradicts the bytes, the bytes win. SVG, CSV, plain text and the Office formats have no distinguishing magic bytes and still need an explicit type.
+
+`role` and `position` are validated: an unrecognised value is a 422 listing the accepted ones in `details.accepted`, not a 500.
+
+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.d.cts

@@ -78,12 +78,17 @@ declare function createMinipimClient(opts: CreateMinipimClientOptions): MinipimC
 
 /**
  * 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.
+ * `{ 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

@@ -78,12 +78,17 @@ declare function createMinipimClient(opts: CreateMinipimClientOptions): MinipimC
 
 /**
  * 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.
+ * `{ 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/openapi.d.cts

@@ -914,11 +914,6 @@ interface paths {
                 content: {
                     "application/json": {
                         code?: string;
-                        /**
-                         * @default product
-                         * @enum {string}
-                         */
-                        entityKind?: "product" | "content";
                         label?: {
                             [key: string]: string;
                         };
@@ -1575,6 +1570,7 @@ interface paths {
                     categoryId?: string;
                     includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     brand?: string;
+                    /** @description Repeatable — `?tag=a&tag=b` matches records carrying ALL listed tags. Values are canonicalized exactly as writes are, so `?tag=Buying%20Guide` matches the stored `buying-guide`; you never have to pre-slugify a filter. Backed by the GIN index on `tags`. */
                     tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
@@ -1621,6 +1617,7 @@ interface paths {
                                 attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                     [key: string]: unknown;
                                 };
+                                /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                                 tags: string[];
                                 /** Format: uuid */
                                 createdBy: string | null;
@@ -1631,7 +1628,7 @@ interface paths {
                             }[];
                             limit: number;
                             offset: number;
-                            hasMore?: boolean;
+                            hasMore: boolean;
                             total?: number;
                         };
                     };
@@ -1670,7 +1667,10 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
-                        /** @default [] */
+                        /**
+                         * @description Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one.
+                         * @default []
+                         */
                         tags?: string[];
                     };
                 };
@@ -1700,6 +1700,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -1766,6 +1767,7 @@ interface paths {
                     categoryId?: string;
                     includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     brand?: string;
+                    /** @description Repeatable — `?tag=a&tag=b` matches records carrying ALL listed tags. Values are canonicalized exactly as writes are, so `?tag=Buying%20Guide` matches the stored `buying-guide`; you never have to pre-slugify a filter. Backed by the GIN index on `tags`. */
                     tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
@@ -1985,6 +1987,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -2108,6 +2111,7 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
+                        /** @description Replaces the full tag list when present. Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one. */
                         tags?: string[];
                     };
                 };
@@ -2137,6 +2141,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -2304,6 +2309,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -2710,6 +2716,7 @@ interface paths {
                         productIds: string[];
                         /** @enum {string} */
                         mode: "add" | "remove" | "replace";
+                        /** @description Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one. */
                         tags: string[];
                     };
                 };
@@ -3514,6 +3521,16 @@ interface paths {
         /**
          * List content pages
          * @description Filters and pagination mirror `GET /v1/products`. `tag` is repeatable and matches pages carrying ALL listed tags.
+         *
+         *     Ordering defaults to `updatedAt` descending. For a blog archive sort by `publishedAt`, which imports preserve from the source system:
+         *
+         *     ```
+         *     curl 'https://api.minipim.com/v1/content?sortBy=publishedAt&sortDir=desc&limit=20'
+         *     ```
+         *
+         *     Pages with no `publishedAt` sort LAST in both directions — an undated page is unscheduled, not newest.
+         *
+         *     `categoryId` is SELF-ONLY. Content is filed against leaf categories, so filtering by a parent returns an empty page unless you add `includeDescendants=true` to match the whole subtree.
          */
         get: {
             parameters: {
@@ -3522,9 +3539,13 @@ interface paths {
                     q?: string;
                     familyId?: string;
                     categoryId?: string;
+                    includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     channelId?: string;
+                    /** @description Repeatable — `?tag=a&tag=b` matches records carrying ALL listed tags. Values are canonicalized exactly as writes are, so `?tag=Buying%20Guide` matches the stored `buying-guide`; you never have to pre-slugify a filter. */
                     tag?: string | string[];
                     updatedSince?: string;
+                    sortBy?: "publishedAt" | "updatedAt" | "createdAt" | "title";
+                    sortDir?: "asc" | "desc";
                     limit?: number;
                     offset?: number;
                 };
@@ -3563,6 +3584,7 @@ interface paths {
                                 attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                     [key: string]: unknown;
                                 };
+                                /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                                 tags: string[];
                                 /** Format: uuid */
                                 createdBy: string | null;
@@ -3571,8 +3593,7 @@ interface paths {
                             }[];
                             limit: number;
                             offset: number;
-                            hasMore?: boolean;
-                            total?: number;
+                            hasMore: boolean;
                         };
                     };
                 };
@@ -3629,7 +3650,10 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
-                        /** @default [] */
+                        /**
+                         * @description Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one.
+                         * @default []
+                         */
                         tags?: string[];
                     };
                 };
@@ -3663,6 +3687,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -3739,6 +3764,63 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/content/tags": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List all content-page tags in use, with counts
+         * @description Every distinct tag currently on at least one content page, ordered by usage. Powers tag autocomplete in the editor, which is what keeps a vocabulary from drifting into `guide` / `guides` / `Guides`. Filter pages by tag with `GET /v1/content?tag=<tag>` (repeatable; multiple tags AND together).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            value: string;
+                            count: number;
+                        }[];
+                    };
+                };
+                /** @description Default Response */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/content/{id}": {
         parameters: {
             query?: never;
@@ -3786,6 +3868,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -3918,6 +4001,7 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
+                        /** @description Replaces the full tag list when present. Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one. */
                         tags?: string[];
                     };
                 };
@@ -3951,6 +4035,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -5913,7 +5998,44 @@ interface paths {
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody: {
+                content: {
+                    "multipart/form-data": {
+                        /**
+                         * Format: binary
+                         * @description The file to upload. Images, video, PDF, Office documents and glTF are accepted; the 422 response lists every allowed type in `details.allowed`. You do NOT have to get the content type right: when you send `application/octet-stream` (or no type at all), the leading bytes are sniffed and the detected type is used — so a PNG whose filename lost its extension uploads fine. SVG, CSV, plain text and Office formats have no distinguishing magic bytes and still need an explicit type. If a specific declared type contradicts the bytes, the bytes win.
+                         */
+                        file: string;
+                        /**
+                         * @description Attach the upload in the same transaction. Requires `entityId`; supplying only one of the pair uploads the file WITHOUT associating it. A value outside the enum is a 422, not a silent miss.
+                         * @enum {string}
+                         */
+                        entityType?: "product" | "variant" | "content_page";
+                        /**
+                         * Format: uuid
+                         * @description The id of the entity named by `entityType`.
+                         */
+                        entityId?: string;
+                        /**
+                         * @description Association role. Ignored unless `entityType`+`entityId` are present. A value outside this enum is rejected with a 422 that lists the accepted values in `details.accepted`.
+                         * @default gallery
+                         * @enum {string}
+                         */
+                        role?: "hero" | "gallery" | "thumbnail" | "technical" | "lifestyle" | "swatch";
+                        /**
+                         * @description Sort position within the entity’s gallery. Must be a non-negative integer; anything else is a 422.
+                         * @default 0
+                         */
+                        position?: number;
+                        /**
+                         * @description A JSON OBJECT keyed by locale, sent as a STRING — e.g. `{"en_US":"Blue widget on white"}`. Unparseable JSON, or JSON that is not an object of locale → string, does NOT fail the upload: the file is stored, no alt text is saved, and the 201 response carries a `warnings` entry saying so. Check `warnings` if you send alt text programmatically. Omit the field entirely if you have none.
+                         *
+                         *     (0.20.0 briefly made this a 422; 0.21.0 restored the original behaviour and added `warnings` instead, so the problem is reported without breaking callers.)
+                         */
+                        altText?: string;
+                    };
+                };
+            };
             responses: {
                 /** @description Default Response */
                 201: {
@@ -5966,6 +6088,8 @@ interface paths {
                                 channelId: string | null;
                             };
                             url: string;
+                            /** @description Non-fatal problems with this upload — currently only malformed `altText`. The upload succeeded; something you sent was ignored. Absent when there is nothing to report. */
+                            warnings?: string[];
                         };
                     };
                 };
@@ -5985,6 +6109,36 @@ interface paths {
                     };
                 };
                 /** @description Default Response */
+                413: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+                /** @description Default Response */
+                422: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+                /** @description Default Response */
                 503: {
                     headers: {
                         [name: string]: unknown;
@@ -7471,7 +7625,7 @@ interface paths {
                             availability: "oss" | "hosted";
                             capabilities: {
                                 /** @enum {string} */
-                                entity: "product" | "variant" | "media" | "category";
+                                entity: "product" | "variant" | "media" | "category" | "content_page";
                                 /** @enum {string} */
                                 direction: "push" | "pull" | "bidirectional";
                             }[];
@@ -8934,11 +9088,12 @@ interface paths {
                                 }) | null;
                                 /** Format: date-time */
                                 createdAt: string;
+                                /** @description Display name for the actor: the user’s name or email for `user` rows, the connector’s name for `connector` rows, null when the actor is unattributed (`system`) or no longer resolvable. */
+                                actorLabel: string | null;
                             }[];
                             limit: number;
                             offset: number;
-                            hasMore?: boolean;
-                            total?: number;
+                            hasMore: boolean;
                         };
                     };
                 };

package/dist/openapi.d.ts

@@ -914,11 +914,6 @@ interface paths {
                 content: {
                     "application/json": {
                         code?: string;
-                        /**
-                         * @default product
-                         * @enum {string}
-                         */
-                        entityKind?: "product" | "content";
                         label?: {
                             [key: string]: string;
                         };
@@ -1575,6 +1570,7 @@ interface paths {
                     categoryId?: string;
                     includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     brand?: string;
+                    /** @description Repeatable — `?tag=a&tag=b` matches records carrying ALL listed tags. Values are canonicalized exactly as writes are, so `?tag=Buying%20Guide` matches the stored `buying-guide`; you never have to pre-slugify a filter. Backed by the GIN index on `tags`. */
                     tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
@@ -1621,6 +1617,7 @@ interface paths {
                                 attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                     [key: string]: unknown;
                                 };
+                                /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                                 tags: string[];
                                 /** Format: uuid */
                                 createdBy: string | null;
@@ -1631,7 +1628,7 @@ interface paths {
                             }[];
                             limit: number;
                             offset: number;
-                            hasMore?: boolean;
+                            hasMore: boolean;
                             total?: number;
                         };
                     };
@@ -1670,7 +1667,10 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
-                        /** @default [] */
+                        /**
+                         * @description Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one.
+                         * @default []
+                         */
                         tags?: string[];
                     };
                 };
@@ -1700,6 +1700,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -1766,6 +1767,7 @@ interface paths {
                     categoryId?: string;
                     includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     brand?: string;
+                    /** @description Repeatable — `?tag=a&tag=b` matches records carrying ALL listed tags. Values are canonicalized exactly as writes are, so `?tag=Buying%20Guide` matches the stored `buying-guide`; you never have to pre-slugify a filter. Backed by the GIN index on `tags`. */
                     tag?: string | string[];
                     connectorId?: string;
                     updatedSince?: string;
@@ -1985,6 +1987,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -2108,6 +2111,7 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
+                        /** @description Replaces the full tag list when present. Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one. */
                         tags?: string[];
                     };
                 };
@@ -2137,6 +2141,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -2304,6 +2309,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -2710,6 +2716,7 @@ interface paths {
                         productIds: string[];
                         /** @enum {string} */
                         mode: "add" | "remove" | "replace";
+                        /** @description Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one. */
                         tags: string[];
                     };
                 };
@@ -3514,6 +3521,16 @@ interface paths {
         /**
          * List content pages
          * @description Filters and pagination mirror `GET /v1/products`. `tag` is repeatable and matches pages carrying ALL listed tags.
+         *
+         *     Ordering defaults to `updatedAt` descending. For a blog archive sort by `publishedAt`, which imports preserve from the source system:
+         *
+         *     ```
+         *     curl 'https://api.minipim.com/v1/content?sortBy=publishedAt&sortDir=desc&limit=20'
+         *     ```
+         *
+         *     Pages with no `publishedAt` sort LAST in both directions — an undated page is unscheduled, not newest.
+         *
+         *     `categoryId` is SELF-ONLY. Content is filed against leaf categories, so filtering by a parent returns an empty page unless you add `includeDescendants=true` to match the whole subtree.
          */
         get: {
             parameters: {
@@ -3522,9 +3539,13 @@ interface paths {
                     q?: string;
                     familyId?: string;
                     categoryId?: string;
+                    includeDescendants?: boolean | ("true" | "false" | "1" | "0");
                     channelId?: string;
+                    /** @description Repeatable — `?tag=a&tag=b` matches records carrying ALL listed tags. Values are canonicalized exactly as writes are, so `?tag=Buying%20Guide` matches the stored `buying-guide`; you never have to pre-slugify a filter. */
                     tag?: string | string[];
                     updatedSince?: string;
+                    sortBy?: "publishedAt" | "updatedAt" | "createdAt" | "title";
+                    sortDir?: "asc" | "desc";
                     limit?: number;
                     offset?: number;
                 };
@@ -3563,6 +3584,7 @@ interface paths {
                                 attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                     [key: string]: unknown;
                                 };
+                                /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                                 tags: string[];
                                 /** Format: uuid */
                                 createdBy: string | null;
@@ -3571,8 +3593,7 @@ interface paths {
                             }[];
                             limit: number;
                             offset: number;
-                            hasMore?: boolean;
-                            total?: number;
+                            hasMore: boolean;
                         };
                     };
                 };
@@ -3629,7 +3650,10 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
-                        /** @default [] */
+                        /**
+                         * @description Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one.
+                         * @default []
+                         */
                         tags?: string[];
                     };
                 };
@@ -3663,6 +3687,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -3739,6 +3764,63 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/content/tags": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List all content-page tags in use, with counts
+         * @description Every distinct tag currently on at least one content page, ordered by usage. Powers tag autocomplete in the editor, which is what keeps a vocabulary from drifting into `guide` / `guides` / `Guides`. Filter pages by tag with `GET /v1/content?tag=<tag>` (repeatable; multiple tags AND together).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            value: string;
+                            count: number;
+                        }[];
+                    };
+                };
+                /** @description Default Response */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/content/{id}": {
         parameters: {
             query?: never;
@@ -3786,6 +3868,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -3918,6 +4001,7 @@ interface paths {
                                 value?: unknown;
                             }[];
                         };
+                        /** @description Replaces the full tag list when present. Free-form tags, canonicalized on write and echoed back in canonical form — the response will NOT match your input verbatim. Each tag is lower-cased, stripped of diacritics, has every run of non-alphanumerics replaced with `-`, is trimmed of leading/trailing `-`, and is then truncated to 60 characters. So `"Buying Guide"` is stored and filtered as `buying-guide`. Tags that normalize to nothing (`""`, `"!!"`) are dropped, and duplicates are removed keeping first-occurrence order, so the array you get back may be SHORTER than the one you sent. Note the asymmetry with `maxLength`: an item may be up to 80 characters on input but is truncated to 60 once canonicalized, which can collapse two long tags into one. */
                         tags?: string[];
                     };
                 };
@@ -3951,6 +4035,7 @@ interface paths {
                             attributes: (string | number | boolean | ("null" | null)) | unknown[] | {
                                 [key: string]: unknown;
                             };
+                            /** @description Tags in canonical form. These are normalized on write (lower-cased, slugified, deduplicated, truncated), so this array will not necessarily match what was submitted — see the `tags` field on the create/update request body for the exact rules. Filter with `?tag=` using either form. */
                             tags: string[];
                             /** Format: uuid */
                             createdBy: string | null;
@@ -5913,7 +5998,44 @@ interface paths {
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody: {
+                content: {
+                    "multipart/form-data": {
+                        /**
+                         * Format: binary
+                         * @description The file to upload. Images, video, PDF, Office documents and glTF are accepted; the 422 response lists every allowed type in `details.allowed`. You do NOT have to get the content type right: when you send `application/octet-stream` (or no type at all), the leading bytes are sniffed and the detected type is used — so a PNG whose filename lost its extension uploads fine. SVG, CSV, plain text and Office formats have no distinguishing magic bytes and still need an explicit type. If a specific declared type contradicts the bytes, the bytes win.
+                         */
+                        file: string;
+                        /**
+                         * @description Attach the upload in the same transaction. Requires `entityId`; supplying only one of the pair uploads the file WITHOUT associating it. A value outside the enum is a 422, not a silent miss.
+                         * @enum {string}
+                         */
+                        entityType?: "product" | "variant" | "content_page";
+                        /**
+                         * Format: uuid
+                         * @description The id of the entity named by `entityType`.
+                         */
+                        entityId?: string;
+                        /**
+                         * @description Association role. Ignored unless `entityType`+`entityId` are present. A value outside this enum is rejected with a 422 that lists the accepted values in `details.accepted`.
+                         * @default gallery
+                         * @enum {string}
+                         */
+                        role?: "hero" | "gallery" | "thumbnail" | "technical" | "lifestyle" | "swatch";
+                        /**
+                         * @description Sort position within the entity’s gallery. Must be a non-negative integer; anything else is a 422.
+                         * @default 0
+                         */
+                        position?: number;
+                        /**
+                         * @description A JSON OBJECT keyed by locale, sent as a STRING — e.g. `{"en_US":"Blue widget on white"}`. Unparseable JSON, or JSON that is not an object of locale → string, does NOT fail the upload: the file is stored, no alt text is saved, and the 201 response carries a `warnings` entry saying so. Check `warnings` if you send alt text programmatically. Omit the field entirely if you have none.
+                         *
+                         *     (0.20.0 briefly made this a 422; 0.21.0 restored the original behaviour and added `warnings` instead, so the problem is reported without breaking callers.)
+                         */
+                        altText?: string;
+                    };
+                };
+            };
             responses: {
                 /** @description Default Response */
                 201: {
@@ -5966,6 +6088,8 @@ interface paths {
                                 channelId: string | null;
                             };
                             url: string;
+                            /** @description Non-fatal problems with this upload — currently only malformed `altText`. The upload succeeded; something you sent was ignored. Absent when there is nothing to report. */
+                            warnings?: string[];
                         };
                     };
                 };
@@ -5985,6 +6109,36 @@ interface paths {
                     };
                 };
                 /** @description Default Response */
+                413: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+                /** @description Default Response */
+                422: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: {
+                                code: string;
+                                message: string;
+                                details?: unknown;
+                            };
+                        };
+                    };
+                };
+                /** @description Default Response */
                 503: {
                     headers: {
                         [name: string]: unknown;
@@ -7471,7 +7625,7 @@ interface paths {
                             availability: "oss" | "hosted";
                             capabilities: {
                                 /** @enum {string} */
-                                entity: "product" | "variant" | "media" | "category";
+                                entity: "product" | "variant" | "media" | "category" | "content_page";
                                 /** @enum {string} */
                                 direction: "push" | "pull" | "bidirectional";
                             }[];
@@ -8934,11 +9088,12 @@ interface paths {
                                 }) | null;
                                 /** Format: date-time */
                                 createdAt: string;
+                                /** @description Display name for the actor: the user’s name or email for `user` rows, the connector’s name for `connector` rows, null when the actor is unattributed (`system`) or no longer resolvable. */
+                                actorLabel: string | null;
                             }[];
                             limit: number;
                             offset: number;
-                            hasMore?: boolean;
-                            total?: number;
+                            hasMore: boolean;
                         };
                     };
                 };

package/package.json

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