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

package/dist/next/attrs.js

@@ -1,8 +1,125 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPA_EDIT = void 0;
+exports.isEditEntry = isEditEntry;
+exports.markEditEntries = markEditEntries;
+exports.markGraphQLEntries = markGraphQLEntries;
+exports.hasGraphQLEntry = hasGraphQLEntry;
+exports.carryEditMark = carryEditMark;
 exports.capaAttrs = capaAttrs;
-function capaAttrs(entry, field, enabled = true) {
+exports.fieldAttrs = fieldAttrs;
+/** `Symbol.for`, so two copies of the SDK in one bundle agree on the mark. */
+exports.CAPA_EDIT = Symbol.for("capacms.edit");
+/** Whether an entry was read in edit mode. */
+function isEditEntry(entry) {
+    return (typeof entry === "object" &&
+        entry !== null &&
+        entry[exports.CAPA_EDIT] === true);
+}
+/**
+ * Where a GraphQL node read in edit mode keeps the namespaces of the fields
+ * GraphQL renamed, by GraphQL name. Hidden like the mark itself.
+ */
+const CAPA_EDIT_NAMESPACES = Symbol.for("capacms.edit.namespaces");
+/** A REST entry: an id beside `fields`. */
+function looksLikeEntry(value) {
+    return typeof value.id === "string" && typeof value.fields === "object" && value.fields !== null;
+}
+/** A GraphQL entry: the `Entry` interface's `id` and `model`, which every model type has. */
+function looksLikeGraphQLEntry(value) {
+    return typeof value.id === "string" && typeof value.model === "string";
+}
+/** Define a hidden property: absent from JSON, keys and spreads. */
+function hide(record, key, value) {
+    Object.defineProperty(record, key, { value, enumerable: false, configurable: true });
+}
+/** Visit every plain object and array inside `value` once, cycles included. */
+function eachObject(value, visit) {
+    const seen = new Set();
+    const walk = (node) => {
+        if (typeof node !== "object" || node === null || seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        const record = node;
+        visit(record);
+        for (const key of Object.keys(record))
+            walk(record[key]);
+    };
+    walk(value);
+}
+/**
+ * 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.
+ */
+function markEditEntries(value) {
+    eachObject(value, (record) => {
+        if (looksLikeEntry(record) && Object.isExtensible(record))
+            hide(record, exports.CAPA_EDIT, true);
+    });
+    return value;
+}
+/**
+ * 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`.
+ */
+function markGraphQLEntries(data, renamed = () => undefined) {
+    eachObject(data, (record) => {
+        if (!looksLikeGraphQLEntry(record) || !Object.isExtensible(record))
+            return;
+        hide(record, exports.CAPA_EDIT, true);
+        const namespaces = renamed(record.model);
+        if (namespaces)
+            hide(record, CAPA_EDIT_NAMESPACES, namespaces);
+    });
+    return data;
+}
+/** Whether a GraphQL result's `data` holds any entry `markGraphQLEntries` would mark. */
+function hasGraphQLEntry(data) {
+    let found = false;
+    eachObject(data, (record) => {
+        found ||= looksLikeGraphQLEntry(record);
+    });
+    return found;
+}
+/** Keep `from`'s edit mark on `to`, for a copy of an entry in another shape (`toTree`). */
+function carryEditMark(from, to) {
+    if (isEditEntry(from) && Object.isExtensible(to))
+        hide(to, exports.CAPA_EDIT, true);
+    return to;
+}
+/** The namespace a field of `entry` is tagged with: a renamed GraphQL field's own, else the name given. */
+function namespaceOf(entry, field) {
+    const namespaces = entry[CAPA_EDIT_NAMESPACES];
+    return namespaces?.[field] ?? field;
+}
+function capaAttrs(entry, field, enabled = isEditEntry(entry)) {
     if (!enabled)
         return {};
-    return { "data-capa-entry": entry.id, "data-capa-field": field };
+    return { "data-capa-entry": entry.id, "data-capa-field": namespaceOf(entry, field) };
+}
+/**
+ * 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.
+ */
+function fieldAttrs(entry, enabled = isEditEntry(entry)) {
+    return new Proxy({}, {
+        get(_target, key) {
+            if (typeof key !== "string")
+                return undefined;
+            return enabled ? { "data-capa-entry": entry.id, "data-capa-field": namespaceOf(entry, key) } : {};
+        },
+    });
 }

package/dist/next/client.d.ts

@@ -1,6 +1,18 @@
-import type { Select } from "./select-types";
+import type { CapaDocumentResult, CapaDocuments, CapaDocumentVariables, NotARecordedDocument } from "./graphql/documents";
+import { type GraphQLCallOptions, type GraphQLResult, type TypedDocument, type VariablesThenOptions } from "./graphql/request";
+import { type GraphQLSchemaSummary } from "./graphql/summary";
+import { type ExactSelection, type QueryResult, type QuerySelection, type UntypedQuery } from "./graphql/typed";
+export { CapaError, isCapaError } from "./errors";
+import type { EntryFields, FlatFields, FlatRead, IncludedFields } from "./entry-fields";
+import type { ExpandedTargets, Select } from "./select-types";
 export interface CapaNextConfig {
     baseUrl: string;
+    /**
+     * A `cap_` key, or the legacy key a site already holds: `pk_`, `sk_`, or
+     * an older key with no prefix. A legacy key reads through every read call,
+     * `preview()` included, and warns once per process; the draft clients of
+     * `@capacms/sdk/nextjs` take a `cap_` key only.
+     */
     apiKey: string;
     version: string;
     contract?: 1;
@@ -34,6 +46,23 @@ export interface CapaNextConfig {
      * Config only, never per call: one build has one schema.
      */
     schemaChecksum?: string;
+    /**
+     * Read in edit mode: every entry this client returns carries the hidden edit
+     * mark, so `capaAttrs` tags it for the Capa editor. Leave it off for visitors
+     * and a published page ships no entry ids. `@capacms/sdk/nextjs` works it out
+     * per request with `editMode()`.
+     *
+     * The same request is sent either way. A GraphQL read marks each object
+     * that selected `id` and `model`, and to tag a field GraphQL renamed by its
+     * namespace, it also reads the key's schema, once a minute.
+     */
+    editMode?: boolean;
+    /**
+     * The concrete path being rendered (`/blog/hello`), sent as `Capa-Path`
+     * beside `Capa-Page` (`/blog/[slug]`). Telemetry only, like `page`: it is how
+     * Capa lists every real URL an entry appears on. Usually set per call.
+     */
+    path?: string;
     /** Injected for tests, non-standard runtimes, and framework fetch wrappers. */
     fetch?: typeof fetch;
 }
@@ -53,7 +82,18 @@ export interface CallOptions {
      * writing the code.
      */
     page?: string;
+    /**
+     * The concrete path THIS read renders (`/blog/hello`). Overrides `path` on the
+     * config. Sent as `Capa-Path` only alongside a `Capa-Page`, since a path with
+     * no page says nothing Capa can group.
+     */
+    path?: string;
 }
+/**
+ * One entry as `/api/entries` returns it: the system keys, and `fields`. A read
+ * types `fields` from its model and select (`EntryFields`), so a relation is a
+ * reference or the related entry, and a relation list is `{ items, pageInfo }`.
+ */
 export interface Entry<T = Record<string, unknown>> {
     id: string;
     model: string;
@@ -97,29 +137,80 @@ export type FilterOperator = "eq" | "ne" | "in" | "nin" | "lt" | "lte" | "gt" |
 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;
+/**
+ * How expanded relations come back (`?shape=`). `tree`, the default, nests each
+ * one inline where it was selected. `flat` answers every relation as a
+ * `{ id, model }` reference and every expanded entry ONCE, in `included`, so
+ * twenty articles by one author carry that author once. `inflate(result)`
+ * turns a flat result back into the tree one.
+ */
+export type ResponseShape = "tree" | "flat";
+export interface ListOptions<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string> extends CallOptions {
+    select?: S;
+    shape?: "tree";
     filter?: Filter;
     where?: Record<string, unknown>;
     sort?: readonly string[];
     limit?: number;
     count?: boolean;
+    /** `page.next`: the page after it. */
     after?: string;
+    /** `page.prev`: the page before it. Or `"end"`: the last `limit` entries of the list. */
     before?: string;
 }
-export interface GetOptions<T = Record<string, unknown>> extends CallOptions {
-    select?: Select<T> | string;
+export interface GetOptions<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string> extends CallOptions {
+    select?: S;
+    shape?: "tree";
+}
+/** `list` with `shape: "flat"`. `S` is the select, which types `included`. */
+export type FlatListOptions<T, S extends Select<T> | string = Select<T>> = Omit<ListOptions<T>, "select" | "shape"> & {
+    select?: S;
+    shape: "flat";
+};
+/** `get` with `shape: "flat"`. */
+export type FlatGetOptions<T, S extends Select<T> | string = Select<T>> = Omit<GetOptions<T>, "select" | "shape"> & {
+    select?: S;
+    shape: "flat";
+};
+/**
+ * `included` of a flat read: model namespace, then entry id, then the entry.
+ * Typed by the select: the union of every entry type it expands, each field
+ * of which may be absent, and every relation in it a reference.
+ */
+export type Included<I> = Record<string, Record<string, Entry<IncludedFields<I>>>>;
+interface FlatExtras<T, S> extends FlatRead<T, S> {
+    included: Included<[ExpandedTargets<T, S>] extends [never] ? never : ExpandedTargets<T, S>>;
+    /** The select this read sent, which is what `inflate` walks. Absent when none was sent. */
+    select?: string;
 }
+/** A `shape=flat` list: every relation in `data` a reference, each expanded entry once in `included`. */
+export type FlatPage<T, S = Select<T>> = Page<Entry<FlatFields<T, S>>> & FlatExtras<T, S>;
+export type FlatSingle<T, S = Select<T>> = Single<Entry<FlatFields<T, S>>> & FlatExtras<T, S>;
+/**
+ * `T` as given, never inferred from the options: a read's model type is
+ * written (`list<Article>`), and without one the read is untyped whatever its
+ * select names. Inferred from a select's names, `T` would be `{ title: any }`,
+ * which refuses the relations the same select expands.
+ */
+type Given<T> = [T][T extends unknown ? 0 : never];
+/**
+ * Reads of `/api/entries`. `T` is the model type (`list<Articles>`), and `S`
+ * the select's own type, for `fields` typed exactly as the read returns them
+ * (`list<Articles, typeof select>`); see `EntryFields`.
+ */
 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>;
+    list<T = Record<string, unknown>, S extends Select<T> | string = Select<T>>(namespace: string, options: FlatListOptions<Given<T>, S>): Promise<FlatPage<T, S>>;
+    list<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string>(namespace: string, options?: ListOptions<Given<T>, S>): Promise<Page<Entry<EntryFields<T, S>>>>;
+    get<T = Record<string, unknown>, S extends Select<T> | string = Select<T>>(namespace: string, id: string, options: FlatGetOptions<Given<T>, S>): Promise<FlatSingle<T, S> | null>;
+    get<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string>(namespace: string, id: string, options?: GetOptions<Given<T>, S>): Promise<Single<Entry<EntryFields<T, S>>> | null>;
+    /** Tree only: it yields entries one at a time, which is what `included` exists to avoid. */
+    iterate<T = Record<string, unknown>, S extends Select<T> | string = Select<T> | string>(namespace: string, options?: ListOptions<Given<T>, S>): AsyncGenerator<Entry<EntryFields<T, S>>, 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
+ * the Capa admin and `@capacms/mcp`), and a second implementation of "this page
  * over-fetches" would drift from the first the moment a threshold moved.
  */
 export interface PageInsight {
@@ -252,7 +343,56 @@ export interface PreviewClaim {
     path: string | null;
     expiresAt: string;
 }
-export interface CapaNextClient {
+/**
+ * `client.graphql`: run a document, or build one from a typed selection with
+ * `client.graphql.query()`. `Q` is the `CapaQuery` type `capa-codegen
+ * --graphql` writes; without it selections and results are untyped. `O` is
+ * what a call takes: `getCapaClient` from `/nextjs` adds Next's cache `tags`
+ * and `revalidate`.
+ */
+export interface GraphQLClient<Q = UntypedQuery, O extends GraphQLCallOptions = GraphQLCallOptions> {
+    /**
+     * Run a document written as a literal (`#graphql`, `/* capa *\/` or
+     * gql(`...`)) that `capa-codegen --graphql` has checked: its text is looked
+     * up in `CapaDocuments`, so `data` and `variables` are typed with no cast.
+     *
+     * Resolves once the API ran the document, even when `errors` is not empty,
+     * because the root fields that worked still carry data. Throws `CapaError`
+     * when the API refused the request as a whole, with `graphqlErrors` holding
+     * every error it sent: `errors` and no `data`, whether sent as a 4xx or, as
+     * GraphQL over HTTP sends it on `application/json`, as a 200.
+     */
+    <D extends keyof CapaDocuments>(document: D, ...rest: VariablesThenOptions<CapaDocumentVariables<D>, O>): Promise<GraphQLResult<CapaDocumentResult<D>>>;
+    /**
+     * Run a GraphQL document. A `<Name>Document` from `capa-codegen --graphql`
+     * types `data` and `variables` by itself; for any other string, pass the
+     * data type: `capa.graphql<{ articles: ... }>(query, variables)`.
+     */
+    <TData = Record<string, unknown>, TVariables = Record<string, unknown>, D extends string = string>(document: NotARecordedDocument<D, TypedDocument<TData, TVariables> | D>, ...rest: VariablesThenOptions<TVariables, O>): Promise<GraphQLResult<TData>>;
+    /**
+     * Build the document from a selection object and run it. See "Typed
+     * builder" in the README. It takes no `persisted`: see `BuilderCallOptions`.
+     */
+    query<const S extends QuerySelection<Q>>(selection: S & ExactSelection<S, Q>, options?: BuilderCallOptions<O>): Promise<GraphQLResult<QueryResult<Q, S>>>;
+}
+/**
+ * What `graphql.query()` takes: a call's options without `persisted`. The
+ * builder prints its document when it runs, so `capa persist`, which stores
+ * the documents written in a project, never stored it, and a production key
+ * never registers one: every read would miss its hash and fall back to a POST,
+ * which is never cached. Unpersisted, a builder read is already a GET the API
+ * and the CDN cache. To persist a read, write it as a `#graphql` literal.
+ */
+export type BuilderCallOptions<O extends GraphQLCallOptions = GraphQLCallOptions> = Omit<O, "persisted">;
+/**
+ * `client.graphql` over one way of reading a document: called with a
+ * document, and `query()` printing a selection's document for it. `createClient`
+ * reads straight from the API, and `getCapaClient` from `/nextjs` the same way
+ * unless a call gives `tags` or `revalidate`, then through Next's data cache,
+ * with the same refusals.
+ */
+export declare function graphqlClient<Q, O extends GraphQLCallOptions>(read: (document: string, variables: Record<string, unknown> | undefined, options: O | undefined) => Promise<GraphQLResult<unknown>>): GraphQLClient<Q, O>;
+export interface CapaNextClient<Q = UntypedQuery, O extends GraphQLCallOptions = GraphQLCallOptions> {
     entries: EntriesResource;
     pages: PagesResource;
     /**
@@ -261,34 +401,38 @@ export interface CapaNextClient {
      * 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.
+     * Takes any key the site holds, a legacy `pk_`, `sk_` or unprefixed key
+     * included: Capa answers a token minted for another tenant as invalid.
      */
     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>;
+    graphql: GraphQLClient<Q, O>;
+    /**
+     * Every model this key can read over GraphQL, with its root fields, fields,
+     * filter operators and sort values, read from one introspection request.
+     * What `buildGraphQLQuery`, `graphqlToSelect` and `toTree` take.
+     */
+    graphqlSchema(options?: {
+        signal?: AbortSignal;
+    }): Promise<GraphQLSchemaSummary<Q>>;
 }
-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;
+/**
+ * The page a layout (or template) reads for: none.
+ *
+ * A root layout renders around every page on the site, so charging its reads
+ * to `/`, the route its file sits at, made the home page look as if it read
+ * every Site singleton and nav on the site. `routeOf` returns this for a
+ * `layout.*` or `template.*` file, and a read that names it sends NO
+ * `Capa-Page` at all, even when the client was built with a `page`.
+ *
+ * Not sent as a value, because the API would drop it anyway: it is not a
+ * `PAGE_ID`, and the API ignores what it cannot store. Staying absent keeps a
+ * layout read byte-identical to one from a client that never named a page.
+ */
+export declare const LAYOUT_PAGE = "(layout)";
 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 {};
+export declare function createClient<Q = UntypedQuery>(config: CapaNextConfig): CapaNextClient<Q>;