@capacms/sdk 1.0.0-next.4 → 1.0.0-next.6

package/dist/nextjs/index.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_API_VERSION = exports.CAPA_ENV = exports.EDIT_CACHE_CONTROL = exports.DRAFT_COOKIE = exports.EDIT_HEADER = exports.EDIT_PARAM = exports.LAYOUT_PAGE = void 0;
+exports.DEFAULT_API_VERSION = exports.CAPA_ENV_ALIASES = exports.CAPA_ENV = exports.EDIT_CACHE_CONTROL = exports.DRAFT_COOKIE = exports.EDIT_HEADER = exports.EDIT_PARAM = exports.LAYOUT_PAGE = exports.gql = exports.MEDIA_TAG = exports.GRAPHQL_TAG = void 0;
 exports.withCache = withCache;
+exports.modelTag = modelTag;
 exports.tagsFor = tagsFor;
 exports.revalidateFromWebhook = revalidateFromWebhook;
 exports.draftClient = draftClient;
@@ -12,12 +13,17 @@ exports.editMode = editMode;
 exports.resolveEditRequest = resolveEditRequest;
 exports.getPublishedClient = getPublishedClient;
 exports.getCapaClient = getCapaClient;
+exports.graphql = graphql;
 exports.safeSitePath = safeSitePath;
 exports.createPreviewRoute = createPreviewRoute;
 exports.exitPreviewRoute = exitPreviewRoute;
 exports.capaMiddleware = capaMiddleware;
 const next_1 = require("../next");
+Object.defineProperty(exports, "gql", { enumerable: true, get: function () { return next_1.gql; } });
 Object.defineProperty(exports, "LAYOUT_PAGE", { enumerable: true, get: function () { return next_1.LAYOUT_PAGE; } });
+const client_1 = require("../next/client");
+const sha256_1 = require("../next/graphql/sha256");
+const key_family_1 = require("../next/key-family");
 /** Add Next.js fetch-cache options without importing `next/*`. */
 function withCache(fetchImpl, options) {
     return (async (input, init = {}) => {
@@ -31,6 +37,38 @@ function withCache(fetchImpl, options) {
         return fetchImpl(input, { ...init, next });
     });
 }
+/**
+ * The Next.js cache tag for every read of a model, by its namespace. A GraphQL
+ * query names its models by namespace (`articles`), not by id, so this is the
+ * tag a GraphQL read is cached under, and `revalidateFromWebhook` revalidates
+ * it when an entry of that model changes.
+ */
+function modelTag(namespace) {
+    return `capa:model:${namespace}`;
+}
+/**
+ * The tag `graphql()` gives a read that names no `tags`, and that
+ * `revalidateFromWebhook` revalidates on every content change: such a page is
+ * never stale after a publish, at the price of refreshing on any publish.
+ * Name the models it reads with `tagsFor({ namespace })` to refresh it only
+ * when one of those changes.
+ */
+exports.GRAPHQL_TAG = "capa:graphql";
+/**
+ * The tag `tagsFor({ namespace })` adds beside its model tags, and that
+ * `revalidateFromWebhook` revalidates on a media event: a GraphQL read shows
+ * a file's URL and alt text whichever models it names, so editing a file in
+ * the media library refreshes it.
+ */
+exports.MEDIA_TAG = "capa:media";
+/**
+ * Next.js cache tags for a read. `model`, `entry`, `key` and `tenant` are the
+ * API's surrogate keys (`m:`, `e:`, `k:`, `t:`), by id; `namespace` is one
+ * `capa:model:<namespace>` tag per model a GraphQL query reads, which
+ * `capa-codegen --graphql` lists as `<Name>Models`, and `MEDIA_TAG`, since
+ * the query may show a file from the media library. Each pairs with
+ * `revalidateFromWebhook`.
+ */
 function tagsFor(input) {
     const tags = [];
     if (input.model)
@@ -41,9 +79,26 @@ function tagsFor(input) {
         tags.push(`k:${input.key}`);
     if (input.tenant)
         tags.push(`t:${input.tenant}`);
+    const namespaces = typeof input.namespace === "string" ? [input.namespace] : (input.namespace ?? []);
+    for (const namespace of namespaces)
+        if (namespace)
+            tags.push(modelTag(namespace));
+    if (namespaces.some(Boolean))
+        tags.push(exports.MEDIA_TAG);
     return tags;
 }
-/** Revalidate the concrete entry and model identities carried by a webhook. */
+/**
+ * Revalidate every tag a webhook's entry and model can be cached under: the
+ * entry (`e:`), the model by id (`m:`) and by namespace (`capa:model:`, the
+ * tag a GraphQL read uses). The namespace is `data.modelNamespace` on
+ * `instance.published`, `instance.unpublished` and `model.published`, and
+ * `data.namespace` on the other events (docs/WEBHOOKS.md). Any of those, and
+ * a `media.` event, also revalidates `GRAPHQL_TAG`, the tag of a `graphql()`
+ * read that named no tags. A `media.` event (a file's alt text, name or
+ * visibility changed, or the file went) revalidates the file's own key
+ * (`f:<fileId>`, as REST's `Surrogate-Key` names it) and `MEDIA_TAG`, which
+ * every read tagged by namespace carries, since it may show that file.
+ */
 async function revalidateFromWebhook(input) {
     const data = input.payload?.data ?? input.payload;
     const tags = [];
@@ -52,14 +107,34 @@ async function revalidateFromWebhook(input) {
         tags.push(`e:${entryId}`);
     if (typeof data?.modelId === "string" && data.modelId)
         tags.push(`m:${data.modelId}`);
+    const namespace = data?.modelNamespace ?? data?.namespace;
+    if (typeof namespace === "string" && namespace)
+        tags.push(modelTag(namespace));
+    const media = typeof input.payload?.type === "string" && input.payload.type.startsWith("media.");
+    if (media) {
+        if (typeof data?.fileId === "string" && data.fileId)
+            tags.push(`f:${data.fileId}`);
+        tags.push(exports.MEDIA_TAG);
+    }
+    if (tags.length > 0 || media)
+        tags.push(exports.GRAPHQL_TAG);
     const unique = [...new Set(tags)];
     for (const tag of unique)
         await input.revalidateTag(tag);
     return unique;
 }
-/** Select a client using server-only draft state supplied by the caller. */
+/**
+ * Select a client using server-only draft state supplied by the caller. Pass
+ * codegen's `CapaQuery` to type the builder, as with `createClient`:
+ * `draftClient<CapaQuery>({ ... })`. `production` may hold the legacy key a
+ * site already has; `draft` needs a `cap_` key, and a legacy one throws a
+ * `TypeError` when draft mode selects it.
+ */
 async function draftClient(input) {
-    return (0, next_1.createClient)((await input.isDraft()) ? input.draft : input.production);
+    if (!(await input.isDraft()))
+        return (0, next_1.createClient)(input.production);
+    (0, key_family_1.requireDraftKey)(input.draft?.apiKey, "the draft config");
+    return (0, next_1.createClient)(input.draft);
 }
 // ------------------------------------------------------------------ pages ---
 /**
@@ -233,7 +308,11 @@ exports.EDIT_CACHE_CONTROL = "private, no-store";
  */
 async function editMode(input) {
     const [draft, headers] = await Promise.all([input.draftMode(), input.headers()]);
-    return draft.isEnabled === true || headers.get(exports.EDIT_HEADER) === "1";
+    return draft.isEnabled === true || verifiedEdit(headers);
+}
+/** Whether `resolveEditRequest` verified a `capa-edit` token for this request. */
+function verifiedEdit(headers) {
+    return headers.get(exports.EDIT_HEADER) === "1";
 }
 /**
  * The middleware half of edit mode.
@@ -271,51 +350,196 @@ async function resolveEditRequest(request, client) {
     return { edit, verified, headers, cacheControl: edit ? exports.EDIT_CACHE_CONTROL : null };
 }
 // ------------------------------------------------- five-minute integration ---
-/** Where the env-driven helpers read their settings (M6). */
+/**
+ * Where the env-driven helpers read their settings (M6): the one pair of
+ * names the whole product uses (the MCP server, `capa-codegen`, `capa
+ * persist`, every curl example in the API docs).
+ */
 exports.CAPA_ENV = {
     baseUrl: "CAPA_API_URL",
     apiKey: "CAPA_KEY",
     draftKey: "CAPA_DRAFT_KEY",
     version: "CAPA_API_VERSION",
 };
+/** Older names that still work, read only when the name above is unset. */
+exports.CAPA_ENV_ALIASES = {
+    CAPA_API_URL: "CAPA_BASE_URL",
+    CAPA_KEY: "CAPA_API_KEY",
+};
 exports.DEFAULT_API_VERSION = "2026-10-01";
-function readEnv(name) {
+function readOne(name) {
     const env = globalThis.process?.env;
     const value = env?.[name];
     return value === undefined || value === "" ? undefined : value;
 }
+function readEnv(name) {
+    const alias = exports.CAPA_ENV_ALIASES[name];
+    return readOne(name) ?? (alias ? readOne(alias) : undefined);
+}
 function requireEnv(name) {
     const value = readEnv(name);
-    if (!value)
-        throw new Error(`@capacms/sdk/nextjs: ${name} is not set.`);
-    return value;
+    if (value)
+        return value;
+    const alias = exports.CAPA_ENV_ALIASES[name];
+    throw new Error(`@capacms/sdk/nextjs: ${name} is not set${alias ? ` (${alias} also works)` : ""}.`);
 }
-/** The published-key client from env: what verifying a token needs. */
+/**
+ * A client config from env, `key` naming the env var for the key. A setting
+ * `config` gives is used as given and its env var is never read, so a full
+ * `config` needs no env at all.
+ */
+function envConfig(config, key) {
+    return {
+        ...config,
+        baseUrl: config?.baseUrl ?? requireEnv(exports.CAPA_ENV.baseUrl),
+        apiKey: config?.apiKey ?? requireEnv(key),
+        version: config?.version ?? readEnv(exports.CAPA_ENV.version) ?? exports.DEFAULT_API_VERSION,
+    };
+}
+/** The published or the draft config from env; the draft key must be a `cap_` key. */
+function modeConfig(config, draft) {
+    if (!draft)
+        return envConfig(config, exports.CAPA_ENV.apiKey);
+    const settings = envConfig(config, exports.CAPA_ENV.draftKey);
+    (0, key_family_1.requireDraftKey)(settings.apiKey, config?.apiKey !== undefined ? "config.apiKey" : exports.CAPA_ENV.draftKey);
+    return settings;
+}
+/**
+ * The published-key client from env: what verifying a token needs. `overrides`
+ * win over env, and pass codegen's `CapaQuery` to type the builder:
+ * `getPublishedClient<CapaQuery>()`.
+ */
 function getPublishedClient(overrides = {}) {
-    return (0, next_1.createClient)({
-        baseUrl: requireEnv(exports.CAPA_ENV.baseUrl),
-        apiKey: requireEnv(exports.CAPA_ENV.apiKey),
-        version: readEnv(exports.CAPA_ENV.version) ?? exports.DEFAULT_API_VERSION,
-        ...overrides,
-    });
+    return (0, next_1.createClient)(envConfig(overrides, exports.CAPA_ENV.apiKey));
 }
 /**
  * The client for this request, from env: the draft key under draft mode,
  * otherwise the published key, and `editMode` worked out for you.
  *
  *   import { draftMode, headers } from "next/headers";
- *   const capa = await getCapaClient({ draftMode, headers });
+ *   const capa = await getCapaClient<CapaQuery>({ draftMode, headers });
+ *   const { data } = await capa.graphql.query(selection, { tags: tagsFor({ namespace: "articles" }) });
+ *
+ * `CapaQuery` (from `capa-codegen --graphql`) types the builder, as with
+ * `createClient`; leave it out for an untyped client. `config` wins over env.
+ *
+ * Its GraphQL reads, a document or the builder, are kept in Next's data cache
+ * exactly as `graphql()` keeps them, each under the `tags` and `revalidate`
+ * it is called with: a published read with no errors, never a draft or an
+ * edit-mode page. Its REST reads are sent as `createClient` sends them.
  */
 async function getCapaClient(input) {
     const draft = (await input.draftMode()).isEnabled === true;
     const edit = await editMode({ draftMode: input.draftMode, headers: input.headers });
-    return (0, next_1.createClient)({
-        baseUrl: requireEnv(exports.CAPA_ENV.baseUrl),
-        apiKey: requireEnv(draft ? exports.CAPA_ENV.draftKey : exports.CAPA_ENV.apiKey),
-        version: readEnv(exports.CAPA_ENV.version) ?? exports.DEFAULT_API_VERSION,
+    const settings = modeConfig(input.config, draft);
+    const client = (0, next_1.createClient)({ editMode: edit, ...settings });
+    const read = { draft, edit, settings, given: input.unstable_cache };
+    const graphql = (0, client_1.graphqlClient)((document, variables, options = {}) => {
+        const { tags, revalidate, ...call } = options;
+        return readInNext(read, document, variables, call, { tags, revalidate });
+    });
+    return { ...client, graphql };
+}
+let loadedUnstableCache;
+/**
+ * Next's own `unstable_cache`, loaded on first use, or null where `next/cache`
+ * cannot be loaded (Next not installed). The package never imports `next/*`
+ * at the top, so a Node script can import this file without Next.
+ */
+function nextUnstableCache() {
+    if (loadedUnstableCache === undefined) {
+        try {
+            loadedUnstableCache = require("next/cache").unstable_cache ?? null;
+        }
+        catch {
+            loadedUnstableCache = null;
+        }
+    }
+    return loadedUnstableCache;
+}
+/** Thrown inside `unstable_cache` so that a result with errors is never stored; caught at once. */
+class NotCached extends Error {
+    result;
+    constructor(result) {
+        super(`@capacms/sdk/nextjs: this GraphQL read answered with errors, so it was not cached: ${result.errors[0]?.message ?? "unknown error"}`);
+        this.result = result;
+        this.name = "NotCached";
+    }
+}
+/**
+ * What a cached read is keyed by: everything that changes its answer. The key
+ * is hashed, so the API key never reaches the cache's index.
+ */
+async function cacheKeyOf(settings, document, variables, call) {
+    return [
+        "@capacms/sdk/nextjs graphql",
+        settings.baseUrl,
+        await (0, sha256_1.sha256Hex)(settings.apiKey),
+        settings.version ?? "",
+        String(settings.contract ?? ""),
+        settings.schemaChecksum ?? "",
+        document,
+        JSON.stringify(variables ?? null),
+        call.operationName ?? "",
+        call.persisted ? "persisted" : "",
+        call.method ?? "",
+    ];
+}
+async function graphql(document, variables, options = {}) {
+    const { tags, revalidate, draft: draftOption, draftMode, headers, config, unstable_cache: given, ...call } = options;
+    const draft = draftOption ?? (draftMode ? (await draftMode()).isEnabled === true : false);
+    const edit = draft || (headers ? verifiedEdit(await headers()) : false);
+    const read = { draft, edit, settings: modeConfig(config, draft), given };
+    return readInNext(read, document, variables, call, { tags, revalidate });
+}
+/**
+ * One GraphQL read in Next, for `graphql()` and `getCapaClient`. Next's data
+ * cache holds only a published read with no errors, and the fetch under it is
+ * never cached. A draft, an edit-mode read (its entries carry marks a cached
+ * copy would lose) and `revalidate: 0` are not cached.
+ */
+async function readInNext(read, document, variables, call, { tags, revalidate }) {
+    const { draft, edit, settings, given } = read;
+    const baseFetch = settings.fetch ?? globalThis.fetch;
+    const cache = given ?? nextUnstableCache();
+    if (cache && !draft) {
+        if (edit || revalidate === 0) {
+            return (0, next_1.createClient)({ editMode: edit, ...settings, fetch: withCache(baseFetch, { revalidate: 0 }) }).graphql(document, variables, call);
+        }
+        const client = (0, next_1.createClient)({ editMode: false, ...settings, fetch: baseFetch });
+        let sent = false;
+        const send = async () => {
+            sent = true;
+            const result = await client.graphql(document, variables, call);
+            if (result.errors.length > 0)
+                throw new NotCached(result);
+            return result;
+        };
+        const keyParts = await cacheKeyOf(settings, document, variables, call);
+        const cacheOptions = { tags: tags ?? [exports.GRAPHQL_TAG] };
+        if (revalidate !== undefined)
+            cacheOptions.revalidate = revalidate;
+        try {
+            return await cache(send, keyParts, cacheOptions)();
+        }
+        catch (error) {
+            if (error instanceof NotCached)
+                return error.result;
+            // Next's own `unstable_cache` throws before it reads anything outside a
+            // Next request (a script, a test, a build step with no cache): the read
+            // is then sent as below. One passed in throws as it did.
+            if (given || sent)
+                throw error;
+        }
+    }
+    const client = (0, next_1.createClient)({
         editMode: edit,
-        ...input.config,
+        ...settings,
+        fetch: draft
+            ? withCache(baseFetch, { revalidate: 0 })
+            : withCache(baseFetch, { tags: tags ?? [exports.GRAPHQL_TAG], revalidate }),
     });
+    return client.graphql(document, variables, call);
 }
 /** Only a path on this site: never `//elsewhere.example` or a full URL. */
 function safeSitePath(value) {

package/dist/nextjs/overlay.d.ts

@@ -0,0 +1,5 @@
+export interface CapaOverlayProps {
+    /** The Capa admin origins allowed to drive the overlay. */
+    adminOrigins: string[];
+}
+export declare function CapaOverlay({ adminOrigins }: CapaOverlayProps): null;

package/dist/nextjs/overlay.js

@@ -0,0 +1,35 @@
+"use strict";
+"use client";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapaOverlay = CapaOverlay;
+/**
+ * `<CapaOverlay />`: Capa's live preview overlay as one Next.js client
+ * component (M6).
+ *
+ *   // app/layout.tsx (a server component)
+ *   import { CapaOverlay } from "@capacms/sdk/nextjs/overlay";
+ *   {edit ? <CapaOverlay adminOrigins={["https://app.capacms.com"]} /> : null}
+ *
+ * Render it only in edit mode (`editMode()` from `@capacms/sdk/nextjs`), so a
+ * visitor never downloads it. Inside the Capa editor it outlines the focused
+ * field, reports clicks back, and on a save re-renders the page with
+ * `router.refresh()`, keeping the scroll position. Outside a Capa frame it does
+ * nothing at all.
+ *
+ * Its own entry point, apart from `@capacms/sdk/nextjs`, because it imports
+ * `react` and `next/navigation` and is a client module: the server helpers must
+ * stay free of both.
+ */
+const react_1 = require("react");
+const navigation_1 = require("next/navigation");
+const overlay_1 = require("../overlay");
+function CapaOverlay({ adminOrigins }) {
+    const router = (0, navigation_1.useRouter)();
+    // A string, so a new array with the same origins does not restart it.
+    const origins = adminOrigins.join(",");
+    (0, react_1.useEffect)(() => (0, overlay_1.startOverlay)({
+        adminOrigins: origins.split(",").filter(Boolean),
+        onRefresh: () => router.refresh(),
+    }), [origins, router]);
+    return null;
+}

package/package.json

@@ -1,16 +1,9 @@
 {
   "name": "@capacms/sdk",
-  "version": "1.0.0-next.4",
+  "version": "1.0.0-next.6",
+  "description": "The TypeScript SDK for Capa's content API: REST and GraphQL reads typed from your models, Next.js caching and live preview, and codegen.",
   "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ZVN-DEV/capa-cms-future.git",
-    "directory": "packages/sdk"
-  },
-  "homepage": "https://github.com/ZVN-DEV/capa-cms-future/tree/main/packages/sdk#readme",
-  "bugs": {
-    "url": "https://github.com/ZVN-DEV/capa-cms-future/issues"
-  },
+  "homepage": "https://docs.capacms.com/api",
   "engines": {
     "node": ">=18"
   },
@@ -18,7 +11,8 @@
   "files": [
     "dist",
     "bin",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -43,7 +37,11 @@
       "types": "./dist/overlay/index.d.ts",
       "default": "./dist/overlay/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./nextjs/overlay": {
+      "types": "./dist/nextjs/overlay.d.ts",
+      "default": "./dist/nextjs/overlay.js"
+    }
   },
   "typesVersions": {
     "*": {
@@ -56,21 +54,45 @@
       "overlay": [
         "dist/overlay/index.d.ts"
       ],
+      "nextjs/overlay": [
+        "dist/nextjs/overlay.d.ts"
+      ],
       "*": [
         "dist/index.d.ts"
       ]
     }
   },
   "bin": {
+    "capa": "bin/capa.js",
     "capa-codegen": "bin/capa-codegen.js"
   },
+  "peerDependencies": {
+    "graphql": "^16.9.0",
+    "next": ">=14",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "graphql": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "graphql": "^16.9.0",
     "typescript": "^5.5.0",
+    "@types/react": "19.0.1",
+    "next": "15.5.9",
+    "react": "19.2.8",
     "@capa/shared": "0.1.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsc -p tsconfig.json && node --test test/codegen.test.js test/client.test.js test/next-client.test.js test/nextjs.test.js test/webhooks.test.js test/attrs.test.js test/overlay.test.js test/inflate.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit"
+    "test": "tsc -p tsconfig.json && node --test test/comments.test.js test/codegen.test.js test/client.test.js test/next-client.test.js test/nextjs.test.js test/webhooks.test.js test/attrs.test.js test/overlay.test.js test/inflate.test.js test/field-names.test.js test/next-graphql.test.js test/graphql-codegen.test.js test/graphql-contract.test.js test/readme-snippets.test.js test/nextjs-app.test.js test/package-json.test.js test/changelog.test.js test/published-docs.test.js test/builder-messages.test.js && tsc -p test/types/tsconfig.consumer.json --noEmit && tsc -p test/types/tsconfig.nonstrict.json --noEmit"
   }
 }