@datocms/cma-client 5.8.1 → 6.0.0

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

@@ -0,0 +1,84 @@
+import type * as ApiTypes from '../generated/ApiTypes.js';
+import type { Client } from '../generated/Client.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 declare function isFieldKeyed(metadata: DefaultFieldMetadata | UploadLocaleKeyedDefaultFieldMetadata): metadata is DefaultFieldMetadata;
+/**
+ * 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 declare function fromLocaleKeyed(byLocale: UploadLocaleKeyedDefaultFieldMetadata): DefaultFieldMetadata;
+/**
+ * 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 declare function toLocaleKeyed({ alt, title, custom_data, focal_point, poster_time, }: DefaultFieldMetadataInRequest, environmentLocales: string[]): UploadLocaleKeyedDefaultFieldMetadataInRequest;
+/**
+ * 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 declare function normalizeUpload(upload: ApiTypes.Upload): ApiTypes.Upload;
+/**
+ * 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 declare function encodeDefaultFieldMetadata<T extends {
+    default_field_metadata?: DefaultFieldMetadataInRequest;
+}>(client: Client, body: T): Promise<T>;

package/dist/esm/utilities/defaultFieldMetadata.js

@@ -0,0 +1,122 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { fetchEnvironmentSettings, isEnvironmentFlagActive, } from './environmentSettings.js';
+/**
+ * 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) {
+    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) {
+    const alt = {};
+    const title = {};
+    const customData = {};
+    let focalPoint = null;
+    let posterTime = 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, }, environmentLocales) {
+    var _a;
+    const result = {};
+    function entryFor(locale) {
+        var _a;
+        const entry = (_a = result[locale]) !== null && _a !== void 0 ? _a : {};
+        result[locale] = entry;
+        return entry;
+    }
+    for (const [locale, value] of Object.entries(alt !== null && alt !== void 0 ? alt : {})) {
+        entryFor(locale).alt = value;
+    }
+    for (const [locale, value] of Object.entries(title !== null && title !== void 0 ? title : {})) {
+        entryFor(locale).title = value;
+    }
+    for (const [locale, value] of Object.entries(custom_data !== null && custom_data !== void 0 ? custom_data : {})) {
+        entryFor(locale).custom_data = value;
+    }
+    if (focal_point !== undefined || poster_time !== undefined) {
+        const locale = (_a = Object.keys(result)[0]) !== null && _a !== void 0 ? _a : 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) {
+    const metadata = upload.default_field_metadata;
+    if (!metadata || isFieldKeyed(metadata)) {
+        return upload;
+    }
+    return Object.assign(Object.assign({}, 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 function encodeDefaultFieldMetadata(client, body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const metadata = body.default_field_metadata;
+        if (!metadata) {
+            return body;
+        }
+        if (yield isEnvironmentFlagActive(client, 'non_localized_focal_points')) {
+            return body;
+        }
+        const { locales } = yield fetchEnvironmentSettings(client);
+        return Object.assign(Object.assign({}, 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) });
+    });
+}
+//# sourceMappingURL=defaultFieldMetadata.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaultFieldMetadata.js","sourceRoot":"","sources":["../../../src/utilities/defaultFieldMetadata.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,35 @@
+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];
+/**
+ * `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 declare function fetchEnvironmentSettings(client: Client): Promise<ApiTypes.Site>;
+/**
+ * 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 declare function isEnvironmentFlagActive(client: Client, flag: EnvironmentFlag): Promise<boolean>;

package/dist/esm/utilities/environmentSettings.js

@@ -0,0 +1,60 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/** How long a fetched `site` is reused before we ask again. */
+const TTL_MS = 20 * 60 * 1000;
+/**
+ * Keyed by client, so the cache covers every resource that asks and dies with
+ * the client that owns it.
+ */
+const caches = new WeakMap();
+/**
+ * `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) {
+    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(() => {
+        var _a;
+        if (((_a = caches.get(client)) === null || _a === void 0 ? void 0 : _a.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 function isEnvironmentFlagActive(client, flag) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        const site = yield fetchEnvironmentSettings(client);
+        return ((_a = site.meta) === null || _a === void 0 ? void 0 : _a[flag]) === true;
+    });
+}
+//# sourceMappingURL=environmentSettings.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"environmentSettings.js","sourceRoot":"","sources":["../../../src/utilities/environmentSettings.ts"],"names":[],"mappings":";;;;;;;;;AAkBA,+DAA+D;AAC/D,MAAM,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAI9B;;;GAGG;AACH,MAAM,MAAM,GAAG,IAAI,OAAO,EAAiB,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAc;IAEd,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,GAAG,EAAE;QACpC,OAAO,MAAM,CAAC,OAAO,CAAC;KACvB;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAEnC,wEAAwE;IACxE,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;;QACjB,IAAI,CAAA,MAAA,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,0CAAE,OAAO,MAAK,OAAO,EAAE;YAC3C,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;SACvB;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,GAAG,MAAM,EAAE,CAAC,CAAC;IAEzD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAgB,uBAAuB,CAC3C,MAAc,EACd,IAAqB;;;QAErB,MAAM,IAAI,GAAG,MAAM,wBAAwB,CAAC,MAAM,CAAC,CAAC;QAEpD,OAAO,CAAA,MAAC,IAAI,CAAC,IAA+C,0CAAG,IAAI,CAAC,MAAK,IAAI,CAAC;;CAC/E"}

package/dist/types/index.d.ts

@@ -4,7 +4,7 @@ export * from './fieldTypes/index.js';
 export { Client } from './generated/Client.js';
 export type { ClientConfigOptions } from './generated/Client.js';
 export * as Resources from './generated/resources/index.js';
-export type { UploadLocaleKeyedDefaultFieldMetadata, UploadLocaleKeyedDefaultFieldMetadataInRequest, } from './resources/Upload.js';
+export type { UploadLocaleKeyedDefaultFieldMetadata, UploadLocaleKeyedDefaultFieldMetadataInRequest, } from './utilities/defaultFieldMetadata.js';
 export * from './utilities/buildBlockRecord.js';
 export * from './utilities/duplicateBlockRecord.js';
 export * from './utilities/fieldsContainingReferences.js';

package/dist/types/resources/Upload.d.ts

@@ -1,46 +1,59 @@
+import type * as ApiTypes from '../generated/ApiTypes.js';
 import BaseUpload from '../generated/resources/Upload.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;
-    };
-};
-/**
- * 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 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}
+     */
+    create(body: ApiTypes.UploadCreateSchema): Promise<ApiTypes.Upload>;
+    /**
+     * Update an upload
+     *
+     * Read more: https://www.datocms.com/docs/content-management-api/resources/upload/update
+     *
+     * @throws {ApiError}
+     * @throws {TimeoutError}
+     */
+    update(uploadId: string | ApiTypes.UploadData, body: ApiTypes.UploadUpdateSchema, queryParams?: ApiTypes.UploadUpdateHrefSchema): Promise<ApiTypes.Upload>;
+    /**
+     * Retrieve an upload
+     *
+     * Read more: https://www.datocms.com/docs/content-management-api/resources/upload/self
+     *
+     * @throws {ApiError}
+     * @throws {TimeoutError}
+     */
+    find(uploadId: string | ApiTypes.UploadData): Promise<ApiTypes.Upload>;
+    /**
+     * List all uploads
+     *
+     * Read more: https://www.datocms.com/docs/content-management-api/resources/upload/instances
+     *
+     * @throws {ApiError}
+     * @throws {TimeoutError}
+     */
+    list(queryParams?: ApiTypes.UploadInstancesHrefSchema): Promise<ApiTypes.Upload[]>;
+    /**
+     * 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}
+     */
+    listPagedIterator(...args: Parameters<BaseUpload['listPagedIterator']>): AsyncGenerator<ApiTypes.Upload, void, unknown>;
 }

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

@@ -0,0 +1,84 @@
+import type * as ApiTypes from '../generated/ApiTypes.js';
+import type { Client } from '../generated/Client.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 declare function isFieldKeyed(metadata: DefaultFieldMetadata | UploadLocaleKeyedDefaultFieldMetadata): metadata is DefaultFieldMetadata;
+/**
+ * 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 declare function fromLocaleKeyed(byLocale: UploadLocaleKeyedDefaultFieldMetadata): DefaultFieldMetadata;
+/**
+ * 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 declare function toLocaleKeyed({ alt, title, custom_data, focal_point, poster_time, }: DefaultFieldMetadataInRequest, environmentLocales: string[]): UploadLocaleKeyedDefaultFieldMetadataInRequest;
+/**
+ * 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 declare function normalizeUpload(upload: ApiTypes.Upload): ApiTypes.Upload;
+/**
+ * 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 declare function encodeDefaultFieldMetadata<T extends {
+    default_field_metadata?: DefaultFieldMetadataInRequest;
+}>(client: Client, body: T): Promise<T>;

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

@@ -0,0 +1,35 @@
+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];
+/**
+ * `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 declare function fetchEnvironmentSettings(client: Client): Promise<ApiTypes.Site>;
+/**
+ * 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 declare function isEnvironmentFlagActive(client: Client, flag: EnvironmentFlag): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datocms/cma-client",
-  "version": "5.8.1",
+  "version": "6.0.0",
   "description": "JS client for DatoCMS REST Content Management API",
   "keywords": [
     "datocms",

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.8.1',
+      userAgent: '@datocms/cma-client v6.0.0',
       baseUrl: this.baseUrl,
       preCallStack: new Error().stack,
       extraHeaders: {

package/src/index.ts

@@ -7,7 +7,7 @@ export * as Resources from './generated/resources/index.js';
 export type {
   UploadLocaleKeyedDefaultFieldMetadata,
   UploadLocaleKeyedDefaultFieldMetadataInRequest,
-} from './resources/Upload.js';
+} from './utilities/defaultFieldMetadata.js';
 export * from './utilities/buildBlockRecord.js';
 export * from './utilities/duplicateBlockRecord.js';
 export * from './utilities/fieldsContainingReferences.js';