@knpkv/jira-api-client 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Root barrel export for `@knpkv/jira-api-client` -- openapi-fetch + Effect Jira REST client.
+ *
+ * **Mental model**
+ *
+ * - **Namespaced version**: `V3` re-exports the generated OpenAPI types (paths, components, operations).
+ * - **Config + client split**: {@link JiraApiConfig} is provided separately from the
+ *   generated client to support auth-polymorphic usage.
+ * - **openapi-fetch wrapper**: {@link OpenApiFetchClient} provides Effect-based `execute` method
+ *   around raw openapi-fetch clients.
+ *
+ * @packageDocumentation
+ */
+export { JiraApiClient, type JiraApiClientShape, layer } from "./JiraApiClient.js";
+export { JiraApiConfig, type JiraApiConfigShape } from "./JiraApiConfig.js";
+export { FetchClientError, type OpenApiFetchClient, type SuccessData, toEffect } from "./OpenApiFetchClient.js";
+export type * as V3 from "./generated/v3/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAElF,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE3E,OAAO,EAAE,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAG/G,YAAY,KAAK,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * Root barrel export for `@knpkv/jira-api-client` -- openapi-fetch + Effect Jira REST client.
+ *
+ * **Mental model**
+ *
+ * - **Namespaced version**: `V3` re-exports the generated OpenAPI types (paths, components, operations).
+ * - **Config + client split**: {@link JiraApiConfig} is provided separately from the
+ *   generated client to support auth-polymorphic usage.
+ * - **openapi-fetch wrapper**: {@link OpenApiFetchClient} provides Effect-based `execute` method
+ *   around raw openapi-fetch clients.
+ *
+ * @packageDocumentation
+ */
+export { JiraApiClient, layer } from "./JiraApiClient.js";
+export { JiraApiConfig } from "./JiraApiConfig.js";
+export { FetchClientError, toEffect } from "./OpenApiFetchClient.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAA2B,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAElF,OAAO,EAAE,aAAa,EAA2B,MAAM,oBAAoB,CAAA;AAE3E,OAAO,EAAE,gBAAgB,EAA6C,QAAQ,EAAE,MAAM,yBAAyB,CAAA"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@knpkv/jira-api-client",
+  "version": "0.2.0",
+  "description": "Effect-based Jira Cloud REST API v3 client",
+  "license": "MIT",
+  "author": "knpkv",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/knpkv/npm.git",
+    "directory": "packages/jira-api-client"
+  },
+  "bugs": {
+    "url": "https://github.com/knpkv/npm/issues"
+  },
+  "homepage": "https://github.com/knpkv/npm/tree/main/packages/jira-api-client#readme",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./JiraApiClient": {
+      "import": "./dist/JiraApiClient.js",
+      "types": "./dist/JiraApiClient.d.ts"
+    },
+    "./JiraApiConfig": {
+      "import": "./dist/JiraApiConfig.js",
+      "types": "./dist/JiraApiConfig.d.ts"
+    },
+    "./v3": {
+      "import": "./dist/generated/v3/index.js",
+      "types": "./dist/generated/v3/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "effect": "^3.19.3"
+  },
+  "devDependencies": {
+    "@effect/cli": "latest",
+    "@effect/platform-node": "latest",
+    "@effect/vitest": "latest",
+    "@types/node": "latest",
+    "effect": "latest",
+    "openapi-typescript": "^7.13.0",
+    "openapi-typescript-helpers": "^0.1.0",
+    "tsx": "^4.19.4",
+    "typescript": "~5.9.0",
+    "vitest": "^4.0.13"
+  },
+  "keywords": [
+    "effect",
+    "effect-ts",
+    "jira",
+    "atlassian",
+    "api-client",
+    "openapi"
+  ],
+  "dependencies": {
+    "openapi-fetch": "^0.17.0"
+  },
+  "scripts": {
+    "build": "tsc && cp src/generated/v3/schema.d.ts dist/generated/v3/schema.d.ts",
+    "clean": "rimraf dist dist-test .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "check": "tsc --noEmit",
+    "regenerate": "tsx scripts/regenerate.ts",
+    "regenerate:check": "tsx scripts/regenerate.ts --check"
+  }
+}

package/scripts/regenerate.ts

@@ -0,0 +1,141 @@
+#!/usr/bin/env tsx
+/**
+ * Regeneration script for Jira API types.
+ *
+ * Fetches OpenAPI specs from Atlassian and regenerates openapi-typescript types.
+ */
+import { Command, Options } from "@effect/cli"
+import { NodeContext, NodeRuntime } from "@effect/platform-node"
+import * as Console from "effect/Console"
+import * as Effect from "effect/Effect"
+import { execSync } from "node:child_process"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+import pkg from "../package.json" with { type: "json" }
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const SPECS_DIR = path.join(__dirname, "..", ".specs")
+const VERSION_V3_FILE = path.join(SPECS_DIR, "VERSION_V3")
+const GENERATED_DIR = path.join(__dirname, "..", "src", "generated", "v3")
+
+const SPEC_URLS = {
+  v3: "https://dac-static.atlassian.com/cloud/jira/platform/swagger-v3.v3.json"
+} as const
+
+interface SpecInfo {
+  version: string
+  title: string
+}
+
+const fetchSpecInfo = (url: string): Effect.Effect<SpecInfo, Error> =>
+  Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url)
+      if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.status}`)
+      }
+      const spec = await response.json() as { info: { version: string; title: string } }
+      return { version: spec.info.version, title: spec.info.title }
+    },
+    catch: (e) => new Error(`Fetch failed: ${e}`)
+  })
+
+const fetchAndSaveSpec = (url: string, outputPath: string): Effect.Effect<void, Error> =>
+  Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(url)
+      if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.status}`)
+      }
+      const spec = await response.text()
+      fs.writeFileSync(outputPath, spec, "utf-8")
+    },
+    catch: (e) => new Error(`Fetch/save failed: ${e}`)
+  })
+
+const readVersion = (file: string): Effect.Effect<string | null> =>
+  Effect.sync(() => {
+    try {
+      return fs.readFileSync(file, "utf-8").trim()
+    } catch {
+      return null
+    }
+  })
+
+const writeVersion = (file: string, version: string): Effect.Effect<void> =>
+  Effect.sync(() => fs.writeFileSync(file, version, "utf-8"))
+
+const ensureDir = (dir: string): Effect.Effect<void> =>
+  Effect.sync(() => {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+    }
+  })
+
+const generateTypes = (specPath: string): Effect.Effect<void, Error> =>
+  Effect.tryPromise({
+    try: async () => {
+      const outputFile = path.join(GENERATED_DIR, "schema.d.ts")
+      execSync(
+        `pnpm exec openapi-typescript "${specPath}" -o "${outputFile}"`,
+        { cwd: path.join(__dirname, "..") }
+      )
+    },
+    catch: (e) => new Error(`Type generation failed: ${e}`)
+  })
+
+const checkOnly = Options.boolean("check").pipe(
+  Options.withDescription("Check only, exit 1 if outdated"),
+  Options.withDefault(false)
+)
+
+const regenerate = Command.make("regenerate", { checkOnly }, ({ checkOnly }) =>
+  Effect.gen(function*() {
+    yield* Console.log("Fetching Jira API spec version...")
+
+    const v3Info = yield* fetchSpecInfo(SPEC_URLS.v3)
+    const currentV3 = yield* readVersion(VERSION_V3_FILE)
+
+    yield* Console.log(`V3: current=${currentV3 ?? "none"}, remote=${v3Info.version}`)
+
+    const v3Changed = currentV3 !== v3Info.version
+
+    if (!v3Changed) {
+      yield* Console.log("Spec is up to date.")
+      return
+    }
+
+    if (checkOnly) {
+      yield* Console.log("Spec is outdated!")
+      yield* Console.log(`  V3: ${currentV3} -> ${v3Info.version}`)
+      return yield* Effect.fail(new Error("Spec outdated"))
+    }
+
+    yield* ensureDir(SPECS_DIR)
+    yield* ensureDir(GENERATED_DIR)
+
+    const specPath = path.join(SPECS_DIR, `jira-v3-${v3Info.version}.json`)
+
+    yield* Console.log(`Fetching V3 spec (${v3Info.version})...`)
+    yield* fetchAndSaveSpec(SPEC_URLS.v3, specPath)
+    yield* Console.log(`Saved: ${specPath}`)
+
+    yield* Console.log("Generating types...")
+    yield* generateTypes(specPath)
+    yield* Console.log(`Generated: src/generated/v3/schema.d.ts`)
+
+    yield* writeVersion(VERSION_V3_FILE, v3Info.version)
+    yield* Console.log("Done!")
+  })
+).pipe(Command.withDescription("Regenerate Jira API types from OpenAPI specs"))
+
+const cli = Command.run(regenerate, {
+  name: pkg.name,
+  version: pkg.version
+})
+
+Effect.suspend(() => cli(process.argv)).pipe(
+  Effect.provide(NodeContext.layer),
+  NodeRuntime.runMain
+)

package/src/JiraApiClient.ts

@@ -0,0 +1,129 @@
+/**
+ * Effect Layer wrapping openapi-fetch Jira V3 client with auth and base URL.
+ *
+ * **Mental model**
+ *
+ * - **Auth-polymorphic**: Supports both Basic (email + API token) and OAuth2 (access token +
+ *   cloud ID) auth. The layer reads {@link JiraApiConfig} to build the Authorization header
+ *   and derive the correct base URL.
+ * - **openapi-fetch wrapper**: Uses {@link OpenApiFetchClient} for Effect-based methods.
+ *
+ * **Common tasks**
+ *
+ * - Use the client: `const jira = yield* JiraApiClient; jira.v3.GET(...)`
+ * - Provide the layer: `Effect.provide(JiraApiClient.layer)`
+ *
+ * @module
+ */
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Encoding from "effect/Encoding"
+import * as Layer from "effect/Layer"
+import * as Redacted from "effect/Redacted"
+import type { paths as V3Paths } from "./generated/v3/schema.js"
+import { JiraApiConfig } from "./JiraApiConfig.js"
+import { makeOpenApiFetchClient, type OpenApiFetchClient } from "./OpenApiFetchClient.js"
+
+/**
+ * Jira API client shape (v3 only).
+ *
+ * @example
+ * ```typescript
+ * import { toEffect } from "@knpkv/jira-api-client"
+ *
+ * // Get issue by key
+ * toEffect(client.v3.client.GET("/rest/api/3/issue/{issueIdOrKey}", {
+ *   params: { path: { issueIdOrKey: "PROJ-123" } }
+ * }))
+ *
+ * // Search issues with JQL
+ * toEffect(client.v3.client.POST("/rest/api/3/search/jql", {
+ *   body: { jql: "project = PROJ", maxResults: 50 }
+ * }))
+ * ```
+ *
+ * @category Client
+ */
+export interface JiraApiClientShape {
+  readonly v3: OpenApiFetchClient<V3Paths>
+}
+
+/**
+ * Jira API client service.
+ *
+ * @example
+ * ```typescript
+ * import { JiraApiClient, JiraApiConfig } from "@knpkv/jira-api-client"
+ * import * as Redacted from "effect/Redacted"
+ * import * as Effect from "effect/Effect"
+ * import * as Layer from "effect/Layer"
+ *
+ * const program = Effect.gen(function* () {
+ *   const client = yield* JiraApiClient
+ *   const issue = yield* toEffect(client.v3.client.GET("/rest/api/3/issue/{issueIdOrKey}", {
+ *     params: { path: { issueIdOrKey: "PROJ-123" } }
+ *   }))
+ *   console.log(issue.fields?.summary)
+ * })
+ *
+ * const configLayer = Layer.succeed(JiraApiConfig, {
+ *   baseUrl: "https://mysite.atlassian.net",
+ *   auth: {
+ *     type: "basic",
+ *     email: "user@example.com",
+ *     apiToken: Redacted.make("token")
+ *   }
+ * })
+ *
+ * Effect.runPromise(
+ *   program.pipe(
+ *     Effect.provide(JiraApiClient.layer),
+ *     Effect.provide(configLayer)
+ *   )
+ * )
+ * ```
+ *
+ * @category Client
+ */
+export class JiraApiClient extends Context.Tag(
+  "@knpkv/jira-api-client/JiraApiClient"
+)<JiraApiClient, JiraApiClientShape>() {
+  /**
+   * Layer that provides JiraApiClient.
+   *
+   * Requires: JiraApiConfig
+   */
+  static readonly layer: Layer.Layer<JiraApiClient, never, JiraApiConfig> = Layer.effect(
+    JiraApiClient,
+    Effect.gen(function*() {
+      const config = yield* JiraApiConfig
+
+      // Build auth header
+      const authHeader = config.auth.type === "basic"
+        ? `Basic ${Encoding.encodeBase64(`${config.auth.email}:${Redacted.value(config.auth.apiToken)}`)}`
+        : `Bearer ${Redacted.value(config.auth.accessToken)}`
+
+      // Base URL differs by auth type
+      const baseUrl = config.auth.type === "oauth2"
+        ? `https://api.atlassian.com/ex/jira/${config.auth.cloudId}`
+        : config.baseUrl
+
+      const headers = {
+        Authorization: authHeader,
+        Accept: "application/json",
+        "Content-Type": "application/json"
+      }
+
+      return {
+        v3: makeOpenApiFetchClient<V3Paths>(baseUrl, headers)
+      }
+    })
+  )
+}
+
+/**
+ * Layer that provides JiraApiClient.
+ *
+ * @category Layers
+ */
+export const layer = JiraApiClient.layer

package/src/JiraApiConfig.ts

@@ -0,0 +1,51 @@
+/**
+ * Configuration service tag for the Jira API client (basic or OAuth2 auth).
+ *
+ * **Mental model**
+ *
+ * - **Discriminated auth union**: The `auth` field is `{ type: "basic", ... } | { type: "oauth2", ... }`.
+ *   Basic auth uses email + Redacted API token; OAuth2 uses Redacted access token + cloud ID.
+ * - **Base URL routing**: For OAuth2, the base URL is derived from cloud ID (`api.atlassian.com/ex/jira/{cloudId}`);
+ *   for basic auth, `baseUrl` is used directly.
+ *
+ * @module
+ */
+import * as Context from "effect/Context"
+import type * as Redacted from "effect/Redacted"
+
+/**
+ * Configuration shape for Jira API client.
+ *
+ * @category Config
+ */
+export interface JiraApiConfigShape {
+  readonly baseUrl: string
+  readonly auth:
+    | { readonly type: "basic"; readonly email: string; readonly apiToken: Redacted.Redacted<string> }
+    | { readonly type: "oauth2"; readonly accessToken: Redacted.Redacted<string>; readonly cloudId: string }
+}
+
+/**
+ * Jira API configuration service.
+ *
+ * @example
+ * ```typescript
+ * import { JiraApiConfig } from "@knpkv/jira-api-client"
+ * import * as Redacted from "effect/Redacted"
+ * import * as Layer from "effect/Layer"
+ *
+ * const configLayer = Layer.succeed(JiraApiConfig, {
+ *   baseUrl: "https://mysite.atlassian.net",
+ *   auth: {
+ *     type: "basic",
+ *     email: "user@example.com",
+ *     apiToken: Redacted.make("token")
+ *   }
+ * })
+ * ```
+ *
+ * @category Config
+ */
+export class JiraApiConfig extends Context.Tag(
+  "@knpkv/jira-api-client/JiraApiConfig"
+)<JiraApiConfig, JiraApiConfigShape>() {}

package/src/OpenApiFetchClient.ts

@@ -0,0 +1,92 @@
+/**
+ * Generic Effect wrapper for openapi-fetch clients.
+ *
+ * Exposes a type-safe `Client<Paths>` and a `toEffect` helper that wraps
+ * any `Promise<FetchResponse>` in Effect with error mapping.
+ *
+ * @example
+ * ```typescript
+ * const page = yield* toEffect(client.GET("/pages/{id}", {
+ *   params: { path: { id: 123 } }
+ * }))
+ * ```
+ *
+ * @module
+ */
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import createClient, { type Client, type FetchResponse } from "openapi-fetch"
+import type { MediaType } from "openapi-typescript-helpers"
+
+/**
+ * Error from openapi-fetch operations.
+ *
+ * @category Errors
+ */
+export class FetchClientError extends Data.TaggedError("FetchClientError")<{
+  readonly error: unknown
+  readonly status: number
+  readonly message: string
+}> {}
+
+/** Extract success `data` from a FetchResponse discriminated union. */
+export type SuccessData<T> = T extends { data: infer D; error?: undefined } ? D
+  : T extends { data?: infer D } ? NonNullable<D>
+  : never
+
+/**
+ * Wrap an openapi-fetch `Promise<FetchResponse>` in Effect.
+ *
+ * Extracts `data` on success, maps errors to `FetchClientError`.
+ * Fully type-safe — path/body constraints come from the `Client<Paths>` call site.
+ *
+ * @example
+ * ```typescript
+ * const page = yield* toEffect(client.GET("/pages/{id}", { params: { path: { id: 123 } } }))
+ * ```
+ *
+ * @category Utilities
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches FetchResponse generic constraint
+export const toEffect = <T extends Record<string | number, any>, O, M extends MediaType>(
+  promise: Promise<FetchResponse<T, O, M>>
+): Effect.Effect<SuccessData<FetchResponse<T, O, M>>, FetchClientError> =>
+  Effect.tryPromise({
+    try: () =>
+      promise.then(({ data, error, response }) => {
+        if (error !== undefined || !response.ok) {
+          throw { error, status: response.status }
+        }
+        return data as SuccessData<FetchResponse<T, O, M>>
+      }),
+    catch: (e) =>
+      new FetchClientError({
+        error: (e as Record<string, unknown>).error ?? e,
+        status: ((e as Record<string, unknown>).status as number | undefined) ?? 0,
+        message: typeof (e as Record<string, unknown>).error === "string"
+          ? (e as Record<string, unknown>).error as string
+          : JSON.stringify((e as Record<string, unknown>).error ?? e)
+      })
+  })
+
+/**
+ * openapi-fetch client paired with the `toEffect` helper.
+ *
+ * @category Client
+ */
+export interface OpenApiFetchClient<Paths extends {}> {
+  /** Type-safe openapi-fetch client. Use with `toEffect()` to get Effect. */
+  readonly client: Client<Paths, "application/json">
+}
+
+/**
+ * Create an openapi-fetch client with auth headers pre-configured.
+ *
+ * @category Constructors
+ */
+export const makeOpenApiFetchClient = <Paths extends {}>(
+  baseUrl: string,
+  headers: Record<string, string>
+): OpenApiFetchClient<Paths> => ({
+  client: createClient<Paths, "application/json">({ baseUrl, headers })
+})

package/src/generated/v3/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Generated Jira Cloud REST API v3 types.
+ *
+ * @module
+ */
+export type { components, operations, paths } from "./schema.js"