@knpkv/confluence-to-markdown 0.2.0

package/src/ConfluenceClient.ts

@@ -0,0 +1,387 @@
+/**
+ * Confluence REST API v2 client service.
+ *
+ * @module
+ */
+import * as HttpClient from "@effect/platform/HttpClient"
+import * as HttpClientRequest from "@effect/platform/HttpClientRequest"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+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"
+
+/**
+ * Request to create a new page.
+ *
+ * @category Types
+ */
+export interface CreatePageRequest {
+  readonly spaceId: string
+  readonly title: string
+  readonly parentId?: string
+  readonly body: {
+    readonly representation: "storage"
+    readonly value: string
+  }
+}
+
+/**
+ * Request to update an existing page.
+ *
+ * @category Types
+ */
+export interface UpdatePageRequest {
+  readonly id: string
+  readonly title: string
+  readonly status?: "current" | "draft"
+  readonly version: {
+    readonly number: number
+    readonly message?: string
+  }
+  readonly body: {
+    readonly representation: "storage"
+    readonly value: string
+  }
+}
+
+/**
+ * Confluence REST API v2 client service.
+ *
+ * @example
+ * ```typescript
+ * import { ConfluenceClient } from "@knpkv/confluence-to-markdown/ConfluenceClient"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const client = yield* ConfluenceClient
+ *   const page = yield* client.getPage("12345")
+ *   console.log(page.title)
+ * })
+ * ```
+ *
+ * @category Client
+ */
+export class ConfluenceClient extends Context.Tag(
+  "@knpkv/confluence-to-markdown/ConfluenceClient"
+)<
+  ConfluenceClient,
+  {
+    /**
+     * Get a page by ID.
+     */
+    readonly getPage: (id: PageId) => Effect.Effect<PageResponse, ApiError | RateLimitError>
+
+    /**
+     * Get children of a page.
+     */
+    readonly getChildren: (id: PageId) => Effect.Effect<PageChildrenResponse, ApiError | RateLimitError>
+
+    /**
+     * Get all children recursively (handles pagination).
+     */
+    readonly getAllChildren: (id: PageId) => Effect.Effect<ReadonlyArray<PageListItem>, ApiError | RateLimitError>
+
+    /**
+     * Create a new page.
+     */
+    readonly createPage: (request: CreatePageRequest) => Effect.Effect<PageResponse, ApiError | RateLimitError>
+
+    /**
+     * Update an existing page.
+     */
+    readonly updatePage: (request: UpdatePageRequest) => Effect.Effect<PageResponse, ApiError | RateLimitError>
+
+    /**
+     * Delete a page.
+     */
+    readonly deletePage: (id: PageId) => Effect.Effect<void, ApiError | RateLimitError>
+  }
+>() {}
+
+/**
+ * Configuration for the Confluence client.
+ *
+ * @category Config
+ */
+export interface ConfluenceClientConfig {
+  readonly baseUrl: string
+  readonly auth: {
+    readonly type: "token"
+    readonly email: string
+    readonly token: string
+  } | {
+    readonly type: "oauth2"
+    readonly accessToken: string
+  }
+}
+
+/**
+ * Rate limit retry schedule with exponential backoff.
+ */
+const rateLimitSchedule = Schedule.exponential("1 second").pipe(
+  Schedule.union(Schedule.spaced("30 seconds")),
+  Schedule.whileInput<RateLimitError | ApiError>((error) => error._tag === "RateLimitError"),
+  Schedule.intersect(Schedule.recurs(3))
+)
+
+/**
+ * Create the Confluence client service.
+ */
+const make = (
+  config: ConfluenceClientConfig
+): Effect.Effect<Context.Tag.Service<typeof ConfluenceClient>, never, HttpClient.HttpClient> =>
+  Effect.gen(function*() {
+    const httpClient = yield* HttpClient.HttpClient
+
+    const authHeader = config.auth.type === "token"
+      ? `Basic ${Buffer.from(`${config.auth.email}:${config.auth.token}`).toString("base64")}`
+      : `Bearer ${config.auth.accessToken}`
+
+    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")
+    )
+
+    /**
+     * 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
+            })
+          )
+        )
+      })
+
+    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
+            })
+          )
+        )
+      })
+
+    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) {
+            return yield* Effect.fail(
+              new ApiError({
+                status: 0,
+                message: `Pagination limit exceeded: more than ${maxIterations} 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 raw = yield* request("GET", path)
+          const response = yield* Schema.decodeUnknown(PageChildrenResponseSchema)(raw).pipe(
+            Effect.mapError((error) =>
+              new ApiError({
+                status: 0,
+                message: `Invalid response schema: ${error.message}`,
+                endpoint: path,
+                pageId: id
+              })
+            )
+          )
+
+          for (const child of response.results) {
+            allChildren.push(child)
+          }
+
+          // Extract cursor from next link if present
+          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> =>
+      Effect.gen(function*() {
+        const raw = yield* request("POST", "/pages", req)
+        return yield* Schema.decodeUnknown(PageResponseSchema)(raw).pipe(
+          Effect.mapError((error) =>
+            new ApiError({
+              status: 0,
+              message: `Invalid response schema: ${error.message}`,
+              endpoint: "/pages"
+            })
+          )
+        )
+      })
+
+    const updatePage = (req: UpdatePageRequest): Effect.Effect<PageResponse, 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
+            })
+          )
+        )
+      })
+
+    const deletePage = (id: PageId): Effect.Effect<void, ApiError | RateLimitError> =>
+      request("DELETE", `/pages/${id}`).pipe(Effect.asVoid)
+
+    return ConfluenceClient.of({
+      getPage,
+      getChildren,
+      getAllChildren,
+      createPage,
+      updatePage,
+      deletePage
+    })
+  })
+
+/**
+ * Layer that provides ConfluenceClient with direct configuration.
+ *
+ * @example
+ * ```typescript
+ * import { ConfluenceClient } from "@knpkv/confluence-to-markdown/ConfluenceClient"
+ * import { NodeHttpClient } from "@effect/platform-node"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const client = yield* ConfluenceClient
+ *   const page = yield* client.getPage("12345")
+ *   console.log(page.title)
+ * })
+ *
+ * Effect.runPromise(
+ *   program.pipe(
+ *     Effect.provide(ConfluenceClient.layer({
+ *       baseUrl: "https://yoursite.atlassian.net",
+ *       auth: {
+ *         type: "token",
+ *         email: "you@example.com",
+ *         token: process.env.CONFLUENCE_API_KEY
+ *       }
+ *     })),
+ *     Effect.provide(NodeHttpClient.layer)
+ *   )
+ * )
+ * ```
+ *
+ * @category Layers
+ */
+export const layer = (
+  config: ConfluenceClientConfig
+): Layer.Layer<ConfluenceClient, never, HttpClient.HttpClient> => Layer.effect(ConfluenceClient, make(config))

package/src/ConfluenceConfig.ts

@@ -0,0 +1,184 @@
+/**
+ * Configuration service for Confluence sync.
+ *
+ * @module
+ */
+import * as FileSystem from "@effect/platform/FileSystem"
+import * as Path from "@effect/platform/Path"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import type { PageId } from "./Brand.js"
+import { ConfigNotFoundError, ConfigParseError } from "./ConfluenceError.js"
+import type { ConfluenceConfigFile } from "./Schemas.js"
+import { ConfluenceConfigFileSchema } from "./Schemas.js"
+
+/**
+ * Configuration service for Confluence operations.
+ *
+ * @example
+ * ```typescript
+ * import { ConfluenceConfig } from "@knpkv/confluence-to-markdown/ConfluenceConfig"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const config = yield* ConfluenceConfig
+ *   console.log(config.rootPageId)
+ *   console.log(config.baseUrl)
+ * })
+ * ```
+ *
+ * @category Config
+ */
+export class ConfluenceConfig extends Context.Tag(
+  "@knpkv/confluence-to-markdown/ConfluenceConfig"
+)<
+  ConfluenceConfig,
+  {
+    /** Root page ID to sync from */
+    readonly rootPageId: PageId
+    /** Confluence Cloud base URL */
+    readonly baseUrl: string
+    /** Optional space key */
+    readonly spaceKey?: string
+    /** Local docs path */
+    readonly docsPath: string
+    /** Glob patterns to exclude */
+    readonly excludePatterns: ReadonlyArray<string>
+  }
+>() {}
+
+/**
+ * Default config file name.
+ */
+const CONFIG_FILE_NAME = ".confluence.json"
+
+/**
+ * Load configuration from a file.
+ */
+const loadConfig = (
+  configPath: string
+): Effect.Effect<ConfluenceConfigFile, ConfigNotFoundError | ConfigParseError, FileSystem.FileSystem> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+
+    const exists = yield* fs.exists(configPath).pipe(
+      Effect.catchAll(() => Effect.succeed(false))
+    )
+    if (!exists) {
+      return yield* Effect.fail(new ConfigNotFoundError({ path: configPath }))
+    }
+
+    const content = yield* fs.readFileString(configPath).pipe(
+      Effect.mapError((cause) => new ConfigParseError({ path: configPath, cause }))
+    )
+
+    const json = yield* Effect.try({
+      try: () => JSON.parse(content) as unknown,
+      catch: (cause) => new ConfigParseError({ path: configPath, cause })
+    })
+
+    return yield* Schema.decodeUnknown(ConfluenceConfigFileSchema)(json).pipe(
+      Effect.mapError((cause) => new ConfigParseError({ path: configPath, cause }))
+    )
+  })
+
+/**
+ * Layer that provides ConfluenceConfig from a config file.
+ *
+ * @example
+ * ```typescript
+ * import { ConfluenceConfig } from "@knpkv/confluence-to-markdown/ConfluenceConfig"
+ * import { NodeFileSystem } from "@effect/platform-node"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const config = yield* ConfluenceConfig
+ *   console.log(config.rootPageId)
+ * })
+ *
+ * Effect.runPromise(
+ *   program.pipe(
+ *     Effect.provide(ConfluenceConfig.layer()),
+ *     Effect.provide(NodeFileSystem.layer)
+ *   )
+ * )
+ * ```
+ *
+ * @category Layers
+ */
+export const layer = (
+  configPath?: string
+): Layer.Layer<ConfluenceConfig, ConfigNotFoundError | ConfigParseError, FileSystem.FileSystem | Path.Path> =>
+  Layer.effect(
+    ConfluenceConfig,
+    Effect.gen(function*() {
+      const path = yield* Path.Path
+      const resolvedPath = configPath ?? path.join(process.cwd(), CONFIG_FILE_NAME)
+      const config = yield* loadConfig(resolvedPath)
+
+      return ConfluenceConfig.of({
+        rootPageId: config.rootPageId,
+        baseUrl: config.baseUrl,
+        ...(config.spaceKey !== undefined ? { spaceKey: config.spaceKey } : {}),
+        docsPath: config.docsPath,
+        excludePatterns: config.excludePatterns
+      })
+    })
+  )
+
+/**
+ * Layer that provides ConfluenceConfig with direct values.
+ *
+ * @category Layers
+ */
+export const layerFromValues = (
+  config: ConfluenceConfigFile
+): Layer.Layer<ConfluenceConfig> =>
+  Layer.succeed(
+    ConfluenceConfig,
+    ConfluenceConfig.of({
+      rootPageId: config.rootPageId,
+      baseUrl: config.baseUrl,
+      ...(config.spaceKey !== undefined ? { spaceKey: config.spaceKey } : {}),
+      docsPath: config.docsPath,
+      excludePatterns: config.excludePatterns
+    })
+  )
+
+/**
+ * Create a new config file.
+ *
+ * @category Utilities
+ */
+export const createConfigFile = (
+  rootPageId: string,
+  baseUrl: string,
+  configPath?: string
+): Effect.Effect<string, ConfigParseError, FileSystem.FileSystem | Path.Path> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const pathService = yield* Path.Path
+
+    const resolvedPath = configPath ?? pathService.join(process.cwd(), CONFIG_FILE_NAME)
+
+    const config: ConfluenceConfigFile = {
+      rootPageId: rootPageId as PageId,
+      baseUrl,
+      docsPath: ".docs/confluence",
+      excludePatterns: []
+    }
+
+    // Validate the config
+    yield* Schema.decodeUnknown(ConfluenceConfigFileSchema)(config).pipe(
+      Effect.mapError((cause) => new ConfigParseError({ path: resolvedPath, cause }))
+    )
+
+    const content = JSON.stringify(config, null, 2)
+    yield* fs.writeFileString(resolvedPath, content).pipe(
+      Effect.mapError((cause) => new ConfigParseError({ path: resolvedPath, cause }))
+    )
+
+    return resolvedPath
+  })