@minipim/sdk 0.7.0 → 0.9.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.