@datocms/cma-client 5.4.3 → 5.4.4

package/README.md

@@ -296,6 +296,61 @@ async function duplicateBlockRecord<D extends ItemTypeDefinition>(
 **Returns:** New block record without IDs, ready to be created
 </details>
 
+### Narrowing Block Types
+
+#### isBlockOfType()
+
+Builds a type guard that narrows a union of block shapes to the one matching a given model. Meant for `Array#filter` / `Array#find` over block-bearing fields — either nested-response arrays (from `client.items.find(..., { nested: true })`) or request-payload arrays you're inspecting before sending.
+
+TypeScript doesn't auto-narrow on discriminators buried in nested properties, so the natural-looking check `block.relationships.item_type.data.id === SOME_ID` won't narrow the block's type. This guard does the walk and returns a proper type-guard predicate.
+
+<details>
+<summary>View details</summary>
+
+**TypeScript Signature:**
+```typescript
+function isBlockOfType<Id extends string>(
+  itemTypeId: Id,
+): <T>(block: T) => block is NarrowBlockByItemType<T, Id>
+
+type NarrowBlockByItemType<T, Id extends string> = Extract<
+  T,
+  { relationships: { item_type: { data: { type: 'item_type'; id: Id } } } }
+>
+```
+
+**Parameters:**
+- `itemTypeId`: The item-type ID literal. For narrowing to work, the argument must be typed as a literal — use `as const` on pre-set ID constants. No `ItemTypeDefinition` type parameter is needed: `Extract` walks the input union using just the ID.
+
+**Returns:** A predicate `(block) => block is D-typed-block` that:
+- Narrows blocks carrying `relationships.item_type.data.id` — that covers `BlockInNestedResponse<D>` and the object variants of `BlockInRequest<D>` (`UpdatedBlockInRequest`, `NewBlockInRequest`).
+- Returns `false` for plain string IDs (unchanged-reference form in request payloads) and for any non-block input.
+
+The default (non-nested) response shape, where block fields are arrays of plain string IDs, is deliberately not supported — there's no way to recover the type from an ID alone.
+
+**Usage Example:**
+```typescript
+import { isBlockOfType } from '@datocms/cma-client';
+
+// ID of the ImageBlock model, one of several allowed inside Article `content`
+const IMAGE_BLOCK_ID = 'FJM79jjKRMSVg-fR6k6X2A' as const;
+
+const article = await client.items.find<Schema.Article>(articleId, { nested: true });
+
+// Before: inline === check does not narrow
+const images = article.content.filter(
+  (b) => b.relationships.item_type.data.id === IMAGE_BLOCK_ID,
+);
+images[0].attributes.upload_id; // ❌ property does not exist on union
+
+// After: guard narrows the filter result
+const images = article.content.filter(isBlockOfType(IMAGE_BLOCK_ID));
+images[0].attributes.upload_id; // ✅ narrowed
+```
+
+Use the `__itemTypeId` discriminator for inline `if` / `switch` narrowing on a single value — that's simpler and doesn't need a helper. Reach for `isBlockOfType` when you need a predicate for `.filter` / `.find`.
+</details>
+
 ### Recursive Block Operations
 
 DatoCMS supports three field types that can contain blocks: Modular Content (arrays of blocks), Single Block fields, and Structured Text (rich-text with embedded blocks). These functions abstract away the differences between field types and can traverse blocks recursively, processing nested blocks within blocks. They require a `SchemaRepository` instance to look up field definitions for nested blocks.

package/dist/cjs/generated/Client.js

@@ -90,7 +90,7 @@ class Client {
         return this.config.baseUrl || Client.defaultBaseUrl;
     }
     request(options) {
-        return (0, rest_client_utils_1.request)(Object.assign(Object.assign(Object.assign({}, this.config), options), { logFn: this.config.logFn || console.log, userAgent: '@datocms/cma-client v5.4.3', baseUrl: this.baseUrl, preCallStack: new Error().stack, extraHeaders: Object.assign(Object.assign(Object.assign({}, (this.config.extraHeaders || {})), (this.config.environment
+        return (0, rest_client_utils_1.request)(Object.assign(Object.assign(Object.assign({}, this.config), options), { logFn: this.config.logFn || console.log, userAgent: '@datocms/cma-client v5.4.4', baseUrl: this.baseUrl, preCallStack: new Error().stack, extraHeaders: Object.assign(Object.assign(Object.assign({}, (this.config.extraHeaders || {})), (this.config.environment
                 ? { 'X-Environment': this.config.environment }
                 : {})), { 'X-API-Version': '3' }), fetchJobResult: (jobId) => {
                 return this.jobResultsFetcher

package/dist/cjs/index.js

@@ -41,6 +41,7 @@ __exportStar(require("./utilities/duplicateBlockRecord"), exports);
 __exportStar(require("./utilities/fieldsContainingReferences"), exports);
 __exportStar(require("./utilities/id"), exports);
 __exportStar(require("./utilities/inspectItem"), exports);
+__exportStar(require("./utilities/isBlockOfType"), exports);
 __exportStar(require("./utilities/itemDefinition"), exports);
 __exportStar(require("./utilities/normalizedFieldValues"), exports);
 __exportStar(require("./utilities/recursiveBlocks"), exports);

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gEAA8E;AAArE,6GAAA,QAAQ,OAAA;AAAE,6GAAA,QAAQ,OAAA;AAAE,iHAAA,YAAY,OAAA;AACzC,gDAA8B;AAC9B,+CAA6B;AAC7B,6CAA4C;AAAnC,gGAAA,MAAM,OAAA;AAEf,mEAAmD;AACnD,+DAA6C;AAC7C,mEAAiD;AACjD,yEAAuD;AACvD,iDAA+B;AAC/B,0DAAwC;AACxC,6DAA2C;AAC3C,oEAAkD;AAClD,8DAA4C;AAC5C,+DAA6C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gEAA8E;AAArE,6GAAA,QAAQ,OAAA;AAAE,6GAAA,QAAQ,OAAA;AAAE,iHAAA,YAAY,OAAA;AACzC,gDAA8B;AAC9B,+CAA6B;AAC7B,6CAA4C;AAAnC,gGAAA,MAAM,OAAA;AAEf,mEAAmD;AACnD,+DAA6C;AAC7C,mEAAiD;AACjD,yEAAuD;AACvD,iDAA+B;AAC/B,0DAAwC;AACxC,4DAA0C;AAC1C,6DAA2C;AAC3C,oEAAkD;AAClD,8DAA4C;AAC5C,+DAA6C"}

package/dist/cjs/utilities/buildBlockRecord.js

@@ -27,11 +27,16 @@ exports.buildBlockRecord = void 0;
 const Utils = __importStar(require("@datocms/rest-client-utils"));
 const resources_1 = require("../generated/resources");
 function buildBlockRecord(body) {
-    return Utils.serializeRequestBody(body, {
+    const data = Utils.serializeRequestBody(body, {
         type: resources_1.Item.TYPE,
         attributes: '*',
         relationships: ['item_type'],
     }).data;
+    // Mirror the deserializer: expose `item_type.data.id` as a top-level
+    // `__itemTypeId` so locally-built blocks support the same TS narrowing
+    // pattern as blocks read from API responses. The field is TS-only and is
+    // stripped again by the serializer when the outer request is sent.
+    return Object.assign(Object.assign({}, data), { __itemTypeId: data.relationships.item_type.data.id });
 }
 exports.buildBlockRecord = buildBlockRecord;
 //# sourceMappingURL=buildBlockRecord.js.map

package/dist/cjs/utilities/buildBlockRecord.js.map

@@ -1 +1 @@
-{"version":3,"file":"buildBlockRecord.js","sourceRoot":"","sources":["../../../src/utilities/buildBlockRecord.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,kEAAoD;AAGpD,sDAA8C;AA6B9C,SAAgB,gBAAgB,CAG9B,IAEuC;IAEvC,OAAO,KAAK,CAAC,oBAAoB,CAE9B,IAAI,EAAE;QACP,IAAI,EAAE,gBAAI,CAAC,IAAI;QACf,UAAU,EAAE,GAAG;QACf,aAAa,EAAE,CAAC,WAAW,CAAC;KAC7B,CAAC,CAAC,IAAI,CAAC;AACV,CAAC;AAdD,4CAcC"}
+{"version":3,"file":"buildBlockRecord.js","sourceRoot":"","sources":["../../../src/utilities/buildBlockRecord.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,kEAAoD;AAGpD,sDAA8C;AA6B9C,SAAgB,gBAAgB,CAG9B,IAEuC;IAEvC,MAAM,IAAI,GAAG,KAAK,CAAC,oBAAoB,CAEpC,IAAI,EAAE;QACP,IAAI,EAAE,gBAAI,CAAC,IAAI;QACf,UAAU,EAAE,GAAG;QACf,aAAa,EAAE,CAAC,WAAW,CAAC;KAC7B,CAAC,CAAC,IAAI,CAAC;IAER,qEAAqE;IACrE,uEAAuE;IACvE,yEAAyE;IACzE,mEAAmE;IACnE,OAAO,gCACF,IAAI,KACP,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,GAClB,CAAC;AACrC,CAAC;AAvBD,4CAuBC"}

package/dist/cjs/utilities/isBlockOfType.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBlockOfType = void 0;
+/**
+ * Builds a type guard that narrows a block to a specific model.
+ *
+ * Call it with the block's `itemTypeId` literal — the ID generic is inferred
+ * from the argument, so no explicit type parameter is needed. The returned
+ * predicate is generic: given any input type `T`, it narrows to
+ * `Extract<T, { relationships: { item_type: { data: { id: Id } } } }>`. It's
+ * meant to plug into `Array#filter` / `Array#find` over block-bearing fields
+ * in any of these contexts:
+ *
+ * - `ItemInNestedResponse<D>` (responses with `nested: true`)
+ * - `ItemCreateSchema<D>` / `ItemUpdateSchema<D>` (request payloads, object
+ *   variants; plain string IDs are filtered out — there's no way to narrow
+ *   them without an external lookup)
+ *
+ * The default (non-nested) response shape, where block fields are arrays of
+ * plain string IDs, is deliberately not supported — the type information is
+ * not recoverable from an ID alone.
+ *
+ * For the literal `Id` to be preserved (and narrowing to work), the argument
+ * must be typed as a literal — use `as const` on pre-set ID constants.
+ *
+ * @example
+ * ```ts
+ * const SESSION_BLOCK_ID = 'abc123' as const;
+ *
+ * const record = await client.items.find<Schema.ConferenceDay>(id, { nested: true });
+ * const sessions = record.agenda.filter(isBlockOfType(SESSION_BLOCK_ID));
+ * sessions[0].attributes.signup_url; // OK — narrowed
+ * ```
+ */
+function isBlockOfType(itemTypeId) {
+    return (block) => {
+        if (typeof block !== 'object' || block === null)
+            return false;
+        const relationships = block.relationships;
+        if (typeof relationships !== 'object' || relationships === null)
+            return false;
+        const itemType = relationships.item_type;
+        if (typeof itemType !== 'object' || itemType === null)
+            return false;
+        const data = itemType.data;
+        if (typeof data !== 'object' || data === null)
+            return false;
+        return data.id === itemTypeId;
+    };
+}
+exports.isBlockOfType = isBlockOfType;
+//# sourceMappingURL=isBlockOfType.js.map

package/dist/cjs/utilities/isBlockOfType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isBlockOfType.js","sourceRoot":"","sources":["../../../src/utilities/isBlockOfType.ts"],"names":[],"mappings":";;;AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,SAAgB,aAAa,CAC3B,UAAc;IAEd,OAAO,CAAI,KAAQ,EAAyC,EAAE;QAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC9D,MAAM,aAAa,GAAI,KAAqC,CAAC,aAAa,CAAC;QAC3E,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,IAAI;YAC7D,OAAO,KAAK,CAAC;QACf,MAAM,QAAQ,GAAI,aAAyC,CAAC,SAAS,CAAC;QACtE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACpE,MAAM,IAAI,GAAI,QAA+B,CAAC,IAAI,CAAC;QACnD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC5D,OAAQ,IAAyB,CAAC,EAAE,KAAK,UAAU,CAAC;IACtD,CAAC,CAAC;AACJ,CAAC;AAdD,sCAcC"}

package/dist/esm/generated/Client.js

@@ -64,7 +64,7 @@ export class Client {
         return this.config.baseUrl || Client.defaultBaseUrl;
     }
     request(options) {
-        return request(Object.assign(Object.assign(Object.assign({}, this.config), options), { logFn: this.config.logFn || console.log, userAgent: '@datocms/cma-client v5.4.3', baseUrl: this.baseUrl, preCallStack: new Error().stack, extraHeaders: Object.assign(Object.assign(Object.assign({}, (this.config.extraHeaders || {})), (this.config.environment
+        return request(Object.assign(Object.assign(Object.assign({}, this.config), options), { logFn: this.config.logFn || console.log, userAgent: '@datocms/cma-client v5.4.4', baseUrl: this.baseUrl, preCallStack: new Error().stack, extraHeaders: Object.assign(Object.assign(Object.assign({}, (this.config.extraHeaders || {})), (this.config.environment
                 ? { 'X-Environment': this.config.environment }
                 : {})), { 'X-API-Version': '3' }), fetchJobResult: (jobId) => {
                 return this.jobResultsFetcher

package/dist/esm/generated/RawApiTypes.d.ts

@@ -6041,7 +6041,7 @@ export type FieldUpdateSchemaStableShell = {
     data: {
         type: FieldType;
         id: FieldIdentity;
-        attributes: {
+        attributes?: {
             /**
              * Default value for Field. When field is localized accepts an object of default values with site locales as keys
              */

package/dist/esm/index.d.ts

@@ -9,6 +9,7 @@ export * from './utilities/duplicateBlockRecord';
 export * from './utilities/fieldsContainingReferences';
 export * from './utilities/id';
 export * from './utilities/inspectItem';
+export * from './utilities/isBlockOfType';
 export * from './utilities/itemDefinition';
 export * from './utilities/normalizedFieldValues';
 export * from './utilities/recursiveBlocks';

package/dist/esm/index.js

@@ -8,6 +8,7 @@ export * from './utilities/duplicateBlockRecord';
 export * from './utilities/fieldsContainingReferences';
 export * from './utilities/id';
 export * from './utilities/inspectItem';
+export * from './utilities/isBlockOfType';
 export * from './utilities/itemDefinition';
 export * from './utilities/normalizedFieldValues';
 export * from './utilities/recursiveBlocks';

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC9E,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,wCAAwC,CAAC;AACvD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC9E,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,wCAAwC,CAAC;AACvD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC"}

package/dist/esm/utilities/buildBlockRecord.js

@@ -1,10 +1,15 @@
 import * as Utils from '@datocms/rest-client-utils';
 import { Item } from '../generated/resources';
 export function buildBlockRecord(body) {
-    return Utils.serializeRequestBody(body, {
+    const data = Utils.serializeRequestBody(body, {
         type: Item.TYPE,
         attributes: '*',
         relationships: ['item_type'],
     }).data;
+    // Mirror the deserializer: expose `item_type.data.id` as a top-level
+    // `__itemTypeId` so locally-built blocks support the same TS narrowing
+    // pattern as blocks read from API responses. The field is TS-only and is
+    // stripped again by the serializer when the outer request is sent.
+    return Object.assign(Object.assign({}, data), { __itemTypeId: data.relationships.item_type.data.id });
 }
 //# sourceMappingURL=buildBlockRecord.js.map

package/dist/esm/utilities/buildBlockRecord.js.map

@@ -1 +1 @@
-{"version":3,"file":"buildBlockRecord.js","sourceRoot":"","sources":["../../../src/utilities/buildBlockRecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,4BAA4B,CAAC;AAGpD,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AA6B9C,MAAM,UAAU,gBAAgB,CAG9B,IAEuC;IAEvC,OAAO,KAAK,CAAC,oBAAoB,CAE9B,IAAI,EAAE;QACP,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,UAAU,EAAE,GAAG;QACf,aAAa,EAAE,CAAC,WAAW,CAAC;KAC7B,CAAC,CAAC,IAAI,CAAC;AACV,CAAC"}
+{"version":3,"file":"buildBlockRecord.js","sourceRoot":"","sources":["../../../src/utilities/buildBlockRecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,4BAA4B,CAAC;AAGpD,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AA6B9C,MAAM,UAAU,gBAAgB,CAG9B,IAEuC;IAEvC,MAAM,IAAI,GAAG,KAAK,CAAC,oBAAoB,CAEpC,IAAI,EAAE;QACP,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,UAAU,EAAE,GAAG;QACf,aAAa,EAAE,CAAC,WAAW,CAAC;KAC7B,CAAC,CAAC,IAAI,CAAC;IAER,qEAAqE;IACrE,uEAAuE;IACvE,yEAAyE;IACzE,mEAAmE;IACnE,OAAO,gCACF,IAAI,KACP,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,GAClB,CAAC;AACrC,CAAC"}

package/dist/esm/utilities/isBlockOfType.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Narrows a union of block shapes to the member whose model (`item_type`)
+ * matches `Id`.
+ *
+ * Any object carrying `relationships.item_type.data.id` is narrowable —
+ * that covers blocks returned from `nested: true` responses as well as the
+ * object variants of request payloads (updated / newly-created blocks). The
+ * bare string IDs that may appear inside request payloads (to reference
+ * existing, unchanged blocks) are filtered out of the result.
+ */
+export type NarrowBlockByItemType<T, Id extends string> = Extract<T, {
+    relationships: {
+        item_type: {
+            data: {
+                type: 'item_type';
+                id: Id;
+            };
+        };
+    };
+}>;
+/**
+ * Builds a type guard that narrows a block to a specific model.
+ *
+ * Call it with the block's `itemTypeId` literal — the ID generic is inferred
+ * from the argument, so no explicit type parameter is needed. The returned
+ * predicate is generic: given any input type `T`, it narrows to
+ * `Extract<T, { relationships: { item_type: { data: { id: Id } } } }>`. It's
+ * meant to plug into `Array#filter` / `Array#find` over block-bearing fields
+ * in any of these contexts:
+ *
+ * - `ItemInNestedResponse<D>` (responses with `nested: true`)
+ * - `ItemCreateSchema<D>` / `ItemUpdateSchema<D>` (request payloads, object
+ *   variants; plain string IDs are filtered out — there's no way to narrow
+ *   them without an external lookup)
+ *
+ * The default (non-nested) response shape, where block fields are arrays of
+ * plain string IDs, is deliberately not supported — the type information is
+ * not recoverable from an ID alone.
+ *
+ * For the literal `Id` to be preserved (and narrowing to work), the argument
+ * must be typed as a literal — use `as const` on pre-set ID constants.
+ *
+ * @example
+ * ```ts
+ * const SESSION_BLOCK_ID = 'abc123' as const;
+ *
+ * const record = await client.items.find<Schema.ConferenceDay>(id, { nested: true });
+ * const sessions = record.agenda.filter(isBlockOfType(SESSION_BLOCK_ID));
+ * sessions[0].attributes.signup_url; // OK — narrowed
+ * ```
+ */
+export declare function isBlockOfType<Id extends string>(itemTypeId: Id): <T>(block: T) => block is NarrowBlockByItemType<T, Id>;

package/dist/esm/utilities/isBlockOfType.js

@@ -0,0 +1,48 @@
+/**
+ * Builds a type guard that narrows a block to a specific model.
+ *
+ * Call it with the block's `itemTypeId` literal — the ID generic is inferred
+ * from the argument, so no explicit type parameter is needed. The returned
+ * predicate is generic: given any input type `T`, it narrows to
+ * `Extract<T, { relationships: { item_type: { data: { id: Id } } } }>`. It's
+ * meant to plug into `Array#filter` / `Array#find` over block-bearing fields
+ * in any of these contexts:
+ *
+ * - `ItemInNestedResponse<D>` (responses with `nested: true`)
+ * - `ItemCreateSchema<D>` / `ItemUpdateSchema<D>` (request payloads, object
+ *   variants; plain string IDs are filtered out — there's no way to narrow
+ *   them without an external lookup)
+ *
+ * The default (non-nested) response shape, where block fields are arrays of
+ * plain string IDs, is deliberately not supported — the type information is
+ * not recoverable from an ID alone.
+ *
+ * For the literal `Id` to be preserved (and narrowing to work), the argument
+ * must be typed as a literal — use `as const` on pre-set ID constants.
+ *
+ * @example
+ * ```ts
+ * const SESSION_BLOCK_ID = 'abc123' as const;
+ *
+ * const record = await client.items.find<Schema.ConferenceDay>(id, { nested: true });
+ * const sessions = record.agenda.filter(isBlockOfType(SESSION_BLOCK_ID));
+ * sessions[0].attributes.signup_url; // OK — narrowed
+ * ```
+ */
+export function isBlockOfType(itemTypeId) {
+    return (block) => {
+        if (typeof block !== 'object' || block === null)
+            return false;
+        const relationships = block.relationships;
+        if (typeof relationships !== 'object' || relationships === null)
+            return false;
+        const itemType = relationships.item_type;
+        if (typeof itemType !== 'object' || itemType === null)
+            return false;
+        const data = itemType.data;
+        if (typeof data !== 'object' || data === null)
+            return false;
+        return data.id === itemTypeId;
+    };
+}
+//# sourceMappingURL=isBlockOfType.js.map

package/dist/esm/utilities/isBlockOfType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isBlockOfType.js","sourceRoot":"","sources":["../../../src/utilities/isBlockOfType.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAc;IAEd,OAAO,CAAI,KAAQ,EAAyC,EAAE;QAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC9D,MAAM,aAAa,GAAI,KAAqC,CAAC,aAAa,CAAC;QAC3E,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,IAAI;YAC7D,OAAO,KAAK,CAAC;QACf,MAAM,QAAQ,GAAI,aAAyC,CAAC,SAAS,CAAC;QACtE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QACpE,MAAM,IAAI,GAAI,QAA+B,CAAC,IAAI,CAAC;QACnD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAC5D,OAAQ,IAAyB,CAAC,EAAE,KAAK,UAAU,CAAC;IACtD,CAAC,CAAC;AACJ,CAAC"}

package/dist/types/generated/RawApiTypes.d.ts

@@ -6041,7 +6041,7 @@ export type FieldUpdateSchemaStableShell = {
     data: {
         type: FieldType;
         id: FieldIdentity;
-        attributes: {
+        attributes?: {
             /**
              * Default value for Field. When field is localized accepts an object of default values with site locales as keys
              */

package/dist/types/index.d.ts

@@ -9,6 +9,7 @@ export * from './utilities/duplicateBlockRecord';
 export * from './utilities/fieldsContainingReferences';
 export * from './utilities/id';
 export * from './utilities/inspectItem';
+export * from './utilities/isBlockOfType';
 export * from './utilities/itemDefinition';
 export * from './utilities/normalizedFieldValues';
 export * from './utilities/recursiveBlocks';

package/dist/types/utilities/isBlockOfType.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Narrows a union of block shapes to the member whose model (`item_type`)
+ * matches `Id`.
+ *
+ * Any object carrying `relationships.item_type.data.id` is narrowable —
+ * that covers blocks returned from `nested: true` responses as well as the
+ * object variants of request payloads (updated / newly-created blocks). The
+ * bare string IDs that may appear inside request payloads (to reference
+ * existing, unchanged blocks) are filtered out of the result.
+ */
+export type NarrowBlockByItemType<T, Id extends string> = Extract<T, {
+    relationships: {
+        item_type: {
+            data: {
+                type: 'item_type';
+                id: Id;
+            };
+        };
+    };
+}>;
+/**
+ * Builds a type guard that narrows a block to a specific model.
+ *
+ * Call it with the block's `itemTypeId` literal — the ID generic is inferred
+ * from the argument, so no explicit type parameter is needed. The returned
+ * predicate is generic: given any input type `T`, it narrows to
+ * `Extract<T, { relationships: { item_type: { data: { id: Id } } } }>`. It's
+ * meant to plug into `Array#filter` / `Array#find` over block-bearing fields
+ * in any of these contexts:
+ *
+ * - `ItemInNestedResponse<D>` (responses with `nested: true`)
+ * - `ItemCreateSchema<D>` / `ItemUpdateSchema<D>` (request payloads, object
+ *   variants; plain string IDs are filtered out — there's no way to narrow
+ *   them without an external lookup)
+ *
+ * The default (non-nested) response shape, where block fields are arrays of
+ * plain string IDs, is deliberately not supported — the type information is
+ * not recoverable from an ID alone.
+ *
+ * For the literal `Id` to be preserved (and narrowing to work), the argument
+ * must be typed as a literal — use `as const` on pre-set ID constants.
+ *
+ * @example
+ * ```ts
+ * const SESSION_BLOCK_ID = 'abc123' as const;
+ *
+ * const record = await client.items.find<Schema.ConferenceDay>(id, { nested: true });
+ * const sessions = record.agenda.filter(isBlockOfType(SESSION_BLOCK_ID));
+ * sessions[0].attributes.signup_url; // OK — narrowed
+ * ```
+ */
+export declare function isBlockOfType<Id extends string>(itemTypeId: Id): <T>(block: T) => block is NarrowBlockByItemType<T, Id>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datocms/cma-client",
-  "version": "5.4.3",
+  "version": "5.4.4",
   "description": "JS client for DatoCMS REST Content Management API",
   "keywords": [
     "datocms",
@@ -45,5 +45,5 @@
     "@datocms/dashboard-client": "^5.4.3",
     "@types/uuid": "^9.0.7"
   },
-  "gitHead": "46382f282c572c8a1206250939a64ba32baae59e"
+  "gitHead": "9bfdb472db5e4c48543fb9a2c3a64b95722c8d78"
 }

package/src/generated/Client.ts

@@ -151,7 +151,7 @@ export class Client {
       ...this.config,
       ...options,
       logFn: this.config.logFn || console.log,
-      userAgent: '@datocms/cma-client v5.4.3',
+      userAgent: '@datocms/cma-client v5.4.4',
       baseUrl: this.baseUrl,
       preCallStack: new Error().stack,
       extraHeaders: {

package/src/generated/RawApiTypes.ts

@@ -6365,7 +6365,7 @@ export type FieldUpdateSchemaStableShell = {
   data: {
     type: FieldType;
     id: FieldIdentity;
-    attributes: {
+    attributes?: {
       /**
        * Default value for Field. When field is localized accepts an object of default values with site locales as keys
        */

package/src/index.ts

@@ -9,6 +9,7 @@ export * from './utilities/duplicateBlockRecord';
 export * from './utilities/fieldsContainingReferences';
 export * from './utilities/id';
 export * from './utilities/inspectItem';
+export * from './utilities/isBlockOfType';
 export * from './utilities/itemDefinition';
 export * from './utilities/normalizedFieldValues';
 export * from './utilities/recursiveBlocks';

package/src/utilities/buildBlockRecord.ts

@@ -37,11 +37,20 @@ export function buildBlockRecord<
     | CreateBlockRecordSchema<NoInfer<D>>
     | UpdateBlockRecordSchema<NoInfer<D>>,
 ): NewBlockInRequest<NoInfer<D>> {
-  return Utils.serializeRequestBody<{
+  const data = Utils.serializeRequestBody<{
     data: NewBlockInRequest<NoInfer<D>>;
   }>(body, {
     type: Item.TYPE,
     attributes: '*',
     relationships: ['item_type'],
   }).data;
+
+  // Mirror the deserializer: expose `item_type.data.id` as a top-level
+  // `__itemTypeId` so locally-built blocks support the same TS narrowing
+  // pattern as blocks read from API responses. The field is TS-only and is
+  // stripped again by the serializer when the outer request is sent.
+  return {
+    ...data,
+    __itemTypeId: data.relationships.item_type.data.id,
+  } as NewBlockInRequest<NoInfer<D>>;
 }

package/src/utilities/isBlockOfType.ts

@@ -0,0 +1,61 @@
+/**
+ * Narrows a union of block shapes to the member whose model (`item_type`)
+ * matches `Id`.
+ *
+ * Any object carrying `relationships.item_type.data.id` is narrowable —
+ * that covers blocks returned from `nested: true` responses as well as the
+ * object variants of request payloads (updated / newly-created blocks). The
+ * bare string IDs that may appear inside request payloads (to reference
+ * existing, unchanged blocks) are filtered out of the result.
+ */
+export type NarrowBlockByItemType<T, Id extends string> = Extract<
+  T,
+  { relationships: { item_type: { data: { type: 'item_type'; id: Id } } } }
+>;
+
+/**
+ * Builds a type guard that narrows a block to a specific model.
+ *
+ * Call it with the block's `itemTypeId` literal — the ID generic is inferred
+ * from the argument, so no explicit type parameter is needed. The returned
+ * predicate is generic: given any input type `T`, it narrows to
+ * `Extract<T, { relationships: { item_type: { data: { id: Id } } } }>`. It's
+ * meant to plug into `Array#filter` / `Array#find` over block-bearing fields
+ * in any of these contexts:
+ *
+ * - `ItemInNestedResponse<D>` (responses with `nested: true`)
+ * - `ItemCreateSchema<D>` / `ItemUpdateSchema<D>` (request payloads, object
+ *   variants; plain string IDs are filtered out — there's no way to narrow
+ *   them without an external lookup)
+ *
+ * The default (non-nested) response shape, where block fields are arrays of
+ * plain string IDs, is deliberately not supported — the type information is
+ * not recoverable from an ID alone.
+ *
+ * For the literal `Id` to be preserved (and narrowing to work), the argument
+ * must be typed as a literal — use `as const` on pre-set ID constants.
+ *
+ * @example
+ * ```ts
+ * const SESSION_BLOCK_ID = 'abc123' as const;
+ *
+ * const record = await client.items.find<Schema.ConferenceDay>(id, { nested: true });
+ * const sessions = record.agenda.filter(isBlockOfType(SESSION_BLOCK_ID));
+ * sessions[0].attributes.signup_url; // OK — narrowed
+ * ```
+ */
+export function isBlockOfType<Id extends string>(
+  itemTypeId: Id,
+): <T>(block: T) => block is NarrowBlockByItemType<T, Id> {
+  return <T>(block: T): block is NarrowBlockByItemType<T, Id> => {
+    if (typeof block !== 'object' || block === null) return false;
+    const relationships = (block as { relationships?: unknown }).relationships;
+    if (typeof relationships !== 'object' || relationships === null)
+      return false;
+    const itemType = (relationships as { item_type?: unknown }).item_type;
+    if (typeof itemType !== 'object' || itemType === null) return false;
+    const data = (itemType as { data?: unknown }).data;
+    if (typeof data !== 'object' || data === null) return false;
+    return (data as { id?: unknown }).id === itemTypeId;
+  };
+}