canopycms 0.0.68-int.98 → 0.1.0

package/dist/api/client.js

@@ -6,10 +6,14 @@
  * (changes will be overwritten), edit the generator's templates instead.
  */
 import { computeContentSha256Hex } from './request-body-hash.js';
+import { resolveTimeoutMs, runWithDeadline } from './request-deadline.js';
+export { isApiTimeoutError, WRITE_TIMED_OUT_MESSAGE } from './request-deadline.js';
 import { readTrailingSlashEnv, withTrailingSlash } from '../utils/url-prefix.js';
+import { EDITOR_MODE_HEADER, EDITOR_MODE_MISMATCH_STATUS } from '../operating-mode/editor-mode-check.js';
 /**
  * Typed client for the CanopyCMS API: one method per endpoint, grouped by namespace, each
- * returning that endpoint's ApiResponse.
+ * returning that endpoint's ApiResponse. Every method takes {@link RequestOptions} last; a call
+ * that outlives its deadline rejects with an `ApiTimeoutError` (request-deadline.ts).
  *
  * @example
  * ```ts
@@ -21,106 +25,106 @@ export class CanopyApiClient {
     constructor(options = {}) {
         this.branches = {
             /** GET /branches */
-            list: () => {
-                return this.request('GET', '/branches');
+            list: (options) => {
+                return this.request('GET', '/branches', undefined, 'standard', options);
             },
             /** POST /branches */
-            create: (body) => {
-                return this.request('POST', '/branches', body);
+            create: (body, options) => {
+                return this.request('POST', '/branches', body, 'long', options);
             },
             /** DELETE /:branch */
-            delete: (params) => {
-                return this.request('DELETE', this.buildPath('/:branch', params));
+            delete: (params, options) => {
+                return this.request('DELETE', this.buildPath('/:branch', params), undefined, 'standard', options);
             },
             /** PATCH /:branch/access */
-            updateAccess: (params, body) => {
-                return this.request('PATCH', this.buildPath('/:branch/access', params), body);
+            updateAccess: (params, body, options) => {
+                return this.request('PATCH', this.buildPath('/:branch/access', params), body, 'standard', options);
             },
         };
         this.workflow = {
             /** POST /:branch/withdraw */
-            withdraw: (params) => {
-                return this.request('POST', this.buildPath('/:branch/withdraw', params));
+            withdraw: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/withdraw', params), undefined, 'standard', options);
             },
             /** POST /:branch/request-changes */
-            requestChanges: (params) => {
-                return this.request('POST', this.buildPath('/:branch/request-changes', params));
+            requestChanges: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/request-changes', params), undefined, 'standard', options);
             },
             /** POST /:branch/approve */
-            approve: (params) => {
-                return this.request('POST', this.buildPath('/:branch/approve', params));
+            approve: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/approve', params), undefined, 'standard', options);
             },
             /** POST /:branch/mark-merged */
-            markMerged: (params) => {
-                return this.request('POST', this.buildPath('/:branch/mark-merged', params));
+            markMerged: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/mark-merged', params), undefined, 'standard', options);
             },
             /** GET /:branch/status */
-            getStatus: (params) => {
-                return this.request('GET', this.buildPath('/:branch/status', params));
+            getStatus: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/status', params), undefined, 'standard', options);
             },
             /** POST /:branch/submit */
-            submit: (params) => {
-                return this.request('POST', this.buildPath('/:branch/submit', params));
+            submit: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/submit', params), undefined, 'long', options);
             },
         };
         this.comments = {
             /** GET /:branch/comments */
-            list: (params) => {
-                return this.request('GET', this.buildPath('/:branch/comments', params));
+            list: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/comments', params), undefined, 'standard', options);
             },
             /** POST /:branch/comments */
-            add: (params, body) => {
-                return this.request('POST', this.buildPath('/:branch/comments', params), body);
+            add: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/comments', params), body, 'standard', options);
             },
             /** POST /:branch/comments/:threadId/resolve */
-            resolve: (params) => {
-                return this.request('POST', this.buildPath('/:branch/comments/:threadId/resolve', params));
+            resolve: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/comments/:threadId/resolve', params), undefined, 'standard', options);
             },
         };
         this.content = {
             /** GET /:branch/content/...path */
-            read: (params) => {
-                return this.request('GET', this.buildPath('/:branch/content/...path', params));
+            read: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/content/...path', params), undefined, 'standard', options);
             },
             /** PUT /:branch/content/...path */
-            write: (params, body) => {
-                return this.request('PUT', this.buildPath('/:branch/content/...path', params), body);
+            write: (params, body, options) => {
+                return this.request('PUT', this.buildPath('/:branch/content/...path', params), body, 'standard', options);
             },
             /** POST /:branch/validate-references/...path */
-            validateReferences: (params, body) => {
-                return this.request('POST', this.buildPath('/:branch/validate-references/...path', params), body);
+            validateReferences: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/validate-references/...path', params), body, 'standard', options, true);
             },
             /** PATCH /:branch/rename-entry/...path */
-            renameEntry: (params, body) => {
-                return this.request('PATCH', this.buildPath('/:branch/rename-entry/...path', params), body);
+            renameEntry: (params, body, options) => {
+                return this.request('PATCH', this.buildPath('/:branch/rename-entry/...path', params), body, 'standard', options);
             },
             /** GET /:branch/reference-options */
-            getReferenceOptions: (params) => {
-                return this.request('GET', this.buildPath('/:branch/reference-options', params));
+            getReferenceOptions: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/reference-options', params), undefined, 'standard', options);
             },
             /** POST /:branch/resolve-references */
-            resolveReferences: (params, body) => {
-                return this.request('POST', this.buildPath('/:branch/resolve-references', params), body);
+            resolveReferences: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/resolve-references', params), body, 'standard', options, true);
             },
         };
         this.entries = {
             /** GET /:branch/entries */
-            list: (params) => {
-                return this.request('GET', this.buildPath('/:branch/entries', params));
+            list: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/entries', params), undefined, 'standard', options);
             },
             /** DELETE /:branch/entries/...entryPath */
-            delete: (params) => {
-                return this.request('DELETE', this.buildPath('/:branch/entries/...entryPath', params));
+            delete: (params, options) => {
+                return this.request('DELETE', this.buildPath('/:branch/entries/...entryPath', params), undefined, 'standard', options);
             },
         };
         this.assets = {
             /** POST /assets/presign */
-            presign: (body) => {
-                return this.request('POST', '/assets/presign', body);
+            presign: (body, options) => {
+                return this.request('POST', '/assets/presign', body, 'standard', options, true);
             },
             /** POST /assets/finalize */
-            finalize: (body) => {
-                return this.request('POST', '/assets/finalize', body);
+            finalize: (body, options) => {
+                return this.request('POST', '/assets/finalize', body, 'standard', options);
             },
             /** POST /assets/upload: multipart upload, hand-written because the generic template only knows JSON bodies. */
             uploadProxied: (file, options) => {
@@ -129,133 +133,137 @@ export class CanopyApiClient {
                 if (options?.filename) {
                     formData.append('filename', options.filename);
                 }
-                return this.request('POST', '/assets/upload', formData);
+                return this.request('POST', '/assets/upload', formData, 'long', options);
             },
             /** GET /assets */
-            list: (params) => {
-                return this.request('GET', this.buildPath('/assets', params));
+            list: (params, options) => {
+                return this.request('GET', this.buildPath('/assets', params), undefined, 'standard', options);
             },
             /** DELETE /assets */
-            delete: (params) => {
-                return this.request('DELETE', this.buildPath('/assets', params));
+            delete: (params, options) => {
+                return this.request('DELETE', this.buildPath('/assets', params), undefined, 'standard', options);
             },
         };
         this.permissions = {
             /** GET /permissions */
-            get: () => {
-                return this.request('GET', '/permissions');
+            get: (options) => {
+                return this.request('GET', '/permissions', undefined, 'standard', options);
             },
             /** PUT /permissions */
-            update: (body) => {
-                return this.request('PUT', '/permissions', body);
+            update: (body, options) => {
+                return this.request('PUT', '/permissions', body, 'standard', options);
             },
             /** GET /users/search */
-            searchUsers: (params) => {
-                return this.request('GET', this.buildPath('/users/search', params));
+            searchUsers: (params, options) => {
+                return this.request('GET', this.buildPath('/users/search', params), undefined, 'standard', options);
             },
             /** GET /groups */
-            listGroups: () => {
-                return this.request('GET', '/groups');
+            listGroups: (options) => {
+                return this.request('GET', '/groups', undefined, 'standard', options);
             },
             /** GET /users/:userId */
-            getUserMetadata: (params) => {
-                return this.request('GET', this.buildPath('/users/:userId', params));
+            getUserMetadata: (params, options) => {
+                return this.request('GET', this.buildPath('/users/:userId', params), undefined, 'standard', options);
+            },
+            /** POST /users/batch */
+            batchGetUserMetadata: (body, options) => {
+                return this.request('POST', '/users/batch', body, 'standard', options, true);
             },
         };
         this.groups = {
             /** GET /groups/internal */
-            getInternal: () => {
-                return this.request('GET', '/groups/internal');
+            getInternal: (options) => {
+                return this.request('GET', '/groups/internal', undefined, 'standard', options);
             },
             /** PUT /groups/internal */
-            updateInternal: (body) => {
-                return this.request('PUT', '/groups/internal', body);
+            updateInternal: (body, options) => {
+                return this.request('PUT', '/groups/internal', body, 'standard', options);
             },
             /** GET /groups/search */
-            searchExternal: (params) => {
-                return this.request('GET', this.buildPath('/groups/search', params));
+            searchExternal: (params, options) => {
+                return this.request('GET', this.buildPath('/groups/search', params), undefined, 'standard', options);
             },
         };
         this.user = {
             /** GET /whoami */
-            whoami: () => {
-                return this.request('GET', '/whoami');
+            whoami: (options) => {
+                return this.request('GET', '/whoami', undefined, 'standard', options);
             },
         };
         this.schema = {
             /** GET /:branch/schema */
-            get: (params) => {
-                return this.request('GET', this.buildPath('/:branch/schema', params));
+            get: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/schema', params), undefined, 'standard', options);
             },
             /** GET /:branch/schema/collection/...collectionPath */
-            getCollection: (params) => {
-                return this.request('GET', this.buildPath('/:branch/schema/collection/...collectionPath', params));
+            getCollection: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/schema/collection/...collectionPath', params), undefined, 'standard', options);
             },
             /** POST /:branch/schema/collections */
-            createCollection: (params, body) => {
-                return this.request('POST', this.buildPath('/:branch/schema/collections', params), body);
+            createCollection: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/schema/collections', params), body, 'standard', options);
             },
             /** PATCH /:branch/schema/collection/...collectionPath */
-            updateCollection: (params, body) => {
-                return this.request('PATCH', this.buildPath('/:branch/schema/collection/...collectionPath', params), body);
+            updateCollection: (params, body, options) => {
+                return this.request('PATCH', this.buildPath('/:branch/schema/collection/...collectionPath', params), body, 'standard', options);
             },
             /** DELETE /:branch/schema/collection/...collectionPath */
-            deleteCollection: (params) => {
-                return this.request('DELETE', this.buildPath('/:branch/schema/collection/...collectionPath', params));
+            deleteCollection: (params, options) => {
+                return this.request('DELETE', this.buildPath('/:branch/schema/collection/...collectionPath', params), undefined, 'standard', options);
             },
             /** POST /:branch/schema/entry-types/...collectionPath */
-            addEntryType: (params, body) => {
-                return this.request('POST', this.buildPath('/:branch/schema/entry-types/...collectionPath', params), body);
+            addEntryType: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/schema/entry-types/...collectionPath', params), body, 'standard', options);
             },
             /** PATCH /:branch/schema/entry-types/:entryTypeName/...collectionPath */
-            updateEntryType: (params, body) => {
-                return this.request('PATCH', this.buildPath('/:branch/schema/entry-types/:entryTypeName/...collectionPath', params), body);
+            updateEntryType: (params, body, options) => {
+                return this.request('PATCH', this.buildPath('/:branch/schema/entry-types/:entryTypeName/...collectionPath', params), body, 'standard', options);
             },
             /** DELETE /:branch/schema/entry-types/:entryTypeName/...collectionPath */
-            removeEntryType: (params) => {
-                return this.request('DELETE', this.buildPath('/:branch/schema/entry-types/:entryTypeName/...collectionPath', params));
+            removeEntryType: (params, options) => {
+                return this.request('DELETE', this.buildPath('/:branch/schema/entry-types/:entryTypeName/...collectionPath', params), undefined, 'standard', options);
             },
             /** PATCH /:branch/schema/order/...collectionPath */
-            updateOrder: (params, body) => {
-                return this.request('PATCH', this.buildPath('/:branch/schema/order/...collectionPath', params), body);
+            updateOrder: (params, body, options) => {
+                return this.request('PATCH', this.buildPath('/:branch/schema/order/...collectionPath', params), body, 'standard', options);
             },
             /** POST /:branch/schema/invalidate-cache */
-            invalidateSchemaCache: (params) => {
-                return this.request('POST', this.buildPath('/:branch/schema/invalidate-cache', params));
+            invalidateSchemaCache: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/schema/invalidate-cache', params), undefined, 'standard', options);
             },
         };
         this.admin = {
             /** GET /admin/branch-health */
-            branchHealth: () => {
-                return this.request('GET', '/admin/branch-health');
+            branchHealth: (params, options) => {
+                return this.request('GET', this.buildPath('/admin/branch-health', params), undefined, 'long', options);
             },
             /** POST /admin/branch-dirs/:dirName/purge */
-            purgeBranchDir: (params) => {
-                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/purge', params));
+            purgeBranchDir: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/purge', params), undefined, 'long', options);
             },
             /** POST /admin/branch-dirs/:dirName/repair-metadata */
-            repairBranchDir: (params) => {
-                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-metadata', params));
+            repairBranchDir: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-metadata', params), undefined, 'long', options);
             },
             /** POST /admin/branch-dirs/:dirName/repair-content-duplicates */
-            repairContentDuplicates: (params) => {
-                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-content-duplicates', params));
+            repairContentDuplicates: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-content-duplicates', params), undefined, 'long', options);
             },
             /** GET /admin/status */
-            status: () => {
-                return this.request('GET', '/admin/status');
+            status: (options) => {
+                return this.request('GET', '/admin/status', undefined, 'standard', options);
             },
             /** GET /admin/tasks/:status */
-            listTasks: (params) => {
-                return this.request('GET', this.buildPath('/admin/tasks/:status', params));
+            listTasks: (params, options) => {
+                return this.request('GET', this.buildPath('/admin/tasks/:status', params), undefined, 'standard', options);
             },
             /** POST /admin/tasks/:taskId/retry */
-            retryTask: (params) => {
-                return this.request('POST', this.buildPath('/admin/tasks/:taskId/retry', params));
+            retryTask: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/tasks/:taskId/retry', params), undefined, 'standard', options);
             },
             /** DELETE /admin/tasks/:status/:fileName */
-            deleteTask: (params) => {
-                return this.request('DELETE', this.buildPath('/admin/tasks/:status/:fileName', params));
+            deleteTask: (params, options) => {
+                return this.request('DELETE', this.buildPath('/admin/tasks/:status/:fileName', params), undefined, 'standard', options);
             },
         };
         this.baseUrl = options.baseUrl ?? '/api/canopycms';
@@ -263,6 +271,8 @@ export class CanopyApiClient {
         this.fetchFn = options.fetch ?? (typeof window !== 'undefined' ? fetch.bind(window) : fetch);
         this.trailingSlash = options.trailingSlash ?? readTrailingSlashEnv();
         this.onUnauthorized = options.onUnauthorized;
+        this.editorMode = options.editorMode;
+        this.onEditorModeMismatch = options.onEditorModeMismatch;
     }
     buildPath(template, params) {
         let result = template;
@@ -293,11 +303,21 @@ export class CanopyApiClient {
         }
         return result;
     }
-    async request(method, path, body, headers = {}) {
+    /** One API call, 429 resends included, under the deadline `timeout` and `options` give it. */
+    request(method, path, body, timeout, options, readOnly = method === 'GET') {
+        return runWithDeadline((signal) => this.send(method, path, body, signal), {
+            method,
+            path,
+            readOnly,
+            timeoutMs: resolveTimeoutMs(timeout, options),
+            signal: options?.signal,
+        });
+    }
+    async send(method, path, body, signal) {
         const url = `${this.baseUrl}${this.trailingSlash ? withTrailingSlash(path) : path}`;
-        const requestHeaders = {
-            ...headers,
-        };
+        const requestHeaders = {};
+        if (this.editorMode)
+            requestHeaders[EDITOR_MODE_HEADER] = this.editorMode;
         let requestBody;
         if (body !== undefined) {
             if (body instanceof FormData) {
@@ -322,10 +342,13 @@ export class CanopyApiClient {
         const init = {
             method,
             headers: requestHeaders,
+            signal,
         };
         if (requestBody !== undefined) {
             init.body = requestBody;
         }
+        // Hashing the body is async, so the deadline may already have passed: send nothing then.
+        signal.throwIfAborted();
         let 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.
@@ -338,13 +361,20 @@ export class CanopyApiClient {
             if (delay === undefined)
                 break;
             await sleep(delay);
+            signal.throwIfAborted();
             response = await this.fetchFn(url, init);
             parsed = await response.json().catch(() => undefined);
         }
-        if (response.status === 401) {
+        // The body's status is the signal: `unauthenticatedStatus` may send it under HTTP 419.
+        if (response.status === 401 || (isApiResponseBody(parsed) && parsed.status === 401)) {
             this.onUnauthorized?.();
             return { ok: false, status: 401, error: errorFromBody(parsed) ?? 'Unauthorized' };
         }
+        if (isApiResponseBody(parsed) &&
+            parsed.status === EDITOR_MODE_MISMATCH_STATUS &&
+            parsed.code === 'EDITOR_MODE_MISMATCH') {
+            this.onEditorModeMismatch?.();
+        }
         if (isApiResponseBody(parsed))
             return parsed;
         const converted = {
@@ -361,13 +391,13 @@ export class CanopyApiClient {
  * clears as they finish, so the waits span a few seconds.
  */
 const THROTTLE_RETRY_DELAYS_MS = [250, 1000, 3000];
-/** The longest `Retry-After` waited; a throttle asking for longer is reported, not resent. */
+/** The longest `Retry-After` honoured; a throttle asking for longer is reported, not resent. */
 const MAX_RETRY_AFTER_MS = 5000;
 /**
  * The wait before resend `attempt`, or undefined when there is to be no resend: the attempts
- * are used up, or `Retry-After` asks for longer than {@link MAX_RETRY_AFTER_MS}. Without a
- * `Retry-After`, the base delay plus up to half again, so throttled requests do not resend in
- * lockstep.
+ * are used up, or `Retry-After` asks for longer than {@link MAX_RETRY_AFTER_MS}. The base delay,
+ * or `Retry-After` when longer, plus up to half the base again, so requests throttled in one
+ * burst do not resend in lockstep.
  */
 function throttleRetryDelayMs(response, attempt) {
     const base = THROTTLE_RETRY_DELAYS_MS[attempt];
@@ -377,11 +407,14 @@ function throttleRetryDelayMs(response, attempt) {
     // `fetch` option may return a Response-like without headers.
     const header = response.headers?.get('retry-after')?.trim();
     const retryAfter = header ? Number(header) : Number.NaN;
+    let wait = base;
     if (Number.isFinite(retryAfter) && retryAfter >= 0) {
         const ms = retryAfter * 1000;
-        return ms > MAX_RETRY_AFTER_MS ? undefined : ms;
+        if (ms > MAX_RETRY_AFTER_MS)
+            return undefined;
+        wait = Math.max(ms, base);
     }
-    return base + Math.random() * base * 0.5;
+    return wait + Math.random() * base * 0.5;
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/api/comments.d.ts

@@ -1,15 +1,21 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
 import type { CommentThread, CommentType } from '../comment-store.js';
+import type { UserProfile } from '../auth/types.js';
+import type { LogicalPath } from '../paths/types.js';
 export interface AddCommentBody {
     text: string;
     threadId?: string;
     type: CommentType;
     entryPath?: string;
     canopyPath?: string;
+    /** For a new field thread: the key of each list item on `canopyPath` (`CommentThread.itemKeys`). */
+    itemKeys?: string[];
 }
 interface ListCommentsResponse {
     threads: CommentThread[];
+    /** Profiles of the people who wrote or resolved `threads`, in no order; unknown ids are absent. */
+    users: UserProfile[];
 }
 /** Response type for listing comments */
 export type CommentsResponse = ApiResponse<ListCommentsResponse>;
@@ -48,19 +54,22 @@ export declare const COMMENT_ROUTES: {
         text: z.ZodString;
         threadId: z.ZodOptional<z.ZodString>;
         type: z.ZodEnum<["field", "entry", "branch"]>;
-        entryPath: z.ZodOptional<z.ZodType<import("../paths/index.js").LogicalPath, z.ZodTypeDef, import("../paths/index.js").LogicalPath>>;
+        entryPath: z.ZodOptional<z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>>;
         canopyPath: z.ZodOptional<z.ZodString>;
+        itemKeys: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, "strip", z.ZodTypeAny, {
         type: "branch" | "entry" | "field";
         text: string;
-        entryPath?: import("../paths/index.js").LogicalPath | undefined;
+        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
+        itemKeys?: string[] | undefined;
         canopyPath?: string | undefined;
     }, {
         type: "branch" | "entry" | "field";
         text: string;
-        entryPath?: import("../paths/index.js").LogicalPath | undefined;
+        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
+        itemKeys?: string[] | undefined;
         canopyPath?: string | undefined;
     }>, AddCommentResponse>;
     readonly resolve: import("./route-builder.js").RouteDefinition<z.ZodObject<{