@capacms/sdk 1.0.0-next.0

package/dist/http.d.ts

@@ -0,0 +1,67 @@
+import type { ResolvedConfig } from "./config";
+export declare class CapaError extends Error {
+    readonly status: number;
+    readonly path: string;
+    constructor(status: number, path: string, body: string);
+}
+export type Query = Record<string, string | number | boolean | undefined | null>;
+/**
+ * Which credential a call carries.
+ *
+ * `key` is the tenant API key, which is what every read in this SDK uses.
+ * `session` is a logged-in person's access token, and it exists because the
+ * webhook routes have no API key mount at all (publishing spec D8): managing an
+ * endpoint is a session-only act, so an API key cannot reach those routes and
+ * `webhooks.*` says so rather than spending a request on a guaranteed 401.
+ */
+export type Auth = "key" | "session";
+/**
+ * The bearer variant.
+ *
+ * `X-Tenant-Key` still goes along for symmetry with the key variant and for
+ * proxies and logs that key on it, but NOTHING on the API reads it on a session
+ * call: `validateTenant` only checks that the request already has a tenant, and
+ * that tenant is the logged-in user's `currentTenant` off the JWT. So `tenantId`
+ * does not select the tenant for `webhooks.*`; the session does.
+ */
+export declare function sessionHeaders(config: ResolvedConfig, extra?: Record<string, string>): {
+    Authorization: string;
+    "X-Tenant-Key": string;
+};
+/**
+ * A plain `fetch` with no caching of our own, deliberately.
+ *
+ * Every framework caches differently and owning it here means reimplementing
+ * all of them badly. Returning plain data from a plain fetch lets Next's fetch
+ * cache, React Router loaders and everything else work natively. What the host
+ * CANNOT know is which surrogate keys a response belongs to for CDN purging —
+ * Capa emits those, so `listContent`/`getContent` surface them and the host
+ * decides what to do with them.
+ */
+export declare function getJson<T>(config: ResolvedConfig, path: string, query?: Query, auth?: Auth): Promise<{
+    body: T;
+    cacheTags: string[];
+}>;
+/** A conditional GET. Returns `null` when the server answers 304. */
+export declare function getJsonConditional<T>(config: ResolvedConfig, path: string, etag: string | null, query?: Query): Promise<{
+    body: T;
+    etag: string | null;
+} | null>;
+/** GET an endpoint that answers with text rather than JSON (e.g. /v2/schema/types). */
+export declare function getText(config: ResolvedConfig, path: string, query?: Query): Promise<string>;
+/**
+ * A write verb — POST, PUT, PATCH or DELETE.
+ *
+ * The SDK was read-only because the surface was: `verifyApiKey` guarded five
+ * route files carrying 15 GETs and no write verb at all. The agent surface
+ * (#383) and ADMIN_UI_OVERHAUL 0h.4b changed that, and
+ * `tenant_api_keys.permission` is now enforced (#4646), so a `read` key gets a
+ * 403 here and a `write` key does not. `CapaError` carries the API's own body,
+ * so a caller can tell the two apart without parsing a message this file made
+ * up.
+ *
+ * Content writes are still NOT offered. `/v2/agent/model-instances` exists, but
+ * an SDK that can silently publish a draft needs a deliberate surface of its
+ * own rather than a second use of this function.
+ */
+export declare function writeJson<T>(config: ResolvedConfig, method: "POST" | "PUT" | "PATCH" | "DELETE", path: string, body: unknown, auth?: Auth): Promise<T>;

package/dist/http.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapaError = void 0;
+exports.sessionHeaders = sessionHeaders;
+exports.getJson = getJson;
+exports.getJsonConditional = getJsonConditional;
+exports.getText = getText;
+exports.writeJson = writeJson;
+class CapaError extends Error {
+    status;
+    path;
+    constructor(status, path, body) {
+        super(`Capa API ${status} on ${path}${body ? ` — ${body.slice(0, 200)}` : ""}`);
+        this.name = "CapaError";
+        this.status = status;
+        this.path = path;
+    }
+}
+exports.CapaError = CapaError;
+function buildUrl(config, path, query) {
+    const url = new URL(config.baseUrl + path);
+    for (const [k, v] of Object.entries(query)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        url.searchParams.set(k, String(v));
+    }
+    return url.toString();
+}
+function headers(config, extra = {}, auth = "key") {
+    return auth === "session"
+        ? sessionHeaders(config, extra)
+        : { "x-api-key": config.apiKey, "X-Tenant-Key": config.tenantId, ...extra };
+}
+/**
+ * The bearer variant.
+ *
+ * `X-Tenant-Key` still goes along for symmetry with the key variant and for
+ * proxies and logs that key on it, but NOTHING on the API reads it on a session
+ * call: `validateTenant` only checks that the request already has a tenant, and
+ * that tenant is the logged-in user's `currentTenant` off the JWT. So `tenantId`
+ * does not select the tenant for `webhooks.*`; the session does.
+ */
+function sessionHeaders(config, extra = {}) {
+    return {
+        Authorization: `Bearer ${config.accessToken ?? ""}`,
+        "X-Tenant-Key": config.tenantId,
+        ...extra,
+    };
+}
+/**
+ * A plain `fetch` with no caching of our own, deliberately.
+ *
+ * Every framework caches differently and owning it here means reimplementing
+ * all of them badly. Returning plain data from a plain fetch lets Next's fetch
+ * cache, React Router loaders and everything else work natively. What the host
+ * CANNOT know is which surrogate keys a response belongs to for CDN purging —
+ * Capa emits those, so `listContent`/`getContent` surface them and the host
+ * decides what to do with them.
+ */
+async function getJson(config, path, query = {}, auth = "key") {
+    const res = await config.fetchImpl(buildUrl(config, path, query), {
+        method: "GET",
+        headers: headers(config, { Accept: "application/json" }, auth),
+    });
+    const text = await res.text();
+    if (!res.ok)
+        throw new CapaError(res.status, path, text);
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new CapaError(res.status, path, `response was not JSON: ${text.slice(0, 200)}`);
+    }
+    const tags = res.headers?.get?.("surrogate-key") ?? "";
+    return { body, cacheTags: tags ? tags.split(/\s+/).filter(Boolean) : [] };
+}
+/** A conditional GET. Returns `null` when the server answers 304. */
+async function getJsonConditional(config, path, etag, query = {}) {
+    const extra = { Accept: "application/json" };
+    if (etag)
+        extra["If-None-Match"] = etag;
+    const res = await config.fetchImpl(buildUrl(config, path, query), {
+        method: "GET",
+        headers: headers(config, extra),
+    });
+    if (res.status === 304)
+        return null;
+    const text = await res.text();
+    if (!res.ok)
+        throw new CapaError(res.status, path, text);
+    return { body: JSON.parse(text), etag: res.headers?.get?.("etag") ?? null };
+}
+/** GET an endpoint that answers with text rather than JSON (e.g. /v2/schema/types). */
+async function getText(config, path, query = {}) {
+    const res = await config.fetchImpl(buildUrl(config, path, query), {
+        method: "GET",
+        headers: headers(config, { Accept: "text/plain, */*" }),
+    });
+    const text = await res.text();
+    if (!res.ok)
+        throw new CapaError(res.status, path, text);
+    return text;
+}
+/**
+ * A write verb — POST, PUT, PATCH or DELETE.
+ *
+ * The SDK was read-only because the surface was: `verifyApiKey` guarded five
+ * route files carrying 15 GETs and no write verb at all. The agent surface
+ * (#383) and ADMIN_UI_OVERHAUL 0h.4b changed that, and
+ * `tenant_api_keys.permission` is now enforced (#4646), so a `read` key gets a
+ * 403 here and a `write` key does not. `CapaError` carries the API's own body,
+ * so a caller can tell the two apart without parsing a message this file made
+ * up.
+ *
+ * Content writes are still NOT offered. `/v2/agent/model-instances` exists, but
+ * an SDK that can silently publish a draft needs a deliberate surface of its
+ * own rather than a second use of this function.
+ */
+async function writeJson(config, method, path, body, auth = "key") {
+    // A DELETE with no body sends no body and no Content-Type. Fastify routes
+    // without a body schema answer 400 to an empty JSON object on DELETE, and
+    // `webhooks.endpoints.delete` has nothing to say anyway.
+    const sendsBody = !(method === "DELETE" && body === undefined);
+    const extra = { Accept: "application/json" };
+    if (sendsBody)
+        extra["Content-Type"] = "application/json";
+    const res = await config.fetchImpl(buildUrl(config, path, {}), {
+        method,
+        headers: headers(config, extra, auth),
+        body: sendsBody ? JSON.stringify(body ?? {}) : undefined,
+    });
+    const text = await res.text();
+    if (!res.ok)
+        throw new CapaError(res.status, path, text);
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CapaError(res.status, path, `response was not JSON: ${text.slice(0, 200)}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { createClient, instanceIdOf } from "./client";
+export type { CapaClient, CreateScheduledActionsInput, CreateScheduledActionsResult, LayoutCard, LayoutDisplay, LayoutField, LayoutInline, LayoutWidth, ListOptions, ListScheduledActionsOptions, ModelLayout, ModelLayoutInfo, ModelsResource, Page, ResolvedScheduleTime, ScheduledAction, ScheduledActionsPage, ScheduledActionsResource, ScheduledActionStatus, ScheduledActionTarget, SearchHit, WorkspaceApplyResult, WorkspaceChanges, WorkspaceDocNode, WorkspaceDocument, WorkspaceSummary, WorkspaceTemplate, WorkspaceTreeDocument, WorkspacesResource, } from "./client";
+export type { CapaConfig } from "./config";
+export { CapaError } from "./http";
+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";

package/dist/index.js

@@ -0,0 +1,21 @@
+"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;
+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; } });
+var http_1 = require("./http");
+Object.defineProperty(exports, "CapaError", { enumerable: true, get: function () { return http_1.CapaError; } });
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "WEBHOOKS_NEED_ACCESS_TOKEN", { enumerable: true, get: function () { return webhooks_1.WEBHOOKS_NEED_ACCESS_TOKEN; } });
+var webhook_signature_1 = require("./webhook-signature");
+Object.defineProperty(exports, "DEFAULT_WEBHOOK_TOLERANCE_SECONDS", { enumerable: true, get: function () { return webhook_signature_1.DEFAULT_WEBHOOK_TOLERANCE_SECONDS; } });
+Object.defineProperty(exports, "parseWebhookSignatureHeader", { enumerable: true, get: function () { return webhook_signature_1.parseWebhookSignatureHeader; } });
+Object.defineProperty(exports, "signWebhookPayload", { enumerable: true, get: function () { return webhook_signature_1.signWebhookPayload; } });
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhook_signature_1.verifyWebhookSignature; } });
+Object.defineProperty(exports, "WEBHOOK_SIGNATURE_HEADER", { enumerable: true, get: function () { return webhook_signature_1.WEBHOOK_SIGNATURE_HEADER; } });
+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, "typeNames", { enumerable: true, get: function () { return codegen_1.typeNames; } });

package/dist/next/client.d.ts

@@ -0,0 +1,294 @@
+import type { Select } from "./select-types";
+export interface CapaNextConfig {
+    baseUrl: string;
+    apiKey: string;
+    version: string;
+    contract?: 1;
+    /**
+     * The page these reads are for, sent as `Capa-Page`: `/blog/[slug]` for a
+     * route, or `/blog/hello` for the concrete path being rendered.
+     *
+     * Optional, and telemetry only. It does not change a single byte of any
+     * response, it is not part of the cache key, and Capa ignores a value it
+     * cannot store. What it buys is the answer to "which pages read this entry",
+     * which nothing else in Capa can work out.
+     *
+     * Usually set per call, from the route being rendered, rather than here. Set
+     * it here when a client serves exactly one page.
+     */
+    page?: string;
+    /**
+     * The checksum of the schema this code was generated from, sent as
+     * `Capa-Schema`. Pass `CAPA_SCHEMA_CHECKSUM` from your generated types:
+     *
+     *     import { CAPA_SCHEMA_CHECKSUM } from "./capa-types";
+     *     createClient({ ..., schemaChecksum: CAPA_SCHEMA_CHECKSUM });
+     *
+     * Optional, and telemetry only. It does not change a single byte of any
+     * response and is not part of the cache key. What it buys is the one thing
+     * Capa cannot work out on its own: whether your deployed site was built
+     * against the models the project has NOW, or against an older set. A site
+     * that has never been rebuilt still sends perfectly valid requests, so
+     * without this stamp a stale build is invisible.
+     *
+     * Config only, never per call: one build has one schema.
+     */
+    schemaChecksum?: string;
+    /** Injected for tests, non-standard runtimes, and framework fetch wrappers. */
+    fetch?: typeof fetch;
+}
+interface ResolvedNextConfig extends CapaNextConfig {
+    baseUrl: string;
+    fetchImpl: typeof fetch;
+}
+export interface CallOptions {
+    signal?: AbortSignal;
+    /**
+     * The page THIS read is for. Overrides `page` on the config, because a client
+     * is usually built once and reused across routes.
+     *
+     * See `CapaNextConfig.page`. A malformed value throws a `TypeError` here
+     * rather than being dropped in silence: the API ignores a header it cannot
+     * store, which is right for a running site and wrong for the moment you are
+     * writing the code.
+     */
+    page?: string;
+}
+export interface Entry<T = Record<string, unknown>> {
+    id: string;
+    model: string;
+    status: "published" | "draft" | "changed" | string;
+    createdAt?: string;
+    updatedAt?: string;
+    publishedAt?: string | null;
+    version?: number;
+    folder?: unknown;
+    tags?: string[];
+    fields: T;
+    [key: string]: unknown;
+}
+export interface ResponseMeta {
+    version: string;
+    contract?: number;
+    environment?: string;
+    requestId: string;
+    [key: string]: unknown;
+}
+export interface PageInfo {
+    limit: number;
+    hasNext: boolean;
+    next: string | null;
+    hasPrev: boolean;
+    prev: string | null;
+    total?: number;
+}
+export interface Page<T> {
+    data: T[];
+    page: PageInfo;
+    meta: ResponseMeta;
+    cacheTags: string[];
+}
+export interface Single<T> {
+    data: T;
+    meta: ResponseMeta;
+    cacheTags: string[];
+}
+export type FilterOperator = "eq" | "ne" | "in" | "nin" | "lt" | "lte" | "gt" | "gte" | "contains" | "startsWith" | "endsWith" | "has" | "hasAny" | "hasAll" | "exists" | "null";
+export type FilterScalar = string | number | boolean | null;
+export type FilterValue = FilterScalar | readonly FilterScalar[];
+export type Filter = Record<string, Partial<Record<FilterOperator, FilterValue>>>;
+export interface ListOptions<T = Record<string, unknown>> extends CallOptions {
+    select?: Select<T> | string;
+    filter?: Filter;
+    where?: Record<string, unknown>;
+    sort?: readonly string[];
+    limit?: number;
+    count?: boolean;
+    after?: string;
+    before?: string;
+}
+export interface GetOptions<T = Record<string, unknown>> extends CallOptions {
+    select?: Select<T> | string;
+}
+export interface EntriesResource {
+    list<T = Record<string, unknown>>(namespace: string, options?: ListOptions<T>): Promise<Page<Entry<T>>>;
+    get<T = Record<string, unknown>>(namespace: string, id: string, options?: GetOptions<T>): Promise<Single<Entry<T>> | null>;
+    iterate<T = Record<string, unknown>>(namespace: string, options?: ListOptions<T>): AsyncGenerator<Entry<T>, void, undefined>;
+}
+/**
+ * One suggestion drawn from a page's own reads.
+ *
+ * Computed on the API, never here. Three clients want this answer (this SDK,
+ * the Capa admin and `@capa/mcp`), and a second implementation of "this page
+ * over-fetches" would drift from the first the moment a threshold moved.
+ */
+export interface PageInsight {
+    kind: "overfetch" | "fanout" | "cache" | "drift" | "unused";
+    severity: "info" | "warn";
+    /** One sentence, present tense. The numbers are in `evidence`. */
+    title: string;
+    /** Why it matters, in one or two sentences. */
+    detail: string;
+    /** The copyable fix, when the rule can build one. Absent when it cannot. */
+    rewrite?: {
+        select?: string;
+        /** Query parameters by their full name, ready to paste. */
+        filter?: Record<string, string>;
+        url?: string;
+    };
+    /** Every number the rule used, so the claim can be checked rather than trusted. */
+    evidence: Record<string, number | string | string[]>;
+    modelId?: string;
+    /** The `queries[]` row this is about: `${modelId}:${selectText ?? ""}`. */
+    queryKey?: string;
+    [key: string]: unknown;
+}
+/** One row of `GET /api/pages`. */
+export interface PageSummary {
+    /** The page string. It is the identity, so `id` and `pattern` are equal. */
+    id: string;
+    pattern: string;
+    kind: "declared" | "observed" | "both";
+    models: Array<{
+        id: string;
+        namespace: string;
+        modelName: string;
+    }>;
+    reads30d: number;
+    /**
+     * The newest read of this page in the window, or null when nothing has read
+     * it. The same instant on the list and on the detail: a folded row knows the
+     * day and not the instant, so it claims the day's end, which is the latest
+     * moment the read could have happened and never a future one.
+     */
+    lastReadAt: string | null;
+    slugField: string | null;
+    /** Present only on a list narrowed with `entry`. */
+    entryReads?: number;
+    [key: string]: unknown;
+}
+/** `GET /api/pages/{page}`: one page, its entries and its queries. */
+export interface PageDetail extends PageSummary {
+    page: string;
+    readsByDay: Array<{
+        day: string;
+        reads: number;
+    }>;
+    entries: Array<{
+        id: string;
+        modelId: string;
+        namespace: string;
+        title: string | null;
+        reads: number;
+    }>;
+    queries: Array<{
+        modelId: string;
+        namespace: string | null;
+        selectText: string | null;
+        reads: number;
+        lastAt: string | null;
+        keyIds: string[];
+        /**
+         * The request this group actually made: the most frequent recorded URL for
+         * it in the window, with its filters, sort and limit, not just its select.
+         * Null when every read in the group has been folded into the daily table,
+         * which keeps counts rather than requests.
+         */
+        url: string | null;
+        /**
+         * The Selection IR this query's `select` parses to, against the model's
+         * CURRENT schema, or null when it no longer parses. Parsed on the API so
+         * every client reads one tree. Exactly one of these two is set.
+         *
+         * A failure is usually not a bug: a select recorded last week naming a
+         * field that has since been removed is the drift this screen exists to
+         * show.
+         */
+        selection: unknown | null;
+        selectionError: {
+            code: string;
+            message: string;
+        } | null;
+    }>;
+    since: string;
+    /** Sorted warn first, then by kind. */
+    insights: PageInsight[];
+}
+export interface PagesListOptions extends CallOptions {
+    /**
+     * Narrow the list to the pages that read one entry, and add `entryReads` to
+     * every row. This is "appears on 4 pages" beside an entry.
+     */
+    entry?: string;
+}
+/**
+ * `meta` on `GET /api/pages`, which carries the tenant-wide `unused` insights.
+ *
+ * IN `meta` AND NOT BESIDE `data` because on a list `data` IS the array, so
+ * `meta` is the one place a fact about the whole answer can go. Always present
+ * and empty when there is nothing to say, so "no insights" and "an older API"
+ * never look alike.
+ */
+export interface PagesListMeta extends ResponseMeta {
+    insights: PageInsight[];
+}
+export interface PagesResource {
+    list(options?: PagesListOptions): Promise<{
+        data: PageSummary[];
+        meta: PagesListMeta;
+    }>;
+    get(page: string, options?: CallOptions): Promise<{
+        data: PageDetail;
+        meta: ResponseMeta;
+    } | null>;
+}
+/** What `GET /api/preview` says a preview token names. */
+export interface PreviewClaim {
+    entryId: string;
+    modelId: string;
+    /** Null when the model has since lost its route. */
+    namespace: string | null;
+    /** Null when the path can no longer be resolved. Falls back to your routing. */
+    path: string | null;
+    expiresAt: string;
+}
+export interface CapaNextClient {
+    entries: EntriesResource;
+    pages: PagesResource;
+    /**
+     * Verify a preview token minted by the Capa admin.
+     *
+     * Returns the claim, or NULL when the token is invalid or expired, because
+     * both mean the same thing to a preview route: do not enable draft mode.
+     * Every other failure throws, so a Capa outage does not look like a bad link.
+     */
+    preview(token: string, options?: CallOptions): Promise<PreviewClaim | null>;
+    me<T = Record<string, unknown>>(options?: CallOptions): Promise<T>;
+    versions<T = Record<string, unknown>>(options?: CallOptions): Promise<T>;
+}
+export declare class CapaError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code: string;
+    readonly param?: string;
+    readonly hint?: string;
+    readonly requestId: string;
+    readonly docs: string;
+    constructor(input: {
+        status: number;
+        type: string;
+        code: string;
+        message: string;
+        param?: string;
+        hint?: string;
+        requestId: string;
+        docs: string;
+    });
+}
+export declare function isCapaError(error: unknown): error is CapaError;
+export declare function resolveNextConfig(config: CapaNextConfig): ResolvedNextConfig;
+type SelectInput = string | ReadonlyArray<unknown>;
+/** Serialize the SDK object form into the canonical `/api/entries` grammar. */
+export declare function serializeSelect(select: SelectInput): string;
+export declare function createClient(config: CapaNextConfig): CapaNextClient;
+export {};