canopycms 0.0.67-int.90 → 0.0.67

package/dist/api/branch.js

@@ -14,9 +14,6 @@ import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRA
 import { GitManager } from '../git-manager.js';
 import { branchNameSchema, branchParamSchema } from './validators.js';
 const log = createDebugLogger({ prefix: 'BranchAPI' });
-// ============================================================================
-// Zod Schemas for Validation
-// ============================================================================
 const createBranchBodySchema = z.object({
     branch: branchNameSchema,
     title: z.string().optional(),
@@ -35,33 +32,28 @@ const updateBranchAccessBodySchema = z.object({
 import { isPrivileged, isAdmin, loadPathPermissions, getBranchProtection, getBranchWriteProtection, } from '../authorization/index.js';
 import { operatingStrategy } from '../operating-mode/index.js';
 /**
- * Check if a user can create branches.
  * Returns true if:
  * - User is Admin or Reviewer (privileged)
  * - User has edit access to at least one path via pathPermissions rules
  * - No path permissions are defined (open access)
+ * @internal Exported for tests.
  */
 export const canCreateBranch = (user, pathPermissions) => {
-    // Admins and Reviewers can always create branches
     if (isPrivileged(user.groups)) {
         return { allowed: true, reason: 'privileged_user' };
     }
-    // If no path permissions defined, anyone can create branches
     if (pathPermissions.length === 0) {
         return { allowed: true, reason: 'no_restrictions' };
     }
-    // Check if user has edit access to at least one path rule
     for (const rule of pathPermissions) {
         const editTarget = rule.edit;
         if (!editTarget)
             continue;
-        // Check if rule has no user/group constraints (open to all)
         const hasUserConstraint = !!editTarget.allowedUsers?.length;
         const hasGroupConstraint = !!editTarget.allowedGroups?.length;
         if (!hasUserConstraint && !hasGroupConstraint) {
             return { allowed: true, reason: 'open_path_rule' };
         }
-        // Check if user matches the rule
         const matchesUser = hasUserConstraint && editTarget.allowedUsers?.includes(user.userId);
         const matchesGroup = hasGroupConstraint && user.groups?.some((gid) => editTarget.allowedGroups?.includes(gid));
         if (matchesUser || matchesGroup) {
@@ -95,6 +87,7 @@ const resolveReadOnlyMirrorPath = (ctx, strategy) => {
         process.env[remoteUrlConfig.envVarName] ??
         remoteUrlConfig.autoDetectRemotePath);
 };
+/** @internal Exported for tests. */
 export const createBranchHandler = async (ctx, req, body) => {
     return log.timed('api', 'createBranch', async () => {
         const branchName = body.branch;
@@ -312,7 +305,6 @@ export const createBranchHandler = async (ctx, req, body) => {
             const operatingMode = ctx.services.config.mode;
             pathPermissions = await loadPathPermissions(baseBranchContext.branchRoot, operatingMode);
         }
-        // Check if user can create branches
         const canCreate = canCreateBranch(req.user, pathPermissions);
         if (!canCreate.allowed) {
             log.debug('api', 'Permission denied', { reason: canCreate.reason });
@@ -336,6 +328,7 @@ export const createBranchHandler = async (ctx, req, body) => {
         return { ok: true, status: 200, data: { branch: context.branch } };
     });
 };
+/** @internal Exported for tests. */
 export const listBranchesHandler = async (ctx, req) => {
     if (!ctx.services.registry) {
         return {
@@ -400,21 +393,17 @@ export const listBranchesHandler = async (ctx, req) => {
         data: { branches: visibleBranches.map(toListItem), defaultBranch },
     };
 };
-/**
- * Check if a user can delete a specific branch.
- * Returns true if user is Admin or the branch creator.
- */
+/** @internal Exported for tests. */
 export const canDeleteBranch = (user, branchContext) => {
-    // Admins can delete any branch
     if (isAdmin(user.groups)) {
         return { allowed: true, reason: 'admin' };
     }
-    // Branch creator can delete their own branch
     if (branchContext.branch.createdBy === user.userId) {
         return { allowed: true, reason: 'creator' };
     }
     return { allowed: false, reason: 'not_authorized' };
 };
+/** @internal Exported for tests. */
 export const deleteBranchHandler = async (ctx, req, params) => {
     const branchName = params.branch;
     // Disallow delete in modes that don't support branching (branch = developer's git checkout)
@@ -426,7 +415,6 @@ export const deleteBranchHandler = async (ctx, req, params) => {
             error: 'Cannot delete branches in this operating mode',
         };
     }
-    // Get branch context
     const branchContext = await ctx.getBranchContext(branchName);
     if (!branchContext) {
         return { ok: false, status: 404, error: 'Branch not found' };
@@ -438,7 +426,6 @@ export const deleteBranchHandler = async (ctx, req, params) => {
     if (isProtected) {
         return { ok: false, status: 400, error: 'Cannot delete the base branch' };
     }
-    // Check permission
     const canDelete = canDeleteBranch(req.user, branchContext);
     if (!canDelete.allowed) {
         return {
@@ -577,24 +564,19 @@ export const deleteBranchHandler = async (ctx, req, params) => {
         data: { deleted: true, ...(cleanupWarning && { cleanupWarning }) },
     };
 };
-/**
- * Check if a user can modify branch access.
- * Returns true if user is Admin or the branch creator.
- */
+/** @internal Exported for tests. */
 export const canModifyBranchAccess = (user, branchContext) => {
-    // Admins can modify any branch
     if (isAdmin(user.groups)) {
         return { allowed: true, reason: 'admin' };
     }
-    // Branch creator can modify their own branch
     if (branchContext.branch.createdBy === user.userId) {
         return { allowed: true, reason: 'creator' };
     }
     return { allowed: false, reason: 'not_authorized' };
 };
+/** @internal Exported for tests. */
 export const updateBranchAccessHandler = async (ctx, req, params, body) => {
     const branchName = params.branch;
-    // Get branch context
     const branchContext = await ctx.getBranchContext(branchName);
     if (!branchContext) {
         return { ok: false, status: 404, error: 'Branch not found' };
@@ -612,7 +594,6 @@ export const updateBranchAccessHandler = async (ctx, req, params, body) => {
             error: 'The base branch does not take an access list. Create a branch to manage access.',
         };
     }
-    // Check permission
     const canModify = canModifyBranchAccess(req.user, branchContext);
     if (!canModify.allowed) {
         return {
@@ -645,12 +626,8 @@ export const updateBranchAccessHandler = async (ctx, req, params, body) => {
     });
     return { ok: true, status: 200, data: { branch: updated.branch } };
 };
-// ============================================================================
-// Route Definitions with defineEndpoint
-// ============================================================================
 /**
  * List all branches visible to current user
- * GET /branches
  */
 const listBranches = defineEndpoint({
     namespace: 'branches',
@@ -662,10 +639,6 @@ const listBranches = defineEndpoint({
     defaultMockData: { branches: [] },
     handler: listBranchesHandler,
 });
-/**
- * Create a new branch
- * POST /branches
- */
 const createBranch = defineEndpoint({
     namespace: 'branches',
     name: 'create',
@@ -687,10 +660,6 @@ const createBranch = defineEndpoint({
     },
     handler: createBranchHandler,
 });
-/**
- * Delete a branch
- * DELETE /:branch
- */
 const deleteBranch = defineEndpoint({
     namespace: 'branches',
     name: 'delete',
@@ -703,9 +672,6 @@ const deleteBranch = defineEndpoint({
     handler: deleteBranchHandler,
 });
 /**
- * Update branch access control
- * PATCH /:branch/access
- *
  * No 'writableBranch' guard: this rewrites branch.json's ACL, not branch
  * content, so a submitted branch's ACL stays editable during review. The base
  * branch is a different matter and IS refused -- the handler rejects protected
@@ -735,9 +701,6 @@ const updateBranchAccess = defineEndpoint({
     },
     handler: updateBranchAccessHandler,
 });
-/**
- * Exported routes for router registration
- */
 export const BRANCH_ROUTES = {
     list: listBranches,
     create: createBranch,

package/dist/api/client.d.ts

@@ -1,8 +1,9 @@
 /**
- * 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 type { BranchDeleteResponse, BranchListResponse, BranchResponse, CreateBranchBody, UpdateBranchAccessBody } from './branch.js';
 import type { BranchMergeResponse } from './branch-status.js';
@@ -18,319 +19,165 @@ import type { UserInfoResponse } from './user.js';
 import type { AddEntryTypeApiResponse, CreateCollectionApiResponse, DeleteCollectionApiResponse, GetCollectionApiResponse, GetSchemaApiResponse, InvalidateSchemaCacheApiResponse, RemoveEntryTypeApiResponse, UpdateCollectionApiResponse, UpdateEntryTypeApiResponse, UpdateOrderApiResponse, UpdateOrderBody } from './schema.js';
 import type { CreateCollectionInput, CreateEntryTypeInput, UpdateCollectionInput, UpdateEntryTypeInput } from './../schema/schema-store-types.js';
 import type { AdminDeleteTaskResponse, AdminRetryTaskResponse, AdminStatusResponse, AdminTasksResponse, BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse } from './admin.js';
-/**
- * Options for creating an ApiClient
- */
+/** Options for {@link createApiClient}. */
 export interface ApiClientOptions {
-    /**
-     * Base URL for API requests. Defaults to '/api/canopycms'
-     */
+    /** Base URL for API requests. Defaults to '/api/canopycms'. */
     baseUrl?: string;
+    /** Custom fetch implementation, e.g. a mock in tests. */
+    fetch?: typeof fetch;
     /**
-     * Custom fetch implementation (useful for testing)
+     * 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.
      */
-    fetch?: typeof fetch;
+    onUnauthorized?: () => void;
 }
 /**
- * Lightweight typed API client for CanopyCMS.
- *
- * Provides type-safe methods for all API endpoints with centralized
- * response unwrapping and error handling.
+ * Typed client for the CanopyCMS API: one method per endpoint, grouped by namespace, each
+ * returning that endpoint's ApiResponse.
  *
- * @example Browser usage
+ * @example
  * ```ts
- * const client = createApiClient()
- * const branches = await client.branches.list()
- * if (branches.ok) {
- *   console.log(branches.data.branches)
- * }
- * ```
- *
- * @example Test usage
- * ```ts
- * const client = createApiClient({
- *   fetch: mockFetch
- * })
+ * const branches = await createApiClient().branches.list()
+ * if (branches.ok) console.log(branches.data.branches)
  * ```
  */
 export declare class CanopyApiClient {
     private baseUrl;
     private fetchFn;
-    /**
-     * branches - Auto-generated methods
-     */
+    private onUnauthorized;
     readonly branches: {
-        /**
-         * list - GET /branches
-         */
+        /** GET /branches */
         list: () => Promise<BranchListResponse>;
-        /**
-         * create - POST /branches
-         */
+        /** POST /branches */
         create: (body: CreateBranchBody) => Promise<BranchResponse>;
-        /**
-         * delete - DELETE /:branch
-         */
+        /** DELETE /:branch */
         delete: (params: Record<string, string>) => Promise<BranchDeleteResponse>;
-        /**
-         * updateAccess - PATCH /:branch/access
-         */
+        /** PATCH /:branch/access */
         updateAccess: (params: Record<string, string>, body: UpdateBranchAccessBody) => Promise<BranchResponse>;
     };
-    /**
-     * workflow - Auto-generated methods
-     */
     readonly workflow: {
-        /**
-         * withdraw - POST /:branch/withdraw
-         */
+        /** POST /:branch/withdraw */
         withdraw: (params: Record<string, string>) => Promise<BranchResponse>;
-        /**
-         * requestChanges - POST /:branch/request-changes
-         */
+        /** POST /:branch/request-changes */
         requestChanges: (params: Record<string, string>) => Promise<BranchResponse>;
-        /**
-         * approve - POST /:branch/approve
-         */
+        /** POST /:branch/approve */
         approve: (params: Record<string, string>) => Promise<BranchResponse>;
-        /**
-         * markMerged - POST /:branch/mark-merged
-         */
+        /** POST /:branch/mark-merged */
         markMerged: (params: Record<string, string>) => Promise<BranchMergeResponse>;
-        /**
-         * getStatus - GET /:branch/status
-         */
+        /** GET /:branch/status */
         getStatus: (params: Record<string, string>) => Promise<BranchResponse>;
-        /**
-         * submit - POST /:branch/submit
-         */
+        /** POST /:branch/submit */
         submit: (params: Record<string, string>) => Promise<BranchResponse>;
     };
-    /**
-     * comments - Auto-generated methods
-     */
     readonly comments: {
-        /**
-         * list - GET /:branch/comments
-         */
+        /** GET /:branch/comments */
         list: (params: Record<string, string>) => Promise<CommentsResponse>;
-        /**
-         * add - POST /:branch/comments
-         */
+        /** POST /:branch/comments */
         add: (params: Record<string, string>, body: AddCommentBody) => Promise<AddCommentResponse>;
-        /**
-         * resolve - POST /:branch/comments/:threadId/resolve
-         */
+        /** POST /:branch/comments/:threadId/resolve */
         resolve: (params: Record<string, string>) => Promise<ResolveCommentResponse>;
     };
-    /**
-     * content - Auto-generated methods
-     */
     readonly content: {
-        /**
-         * read - GET /:branch/content/...path
-         */
+        /** GET /:branch/content/...path */
         read: (params: Record<string, string>) => Promise<ContentReadResponse>;
-        /**
-         * write - PUT /:branch/content/...path
-         */
+        /** PUT /:branch/content/...path */
         write: (params: Record<string, string>, body: WriteContentBody) => Promise<ContentWriteResponse>;
-        /**
-         * validateReferences - POST /:branch/validate-references/...path
-         */
+        /** POST /:branch/validate-references/...path */
         validateReferences: (params: Record<string, string>, body: ValidateReferencesBody) => Promise<ReferenceValidationResponse>;
-        /**
-         * renameEntry - PATCH /:branch/rename-entry/...path
-         */
+        /** PATCH /:branch/rename-entry/...path */
         renameEntry: (params: Record<string, string>, body: RenameEntryBody) => Promise<RenameEntryResponse>;
-        /**
-         * getReferenceOptions - GET /:branch/reference-options
-         */
+        /** GET /:branch/reference-options */
         getReferenceOptions: (params: Record<string, string>) => Promise<ReferenceOptionsResponse>;
-        /**
-         * resolveReferences - POST /:branch/resolve-references
-         */
+        /** POST /:branch/resolve-references */
         resolveReferences: (params: Record<string, string>, body: ResolveReferencesBody) => Promise<ResolveReferencesResponse>;
     };
-    /**
-     * entries - Auto-generated methods
-     */
     readonly entries: {
-        /**
-         * list - GET /:branch/entries
-         */
+        /** GET /:branch/entries */
         list: (params: Record<string, string>) => Promise<EntriesResponse>;
-        /**
-         * delete - DELETE /:branch/entries/...entryPath
-         */
+        /** DELETE /:branch/entries/...entryPath */
         delete: (params: Record<string, string>) => Promise<DeleteEntryResponse>;
     };
-    /**
-     * assets - Auto-generated methods
-     */
     readonly assets: {
-        /**
-         * presign - POST /assets/presign
-         */
+        /** POST /assets/presign */
         presign: (body: PresignAssetBody) => Promise<PresignAssetResponse>;
-        /**
-         * finalize - POST /assets/finalize
-         */
+        /** POST /assets/finalize */
         finalize: (body: FinalizeAssetBody) => Promise<FinalizeAssetResponse>;
-        /**
-         * 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: File, options?: {
             filename?: string;
         }) => Promise<FinalizeAssetResponse>;
-        /**
-         * list - GET /assets
-         */
+        /** GET /assets */
         list: (params: Record<string, string>) => Promise<AssetsListResponse>;
-        /**
-         * delete - DELETE /assets
-         */
+        /** DELETE /assets */
         delete: (params: Record<string, string>) => Promise<AssetDeleteResponse>;
     };
-    /**
-     * permissions - Auto-generated methods
-     */
     readonly permissions: {
-        /**
-         * get - GET /permissions
-         */
+        /** GET /permissions */
         get: () => Promise<PermissionsResponse>;
-        /**
-         * update - PUT /permissions
-         */
+        /** PUT /permissions */
         update: (body: UpdatePermissionsBody) => Promise<PermissionsResponse>;
-        /**
-         * searchUsers - GET /users/search
-         */
+        /** GET /users/search */
         searchUsers: (params: Record<string, string>) => Promise<SearchUsersResponse>;
-        /**
-         * listGroups - GET /groups
-         */
+        /** GET /groups */
         listGroups: () => Promise<ListGroupsResponse>;
-        /**
-         * getUserMetadata - GET /users/:userId
-         */
+        /** GET /users/:userId */
         getUserMetadata: (params: Record<string, string>) => Promise<GetUserMetadataResponse>;
     };
-    /**
-     * groups - Auto-generated methods
-     */
     readonly groups: {
-        /**
-         * getInternal - GET /groups/internal
-         */
+        /** GET /groups/internal */
         getInternal: () => Promise<InternalGroupsResponse>;
-        /**
-         * updateInternal - PUT /groups/internal
-         */
+        /** PUT /groups/internal */
         updateInternal: (body: UpdateInternalGroupsBody) => Promise<UpdateInternalGroupsResponse>;
-        /**
-         * searchExternal - GET /groups/search
-         */
+        /** GET /groups/search */
         searchExternal: (params: Record<string, string>) => Promise<ExternalGroupsResponse>;
     };
-    /**
-     * user - Auto-generated methods
-     */
     readonly user: {
-        /**
-         * whoami - GET /whoami
-         */
+        /** GET /whoami */
         whoami: () => Promise<UserInfoResponse>;
     };
-    /**
-     * schema - Auto-generated methods
-     */
     readonly schema: {
-        /**
-         * get - GET /:branch/schema
-         */
+        /** GET /:branch/schema */
         get: (params: Record<string, string>) => Promise<GetSchemaApiResponse>;
-        /**
-         * getCollection - GET /:branch/schema/collection/...collectionPath
-         */
+        /** GET /:branch/schema/collection/...collectionPath */
         getCollection: (params: Record<string, string>) => Promise<GetCollectionApiResponse>;
-        /**
-         * createCollection - POST /:branch/schema/collections
-         */
+        /** POST /:branch/schema/collections */
         createCollection: (params: Record<string, string>, body: CreateCollectionInput) => Promise<CreateCollectionApiResponse>;
-        /**
-         * updateCollection - PATCH /:branch/schema/collection/...collectionPath
-         */
+        /** PATCH /:branch/schema/collection/...collectionPath */
         updateCollection: (params: Record<string, string>, body: UpdateCollectionInput) => Promise<UpdateCollectionApiResponse>;
-        /**
-         * deleteCollection - DELETE /:branch/schema/collection/...collectionPath
-         */
+        /** DELETE /:branch/schema/collection/...collectionPath */
         deleteCollection: (params: Record<string, string>) => Promise<DeleteCollectionApiResponse>;
-        /**
-         * addEntryType - POST /:branch/schema/entry-types/...collectionPath
-         */
+        /** POST /:branch/schema/entry-types/...collectionPath */
         addEntryType: (params: Record<string, string>, body: CreateEntryTypeInput) => Promise<AddEntryTypeApiResponse>;
-        /**
-         * updateEntryType - PATCH /:branch/schema/entry-types/:entryTypeName/...collectionPath
-         */
+        /** PATCH /:branch/schema/entry-types/:entryTypeName/...collectionPath */
         updateEntryType: (params: Record<string, string>, body: UpdateEntryTypeInput) => Promise<UpdateEntryTypeApiResponse>;
-        /**
-         * removeEntryType - DELETE /:branch/schema/entry-types/:entryTypeName/...collectionPath
-         */
+        /** DELETE /:branch/schema/entry-types/:entryTypeName/...collectionPath */
         removeEntryType: (params: Record<string, string>) => Promise<RemoveEntryTypeApiResponse>;
-        /**
-         * updateOrder - PATCH /:branch/schema/order/...collectionPath
-         */
+        /** PATCH /:branch/schema/order/...collectionPath */
         updateOrder: (params: Record<string, string>, body: UpdateOrderBody) => Promise<UpdateOrderApiResponse>;
-        /**
-         * invalidateSchemaCache - POST /:branch/schema/invalidate-cache
-         */
+        /** POST /:branch/schema/invalidate-cache */
         invalidateSchemaCache: (params: Record<string, string>) => Promise<InvalidateSchemaCacheApiResponse>;
     };
-    /**
-     * admin - Auto-generated methods
-     */
     readonly admin: {
-        /**
-         * branchHealth - GET /admin/branch-health
-         */
+        /** GET /admin/branch-health */
         branchHealth: () => Promise<BranchHealthResponse>;
-        /**
-         * purgeBranchDir - POST /admin/branch-dirs/:dirName/purge
-         */
+        /** POST /admin/branch-dirs/:dirName/purge */
         purgeBranchDir: (params: Record<string, string>) => Promise<PurgeBranchDirResponse>;
-        /**
-         * repairBranchDir - POST /admin/branch-dirs/:dirName/repair-metadata
-         */
+        /** POST /admin/branch-dirs/:dirName/repair-metadata */
         repairBranchDir: (params: Record<string, string>) => Promise<RepairBranchDirResponse>;
-        /**
-         * repairContentDuplicates - POST /admin/branch-dirs/:dirName/repair-content-duplicates
-         */
+        /** POST /admin/branch-dirs/:dirName/repair-content-duplicates */
         repairContentDuplicates: (params: Record<string, string>) => Promise<RepairContentDuplicatesResponse>;
-        /**
-         * status - GET /admin/status
-         */
+        /** GET /admin/status */
         status: () => Promise<AdminStatusResponse>;
-        /**
-         * listTasks - GET /admin/tasks/:status
-         */
+        /** GET /admin/tasks/:status */
         listTasks: (params: Record<string, string>) => Promise<AdminTasksResponse>;
-        /**
-         * retryTask - POST /admin/tasks/:taskId/retry
-         */
+        /** POST /admin/tasks/:taskId/retry */
         retryTask: (params: Record<string, string>) => Promise<AdminRetryTaskResponse>;
-        /**
-         * deleteTask - DELETE /admin/tasks/:status/:fileName
-         */
+        /** DELETE /admin/tasks/:status/:fileName */
         deleteTask: (params: Record<string, string>) => Promise<AdminDeleteTaskResponse>;
     };
     constructor(options?: ApiClientOptions);
     private buildPath;
     private request;
 }
-/**
- * Create a new API client instance
- */
+/** Create a {@link CanopyApiClient}; pass a custom fetch for tests. */
 export declare function createApiClient(options?: ApiClientOptions): CanopyApiClient;