@knpkv/confluence-to-markdown 0.2.0 → 0.4.1

package/src/ConfluenceClient.ts

@@ -1,19 +1,26 @@
 /**
  * Confluence REST API v2 client service.
  *
+ * Wraps @knpkv/confluence-api-client with rate limit retry logic and pagination helpers.
+ *
  * @module
  */
 import * as HttpClient from "@effect/platform/HttpClient"
-import * as HttpClientRequest from "@effect/platform/HttpClientRequest"
+import {
+  ConfluenceApiClient,
+  ConfluenceApiConfig,
+  type V1ApiError,
+  type V2ApiError
+} from "@knpkv/confluence-api-client"
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
+import * as Redacted from "effect/Redacted"
 import * as Schedule from "effect/Schedule"
-import * as Schema from "effect/Schema"
 import type { PageId } from "./Brand.js"
-import { ApiError, RateLimitError } from "./ConfluenceError.js"
-import type { PageChildrenResponse, PageListItem, PageResponse } from "./Schemas.js"
-import { PageChildrenResponseSchema, PageResponseSchema } from "./Schemas.js"
+import type { RateLimitError } from "./ConfluenceError.js"
+import { ApiError } from "./ConfluenceError.js"
+import type { AtlassianUser, PageChildrenResponse, PageListItem, PageResponse, PageVersion } from "./Schemas.js"
 
 /**
  * Request to create a new page.
@@ -100,6 +107,30 @@ export class ConfluenceClient extends Context.Tag(
      * Delete a page.
      */
     readonly deletePage: (id: PageId) => Effect.Effect<void, ApiError | RateLimitError>
+
+    /**
+     * Get version history for a page.
+     */
+    readonly getPageVersions: (
+      id: PageId,
+      options?: { since?: number; includeBody?: boolean }
+    ) => Effect.Effect<ReadonlyArray<PageVersion>, ApiError | RateLimitError>
+
+    /**
+     * Get user info by account ID.
+     */
+    readonly getUser: (accountId: string) => Effect.Effect<AtlassianUser, ApiError | RateLimitError>
+
+    /**
+     * Get space ID for a page.
+     */
+    readonly getSpaceId: (pageId: PageId) => Effect.Effect<string, ApiError | RateLimitError>
+
+    /**
+     * Set editor version for a page (v1 or v2).
+     * Uses V1 API to set page property.
+     */
+    readonly setEditorVersion: (pageId: PageId, version: "v1" | "v2") => Effect.Effect<void, ApiError | RateLimitError>
   }
 >() {}
 
@@ -117,9 +148,16 @@ export interface ConfluenceClientConfig {
   } | {
     readonly type: "oauth2"
     readonly accessToken: string
+    readonly cloudId: string
   }
 }
 
+/** Maximum pagination iterations to prevent infinite loops */
+const MAX_PAGINATION_ITERATIONS = 100
+
+/** Default page size for version fetching */
+const VERSIONS_PAGE_SIZE = 50
+
 /**
  * Rate limit retry schedule with exponential backoff.
  */
@@ -129,6 +167,17 @@ const rateLimitSchedule = Schedule.exponential("1 second").pipe(
   Schedule.intersect(Schedule.recurs(3))
 )
 
+/**
+ * Map API client errors to domain errors.
+ */
+const mapApiError = (error: V1ApiError | V2ApiError, endpoint: string, pageId?: string): ApiError =>
+  new ApiError({
+    status: error.status,
+    message: error.message,
+    endpoint,
+    ...(pageId !== undefined && { pageId })
+  })
+
 /**
  * Create the Confluence client service.
  */
@@ -136,168 +185,128 @@ const make = (
   config: ConfluenceClientConfig
 ): Effect.Effect<Context.Tag.Service<typeof ConfluenceClient>, never, HttpClient.HttpClient> =>
   Effect.gen(function*() {
-    const httpClient = yield* HttpClient.HttpClient
+    // Create underlying API client
+    const apiConfigLayer = Layer.succeed(ConfluenceApiConfig, {
+      baseUrl: config.baseUrl,
+      auth: config.auth.type === "token"
+        ? { type: "basic", email: config.auth.email, apiToken: Redacted.make(config.auth.token) }
+        : { type: "oauth2", accessToken: Redacted.make(config.auth.accessToken), cloudId: config.auth.cloudId }
+    })
 
-    const authHeader = config.auth.type === "token"
-      ? `Basic ${Buffer.from(`${config.auth.email}:${config.auth.token}`).toString("base64")}`
-      : `Bearer ${config.auth.accessToken}`
+    const httpClient = yield* HttpClient.HttpClient
 
-    const baseRequest = HttpClientRequest.get(`${config.baseUrl}/wiki/api/v2`).pipe(
-      HttpClientRequest.setHeader("Authorization", authHeader),
-      HttpClientRequest.setHeader("Accept", "application/json"),
-      HttpClientRequest.setHeader("Content-Type", "application/json")
+    const apiClient = yield* ConfluenceApiClient.pipe(
+      Effect.provide(ConfluenceApiClient.layer),
+      Effect.provide(apiConfigLayer),
+      Effect.provide(Layer.succeed(HttpClient.HttpClient, httpClient))
     )
 
-    /**
-     * Make an HTTP request to the Confluence API.
-     * Returns raw JSON - callers must validate with Schema.decodeUnknown.
-     */
-    const request = (
-      method: "GET" | "POST" | "PUT" | "DELETE",
-      path: string,
-      body?: unknown
-    ): Effect.Effect<unknown, ApiError | RateLimitError, never> =>
-      Effect.gen(function*() {
-        let req = baseRequest.pipe(
-          HttpClientRequest.setMethod(method),
-          HttpClientRequest.setUrl(`${config.baseUrl}/wiki/api/v2${path}`)
-        )
-
-        if (body !== undefined) {
-          req = HttpClientRequest.bodyJson(req, body).pipe(
-            Effect.catchAll(() => Effect.succeed(req)),
-            Effect.runSync
-          )
-        }
-
-        const response = yield* httpClient.execute(req).pipe(
-          Effect.mapError((error) =>
-            new ApiError({
-              status: 0,
-              message: `Request failed: ${error.message}`,
-              endpoint: path
-            })
-          )
-        )
-
-        if (response.status === 429) {
-          const retryAfterHeader = response.headers["retry-after"]
-          const retryAfter = retryAfterHeader ? parseInt(retryAfterHeader, 10) : undefined
-          return yield* Effect.fail(
-            retryAfter !== undefined
-              ? new RateLimitError({ retryAfter })
-              : new RateLimitError({})
-          )
-        }
-
-        if (response.status >= 400) {
-          const text = yield* response.text.pipe(
-            Effect.catchAll(() => Effect.succeed(""))
-          )
-          return yield* Effect.fail(
-            new ApiError({
-              status: response.status,
-              message: text || `HTTP ${response.status}`,
-              endpoint: path
-            })
-          )
-        }
-
-        if (method === "DELETE" && response.status === 204) {
-          return undefined
-        }
-
-        const json = yield* response.json.pipe(
-          Effect.mapError((error) =>
-            new ApiError({
-              status: response.status,
-              message: `Failed to parse response: ${error}`,
-              endpoint: path
-            })
-          )
-        )
-
-        return json
-      }).pipe(
-        Effect.retry(rateLimitSchedule)
-      )
-
     const getPage = (id: PageId): Effect.Effect<PageResponse, ApiError | RateLimitError> =>
-      Effect.gen(function*() {
-        const raw = yield* request(
-          "GET",
-          `/pages/${id}?body-format=storage`
-        )
-        return yield* Schema.decodeUnknown(PageResponseSchema)(raw).pipe(
-          Effect.mapError((error) =>
-            new ApiError({
-              status: 0,
-              message: `Invalid response schema: ${error.message}`,
-              endpoint: `/pages/${id}`,
-              pageId: id
-            })
-          )
-        )
-      })
+      apiClient.v2.getPageById(id, { bodyFormat: "storage" }).pipe(
+        Effect.mapError((e) => mapApiError(e, `/pages/${id}`, id)),
+        Effect.retry(rateLimitSchedule)
+      ) as Effect.Effect<PageResponse, ApiError | RateLimitError>
 
     const getChildren = (id: PageId): Effect.Effect<PageChildrenResponse, ApiError | RateLimitError> =>
-      Effect.gen(function*() {
-        const raw = yield* request(
-          "GET",
-          `/pages/${id}/children?body-format=storage`
-        )
-        return yield* Schema.decodeUnknown(PageChildrenResponseSchema)(raw).pipe(
-          Effect.mapError((error) =>
-            new ApiError({
-              status: 0,
-              message: `Invalid response schema: ${error.message}`,
-              endpoint: `/pages/${id}/children`,
-              pageId: id
-            })
-          )
-        )
-      })
+      apiClient.v2.getPageChildren(id, { bodyFormat: "storage" }).pipe(
+        Effect.mapError((e) => mapApiError(e, `/pages/${id}/children`, id)),
+        Effect.retry(rateLimitSchedule)
+      ) as Effect.Effect<PageChildrenResponse, ApiError | RateLimitError>
 
     const getAllChildren = (id: PageId): Effect.Effect<ReadonlyArray<PageListItem>, ApiError | RateLimitError> =>
       Effect.gen(function*() {
         const allChildren: Array<PageListItem> = []
         let cursor: string | undefined
         let iterations = 0
-        const maxIterations = 100 // Prevent unbounded pagination
 
         do {
-          if (iterations >= maxIterations) {
+          if (iterations >= MAX_PAGINATION_ITERATIONS) {
             return yield* Effect.fail(
               new ApiError({
                 status: 0,
-                message: `Pagination limit exceeded: more than ${maxIterations} pages of children`,
+                message: `Pagination limit exceeded: more than ${MAX_PAGINATION_ITERATIONS} pages of children`,
                 endpoint: `/pages/${id}/children`,
                 pageId: id
               })
             )
           }
 
-          const path = cursor
-            ? `/pages/${id}/children?body-format=storage&cursor=${cursor}`
-            : `/pages/${id}/children?body-format=storage`
+          const response = yield* apiClient.v2.getPageChildren(id, {
+            bodyFormat: "storage",
+            cursor
+          }).pipe(
+            Effect.mapError((e) => mapApiError(e, `/pages/${id}/children`, id)),
+            Effect.retry(rateLimitSchedule)
+          )
+
+          for (const child of response.results) {
+            allChildren.push(child as PageListItem)
+          }
+
+          cursor = response._links?.next
+            ? new URL(response._links.next, config.baseUrl).searchParams.get("cursor") ?? undefined
+            : undefined
+
+          iterations++
+        } while (cursor)
+
+        return allChildren
+      })
+
+    const createPage = (req: CreatePageRequest): Effect.Effect<PageResponse, ApiError | RateLimitError> =>
+      apiClient.v2.createPage(req).pipe(
+        Effect.mapError((e) => mapApiError(e, "/pages")),
+        Effect.retry(rateLimitSchedule)
+      ) as Effect.Effect<PageResponse, ApiError | RateLimitError>
 
-          const raw = yield* request("GET", path)
-          const response = yield* Schema.decodeUnknown(PageChildrenResponseSchema)(raw).pipe(
-            Effect.mapError((error) =>
+    const updatePage = (req: UpdatePageRequest): Effect.Effect<PageResponse, ApiError | RateLimitError> =>
+      apiClient.v2.updatePage(req.id, req).pipe(
+        Effect.mapError((e) => mapApiError(e, `/pages/${req.id}`, req.id)),
+        Effect.retry(rateLimitSchedule)
+      ) as Effect.Effect<PageResponse, ApiError | RateLimitError>
+
+    const deletePage = (id: PageId): Effect.Effect<void, ApiError | RateLimitError> =>
+      apiClient.v2.deletePage(id).pipe(
+        Effect.mapError((e) => mapApiError(e, `/pages/${id}`, id)),
+        Effect.retry(rateLimitSchedule)
+      )
+
+    const getPageVersions = (
+      id: PageId,
+      options?: { since?: number; includeBody?: boolean }
+    ): Effect.Effect<ReadonlyArray<PageVersion>, ApiError | RateLimitError> =>
+      Effect.gen(function*() {
+        const allVersions: Array<PageVersion> = []
+        let cursor: string | undefined
+        let iterations = 0
+
+        do {
+          if (iterations >= MAX_PAGINATION_ITERATIONS) {
+            return yield* Effect.fail(
               new ApiError({
                 status: 0,
-                message: `Invalid response schema: ${error.message}`,
-                endpoint: path,
+                message: `Pagination limit exceeded: more than ${MAX_PAGINATION_ITERATIONS} pages of versions`,
+                endpoint: `/pages/${id}/versions`,
                 pageId: id
               })
             )
+          }
+
+          const response = yield* apiClient.v2.getPageVersions(id, {
+            bodyFormat: options?.includeBody ? "storage" : undefined,
+            cursor,
+            limit: VERSIONS_PAGE_SIZE
+          }).pipe(
+            Effect.mapError((e) => mapApiError(e, `/pages/${id}/versions`, id)),
+            Effect.retry(rateLimitSchedule)
           )
 
-          for (const child of response.results) {
-            allChildren.push(child)
+          for (const version of response.results) {
+            if (options?.since === undefined || (version.number ?? 0) > options.since) {
+              allVersions.push(version as PageVersion)
+            }
           }
 
-          // Extract cursor from next link if present
           cursor = response._links?.next
             ? new URL(response._links.next, config.baseUrl).searchParams.get("cursor") ?? undefined
             : undefined
@@ -305,40 +314,59 @@ const make = (
           iterations++
         } while (cursor)
 
-        return allChildren
+        return allVersions
       })
 
-    const createPage = (req: CreatePageRequest): Effect.Effect<PageResponse, ApiError | RateLimitError> =>
+    const getUser = (accountId: string): Effect.Effect<AtlassianUser, ApiError | RateLimitError> =>
+      apiClient.v1.getUser({ accountId }).pipe(
+        Effect.mapError((e) => mapApiError(e, `/user?accountId=${accountId}`)),
+        Effect.retry(rateLimitSchedule)
+      ) as Effect.Effect<AtlassianUser, ApiError | RateLimitError>
+
+    const getSpaceId = (pageId: PageId): Effect.Effect<string, ApiError | RateLimitError> =>
       Effect.gen(function*() {
-        const raw = yield* request("POST", "/pages", req)
-        return yield* Schema.decodeUnknown(PageResponseSchema)(raw).pipe(
-          Effect.mapError((error) =>
+        const page = yield* getPage(pageId)
+        if (!page.spaceId) {
+          return yield* Effect.fail(
             new ApiError({
               status: 0,
-              message: `Invalid response schema: ${error.message}`,
-              endpoint: "/pages"
+              message: `Page ${pageId} does not have spaceId`,
+              endpoint: `/pages/${pageId}`,
+              pageId
             })
           )
-        )
+        }
+        return page.spaceId
       })
 
-    const updatePage = (req: UpdatePageRequest): Effect.Effect<PageResponse, ApiError | RateLimitError> =>
+    const setEditorVersion = (pageId: PageId, version: "v1" | "v2"): Effect.Effect<void, ApiError | RateLimitError> =>
       Effect.gen(function*() {
-        const raw = yield* request("PUT", `/pages/${req.id}`, req)
-        return yield* Schema.decodeUnknown(PageResponseSchema)(raw).pipe(
-          Effect.mapError((error) =>
-            new ApiError({
-              status: 0,
-              message: `Invalid response schema: ${error.message}`,
-              endpoint: `/pages/${req.id}`,
-              pageId: req.id
-            })
-          )
+        // Try to get current property version, only treat 404 as "not exists"
+        const propertyVersion = yield* apiClient.v1.getContentProperty(pageId, "editor").pipe(
+          Effect.map((prop) => prop.version.number + 1),
+          Effect.catchIf(
+            (e) => e.status === 404,
+            () => Effect.succeed(1)
+          ),
+          Effect.mapError((e) => mapApiError(e, `/content/${pageId}/property/editor`, pageId))
         )
-      })
 
-    const deletePage = (id: PageId): Effect.Effect<void, ApiError | RateLimitError> =>
-      request("DELETE", `/pages/${id}`).pipe(Effect.asVoid)
+        const payload = {
+          key: "editor",
+          value: version,
+          version: { number: propertyVersion }
+        }
+
+        if (propertyVersion === 1) {
+          yield* apiClient.v1.createContentProperty(pageId, { payload }).pipe(
+            Effect.mapError((e) => mapApiError(e, `/content/${pageId}/property/editor`, pageId))
+          )
+        } else {
+          yield* apiClient.v1.updateContentProperty(pageId, "editor", { payload }).pipe(
+            Effect.mapError((e) => mapApiError(e, `/content/${pageId}/property/editor`, pageId))
+          )
+        }
+      }).pipe(Effect.retry(rateLimitSchedule))
 
     return ConfluenceClient.of({
       getPage,
@@ -346,7 +374,11 @@ const make = (
       getAllChildren,
       createPage,
       updatePage,
-      deletePage
+      deletePage,
+      getPageVersions,
+      getUser,
+      getSpaceId,
+      setEditorVersion
     })
   })
 

package/src/ConfluenceConfig.ts

@@ -46,13 +46,22 @@ export class ConfluenceConfig extends Context.Tag(
     readonly docsPath: string
     /** Glob patterns to exclude */
     readonly excludePatterns: ReadonlyArray<string>
+    /** Save original Confluence HTML alongside markdown */
+    readonly saveSource: boolean
+    /** Glob patterns for files to track in git */
+    readonly trackedPaths: ReadonlyArray<string>
   }
 >() {}
 
+/**
+ * Default config directory.
+ */
+const CONFIG_DIR = ".confluence"
+
 /**
  * Default config file name.
  */
-const CONFIG_FILE_NAME = ".confluence.json"
+const CONFIG_FILE_NAME = "config.json"
 
 /**
  * Load configuration from a file.
@@ -108,6 +117,35 @@ const loadConfig = (
  *
  * @category Layers
  */
+/**
+ * Validate docsPath configuration.
+ * docsPath must be either:
+ * - ".confluence/docs" (default, files in git repo)
+ * - A path outside ".confluence/" (external docs directory)
+ * NOT: ".confluence/other" which would cause confusion
+ */
+const validateDocsPath = (
+  docsPath: string,
+  configPath: string
+): Effect.Effect<void, ConfigParseError> => {
+  const isDefault = docsPath === ".confluence/docs"
+  const isInsideConfluence = docsPath.startsWith(".confluence/") || docsPath.startsWith(".confluence\\")
+  const isOutside = !isInsideConfluence
+
+  if (isDefault || isOutside) {
+    return Effect.void
+  }
+
+  // docsPath is inside .confluence/ but not the default - this is invalid
+  return Effect.fail(
+    new ConfigParseError({
+      path: configPath,
+      cause:
+        `Invalid docsPath "${docsPath}". Must be either ".confluence/docs" (default) or a path outside ".confluence/" (e.g., "docs" for external docs).`
+    })
+  )
+}
+
 export const layer = (
   configPath?: string
 ): Layer.Layer<ConfluenceConfig, ConfigNotFoundError | ConfigParseError, FileSystem.FileSystem | Path.Path> =>
@@ -115,15 +153,20 @@ export const layer = (
     ConfluenceConfig,
     Effect.gen(function*() {
       const path = yield* Path.Path
-      const resolvedPath = configPath ?? path.join(process.cwd(), CONFIG_FILE_NAME)
+      const resolvedPath = configPath ?? path.join(process.cwd(), CONFIG_DIR, CONFIG_FILE_NAME)
       const config = yield* loadConfig(resolvedPath)
 
+      // Validate docsPath
+      yield* validateDocsPath(config.docsPath, resolvedPath)
+
       return ConfluenceConfig.of({
         rootPageId: config.rootPageId,
         baseUrl: config.baseUrl,
         ...(config.spaceKey !== undefined ? { spaceKey: config.spaceKey } : {}),
         docsPath: config.docsPath,
-        excludePatterns: config.excludePatterns
+        excludePatterns: config.excludePatterns,
+        saveSource: config.saveSource,
+        trackedPaths: config.trackedPaths
       })
     })
   )
@@ -143,7 +186,9 @@ export const layerFromValues = (
       baseUrl: config.baseUrl,
       ...(config.spaceKey !== undefined ? { spaceKey: config.spaceKey } : {}),
       docsPath: config.docsPath,
-      excludePatterns: config.excludePatterns
+      excludePatterns: config.excludePatterns,
+      saveSource: config.saveSource,
+      trackedPaths: config.trackedPaths
     })
   )
 
@@ -161,13 +206,16 @@ export const createConfigFile = (
     const fs = yield* FileSystem.FileSystem
     const pathService = yield* Path.Path
 
-    const resolvedPath = configPath ?? pathService.join(process.cwd(), CONFIG_FILE_NAME)
+    const configDir = pathService.join(process.cwd(), CONFIG_DIR)
+    const resolvedPath = configPath ?? pathService.join(configDir, CONFIG_FILE_NAME)
 
     const config: ConfluenceConfigFile = {
       rootPageId: rootPageId as PageId,
       baseUrl,
-      docsPath: ".docs/confluence",
-      excludePatterns: []
+      docsPath: ".confluence/docs",
+      excludePatterns: [],
+      saveSource: false,
+      trackedPaths: ["**/*.md"]
     }
 
     // Validate the config
@@ -175,6 +223,14 @@ export const createConfigFile = (
       Effect.mapError((cause) => new ConfigParseError({ path: resolvedPath, cause }))
     )
 
+    // Create .confluence directory if it doesn't exist
+    const dirExists = yield* fs.exists(configDir).pipe(Effect.catchAll(() => Effect.succeed(false)))
+    if (!dirExists) {
+      yield* fs.makeDirectory(configDir, { recursive: true }).pipe(
+        Effect.mapError((cause) => new ConfigParseError({ path: configDir, cause }))
+      )
+    }
+
     const content = JSON.stringify(config, null, 2)
     yield* fs.writeFileString(resolvedPath, content).pipe(
       Effect.mapError((cause) => new ConfigParseError({ path: resolvedPath, cause }))