@capacms/sdk 1.0.0-next.0

package/bin/capa-codegen.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * capa-codegen — write a tenant's generated types to disk.
+ *
+ *   CAPA_BASE_URL=... CAPA_API_KEY=... CAPA_TENANT_ID=... \
+ *     capa-codegen --out src/capa-types.ts
+ *
+ * Exit codes: 0 wrote or already current, 1 failed, 2 --check found a diff.
+ * `--check` is the CI mode: it fails when the committed file is out of date
+ * with the tenant's schema, which is the whole point of committing it.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const { generate } = require("../dist/codegen.js");
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(name);
+  return i === -1 ? fallback : process.argv[i + 1];
+}
+
+async function main() {
+  const out = arg("--out", "capa-types.ts");
+  const check = process.argv.includes("--check");
+  const config = {
+    baseUrl: process.env.CAPA_BASE_URL || "",
+    apiKey: process.env.CAPA_API_KEY || "",
+    tenantId: process.env.CAPA_TENANT_ID || "",
+  };
+  const target = path.resolve(process.cwd(), out);
+  const existing = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : null;
+
+  const result = await generate(config, existing);
+
+  if (!result.changed) {
+    console.log(`capa-codegen: ${out} is up to date (schema ${result.checksum ?? "unknown"}).`);
+    return 0;
+  }
+  if (check) {
+    console.error(
+      `capa-codegen: ${out} is OUT OF DATE with the tenant schema (${result.checksum}).\n` +
+        `  Run: capa-codegen --out ${out}\n` +
+        `  Types now present: ${result.types.join(", ")}`
+    );
+    return 2;
+  }
+  fs.writeFileSync(target, result.source, "utf8");
+  console.log(`capa-codegen: wrote ${out} — ${result.types.length} types (schema ${result.checksum}).`);
+  return 0;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error(`capa-codegen: ${err.message}`);
+    process.exit(1);
+  }
+);

package/dist/client.d.ts

@@ -0,0 +1,413 @@
+/**
+ * client.ts — the read client, plus the one thing it can write.
+ *
+ * This file used to say the SDK was read-only "because the surface it talks to
+ * is". That was true when it was written and is not any more: the agent surface
+ * (#383) put `/v2/agent/*` behind `verifyApiKey`, ADMIN_UI_OVERHAUL 0h.4b added
+ * `/v2/agent/workspaces`, and `tenant_api_keys.permission` became a real
+ * control (#4646).
+ *
+ * So `workspaces` writes, and nothing else does. A workspace is NAVIGATION —
+ * which models, entries and media folders the admin's left rail keeps in reach,
+ * in which folders — so applying one touches no record and deletes nothing. The
+ * content writes an SDK could now technically reach need a surface designed for
+ * them, not a fourth method quietly added to this object.
+ */
+import { type CapaConfig } from "./config";
+import { type WebhooksResource } from "./webhooks";
+export interface ListOptions {
+    limit?: number;
+    page?: number;
+    /** Relation hops to follow. Higher is much larger. */
+    depth?: number;
+    sort?: string;
+    /**
+     * Field filters, applied server-side: `{ handle: "about-us" }` becomes
+     * `?handle=about-us`. Verified against a live tenant — a matching value
+     * returns the row, a non-matching one returns an empty set.
+     */
+    where?: Record<string, string | number | boolean>;
+}
+export interface Page<T> {
+    data: T[];
+    /**
+     * Instance ids positionally matching `data`, `null` only when the API sent
+     * no usable id at all. See `instanceIdOf`. Read these rather than `row.id`,
+     * which is the model's own field whenever one is named `id`.
+     */
+    ids: (string | null)[];
+    meta: {
+        total?: number;
+        totalPages?: number;
+        currentPage?: number;
+        limit?: number;
+        hasNextPage?: boolean | null;
+        hasPrevPage?: boolean | null;
+    };
+    /** Fastly surrogate keys for this response, for the host's CDN purging. */
+    cacheTags: string[];
+}
+export interface CapaClient {
+    listContent<T = Record<string, unknown>>(namespace: string, options?: ListOptions): Promise<Page<T>>;
+    getContentById<T = Record<string, unknown>>(namespace: string, id: string, options?: Pick<ListOptions, "depth">): Promise<T | null>;
+    findOne<T = Record<string, unknown>>(namespace: string, where: Record<string, string | number | boolean>, options?: Pick<ListOptions, "depth">): Promise<T | null>;
+    search(q: string, options?: {
+        namespace?: string;
+        limit?: number;
+        page?: number;
+    }): Promise<SearchHit[]>;
+    /** Saved arrangements of the Capa admin's left rail. ADMIN_UI_OVERHAUL 0h. */
+    workspaces: WorkspacesResource;
+    /** Model schema reads, and the entry-editor layout. ADMIN_UI_OVERHAUL 0m. */
+    models: ModelsResource;
+    /** Scheduled publishes and unpublishes. docs/PUBLISHING.md. */
+    scheduledActions: ScheduledActionsResource;
+    /**
+     * Webhook endpoints and their deliveries. docs/WEBHOOKS.md.
+     *
+     * The one resource that needs `accessToken` rather than `apiKey`: the routes
+     * behind it have no API key mount at all (publishing spec D8), and every
+     * method throws with that message when the token is missing.
+     */
+    webhooks: WebhooksResource;
+}
+export type LayoutWidth = "full" | "two_thirds" | "half" | "third";
+/**
+ * How a relation field renders. `picker` is a link to the related entry,
+ * `inline` a list of expandable rows, and `embedded` (0m.8) the related
+ * entry's own fields drawn directly in the parent card.
+ */
+export type LayoutDisplay = "picker" | "inline" | "embedded";
+export interface LayoutInline {
+    allowCreate: boolean;
+    allowRemove: boolean;
+    allowReorder: boolean;
+    /** Up to 3 field ids of the RELATED model, shown on a collapsed row. */
+    summary: string[];
+}
+export interface LayoutField {
+    t: "field";
+    /** Layout node id — stable across edits, unique in the document. */
+    id: string;
+    /** A field id of THIS model. Every field appears at most once. */
+    fieldId: string;
+    width: LayoutWidth;
+    /** Relation fields only. Left out, the related model's `embedByDefault` decides. */
+    display?: LayoutDisplay;
+    /** Relation fields only. */
+    inline?: LayoutInline;
+}
+export interface LayoutCard {
+    t: "card";
+    id: string;
+    title: string;
+    description?: string;
+    collapsible: boolean;
+    collapsed: boolean;
+    items: LayoutField[];
+}
+/**
+ * How one model's entry editor is arranged: cards in a main column and a side
+ * column. `null` on a model means the linear editor, which is what every model
+ * had before 0m and what a model without a layout still gets.
+ */
+export interface ModelLayout {
+    v: 1;
+    main: LayoutCard[];
+    aside: LayoutCard[];
+}
+/**
+ * The two model-level facts 0m adds, as `GET /v2/models/:id` carries them.
+ *
+ * They are read together because a form renderer needs both: the layout says
+ * where the fields go, and `embedByDefault` decides what a relation field with
+ * no `display` does — including in linear mode, where there is no layout to
+ * carry a node at all.
+ */
+export interface ModelLayoutInfo {
+    /** The layout document, or null when the model is in linear mode. */
+    layout: ModelLayout | null;
+    /**
+     * Whether a relation field pointing AT this model renders this model's
+     * fields inside the parent form by default (0m.8). A layout node's own
+     * `display` always wins over it.
+     */
+    embedByDefault: boolean;
+}
+export interface ModelsResource {
+    /** The layout document, or null when the model is in linear mode. */
+    getLayout(id: string): Promise<ModelLayout | null>;
+    /** `getLayout` plus the model's pass-through default, in one read. */
+    getLayoutInfo(id: string): Promise<ModelLayoutInfo>;
+    /**
+     * Save a layout, or pass `null` to reset the model to the linear editor.
+     *
+     * The API validates the document against the model (§0m.1) and answers 400
+     * with `{ error, path }` naming the offending node — `CapaError.message`
+     * carries both. It stores the NORMALISED document, which is what comes back,
+     * so the return value is what the next `getLayout` will return.
+     */
+    setLayout(id: string, layout: ModelLayout | null): Promise<ModelLayout | null>;
+}
+/**
+ * One node of a workspace document. Models take a namespace OR an id.
+ *
+ * §0t made a folder hold ANY of these. 0h had three separate trees keyed by
+ * section, so a folder had a kind; the customer names folders now, and a folder
+ * called "Config" cannot also mean a kind.
+ */
+export type WorkspaceDocNode = {
+    folder: string;
+    children?: WorkspaceDocNode[];
+} | {
+    model: string;
+} | {
+    instance: string;
+} | {
+    media_folder: string;
+};
+/**
+ * 0h's three-key tree, accepted for ONE more release.
+ *
+ * Sending it lands the three lists in folders called Models, Content and Media,
+ * and a key you omit is left alone even in replace mode — that was 0h's rule
+ * for a section it had no key for, and breaking it would turn a grace period
+ * into a data-loss bug. Send `WorkspaceDocNode[]` instead.
+ *
+ * @deprecated Send a `WorkspaceDocNode[]` as `tree`.
+ */
+export interface WorkspaceTreeDocument {
+    model?: WorkspaceDocNode[];
+    content?: WorkspaceDocNode[];
+    /** Media folder ids. Media stays folder-backed; a workspace pins a subset. */
+    media?: string[];
+}
+/** What a workspace starts with (§0t). A template is only a folder list. */
+export type WorkspaceTemplate = "blank" | "website" | "catalog";
+/**
+ * What `get` returns and `apply` accepts — the SAME shape, so a caller can read
+ * one, edit it and write it back without a translation step.
+ */
+export interface WorkspaceDocument {
+    id: string;
+    name: string;
+    icon: string | null;
+    visibility: "team" | "private";
+    isDefault: boolean;
+    /** The top level. There is no root node, so this IS the workspace. */
+    tree: WorkspaceDocNode[];
+}
+export interface WorkspaceSummary {
+    id: string;
+    name: string;
+    icon: string | null;
+    visibility: "team" | "private";
+    isDefault: boolean;
+    sortOrder: number;
+    assignedRoles: string[];
+    createdById: string | null;
+    isMine: boolean;
+    nodeCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * What changed. Read it rather than the final state to find out whether a call
+ * did anything: applying the same document twice reports all zeros.
+ */
+export interface WorkspaceChanges {
+    created: number;
+    moved: number;
+    renamed: number;
+    removed: number;
+    unchanged: number;
+}
+export interface WorkspaceApplyResult {
+    workspace: WorkspaceSummary;
+    changes: WorkspaceChanges;
+    /** Ids and namespaces the document named that this tenant does not have. */
+    unresolved?: string[];
+}
+export interface WorkspacesResource {
+    list(options?: {
+        includePrivate?: boolean;
+    }): Promise<{
+        workspaces: WorkspaceSummary[];
+        currentId: string | null;
+        defaultId: string | null;
+    }>;
+    /** One workspace's summary row, or null. */
+    get(id: string): Promise<WorkspaceSummary | null>;
+    /** The declarative document — the shape `apply` takes back. */
+    getDocument(id: string): Promise<WorkspaceDocument>;
+    apply(id: string, document: {
+        tree?: WorkspaceDocNode[] | WorkspaceTreeDocument;
+    }, options?: {
+        mode?: "replace" | "merge";
+    }): Promise<WorkspaceApplyResult>;
+    create(input: {
+        name: string;
+        icon?: string | null;
+        /** Folders to start with. Ignored when `tree` is given. */
+        template?: WorkspaceTemplate;
+        tree?: WorkspaceDocNode[] | WorkspaceTreeDocument;
+    }): Promise<WorkspaceApplyResult>;
+}
+export type ScheduledActionStatus = "pending" | "running" | "done" | "failed" | "dead" | "cancelled";
+/**
+ * One row of the publishing ledger: one thing to do, to one target, at one
+ * instant. `versionId: null` means the latest draft AT FIRE TIME, which is the
+ * default and the point of the feature (decision D1) — a typo fixed on Tuesday
+ * is live when Wednesday's schedule runs.
+ *
+ * `runAt` is the only column the worker reads. `wallTime` and `timezone` are
+ * what the person chose, kept so a screen can show it back and a reschedule can
+ * re-resolve it; they are never used to decide when to fire.
+ */
+export interface ScheduledAction {
+    id: string;
+    tenantId: string;
+    batchId: string;
+    action: "publish" | "unpublish";
+    targetType: "instance" | "model";
+    targetId: string;
+    versionId: string | null;
+    runAt: string;
+    /** `runAt` rendered in this row's own zone, ISO with offset. */
+    runAtInTimezone: string;
+    timezone: string;
+    wallTime: string;
+    status: ScheduledActionStatus;
+    attempts: number;
+    lastError: string | null;
+    errorCode: string | null;
+    /** The version row the publish created. "Why did this go live at 3am". */
+    resultVersionId: string | null;
+    requestedBy: string | null;
+    cancelledBy: string | null;
+    cancelledAt: string | null;
+    completedAt: string | null;
+    retryOfId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /** `null` when the target row is gone. */
+    target: {
+        title: string | null;
+        modelId: string;
+        modelNamespace: string;
+        modelName: string;
+    } | null;
+    [column: string]: unknown;
+}
+/** What the server made of a `wallTime` + `timezone` pair. */
+export interface ResolvedScheduleTime {
+    runAt: string;
+    wallTime: string;
+    timezone: string;
+    runAtInTimezone: string;
+    /**
+     * Non-null when daylight saving moved the time: a wall time that does not
+     * exist resolves forward, one that happens twice takes the earlier offset.
+     * Written as a sentence to show a person, so show it.
+     */
+    note: string | null;
+}
+export interface ScheduledActionTarget {
+    /**
+     * `"model"` is a session-only target in phase 1. It needs `model:publish`,
+     * and no API key bundle grants that, so a model target sent with a key is a
+     * 403 every time. Schedule models from the admin until a bundle carries it.
+     */
+    type: "instance" | "model";
+    id: string;
+    /** Omit for the latest draft at fire time, which is what you usually want. */
+    versionId?: string;
+}
+export interface CreateScheduledActionsInput {
+    action: "publish" | "unpublish";
+    targets: ScheduledActionTarget[];
+    /** Local wall clock, NO offset: "2026-10-01T09:00". */
+    wallTime: string;
+    /** IANA name, e.g. "America/New_York". */
+    timezone: string;
+}
+export interface CreateScheduledActionsResult {
+    batchId: string;
+    runAt: string;
+    resolved: ResolvedScheduleTime;
+    actions: ScheduledAction[];
+    /** Ids of actions cancelled to make room. One active action per target per verb. */
+    replaced: string[];
+}
+export interface ScheduledActionsPage {
+    actions: ScheduledAction[];
+    pagination: {
+        total: number;
+        page: number;
+        limit: number;
+        totalPages: number;
+        hasMore: boolean;
+    };
+}
+export interface ListScheduledActionsOptions {
+    status?: ScheduledActionStatus[];
+    targetId?: string;
+    batchId?: string;
+    from?: string;
+    to?: string;
+    page?: number;
+    limit?: number;
+}
+export interface ScheduledActionsResource {
+    create(input: CreateScheduledActionsInput): Promise<CreateScheduledActionsResult>;
+    list(options?: ListScheduledActionsOptions): Promise<ScheduledActionsPage>;
+    get(id: string): Promise<ScheduledAction | null>;
+    /**
+     * Returns the moved action with the server's `resolved` block attached, the
+     * same one `create` returns. Read `resolved.note` before showing a time.
+     */
+    reschedule(id: string, when: {
+        wallTime: string;
+        timezone: string;
+    }): Promise<ScheduledAction & {
+        resolved: ResolvedScheduleTime;
+    }>;
+    cancel(id: string): Promise<ScheduledAction>;
+    /** Creates a NEW pending row; the failed one keeps its history. */
+    retry(id: string): Promise<ScheduledAction>;
+}
+export interface SearchHit {
+    /**
+     * The instance UUID, via `instanceIdOf`. `null` means the server sent no
+     * usable id: an extended search row hoists the model's own fields the same
+     * way a content row does, so a model with a field named `id` shadows it, and
+     * a server older than #4628 sends no `instanceId` beside it.
+     */
+    id: string | null;
+    namespace: string | null;
+    model?: string;
+    title: unknown;
+}
+/**
+ * The Capa instance id for a row.
+ *
+ * `instanceId` FIRST, and it is the answer on any current server: #4628 added
+ * it to every public read row as the last key, precisely so that one key always
+ * means the instance id.
+ *
+ * `id` is the fallback, and it is a fallback because it is not trustworthy.
+ * `GET /v2/api/:ns` builds each row as `{...instance, ...formatInstanceData(instance)}`
+ * — the model's own fields are hoisted to the top level and spread SECOND, so a
+ * field named `id` overwrites the instance's id and the real UUID is then absent
+ * from the row, not merely moved. The same happens to `title` and `tags`. In one
+ * ordinary tenant 20 of 20 models have a field named `title` and 7 of 20 have
+ * one named `id` (every shopify_* model, plus judge_me_review), so this is the
+ * common case. The UUID test is therefore kept for servers older than the fix,
+ * where it is the only thing separating an instance id from a Shopify numeric
+ * id that happens to live in a field called `id`.
+ *
+ * `null` means the server sent no usable id at all: an old server AND a
+ * shadowing model. `getContentById` cannot be reached for such a row.
+ */
+export declare function instanceIdOf(row: unknown): string | null;
+export declare function createClient(config: CapaConfig): CapaClient;