canopycms 0.0.68-int.98 → 0.1.0

package/dist/api/permissions.js

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { loadPermissionsFile, mutatePermissionsFile, loadGroupsFile, deriveInternalGroups, SettingsVersionConflictError, SettingsFileConflictError, } from '../authorization/index.js';
 import { permissionPathSchema } from './validators.js';
 import { MAX_ENTRIES_PER_PAGE } from './entries-constants.js';
+import { MAX_USER_METADATA_BATCH } from './users-constants.js';
+import { lookupUsersMetadata } from '../auth/user-metadata-lookup.js';
 import { defineEndpoint } from './route-builder.js';
 import { getSettingsBranchContext, commitSettings } from './settings-helpers.js';
 import { getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
@@ -29,6 +31,10 @@ const searchUsersParamsSchema = z.object({
 const getUserMetadataParamsSchema = z.object({
     userId: z.string(),
 });
+const userIdSchema = z.string().min(1).max(256);
+const batchGetUserMetadataBodySchema = z.object({
+    userIds: z.array(userIdSchema).min(1).max(MAX_USER_METADATA_BATCH),
+});
 const getPermissionsHandler = async (_gc, ctx, _req) => {
     try {
         const result = await getSettingsBranchContext(ctx);
@@ -82,6 +88,7 @@ const updatePermissionsHandler = async (_gc, ctx, req, body) => {
             branchRoot: context.branchRoot,
             fileName: 'permissions.json',
             message: 'Update permissions',
+            actor: req.user,
             mode,
         });
         if (!commitResult.pushed) {
@@ -95,7 +102,7 @@ const updatePermissionsHandler = async (_gc, ctx, req, body) => {
     }
     catch (error) {
         if (error instanceof SettingsVersionConflictError) {
-            return { ok: false, status: 409, error: error.message };
+            return { ok: false, status: 409, error: error.message, code: 'SETTINGS_CHANGED' };
         }
         if (error instanceof SettingsFileConflictError) {
             return { ok: false, status: 409, error: 'Settings are busy, please try again.' };
@@ -198,8 +205,29 @@ const getUserMetadataHandler = async (_gc, ctx, req, params) => {
         return { ok: false, status: 501, error: 'Auth plugin not configured' };
     }
     try {
-        const user = await authPlugin.getUserMetadata(params.userId);
-        return { ok: true, status: 200, data: { user } };
+        const users = await lookupUsersMetadata(authPlugin, [params.userId]);
+        return { ok: true, status: 200, data: { user: users.get(params.userId) ?? null } };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 500,
+            error: sanitizeErrorMessage(getErrorMessage(error)),
+        };
+    }
+};
+/**
+ * Get metadata for many users at once (for UI display)
+ */
+const batchGetUserMetadataHandler = async (_gc, ctx, _req, body) => {
+    const authPlugin = ctx.authPlugin;
+    if (!authPlugin) {
+        return { ok: false, status: 501, error: 'Auth plugin not configured' };
+    }
+    try {
+        const found = await lookupUsersMetadata(authPlugin, body.userIds);
+        const users = [...found.values()].filter((user) => user !== null);
+        return { ok: true, status: 200, data: { users } };
     }
     catch (error) {
         return {
@@ -288,6 +316,24 @@ const getUserMetadata = defineEndpoint({
     guards: ['privileged'],
     handler: getUserMetadataHandler,
 });
+/**
+ * Get metadata for up to MAX_USER_METADATA_BATCH users (admin/reviewer only)
+ * POST /users/batch
+ */
+const batchGetUserMetadata = defineEndpoint({
+    namespace: 'permissions',
+    name: 'batchGetUserMetadata',
+    method: 'POST',
+    readOnly: true,
+    path: '/users/batch',
+    body: batchGetUserMetadataBodySchema,
+    bodyType: 'BatchGetUserMetadataBody',
+    responseType: 'BatchGetUserMetadataResponse',
+    response: {},
+    defaultMockData: { users: [] },
+    guards: ['privileged'],
+    handler: batchGetUserMetadataHandler,
+});
 /**
  * Exported routes for router registration
  */
@@ -297,4 +343,5 @@ export const PERMISSION_ROUTES = {
     searchUsers: searchUsers,
     listGroups: listGroups,
     getUserMetadata: getUserMetadata,
+    batchGetUserMetadata: batchGetUserMetadata,
 };

package/dist/api/request-deadline.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Deadlines for the editor's API requests. A request that never answers (network drop, laptop
+ * sleep) must not hold a busy state open forever, so every client call runs under a deadline and,
+ * past it, rejects with {@link ApiTimeoutError}: a thrown error, as a network failure is, but
+ * distinguishable from one. HTTP error statuses stay `ok: false` responses.
+ */
+/**
+ * @internal Exported for tests.
+ *
+ * How long each class of request may take. `standard` is past the 60 s an API behind CloudFront
+ * gets (canopycms-cdk's `assertOriginReadTimeout`), so a server still working answers, or its
+ * proxy's 504 does, before the editor gives up; reads get it too, since any request may first
+ * provision the base branch's workspace (`http/handler.ts`). `long` is
+ * for the operations that legitimately run longer: branch create, submit, admin scans and
+ * repairs, and an upload without progress.
+ */
+export declare const REQUEST_TIMEOUT_MS: {
+    readonly standard: 75000;
+    readonly long: 180000;
+};
+/** An endpoint's timeout class; `none` waits as long as the browser does. */
+export type RequestTimeoutClass = keyof typeof REQUEST_TIMEOUT_MS | 'none';
+/** Per-call options every API client method accepts as its last argument. */
+export interface RequestOptions {
+    /** Aborts the request; the call then rejects with the signal's `reason`. */
+    signal?: AbortSignal;
+    /** Replaces the endpoint's timeout, in ms; `null` waits as long as the browser does. */
+    timeoutMs?: number | null;
+}
+/** @internal Exported for tests. A timed-out read's message: retrying it is safe. */
+export declare const REQUEST_TIMED_OUT_MESSAGE = "The server didn't answer in time. Check your connection and try again.";
+/** @internal Exported for tests. A timed-out write's message: the server may have acted on it. */
+export declare const WRITE_TIMED_OUT_MESSAGE = "The server didn't answer, so this may have gone through anyway. Check before trying again.";
+/**
+ * A request ran past its deadline and was abandoned; the server may still have acted on it.
+ * `readOnly` defaults to GET; a body-taking lookup passes it (`EndpointConfigBase['readOnly']`).
+ */
+export declare class ApiTimeoutError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly timeoutMs: number;
+    readonly name = "ApiTimeoutError";
+    constructor(method: string, path: string, timeoutMs: number, readOnly?: boolean);
+}
+export declare function isApiTimeoutError(err: unknown): err is ApiTimeoutError;
+/** The timeout, in ms or `null` for none, that a call with `options` to a `timeout`-class endpoint gets. */
+export declare function resolveTimeoutMs(timeout: RequestTimeoutClass, options: RequestOptions | undefined): number | null;
+/**
+ * Run `run` with a signal that aborts at the deadline or when `options.signal` does, and settle
+ * then even if `run` ignores its signal (a custom `fetch` may). Past the deadline the call
+ * rejects with an {@link ApiTimeoutError}; on the caller's abort, with the caller's reason.
+ */
+export declare function runWithDeadline<T>(run: (signal: AbortSignal) => Promise<T>, request: {
+    method: string;
+    path: string;
+    timeoutMs: number | null;
+    signal?: AbortSignal;
+    readOnly?: boolean;
+}): Promise<T>;

package/dist/api/request-deadline.js

@@ -0,0 +1,73 @@
+/**
+ * Deadlines for the editor's API requests. A request that never answers (network drop, laptop
+ * sleep) must not hold a busy state open forever, so every client call runs under a deadline and,
+ * past it, rejects with {@link ApiTimeoutError}: a thrown error, as a network failure is, but
+ * distinguishable from one. HTTP error statuses stay `ok: false` responses.
+ */
+/**
+ * @internal Exported for tests.
+ *
+ * How long each class of request may take. `standard` is past the 60 s an API behind CloudFront
+ * gets (canopycms-cdk's `assertOriginReadTimeout`), so a server still working answers, or its
+ * proxy's 504 does, before the editor gives up; reads get it too, since any request may first
+ * provision the base branch's workspace (`http/handler.ts`). `long` is
+ * for the operations that legitimately run longer: branch create, submit, admin scans and
+ * repairs, and an upload without progress.
+ */
+export const REQUEST_TIMEOUT_MS = {
+    standard: 75_000,
+    long: 180_000,
+};
+/** @internal Exported for tests. A timed-out read's message: retrying it is safe. */
+export const REQUEST_TIMED_OUT_MESSAGE = "The server didn't answer in time. Check your connection and try again.";
+/** @internal Exported for tests. A timed-out write's message: the server may have acted on it. */
+export const WRITE_TIMED_OUT_MESSAGE = "The server didn't answer, so this may have gone through anyway. Check before trying again.";
+/**
+ * A request ran past its deadline and was abandoned; the server may still have acted on it.
+ * `readOnly` defaults to GET; a body-taking lookup passes it (`EndpointConfigBase['readOnly']`).
+ */
+export class ApiTimeoutError extends Error {
+    constructor(method, path, timeoutMs, readOnly = method === 'GET') {
+        super(readOnly ? REQUEST_TIMED_OUT_MESSAGE : WRITE_TIMED_OUT_MESSAGE);
+        this.method = method;
+        this.path = path;
+        this.timeoutMs = timeoutMs;
+        this.name = 'ApiTimeoutError';
+    }
+}
+export function isApiTimeoutError(err) {
+    return err instanceof ApiTimeoutError;
+}
+/** The timeout, in ms or `null` for none, that a call with `options` to a `timeout`-class endpoint gets. */
+export function resolveTimeoutMs(timeout, options) {
+    if (options?.timeoutMs !== undefined)
+        return options.timeoutMs;
+    return timeout === 'none' ? null : REQUEST_TIMEOUT_MS[timeout];
+}
+/**
+ * Run `run` with a signal that aborts at the deadline or when `options.signal` does, and settle
+ * then even if `run` ignores its signal (a custom `fetch` may). Past the deadline the call
+ * rejects with an {@link ApiTimeoutError}; on the caller's abort, with the caller's reason.
+ */
+export async function runWithDeadline(run, request) {
+    const { signal: callerSignal, timeoutMs } = request;
+    callerSignal?.throwIfAborted();
+    const controller = new AbortController();
+    const onCallerAbort = () => controller.abort(callerSignal?.reason);
+    callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
+    const timer = timeoutMs === null
+        ? undefined
+        : setTimeout(() => controller.abort(new ApiTimeoutError(request.method, request.path, timeoutMs, request.readOnly)), timeoutMs);
+    const aborted = new Promise((_, reject) => {
+        controller.signal.addEventListener('abort', () => reject(controller.signal.reason), {
+            once: true,
+        });
+    });
+    try {
+        return await Promise.race([run(controller.signal), aborted]);
+    }
+    finally {
+        clearTimeout(timer);
+        callerSignal?.removeEventListener('abort', onCallerAbort);
+    }
+}

package/dist/api/resolve-references.js

@@ -25,17 +25,16 @@ const resolveReferencesHandler = async (gc, ctx, req, params, body) => {
     const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
     const access = (logicalPath) => checkAccess(logicalPath, 'read').allowed;
     // The resolution `read()` applies to a reference field, so live preview shows this user what
-    // `read()` would: the target's data, or a `RestrictedReference` for a target they may not
-    // read. The target's own references stay ids, as in `read()`.
+    // `read()` would: the target's data, a `RestrictedReference` for a target they may not read,
+    // or a `MissingReference` for an id naming no entry. The target's own references stay ids, as
+    // in `read()`.
     const resolved = {};
     for (const id of ids) {
         try {
-            const value = await store.resolveReferenceTarget(id, access);
-            if (value)
-                resolved[id] = value;
+            resolved[id] = await store.resolveReferenceTarget(id, access);
         }
         catch (error) {
-            // An id that fails to resolve is omitted rather than failing the whole request.
+            // An id whose lookup throws is omitted rather than failing the whole request.
             console.error(`Failed to resolve reference ID ${id}:`, error);
         }
     }
@@ -47,7 +46,8 @@ const resolveReferencesHandler = async (gc, ctx, req, params, body) => {
 };
 /**
  * Resolve reference IDs as a reference field would: full target data, or title + URL tagged
- * `unavailable` for a target the user may not read. An id naming no entry is omitted.
+ * `unavailable` for a target the user may not read, or `{ id, unavailable: true, reason: 'missing' }`
+ * for an id naming no entry.
  * POST /:branch/resolve-references
  * Body: { ids: string[] }
  */
@@ -55,6 +55,7 @@ const resolveReferences = defineEndpoint({
     namespace: 'content',
     name: 'resolveReferences',
     method: 'POST',
+    readOnly: true,
     path: '/:branch/resolve-references',
     params: resolveReferencesParamsSchema,
     body: resolveReferencesBodySchema,

package/dist/api/route-builder.d.ts

@@ -34,6 +34,10 @@ export interface RouteMetadata {
     defaultMockData?: unknown;
     /** Casts to apply to mock data fields for branded types */
     mockDataCasts?: MockDataCasts;
+    /** See `EndpointConfigBase['clientTimeout']`. */
+    clientTimeout?: 'long' | 'none';
+    /** See `EndpointConfigBase['readOnly']`. */
+    readOnly?: true;
 }
 /**
  * Route definition created by defineEndpoint.
@@ -100,6 +104,16 @@ interface EndpointConfigBase<TParams extends z.ZodType | undefined, TBody extend
     mockDataCasts?: MockDataCasts;
     /** See `RouteDefinition['bodyFormat']` above. */
     bodyFormat?: 'multipart';
+    /**
+     * The generated client's timeout for this endpoint, when not `standard`; see
+     * `REQUEST_TIMEOUT_MS` in request-deadline.ts.
+     */
+    clientTimeout?: 'long' | 'none';
+    /**
+     * A non-GET endpoint that changes nothing, such as a lookup taking its input in a body. Its
+     * timeout then says to try again rather than that it may have gone through (`ApiTimeoutError`).
+     */
+    readOnly?: true;
 }
 /** Config for an endpoint without guards */
 interface UnguardedEndpointConfig<TParams extends z.ZodType | undefined, TBody extends z.ZodType | undefined, TResponse> extends EndpointConfigBase<TParams, TBody> {

package/dist/api/route-builder.js

@@ -9,6 +9,9 @@
  * - Self-documents the API surface
  */
 import { executeGuards } from './guards.js';
+function isOkResponse(response) {
+    return (typeof response === 'object' && response !== null && 'ok' in response && response.ok === true);
+}
 /**
  * Global registry - generator reads this
  */
@@ -28,6 +31,8 @@ export function defineEndpoint(config) {
         responseTypeName: config.responseType,
         defaultMockData: config.defaultMockData,
         mockDataCasts: config.mockDataCasts,
+        clientTimeout: config.clientTimeout,
+        readOnly: config.readOnly,
     });
     // Convert path template to pattern array for router
     const pattern = config.path.split('/').filter(Boolean);
@@ -71,6 +76,7 @@ export function defineEndpoint(config) {
     if (config.guards && config.guards.length > 0) {
         const guards = config.guards;
         const guardedHandler = config.handler;
+        const recordsEditor = guards.includes('writableBranch');
         handler = async (ctx, req, ...args) => {
             // Extract params from args (first arg after ctx/req if present)
             const params = args[0] ?? {};
@@ -79,7 +85,14 @@ export function defineEndpoint(config) {
                 return guardResult.response;
             }
             // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-            return guardedHandler(guardResult.guardContext, ctx, req, ...args);
+            const response = await guardedHandler(guardResult.guardContext, ctx, req, ...args);
+            // Every 'writableBranch' endpoint changes the branch's working tree, so one that succeeds
+            // makes its user an editor of the branch.
+            if (recordsEditor && isOkResponse(response)) {
+                const { branchContext } = guardResult.guardContext;
+                await ctx.services.recordBranchEditor(branchContext, req.user);
+            }
+            return response;
         };
     }
     else {

package/dist/api/schema.d.ts

@@ -6,7 +6,7 @@
  */
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
-import type { ContentFormat, EntrySchema } from '../config/index.js';
+import type { EntryTypeUnavailable, ContentFormat, EntrySchema } from '../config/index.js';
 import { type LogicalPath, type ContentId } from '../paths/index.js';
 /** Entry type in wire format: schemaRef instead of resolved schema */
 interface WireEntryType {
@@ -16,6 +16,7 @@ interface WireEntryType {
     readonly label?: string;
     readonly default?: boolean;
     readonly maxItems?: number;
+    readonly unavailable?: EntryTypeUnavailable;
 }
 /** Collection in wire format (entry types carry schemaRef, not resolved schema) */
 interface WireCollectionConfig {
@@ -52,6 +53,7 @@ type WireFlatSchemaItem = {
     schemaRef: string;
     default?: boolean;
     maxItems?: number;
+    unavailable?: EntryTypeUnavailable;
 };
 interface SchemaResponse {
     flatSchema: WireFlatSchemaItem[];
@@ -339,18 +341,18 @@ export declare const updateEntryType: import("./route-builder.js").RouteDefiniti
     branch: string & {
         readonly __brand: "BranchName";
     };
-    entryTypeName: string;
     collectionPath: string & {
         readonly __brand: "LogicalPath";
     };
+    entryTypeName: string;
 }, {
     branch: string & {
         readonly __brand: "BranchName";
     };
-    entryTypeName: string;
     collectionPath: string & {
         readonly __brand: "LogicalPath";
     };
+    entryTypeName: string;
 }>, z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     format: z.ZodOptional<z.ZodEnum<["md", "mdx", "json", "yaml"]>>;
@@ -383,18 +385,18 @@ export declare const removeEntryType: import("./route-builder.js").RouteDefiniti
     branch: string & {
         readonly __brand: "BranchName";
     };
-    entryTypeName: string;
     collectionPath: string & {
         readonly __brand: "LogicalPath";
     };
+    entryTypeName: string;
 }, {
     branch: string & {
         readonly __brand: "BranchName";
     };
-    entryTypeName: string;
     collectionPath: string & {
         readonly __brand: "LogicalPath";
     };
+    entryTypeName: string;
 }>, undefined, RemoveEntryTypeApiResponse>;
 /**
  * PATCH /:branch/schema/order/...collectionPath - Update item order
@@ -616,18 +618,18 @@ export declare const SCHEMA_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-        entryTypeName: string;
         collectionPath: string & {
             readonly __brand: "LogicalPath";
         };
+        entryTypeName: string;
     }, {
         branch: string & {
             readonly __brand: "BranchName";
         };
-        entryTypeName: string;
         collectionPath: string & {
             readonly __brand: "LogicalPath";
         };
+        entryTypeName: string;
     }>, z.ZodObject<{
         label: z.ZodOptional<z.ZodString>;
         format: z.ZodOptional<z.ZodEnum<["md", "mdx", "json", "yaml"]>>;
@@ -655,18 +657,18 @@ export declare const SCHEMA_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-        entryTypeName: string;
         collectionPath: string & {
             readonly __brand: "LogicalPath";
         };
+        entryTypeName: string;
     }, {
         branch: string & {
             readonly __brand: "BranchName";
         };
-        entryTypeName: string;
         collectionPath: string & {
             readonly __brand: "LogicalPath";
         };
+        entryTypeName: string;
     }>, undefined, RemoveEntryTypeApiResponse>;
     readonly updateOrder: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;

package/dist/api/schema.js

@@ -57,6 +57,7 @@ function toWireEntryType(et, registry) {
         ...(et.label !== undefined && { label: et.label }),
         ...(et.default !== undefined && { default: et.default }),
         ...(et.maxItems !== undefined && { maxItems: et.maxItems }),
+        ...(et.unavailable && { unavailable: et.unavailable }),
     };
 }
 function toWireCollection(col, registry) {
@@ -99,6 +100,7 @@ function toWireFlatSchema(items, registry) {
             schemaRef: resolveSchemaRef(item, registry),
             ...(item.default !== undefined && { default: item.default }),
             ...(item.maxItems !== undefined && { maxItems: item.maxItems }),
+            ...(item.unavailable && { unavailable: item.unavailable }),
         };
     });
 }

package/dist/api/settings-helpers.d.ts

@@ -1,5 +1,6 @@
 import type { ApiContext } from './types.js';
 import type { OperatingMode } from '../operating-mode/index.js';
+import type { CanopyUser } from '../user.js';
 /**
  * Get the appropriate root path for settings (permissions/groups).
  * Returns the settings root managed by the settings workspace.
@@ -30,7 +31,8 @@ export interface CommitSettingsResult {
 /**
  * Commit and push settings changes based on the mode.
  * Both prod and dev use commitToSettingsBranch.
- * Settings changes are never reviewed through a PR (see commitToSettingsBranch).
+ * Settings changes are never reviewed through a PR (see commitToSettingsBranch), and the bot
+ * authors the commit, so its trailers, not its author line, name who made the change.
  */
 export declare function commitSettings(ctx: ApiContext, options: {
     context: {
@@ -39,5 +41,7 @@ export declare function commitSettings(ctx: ApiContext, options: {
     branchRoot: string;
     fileName: string;
     message: string;
+    /** The user making the change, named in the commit's trailers as a submit names its editors. */
+    actor: CanopyUser;
     mode: OperatingMode;
 }): Promise<CommitSettingsResult>;

package/dist/api/settings-helpers.js

@@ -1,5 +1,6 @@
 import { operatingStrategy } from '../operating-mode/index.js';
 import { sanitizeErrorMessage } from '../utils/error.js';
+import { appendTrailers, buildEditorTrailers, submissionEditorFromUser, } from '../submission-attribution.js';
 /**
  * Get the appropriate root path for settings (permissions/groups).
  * Returns the settings root managed by the settings workspace.
@@ -23,7 +24,8 @@ export async function getSettingsBranchContext(ctx) {
 /**
  * Commit and push settings changes based on the mode.
  * Both prod and dev use commitToSettingsBranch.
- * Settings changes are never reviewed through a PR (see commitToSettingsBranch).
+ * Settings changes are never reviewed through a PR (see commitToSettingsBranch), and the bot
+ * authors the commit, so its trailers, not its author line, name who made the change.
  */
 export async function commitSettings(ctx, options) {
     const strategy = operatingStrategy(options.mode);
@@ -34,10 +36,16 @@ export async function commitSettings(ctx, options) {
     }
     // For modes that use separate settings branch, commit to settings branch
     if (strategy.usesSeparateSettingsBranch()) {
+        const actor = submissionEditorFromUser(options.actor);
+        const { config } = ctx.services;
+        const trailers = buildEditorTrailers(actor ? [actor] : [], {
+            editedBy: config.gitEditedByTrailers ?? true,
+            coAuthoredBy: config.gitCoAuthoredByTrailers ?? false,
+        });
         const result = await ctx.services.commitToSettingsBranch({
             branchRoot: options.branchRoot,
             files: options.fileName,
-            message: options.message,
+            message: appendTrailers(options.message, trailers),
         });
         if (!result.pushed) {
             console.warn(`${options.message} committed but not pushed:`, result.error);

package/dist/api/types.d.ts

@@ -48,4 +48,22 @@ export interface ApiResponse<TData = unknown> {
         fieldPath: string;
         message: string;
     }>;
+    /** A machine-readable reason for some failures; see {@link ApiErrorCode}. */
+    code?: ApiErrorCode;
 }
+/**
+ * `SCHEMA_UNAVAILABLE`: the entry's type names an entry schema the running code lacks (a 503,
+ * see `SchemaUnavailableError`). `WORKER_FAILED`: the CMS worker recorded that its latest start
+ * failed, so a retry will not help until an admin fixes it (a 503 with no `Retry-After`).
+ * `WRITE_OUTCOME_UNKNOWN`: an entry save ran but lost its branch lock mid-write, so it may have
+ * landed (a 409); the version the caller holds may be stale, so it must re-read before retrying.
+ * `ENTRY_GONE`: an entry update found no file, because the entry was deleted or moved since the
+ * caller read it (a 409); it was not saved, and only a create can bring the entry back.
+ * `EDITOR_MODE_MISMATCH`: the editor bundle was built for the other operating mode than the
+ * server runs (a 412, see operating-mode/editor-mode-check.ts); only a rebuild fixes it.
+ * `SETTINGS_CHANGED`: a groups or permissions save named a version the file has moved on from (a
+ * 409, see `SettingsVersionConflictError`); nothing was saved, and a reload shows the other edit.
+ * The other settings 409, a busy file lock, carries no code. `BRANCH_SYNCING`: an entry save was
+ * refused because the branch is mid-rebase (a 409); nothing was saved, and a retry soon can pass.
+ */
+export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED' | 'WRITE_OUTCOME_UNKNOWN' | 'ENTRY_GONE' | 'EDITOR_MODE_MISMATCH' | 'SETTINGS_CHANGED' | 'BRANCH_SYNCING';

package/dist/api/users-constants.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Constants the user endpoints share with the editor, kept dependency-free so the editor's
+ * browser bundle can import them without pulling in `permissions.ts` and its server-only deps.
+ */
+/** Most user ids one `POST /users/batch` request may carry; the editor splits larger sets. */
+export declare const MAX_USER_METADATA_BATCH = 100;

package/dist/api/users-constants.js

@@ -0,0 +1,6 @@
+/**
+ * Constants the user endpoints share with the editor, kept dependency-free so the editor's
+ * browser bundle can import them without pulling in `permissions.ts` and its server-only deps.
+ */
+/** Most user ids one `POST /users/batch` request may carry; the editor splits larger sets. */
+export const MAX_USER_METADATA_BATCH = 100;

package/dist/assets/asset-url.d.ts

@@ -1,14 +1,17 @@
 /**
  * Build/adjust transform URLs for `<img>`/srcset without pulling in the
- * server-only transform engine. Isomorphic - depends only on
- * transform-directives.ts, the plain `ASSET_PREFIXES` constant, and
- * utils/url-prefix.ts, none of which import node builtins, so this is safe to
- * import from client (editor) code as well as during static builds.
+ * server-only transform engine. Isomorphic - none of its imports reach a node
+ * builtin, so this is safe to import from client (editor) code as well as during
+ * static builds.
  */
 import { type CropRect, type OutputFormat } from './transform-directives.js';
-/** The minimal shape `assetUrl`/`assetSrcSet` need from a stored asset reference. */
+/**
+ * The minimal shape `assetUrl`/`assetSrcSet` need from a stored asset reference. An
+ * `ImageFieldValue` is one, so passing a field value renders the crop the editor stored.
+ */
 export interface AssetRef {
     src: string;
+    crop?: CropRect;
 }
 export interface AssetUrlOptions {
     width?: number;
@@ -23,16 +26,14 @@ export interface AssetUrlOptions {
      * option beside it. Two shapes are legitimate, and they are alternatives, never composed:
      *
      * - An absolute origin (`https://assets.example.com`) — assets served from another origin.
-     *   `media.publicBaseUrl` is one source of this, and is the source the editor uses; it is
-     *   validated as an absolute URL, so it structurally cannot carry the second shape.
      * - A same-origin path prefix (`/preview-123`) — the site is deployed under a Next `basePath`
      *   AND its assets are served by Next (`withCanopy`'s `/assets/:path*` rewrite, which Next
      *   auto-prefixes). NOT the right value on a CloudFront/CDK deployment, where the asset
      *   behaviors are anchored at the distribution root and a `basePath` does not move them —
      *   there the correct value is none at all. See the README's asset-mount table.
      *
-     * It is a per-render option rather than a config field precisely because the editor and the
-     * public site can legitimately have different answers.
+     * It is a per-render option rather than a config field because different renderers see the
+     * `/assets` space at different places.
      *
      * **Render-time only — never stored.** A stored `src` is always root-relative (see
      * `assets/asset-src.ts`), because content moves between branches and environments. Nothing
@@ -41,16 +42,27 @@ export interface AssetUrlOptions {
     baseUrl?: string;
 }
 /**
- * Build a transform URL, merging `opts` over the directives already present
- * in `ref.src` (opts win). For static srcs (svg/pdf under `/assets/{hash}/...`,
- * or any src that isn't one of our own transform URLs) the src is returned
- * unchanged and `opts` are ignored - there is nothing to transform.
+ * Whether `src` is in canopycms's own `/assets` URL space - a transform or static asset src the
+ * asset store serves. Every other src (a site's own static file, an off-site URL, a `data:` URI)
+ * is the host's, and the asset store never serves it.
+ */
+export declare function isAssetStoreSrc(src: string): boolean;
+/**
+ * Build a transform URL, merging `opts` and `ref.crop` over the directives already present
+ * in `ref.src` (see `mergeDirectives` for precedence). For static srcs (svg/pdf under
+ * `/assets/{hash}/...`, or any src that isn't one of our own transform URLs) the src is
+ * returned unchanged and every directive is ignored - there is nothing to transform.
+ *
+ * In a live preview, a transform URL goes behind the editor's authenticated route
+ * (`editor/preview-asset-base.ts`) instead of `opts.baseUrl`: a draft's crop or width may exist
+ * nowhere a build put it. Static srcs keep `opts.baseUrl`, since finalize wrote them.
  */
 export declare function assetUrl(ref: AssetRef, opts?: AssetUrlOptions): string;
 /**
  * Build a comma-joined `url w` srcset descriptor list. `widths` must all be
- * on the transform width allowlist (multiples of 160 in [160, 4096]) - this
- * is developer-facing (a host app's own responsive-image markup), so an
- * invalid width throws rather than silently dropping it.
+ * integers in [1, 8192] (the `any` width policy) - this is developer-facing (a
+ * host app's own responsive-image markup), so an invalid width throws rather
+ * than silently dropping it. A site serving the opt-in lazy public path, which
+ * transforms only allowlisted widths, must pick widths from that allowlist.
  */
 export declare function assetSrcSet(ref: AssetRef, widths: readonly number[], opts?: Omit<AssetUrlOptions, 'width'>): string;