Add poster_time to file/gallery field value types

The CMA returns (and accepts) a `poster_time` metadata key on file and
gallery field values for video assets — the float second into the video
used to generate the thumbnail. The hand-written field value types didn't
include it, so it was missing from `FileFieldValue`,
`FileFieldValueInRequest`, and (via re-export) the gallery equivalents.

- Add `poster_time` to `FileFieldValue` (`number | null`) and
  `FileFieldValueInRequest` (`number | null`, optional).
- Require `poster_time` in the `isFileFieldValue` response type guard,
  matching the existing `focal_point` check.
- Surface `poster_time` in `inspectItem` for file and gallery items.

Gallery types derive from the file types, so they pick this up for free.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: stefanoverna

packages/cma-client/__tests__/inspectItem.test.ts

@@ -398,13 +398,15 @@ describe('inspectItem', () => {
             title: 'English file title',
             custom_data: {},
             focal_point: null,
+            poster_time: null,
           },
           it: {
             upload_id: 'italian-file-id',
             alt: 'Testo alternativo italiano',
             title: 'Titolo file italiano',
             custom_data: { locale: 'it' },
             focal_point: { x: 0.6, y: 0.4 },
+            poster_time: null,
           },
         },
 

packages/cma-client/src/fieldTypes/file.ts

@@ -17,13 +17,14 @@ import type { RequiredAltTitleValidator } from './validators/required_alt_title.
  * which contain file uploads with optional metadata like alt text, title, custom data, and focal points.
  *
  * The challenge we're solving:
- * - DatoCMS File fields can have optional metadata fields (alt, title, custom_data, focal_point)
+ * - DatoCMS File fields can have optional metadata fields (alt, title, custom_data, focal_point, poster_time)
  * - For API requests, all these fields are optional and can be omitted
  * - For API responses, DatoCMS provides default values for missing fields:
  *   - alt: null
  *   - title: null
  *   - custom_data: {}
  *   - focal_point: null
+ *   - poster_time: null
  * - This creates a need for different type variants for the same conceptual data structure
  *
  * This module provides separate types for:
@@ -52,6 +53,7 @@ export type FileFieldValue = {
     x: number;
     y: number;
   } | null;
+  poster_time: number | null;
 } | null;
 
 /**
@@ -75,6 +77,7 @@ export type FileFieldValueInRequest = {
     x: number;
     y: number;
   } | null;
+  poster_time?: number | null;
 } | null;
 
 /**
@@ -95,7 +98,8 @@ export function isFileFieldValue(value: unknown): value is FileFieldValue {
     'alt' in value &&
     'title' in value &&
     'custom_data' in value &&
-    'focal_point' in value
+    'focal_point' in value &&
+    'poster_time' in value
   );
 }
 

packages/cma-client/src/utilities/inspectItem.ts

@@ -387,6 +387,10 @@ function fileInspectionTreeNodes(
     nodes.push({ label: `focal_point: x=${x}% y=${y}%` });
   }
 
+  if (typeof value.poster_time === 'number') {
+    nodes.push({ label: `poster_time: ${value.poster_time}s` });
+  }
+
   return nodes;
 }
 
@@ -432,6 +436,10 @@ function galleryInspectionTreeNodes(
       nodes.push({ label: `focal_point: x=${x}% y=${y}%` });
     }
 
+    if (typeof item.poster_time === 'number') {
+      nodes.push({ label: `poster_time: ${item.poster_time}s` });
+    }
+
     return {
       label: `[${index}]`,
       nodes: nodes,