canopycms 0.0.67 → 0.0.68-int.94

package/README.md

@@ -104,6 +104,7 @@ export default defineCanopyConfig({
       colors: { brand: '#4f46e5' },
     },
     // previewBase: { 'content/posts': '/blog' }, // optional overrides
+    // previewPrefix: '/preview', // optional, in front of every preview URL
   },
   // For prod mode, defaultRemoteUrl is required.
   // For dev, it's optional - if omitted, uses auto-initialized local remote at .canopy-dev/remote.git
@@ -323,7 +324,7 @@ name) works, but leaves the entry's real `urlPath` as
 URL-derived surface then has to be told about one at a time. The example app in this repo used to
 do that and no longer does.
 
-Both methods return `{ data, path }`. `read` throws if the content is missing; `readByUrlPath` returns `null` instead. Pass a `branch` option when you want branch-specific data (e.g., for preview); otherwise it defaults to your configured base branch. Both enforce the same branch/path access rules as the API handlers.
+Both methods return `{ data, path }`. `read` throws if the content is missing; `readByUrlPath` returns `null` instead. Pass a `branch` option when you want branch-specific data (e.g., for preview); otherwise it defaults to the active branch: `defaultActiveBranch`, or when that is unset, git HEAD in `dev` and your base branch in `prod`. Any other branch must already exist and be readable by the current user, or it reads as not found. Both enforce the same branch/path access rules as the API handlers.
 
 **Index entries and URL resolution**
 
@@ -401,7 +402,7 @@ _TODO_ show real examples of what to do
 
 ### Preview branch awareness
 
-- When building preview URLs, include the current branch as a query param (e.g., `/?branch=feature-foo` or `/posts/hello?branch=feature-foo`) so SSR preview pages read from the same branch workspace the editor is editing. The `Editor` component appends the branch param automatically to `previewBaseByCollection`; your page loaders should read `searchParams.branch` and pass it into `createContentReader`.
+- When building preview URLs, include the current branch as a query param (e.g., `/?branch=feature-foo` or `/posts/hello?branch=feature-foo`) so SSR preview pages read from the same branch workspace the editor is editing. The `Editor` component appends the branch param automatically to `previewBaseByCollection`; your page loaders should read `searchParams.branch` and pass it as the `branch` option to `getCanopy()`'s `read`/`readByUrlPath`.
 - For public static builds, omit/ignore the branch param; this pattern is only for the editor/preview environment.
 - Likewise, include `branch` in your editor route (e.g., `/edit?branch=feature-foo`) and have your editor page pass it to `<Editor>` so reloads/links preserve the selected branch. The `Editor` will also reflect branch switches back into the query string.
 

package/dist/ai/handler.js

@@ -13,6 +13,7 @@
 import { ContentStore } from '../content-store.js';
 import { BranchSchemaCache } from '../branch-schema-cache.js';
 import { getErrorMessage } from '../utils/error.js';
+import { workerNotReadyResponse } from '../http/worker-not-ready.js';
 import { generateAIContent } from './generate.js';
 import { resolveBranchRoot } from './resolve-branch.js';
 /**
@@ -76,6 +77,13 @@ export function createAIContentHandler(options) {
         catch (error) {
             // Log the real error server-side; don't leak internals to unauthenticated callers
             console.error('AI content handler error:', getErrorMessage(error));
+            const notReady = workerNotReadyResponse(error);
+            if (notReady) {
+                return new Response(JSON.stringify({ error: notReady.body.error }), {
+                    status: notReady.status,
+                    headers: { 'Content-Type': 'application/json', ...notReady.headers },
+                });
+            }
             return new Response(JSON.stringify({ error: 'Internal server error' }), {
                 status: 500,
                 headers: { 'Content-Type': 'application/json' },

package/dist/api/admin-branch-health.js

@@ -22,7 +22,7 @@ import { ContentIdIndex } from '../content-id-index.js';
 import { invalidateContentIndexesDurable } from '../content-index-generation.js';
 import { getDefaultBranchBase, sanitizeBranchName } from '../paths/index.js';
 import { withOccFileLock } from '../utils/occ-json-write.js';
-import { tryAcquireProvisioningLock } from '../utils/provisioning-lock.js';
+import { branchProvisioningLockName, tryAcquireProvisioningLock } from '../utils/provisioning-lock.js';
 import { withContentWriteLock, ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, } from '../utils/content-write-lock.js';
 import { getErrorMessage, isNodeError, isNotFoundError } from '../utils/error.js';
 import { defineEndpoint } from './route-builder.js';
@@ -147,12 +147,17 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
     // True orphan (no branch.json, no load error) vs. corrupt-metadata
     // (loadOnly threw). Only true orphans are subject to the youth rail below.
     const isTrueOrphan = !hadLoadError;
-    // [H1] freshness rail: a fresh init lock means provisioning may genuinely
-    // be in progress; a stale one is just crash debris and does not block.
-    const lockPath = path.join(baseRoot, `.${params.dirName}.init.lock`);
+    // [H1] freshness rail: a fresh init lock means provisioning, or the worker's
+    // sync of this branch, may genuinely be in progress; a stale one is just
+    // crash debris and does not block.
+    const lockPath = path.join(baseRoot, branchProvisioningLockName(params.dirName));
     const lockStat = await fs.stat(lockPath).catch(() => null);
     if (lockStat && Date.now() - lockStat.mtimeMs < PROVISIONING_LOCK_FRESH_MS) {
-        return { ok: false, status: 409, error: 'Provisioning may be in progress' };
+        return {
+            ok: false,
+            status: 409,
+            error: 'Provisioning, or the worker syncing this branch, may be in progress',
+        };
     }
     // Youth rail: a brand-new orphan dir may be a clone that just hasn't
     // written branch.json yet. Corrupt-metadata dirs are exempt -- a
@@ -171,7 +176,7 @@ const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
     // contention instead of hanging the request for ~5 minutes.
     let releaseProvisioningLock;
     try {
-        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, `.${params.dirName}.init.lock`);
+        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, branchProvisioningLockName(params.dirName));
     }
     catch (err) {
         if (isNodeError(err) && err.code === 'ELOCKED') {
@@ -279,7 +284,7 @@ const repairBranchDirHandler = async (_gc, ctx, req, params) => {
     // Held until the `finally` below, AFTER save() completes.
     let releaseProvisioningLock;
     try {
-        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, `.${params.dirName}.init.lock`);
+        releaseProvisioningLock = await tryAcquireProvisioningLock(baseRoot, branchProvisioningLockName(params.dirName));
     }
     catch (err) {
         if (isNodeError(err) && err.code === 'ELOCKED') {

package/dist/api/admin.d.ts

@@ -8,7 +8,7 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
 import type { Task, QueueStats, CorruptTaskFile } from '../task-queue/cms-task-queue.js';
-import type { WorkerStatusReport } from '../types.js';
+import type { BuildIdentity, WorkerStatusReport } from '../types.js';
 import type { OperatingMode } from '../operating-mode/index.js';
 export type { BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse, } from './admin-branch-health.js';
 type WorkerLivenessState = 'alive' | 'stale' | 'absent';
@@ -31,6 +31,18 @@ export interface AdminStatusData {
     worker: WorkerLiveness;
     workerStatus: WorkerStatusReport | null;
     statusReadError?: string;
+    /**
+     * Why this process cannot provision the settings workspace (groups and path rules), when it
+     * cannot. Its requests that resolve a user answer 503 meanwhile; bootstrap admins still reach
+     * /admin.
+     */
+    settingsWorkspaceError?: string;
+    /** Build of the API process answering this request. */
+    build: BuildIdentity;
+    /** Whether `media` is configured; without it every upload returns 501. */
+    assetStore: {
+        configured: boolean;
+    };
 }
 /** Response type for GET /admin/status */
 export type AdminStatusResponse = ApiResponse<AdminStatusData>;
@@ -54,10 +66,10 @@ declare const listAdminTasksParamsSchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
     limit: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+    status: "failed" | "pending" | "processing" | "completed" | "corrupt";
     limit?: number | undefined;
 }, {
-    status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+    status: "failed" | "pending" | "processing" | "completed" | "corrupt";
     limit?: number | undefined;
 }>;
 export type ListAdminTasksParams = z.infer<typeof listAdminTasksParamsSchema>;
@@ -65,10 +77,10 @@ declare const deleteTaskParamsSchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "failed", "corrupt"]>;
     fileName: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
-    status: "pending" | "failed" | "corrupt";
+    status: "failed" | "pending" | "corrupt";
     fileName: string;
 }, {
-    status: "pending" | "failed" | "corrupt";
+    status: "failed" | "pending" | "corrupt";
     fileName: string;
 }>;
 export type DeleteTaskParams = z.infer<typeof deleteTaskParamsSchema>;
@@ -108,10 +120,10 @@ export declare const ADMIN_ROUTES: {
         status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
         limit: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+        status: "failed" | "pending" | "processing" | "completed" | "corrupt";
         limit?: number | undefined;
     }, {
-        status: "pending" | "processing" | "completed" | "failed" | "corrupt";
+        status: "failed" | "pending" | "processing" | "completed" | "corrupt";
         limit?: number | undefined;
     }>, undefined, AdminTasksResponse>;
     readonly retryTask: import("./route-builder.js").RouteDefinition<z.ZodObject<{
@@ -125,10 +137,10 @@ export declare const ADMIN_ROUTES: {
         status: z.ZodEnum<["pending", "failed", "corrupt"]>;
         fileName: z.ZodEffects<z.ZodString, string, string>;
     }, "strip", z.ZodTypeAny, {
-        status: "pending" | "failed" | "corrupt";
+        status: "failed" | "pending" | "corrupt";
         fileName: string;
     }, {
-        status: "pending" | "failed" | "corrupt";
+        status: "failed" | "pending" | "corrupt";
         fileName: string;
     }>, undefined, AdminDeleteTaskResponse>;
 };

package/dist/api/admin.js

@@ -12,7 +12,8 @@ import { getQueueStats, listTasks, listCorruptTaskFiles, requeueFailedTask, } fr
 import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
 import { WORKER_STATUS_FILE } from '../task-queue/worker-status.js';
 import { defineEndpoint } from './route-builder.js';
-import { getErrorMessage, isNotFoundError } from '../utils/error.js';
+import { getErrorMessage, isNotFoundError, redactCredentials } from '../utils/error.js';
+import { getBuildIdentity } from '../build-identity.js';
 import { ADMIN_BRANCH_HEALTH_ROUTES } from './admin-branch-health.js';
 /**
  * 60_000 = DEFAULT_LOCK_STALE_MS in worker/cms-worker.ts, hardcoded rather
@@ -72,6 +73,15 @@ async function readWorkerStatus(taskDir) {
         return { workerStatus: null, statusReadError: getErrorMessage(err) };
     }
 }
+async function readSettingsWorkspaceError(ctx) {
+    try {
+        await ctx.services.getSettingsBranchRoot();
+        return undefined;
+    }
+    catch (err) {
+        return redactCredentials(getErrorMessage(err));
+    }
+}
 /** Age (ms) of the oldest file in pending/, or undefined if empty/missing. */
 async function getOldestPendingAgeMs(taskDir) {
     const pendingDir = path.join(taskDir, 'pending');
@@ -126,11 +136,12 @@ const deleteTaskParamsSchema = z.object({
 const getAdminStatusHandler = async (_gc, ctx, _req) => {
     const taskDir = getTaskQueueDir(ctx.services.config);
     try {
-        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }] = await Promise.all([
+        const [queueStats, oldestPendingAgeMs, worker, { workerStatus, statusReadError }, settingsWorkspaceError,] = await Promise.all([
             getQueueStats(taskDir),
             getOldestPendingAgeMs(taskDir),
             classifyWorkerLiveness(taskDir),
             readWorkerStatus(taskDir),
+            readSettingsWorkspaceError(ctx),
         ]);
         return {
             ok: true,
@@ -145,6 +156,9 @@ const getAdminStatusHandler = async (_gc, ctx, _req) => {
                 worker,
                 workerStatus,
                 ...(statusReadError ? { statusReadError } : {}),
+                ...(settingsWorkspaceError ? { settingsWorkspaceError } : {}),
+                build: getBuildIdentity(),
+                assetStore: { configured: !!ctx.assetStore },
             },
         };
     }
@@ -255,6 +269,8 @@ const getAdminStatus = defineEndpoint({
         queue: { pending: 0, processing: 0, completed: 0, failed: 0, corrupt: 0 },
         worker: { state: 'absent' },
         workerStatus: null,
+        build: { canopycmsVersion: '0.0.0' },
+        assetStore: { configured: false },
     },
     guards: ['admin'],
     handler: getAdminStatusHandler,

package/dist/api/branch-status.js

@@ -8,6 +8,8 @@ import { canPerformWorkflowAction, getBranchProtection } from '../authorization/
 import { syncSubmitPr } from './github-sync.js';
 import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../utils/error.js';
 import { isNonFastForwardRejection } from '../utils/git.js';
+import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
+import { submissionEditorFromUser } from '../submission-attribution.js';
 const getBranchStatusHandler = async (gc, _ctx, _req, _params) => {
     const { branchContext } = gc;
     return { ok: true, status: 200, data: { branch: branchContext.branch } };
@@ -49,10 +51,24 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         };
     }
     // Commit and push changes
+    const submitter = submissionEditorFromUser(req.user);
+    let changedPaths;
     try {
-        await ctx.services.submitBranch({ context: branchContext });
+        ;
+        ({ changedPaths } = await ctx.services.submitBranch({ context: branchContext, submitter }));
     }
     catch (err) {
+        // Retriable either way: a resubmit commits nothing new and pushes only
+        // what has not reached the remote.
+        if (err instanceof ContentWriteLockBusyError) {
+            return {
+                ok: false,
+                status: 409,
+                error: err.outcome === 'not-run'
+                    ? `Could not submit "${branchContext.branch.name}" right now: it is being synced with its base branch, or a save is in flight. Nothing was submitted; try again in a moment.`
+                    : `"${branchContext.branch.name}" was being synced while it was submitted, so the submit may not have completed. Try submitting again.`,
+            };
+        }
         const message = getErrorMessage(err);
         // Full path detail (including branchRoot, an absolute path) to server logs
         // only; the client only ever sees the sanitized form (API-H2). Credentials
@@ -62,8 +78,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         // A non-fast-forward rejection means this branch and the deployment's
         // local repository have diverged. Retrying the identical push can never
         // succeed (see isNonFastForwardRejection), so surface 409 instead of the
-        // generic 500 below. Everything else (network, auth, lock contention)
-        // keeps the existing 500 path unchanged.
+        // generic 500 below. Everything else (network, auth) keeps the 500 path.
         //
         // This push targets the deployment's OWN local origin (remote.git), not
         // GitHub, so the message deliberately states only the observable fact and
@@ -91,7 +106,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         };
     }
     // Create or update PR (sync via githubService, or async via task queue)
-    const prResult = await syncSubmitPr(ctx, branchContext);
+    const prResult = await syncSubmitPr(ctx, branchContext, { submitter, changedPaths });
     // Update metadata with status and PR info
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
     const updated = await meta.save({

package/dist/api/branch.js

@@ -10,7 +10,7 @@ import { clientOperatingStrategy } from '../operating-mode/index.js';
 import { isNotFoundError, getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
 import { filePathExists } from '../utils/fs.js';
 import { isNetworkRemoteUrl } from '../utils/git.js';
-import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, } from '../paths/index.js';
+import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from '../paths/index.js';
 import { GitManager } from '../git-manager.js';
 import { branchNameSchema, branchParamSchema } from './validators.js';
 const log = createDebugLogger({ prefix: 'BranchAPI' });
@@ -95,15 +95,12 @@ export const createBranchHandler = async (ctx, req, body) => {
             branchName,
             userId: req.user.userId,
         });
-        // Scope note: the collision guards below (settings-branch collision,
-        // reserved canopycms-settings- prefix, and the remote-mirror check
-        // further down) apply ONLY to this user-facing creation path.
-        // http/handler.ts's auto-create (base/active/settings branches) and
-        // branch-workspace.ts's loadOrCreateBranchContext (reached from run-time
-        // content reads and the AI pipeline; build-time reads return the checkout
-        // and never provision) provision system/known branch names, not
-        // user-chosen ones, and deliberately stay uncovered -- intentional, not
-        // an oversight.
+        // Scope note: the remote-mirror check further down applies ONLY to this
+        // user-facing creation path; http/handler.ts's auto-create (base/active
+        // branches) and loadOrCreateBranchContext provision known names. The two
+        // settings-branch checks below give this path a specific 400; every
+        // provisioning path, this one included, also refuses a settings branch in
+        // BranchWorkspaceManager.openOrCreateBranch.
         // Prevent git branch name collision with the settings branch. Settings
         // live in a separate directory but share the same git remote, and
         // openOrCreateBranch (branch-workspace.ts) uses the SANITIZED name as the
@@ -337,7 +334,10 @@ export const listBranchesHandler = async (ctx, req) => {
             error: 'Branch registry not initialized — ensure the workspace has been initialized',
         };
     }
-    const allBranches = await ctx.services.registry.list();
+    // A settings-branch workspace is never resolvable as a content branch (see
+    // http/handler.ts), so one left on disk is hidden rather than listed unopenable.
+    const settingsBranch = operatingStrategy(ctx.services.config.mode).getSettingsBranchName(ctx.services.config);
+    const allBranches = (await ctx.services.registry.list()).filter((context) => !isSettingsBranchName(context.branch.name, settingsBranch));
     // The branch the editor should open when none is pinned via URL/config.
     // Read per-request so dev-mode refreshActiveBranch() updates are reflected.
     // Sanitized: dev mode detects the RAW git HEAD name (e.g. 'claude/foo'),

package/dist/api/client.d.ts

@@ -25,6 +25,12 @@ export interface ApiClientOptions {
     baseUrl?: string;
     /** Custom fetch implementation, e.g. a mock in tests. */
     fetch?: typeof fetch;
+    /**
+     * End request paths with `/` (by `withTrailingSlash`'s rule), matching a Next host built with
+     * `trailingSlash: true`. Defaults to the value `withCanopy` inlines at build time (see
+     * `readTrailingSlashEnv`), else false.
+     */
+    trailingSlash?: boolean;
     /**
      * Called whenever a response comes back 401: the credential is no longer accepted. A
      * notification, not a retry; the editor's auth gate uses it to show sign-in.
@@ -44,6 +50,7 @@ export interface ApiClientOptions {
 export declare class CanopyApiClient {
     private baseUrl;
     private fetchFn;
+    private trailingSlash;
     private onUnauthorized;
     readonly branches: {
         /** GET /branches */
@@ -179,5 +186,10 @@ export declare class CanopyApiClient {
     private buildPath;
     private request;
 }
+/**
+ * Whether `result` was converted from a body no CanopyCMS handler wrote (a proxy or CDN
+ * error page), so its status says nothing about the API itself.
+ */
+export declare function isNonApiResponse(result: object): boolean;
 /** Create a {@link CanopyApiClient}; pass a custom fetch for tests. */
 export declare function createApiClient(options?: ApiClientOptions): CanopyApiClient;

package/dist/api/client.js

@@ -6,6 +6,7 @@
  * (changes will be overwritten), edit the generator's templates instead.
  */
 import { computeContentSha256Hex } from './request-body-hash.js';
+import { readTrailingSlashEnv, withTrailingSlash } from '../utils/url-prefix.js';
 /**
  * Typed client for the CanopyCMS API: one method per endpoint, grouped by namespace, each
  * returning that endpoint's ApiResponse.
@@ -260,6 +261,7 @@ export class CanopyApiClient {
         this.baseUrl = options.baseUrl ?? '/api/canopycms';
         // An unbound fetch throws "Illegal invocation" in browsers; Node has no window.
         this.fetchFn = options.fetch ?? (typeof window !== 'undefined' ? fetch.bind(window) : fetch);
+        this.trailingSlash = options.trailingSlash ?? readTrailingSlashEnv();
         this.onUnauthorized = options.onUnauthorized;
     }
     buildPath(template, params) {
@@ -292,7 +294,7 @@ export class CanopyApiClient {
         return result;
     }
     async request(method, path, body, headers = {}) {
-        const url = `${this.baseUrl}${path}`;
+        const url = `${this.baseUrl}${this.trailingSlash ? withTrailingSlash(path) : path}`;
         const requestHeaders = {
             ...headers,
         };
@@ -325,21 +327,42 @@ export class CanopyApiClient {
             init.body = requestBody;
         }
         const response = await this.fetchFn(url, init);
+        // A body from in front of the API (a proxy or CDN error page) may be empty, not JSON, or
+        // not an ApiResponse; every such body becomes an `ok: false` ApiResponse, never a throw.
+        const parsed = await response.json().catch(() => undefined);
         if (response.status === 401) {
             this.onUnauthorized?.();
-            // A 401 is an auth answer whatever its body: one from in front of the API (a proxy) may
-            // not be an ApiResponse, or not JSON. Always return it as one rather than throwing.
-            const body = await response.json().catch(() => undefined);
-            const error = typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string'
-                ? body.error
-                : 'Unauthorized';
-            return { ok: false, status: 401, error };
+            return { ok: false, status: 401, error: errorFromBody(parsed) ?? 'Unauthorized' };
         }
-        const payload = await response.json();
-        // All responses use ApiResponse format: { ok, status, data?, error? }
-        return payload;
+        if (isApiResponseBody(parsed))
+            return parsed;
+        const converted = {
+            ok: false,
+            status: response.status,
+            error: errorFromBody(parsed) ?? `Unexpected response from server (HTTP ${response.status})`,
+        };
+        convertedResponses.add(converted);
+        return converted;
     }
 }
+const convertedResponses = new WeakSet();
+/**
+ * Whether `result` was converted from a body no CanopyCMS handler wrote (a proxy or CDN
+ * error page), so its status says nothing about the API itself.
+ */
+export function isNonApiResponse(result) {
+    return convertedResponses.has(result);
+}
+/** The `error` string of a JSON body, when it has one. */
+function errorFromBody(body) {
+    return typeof body === 'object' && body !== null && 'error' in body && typeof body.error === 'string'
+        ? body.error
+        : undefined;
+}
+/** Whether a parsed body has the `{ ok, status, ... }` shape every handler returns. */
+function isApiResponseBody(body) {
+    return typeof body === 'object' && body !== null && 'ok' in body && typeof body.ok === 'boolean';
+}
 /** Create a {@link CanopyApiClient}; pass a custom fetch for tests. */
 export function createApiClient(options) {
     return new CanopyApiClient(options);

package/dist/api/content.d.ts

@@ -40,11 +40,12 @@ export interface WriteContentBody {
     data?: Record<string, unknown>;
     body?: string;
     /**
-     * OCC / create-intent token. Omit for a blind write (no opinion). A number
-     * from a prior read/write response rejects the write with 409 if the file
-     * has changed since. `null` means "this entry must not already exist" —
-     * the create path uses this so a create against an existing slug is
-     * rejected with 409 instead of silently overwriting it.
+     * OCC token. A number from a prior read/write response makes this an update,
+     * rejected with 409 if the file's mtime no longer matches (a file deleted
+     * since is written anew). `null` or omitted makes it
+     * a create, rejected with 409 if the entry already exists. There is no blind
+     * write: without a token, "no conflict detection" would be indistinguishable
+     * from "lost the token", so an update has to prove which version it read.
      */
     expectedVersion?: number | null;
 }