canopycms 0.0.67-int.90 → 0.0.67

package/dist/api/client.js

@@ -1,207 +1,127 @@
 /**
- * Typed API client for CanopyCMS.
+ * Typed API client for CanopyCMS: one method per endpoint, each returning that
+ * endpoint's ApiResponse.
  *
- * AUTO-GENERATED by scripts/generate-client.ts
- * Do not edit this file manually - changes will be overwritten.
+ * AUTO-GENERATED by scripts/generate-client.ts; do not edit this file manually
+ * (changes will be overwritten), edit the generator's templates instead.
  */
 import { computeContentSha256Hex } from './request-body-hash.js';
 /**
- * Lightweight typed API client for CanopyCMS.
+ * Typed client for the CanopyCMS API: one method per endpoint, grouped by namespace, each
+ * returning that endpoint's ApiResponse.
  *
- * Provides type-safe methods for all API endpoints with centralized
- * response unwrapping and error handling.
- *
- * @example Browser usage
- * ```ts
- * const client = createApiClient()
- * const branches = await client.branches.list()
- * if (branches.ok) {
- *   console.log(branches.data.branches)
- * }
- * ```
- *
- * @example Test usage
+ * @example
  * ```ts
- * const client = createApiClient({
- *   fetch: mockFetch
- * })
+ * const branches = await createApiClient().branches.list()
+ * if (branches.ok) console.log(branches.data.branches)
  * ```
  */
 export class CanopyApiClient {
     constructor(options = {}) {
-        // ========== Auto-Generated Client Namespaces ==========
-        // Generated by scripts/generate-client.ts - DO NOT EDIT MANUALLY
-        /**
-         * branches - Auto-generated methods
-         */
         this.branches = {
-            /**
-             * list - GET /branches
-             */
+            /** GET /branches */
             list: () => {
                 return this.request('GET', '/branches');
             },
-            /**
-             * create - POST /branches
-             */
+            /** POST /branches */
             create: (body) => {
                 return this.request('POST', '/branches', body);
             },
-            /**
-             * delete - DELETE /:branch
-             */
+            /** DELETE /:branch */
             delete: (params) => {
                 return this.request('DELETE', this.buildPath('/:branch', params));
             },
-            /**
-             * updateAccess - PATCH /:branch/access
-             */
+            /** PATCH /:branch/access */
             updateAccess: (params, body) => {
                 return this.request('PATCH', this.buildPath('/:branch/access', params), body);
             },
         };
-        /**
-         * workflow - Auto-generated methods
-         */
         this.workflow = {
-            /**
-             * withdraw - POST /:branch/withdraw
-             */
+            /** POST /:branch/withdraw */
             withdraw: (params) => {
                 return this.request('POST', this.buildPath('/:branch/withdraw', params));
             },
-            /**
-             * requestChanges - POST /:branch/request-changes
-             */
+            /** POST /:branch/request-changes */
             requestChanges: (params) => {
                 return this.request('POST', this.buildPath('/:branch/request-changes', params));
             },
-            /**
-             * approve - POST /:branch/approve
-             */
+            /** POST /:branch/approve */
             approve: (params) => {
                 return this.request('POST', this.buildPath('/:branch/approve', params));
             },
-            /**
-             * markMerged - POST /:branch/mark-merged
-             */
+            /** POST /:branch/mark-merged */
             markMerged: (params) => {
                 return this.request('POST', this.buildPath('/:branch/mark-merged', params));
             },
-            /**
-             * getStatus - GET /:branch/status
-             */
+            /** GET /:branch/status */
             getStatus: (params) => {
                 return this.request('GET', this.buildPath('/:branch/status', params));
             },
-            /**
-             * submit - POST /:branch/submit
-             */
+            /** POST /:branch/submit */
             submit: (params) => {
                 return this.request('POST', this.buildPath('/:branch/submit', params));
             },
         };
-        /**
-         * comments - Auto-generated methods
-         */
         this.comments = {
-            /**
-             * list - GET /:branch/comments
-             */
+            /** GET /:branch/comments */
             list: (params) => {
                 return this.request('GET', this.buildPath('/:branch/comments', params));
             },
-            /**
-             * add - POST /:branch/comments
-             */
+            /** POST /:branch/comments */
             add: (params, body) => {
                 return this.request('POST', this.buildPath('/:branch/comments', params), body);
             },
-            /**
-             * resolve - POST /:branch/comments/:threadId/resolve
-             */
+            /** POST /:branch/comments/:threadId/resolve */
             resolve: (params) => {
                 return this.request('POST', this.buildPath('/:branch/comments/:threadId/resolve', params));
             },
         };
-        /**
-         * content - Auto-generated methods
-         */
         this.content = {
-            /**
-             * read - GET /:branch/content/...path
-             */
+            /** GET /:branch/content/...path */
             read: (params) => {
                 return this.request('GET', this.buildPath('/:branch/content/...path', params));
             },
-            /**
-             * write - PUT /:branch/content/...path
-             */
+            /** PUT /:branch/content/...path */
             write: (params, body) => {
                 return this.request('PUT', this.buildPath('/:branch/content/...path', params), body);
             },
-            /**
-             * validateReferences - POST /:branch/validate-references/...path
-             */
+            /** POST /:branch/validate-references/...path */
             validateReferences: (params, body) => {
                 return this.request('POST', this.buildPath('/:branch/validate-references/...path', params), body);
             },
-            /**
-             * renameEntry - PATCH /:branch/rename-entry/...path
-             */
+            /** PATCH /:branch/rename-entry/...path */
             renameEntry: (params, body) => {
                 return this.request('PATCH', this.buildPath('/:branch/rename-entry/...path', params), body);
             },
-            /**
-             * getReferenceOptions - GET /:branch/reference-options
-             */
+            /** GET /:branch/reference-options */
             getReferenceOptions: (params) => {
                 return this.request('GET', this.buildPath('/:branch/reference-options', params));
             },
-            /**
-             * resolveReferences - POST /:branch/resolve-references
-             */
+            /** POST /:branch/resolve-references */
             resolveReferences: (params, body) => {
                 return this.request('POST', this.buildPath('/:branch/resolve-references', params), body);
             },
         };
-        /**
-         * entries - Auto-generated methods
-         */
         this.entries = {
-            /**
-             * list - GET /:branch/entries
-             */
+            /** GET /:branch/entries */
             list: (params) => {
                 return this.request('GET', this.buildPath('/:branch/entries', params));
             },
-            /**
-             * delete - DELETE /:branch/entries/...entryPath
-             */
+            /** DELETE /:branch/entries/...entryPath */
             delete: (params) => {
                 return this.request('DELETE', this.buildPath('/:branch/entries/...entryPath', params));
             },
         };
-        /**
-         * assets - Auto-generated methods
-         */
         this.assets = {
-            /**
-             * presign - POST /assets/presign
-             */
+            /** POST /assets/presign */
             presign: (body) => {
                 return this.request('POST', '/assets/presign', body);
             },
-            /**
-             * finalize - POST /assets/finalize
-             */
+            /** POST /assets/finalize */
             finalize: (body) => {
                 return this.request('POST', '/assets/finalize', body);
             },
-            /**
-             * uploadProxied - POST /assets/upload (multipart/form-data - hand-written;
-             * the generic template only knows JSON bodies, and this route accepts a file)
-             */
+            /** POST /assets/upload: multipart upload, hand-written because the generic template only knows JSON bodies. */
             uploadProxied: (file, options) => {
                 const formData = new FormData();
                 formData.append('file', file);
@@ -210,217 +130,142 @@ export class CanopyApiClient {
                 }
                 return this.request('POST', '/assets/upload', formData);
             },
-            /**
-             * list - GET /assets
-             */
+            /** GET /assets */
             list: (params) => {
                 return this.request('GET', this.buildPath('/assets', params));
             },
-            /**
-             * delete - DELETE /assets
-             */
+            /** DELETE /assets */
             delete: (params) => {
                 return this.request('DELETE', this.buildPath('/assets', params));
             },
         };
-        /**
-         * permissions - Auto-generated methods
-         */
         this.permissions = {
-            /**
-             * get - GET /permissions
-             */
+            /** GET /permissions */
             get: () => {
                 return this.request('GET', '/permissions');
             },
-            /**
-             * update - PUT /permissions
-             */
+            /** PUT /permissions */
             update: (body) => {
                 return this.request('PUT', '/permissions', body);
             },
-            /**
-             * searchUsers - GET /users/search
-             */
+            /** GET /users/search */
             searchUsers: (params) => {
                 return this.request('GET', this.buildPath('/users/search', params));
             },
-            /**
-             * listGroups - GET /groups
-             */
+            /** GET /groups */
             listGroups: () => {
                 return this.request('GET', '/groups');
             },
-            /**
-             * getUserMetadata - GET /users/:userId
-             */
+            /** GET /users/:userId */
             getUserMetadata: (params) => {
                 return this.request('GET', this.buildPath('/users/:userId', params));
             },
         };
-        /**
-         * groups - Auto-generated methods
-         */
         this.groups = {
-            /**
-             * getInternal - GET /groups/internal
-             */
+            /** GET /groups/internal */
             getInternal: () => {
                 return this.request('GET', '/groups/internal');
             },
-            /**
-             * updateInternal - PUT /groups/internal
-             */
+            /** PUT /groups/internal */
             updateInternal: (body) => {
                 return this.request('PUT', '/groups/internal', body);
             },
-            /**
-             * searchExternal - GET /groups/search
-             */
+            /** GET /groups/search */
             searchExternal: (params) => {
                 return this.request('GET', this.buildPath('/groups/search', params));
             },
         };
-        /**
-         * user - Auto-generated methods
-         */
         this.user = {
-            /**
-             * whoami - GET /whoami
-             */
+            /** GET /whoami */
             whoami: () => {
                 return this.request('GET', '/whoami');
             },
         };
-        /**
-         * schema - Auto-generated methods
-         */
         this.schema = {
-            /**
-             * get - GET /:branch/schema
-             */
+            /** GET /:branch/schema */
             get: (params) => {
                 return this.request('GET', this.buildPath('/:branch/schema', params));
             },
-            /**
-             * getCollection - GET /:branch/schema/collection/...collectionPath
-             */
+            /** GET /:branch/schema/collection/...collectionPath */
             getCollection: (params) => {
                 return this.request('GET', this.buildPath('/:branch/schema/collection/...collectionPath', params));
             },
-            /**
-             * createCollection - POST /:branch/schema/collections
-             */
+            /** POST /:branch/schema/collections */
             createCollection: (params, body) => {
                 return this.request('POST', this.buildPath('/:branch/schema/collections', params), body);
             },
-            /**
-             * updateCollection - PATCH /:branch/schema/collection/...collectionPath
-             */
+            /** PATCH /:branch/schema/collection/...collectionPath */
             updateCollection: (params, body) => {
                 return this.request('PATCH', this.buildPath('/:branch/schema/collection/...collectionPath', params), body);
             },
-            /**
-             * deleteCollection - DELETE /:branch/schema/collection/...collectionPath
-             */
+            /** DELETE /:branch/schema/collection/...collectionPath */
             deleteCollection: (params) => {
                 return this.request('DELETE', this.buildPath('/:branch/schema/collection/...collectionPath', params));
             },
-            /**
-             * addEntryType - POST /:branch/schema/entry-types/...collectionPath
-             */
+            /** POST /:branch/schema/entry-types/...collectionPath */
             addEntryType: (params, body) => {
                 return this.request('POST', this.buildPath('/:branch/schema/entry-types/...collectionPath', params), body);
             },
-            /**
-             * updateEntryType - PATCH /:branch/schema/entry-types/:entryTypeName/...collectionPath
-             */
+            /** PATCH /:branch/schema/entry-types/:entryTypeName/...collectionPath */
             updateEntryType: (params, body) => {
                 return this.request('PATCH', this.buildPath('/:branch/schema/entry-types/:entryTypeName/...collectionPath', params), body);
             },
-            /**
-             * removeEntryType - DELETE /:branch/schema/entry-types/:entryTypeName/...collectionPath
-             */
+            /** DELETE /:branch/schema/entry-types/:entryTypeName/...collectionPath */
             removeEntryType: (params) => {
                 return this.request('DELETE', this.buildPath('/:branch/schema/entry-types/:entryTypeName/...collectionPath', params));
             },
-            /**
-             * updateOrder - PATCH /:branch/schema/order/...collectionPath
-             */
+            /** PATCH /:branch/schema/order/...collectionPath */
             updateOrder: (params, body) => {
                 return this.request('PATCH', this.buildPath('/:branch/schema/order/...collectionPath', params), body);
             },
-            /**
-             * invalidateSchemaCache - POST /:branch/schema/invalidate-cache
-             */
+            /** POST /:branch/schema/invalidate-cache */
             invalidateSchemaCache: (params) => {
                 return this.request('POST', this.buildPath('/:branch/schema/invalidate-cache', params));
             },
         };
-        /**
-         * admin - Auto-generated methods
-         */
         this.admin = {
-            /**
-             * branchHealth - GET /admin/branch-health
-             */
+            /** GET /admin/branch-health */
             branchHealth: () => {
                 return this.request('GET', '/admin/branch-health');
             },
-            /**
-             * purgeBranchDir - POST /admin/branch-dirs/:dirName/purge
-             */
+            /** POST /admin/branch-dirs/:dirName/purge */
             purgeBranchDir: (params) => {
                 return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/purge', params));
             },
-            /**
-             * repairBranchDir - POST /admin/branch-dirs/:dirName/repair-metadata
-             */
+            /** POST /admin/branch-dirs/:dirName/repair-metadata */
             repairBranchDir: (params) => {
                 return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-metadata', params));
             },
-            /**
-             * repairContentDuplicates - POST /admin/branch-dirs/:dirName/repair-content-duplicates
-             */
+            /** POST /admin/branch-dirs/:dirName/repair-content-duplicates */
             repairContentDuplicates: (params) => {
                 return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-content-duplicates', params));
             },
-            /**
-             * status - GET /admin/status
-             */
+            /** GET /admin/status */
             status: () => {
                 return this.request('GET', '/admin/status');
             },
-            /**
-             * listTasks - GET /admin/tasks/:status
-             */
+            /** GET /admin/tasks/:status */
             listTasks: (params) => {
                 return this.request('GET', this.buildPath('/admin/tasks/:status', params));
             },
-            /**
-             * retryTask - POST /admin/tasks/:taskId/retry
-             */
+            /** POST /admin/tasks/:taskId/retry */
             retryTask: (params) => {
                 return this.request('POST', this.buildPath('/admin/tasks/:taskId/retry', params));
             },
-            /**
-             * deleteTask - DELETE /admin/tasks/:status/:fileName
-             */
+            /** DELETE /admin/tasks/:status/:fileName */
             deleteTask: (params) => {
                 return this.request('DELETE', this.buildPath('/admin/tasks/:status/:fileName', params));
             },
         };
         this.baseUrl = options.baseUrl ?? '/api/canopycms';
-        // Bind fetch to window to prevent "Illegal invocation" errors in browsers
-        // In Node.js tests, window is undefined so use fetch directly
+        // An unbound fetch throws "Illegal invocation" in browsers; Node has no window.
         this.fetchFn = options.fetch ?? (typeof window !== 'undefined' ? fetch.bind(window) : fetch);
+        this.onUnauthorized = options.onUnauthorized;
     }
-    // ========== Low-level HTTP methods ==========
     buildPath(template, params) {
         let result = template;
         const queryParams = {};
         for (const [key, value] of Object.entries(params)) {
-            // Check if this param is in the path template
             const pathParamPattern = `:${key}`;
             const restParamPattern = `...${key}`;
             if (result.includes(pathParamPattern)) {
@@ -432,15 +277,13 @@ export class CanopyApiClient {
                 result = result.replace(restParamPattern, encoded);
             }
             else {
-                // Not in path template, so it's a query param
                 queryParams[key] = value;
             }
         }
-        // Append query params if any
         if (Object.keys(queryParams).length > 0) {
             const queryString = Object.entries(queryParams)
                 .map(([key, value]) => {
-                // URL-encode with proper handling of spaces and special chars
+                // Spaces encode as '+' in the query string.
                 return `${encodeURIComponent(key)}=${encodeURIComponent(String(value)).replace(/%20/g, '+')}`;
             })
                 .join('&');
@@ -456,20 +299,18 @@ export class CanopyApiClient {
         let requestBody;
         if (body !== undefined) {
             if (body instanceof FormData) {
-                // Don't set Content-Type for FormData - browser will set it with boundary.
-                // NOTE: FormData bodies cannot carry an x-amz-content-sha256 hash (the
-                // multipart boundary is generated at send time), so requests with a
-                // FormData body will 403 behind the CloudFront OAC prod shape. See
+                // No Content-Type for FormData: the browser sets it with the boundary. A
+                // FormData body cannot carry x-amz-content-sha256 (the boundary is generated
+                // at send time), so it 403s behind the CloudFront OAC prod shape -- see
                 // docs/deploying-to-aws.md.
                 requestBody = body;
             }
             else {
                 requestHeaders['Content-Type'] = 'application/json';
                 requestBody = JSON.stringify(body);
-                // CloudFront's Origin Access Control signs origin requests but never
-                // hashes the payload itself - the viewer request must already carry
-                // x-amz-content-sha256 or the OAC-protected Lambda Function URL
-                // rejects the request with 403. Harmless on non-AWS deployments.
+                // CloudFront's OAC signs the origin request but never hashes the payload, so
+                // the viewer request must carry x-amz-content-sha256 or the OAC-protected
+                // Function URL returns 403. Harmless on non-AWS deployments.
                 const contentHash = await computeContentSha256Hex(requestBody);
                 if (contentHash) {
                     requestHeaders['x-amz-content-sha256'] = contentHash;
@@ -484,14 +325,22 @@ export class CanopyApiClient {
             init.body = requestBody;
         }
         const response = await this.fetchFn(url, init);
+        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 };
+        }
         const payload = await response.json();
         // All responses use ApiResponse format: { ok, status, data?, error? }
         return payload;
     }
 }
-/**
- * Create a new API client instance
- */
+/** Create a {@link CanopyApiClient}; pass a custom fetch for tests. */
 export function createApiClient(options) {
     return new CanopyApiClient(options);
 }

package/dist/api/comments.d.ts

@@ -8,7 +8,7 @@ export interface AddCommentBody {
     entryPath?: string;
     canopyPath?: string;
 }
-export interface ListCommentsResponse {
+interface ListCommentsResponse {
     threads: CommentThread[];
 }
 /** Response type for listing comments */
@@ -22,9 +22,6 @@ export type AddCommentResponse = ApiResponse<{
 export type ResolveCommentResponse = ApiResponse<{
     resolved: boolean;
 }>;
-/**
- * Exported routes for router registration
- */
 export declare const COMMENT_ROUTES: {
     readonly list: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
@@ -81,3 +78,4 @@ export declare const COMMENT_ROUTES: {
         threadId: string;
     }>, undefined, ResolveCommentResponse>;
 };
+export {};

package/dist/api/comments.js

@@ -54,7 +54,6 @@ const addCommentHandler = async (gc, _ctx, req, _params, body) => {
 const resolveCommentHandler = async (gc, _ctx, req, params) => {
     const { branchContext } = gc;
     const commentStore = new CommentStore(branchContext.branchRoot);
-    // Get the thread to check permissions
     const thread = await commentStore.getThread(params.threadId);
     if (!thread) {
         return { ok: false, status: 404, error: 'Thread not found' };
@@ -75,17 +74,9 @@ const resolveCommentHandler = async (gc, _ctx, req, params) => {
     }
     return { ok: true, status: 200, data: { resolved: true } };
 };
-// ============================================================================
-// Route Definitions with defineEndpoint
-// ============================================================================
-//
 // Deliberately no 'writableBranch' guard on any endpoint below: comments live
 // in .canopy-meta/comments.json, which is never committed to git. Commenting
 // while browsing the (read-only) protected base branch is desirable.
-/**
- * List all comment threads for a branch
- * GET /:branch/comments
- */
 const listComments = defineEndpoint({
     namespace: 'comments',
     name: 'list',
@@ -100,7 +91,6 @@ const listComments = defineEndpoint({
 });
 /**
  * Add a comment to a thread or create new thread
- * POST /:branch/comments
  */
 const addComment = defineEndpoint({
     namespace: 'comments',
@@ -116,10 +106,6 @@ const addComment = defineEndpoint({
     guards: ['branchAccess'],
     handler: addCommentHandler,
 });
-/**
- * Resolve a comment thread
- * POST /:branch/comments/:threadId/resolve
- */
 const resolveComment = defineEndpoint({
     namespace: 'comments',
     name: 'resolve',
@@ -132,9 +118,6 @@ const resolveComment = defineEndpoint({
     guards: ['branchAccess'],
     handler: resolveCommentHandler,
 });
-/**
- * Exported routes for router registration
- */
 export const COMMENT_ROUTES = {
     list: listComments,
     add: addComment,