@minipim/sdk 0.7.0 → 0.8.0

package/README.md

@@ -192,6 +192,20 @@ await pim.GET('/v1/content', { params: { query: { tag: 'Buying Guide' } } }); //
 
 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:
@@ -205,7 +219,21 @@ form.append('role', 'technical');           // hero | gallery | thumbnail | tech
 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(...)`.
+`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.
 

package/dist/openapi.d.cts

@@ -3521,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: {
@@ -3529,10 +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;
                 };
@@ -5990,11 +6003,11 @@ interface paths {
                     "multipart/form-data": {
                         /**
                          * Format: binary
-                         * @description The file to upload. Images, video and PDF are accepted; see the 400 response for the rejected-mime and blocked-extension cases.
+                         * @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.
+                         * @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";
@@ -6004,17 +6017,21 @@ interface paths {
                          */
                         entityId?: string;
                         /**
-                         * @description Association role. Ignored unless `entityType`+`entityId` are present.
+                         * @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.
+                         * @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 is ignored rather than rejected, so malformed alt text costs you the alt text, not the upload. */
+                        /**
+                         * @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;
                     };
                 };
@@ -6071,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[];
                         };
                     };
                 };
@@ -6090,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;
@@ -9039,6 +9088,8 @@ 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;

package/dist/openapi.d.ts

@@ -3521,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: {
@@ -3529,10 +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;
                 };
@@ -5990,11 +6003,11 @@ interface paths {
                     "multipart/form-data": {
                         /**
                          * Format: binary
-                         * @description The file to upload. Images, video and PDF are accepted; see the 400 response for the rejected-mime and blocked-extension cases.
+                         * @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.
+                         * @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";
@@ -6004,17 +6017,21 @@ interface paths {
                          */
                         entityId?: string;
                         /**
-                         * @description Association role. Ignored unless `entityType`+`entityId` are present.
+                         * @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.
+                         * @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 is ignored rather than rejected, so malformed alt text costs you the alt text, not the upload. */
+                        /**
+                         * @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;
                     };
                 };
@@ -6071,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[];
                         };
                     };
                 };
@@ -6090,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;
@@ -9039,6 +9088,8 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minipim/sdk",
-  "version": "0.7.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",