@capacms/sdk 1.0.0-next.0

package/dist/next/client.js

@@ -0,0 +1,408 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapaError = void 0;
+exports.isCapaError = isCapaError;
+exports.resolveNextConfig = resolveNextConfig;
+exports.serializeSelect = serializeSelect;
+exports.createClient = createClient;
+/**
+ * What a `Capa-Schema` value may look like: hex, 8 to 64 characters.
+ *
+ * COPIED, DELIBERATELY, from `SCHEMA_CHECKSUM` in
+ * `apps/api/src/api-next/page-header.ts`, for the same reason `PAGE_ID` below
+ * is copied: this package ships with no runtime dependencies at all. If you
+ * change one, change the other. The API silently ignores a stamp it cannot
+ * parse, so a drift would show up as a `drift` insight that quietly never
+ * appears rather than as an error.
+ */
+const SCHEMA_CHECKSUM = /^[a-f0-9]{8,64}$/;
+class CapaError extends Error {
+    status;
+    type;
+    code;
+    param;
+    hint;
+    requestId;
+    docs;
+    constructor(input) {
+        super(input.message);
+        this.name = "CapaError";
+        this.status = input.status;
+        this.type = input.type;
+        this.code = input.code;
+        this.param = input.param;
+        this.hint = input.hint;
+        this.requestId = input.requestId;
+        this.docs = input.docs;
+    }
+}
+exports.CapaError = CapaError;
+function isCapaError(error) {
+    return error instanceof CapaError;
+}
+function resolveNextConfig(config) {
+    const value = (config ?? {});
+    const missing = ["baseUrl", "apiKey", "version"].filter((key) => !value[key]);
+    if (missing.length) {
+        throw new Error(`@capacms/sdk/next: missing ${missing.join(", ")}. ` +
+            "createClient needs baseUrl, apiKey and version.");
+    }
+    if (!value.apiKey.startsWith("cap_")) {
+        throw new Error("@capacms/sdk/next: apiKey must start with cap_. Use the legacy @capacms/sdk client for pk_ and sk_ keys.");
+    }
+    if (value.contract !== undefined && value.contract !== 1) {
+        throw new Error("@capacms/sdk/next: contract must be 1 when provided.");
+    }
+    const fetchImpl = value.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        throw new Error("@capacms/sdk/next: no fetch available. Pass one via config.fetch.");
+    }
+    // Checked here as well as per call, so a bad page on the config throws where
+    // the client is built rather than on whichever read happens to run first.
+    resolvePage(value.page, undefined);
+    // THROWS rather than dropping, the same rule `page` follows and for the same
+    // reason: the API must never 400 a running site over a telemetry header, so
+    // it ignores what it cannot store, and the SDK is the place a wrong value
+    // should surface while somebody is still writing the code. A checksum that
+    // is silently dropped is a `drift` insight that never appears, which looks
+    // exactly like a site that is up to date.
+    if (value.schemaChecksum !== undefined && value.schemaChecksum !== null) {
+        if (typeof value.schemaChecksum !== "string" || !SCHEMA_CHECKSUM.test(value.schemaChecksum)) {
+            throw new TypeError(`@capacms/sdk/next: schemaChecksum must be the hex checksum from your generated types, for example CAPA_SCHEMA_CHECKSUM. Got ${JSON.stringify(value.schemaChecksum)}.`);
+        }
+    }
+    return { ...value, baseUrl: value.baseUrl.replace(/\/+$/, ""), fetchImpl };
+}
+/**
+ * What a `Capa-Page` value may look like.
+ *
+ * COPIED, DELIBERATELY, from `PAGE_ID_PATTERN` in
+ * `packages/shared/src/pages/route-pattern.ts`, which is the one definition the
+ * API and the admin both read. It is copied rather than imported because this
+ * package ships with no runtime dependencies at all, and `@capa/shared` is a
+ * devDependency here. If you change one, change the other: the API silently
+ * drops a header it cannot store, so a drift would show up as telemetry that
+ * quietly stops arriving rather than as an error.
+ */
+const PAGE_ID = /^\/[A-Za-z0-9._\-[\]/]{0,199}$/;
+/**
+ * The page for one call: the call's own value, else the client's, else none.
+ *
+ * THROWS on a malformed value, and that is the difference between this and the
+ * API. A running site must never 400 because a page identity was mangled, so
+ * the API ignores what it cannot store. The SDK is the place a typo should
+ * surface, while you are writing the code and can still fix it.
+ */
+function resolvePage(configPage, callPage) {
+    const value = callPage !== undefined ? callPage : configPage;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string" || !PAGE_ID.test(value)) {
+        throw new TypeError(`@capacms/sdk/next: page must be a path such as "/blog/[slug]" or "/blog/hello". Got ${JSON.stringify(value)}.`);
+    }
+    return value;
+}
+const NAME = /^[A-Za-z0-9_-]+$/;
+function selectName(value, context) {
+    if (typeof value !== "string" || !NAME.test(value)) {
+        throw new TypeError(`@capacms/sdk/next: ${context} must be a field name.`);
+    }
+    return value;
+}
+function serializeSelectItems(items) {
+    if (items.length === 0)
+        throw new TypeError("@capacms/sdk/next: select cannot be empty.");
+    return items
+        .map((item) => {
+        if (typeof item === "string") {
+            return item === "*" ? item : selectName(item, "select item");
+        }
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new TypeError("@capacms/sdk/next: each select item must be a field name or relation object.");
+        }
+        const entries = Object.entries(item);
+        if (entries.length !== 1) {
+            throw new TypeError("@capacms/sdk/next: a relation select object must name exactly one field.");
+        }
+        const [rawName, value] = entries[0];
+        const name = selectName(rawName, "relation select key");
+        if (value === "*")
+            return `${name}(*)`;
+        if (Array.isArray(value))
+            return `${name}(${serializeSelectItems(value)})`;
+        if (!value || typeof value !== "object") {
+            throw new TypeError(`@capacms/sdk/next: ${name} must select fields, "*", or select options.`);
+        }
+        const options = value;
+        const allowed = new Set(["select", "limit", "sort", "after"]);
+        for (const key of Object.keys(options)) {
+            if (!allowed.has(key)) {
+                throw new TypeError(`@capacms/sdk/next: ${key} is not a relation select option.`);
+            }
+        }
+        const inner = options.select === "*"
+            ? "*"
+            : Array.isArray(options.select)
+                ? serializeSelectItems(options.select)
+                : (() => {
+                    throw new TypeError(`@capacms/sdk/next: ${name}.select must be an array or "*".`);
+                })();
+        const args = [inner];
+        if (options.limit !== undefined) {
+            if (!Number.isInteger(options.limit) || Number(options.limit) < 1 || Number(options.limit) > 200) {
+                throw new TypeError(`@capacms/sdk/next: ${name}.limit must be an integer from 1 to 200.`);
+            }
+            args.push(`limit:${options.limit}`);
+        }
+        if (options.sort !== undefined) {
+            if (typeof options.sort !== "string" || !/^-?[A-Za-z0-9_-]+$/.test(options.sort)) {
+                throw new TypeError(`@capacms/sdk/next: ${name}.sort must be one field name.`);
+            }
+            args.push(`sort:${options.sort}`);
+        }
+        if (options.after !== undefined) {
+            if (typeof options.after !== "string" || options.after === "") {
+                throw new TypeError(`@capacms/sdk/next: ${name}.after must be a non-empty cursor.`);
+            }
+            args.push(`after:${options.after}`);
+        }
+        return `${name}(${args.join(",")})`;
+    })
+        .join(",");
+}
+/** Serialize the SDK object form into the canonical `/api/entries` grammar. */
+function serializeSelect(select) {
+    if (typeof select === "string")
+        return select;
+    if (!Array.isArray(select)) {
+        throw new TypeError("@capacms/sdk/next: select must be a grammar string or an array.");
+    }
+    return serializeSelectItems(select);
+}
+const FILTER_OPERATORS = new Set([
+    "eq",
+    "ne",
+    "in",
+    "nin",
+    "lt",
+    "lte",
+    "gt",
+    "gte",
+    "contains",
+    "startsWith",
+    "endsWith",
+    "has",
+    "hasAny",
+    "hasAll",
+    "exists",
+    "null",
+]);
+const ARRAY_OPERATORS = new Set(["in", "nin", "hasAny", "hasAll"]);
+function filterValue(operator, value) {
+    if (Array.isArray(value)) {
+        if (!ARRAY_OPERATORS.has(operator)) {
+            throw new TypeError(`@capacms/sdk/next: filter operator ${operator} does not accept an array.`);
+        }
+        return value.map(String).join(",");
+    }
+    return String(value);
+}
+function listQuery(options) {
+    const query = new URLSearchParams();
+    if (options.select !== undefined)
+        query.set("select", serializeSelect(options.select));
+    if (options.filter !== undefined) {
+        for (const [path, operations] of Object.entries(options.filter)) {
+            for (const [rawOperator, value] of Object.entries(operations)) {
+                if (!FILTER_OPERATORS.has(rawOperator)) {
+                    throw new TypeError(`@capacms/sdk/next: unknown filter operator ${rawOperator}.`);
+                }
+                if (value === undefined)
+                    continue;
+                const operator = rawOperator;
+                query.set(`filter[${path}][${operator}]`, filterValue(operator, value));
+            }
+        }
+    }
+    if (options.where !== undefined)
+        query.set("where", JSON.stringify(options.where));
+    if (options.sort !== undefined)
+        query.set("sort", options.sort.join(","));
+    if (options.limit !== undefined)
+        query.set("limit", String(options.limit));
+    if (options.count !== undefined)
+        query.set("count", String(options.count));
+    if (options.after !== undefined)
+        query.set("after", options.after);
+    if (options.before !== undefined)
+        query.set("before", options.before);
+    return query;
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function unparseable(status, requestId) {
+    return new CapaError({
+        status,
+        type: "api_error",
+        code: "unparseable_response",
+        message: "Capa returned a response that was not a valid /api/ JSON envelope.",
+        requestId,
+        docs: "",
+    });
+}
+function errorFromEnvelope(status, body, fallbackRequestId) {
+    const detail = body.error;
+    if (!detail ||
+        typeof detail.type !== "string" ||
+        typeof detail.code !== "string" ||
+        typeof detail.message !== "string" ||
+        typeof detail.docs !== "string") {
+        return unparseable(status, fallbackRequestId);
+    }
+    return new CapaError({
+        status,
+        type: detail.type,
+        code: detail.code,
+        message: detail.message,
+        param: optionalString(detail.param),
+        hint: optionalString(detail.hint),
+        requestId: optionalString(body.meta?.requestId) ?? fallbackRequestId,
+        docs: detail.docs,
+    });
+}
+function cacheTags(response) {
+    const value = response.headers?.get?.("Surrogate-Key") ?? "";
+    return value.split(/\s+/).filter(Boolean);
+}
+function createRequester(config) {
+    return async function request(path, query = new URLSearchParams(), signal, page) {
+        const url = new URL(config.baseUrl + path);
+        query.forEach((value, key) => url.searchParams.append(key, value));
+        const headers = {
+            Accept: "application/json",
+            "x-api-key": config.apiKey,
+            "Capa-Version": config.version,
+        };
+        if (config.contract !== undefined)
+            headers["Capa-Contract"] = String(config.contract);
+        // Absent unless a page was named, so a client that never sets one sends
+        // byte-identical requests to the ones it sent before this option existed.
+        if (page !== undefined)
+            headers["Capa-Page"] = page;
+        // Same rule, and on EVERY call rather than only the entries reads: the
+        // stamp describes the build, so a page whose only Capa call is `me()`
+        // still reports which schema it was generated from.
+        if (config.schemaChecksum !== undefined)
+            headers["Capa-Schema"] = config.schemaChecksum;
+        const response = await config.fetchImpl(url.toString(), { method: "GET", headers, signal });
+        const requestId = response.headers?.get?.("X-Request-Id") ?? "";
+        const text = await response.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw unparseable(response.status, requestId);
+        }
+        if (!response.ok)
+            throw errorFromEnvelope(response.status, body, requestId);
+        if (!body || typeof body !== "object")
+            throw unparseable(response.status, requestId);
+        return { body: body, cacheTags: cacheTags(response) };
+    };
+}
+function createClient(config) {
+    const resolved = resolveNextConfig(config);
+    const request = createRequester(resolved);
+    const entries = {
+        async list(namespace, options = {}) {
+            const result = await request(`/api/entries/${encodeURIComponent(namespace)}`, listQuery(options), options.signal, resolvePage(resolved.page, options.page));
+            return { ...result.body, cacheTags: result.cacheTags };
+        },
+        async get(namespace, id, options = {}) {
+            const query = new URLSearchParams();
+            if (options.select !== undefined)
+                query.set("select", serializeSelect(options.select));
+            try {
+                const result = await request(`/api/entries/${encodeURIComponent(namespace)}/${encodeURIComponent(id)}`, query, options.signal, resolvePage(resolved.page, options.page));
+                return { ...result.body, cacheTags: result.cacheTags };
+            }
+            catch (error) {
+                if (error instanceof CapaError &&
+                    error.status === 404 &&
+                    error.type === "not_found" &&
+                    error.code === "entry_not_found") {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async *iterate(namespace, options = {}) {
+            let after = options.after;
+            for (;;) {
+                const page = await entries.list(namespace, { ...options, after });
+                for (const entry of page.data)
+                    yield entry;
+                if (!page.page.hasNext || !page.page.next)
+                    return;
+                after = page.page.next;
+            }
+        },
+    };
+    const pages = {
+        async list(options = {}) {
+            const query = new URLSearchParams();
+            if (options.entry !== undefined)
+                query.set("entry", options.entry);
+            return (await request("/api/pages", query, options.signal)).body;
+        },
+        async get(page, options = {}) {
+            try {
+                return (await request(
+                // A page identity contains slashes, so it is encoded whole into one
+                // path segment. The API decodes it back before looking it up.
+                `/api/pages/${encodeURIComponent(page)}`, new URLSearchParams(), options.signal)).body;
+            }
+            catch (error) {
+                // Same shape as `entries.get`: a page nobody has declared or read is a
+                // null, not a throw, because "is this page known to Capa" is a question
+                // a caller asks on purpose.
+                if (error instanceof CapaError &&
+                    error.status === 404 &&
+                    error.code === "page_not_found") {
+                    return null;
+                }
+                throw error;
+            }
+        },
+    };
+    return {
+        entries,
+        pages,
+        async preview(token, options = {}) {
+            const query = new URLSearchParams();
+            query.set("token", token);
+            try {
+                return (await request("/api/preview", query, options.signal)).body.data;
+            }
+            catch (error) {
+                // Invalid and expired both mean "do not enable draft mode", and a
+                // preview route has the same fallback for either: render the published
+                // page. Anything else (a 500, a network failure, a missing scope) is a
+                // real problem and must not be mistaken for a stale link.
+                if (error instanceof CapaError &&
+                    (error.code === "preview_token_invalid" || error.code === "preview_token_expired")) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async me(options = {}) {
+            return (await request("/api/me", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page))).body;
+        },
+        async versions(options = {}) {
+            return (await request("/api/versions", new URLSearchParams(), options.signal, resolvePage(resolved.page, options.page))).body;
+        },
+    };
+}

package/dist/next/index.d.ts

@@ -0,0 +1,3 @@
+export { CapaError, createClient, isCapaError, resolveNextConfig, serializeSelect, } from "./client";
+export type { CallOptions, CapaNextClient, CapaNextConfig, EntriesResource, Entry, Filter, FilterOperator, FilterScalar, FilterValue, GetOptions, ListOptions, Page, PageDetail, PageInfo, PageSummary, PagesListOptions, PagesResource, PreviewClaim, ResponseMeta, Single, } from "./client";
+export type { CapaRelation, CapaRelationList, RelationSelectOptions, Select, SelectItem, SelectSort, } from "./select-types";

package/dist/next/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeSelect = exports.resolveNextConfig = exports.isCapaError = exports.createClient = exports.CapaError = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "CapaError", { enumerable: true, get: function () { return client_1.CapaError; } });
+Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
+Object.defineProperty(exports, "isCapaError", { enumerable: true, get: function () { return client_1.isCapaError; } });
+Object.defineProperty(exports, "resolveNextConfig", { enumerable: true, get: function () { return client_1.resolveNextConfig; } });
+Object.defineProperty(exports, "serializeSelect", { enumerable: true, get: function () { return client_1.serializeSelect; } });

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

@@ -0,0 +1,39 @@
+/** A single relation field emitted by `capa-codegen`. */
+export type CapaRelation<T> = T & {
+    readonly __capaRelation: "one";
+    readonly __capaRelationTarget: T;
+};
+/** An array relation field emitted by `capa-codegen`. */
+export type CapaRelationList<T> = T[] & {
+    readonly __capaRelation: "many";
+    readonly __capaRelationTarget: T;
+};
+type StringKey<T> = Extract<keyof T, string>;
+type RelationValue = {
+    readonly __capaRelation: "one" | "many";
+    readonly __capaRelationTarget: unknown;
+};
+type RelationKeys<T> = {
+    [K in StringKey<T>]-?: 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>}`;
+export interface RelationSelectOptions<T> {
+    select: Select<T> | "*";
+    limit?: number;
+    sort?: SelectSort<T>;
+    /** An opaque relation cursor returned by the API. */
+    after?: string;
+}
+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>];
+/** A typed form of the `/api/entries` `select` grammar. */
+export type Select<T> = ReadonlyArray<SelectItem<T>>;
+export {};

package/dist/next/select-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/nextjs/index.d.ts

@@ -0,0 +1,53 @@
+import { type CapaNextClient, type CapaNextConfig, type PagesResource, type PreviewClaim } from "../next";
+export interface CacheOptions {
+    tags?: string[];
+    revalidate?: number | false;
+}
+/** Add Next.js fetch-cache options without importing `next/*`. */
+export declare function withCache(fetchImpl: typeof fetch, options: CacheOptions): typeof fetch;
+export declare function tagsFor(input: {
+    model?: string;
+    entry?: string;
+    key?: string;
+    tenant?: string;
+}): string[];
+export interface WebhookPayload {
+    data?: {
+        instanceId?: unknown;
+        modelId?: unknown;
+        [key: string]: unknown;
+    };
+    instanceId?: unknown;
+    entryId?: unknown;
+    modelId?: unknown;
+    [key: string]: unknown;
+}
+/** Revalidate the concrete entry and model identities carried by a webhook. */
+export declare function revalidateFromWebhook(input: {
+    payload: WebhookPayload;
+    revalidateTag: (tag: string) => void | Promise<void>;
+}): Promise<string[]>;
+/** Select a client using server-only draft state supplied by the caller. */
+export declare function draftClient(input: {
+    production: CapaNextConfig;
+    draft: CapaNextConfig;
+    isDraft: () => boolean | Promise<boolean>;
+}): Promise<CapaNextClient>;
+export declare function routeOf(file: string): string;
+/**
+ * Verify a preview token from a Next route handler.
+ *
+ * A thin pass-through to `client.preview`, here so that a preview route reads
+ * as one import from `@capacms/sdk/nextjs` alongside the rest of the Next
+ * helpers. Null means "do not enable draft mode".
+ */
+export declare function preview(token: string, client: CapaNextClient): Promise<PreviewClaim | null>;
+/**
+ * The page list, as a standalone value.
+ *
+ * `pagesFor(client)` is `client.pages` and exists for symmetry with the other
+ * helpers in this module: a build script that only wants the page list can take
+ * this and never hold the whole client.
+ */
+export declare function pagesFor(client: CapaNextClient): PagesResource;
+export type { PreviewClaim };