@capacms/sdk 1.0.0-next.0 → 1.0.0-next.10

package/dist/next/inflate.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSelectLevels = parseSelectLevels;
+exports.inflate = inflate;
+/**
+ * inflate.ts — turn a `shape=flat` response back into the `shape=tree` one.
+ *
+ * A flat response carries every expanded entry once, in `included`, keyed by
+ * model namespace and then id, and every relation as a `{ id, model }`
+ * reference. `inflate` walks the SAME select the request sent and puts each
+ * referenced entry back where the tree would have nested it, holding exactly
+ * the system keys and fields that path selected. The result is deep-equal to
+ * the `shape=tree` body for the same request (amendment 16 of the api-next spec
+ * names the one exception).
+ *
+ * WHY IT NEEDS THE SELECT. An included entry holds the UNION of every path that
+ * reached it, and an entry in `data` also carries what any relation path asked
+ * of it. Only the select says which of those fields belong at which place in
+ * the tree, and which references were expanded. A result from this SDK's
+ * `shape: "flat"` read carries the select it sent (`response.select`), so
+ * `inflate(response)` is enough; for a body fetched by hand, pass the select
+ * you sent as the second argument. A request that sent no select expanded
+ * nothing, and `inflate` returns its data unchanged.
+ *
+ * COPIES, NEVER SHARED INSTANCES. Every entry in the result is a new object,
+ * and so is every value inside it: the same author reached from twenty
+ * articles comes back as twenty equal, independent objects, exactly as the
+ * tree response parses. Mutating one never changes another, the input is never
+ * modified, and `JSON.stringify` of the result cannot meet a cycle.
+ *
+ * CYCLES END WHERE THE SELECT ENDS. `a` related to `b` related to `a` is
+ * inflated to the depth the select wrote (at most four levels, the API's cap)
+ * and no further: the walk follows the select, never the references, so it
+ * cannot loop. A reference the select did not expand stays a reference.
+ */
+const attrs_1 = require("./attrs");
+const system_keys_1 = require("./system-keys");
+const field_names_1 = require("./field-names");
+const ALWAYS_KEYS = new Set(["id", "model", "status"]);
+/**
+ * The select grammar, read only as far as `inflate` needs it: names, bare or
+ * quoted (`"price.usd"`, spec 17 amendment 121), nesting and `*`. Modifiers
+ * (`limit:`, `sort:`, `after:`) decide which rows the API returned, which the
+ * response already reflects, so they are skipped. The API validated the
+ * select before answering, so this parser trusts its shape and throws a
+ * `TypeError` only on text it cannot split at all.
+ */
+function parseSelectLevels(select) {
+    let pos = 0;
+    const fail = () => {
+        throw new TypeError(`@capacms/sdk/next: inflate could not read the select ${JSON.stringify(select)}.`);
+    };
+    /** The quoted name at `pos`, read back, with `pos` moved past it. */
+    const quotedAt = () => {
+        const read = (0, field_names_1.readQuoted)(select, pos);
+        if (!read)
+            return fail();
+        pos = read.end;
+        return read.name;
+    };
+    const level = () => {
+        const out = { star: false, items: [] };
+        for (;;) {
+            const quoted = select[pos] === field_names_1.NAME_QUOTE;
+            let token = "";
+            if (quoted) {
+                token = quotedAt();
+            }
+            else {
+                const start = pos;
+                // A modifier's value may quote a name too: `sort:-"zip.code"`.
+                while (pos < select.length && !",()".includes(select[pos])) {
+                    if (select[pos] === field_names_1.NAME_QUOTE)
+                        quotedAt();
+                    else
+                        pos += 1;
+                }
+                token = select.slice(start, pos);
+            }
+            if (select[pos] === "(") {
+                if (token === "")
+                    fail();
+                pos += 1;
+                const inner = level();
+                if (select[pos] !== ")")
+                    fail();
+                pos += 1;
+                out.items.push({ name: token, expand: inner, ...(quoted ? { quoted } : {}) });
+            }
+            else if (!quoted && token === "*") {
+                out.star = true;
+            }
+            else if (!quoted && token.includes(":")) {
+                // A modifier: `limit:2`, `sort:-name`, `after:<cursor>`.
+            }
+            else if (quoted || token !== "") {
+                out.items.push({ name: token, expand: null, ...(quoted ? { quoted } : {}) });
+            }
+            else {
+                fail();
+            }
+            if (select[pos] !== ",")
+                return out;
+            pos += 1;
+        }
+    };
+    const root = level();
+    if (pos !== select.length)
+        fail();
+    return root;
+}
+// ----------------------------------------------------------------- walk ----
+function clone(value) {
+    if (Array.isArray(value))
+        return value.map(clone);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, inner] of Object.entries(value))
+            out[key] = clone(inner);
+        return out;
+    }
+    return value;
+}
+function isReference(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        typeof value.id === "string" &&
+        !("fields" in value));
+}
+function resolve(index, ref) {
+    if (ref.missing)
+        return null;
+    const fromIncluded = ref.model ? index.included[ref.model]?.[ref.id] : undefined;
+    if (fromIncluded && typeof fromIncluded === "object")
+        return fromIncluded;
+    return index.data.get(ref.id) ?? null;
+}
+/**
+ * One entry as the tree holds it at a place whose select is `level`. `null`
+ * is "no select was sent", which is every key and every field, unexpanded.
+ */
+function project(entry, level, index) {
+    const fields = (entry.fields ?? {});
+    const all = level === null || level.star;
+    // `$tags` is always the system key (spec 17, amendment 29). A plain name is
+    // a FIELD when the entry has a field of that name, otherwise a system key:
+    // a model field shadows a system key of the same name (spec 3.3), and a
+    // path that selected the field is exactly what put it here.
+    const wanted = new Set(ALWAYS_KEYS);
+    if (level) {
+        for (const item of level.items) {
+            const system = (0, system_keys_1.sigilSystemKey)(item.name);
+            if (system !== null)
+                wanted.add(system);
+            else if (!item.quoted && !(item.name in fields) && (0, system_keys_1.isSystemKey)(item.name))
+                wanted.add(item.name);
+        }
+    }
+    const out = {};
+    for (const key of system_keys_1.SYSTEM_KEYS) {
+        if (!(key in entry))
+            continue;
+        if (all || wanted.has(key))
+            out[key] = clone(entry[key]);
+    }
+    const expansions = new Map();
+    const names = [];
+    if (level) {
+        for (const item of level.items) {
+            if (item.expand)
+                expansions.set(item.name, item.expand);
+            if (item.name in fields && !all)
+                names.push(item.name);
+        }
+    }
+    if (all)
+        names.push(...Object.keys(fields));
+    const outFields = {};
+    for (const name of names) {
+        const expand = expansions.get(name);
+        outFields[name] = expand ? expandValue(fields[name], expand, index) : clone(fields[name]);
+    }
+    out.fields = outFields;
+    if ((0, attrs_1.isEditEntry)(entry)) {
+        Object.defineProperty(out, attrs_1.CAPA_EDIT, { value: true, enumerable: false, configurable: true });
+    }
+    return out;
+}
+/** A reference, or an array relation's `{ items, pageInfo }`, put back in place. */
+function expandValue(value, level, index) {
+    if (isReference(value)) {
+        const target = resolve(index, value);
+        return target ? project(target, level, index) : clone(value);
+    }
+    if (value && typeof value === "object" && Array.isArray(value.items)) {
+        const list = value;
+        const out = {};
+        for (const [key, inner] of Object.entries(list)) {
+            out[key] =
+                key === "items"
+                    ? list.items.map((item) => expandValue(item, level, index))
+                    : clone(inner);
+        }
+        return out;
+    }
+    return clone(value);
+}
+/**
+ * The tree shape of a flat response: `data` with every expansion nested back
+ * in, `included` and `select` removed, everything else (`page`, `meta`,
+ * `cacheTags`) carried over as it was.
+ *
+ * `select` is what the request sent; it defaults to `response.select`, which
+ * an SDK flat read fills in. A request with no select expanded nothing.
+ */
+function inflate(response, select) {
+    if (!response || typeof response !== "object" || !("included" in response)) {
+        throw new TypeError("@capacms/sdk/next: inflate takes a shape=flat response, which carries included.");
+    }
+    const text = select ?? response.select;
+    const level = text === undefined || text === null ? null : parseSelectLevels(text);
+    const rows = Array.isArray(response.data) ? response.data : [response.data];
+    const index = { included: response.included ?? {}, data: new Map() };
+    for (const row of rows) {
+        if (row && typeof row === "object" && typeof row.id === "string") {
+            index.data.set(row.id, row);
+        }
+    }
+    const inflateRow = (row) => row && typeof row === "object" ? project(row, level, index) : row;
+    const out = {};
+    for (const [key, value] of Object.entries(response)) {
+        if (key === "included" || key === "select")
+            continue;
+        if (key === "data") {
+            out.data = Array.isArray(value) ? value.map(inflateRow) : inflateRow(value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}

package/dist/next/key-family.d.ts

@@ -0,0 +1,31 @@
+/**
+ * key-family.ts — which keys `@capacms/sdk/next` takes, and for what.
+ *
+ * A `cap_` key is the `/api/` key: scoped, hashed at rest, and the only kind
+ * the draft clients take to read drafts. Every other key is legacy, which is
+ * the API's rule (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and
+ * `sk_` keys, and the unprefixed keys older tenants were minted, all reach
+ * `/api/` with the grants their permission gives. So every read call takes
+ * them, `preview()` included: `GET /api/preview` asks for `instance:read`,
+ * which every legacy permission grants, and refuses a token minted for another
+ * tenant. The first client built with one warns once per process, naming the
+ * key to mint.
+ *
+ * The `cap_` prefix is the whole rule, case-sensitive, as on the API:
+ * `CAP_live_…` is not a key Capa mints, so it is looked up as a legacy key.
+ * `@capacms/mcp` applies the same rule, and both packages are tested against one
+ * vector file, `test/fixtures/key-family.json`.
+ */
+export type KeyFamily = "cap" | "legacy";
+/** The family of `apiKey`, or null for a value that is no key at all: not a string, or empty. */
+export declare function keyFamily(apiKey: unknown): KeyFamily | null;
+/** Warn about a legacy key once per process: a site builds a client per request. */
+export declare function warnLegacyKeyOnce(apiKey: string): void;
+/**
+ * Throws for a legacy key: a draft read takes a `cap_` key. `holder` names
+ * where the key came from (`CAPA_DRAFT_KEY`, `the draft config`), so the
+ * message says what to change.
+ */
+export declare function requireDraftKey(apiKey: string, holder: string): void;
+/** Forget that the warning was printed. For tests. */
+export declare function __resetKeyWarningForTests(): void;

package/dist/next/key-family.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * key-family.ts — which keys `@capacms/sdk/next` takes, and for what.
+ *
+ * A `cap_` key is the `/api/` key: scoped, hashed at rest, and the only kind
+ * the draft clients take to read drafts. Every other key is legacy, which is
+ * the API's rule (`apps/api/src/api-next/auth/key-format.ts`): the `pk_` and
+ * `sk_` keys, and the unprefixed keys older tenants were minted, all reach
+ * `/api/` with the grants their permission gives. So every read call takes
+ * them, `preview()` included: `GET /api/preview` asks for `instance:read`,
+ * which every legacy permission grants, and refuses a token minted for another
+ * tenant. The first client built with one warns once per process, naming the
+ * key to mint.
+ *
+ * The `cap_` prefix is the whole rule, case-sensitive, as on the API:
+ * `CAP_live_…` is not a key Capa mints, so it is looked up as a legacy key.
+ * `@capacms/mcp` applies the same rule, and both packages are tested against one
+ * vector file, `test/fixtures/key-family.json`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyFamily = keyFamily;
+exports.warnLegacyKeyOnce = warnLegacyKeyOnce;
+exports.requireDraftKey = requireDraftKey;
+exports.__resetKeyWarningForTests = __resetKeyWarningForTests;
+const LEGACY_PREFIX = /^(pk|sk)_/;
+/** The family of `apiKey`, or null for a value that is no key at all: not a string, or empty. */
+function keyFamily(apiKey) {
+    if (typeof apiKey !== "string" || apiKey === "")
+        return null;
+    return apiKey.startsWith("cap_") ? "cap" : "legacy";
+}
+function isLegacy(apiKey) {
+    return keyFamily(apiKey) === "legacy";
+}
+/**
+ * How a message names a legacy key: by its `pk_` or `sk_` prefix, and an
+ * unprefixed key by that fact alone, since every other character is the secret.
+ */
+function legacyKind(apiKey) {
+    const prefix = LEGACY_PREFIX.exec(apiKey)?.[0];
+    return prefix ? `legacy ${prefix} key` : "legacy key with no pk_ or sk_ prefix";
+}
+const MINT = "in the Capa admin under Developers > Keys.";
+let warned = false;
+/** Warn about a legacy key once per process: a site builds a client per request. */
+function warnLegacyKeyOnce(apiKey) {
+    if (warned)
+        return;
+    warned = true;
+    console.warn(`@capacms/sdk/next: this client reads with a ${legacyKind(apiKey)}. Reads and preview links work as they do with a cap_ key. ` +
+        `Draft reads need a cap_ key: mint one ${MINT}`);
+}
+/**
+ * Throws for a legacy key: a draft read takes a `cap_` key. `holder` names
+ * where the key came from (`CAPA_DRAFT_KEY`, `the draft config`), so the
+ * message says what to change.
+ */
+function requireDraftKey(apiKey, holder) {
+    if (!isLegacy(apiKey))
+        return;
+    throw new TypeError(`@capacms/sdk/next: draft reads need a cap_ key, and ${holder} holds a ${legacyKind(apiKey)}. Mint a development cap_ key ${MINT}`);
+}
+/** Forget that the warning was printed. For tests. */
+function __resetKeyWarningForTests() {
+    warned = false;
+}

package/dist/next/select-types.d.ts

@@ -1,3 +1,4 @@
+import type { SortableSystemKeyName, SystemKeyName } from "./system-keys";
 /** A single relation field emitted by `capa-codegen`. */
 export type CapaRelation<T> = T & {
     readonly __capaRelation: "one";
@@ -13,14 +14,38 @@ type RelationValue = {
     readonly __capaRelation: "one" | "many";
     readonly __capaRelationTarget: unknown;
 };
+/**
+ * A field type that says nothing about the field: `unknown`, as every field
+ * of an untyped client's `Record<string, unknown>` is, or `any`, as a type
+ * inferred from a select's names is. Such a field may be a relation or not.
+ */
+type Untyped<V> = 0 extends 1 & V ? true : unknown extends V ? true : false;
+type UntypedKeys<T> = {
+    [K in StringKey<T>]-?: Untyped<T[K]> extends true ? K : never;
+}[StringKey<T>];
 type RelationKeys<T> = {
-    [K in StringKey<T>]-?: NonNullable<T[K]> extends RelationValue ? K : never;
+    [K in StringKey<T>]-?: Untyped<T[K]> extends true ? never : NonNullable<T[K]> extends RelationValue ? K : never;
 }[StringKey<T>];
 type ScalarKeys<T> = Exclude<StringKey<T>, RelationKeys<T>>;
 type RelationTarget<T> = NonNullable<T> extends {
     readonly __capaRelationTarget: infer R;
 } ? R : never;
-export type SelectSort<T> = ScalarKeys<T> | `-${ScalarKeys<T>}`;
+/**
+ * A system key by its `$` name. The API reads a plain name as the model's
+ * field first, so `$tags` is how a select or sort asks for the entry's own
+ * tags beside a field called `tags` (spec 17, amendment 29).
+ */
+export type SystemKey = `$${SystemKeyName}`;
+/** A system key the API sorts by: `$id`, `$createdAt`, `$updatedAt`, `$publishedAt`. */
+export type SortableSystemKey = `$${SortableSystemKeyName}`;
+/**
+ * A field the grammar can name: every one but a namespace starting with `$`,
+ * which is a system key's spelling (spec 17, amendment 121). `select: "*"`
+ * still returns such a field. A namespace holding `.` or `,` is named as it
+ * is (`"price.usd"`), and the client writes it quoted.
+ */
+type Nameable<K extends string> = Exclude<K, `$${string}`>;
+export type SelectSort<T> = Nameable<ScalarKeys<T>> | `-${Nameable<ScalarKeys<T>>}` | SortableSystemKey | `-${SortableSystemKey}`;
 export interface RelationSelectOptions<T> {
     select: Select<T> | "*";
     limit?: number;
@@ -31,9 +56,37 @@ export interface RelationSelectOptions<T> {
 type RelationSelect<T, K extends RelationKeys<T>> = {
     [P in K]: Select<RelationTarget<T[P]>> | "*" | RelationSelectOptions<RelationTarget<T[P]>>;
 };
-export type SelectItem<T> = "*" | ScalarKeys<T> | {
-    [K in RelationKeys<T>]: RelationSelect<T, K>;
-}[RelationKeys<T>];
+/** An expansion of a field whose type says nothing (`Untyped`): its target is read untyped too. */
+type UntypedRelationSelect<K extends string> = {
+    [P in K]: Select<Record<string, unknown>> | "*" | RelationSelectOptions<Record<string, unknown>>;
+};
+/**
+ * One item of a select: `*`, a field by name (a relation named alone is read
+ * as a reference, `{ id, model }`), a system key by its `$` name, or a
+ * relation expanded into the fields its own select names. A field whose
+ * namespace starts with `$` has no name (`Nameable`).
+ */
+export type SelectItem<T> = "*" | Nameable<ScalarKeys<T>> | Nameable<RelationKeys<T>> | SystemKey | {
+    [K in Nameable<RelationKeys<T>>]: RelationSelect<T, K>;
+}[Nameable<RelationKeys<T>>] | ([UntypedKeys<T>] extends [never] ? never : UntypedRelationSelect<UntypedKeys<T>>);
 /** A typed form of the `/api/entries` `select` grammar. */
 export type Select<T> = ReadonlyArray<SelectItem<T>>;
+type Depth = [never, 0, 1, 2, 3, 4];
+/** The target types one select item expands, and everything below them. */
+type ItemTargets<T, I, D extends number> = [D] extends [never] ? never : I extends string ? never : {
+    [K in Extract<keyof I, RelationKeys<T>>]: RelationTarget<T[K]> | ValueTargets<RelationTarget<T[K]>, I[K], Depth[D]>;
+}[Extract<keyof I, RelationKeys<T>>] | ([Extract<keyof I, UntypedKeys<T>>] extends [never] ? never : Record<string, unknown>);
+type ValueTargets<R, V, D extends number> = V extends "*" ? never : V extends {
+    select: infer S;
+} ? ExpandedTargetsAt<R, S, D> : ExpandedTargetsAt<R, V, D>;
+type ExpandedTargetsAt<T, S, D extends number> = S extends ReadonlyArray<infer I> ? ItemTargets<T, I, D> : never;
+/**
+ * Every entry type a select EXPANDS, at any depth: what `included` can hold
+ * for a `shape: "flat"` read. `[{ author: ["name"] }]` on an article is
+ * `Author`; a select given as a string cannot be read by the type system and is
+ * `Record<string, unknown>`. Bounded one level past the 4 relations the API
+ * reads below the root entry, so a model that relates to itself does not
+ * recurse forever.
+ */
+export type ExpandedTargets<T, S> = S extends string ? Record<string, unknown> : [ExpandedTargetsAt<T, S, 4>] extends [never] ? never : ExpandedTargetsAt<T, S, 4>;
 export {};

package/dist/next/system-keys.d.ts

@@ -0,0 +1,27 @@
+/**
+ * system-keys.ts — the entry's own keys, as REST names them.
+ *
+ * Every entry REST returns carries these beside `fields`, in this order. A
+ * request names one plainly (`tags`) only where the model has no field of that
+ * name, because REST reads a plain name as the field first; `$tags` always
+ * means the system key, in `select`, `where` and `sort`, and after a hop as
+ * `author.$id` (spec 17, amendment 29). REST names no field whose namespace
+ * starts with `$` (field-names.ts), so no field is ever spelled like one.
+ */
+/** The system keys, in the order the API prints them on an entry. */
+export declare const SYSTEM_KEYS: readonly ["id", "model", "status", "createdAt", "updatedAt", "publishedAt", "version", "folder", "tags"];
+export type SystemKeyName = (typeof SYSTEM_KEYS)[number];
+/**
+ * The system keys the API sorts by, as `packages/shared`'s `SORTABLE_SYSTEM_KEYS`
+ * lists them: `$tags` is a list and `$version`, `$model`, `$status` and
+ * `$folder` are refused as sort keys.
+ */
+export declare const SORTABLE_SYSTEM_KEYS: readonly ["id", "createdAt", "updatedAt", "publishedAt"];
+export type SortableSystemKeyName = (typeof SORTABLE_SYSTEM_KEYS)[number];
+export declare function isSortableSystemKey(name: string): name is SortableSystemKeyName;
+export declare const SYSTEM_KEY_SIGIL = "$";
+export declare function isSystemKey(name: string): name is SystemKeyName;
+/** Every system key by its `$` name, for a message that lists them. */
+export declare const SYSTEM_KEY_LIST: string;
+/** The system key a `$` name spells (`$tags` is `tags`), or null for any other name. */
+export declare function sigilSystemKey(name: string): SystemKeyName | null;

package/dist/next/system-keys.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * system-keys.ts — the entry's own keys, as REST names them.
+ *
+ * Every entry REST returns carries these beside `fields`, in this order. A
+ * request names one plainly (`tags`) only where the model has no field of that
+ * name, because REST reads a plain name as the field first; `$tags` always
+ * means the system key, in `select`, `where` and `sort`, and after a hop as
+ * `author.$id` (spec 17, amendment 29). REST names no field whose namespace
+ * starts with `$` (field-names.ts), so no field is ever spelled like one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_KEY_LIST = exports.SYSTEM_KEY_SIGIL = exports.SORTABLE_SYSTEM_KEYS = exports.SYSTEM_KEYS = void 0;
+exports.isSortableSystemKey = isSortableSystemKey;
+exports.isSystemKey = isSystemKey;
+exports.sigilSystemKey = sigilSystemKey;
+/** The system keys, in the order the API prints them on an entry. */
+exports.SYSTEM_KEYS = ["id", "model", "status", "createdAt", "updatedAt", "publishedAt", "version", "folder", "tags"];
+/**
+ * The system keys the API sorts by, as `packages/shared`'s `SORTABLE_SYSTEM_KEYS`
+ * lists them: `$tags` is a list and `$version`, `$model`, `$status` and
+ * `$folder` are refused as sort keys.
+ */
+exports.SORTABLE_SYSTEM_KEYS = ["id", "createdAt", "updatedAt", "publishedAt"];
+const SORTABLE_SYSTEM_KEY_SET = new Set(exports.SORTABLE_SYSTEM_KEYS);
+function isSortableSystemKey(name) {
+    return SORTABLE_SYSTEM_KEY_SET.has(name);
+}
+exports.SYSTEM_KEY_SIGIL = "$";
+const SYSTEM_KEY_SET = new Set(exports.SYSTEM_KEYS);
+function isSystemKey(name) {
+    return SYSTEM_KEY_SET.has(name);
+}
+/** Every system key by its `$` name, for a message that lists them. */
+exports.SYSTEM_KEY_LIST = exports.SYSTEM_KEYS.map((key) => `${exports.SYSTEM_KEY_SIGIL}${key}`).join(", ");
+/** The system key a `$` name spells (`$tags` is `tags`), or null for any other name. */
+function sigilSystemKey(name) {
+    if (!name.startsWith(exports.SYSTEM_KEY_SIGIL))
+        return null;
+    const key = name.slice(exports.SYSTEM_KEY_SIGIL.length);
+    return isSystemKey(key) ? key : null;
+}

package/dist/nextjs/image-loader.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `@capacms/sdk/nextjs/image-loader`: a next/image loader that lets Capa's CDN
+ * resize, in place of Next's own image optimization.
+ *
+ * Its own entry point, apart from `@capacms/sdk/nextjs`, because next/image
+ * runs the loader in the browser: `images.loaderFile` puts this module in
+ * every page that shows an image, and this entry carries the image rules and
+ * nothing else. `@capacms/sdk/nextjs` exports the same functions for server
+ * code.
+ *
+ * ```js
+ * // next.config.mjs
+ * export default { images: { loader: "custom", loaderFile: "./capa-image-loader.js" } };
+ *
+ * // capa-image-loader.js
+ * "use client";
+ * import { createCapaImageLoader } from "@capacms/sdk/nextjs/image-loader";
+ * export default createCapaImageLoader({ format: "webp" });
+ * ```
+ */
+import { type ImageFormat } from "../image/index.js";
+/** What next/image passes a loader. Declared here so this module does not import `next`. */
+export interface CapaImageLoaderProps {
+    src: string;
+    width: number;
+    quality?: number;
+}
+/** A next/image loader. */
+export type CapaImageLoader = (props: CapaImageLoaderProps) => string;
+/** What every image through the loader gets, unless next/image's own props say otherwise. */
+export interface CapaImageLoaderOptions {
+    /**
+     * The format to encode. Left out, each image keeps its own. `auto` picks AVIF
+     * or WebP from the browser's `Accept` header; through the CDN it currently
+     * returns JPEG, so use `webp` until that is fixed.
+     */
+    format?: ImageFormat;
+    /** Quality when an `<Image>` gives none, 1 to 100. Left out, Capa's default, 80. */
+    quality?: number;
+}
+/**
+ * A next/image loader with fixed options. A `src` that is a full Capa URL
+ * (`https://cdn.capacms.com/files/...`, or `https://api.capacms.com/files/...`,
+ * which is built on the CDN host) is resized to the width next/image asks for.
+ * Any other `src` (a file in `public/`, a bare file name, another host) is
+ * returned unchanged.
+ *
+ * The loader never throws, since a throw would fail the render of the whole
+ * page: a `src` or prop the CDN would refuse (`dpr=2` past the 4096-pixel
+ * edge, `quality=abc` in the src, `quality={0}`) gets the `src` back unchanged.
+ * The options given here are checked once, when the loader is made, so a bad
+ * one fails at build time rather than on every image.
+ */
+export declare function createCapaImageLoader(options?: CapaImageLoaderOptions): CapaImageLoader;
+/**
+ * The next/image loader with no options: each image keeps its own format, and
+ * its quality is the `<Image>`'s `quality` prop or Capa's default.
+ */
+export declare const capaImageLoader: CapaImageLoader;
+export default capaImageLoader;

package/dist/nextjs/image-loader.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capaImageLoader = void 0;
+exports.createCapaImageLoader = createCapaImageLoader;
+/**
+ * `@capacms/sdk/nextjs/image-loader`: a next/image loader that lets Capa's CDN
+ * resize, in place of Next's own image optimization.
+ *
+ * Its own entry point, apart from `@capacms/sdk/nextjs`, because next/image
+ * runs the loader in the browser: `images.loaderFile` puts this module in
+ * every page that shows an image, and this entry carries the image rules and
+ * nothing else. `@capacms/sdk/nextjs` exports the same functions for server
+ * code.
+ *
+ * ```js
+ * // next.config.mjs
+ * export default { images: { loader: "custom", loaderFile: "./capa-image-loader.js" } };
+ *
+ * // capa-image-loader.js
+ * "use client";
+ * import { createCapaImageLoader } from "@capacms/sdk/nextjs/image-loader";
+ * export default createCapaImageLoader({ format: "webp" });
+ * ```
+ */
+const index_js_1 = require("../image/index.js");
+/**
+ * A next/image loader with fixed options. A `src` that is a full Capa URL
+ * (`https://cdn.capacms.com/files/...`, or `https://api.capacms.com/files/...`,
+ * which is built on the CDN host) is resized to the width next/image asks for.
+ * Any other `src` (a file in `public/`, a bare file name, another host) is
+ * returned unchanged.
+ *
+ * The loader never throws, since a throw would fail the render of the whole
+ * page: a `src` or prop the CDN would refuse (`dpr=2` past the 4096-pixel
+ * edge, `quality=abc` in the src, `quality={0}`) gets the `src` back unchanged.
+ * The options given here are checked once, when the loader is made, so a bad
+ * one fails at build time rather than on every image.
+ */
+function createCapaImageLoader(options = {}) {
+    const { format, quality } = options;
+    try {
+        (0, index_js_1.imageUrl)("x", { format, quality });
+    }
+    catch (error) {
+        throw new TypeError(String(error.message).replace("imageUrl:", "createCapaImageLoader:"));
+    }
+    return (props) => {
+        // Everything inside the try, the props' own destructuring included: a call
+        // with no props object gives back no src rather than throwing.
+        try {
+            const { src, width, quality: asked } = props;
+            if (!(0, index_js_1.isCapaImageUrl)(src))
+                return src;
+            return (0, index_js_1.imageUrl)(src, {
+                // A width past Capa's edge asks for the edge, which keeps the image resized.
+                width: Math.min(width, index_js_1.MAX_OUTPUT_EDGE),
+                quality: asked ?? quality,
+                format,
+            });
+        }
+        catch {
+            return props?.src;
+        }
+    };
+}
+/**
+ * The next/image loader with no options: each image keeps its own format, and
+ * its quality is the `<Image>`'s `quality` prop or Capa's default.
+ */
+exports.capaImageLoader = createCapaImageLoader();
+exports.default = exports.capaImageLoader;