@flexacms/client 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Mercedes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @flexacms/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed, dependency-free client for the [Flexa](https://github.com/flexacms) headless CMS content API. Works in Node 20+, Bun, Deno, edge runtimes and browsers.
+
+```bash
+npm install @flexacms/client
+```
+
+```ts
+import { createClient, localize } from '@flexacms/client';
+
+const flexa = createClient({
+    url: process.env.FLEXA_URL!, // https://cms.example.com
+    apiKey: process.env.FLEXA_API_KEY!,
+});
+
+const { data: posts, meta } = await flexa
+    .entity('posts')
+    .list({ status: 'published', perPage: 12 });
+const post = await flexa.entity('posts').find('hello-world'); // null when missing
+const headline = localize(post?.values.headline, 'es', ['en']);
+```
+
+> Keep the API key on the server. Anyone with it can do what its abilities allow; use a **Read** key limited to the entities a public site needs.
+
+## Typed content
+
+Generate types for your workspace with [`@flexacms/cli`](../cli) and pass them to the client:
+
+```ts
+import type { FlexaSchema } from './flexa';
+
+const flexa = createClient<FlexaSchema>({ url, apiKey });
+const page = await flexa.entity('pages').get('home');
+page.values.headline.en; // string | null | undefined, typed from your content model
+```
+
+## API
+
+| Method                                               | Description                                                                                |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `entities()`                                         | Content models the key can read                                                            |
+| `entity(slug).schema()`                              | Fields, groups, categories and locales                                                     |
+| `entity(slug).list(params)`                          | One page: `status`, `search`, `category`, `page`, `perPage`, `trashed`, `includeRelations` |
+| `entity(slug).all(params)` / `iterate(params)`       | Every matching entry, page by page                                                         |
+| `entity(slug).get(idOrSlug)` / `find(idOrSlug)`      | One entry (`find` resolves to `null` on 404)                                               |
+| `entity(slug).create(input)` / `update(id, input)`   | Write entries (Write ability)                                                              |
+| `entity(slug).delete(id, { force })` / `restore(id)` | Trash, delete for good or restore                                                          |
+
+Every method accepts a last `{ signal, init }` argument; `init` is merged into the `fetch` call.
+
+## Errors and retries
+
+Failed requests throw a `FlexaError` with `status`, `message`, `errors` (validation errors keyed by field) and helpers such as `isNotFound` or `isValidationError`. Reads are retried after `429`, `502`, `503`, `504` and network failures (honouring `Retry-After`); writes are never retried.
+
+| Option    | Default        |                                          |
+| --------- | -------------- | ---------------------------------------- |
+| `apiPath` | `/api/v1`      | Path of the content API                  |
+| `timeout` | `30000`        | Milliseconds before a request is aborted |
+| `retries` | `2`            | Retries for reads                        |
+| `headers` | —              | Extra headers on every request           |
+| `fetch`   | global `fetch` | Custom fetch implementation              |

package/dist/index.cjs

@@ -0,0 +1,352 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  EntityClient: () => EntityClient,
+  FlexaClient: () => FlexaClient,
+  FlexaError: () => FlexaError,
+  createClient: () => createClient,
+  isFlexaError: () => isFlexaError,
+  isLocalized: () => isLocalized,
+  localize: () => localize
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var FlexaError = class extends Error {
+  constructor(message, status, errors = {}, body = null) {
+    super(message);
+    this.status = status;
+    this.errors = errors;
+    this.body = body;
+  }
+  status;
+  errors;
+  body;
+  name = "FlexaError";
+  get isNotFound() {
+    return this.status === 404;
+  }
+  get isUnauthorized() {
+    return this.status === 401;
+  }
+  get isForbidden() {
+    return this.status === 403;
+  }
+  get isValidationError() {
+    return this.status === 422;
+  }
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+function isFlexaError(error) {
+  return error instanceof FlexaError;
+}
+
+// src/client.ts
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+var FlexaClient = class {
+  baseUrl;
+  options;
+  constructor(options) {
+    if (!options.url) {
+      throw new TypeError('Flexa: the "url" option is required.');
+    }
+    if (!options.apiKey) {
+      throw new TypeError('Flexa: the "apiKey" option is required.');
+    }
+    const apiPath = `/${(options.apiPath ?? "/api/v1").replace(/^\/+|\/+$/g, "")}`;
+    this.baseUrl = `${options.url.replace(/\/+$/, "")}${apiPath}`;
+    this.options = { timeout: 3e4, retries: 2, ...options };
+  }
+  /** Entities (content models) the API key can read. */
+  async entities(options) {
+    const response = await this.request(
+      "GET",
+      "/entities",
+      void 0,
+      options
+    );
+    return response.data;
+  }
+  /** Typed access to the entries of one entity. */
+  entity(slug) {
+    return new EntityClient(this, slug);
+  }
+  /**
+   * Send a request to the content API. Exposed for endpoints the typed helpers
+   * do not cover yet; `path` is relative to the API base (e.g. `/posts`).
+   */
+  async request(method, path, body, options = {}) {
+    const fetchImplementation = this.options.fetch ?? globalThis.fetch;
+    if (typeof fetchImplementation !== "function") {
+      throw new TypeError(
+        'Flexa: no fetch implementation available. Pass one with the "fetch" option.'
+      );
+    }
+    const attempts = method === "GET" ? this.options.retries + 1 : 1;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      const signals = [
+        AbortSignal.timeout(this.options.timeout),
+        options.signal
+      ].filter((signal) => signal !== void 0);
+      let response;
+      try {
+        response = await fetchImplementation(`${this.baseUrl}${path}`, {
+          ...options.init,
+          method,
+          signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0],
+          headers: {
+            Accept: "application/json",
+            ...body === void 0 ? {} : { "Content-Type": "application/json" },
+            ...this.options.headers,
+            ...options.init?.headers,
+            Authorization: `Bearer ${this.options.apiKey}`
+          },
+          body: body === void 0 ? void 0 : JSON.stringify(body)
+        });
+      } catch (error) {
+        if (options.signal?.aborted || attempt === attempts) {
+          throw new FlexaError(
+            error instanceof Error ? `Flexa request failed: ${error.message}` : "Flexa request failed.",
+            0
+          );
+        }
+        lastError = error;
+        await sleep(this.backoff(attempt));
+        continue;
+      }
+      if (response.ok) {
+        return response.status === 204 ? void 0 : await response.json();
+      }
+      if (attempt < attempts && RETRYABLE_STATUSES.has(response.status)) {
+        await sleep(
+          this.backoff(attempt, response.headers.get("Retry-After"))
+        );
+        continue;
+      }
+      throw await this.toError(response);
+    }
+    throw lastError;
+  }
+  backoff(attempt, retryAfter) {
+    const seconds = Number(retryAfter);
+    if (retryAfter && Number.isFinite(seconds)) {
+      return Math.min(seconds * 1e3, 3e4);
+    }
+    return 250 * 2 ** (attempt - 1);
+  }
+  async toError(response) {
+    let body = null;
+    try {
+      body = await response.json();
+    } catch {
+    }
+    const payload = body ?? {};
+    const message = typeof payload.message === "string" && payload.message !== "" ? payload.message : `Flexa request failed with status ${response.status}.`;
+    return new FlexaError(
+      message,
+      response.status,
+      payload.errors && typeof payload.errors === "object" ? payload.errors : {},
+      body
+    );
+  }
+};
+var EntityClient = class {
+  constructor(client, slug) {
+    this.client = client;
+    this.slug = slug;
+  }
+  client;
+  slug;
+  get path() {
+    return `/${encodeURIComponent(this.slug)}`;
+  }
+  /** Fields, groups, categories and locales of the entity. */
+  async schema(options) {
+    const response = await this.client.request(
+      "GET",
+      `${this.path}/schema`,
+      void 0,
+      options
+    );
+    return response.data;
+  }
+  /** One page of entries. */
+  list(params = {}, options) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries({
+      status: params.status,
+      search: params.search,
+      category: params.category,
+      page: params.page,
+      per_page: params.perPage,
+      trashed: params.trashed,
+      include: params.includeRelations ? "relations" : void 0
+    })) {
+      if (value !== void 0 && value !== null && value !== "") {
+        query.set(key, String(value));
+      }
+    }
+    const search = query.toString();
+    return this.client.request(
+      "GET",
+      `${this.path}${search ? `?${search}` : ""}`,
+      void 0,
+      options
+    );
+  }
+  /** Iterate over every matching entry, fetching pages as needed. */
+  async *iterate(params = {}, options) {
+    let page = 1;
+    let lastPage = 1;
+    do {
+      const result = await this.list(
+        { perPage: 100, ...params, page },
+        options
+      );
+      yield* result.data;
+      lastPage = result.meta.last_page;
+      page++;
+    } while (page <= lastPage);
+  }
+  /** Every matching entry, across all pages. */
+  async all(params = {}, options) {
+    const entries = [];
+    for await (const entry of this.iterate(params, options)) {
+      entries.push(entry);
+    }
+    return entries;
+  }
+  /** An entry by id or slug. Throws a 404 `FlexaError` when it does not exist. */
+  async get(idOrSlug, params = {}, options) {
+    const query = params.includeRelations ? "?include=relations" : "";
+    const response = await this.client.request(
+      "GET",
+      `${this.path}/${encodeURIComponent(String(idOrSlug))}${query}`,
+      void 0,
+      options
+    );
+    return response.data;
+  }
+  /** Like `get()`, but resolves to `null` when the entry does not exist. */
+  async find(idOrSlug, params = {}, options) {
+    try {
+      return await this.get(idOrSlug, params, options);
+    } catch (error) {
+      if (error instanceof FlexaError && error.isNotFound) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /** Create an entry. Needs the Write ability. */
+  async create(input, options) {
+    const response = await this.client.request(
+      "POST",
+      this.path,
+      input,
+      options
+    );
+    return response.data;
+  }
+  /** Partially update an entry. Needs the Write ability. */
+  async update(idOrSlug, input, options) {
+    const response = await this.client.request(
+      "PATCH",
+      `${this.path}/${encodeURIComponent(String(idOrSlug))}`,
+      input,
+      options
+    );
+    return response.data;
+  }
+  /** Move an entry to the trash, or delete it for good with `force`. Needs the Delete ability. */
+  async delete(idOrSlug, params = {}, options) {
+    await this.client.request(
+      "DELETE",
+      `${this.path}/${encodeURIComponent(String(idOrSlug))}${params.force ? "?force=1" : ""}`,
+      void 0,
+      options
+    );
+  }
+  /** Restore a trashed entry. Needs the Write ability. */
+  async restore(idOrSlug, options) {
+    const response = await this.client.request(
+      "POST",
+      `${this.path}/${encodeURIComponent(String(idOrSlug))}/restore`,
+      void 0,
+      options
+    );
+    return response.data;
+  }
+};
+function createClient(options) {
+  return new FlexaClient(options);
+}
+
+// src/localize.ts
+function isLocalized(value, locales) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) {
+    return false;
+  }
+  return locales ? keys.every((key) => locales.includes(key)) : keys.every((key) => /^[a-z]{2,3}([_-][A-Za-z]{2,4})?$/.test(key));
+}
+function localize(value, locale, fallbacks = []) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (!isLocalized(value)) {
+    return value;
+  }
+  const translations = value;
+  for (const candidate of [locale, ...fallbacks]) {
+    const translation = translations[candidate];
+    if (translation !== null && translation !== void 0 && translation !== "") {
+      return translation;
+    }
+  }
+  for (const translation of Object.values(translations)) {
+    if (translation !== null && translation !== void 0 && translation !== "") {
+      return translation;
+    }
+  }
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EntityClient,
+  FlexaClient,
+  FlexaError,
+  createClient,
+  isFlexaError,
+  isLocalized,
+  localize
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/client.ts","../src/localize.ts"],"sourcesContent":["export { createClient, EntityClient, FlexaClient } from './client';\nexport type { FlexaClientOptions } from './client';\nexport { FlexaError, isFlexaError } from './errors';\nexport { isLocalized, localize } from './localize';\nexport type * from './types';\n","/**\n * Error thrown for every non-2xx response from the content API.\n */\nexport class FlexaError extends Error {\n    override readonly name = 'FlexaError';\n\n    constructor(\n        message: string,\n        /** HTTP status, or 0 when the request never reached the server. */\n        readonly status: number,\n        /** Validation errors keyed by field (422 responses). */\n        readonly errors: Record<string, string[]> = {},\n        /** Parsed response body, when there was one. */\n        readonly body: unknown = null,\n    ) {\n        super(message);\n    }\n\n    get isNotFound(): boolean {\n        return this.status === 404;\n    }\n\n    get isUnauthorized(): boolean {\n        return this.status === 401;\n    }\n\n    get isForbidden(): boolean {\n        return this.status === 403;\n    }\n\n    get isValidationError(): boolean {\n        return this.status === 422;\n    }\n\n    get isRateLimited(): boolean {\n        return this.status === 429;\n    }\n}\n\nexport function isFlexaError(error: unknown): error is FlexaError {\n    return error instanceof FlexaError;\n}\n","import { FlexaError } from './errors';\nimport type {\n    ContentSchema,\n    EntitySchema,\n    EntitySummary,\n    Entry,\n    EntryInput,\n    EntryValues,\n    GetParams,\n    ListParams,\n    Paginated,\n    RequestOptions,\n} from './types';\n\nexport interface FlexaClientOptions {\n    /** Base URL of your Flexa installation, e.g. `https://cms.example.com`. */\n    url: string;\n    /**\n     * Workspace API key. Keep it on the server: anyone with the key can do what\n     * its abilities allow. Use a Read-only key for public websites.\n     */\n    apiKey: string;\n    /** Path of the content API. Defaults to `/api/v1`. */\n    apiPath?: string;\n    /** Custom fetch implementation (defaults to the global `fetch`). */\n    fetch?: typeof fetch;\n    /** Extra headers sent with every request. */\n    headers?: Record<string, string>;\n    /** Abort requests that take longer than this, in milliseconds. Defaults to 30s. */\n    timeout?: number;\n    /**\n     * How many times to retry reads after a rate limit (429), a gateway error\n     * (502/503/504) or a network failure. Writes are never retried. Defaults to 2.\n     */\n    retries?: number;\n}\n\ntype ValuesOf<\n    TSchema extends object,\n    TEntity extends string,\n> = TEntity extends keyof TSchema\n    ? TSchema[TEntity] extends object\n        ? TSchema[TEntity]\n        : EntryValues\n    : EntryValues;\n\n/** The part of the client entity helpers need: sending requests. */\ntype RequestSender = Pick<FlexaClient, 'request'>;\n\nconst RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);\n\nfunction sleep(milliseconds: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, milliseconds));\n}\n\n/**\n * Content API client for one Flexa workspace (the workspace is set by the API key).\n */\nexport class FlexaClient<TSchema extends object = ContentSchema> {\n    readonly baseUrl: string;\n\n    private readonly options: Required<\n        Pick<FlexaClientOptions, 'timeout' | 'retries'>\n    > &\n        FlexaClientOptions;\n\n    constructor(options: FlexaClientOptions) {\n        if (!options.url) {\n            throw new TypeError('Flexa: the \"url\" option is required.');\n        }\n\n        if (!options.apiKey) {\n            throw new TypeError('Flexa: the \"apiKey\" option is required.');\n        }\n\n        const apiPath = `/${(options.apiPath ?? '/api/v1').replace(/^\\/+|\\/+$/g, '')}`;\n\n        this.baseUrl = `${options.url.replace(/\\/+$/, '')}${apiPath}`;\n        this.options = { timeout: 30_000, retries: 2, ...options };\n    }\n\n    /** Entities (content models) the API key can read. */\n    async entities(options?: RequestOptions): Promise<EntitySummary[]> {\n        const response = await this.request<{ data: EntitySummary[] }>(\n            'GET',\n            '/entities',\n            undefined,\n            options,\n        );\n\n        return response.data;\n    }\n\n    /** Typed access to the entries of one entity. */\n    entity<TEntity extends Extract<keyof TSchema, string> | (string & {})>(\n        slug: TEntity,\n    ): EntityClient<ValuesOf<TSchema, TEntity>> {\n        return new EntityClient(this, slug);\n    }\n\n    /**\n     * Send a request to the content API. Exposed for endpoints the typed helpers\n     * do not cover yet; `path` is relative to the API base (e.g. `/posts`).\n     */\n    async request<T>(\n        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',\n        path: string,\n        body?: unknown,\n        options: RequestOptions = {},\n    ): Promise<T> {\n        const fetchImplementation = this.options.fetch ?? globalThis.fetch;\n\n        if (typeof fetchImplementation !== 'function') {\n            throw new TypeError(\n                'Flexa: no fetch implementation available. Pass one with the \"fetch\" option.',\n            );\n        }\n\n        const attempts = method === 'GET' ? this.options.retries + 1 : 1;\n        let lastError: unknown;\n\n        for (let attempt = 1; attempt <= attempts; attempt++) {\n            const signals = [\n                AbortSignal.timeout(this.options.timeout),\n                options.signal,\n            ].filter((signal): signal is AbortSignal => signal !== undefined);\n\n            let response: Response;\n\n            try {\n                response = await fetchImplementation(`${this.baseUrl}${path}`, {\n                    ...options.init,\n                    method,\n                    signal:\n                        signals.length > 1\n                            ? AbortSignal.any(signals)\n                            : signals[0],\n                    headers: {\n                        Accept: 'application/json',\n                        ...(body === undefined\n                            ? {}\n                            : { 'Content-Type': 'application/json' }),\n                        ...this.options.headers,\n                        ...(options.init?.headers as\n                            | Record<string, string>\n                            | undefined),\n                        Authorization: `Bearer ${this.options.apiKey}`,\n                    },\n                    body: body === undefined ? undefined : JSON.stringify(body),\n                });\n            } catch (error) {\n                if (options.signal?.aborted || attempt === attempts) {\n                    throw new FlexaError(\n                        error instanceof Error\n                            ? `Flexa request failed: ${error.message}`\n                            : 'Flexa request failed.',\n                        0,\n                    );\n                }\n\n                lastError = error;\n                await sleep(this.backoff(attempt));\n                continue;\n            }\n\n            if (response.ok) {\n                return (\n                    response.status === 204 ? undefined : await response.json()\n                ) as T;\n            }\n\n            if (attempt < attempts && RETRYABLE_STATUSES.has(response.status)) {\n                await sleep(\n                    this.backoff(attempt, response.headers.get('Retry-After')),\n                );\n                continue;\n            }\n\n            throw await this.toError(response);\n        }\n\n        throw lastError;\n    }\n\n    private backoff(attempt: number, retryAfter?: string | null): number {\n        const seconds = Number(retryAfter);\n\n        if (retryAfter && Number.isFinite(seconds)) {\n            return Math.min(seconds * 1000, 30_000);\n        }\n\n        return 250 * 2 ** (attempt - 1);\n    }\n\n    private async toError(response: Response): Promise<FlexaError> {\n        let body: unknown = null;\n\n        try {\n            body = await response.json();\n        } catch {\n            // Not a JSON body.\n        }\n\n        const payload = (body ?? {}) as { message?: unknown; errors?: unknown };\n        const message =\n            typeof payload.message === 'string' && payload.message !== ''\n                ? payload.message\n                : `Flexa request failed with status ${response.status}.`;\n\n        return new FlexaError(\n            message,\n            response.status,\n            (payload.errors && typeof payload.errors === 'object'\n                ? payload.errors\n                : {}) as Record<string, string[]>,\n            body,\n        );\n    }\n}\n\n/**\n * Entries of one entity: list, read, create, update, delete and restore.\n */\nexport class EntityClient<TValues extends object = EntryValues> {\n    constructor(\n        private readonly client: RequestSender,\n        readonly slug: string,\n    ) {}\n\n    private get path(): string {\n        return `/${encodeURIComponent(this.slug)}`;\n    }\n\n    /** Fields, groups, categories and locales of the entity. */\n    async schema(options?: RequestOptions): Promise<EntitySchema> {\n        const response = await this.client.request<{ data: EntitySchema }>(\n            'GET',\n            `${this.path}/schema`,\n            undefined,\n            options,\n        );\n\n        return response.data;\n    }\n\n    /** One page of entries. */\n    list(\n        params: ListParams = {},\n        options?: RequestOptions,\n    ): Promise<Paginated<Entry<TValues>>> {\n        const query = new URLSearchParams();\n\n        for (const [key, value] of Object.entries({\n            status: params.status,\n            search: params.search,\n            category: params.category,\n            page: params.page,\n            per_page: params.perPage,\n            trashed: params.trashed,\n            include: params.includeRelations ? 'relations' : undefined,\n        })) {\n            if (value !== undefined && value !== null && value !== '') {\n                query.set(key, String(value));\n            }\n        }\n\n        const search = query.toString();\n\n        return this.client.request(\n            'GET',\n            `${this.path}${search ? `?${search}` : ''}`,\n            undefined,\n            options,\n        );\n    }\n\n    /** Iterate over every matching entry, fetching pages as needed. */\n    async *iterate(\n        params: Omit<ListParams, 'page'> = {},\n        options?: RequestOptions,\n    ): AsyncGenerator<Entry<TValues>> {\n        let page = 1;\n        let lastPage = 1;\n\n        do {\n            const result = await this.list(\n                { perPage: 100, ...params, page },\n                options,\n            );\n\n            yield* result.data;\n            lastPage = result.meta.last_page;\n            page++;\n        } while (page <= lastPage);\n    }\n\n    /** Every matching entry, across all pages. */\n    async all(\n        params: Omit<ListParams, 'page'> = {},\n        options?: RequestOptions,\n    ): Promise<Entry<TValues>[]> {\n        const entries: Entry<TValues>[] = [];\n\n        for await (const entry of this.iterate(params, options)) {\n            entries.push(entry);\n        }\n\n        return entries;\n    }\n\n    /** An entry by id or slug. Throws a 404 `FlexaError` when it does not exist. */\n    async get(\n        idOrSlug: number | string,\n        params: GetParams = {},\n        options?: RequestOptions,\n    ): Promise<Entry<TValues>> {\n        const query = params.includeRelations ? '?include=relations' : '';\n        const response = await this.client.request<{ data: Entry<TValues> }>(\n            'GET',\n            `${this.path}/${encodeURIComponent(String(idOrSlug))}${query}`,\n            undefined,\n            options,\n        );\n\n        return response.data;\n    }\n\n    /** Like `get()`, but resolves to `null` when the entry does not exist. */\n    async find(\n        idOrSlug: number | string,\n        params: GetParams = {},\n        options?: RequestOptions,\n    ): Promise<Entry<TValues> | null> {\n        try {\n            return await this.get(idOrSlug, params, options);\n        } catch (error) {\n            if (error instanceof FlexaError && error.isNotFound) {\n                return null;\n            }\n\n            throw error;\n        }\n    }\n\n    /** Create an entry. Needs the Write ability. */\n    async create(\n        input: EntryInput<TValues>,\n        options?: RequestOptions,\n    ): Promise<Entry<TValues>> {\n        const response = await this.client.request<{ data: Entry<TValues> }>(\n            'POST',\n            this.path,\n            input,\n            options,\n        );\n\n        return response.data;\n    }\n\n    /** Partially update an entry. Needs the Write ability. */\n    async update(\n        idOrSlug: number | string,\n        input: EntryInput<TValues>,\n        options?: RequestOptions,\n    ): Promise<Entry<TValues>> {\n        const response = await this.client.request<{ data: Entry<TValues> }>(\n            'PATCH',\n            `${this.path}/${encodeURIComponent(String(idOrSlug))}`,\n            input,\n            options,\n        );\n\n        return response.data;\n    }\n\n    /** Move an entry to the trash, or delete it for good with `force`. Needs the Delete ability. */\n    async delete(\n        idOrSlug: number | string,\n        params: { force?: boolean } = {},\n        options?: RequestOptions,\n    ): Promise<void> {\n        await this.client.request(\n            'DELETE',\n            `${this.path}/${encodeURIComponent(String(idOrSlug))}${params.force ? '?force=1' : ''}`,\n            undefined,\n            options,\n        );\n    }\n\n    /** Restore a trashed entry. Needs the Write ability. */\n    async restore(\n        idOrSlug: number | string,\n        options?: RequestOptions,\n    ): Promise<Entry<TValues>> {\n        const response = await this.client.request<{ data: Entry<TValues> }>(\n            'POST',\n            `${this.path}/${encodeURIComponent(String(idOrSlug))}/restore`,\n            undefined,\n            options,\n        );\n\n        return response.data;\n    }\n}\n\nexport function createClient<TSchema extends object = ContentSchema>(\n    options: FlexaClientOptions,\n): FlexaClient<TSchema> {\n    return new FlexaClient<TSchema>(options);\n}\n","import type { Localized } from './types';\n\n/**\n * Whether a field value is a translatable value ({ \"en\": \"...\", \"es\": \"...\" }).\n */\nexport function isLocalized(\n    value: unknown,\n    locales?: readonly string[],\n): value is Localized<unknown> {\n    if (value === null || typeof value !== 'object' || Array.isArray(value)) {\n        return false;\n    }\n\n    const keys = Object.keys(value);\n\n    if (keys.length === 0) {\n        return false;\n    }\n\n    return locales\n        ? keys.every((key) => locales.includes(key))\n        : keys.every((key) => /^[a-z]{2,3}([_-][A-Za-z]{2,4})?$/.test(key));\n}\n\n/**\n * Pick one locale of a translatable value, falling back to the given locales\n * (and then to the first non-empty translation). Plain values pass through.\n */\nexport function localize<T>(\n    value: Localized<T> | T | null | undefined,\n    locale: string,\n    fallbacks: readonly string[] = [],\n): T | null {\n    if (value === null || value === undefined) {\n        return null;\n    }\n\n    if (!isLocalized(value)) {\n        return value as T;\n    }\n\n    const translations = value as Localized<T>;\n\n    for (const candidate of [locale, ...fallbacks]) {\n        const translation = translations[candidate];\n\n        if (\n            translation !== null &&\n            translation !== undefined &&\n            translation !== ''\n        ) {\n            return translation;\n        }\n    }\n\n    for (const translation of Object.values(translations)) {\n        if (\n            translation !== null &&\n            translation !== undefined &&\n            translation !== ''\n        ) {\n            return translation;\n        }\n    }\n\n    return null;\n}\n"],"mappings":"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","names":[]}