@aaronshaf/confluence-cli 0.1.15

package/src/lib/confluence-client/comment-operations.ts

@@ -0,0 +1,60 @@
+import { Effect, Schema } from 'effect';
+import { ApiError, AuthError, NetworkError, type RateLimitError } from '../errors.js';
+import { CommentsResponseSchema, type Comment, type CommentsResponse } from './types.js';
+
+/**
+ * Extract cursor from a Confluence API next-page link.
+ */
+function extractCursor(nextLink: string | undefined): string | undefined {
+  if (!nextLink) return undefined;
+  try {
+    const url = new URL(nextLink, 'https://placeholder.invalid');
+    return url.searchParams.get('cursor') ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Fetch one page of footer comments (Effect version).
+ */
+export function getFooterCommentsEffect(
+  baseUrl: string,
+  authHeader: string,
+  path: string,
+): Effect.Effect<CommentsResponse, ApiError | AuthError | NetworkError | RateLimitError> {
+  const url = `${baseUrl}/wiki/api/v2${path}`;
+  return Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        headers: { Authorization: authHeader, Accept: 'application/json' },
+      });
+      if (response.status === 401) throw new AuthError('Invalid credentials', 401);
+      if (!response.ok) throw new ApiError(`Request failed: ${response.status}`, response.status);
+      const data = await response.json();
+      return Schema.decodeUnknownSync(CommentsResponseSchema)(data);
+    },
+    catch: (e) => (e instanceof AuthError || e instanceof ApiError ? e : new NetworkError(String(e))),
+  });
+}
+
+/**
+ * Get all footer comments for a page with cursor pagination (async version).
+ */
+export async function getAllFooterComments(baseUrl: string, authHeader: string, pageId: string): Promise<Comment[]> {
+  const allComments: Comment[] = [];
+  let cursor: string | undefined;
+  do {
+    let path = `/pages/${pageId}/footer-comments?body-format=storage&limit=100`;
+    if (cursor) path += `&cursor=${encodeURIComponent(cursor)}`;
+    const url = `${baseUrl}/wiki/api/v2${path}`;
+    const response = await fetch(url, {
+      headers: { Authorization: authHeader, Accept: 'application/json' },
+    });
+    if (!response.ok) throw new ApiError(`Request failed: ${response.status}`, response.status);
+    const data = Schema.decodeUnknownSync(CommentsResponseSchema)(await response.json());
+    allComments.push(...data.results);
+    cursor = extractCursor(data._links?.next);
+  } while (cursor);
+  return allComments;
+}

package/src/lib/confluence-client/folder-operations.ts

@@ -0,0 +1,203 @@
+/**
+ * Folder API operations for Confluence
+ * Per ADR-0018 and ADR-0023
+ */
+
+import { Effect, pipe, Schedule, Schema } from 'effect';
+import {
+  ApiError,
+  AuthError,
+  FolderNotFoundError,
+  NetworkError,
+  PageNotFoundError,
+  RateLimitError,
+} from '../errors.js';
+import { FolderSchema, type CreateFolderRequest, type Folder } from './types.js';
+
+/**
+ * Retry configuration for rate limiting
+ */
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const rateLimitRetrySchedule = Schedule.exponential(BASE_DELAY_MS).pipe(
+  Schedule.jittered,
+  Schedule.whileInput((error: unknown) => error instanceof RateLimitError),
+  Schedule.upTo(MAX_RETRIES * BASE_DELAY_MS * 32),
+);
+
+/**
+ * Get a folder by ID (Effect version)
+ */
+export function getFolderEffect(
+  baseUrl: string,
+  authHeader: string,
+  folderId: string,
+): Effect.Effect<Folder, ApiError | AuthError | NetworkError | RateLimitError | FolderNotFoundError> {
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const url = `${baseUrl}/wiki/api/v2/folders/${folderId}`;
+      const response = await fetch(url, {
+        headers: { Authorization: authHeader, Accept: 'application/json' },
+      });
+
+      if (response.status === 404) throw new FolderNotFoundError(folderId);
+      if (response.status === 401) throw new AuthError('Invalid credentials', 401);
+      if (response.status === 403) throw new AuthError('Access denied', 403);
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+      if (!response.ok) throw new ApiError(`API error: ${response.status}`, response.status);
+
+      const data = await response.json();
+      return Schema.decodeUnknownSync(FolderSchema)(data);
+    },
+    catch: (error) => {
+      if (
+        error instanceof FolderNotFoundError ||
+        error instanceof AuthError ||
+        error instanceof ApiError ||
+        error instanceof RateLimitError
+      ) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(makeRequest, Effect.retry(rateLimitRetrySchedule));
+}
+
+/**
+ * Create a new folder (Effect version)
+ */
+export function createFolderEffect(
+  baseUrl: string,
+  authHeader: string,
+  request: CreateFolderRequest,
+): Effect.Effect<Folder, ApiError | AuthError | NetworkError | RateLimitError> {
+  const url = `${baseUrl}/wiki/api/v2/folders`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { Authorization: authHeader, Accept: 'application/json', 'Content-Type': 'application/json' },
+        body: JSON.stringify(request),
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+      if (response.status === 401) throw new AuthError('Invalid credentials', 401);
+      if (response.status === 403) throw new AuthError('Access denied', 403);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new ApiError(`API request failed: ${response.status} ${errorText}`, response.status);
+      }
+
+      return response.json();
+    },
+    catch: (error) => {
+      if (error instanceof RateLimitError || error instanceof AuthError || error instanceof ApiError) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(
+    makeRequest,
+    Effect.flatMap((data) =>
+      Schema.decodeUnknown(FolderSchema)(data).pipe(
+        Effect.mapError((e) => new ApiError(`Invalid response: ${e}`, 500)),
+      ),
+    ),
+    Effect.retry(rateLimitRetrySchedule),
+  );
+}
+
+/**
+ * Move a page to a new parent (Effect version)
+ * Uses v1 API: PUT /wiki/rest/api/content/{id}/move/{position}/{targetId}
+ * Returns void since response structure varies and is not needed by callers
+ */
+export function movePageEffect(
+  baseUrl: string,
+  authHeader: string,
+  pageId: string,
+  targetId: string,
+  position: 'append' | 'prepend' = 'append',
+): Effect.Effect<void, ApiError | AuthError | NetworkError | RateLimitError | PageNotFoundError> {
+  const url = `${baseUrl}/wiki/rest/api/content/${pageId}/move/${position}/${targetId}`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        method: 'PUT',
+        headers: { Authorization: authHeader, Accept: 'application/json', 'Content-Type': 'application/json' },
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+      if (response.status === 401) throw new AuthError('Invalid credentials', 401);
+      if (response.status === 403) throw new AuthError('Access denied', 403);
+      if (response.status === 404) throw new PageNotFoundError(pageId);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new ApiError(`API request failed: ${response.status} ${errorText}`, response.status);
+      }
+      // Response body not validated - structure varies when moving to folders vs pages
+    },
+    catch: (error) => {
+      if (
+        error instanceof RateLimitError ||
+        error instanceof AuthError ||
+        error instanceof ApiError ||
+        error instanceof PageNotFoundError
+      ) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(makeRequest, Effect.retry(rateLimitRetrySchedule));
+}
+
+/**
+ * Find a folder by title in a space using CQL search
+ */
+export async function findFolderByTitle(
+  baseUrl: string,
+  authHeader: string,
+  spaceKey: string,
+  title: string,
+  parentId?: string,
+): Promise<Folder | null> {
+  const escapedTitle = title.replace(/"/g, '\\"');
+  let cql = `type=folder AND space="${spaceKey}" AND title="${escapedTitle}"`;
+  if (parentId) cql += ` AND parent=${parentId}`;
+
+  const url = `${baseUrl}/wiki/rest/api/search?cql=${encodeURIComponent(cql)}&limit=10`;
+  const response = await fetch(url, { headers: { Authorization: authHeader, Accept: 'application/json' } });
+
+  if (!response.ok) return null;
+
+  const data = await response.json();
+  for (const result of data?.results || []) {
+    if (result.content?.type === 'folder' && result.content?.title === title) {
+      const content = result.content;
+      return {
+        id: content.id,
+        type: 'folder' as const,
+        title: content.title,
+        parentId: content.ancestors?.length > 0 ? content.ancestors[content.ancestors.length - 1]?.id : undefined,
+      };
+    }
+  }
+  return null;
+}

package/src/lib/confluence-client/index.ts

@@ -0,0 +1,47 @@
+export { ConfluenceClient } from './client.js';
+export type {
+  Attachment,
+  AttachmentsResponse,
+  Body,
+  Comment,
+  CommentsResponse,
+  ContentItem,
+  ContentTreeNode,
+  CreateFolderRequest,
+  CreatePageRequest,
+  Folder,
+  Label,
+  LabelsResponse,
+  Page,
+  PagesResponse,
+  PageTreeNode,
+  SearchResponse,
+  SearchResultItem,
+  Space,
+  SpacesResponse,
+  UpdatePageRequest,
+  User,
+  Version,
+} from './types.js';
+export {
+  AttachmentSchema,
+  AttachmentsResponseSchema,
+  BodySchema,
+  CommentSchema,
+  CommentsResponseSchema,
+  CreateFolderRequestSchema,
+  CreatePageRequestSchema,
+  FolderSchema,
+  isFolder,
+  LabelSchema,
+  LabelsResponseSchema,
+  PageSchema,
+  PagesResponseSchema,
+  SearchResponseSchema,
+  SearchResultItemSchema,
+  SpaceSchema,
+  SpacesResponseSchema,
+  UpdatePageRequestSchema,
+  UserSchema,
+  VersionSchema,
+} from './types.js';

package/src/lib/confluence-client/label-operations.ts

@@ -0,0 +1,102 @@
+/**
+ * Label operations for Confluence pages
+ */
+
+import { Effect, pipe, Schedule } from 'effect';
+import { ApiError, AuthError, NetworkError, RateLimitError } from '../errors.js';
+
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const rateLimitRetrySchedule = Schedule.exponential(BASE_DELAY_MS).pipe(
+  Schedule.jittered,
+  Schedule.whileInput((error: unknown) => error instanceof RateLimitError),
+  Schedule.upTo(MAX_RETRIES * BASE_DELAY_MS * 32),
+);
+
+/**
+ * Add a label to a page (Effect version)
+ * Uses POST /wiki/rest/api/content/{pageId}/label
+ */
+export function addLabelEffect(
+  baseUrl: string,
+  authHeader: string,
+  pageId: string,
+  labelName: string,
+): Effect.Effect<void, ApiError | AuthError | NetworkError | RateLimitError> {
+  const url = `${baseUrl}/wiki/rest/api/content/${pageId}/label`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          Authorization: authHeader,
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify([{ prefix: 'global', name: labelName }]),
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+
+      if (response.status === 401) throw new AuthError('Authentication failed', 401);
+      if (response.status === 403) throw new AuthError('Permission denied', 403);
+      if (!response.ok) throw new ApiError(`Failed to add label: ${await response.text()}`, response.status);
+    },
+    catch: (error) => {
+      if (error instanceof RateLimitError || error instanceof AuthError || error instanceof ApiError) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(makeRequest, Effect.retry(rateLimitRetrySchedule));
+}
+
+/**
+ * Remove a label from a page (Effect version)
+ * Uses DELETE /wiki/rest/api/content/{pageId}/label/{labelName}
+ */
+export function removeLabelEffect(
+  baseUrl: string,
+  authHeader: string,
+  pageId: string,
+  labelName: string,
+): Effect.Effect<void, ApiError | AuthError | NetworkError | RateLimitError> {
+  const url = `${baseUrl}/wiki/rest/api/content/${pageId}/label/${encodeURIComponent(labelName)}`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        method: 'DELETE',
+        headers: {
+          Authorization: authHeader,
+          Accept: 'application/json',
+        },
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+
+      if (response.status === 401) throw new AuthError('Authentication failed', 401);
+      if (response.status === 403) throw new AuthError('Permission denied', 403);
+      if (response.status !== 204 && !response.ok) {
+        throw new ApiError(`Failed to remove label: ${await response.text()}`, response.status);
+      }
+    },
+    catch: (error) => {
+      if (error instanceof RateLimitError || error instanceof AuthError || error instanceof ApiError) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(makeRequest, Effect.retry(rateLimitRetrySchedule));
+}

package/src/lib/confluence-client/page-operations.ts

@@ -0,0 +1,270 @@
+/**
+ * Page mutation operations for Confluence
+ * Extracted from client.ts for file size management
+ */
+
+import { Effect, pipe, Schedule, Schema } from 'effect';
+import {
+  ApiError,
+  AuthError,
+  NetworkError,
+  PageNotFoundError,
+  RateLimitError,
+  VersionConflictError,
+} from '../errors.js';
+import {
+  PageSchema,
+  type CreatePageRequest,
+  type Page,
+  type UpdatePageRequest,
+  type VersionConflictResponse,
+} from './types.js';
+
+/**
+ * Retry configuration for rate limiting
+ */
+const MAX_RETRIES = 5;
+const BASE_DELAY_MS = 1000;
+const rateLimitRetrySchedule = Schedule.exponential(BASE_DELAY_MS).pipe(
+  Schedule.jittered,
+  Schedule.whileInput((error: unknown) => error instanceof RateLimitError),
+  Schedule.upTo(MAX_RETRIES * BASE_DELAY_MS * 32),
+);
+
+/**
+ * Create a new page (Effect version)
+ */
+export function createPageEffect(
+  baseUrl: string,
+  authHeader: string,
+  request: CreatePageRequest,
+): Effect.Effect<Page, ApiError | AuthError | NetworkError | RateLimitError> {
+  const url = `${baseUrl}/wiki/api/v2/pages`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          Authorization: authHeader,
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(request),
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError(
+          'Rate limited by Confluence API',
+          retryAfter ? Number.parseInt(retryAfter, 10) : undefined,
+        );
+      }
+
+      if (response.status === 401) {
+        throw new AuthError('Invalid credentials. Please check your email and API token.', 401);
+      }
+
+      if (response.status === 403) {
+        throw new AuthError('Access denied. Please check your permissions.', 403);
+      }
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new ApiError(`API request failed: ${response.status} ${errorText}`, response.status);
+      }
+
+      return response.json();
+    },
+    catch: (error) => {
+      if (error instanceof RateLimitError || error instanceof AuthError || error instanceof ApiError) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(
+    makeRequest,
+    Effect.flatMap((data) =>
+      Schema.decodeUnknown(PageSchema)(data).pipe(Effect.mapError((e) => new ApiError(`Invalid response: ${e}`, 500))),
+    ),
+    Effect.retry(rateLimitRetrySchedule),
+  );
+}
+
+/**
+ * Update a page (Effect version)
+ * Uses PUT /wiki/api/v2/pages/{id} endpoint
+ */
+export function updatePageEffect(
+  baseUrl: string,
+  authHeader: string,
+  request: UpdatePageRequest,
+): Effect.Effect<
+  Page,
+  ApiError | AuthError | NetworkError | RateLimitError | PageNotFoundError | VersionConflictError
+> {
+  const url = `${baseUrl}/wiki/api/v2/pages/${request.id}`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        method: 'PUT',
+        headers: {
+          Authorization: authHeader,
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(request),
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError(
+          'Rate limited by Confluence API',
+          retryAfter ? Number.parseInt(retryAfter, 10) : undefined,
+        );
+      }
+
+      if (response.status === 401) {
+        throw new AuthError('Invalid credentials. Please check your email and API token.', 401);
+      }
+
+      if (response.status === 403) {
+        throw new AuthError('Access denied. Please check your permissions.', 403);
+      }
+
+      if (response.status === 404) {
+        throw new PageNotFoundError(request.id);
+      }
+
+      if (response.status === 409) {
+        // Version conflict - the remote version has changed
+        const errorData: VersionConflictResponse = await response.json().catch(() => ({}));
+        const remoteVersion = errorData?.version?.number ?? 0;
+        throw new VersionConflictError(request.version.number, remoteVersion);
+      }
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new ApiError(`API request failed: ${response.status} ${errorText}`, response.status);
+      }
+
+      return response.json();
+    },
+    catch: (error) => {
+      if (
+        error instanceof RateLimitError ||
+        error instanceof AuthError ||
+        error instanceof ApiError ||
+        error instanceof PageNotFoundError ||
+        error instanceof VersionConflictError
+      ) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(
+    makeRequest,
+    Effect.flatMap((data) =>
+      Schema.decodeUnknown(PageSchema)(data).pipe(Effect.mapError((e) => new ApiError(`Invalid response: ${e}`, 500))),
+    ),
+    Effect.retry(rateLimitRetrySchedule),
+  );
+}
+
+/**
+ * Set a content property on a page (Effect version)
+ */
+export function setContentPropertyEffect(
+  baseUrl: string,
+  authHeader: string,
+  pageId: string,
+  key: string,
+  value: unknown,
+): Effect.Effect<void, ApiError | AuthError | NetworkError | RateLimitError> {
+  const url = `${baseUrl}/wiki/api/v2/pages/${pageId}/properties`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          Authorization: authHeader,
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ key, value }),
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+
+      if (response.status === 401) throw new AuthError('Authentication failed', 401);
+      if (response.status === 403) throw new AuthError('Permission denied', 403);
+      if (!response.ok) throw new ApiError(`Failed to set content property: ${await response.text()}`, response.status);
+    },
+    catch: (error) => {
+      if (error instanceof RateLimitError || error instanceof AuthError || error instanceof ApiError) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(makeRequest, Effect.retry(rateLimitRetrySchedule));
+}
+
+/**
+ * Delete a page (Effect version)
+ * Uses DELETE /wiki/api/v2/pages/{id} endpoint
+ */
+export function deletePageEffect(
+  baseUrl: string,
+  authHeader: string,
+  pageId: string,
+): Effect.Effect<void, ApiError | AuthError | NetworkError | RateLimitError | PageNotFoundError> {
+  const url = `${baseUrl}/wiki/api/v2/pages/${pageId}`;
+
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url, {
+        method: 'DELETE',
+        headers: {
+          Authorization: authHeader,
+          Accept: 'application/json',
+        },
+      });
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+
+      if (response.status === 401) throw new AuthError('Authentication failed', 401);
+      if (response.status === 403) throw new AuthError('Permission denied', 403);
+      if (response.status === 404) throw new PageNotFoundError(pageId);
+      if (response.status !== 204 && !response.ok) {
+        throw new ApiError(`Failed to delete page: ${await response.text()}`, response.status);
+      }
+    },
+    catch: (error) => {
+      if (
+        error instanceof RateLimitError ||
+        error instanceof AuthError ||
+        error instanceof ApiError ||
+        error instanceof PageNotFoundError
+      ) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(makeRequest, Effect.retry(rateLimitRetrySchedule));
+}