@knpkv/jira-api-client 0.3.1 → 1.0.0

package/src/index.ts

@@ -1,22 +1,11 @@
 /**
- * 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.
+ * Schema-validated Effect client for Jira Cloud REST API v3.
  *
  * @packageDocumentation
  */
 
-export { JiraApiClient, type JiraApiClientShape, layer } from "./JiraApiClient.js"
+export { JiraApiClient, type JiraApiClientShape, layer, make, type UploadAttachmentInput } from "./JiraApiClient.js"
 
 export { JiraApiConfig, type JiraApiConfigShape } from "./JiraApiConfig.js"
 
-export { FetchClientError, type OpenApiFetchClient, type SuccessData, toEffect } from "./OpenApiFetchClient.js"
-
-// Re-export generated V3 types
-export type * as V3 from "./generated/v3/index.js"
+export * as JiraApi from "./generated/JiraApi.js"

package/test/JiraApiClient.test.ts

@@ -1,152 +1,170 @@
-import { describe, expect, it, vi } from "@effect/vitest"
+import { describe, expect, it } from "@effect/vitest"
 import * as Effect from "effect/Effect"
 import * as Layer from "effect/Layer"
-import * as Predicate from "effect/Predicate"
 import * as Redacted from "effect/Redacted"
-import { FetchClientError, JiraApiClient, JiraApiConfig, toEffect } from "../src/index.js"
-
-const isRequest = (input: RequestInfo | URL): input is Request =>
-  Predicate.hasProperty(input, "url") &&
-  Predicate.hasProperty(input, "headers") &&
-  Predicate.hasProperty(input.headers, "entries") &&
-  typeof input.headers.entries === "function"
-
-/**
- * Mock global fetch to capture requests and return canned responses.
- */
-const withMockFetch = <A, E>(
-  responses: Array<{ status: number; body: unknown }>,
-  fn: (capturedRequests: Array<{ url: string; init: RequestInit }>) => Effect.Effect<A, E>
-): Effect.Effect<A, E> => {
-  const capturedRequests: Array<{ url: string; init: RequestInit }> = []
-  let requestIndex = 0
-  const originalFetch = fetch
-
-  vi.stubGlobal("fetch", async (input: RequestInfo | URL, init?: RequestInit) => {
-    const url = typeof input === "string" ? input : isRequest(input) ? input.url : input.toString()
-    const headers = isRequest(input)
-      ? Object.fromEntries(input.headers.entries())
-      : (init?.headers as Record<string, string> | undefined) ?? {}
-    capturedRequests.push({ url, init: { ...init, headers } })
-    const response = responses[requestIndex] ?? { status: 200, body: {} }
-    requestIndex++
-    return new Response(JSON.stringify(response.body), {
-      status: response.status,
-      headers: { "content-type": "application/json" }
-    })
-  })
-
-  return Effect.ensuring(
-    fn(capturedRequests),
-    Effect.sync(() => {
-      vi.stubGlobal("fetch", originalFetch)
-    })
+import * as HttpClient from "effect/unstable/http/HttpClient"
+import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
+import { JiraApiClient, JiraApiConfig, type JiraApiConfigShape } from "../src/index.js"
+
+const clientLayer = (
+  config: JiraApiConfigShape,
+  response: { readonly status: number; readonly body?: unknown },
+  requests: Array<HttpClientRequest.HttpClientRequest>
+) =>
+  JiraApiClient.layer.pipe(
+    Layer.provide(Layer.succeed(JiraApiConfig, config)),
+    Layer.provide(Layer.succeed(
+      HttpClient.HttpClient,
+      HttpClient.make((request) =>
+        Effect.sync(() => {
+          requests.push(request)
+          return HttpClientResponse.fromWeb(
+            request,
+            new Response(response.body === undefined ? null : JSON.stringify(response.body), {
+              status: response.status,
+              headers: { "content-type": "application/json" }
+            })
+          )
+        })
+      )
+    ))
   )
+
+const basicConfig: JiraApiConfigShape = {
+  baseUrl: "https://jira.test",
+  auth: {
+    type: "basic",
+    email: "user@example.com",
+    apiToken: Redacted.make("test-token")
+  }
 }
 
 describe("JiraApiClient", () => {
-  describe("layer construction", () => {
-    // Verifies basic auth applies Base64-encoded email:token as Authorization header and routes to baseUrl
-    it.effect("creates client with basic auth", () =>
-      withMockFetch(
-        [{ status: 200, body: { id: "10001", key: "PROJ-1", fields: { summary: "Test" } } }],
-        (capturedRequests) =>
-          Effect.gen(function*() {
-            const configLayer = Layer.succeed(JiraApiConfig, {
-              baseUrl: "https://test.atlassian.net",
-              auth: {
-                type: "basic",
-                email: "user@example.com",
-                apiToken: Redacted.make("test-token")
-              }
-            })
-
-            const client = yield* JiraApiClient.pipe(
-              Effect.provide(JiraApiClient.layer),
-              Effect.provide(configLayer)
-            )
-
-            const issue = yield* toEffect(client.v3.client.GET("/rest/api/3/issue/{issueIdOrKey}", {
-              params: { path: { issueIdOrKey: "PROJ-1" } }
-            }))
-
-            expect(issue.id).toBe("10001")
-            expect(issue.key).toBe("PROJ-1")
-            expect(capturedRequests).toHaveLength(1)
-
-            const request = capturedRequests[0]!
-            expect(request.url).toContain("test.atlassian.net")
-            expect(request.url).toContain("/rest/api/3/issue/PROJ-1")
-            const authHeader = (request.init.headers as Record<string, string>)["Authorization"] ??
-              (request.init.headers as Record<string, string>)["authorization"]
-            expect(authHeader).toMatch(/^Basic /)
-          })
-      ))
-
-    // Verifies OAuth2 applies Bearer token and routes through Atlassian cloud proxy
-    it.effect("creates client with OAuth2 auth and applies Bearer token", () =>
-      withMockFetch(
-        [{ status: 200, body: { id: "10001", key: "PROJ-1", fields: { summary: "Test" } } }],
-        (capturedRequests) =>
-          Effect.gen(function*() {
-            const configLayer = Layer.succeed(JiraApiConfig, {
-              baseUrl: "https://test.atlassian.net",
-              auth: {
-                type: "oauth2",
-                accessToken: Redacted.make("oauth-token"),
-                cloudId: "cloud-123"
-              }
-            })
-
-            const client = yield* JiraApiClient.pipe(
-              Effect.provide(JiraApiClient.layer),
-              Effect.provide(configLayer)
-            )
-
-            const issue = yield* toEffect(client.v3.client.GET("/rest/api/3/issue/{issueIdOrKey}", {
-              params: { path: { issueIdOrKey: "PROJ-1" } }
-            }))
-
-            expect(issue.id).toBe("10001")
-            expect(capturedRequests).toHaveLength(1)
+  it.effect("applies basic auth and decodes dynamic issue fields", () => {
+    const requests: Array<HttpClientRequest.HttpClientRequest> = []
+    return Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      const issue = yield* client.getIssue("PROJ-1", undefined)
+      expect(issue.key).toBe("PROJ-1")
+      expect(issue.fields?.customfield_10001).toBe("dynamic")
+      expect(requests[0]?.url).toBe("https://jira.test/rest/api/3/issue/PROJ-1")
+      expect(requests[0]?.headers.authorization).toMatch(/^Basic /)
+    }).pipe(Effect.provide(clientLayer(basicConfig, {
+      status: 200,
+      body: { id: "10001", key: "PROJ-1", fields: { customfield_10001: "dynamic" } }
+    }, requests)))
+  })
 
-            const request = capturedRequests[0]!
-            expect(request.url).toContain("api.atlassian.com/ex/jira/cloud-123")
-            const authHeader = (request.init.headers as Record<string, string>)["Authorization"] ??
-              (request.init.headers as Record<string, string>)["authorization"]
-            expect(authHeader).toBe("Bearer oauth-token")
-          })
-      ))
+  it.effect("routes OAuth2 through the Atlassian cloud gateway", () => {
+    const requests: Array<HttpClientRequest.HttpClientRequest> = []
+    return Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      yield* client.getIssue("PROJ-1", undefined)
+      expect(requests[0]?.url).toBe("https://api.atlassian.com/ex/jira/cloud-123/rest/api/3/issue/PROJ-1")
+      expect(requests[0]?.headers.authorization).toBe("Bearer oauth-token")
+    }).pipe(Effect.provide(clientLayer(
+      {
+        baseUrl: "",
+        auth: { type: "oauth2", accessToken: Redacted.make("oauth-token"), cloudId: "cloud-123" }
+      },
+      { status: 200, body: { id: "10001", key: "PROJ-1", fields: {} } },
+      requests
+    )))
   })
 
-  describe("V3 client", () => {
-    // API errors must propagate as FetchClientError
-    it.effect("handles API errors", () =>
-      withMockFetch(
-        [{ status: 404, body: { errorMessages: ["Issue does not exist"] } }],
-        () =>
-          Effect.gen(function*() {
-            const configLayer = Layer.succeed(JiraApiConfig, {
-              baseUrl: "https://test.atlassian.net",
-              auth: { type: "basic", email: "u@e.com", apiToken: Redacted.make("t") }
-            })
+  it.effect("keeps bodyless-spec 404 responses in the typed error channel", () =>
+    Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      const result = yield* Effect.result(client.getIssue("NOPE-999", undefined))
+      expect(result._tag).toBe("Failure")
+      if (result._tag === "Failure") expect(result.failure._tag).toBe("GetIssue404")
+    }).pipe(Effect.provide(clientLayer(basicConfig, {
+      status: 404,
+      body: { errorMessages: ["Issue does not exist"] }
+    }, []))))
+
+  it.effect("never treats a genuinely empty 404 as success", () =>
+    Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      const result = yield* Effect.result(client.getIssue("NOPE-EMPTY", undefined))
+      expect(result._tag).toBe("Failure")
+    }).pipe(Effect.provide(clientLayer(basicConfig, { status: 404 }, []))))
+
+  it.effect("decodes a terminal JQL page whose nextPageToken is null", () =>
+    Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      const result = yield* client.searchIssuesUsingJql({ params: { jql: "project = PROJ" } })
+      expect(result.nextPageToken).toBeNull()
+      expect(result.isLast).toBe(true)
+    }).pipe(Effect.provide(clientLayer(basicConfig, {
+      status: 200,
+      body: { issues: [], isLast: true, nextPageToken: null }
+    }, []))))
+
+  it.effect("preserves Jira Premium contributors on decoded versions", () =>
+    Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      const version = yield* client.getVersion("10000", undefined)
+      expect(version.contributors).toEqual([
+        "account-1",
+        { accountId: "account-2", displayName: "Ada" }
+      ])
+    }).pipe(Effect.provide(clientLayer(basicConfig, {
+      status: 200,
+      body: {
+        id: "10000",
+        name: "1.0.0",
+        contributors: ["account-1", { accountId: "account-2", displayName: "Ada" }]
+      }
+    }, []))))
+
+  it.effect("rejects malformed successful responses", () =>
+    Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      const result = yield* Effect.result(client.getFields(undefined))
+      expect(result._tag).toBe("Failure")
+    }).pipe(Effect.provide(clientLayer(basicConfig, { status: 200, body: {} }, []))))
+
+  it.effect("returns void for Jira 204 responses that advertise an empty JSON schema", () => {
+    const requests: Array<HttpClientRequest.HttpClientRequest> = []
+    return Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      const result = yield* client.setBanner({
+        payload: { isEnabled: true, message: "Maintenance" }
+      })
+
+      expect(result).toBeUndefined()
+      expect(requests).toHaveLength(1)
+    }).pipe(Effect.provide(clientLayer(basicConfig, { status: 204 }, requests)))
+  })
 
-            const client = yield* JiraApiClient.pipe(
-              Effect.provide(JiraApiClient.layer),
-              Effect.provide(configLayer)
-            )
+  it.effect("keeps naturally bodyless delete operations void", () => {
+    const requests: Array<HttpClientRequest.HttpClientRequest> = []
+    return Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      const result = yield* client.deleteIssue("PROJ-1", undefined)
 
-            const result = yield* toEffect(client.v3.client.GET("/rest/api/3/issue/{issueIdOrKey}", {
-              params: { path: { issueIdOrKey: "NOPE-999" } }
-            }))
-              .pipe(Effect.result)
+      expect(result).toBeUndefined()
+      expect(requests).toHaveLength(1)
+    }).pipe(Effect.provide(clientLayer(basicConfig, { status: 204 }, requests)))
+  })
 
-            expect(result._tag).toBe("Failure")
-            if (result._tag === "Failure") {
-              expect(result.failure).toBeInstanceOf(FetchClientError)
-              expect((result.failure as FetchClientError).status).toBe(404)
-            }
-          })
-      ))
+  it.effect("uploads multipart data with the Atlassian CSRF bypass header", () => {
+    const requests: Array<HttpClientRequest.HttpClientRequest> = []
+    return Effect.gen(function*() {
+      const client = yield* JiraApiClient
+      const attachments = yield* client.uploadAttachment("PROJ-1", {
+        bytes: new Uint8Array([1, 2, 3]),
+        filename: "example.bin",
+        mediaType: "application/octet-stream"
+      })
+      expect(attachments[0]?.filename).toBe("example.bin")
+      expect(requests[0]?.headers["x-atlassian-token"]).toBe("no-check")
+      expect(requests[0]?.body._tag).toBe("FormData")
+    }).pipe(Effect.provide(clientLayer(basicConfig, {
+      status: 200,
+      body: [{ id: "1", filename: "example.bin", size: 3 }]
+    }, requests)))
   })
 })

package/.specs/VERSION_V3

@@ -1 +0,0 @@
-1001.0.0-SNAPSHOT-05f20e18d9bde3de68f911b4915970482f536d4e