@datocms/cma-client 5.8.1 → 6.0.0

package/src/resources/Upload.ts

@@ -1,38 +1,94 @@
+import type * as ApiTypes from '../generated/ApiTypes.js';
 import BaseUpload from '../generated/resources/Upload.js';
+import {
+  encodeDefaultFieldMetadata,
+  normalizeUpload,
+} from '../utilities/defaultFieldMetadata.js';
 
 /**
- * Legacy locale-keyed shape of an upload's `default_field_metadata`, as
- * returned and accepted by environments where the `non_localized_focal_points`
- * opt-in is inactive.
+ * `default_field_metadata` travels in one of two shapes, and which one an
+ * environment speaks depends on the `non_localized_focal_points` opt-in — each
+ * rejects the other with `422 INVALID_FORMAT`. This resource hides that: you
+ * always read and write the field-keyed shape the types describe, and the
+ * legacy one is converted to and from as needed.
  *
- * The generated `Upload.default_field_metadata` type reflects the new
- * field-keyed shape (the path forward). This type is provided so consumers
- * targeting opted-out environments during the transition can cast the
- * response value to a structurally accurate shape.
+ * The raw methods are deliberately left alone: they are the escape hatch for
+ * anyone who needs to see what actually goes over the wire.
  */
-export type UploadLocaleKeyedDefaultFieldMetadata = {
-  [localeCode: string]: {
-    alt: string | null;
-    title: string | null;
-    custom_data: { [k: string]: unknown };
-    focal_point: { x: number; y: number } | null;
-    poster_time: number | null;
-  };
-};
+export default class UploadResource extends BaseUpload {
+  /**
+   * Create a new upload
+   *
+   * Read more: https://www.datocms.com/docs/content-management-api/resources/upload/create
+   *
+   * @throws {ApiError}
+   * @throws {TimeoutError}
+   */
+  async create(body: ApiTypes.UploadCreateSchema) {
+    return normalizeUpload(
+      await super.create(await encodeDefaultFieldMetadata(this.client, body)),
+    );
+  }
 
-/**
- * Legacy locale-keyed shape accepted on `create` / `update` request bodies
- * by environments where the `non_localized_focal_points` opt-in is inactive.
- * All fields are optional, matching the partial-write contract.
- */
-export type UploadLocaleKeyedDefaultFieldMetadataInRequest = {
-  [localeCode: string]: {
-    alt?: string | null;
-    title?: string | null;
-    custom_data?: { [k: string]: unknown };
-    focal_point?: { x: number; y: number } | null;
-    poster_time?: number | null;
-  };
-};
+  /**
+   * Update an upload
+   *
+   * Read more: https://www.datocms.com/docs/content-management-api/resources/upload/update
+   *
+   * @throws {ApiError}
+   * @throws {TimeoutError}
+   */
+  async update(
+    uploadId: string | ApiTypes.UploadData,
+    body: ApiTypes.UploadUpdateSchema,
+    queryParams?: ApiTypes.UploadUpdateHrefSchema,
+  ) {
+    return normalizeUpload(
+      await super.update(
+        uploadId,
+        await encodeDefaultFieldMetadata(this.client, body),
+        queryParams,
+      ),
+    );
+  }
+
+  /**
+   * Retrieve an upload
+   *
+   * Read more: https://www.datocms.com/docs/content-management-api/resources/upload/self
+   *
+   * @throws {ApiError}
+   * @throws {TimeoutError}
+   */
+  async find(uploadId: string | ApiTypes.UploadData) {
+    return normalizeUpload(await super.find(uploadId));
+  }
+
+  /**
+   * List all uploads
+   *
+   * Read more: https://www.datocms.com/docs/content-management-api/resources/upload/instances
+   *
+   * @throws {ApiError}
+   * @throws {TimeoutError}
+   */
+  async list(queryParams?: ApiTypes.UploadInstancesHrefSchema) {
+    return (await super.list(queryParams)).map(normalizeUpload);
+  }
 
-export default class UploadResource extends BaseUpload {}
+  /**
+   * Async iterator to auto-paginate over elements returned by list()
+   *
+   * Read more: https://www.datocms.com/docs/content-management-api/resources/upload/instances
+   *
+   * @throws {ApiError}
+   * @throws {TimeoutError}
+   */
+  async *listPagedIterator(
+    ...args: Parameters<BaseUpload['listPagedIterator']>
+  ) {
+    for await (const upload of super.listPagedIterator(...args)) {
+      yield normalizeUpload(upload);
+    }
+  }
+}

package/src/utilities/defaultFieldMetadata.ts

@@ -0,0 +1,193 @@
+import type * as ApiTypes from '../generated/ApiTypes.js';
+import type { Client } from '../generated/Client.js';
+import {
+  fetchEnvironmentSettings,
+  isEnvironmentFlagActive,
+} from './environmentSettings.js';
+
+/**
+ * Legacy locale-keyed shape of an upload's `default_field_metadata`, as
+ * returned and accepted by environments where the `non_localized_focal_points`
+ * opt-in is inactive.
+ *
+ * The `uploads` resource converts to and from this shape on your behalf, so you
+ * only ever see the field-keyed one. The type is exported for those working at
+ * the raw layer, which performs no conversion.
+ */
+export type UploadLocaleKeyedDefaultFieldMetadata = {
+  [localeCode: string]: {
+    alt: string | null;
+    title: string | null;
+    custom_data: { [k: string]: unknown };
+    focal_point: { x: number; y: number } | null;
+    poster_time: number | null;
+  };
+};
+
+/**
+ * Legacy locale-keyed shape accepted on `create` / `update` request bodies
+ * by environments where the `non_localized_focal_points` opt-in is inactive.
+ * All fields are optional, matching the partial-write contract.
+ */
+export type UploadLocaleKeyedDefaultFieldMetadataInRequest = {
+  [localeCode: string]: {
+    alt?: string | null;
+    title?: string | null;
+    custom_data?: { [k: string]: unknown };
+    focal_point?: { x: number; y: number } | null;
+    poster_time?: number | null;
+  };
+};
+
+export type DefaultFieldMetadata = ApiTypes.Upload['default_field_metadata'];
+
+export type DefaultFieldMetadataInRequest = NonNullable<
+  ApiTypes.UploadUpdateSchema['default_field_metadata']
+>;
+
+/**
+ * Tells the two wire shapes apart. A field-keyed payload always carries a
+ * top-level `focal_point`, and a locale-keyed one never can: its keys are
+ * locale codes, and no locale code is the literal string `focal_point`.
+ */
+export function isFieldKeyed(
+  metadata: DefaultFieldMetadata | UploadLocaleKeyedDefaultFieldMetadata,
+): metadata is DefaultFieldMetadata {
+  return 'focal_point' in metadata;
+}
+
+/**
+ * Collapses a legacy response payload into the field-keyed shape. The API
+ * replicates the non-localized values into every locale entry on read, so every
+ * entry carries the same value and the first one is enough.
+ */
+export function fromLocaleKeyed(
+  byLocale: UploadLocaleKeyedDefaultFieldMetadata,
+): DefaultFieldMetadata {
+  const alt: Record<string, string | null> = {};
+  const title: Record<string, string | null> = {};
+  const customData: Record<string, { [k: string]: unknown }> = {};
+
+  let focalPoint: { x: number; y: number } | null = null;
+  let posterTime: number | null = null;
+  let seenAnEntry = false;
+
+  for (const [locale, entry] of Object.entries(byLocale)) {
+    alt[locale] = entry.alt;
+    title[locale] = entry.title;
+    customData[locale] = entry.custom_data;
+
+    if (!seenAnEntry) {
+      seenAnEntry = true;
+      focalPoint = entry.focal_point;
+      posterTime = entry.poster_time;
+    }
+  }
+
+  return {
+    alt,
+    title,
+    custom_data: customData,
+    focal_point: focalPoint,
+    poster_time: posterTime,
+  };
+}
+
+/**
+ * Rewrites a field-keyed patch into the legacy locale-keyed one: the localized
+ * keys are pivoted per locale, and the non-localized ones ride along on a
+ * single entry. The API takes `focal_point` / `poster_time` off the first entry
+ * that carries one and ignores the rest, so writing them once is enough — on
+ * any locale the patch already touches, or the environment's first one when it
+ * touches none.
+ */
+export function toLocaleKeyed(
+  {
+    alt,
+    title,
+    custom_data,
+    focal_point,
+    poster_time,
+  }: DefaultFieldMetadataInRequest,
+  environmentLocales: string[],
+): UploadLocaleKeyedDefaultFieldMetadataInRequest {
+  const result: UploadLocaleKeyedDefaultFieldMetadataInRequest = {};
+
+  function entryFor(locale: string) {
+    const entry = result[locale] ?? {};
+    result[locale] = entry;
+    return entry;
+  }
+
+  for (const [locale, value] of Object.entries(alt ?? {})) {
+    entryFor(locale).alt = value;
+  }
+
+  for (const [locale, value] of Object.entries(title ?? {})) {
+    entryFor(locale).title = value;
+  }
+
+  for (const [locale, value] of Object.entries(custom_data ?? {})) {
+    entryFor(locale).custom_data = value;
+  }
+
+  if (focal_point !== undefined || poster_time !== undefined) {
+    const locale = Object.keys(result)[0] ?? environmentLocales[0];
+
+    if (locale) {
+      if (focal_point !== undefined) entryFor(locale).focal_point = focal_point;
+      if (poster_time !== undefined) entryFor(locale).poster_time = poster_time;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Normalizes an upload as served by the API into the field-keyed shape the
+ * `Upload` type describes. Returns the entity untouched — no copy — when it is
+ * already field-keyed, which is the case for every environment that has taken
+ * the opt-in.
+ */
+export function normalizeUpload(upload: ApiTypes.Upload): ApiTypes.Upload {
+  const metadata = upload.default_field_metadata;
+
+  if (!metadata || isFieldKeyed(metadata)) {
+    return upload;
+  }
+
+  return { ...upload, default_field_metadata: fromLocaleKeyed(metadata) };
+}
+
+/**
+ * Encodes a `create` / `update` body into the shape the environment accepts.
+ *
+ * The environment is only consulted when there is metadata to encode, so a
+ * client that never writes asset metadata never asks — and when it does ask,
+ * the lookup is memoized and shared, so a batch of writes pays for one.
+ */
+export async function encodeDefaultFieldMetadata<
+  T extends { default_field_metadata?: DefaultFieldMetadataInRequest },
+>(client: Client, body: T): Promise<T> {
+  const metadata = body.default_field_metadata;
+
+  if (!metadata) {
+    return body;
+  }
+
+  if (await isEnvironmentFlagActive(client, 'non_localized_focal_points')) {
+    return body;
+  }
+
+  const { locales } = await fetchEnvironmentSettings(client);
+
+  return {
+    ...body,
+    // The declared type describes the field-keyed shape, which is what callers
+    // write. The legacy payload is this module's business.
+    default_field_metadata: toLocaleKeyed(
+      metadata,
+      locales,
+    ) as unknown as DefaultFieldMetadataInRequest,
+  };
+}

package/src/utilities/environmentSettings.ts

@@ -0,0 +1,80 @@
+import type * as ApiTypes from '../generated/ApiTypes.js';
+import type { Client } from '../generated/Client.js';
+
+/**
+ * Every boolean an environment reports about itself in `site.meta`: the
+ * product-update opt-ins (`improved_items_listing`, `milliseconds_in_datetime`,
+ * `non_localized_focal_points`, …) plus the plain state flags.
+ *
+ * Derived from the generated type rather than listed, so a flag added to the
+ * schema is usable here as soon as the types are regenerated, with nothing to
+ * keep in sync.
+ */
+export type EnvironmentFlag = {
+  [K in keyof ApiTypes.SiteMeta]-?: boolean extends ApiTypes.SiteMeta[K]
+    ? K
+    : never;
+}[keyof ApiTypes.SiteMeta];
+
+/** How long a fetched `site` is reused before we ask again. */
+const TTL_MS = 20 * 60 * 1000;
+
+type Cache = { promise: Promise<ApiTypes.Site>; expiresAt: number };
+
+/**
+ * Keyed by client, so the cache covers every resource that asks and dies with
+ * the client that owns it.
+ */
+const caches = new WeakMap<Client, Cache>();
+
+/**
+ * `site.find()`, memoized per client for {@link TTL_MS}.
+ *
+ * The promise is cached rather than its result, so concurrent callers share one
+ * request instead of firing one each — the difference between one lookup and
+ * ten thousand when a batch job starts. A failed lookup is not cached.
+ *
+ * Everything expires on the same clock, including flags that in practice never
+ * change back: re-reading `site` every twenty minutes costs nothing next to the
+ * work these clients are doing, and it means a client stays correct across an
+ * activation that happens while it runs.
+ */
+export function fetchEnvironmentSettings(
+  client: Client,
+): Promise<ApiTypes.Site> {
+  const cached = caches.get(client);
+  const now = Date.now();
+
+  if (cached && cached.expiresAt > now) {
+    return cached.promise;
+  }
+
+  const promise = client.site.find();
+
+  // A failed lookup must not be cached, or every later caller inherits it
+  promise.catch(() => {
+    if (caches.get(client)?.promise === promise) {
+      caches.delete(client);
+    }
+  });
+
+  caches.set(client, { promise, expiresAt: now + TTL_MS });
+
+  return promise;
+}
+
+/**
+ * Whether a `site.meta` flag is on for the environment this client talks to.
+ *
+ * An API predating a flag omits it from the meta entirely, which the types
+ * don't admit but runtime does — so anything short of an explicit `true` reads
+ * as off.
+ */
+export async function isEnvironmentFlagActive(
+  client: Client,
+  flag: EnvironmentFlag,
+): Promise<boolean> {
+  const site = await fetchEnvironmentSettings(client);
+
+  return (site.meta as Partial<ApiTypes.SiteMeta> | undefined)?.[flag] === true;
+}