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

package/dist/image/shared-params.generated.js

@@ -0,0 +1,471 @@
+"use strict";
+// GENERATED by scripts/shared-image.js from packages/shared/src/image/params.ts, the rules the API serves
+// /files/* by. Do not edit: change the source, and the API and this package follow.
+/**
+ * Query parsing, validation and canonicalisation for `GET /files/*`
+ * (ADMIN_UI_OVERHAUL §0i.1, "The image processor, made tight").
+ *
+ * PURE ON PURPOSE. Nothing here touches sharp, the network or the database, so
+ * the whole parameter surface — every accepted value, every rejection, and the
+ * canonical spelling of every URL — is testable without a server and without a
+ * live Backblaze object. That matters for this route in particular: its eight
+ * parity fixtures are all 400/404 cases because a DB hit immediately leaves the
+ * process (docs/TURBINE_PORT_NOTES.md, "Deferred to the P6 cloud parity pass"),
+ * so the transform surface has no golden coverage at all unless it is reachable
+ * from a unit test.
+ *
+ * THE RULE THAT SHAPES EVERYTHING BELOW: a caller that sends only today's three
+ * parameters (`width`, `height`, `blur`) must get today's response. Every
+ * default here is therefore today's behaviour, and the one place that could
+ * have broken it — the canonical-query redirect — is deliberately gated on a
+ * NEW parameter being present. See `canonicalise`.
+ *
+ * WHY IT LIVES IN @capa/shared. `@capacms/sdk` builds image URLs, and a URL
+ * that is not spelled the way `canonicalise` spells it costs every first view
+ * a 301 that the edge then keeps for a year. So the SDK compiles this file into
+ * its own build rather than keeping a second copy of the rules, and its tests
+ * run what it builds back through `canonicalise`. The API imports it from here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEW_PARAMS = exports.LEGACY_PARAMS = exports.AVIF_DEFAULT_QUALITY = exports.DEFAULT_QUALITY = exports.MAX_BLUR = exports.MIN_BLUR = exports.MAX_OUTPUT_EDGE = exports.OUTPUT_MIME = void 0;
+exports.defaultQuality = defaultQuality;
+exports.droppableQuality = droppableQuality;
+exports.parseImageParams = parseImageParams;
+exports.canonicalise = canonicalise;
+exports.canonicalQuery = canonicalQuery;
+exports.buildSignature = buildSignature;
+exports.resolveAutoFormat = resolveAutoFormat;
+/** Content type emitted for each explicitly requestable output format. */
+exports.OUTPUT_MIME = {
+    webp: "image/webp",
+    avif: "image/avif",
+    jpeg: "image/jpeg",
+    png: "image/png",
+};
+/**
+ * The longest edge this route will ever produce.
+ *
+ * A cap rather than a clamp, because a clamp makes two different URLs return
+ * the same bytes and therefore occupy two edge objects for one representation.
+ * 4096 is the §0i.1 figure; it is also comfortably above any real layout width
+ * at dpr 3 (1365 CSS px).
+ */
+exports.MAX_OUTPUT_EDGE = 4096;
+/** Today's blur bounds, previously applied as a silent clamp. */
+exports.MIN_BLUR = 1;
+exports.MAX_BLUR = 256;
+/** Default quality for lossy outputs except AVIF. Ignored for png, which is lossless. */
+exports.DEFAULT_QUALITY = 80;
+/**
+ * AVIF's own default quality (Penelope Hospitality onboarding, #300). At 80,
+ * AVIF came back larger than WebP at 80; 60 at effort 2 is 16 to 18% smaller
+ * than WebP with equal or better SSIM on eight client photos. The route's
+ * encoder and the effort live in apps/api (image-transform.ts); the number
+ * lives here because canonicalQuery has to know it (see droppableQuality).
+ */
+exports.AVIF_DEFAULT_QUALITY = 60;
+/**
+ * The quality an encode into `output` uses when the URL names none.
+ *
+ * The route only ever calls this with a format the URL asked for, explicitly or
+ * through `auto`: with no `format` and no `quality` it selects no encoder at
+ * all and the source keeps its own format (`resolveOutputFormat`).
+ */
+function defaultQuality(output) {
+    return output === "avif" ? exports.AVIF_DEFAULT_QUALITY : exports.DEFAULT_QUALITY;
+}
+/**
+ * The `quality` canonicalQuery drops from a URL with this `format`, or null
+ * when it keeps every value.
+ *
+ * CANONICALISATION MUST NEVER CHANGE WHAT A URL RENDERS. A value may be dropped
+ * only when the URL without it encodes at that same value. After #300 gave
+ * AVIF its own default, dropping 80 everywhere sent `format=avif&quality=80`
+ * to `format=avif`, which is quality 60.
+ *
+ * - `avif`: null. 80 is not AVIF's default, so it must stay. 60 is, and could
+ *   be dropped without changing the bytes; it is KEPT ON PURPOSE. The SDK's
+ *   frozen URLs (#316, and @capacms/sdk's own tests) include
+ *   `format=avif&quality=60`, which would start taking a 301; and an explicit
+ *   number keeps meaning that number if AVIF's default is retuned, which
+ *   `format=avif` does not. The cost is two edge objects for one image when a
+ *   caller spells the default out.
+ * - `auto`: null. Negotiation picks AVIF (default 60) or WebP or the source's
+ *   own format (default 80), so no single value means "no quality" for every
+ *   browser.
+ * - `webp`, `jpeg`, `png` and no format: DEFAULT_QUALITY, as before.
+ *
+ * KNOWN GAP, older than #300 and left as it is because a URL with no `format`
+ * keeps its spelling: with no format the output follows the SOURCE, which a URL
+ * cannot see. `?quality=80&width=200` on an AVIF or HEIF source is an AVIF at
+ * 80, and `?width=200` keeps sharp's own AVIF default (50). `?quality=80` with
+ * nothing else redirects to the bare URL, which is the stored file, not a
+ * re-encode.
+ */
+function droppableQuality(format) {
+    if (format === "avif" || format === "auto")
+        return null;
+    return exports.DEFAULT_QUALITY;
+}
+/**
+ * The parameters that existed before §0i.1.
+ *
+ * A URL built only from these is GRANDFATHERED: it is treated as already
+ * canonical and is never redirected, however it is spelled. Without this, every
+ * live `?width=100&height=50` in every customer's markup would start taking a
+ * 301 — which is not a behaviour anyone asked to change, and "keep today's
+ * calls byte-identical" outranks de-duplicating an edge object that has been
+ * duplicated for years already.
+ */
+exports.LEGACY_PARAMS = new Set(["width", "height", "blur"]);
+/** Parameters introduced by §0i.1. Their presence is what enables canonicalisation. */
+exports.NEW_PARAMS = new Set(["format", "quality", "fit", "dpr", "upscale", "keepMetadata"]);
+/**
+ * Fastify gives `?a=1&a=2` as an array. A repeated parameter has no defensible
+ * meaning here and silently picking one is exactly the "never silently ignored"
+ * failure §0i.1 calls out, so it is a rejection.
+ */
+function single(raw, param) {
+    if (raw === undefined || raw === null)
+        return { ok: true };
+    if (Array.isArray(raw)) {
+        return { ok: false, rejection: { error: `\`${param}\` was given more than once`, param } };
+    }
+    if (typeof raw !== "string") {
+        return { ok: false, rejection: { error: `\`${param}\` must be a single value`, param } };
+    }
+    return { ok: true, value: raw };
+}
+/**
+ * Strict integer parse.
+ *
+ * `parseInt` is what this route used to do and it is the reason `?width=abc`
+ * was a 500: `parseInt("abc")` is NaN, NaN reaches sharp, sharp throws, and the
+ * outer catch turns a bad request into "Failed to process file". `parseInt`
+ * also accepts `12px` and `0x10`. Neither is a width.
+ */
+function strictInt(value) {
+    if (!/^-?\d+$/.test(value.trim()))
+        return null;
+    const n = Number(value.trim());
+    return Number.isSafeInteger(n) ? n : null;
+}
+function strictNumber(value) {
+    if (!/^-?\d+(\.\d+)?$/.test(value.trim()))
+        return null;
+    const n = Number(value.trim());
+    return Number.isFinite(n) ? n : null;
+}
+const BOOL_TRUE = new Set(["1", "true"]);
+const BOOL_FALSE = new Set(["0", "false"]);
+/**
+ * Parse and validate the whole query in one pass.
+ *
+ * Unknown VALUES for a known parameter are rejected. Unknown KEYS are not:
+ * `?v=3` cache-busters and analytics tags are real traffic on a public CDN
+ * origin, and turning them into 400s would break callers who are not using the
+ * image surface at all. They are carried through canonicalisation untouched.
+ */
+function parseImageParams(query) {
+    const reject = (error, param) => ({ ok: false, rejection: { error, param } });
+    // --- dpr first: it multiplies the dimensions, so the cap has to see it.
+    const dprRaw = single(query.dpr, "dpr");
+    if (!dprRaw.ok)
+        return { ok: false, rejection: dprRaw.rejection };
+    let dpr = 1;
+    if (dprRaw.value !== undefined) {
+        const n = strictNumber(dprRaw.value);
+        if (n === null || n < 1 || n > 3) {
+            return reject("`dpr` must be a number between 1 and 3", "dpr");
+        }
+        dpr = n;
+    }
+    const dimension = (name) => {
+        const raw = single(query[name], name);
+        if (!raw.ok)
+            return raw;
+        if (raw.value === undefined)
+            return { ok: true };
+        const n = strictInt(raw.value);
+        if (n === null || n < 1) {
+            return { ok: false, rejection: { error: `\`${name}\` must be a positive integer`, param: name } };
+        }
+        const effective = Math.round(n * dpr);
+        if (effective > exports.MAX_OUTPUT_EDGE) {
+            return {
+                ok: false,
+                rejection: {
+                    error: `\`${name}\` × \`dpr\` is ${effective}px; the maximum output edge is ${exports.MAX_OUTPUT_EDGE}px`,
+                    param: name,
+                },
+            };
+        }
+        return { ok: true, value: effective };
+    };
+    const w = dimension("width");
+    if (!w.ok)
+        return { ok: false, rejection: w.rejection };
+    const h = dimension("height");
+    if (!h.ok)
+        return { ok: false, rejection: h.rejection };
+    const blurRaw = single(query.blur, "blur");
+    if (!blurRaw.ok)
+        return { ok: false, rejection: blurRaw.rejection };
+    let blur;
+    if (blurRaw.value !== undefined) {
+        const n = strictInt(blurRaw.value);
+        // This used to be `Math.max(1, Math.min(256, parseInt(blur)))` — a silent
+        // clamp, so `blur=99999` and `blur=256` were one representation under two
+        // URLs, and `blur=abc` was a 500.
+        if (n === null || n < exports.MIN_BLUR || n > exports.MAX_BLUR) {
+            return reject(`\`blur\` must be an integer between ${exports.MIN_BLUR} and ${exports.MAX_BLUR}`, "blur");
+        }
+        blur = n;
+    }
+    const formatRaw = single(query.format, "format");
+    if (!formatRaw.ok)
+        return { ok: false, rejection: formatRaw.rejection };
+    let format;
+    if (formatRaw.value !== undefined) {
+        const v = formatRaw.value.trim().toLowerCase();
+        const canon = v === "jpg" ? "jpeg" : v;
+        if (canon !== "webp" && canon !== "avif" && canon !== "jpeg" && canon !== "png" && canon !== "auto") {
+            return reject("`format` must be one of webp, avif, jpeg, png, auto", "format");
+        }
+        format = canon;
+    }
+    const qualityRaw = single(query.quality, "quality");
+    if (!qualityRaw.ok)
+        return { ok: false, rejection: qualityRaw.rejection };
+    let quality;
+    if (qualityRaw.value !== undefined) {
+        const n = strictInt(qualityRaw.value);
+        if (n === null || n < 1 || n > 100) {
+            return reject("`quality` must be an integer between 1 and 100", "quality");
+        }
+        quality = n;
+    }
+    const fitRaw = single(query.fit, "fit");
+    if (!fitRaw.ok)
+        return { ok: false, rejection: fitRaw.rejection };
+    let fit = "inside";
+    if (fitRaw.value !== undefined) {
+        const v = fitRaw.value.trim().toLowerCase();
+        if (v !== "inside" && v !== "cover" && v !== "contain") {
+            return reject("`fit` must be one of inside, cover, contain", "fit");
+        }
+        fit = v;
+    }
+    const flag = (name) => {
+        const raw = single(query[name], name);
+        if (!raw.ok)
+            return raw;
+        if (raw.value === undefined)
+            return { ok: true, value: false };
+        const v = raw.value.trim().toLowerCase();
+        if (BOOL_TRUE.has(v))
+            return { ok: true, value: true };
+        if (BOOL_FALSE.has(v))
+            return { ok: true, value: false };
+        return { ok: false, rejection: { error: `\`${name}\` must be 0 or 1`, param: name } };
+    };
+    const upscale = flag("upscale");
+    if (!upscale.ok)
+        return { ok: false, rejection: upscale.rejection };
+    const keepMetadata = flag("keepMetadata");
+    if (!keepMetadata.ok)
+        return { ok: false, rejection: keepMetadata.rejection };
+    /**
+     * What counts as "the caller asked for a transform".
+     *
+     * `fit`, `dpr` and `upscale` only modify a resize, so on their own they
+     * change nothing — a URL carrying just `?fit=cover` must stay the pass-through
+     * it is today. `keepMetadata` likewise: there is nothing to strip if we are
+     * not re-encoding.
+     */
+    const wantsTransform = w.value !== undefined ||
+        h.value !== undefined ||
+        blur !== undefined ||
+        format !== undefined ||
+        quality !== undefined;
+    return {
+        ok: true,
+        params: {
+            width: w.value,
+            height: h.value,
+            blur,
+            format,
+            quality,
+            fit,
+            dpr,
+            upscale: upscale.value,
+            keepMetadata: keepMetadata.value,
+            wantsTransform,
+        },
+    };
+}
+/** Render a number the way the canonical URL spells it (no trailing zeros). */
+function num(n) {
+    return String(Number(n));
+}
+/**
+ * One key or value of the canonical query, percent-encoded so that a browser
+ * sends it back byte for byte.
+ *
+ * `encodeURIComponent` leaves `'` as it is, but a browser's URL parser
+ * percent-encodes `'` in the query of an http(s) URL. A redirect whose Location
+ * carried a raw `'` was therefore requested as `%27`, which is not the spelling
+ * this module wrote, so it was redirected again, forever. Every other
+ * character `encodeURIComponent` leaves alone (`!` `(` `)` `*` `~` and the
+ * unreserved set) a browser leaves alone too.
+ */
+function encodePart(text) {
+    return encodeURIComponent(text).replace(/'/g, "%27");
+}
+/**
+ * The canonical spelling of a query, so `?width=200&format=webp` and
+ * `?format=webp&width=200` are one edge object rather than two.
+ *
+ * GATED, DELIBERATELY. Canonicalisation only applies once the caller uses a
+ * parameter introduced by §0i.1. A URL made only of `width`/`height`/`blur` is
+ * declared canonical as received, whatever its key order — see LEGACY_PARAMS
+ * for why. The gate is also what keeps the `files-404-params-ignored` parity
+ * fixture (`?width=100&height=50&blur=9`) from becoming a 301.
+ *
+ * @param rawQuery the query string as received, without the leading `?`
+ */
+function canonicalise(rawQuery, params) {
+    const received = new URLSearchParams(rawQuery);
+    const usesNewParam = [...received.keys()].some((k) => exports.NEW_PARAMS.has(k));
+    if (!usesNewParam)
+        return { query: rawQuery, isCanonical: true };
+    const query = canonicalQuery(rawQuery, params);
+    return { query, isCanonical: query === rawQuery };
+}
+/**
+ * The canonical spelling itself, without `canonicalise`'s gate.
+ *
+ * `canonicalise` is this plus the LEGACY_PARAMS grandfather clause. For a query
+ * that uses a new parameter the two agree; for one made only of
+ * `width`/`height`/`blur` this still sorts and re-spells it, which the API
+ * accepts as canonical too, since the gate declares any legacy spelling
+ * canonical. So a URL built with this is never redirected, whichever
+ * parameters it carries. @capacms/sdk builds every image URL with it.
+ *
+ * @param rawQuery the query string, without the leading `?`; read only for the
+ *   keys this module does not know, which are kept
+ */
+function canonicalQuery(rawQuery, params) {
+    const received = new URLSearchParams(rawQuery);
+    const keys = [...new Set([...received.keys()])];
+    const out = new Map();
+    // Known parameters are re-rendered from the PARSED value, so `width=0200`,
+    // `format=JPG` and `upscale=true` all collapse onto one spelling. Defaults are
+    // dropped: a URL that asks for the default is the same representation as one
+    // that does not mention it. `quality` only where that is true for every
+    // output the URL can produce (droppableQuality).
+    //
+    // `width`/`height` are re-rendered PRE-dpr, because dpr stays in the URL as
+    // its own term; folding it into the dimension would make `?width=200&dpr=2`
+    // redirect to `?width=400`, which is a different request as far as the caller
+    // who wrote it is concerned.
+    if (params.width !== undefined)
+        out.set("width", num(Math.round(params.width / params.dpr)));
+    if (params.height !== undefined)
+        out.set("height", num(Math.round(params.height / params.dpr)));
+    if (params.blur !== undefined)
+        out.set("blur", num(params.blur));
+    if (params.format !== undefined)
+        out.set("format", params.format);
+    if (params.quality !== undefined && params.quality !== droppableQuality(params.format))
+        out.set("quality", num(params.quality));
+    if (params.fit !== "inside")
+        out.set("fit", params.fit);
+    if (params.dpr !== 1)
+        out.set("dpr", num(params.dpr));
+    if (params.upscale)
+        out.set("upscale", "1");
+    if (params.keepMetadata)
+        out.set("keepMetadata", "1");
+    // Unknown keys are preserved verbatim (first value wins, repeats collapse),
+    // so a cache-buster survives the redirect instead of being silently dropped.
+    //
+    // An empty pair (`&=`, an empty key with an empty value) is dropped: written
+    // back it would be an empty segment, which parses to nothing, so the URL it
+    // redirected to was itself redirected again.
+    for (const key of keys) {
+        if (exports.LEGACY_PARAMS.has(key) || exports.NEW_PARAMS.has(key))
+            continue;
+        const value = received.get(key) ?? "";
+        if (key === "" && value === "")
+            continue;
+        out.set(key, value);
+    }
+    const sorted = [...out.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return sorted
+        .map(([k, v]) => (v === "" ? encodePart(k) : `${encodePart(k)}=${encodePart(v)}`))
+        .join("&");
+}
+/**
+ * A stable string identifying the transform, for the ETag.
+ *
+ * Built from the RESOLVED parameters rather than the URL, so two spellings of
+ * one representation share an ETag even when the redirect is not in play.
+ * `auto` resolves per request, so the caller passes the resolved format in.
+ */
+function buildSignature(params, resolvedFormat) {
+    if (!params.wantsTransform)
+        return "raw";
+    const parts = [];
+    if (params.width !== undefined)
+        parts.push(`w${params.width}`);
+    if (params.height !== undefined)
+        parts.push(`h${params.height}`);
+    if (params.width !== undefined || params.height !== undefined) {
+        parts.push(`f${params.fit}`);
+        if (params.upscale)
+            parts.push("up");
+    }
+    if (params.blur !== undefined)
+        parts.push(`b${params.blur}`);
+    if (resolvedFormat)
+        parts.push(`o${resolvedFormat}`);
+    if (params.quality !== undefined)
+        parts.push(`q${params.quality}`);
+    if (params.keepMetadata)
+        parts.push("meta");
+    return parts.join("_") || "raw";
+}
+/**
+ * Which concrete format `format=auto` resolves to for this request.
+ *
+ * Returns null when the client advertises neither modern format, in which case
+ * the source format is kept — `auto` never makes a response worse than the
+ * object already is.
+ *
+ * `q=0` is an explicit REFUSAL in RFC 9110 content negotiation, not a weak
+ * preference, so an entry carrying it is skipped rather than matched.
+ */
+function resolveAutoFormat(accept) {
+    if (!accept)
+        return null;
+    const offered = new Map();
+    for (const entry of accept.split(",")) {
+        const [type, ...paramParts] = entry.split(";");
+        const name = type.trim().toLowerCase();
+        if (!name)
+            continue;
+        let q = 1;
+        for (const p of paramParts) {
+            const m = /^\s*q\s*=\s*([\d.]+)\s*$/i.exec(p);
+            if (m)
+                q = Number(m[1]);
+        }
+        offered.set(name, Number.isFinite(q) ? q : 1);
+    }
+    if ((offered.get("image/avif") ?? 0) > 0)
+        return "avif";
+    if ((offered.get("image/webp") ?? 0) > 0)
+        return "webp";
+    return null;
+}

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export { WEBHOOKS_NEED_ACCESS_TOKEN } from "./webhooks";
 export type { CreateWebhookEndpointInput, ListWebhookDeliveriesOptions, ResumeWebhookEndpointOptions, ResumeWebhookEndpointResult, UpdateWebhookEndpointInput, WebhookDeliveriesPage, WebhookDeliveriesResource, WebhookDelivery, WebhookDeliveryDetail, WebhookDeliveryStatus, WebhookDisabledReason, WebhookEndpoint, WebhookEndpointDetail, WebhookEndpointsResource, WebhookEndpointWithSecret, WebhookEventCatalogueEntry, WebhookEventGroup, WebhookPagination, WebhooksResource, } from "./webhooks";
 export { DEFAULT_WEBHOOK_TOLERANCE_SECONDS, parseWebhookSignatureHeader, signWebhookPayload, verifyWebhookSignature, WEBHOOK_SIGNATURE_HEADER, } from "./webhook-signature";
 export type { ParsedWebhookSignature, VerifyWebhookSignatureInput, } from "./webhook-signature";
-export { generate, normalizeTypes, readStampedChecksum, typeNames } from "./codegen";
-export type { CodegenResult } from "./codegen";
+export { generate, normalizeTypes, readStampedChecksum, restTypesFromIntrospection, typeNames } from "./codegen";
+export type { CodegenResult, RestTypesResult } from "./codegen";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.typeNames = exports.readStampedChecksum = exports.normalizeTypes = exports.generate = exports.WEBHOOK_SIGNATURE_HEADER = exports.verifyWebhookSignature = exports.signWebhookPayload = exports.parseWebhookSignatureHeader = exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOKS_NEED_ACCESS_TOKEN = exports.CapaError = exports.instanceIdOf = exports.createClient = void 0;
+exports.typeNames = exports.restTypesFromIntrospection = exports.readStampedChecksum = exports.normalizeTypes = exports.generate = exports.WEBHOOK_SIGNATURE_HEADER = exports.verifyWebhookSignature = exports.signWebhookPayload = exports.parseWebhookSignatureHeader = exports.DEFAULT_WEBHOOK_TOLERANCE_SECONDS = exports.WEBHOOKS_NEED_ACCESS_TOKEN = exports.CapaError = exports.instanceIdOf = exports.createClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
 Object.defineProperty(exports, "instanceIdOf", { enumerable: true, get: function () { return client_1.instanceIdOf; } });
@@ -18,4 +18,5 @@ var codegen_1 = require("./codegen");
 Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return codegen_1.generate; } });
 Object.defineProperty(exports, "normalizeTypes", { enumerable: true, get: function () { return codegen_1.normalizeTypes; } });
 Object.defineProperty(exports, "readStampedChecksum", { enumerable: true, get: function () { return codegen_1.readStampedChecksum; } });
+Object.defineProperty(exports, "restTypesFromIntrospection", { enumerable: true, get: function () { return codegen_1.restTypesFromIntrospection; } });
 Object.defineProperty(exports, "typeNames", { enumerable: true, get: function () { return codegen_1.typeNames; } });

package/dist/next/attrs.d.ts

@@ -1,15 +1,31 @@
 /**
  * The attributes that make a rendered field clickable in Capa's live preview.
  *
- *   <h1 {...capaAttrs(entry, "title", isDraft)}>{entry.fields.title}</h1>
+ *   <h1 {...capaAttrs(entry, "title")}>{entry.fields.title}</h1>
+ *   <h1 {...capaAttrs(node, "title")}>{node.title}</h1>          // a GraphQL node
  *
- * `field` is the field's namespace, which is the key it has in `entry.fields`:
- * the API renders every field under its namespace, and the Capa editor tags
- * each field row with that same namespace, so one string names the field on
- * both sides of the preview frame.
+ * For a REST entry, `field` is the field's namespace, which is the key it has
+ * in `entry.fields`: the API renders every field under its namespace, and the
+ * Capa editor tags each field row with that same namespace, so one string
+ * names the field on both sides of the preview frame.
  *
- * Pass `enabled = false` outside draft mode and the element carries nothing, so
- * a published page never ships entry ids in its markup.
+ * For a GraphQL node (an object that selected `id` and `model`), `field` is
+ * the field as selected. A field GraphQL renamed (`hero_image` for
+ * `hero-image`, `status_field` for `status`) is tagged by its namespace: a
+ * client in edit mode reads the key's schema to know which those are.
+ *
+ * EDIT MODE DECIDES, NOT THE CALLER. An entry read by a client created with
+ * `editMode: true` carries a hidden edit mark (`markEditEntries`), and
+ * `capaAttrs` tags only marked entries. So a published page, read with a normal
+ * client, ships no entry ids in its markup without the site passing anything,
+ * and the same component in the Capa editor is clickable. The mark is a
+ * non-enumerable symbol: it does not show up in JSON, logs or a spread copy, and
+ * it does not survive being passed to a client component as a prop, which is
+ * the safe direction to fail in.
+ *
+ * Pass `enabled` to override: `true` tags an unmarked entry, `false` tags
+ * nothing. Sites written before edit mode passed `isDraft` here and keep
+ * working unchanged.
  */
 export type CapaAttrs = {
     "data-capa-entry": string;
@@ -18,7 +34,65 @@ export type CapaAttrs = {
     "data-capa-entry"?: undefined;
     "data-capa-field"?: undefined;
 };
-export declare function capaAttrs<T = Record<string, unknown>>(entry: {
+/** `Symbol.for`, so two copies of the SDK in one bundle agree on the mark. */
+export declare const CAPA_EDIT: unique symbol;
+/** Whether an entry was read in edit mode. */
+export declare function isEditEntry(entry: unknown): boolean;
+/**
+ * Mark every entry inside `value`, related entries included, so a click on an
+ * author inside an article opens the author. Walks arrays and plain objects,
+ * never the same object twice. Returns `value` for chaining.
+ */
+export declare function markEditEntries<T>(value: T): T;
+/**
+ * Mark every entry inside a GraphQL result's `data`: each object that
+ * selected `id` and `model`, related entries included. `renamed(model)` gives
+ * that model's fields whose GraphQL name is not their namespace, by GraphQL
+ * name, so `capaAttrs` tags those by namespace. Returns `data`.
+ */
+export declare function markGraphQLEntries<T>(data: T, renamed?: (model: string) => Readonly<Record<string, string>> | undefined): T;
+/** Whether a GraphQL result's `data` holds any entry `markGraphQLEntries` would mark. */
+export declare function hasGraphQLEntry(data: unknown): boolean;
+/** Keep `from`'s edit mark on `to`, for a copy of an entry in another shape (`toTree`). */
+export declare function carryEditMark<T extends object>(from: unknown, to: T): T;
+/** GraphQL's system fields, which name the entry rather than one of its fields. */
+type GraphQLSystemField = "id" | "model" | "status" | "createdAt" | "updatedAt" | "publishedAt" | "_version" | "_tags" | "_folder" | "__typename";
+/**
+ * The `field` `capaAttrs` takes for `E`: a key of `fields` for a REST entry;
+ * a field as selected for a GraphQL node, which selected `id` and `model`;
+ * any name for a bare `{ id }`. A GraphQL node without `model` takes none,
+ * and the compiler says why.
+ */
+export type TaggableField<E> = unknown extends FieldsOf<E> ? E extends {
+    model: string;
+} ? Exclude<Extract<keyof E, string>, GraphQLSystemField> : [Exclude<keyof E, "id">] extends [never] ? string : "select model on this node: capaAttrs tags an entry that selected id and model" : Extract<keyof NonNullable<FieldsOf<E>>, string>;
+/** A REST entry's `fields` type; `unknown` for anything without one (a GraphQL node, a bare `{ id }`). */
+type FieldsOf<E> = "fields" extends keyof E ? E["fields" & keyof E] : unknown;
+export declare function capaAttrs<E extends {
     id: string;
-    fields?: T;
-}, field: Extract<keyof T, string>, enabled?: boolean): CapaAttrs;
+}>(entry: E, field: TaggableField<E>, enabled?: boolean): CapaAttrs;
+/**
+ * The attributes for every field of `T`, one `CapaAttrs` per field name.
+ * `capa-codegen` writes `<Model>Attrs = FieldAttrs<Model>` beside each
+ * `<Model>Select`, so `const a: ArticleAttrs = fieldAttrs(entry)` fails to
+ * compile on a wrong field name (M5). `fieldAttrs` of a REST entry typed with
+ * `Model` returns exactly this type.
+ */
+export type FieldAttrs<T> = {
+    readonly [K in Extract<keyof T, string>]: CapaAttrs;
+};
+/**
+ * Typed attributes for every field of one entry (M5), or of one GraphQL node:
+ *
+ *   const a = fieldAttrs(article);
+ *   <h1 {...a.title}>…</h1>        // a.titel is a compile error
+ *
+ * Same rule as `capaAttrs`: empty unless the entry was read in edit mode, or
+ * `enabled` says otherwise.
+ */
+export declare function fieldAttrs<E extends {
+    id: string;
+}>(entry: E, enabled?: boolean): {
+    readonly [K in TaggableField<E>]: CapaAttrs;
+};
+export {};