@knpkv/jira-api-client 1.0.1 → 2.0.0

package/dist/index.d.ts

@@ -3,7 +3,8 @@
  *
  * @packageDocumentation
  */
-export { JiraApiClient, type JiraApiClientShape, layer, make, type UploadAttachmentInput } from "./JiraApiClient.js";
-export { JiraApiConfig, type JiraApiConfigShape } from "./JiraApiConfig.js";
+export { JiraApiClient, type JiraApiClientContract, layer, make, type UploadAttachmentInput } from "./JiraApiClient.js";
+export { JiraApiConfig, type JiraApiConfigContract, type JiraApiCredential } from "./JiraApiConfig.js";
 export * as JiraApi from "./generated/JiraApi.js";
+export { ownOptionalKey, type PrototypeKey } from "./OwnOptionalKey.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAEpH,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE3E,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAEvH,OAAO,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAEtG,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAA;AAEjD,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/index.js

@@ -6,4 +6,5 @@
 export { JiraApiClient, layer, make } from "./JiraApiClient.js";
 export { JiraApiConfig } from "./JiraApiConfig.js";
 export * as JiraApi from "./generated/JiraApi.js";
+export { ownOptionalKey } from "./OwnOptionalKey.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAA2B,KAAK,EAAE,IAAI,EAA8B,MAAM,oBAAoB,CAAA;AAEpH,OAAO,EAAE,aAAa,EAA2B,MAAM,oBAAoB,CAAA;AAE3E,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAA8B,KAAK,EAAE,IAAI,EAA8B,MAAM,oBAAoB,CAAA;AAEvH,OAAO,EAAE,aAAa,EAAsD,MAAM,oBAAoB,CAAA;AAEtG,OAAO,KAAK,OAAO,MAAM,wBAAwB,CAAA;AAEjD,OAAO,EAAE,cAAc,EAAqB,MAAM,qBAAqB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knpkv/jira-api-client",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Effect-based Jira Cloud REST API v3 client",
   "license": "MIT",
   "author": "knpkv",
@@ -39,18 +39,18 @@
     "access": "public"
   },
   "peerDependencies": {
-    "effect": "4.0.0-beta.98"
+    "effect": "4.0.0"
   },
   "devDependencies": {
-    "@effect/openapi-generator": "4.0.0-beta.98",
-    "@effect/platform-node": "4.0.0-beta.98",
-    "@effect/vitest": "4.0.0-beta.98",
+    "@effect/openapi-generator": "4.0.0",
+    "@effect/platform-node": "4.0.0",
+    "@effect/vitest": "4.0.0",
     "@types/node": "latest",
-    "effect": "4.0.0-beta.98",
-    "prettier": "^3.9.5",
-    "tsx": "^4.23.0",
-    "typescript": "~6.0.3",
-    "vitest": "^4.1.10"
+    "effect": "4.0.0",
+    "prettier": "^3.9.9",
+    "tsx": "^4.23.15",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^5.0.3"
   },
   "keywords": [
     "effect",

package/scripts/regenerate.ts

@@ -8,19 +8,19 @@
 import * as OpenApiGenerator from "@effect/openapi-generator/OpenApiGenerator"
 import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
 import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node"
+import * as Command from "effect/cli/Command"
+import * as Flag from "effect/cli/Flag"
 import * as Console from "effect/Console"
 import * as Data from "effect/Data"
 import * as Effect from "effect/Effect"
 import * as FileSystem from "effect/FileSystem"
+import type { OpenAPISpec } from "effect/http-api/OpenApi"
+import * as HttpClient from "effect/http/HttpClient"
 import type * as JsonSchema from "effect/JsonSchema"
 import * as Layer from "effect/Layer"
 import * as Path from "effect/Path"
 import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
-import * as Command from "effect/unstable/cli/Command"
-import * as Flag from "effect/unstable/cli/Flag"
-import * as HttpClient from "effect/unstable/http/HttpClient"
-import type { OpenAPISpec } from "effect/unstable/httpapi/OpenApi"
 import { format as formatSource } from "prettier"
 
 const SPEC_URL = "https://dac-static.atlassian.com/cloud/jira/platform/swagger-v3.v3.json"
@@ -167,6 +167,17 @@ const normalizeResponses = (document: Schema.Json): Schema.Json => {
 
 const stripTrailingWhitespace = (source: string): string => source.replace(/[ \t]+$/gm, "")
 
+/** Route optional keys named after `Object.prototype` members through `ownOptionalKey`; see `src/OwnOptionalKey.ts`. */
+const ownPrototypeKeys = (source: string): string => {
+  const rewritten = source.replace(/"(toString)": Schema\.optionalKey\(/g, "\"$1\": ownOptionalKey(\"$1\", ")
+  return rewritten === source
+    ? source
+    : rewritten.replace(
+      /^(import \* as Schema from "effect\/Schema"\n)/m,
+      "$1import { ownOptionalKey } from \"../OwnOptionalKey.js\"\n"
+    )
+}
+
 const generate = Effect.fn("Jira.regenerate.generate")(function*(scriptPaths: ScriptPaths, upstream: Schema.Json) {
   const fs = yield* FileSystem.FileSystem
   const patch = yield* OpenApiPatch.parsePatchInput(scriptPaths.patchFile).pipe(
@@ -195,17 +206,19 @@ const generate = Effect.fn("Jira.regenerate.generate")(function*(scriptPaths: Sc
     (warning) => Console.warn(`[${warning.code}] ${warning.method ?? ""} ${warning.path ?? ""}: ${warning.message}`),
     { discard: true }
   )
-  yield* fs.writeFileString(scriptPaths.outputFile, stripTrailingWhitespace(generated)).pipe(
+  yield* fs.writeFileString(scriptPaths.outputFile, ownPrototypeKeys(stripTrailingWhitespace(generated))).pipe(
     Effect.mapError((cause) => new RegenerateError({ message: "Could not write generated Jira client", cause }))
   )
 })
 
-const check = Flag.boolean("check").pipe(
-  Flag.withDescription("Exit non-zero when the committed upstream spec differs from Jira")
+const check = Flag.Boolean("check").pipe(
+  Flag.withDescription("Exit non-zero when the committed upstream spec differs from Jira"),
+  Flag.withDefault(false)
 )
 
-const local = Flag.boolean("local").pipe(
-  Flag.withDescription("Regenerate from the committed spec without contacting Jira")
+const local = Flag.Boolean("local").pipe(
+  Flag.withDescription("Regenerate from the committed spec without contacting Jira"),
+  Flag.withDefault(false)
 )
 
 const root = Command.make("jira-api-regenerate", { check, local }).pipe(

package/src/JiraApiClient.ts

@@ -9,17 +9,17 @@
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
-import * as Encoding from "effect/Encoding"
+import { Base64 } from "effect/encoding"
 import { flow } from "effect/Function"
+import * as HttpClient from "effect/http/HttpClient"
+import type * as HttpClientError from "effect/http/HttpClientError"
+import * as HttpClientRequest from "effect/http/HttpClientRequest"
+import * as HttpClientResponse from "effect/http/HttpClientResponse"
 import * as Layer from "effect/Layer"
 import * as Redacted from "effect/Redacted"
 import type { SchemaError } from "effect/Schema"
-import * as HttpClient from "effect/unstable/http/HttpClient"
-import type * as HttpClientError from "effect/unstable/http/HttpClientError"
-import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
-import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse"
 import * as Generated from "./generated/JiraApi.js"
-import { JiraApiConfig, type JiraApiConfigShape } from "./JiraApiConfig.js"
+import { JiraApiConfig, type JiraApiConfigContract, type JiraApiCredential } from "./JiraApiConfig.js"
 
 export interface UploadAttachmentInput {
   readonly bytes: Uint8Array
@@ -27,37 +27,59 @@ export interface UploadAttachmentInput {
   readonly mediaType?: string | undefined
 }
 
-export interface JiraApiClientShape extends Generated.JiraApi {
+export interface JiraApiClientContract extends Generated.JiraApi {
   readonly uploadAttachment: (
     issueIdOrKey: string,
     input: UploadAttachmentInput
   ) => Effect.Effect<Generated.AddAttachment200, HttpClientError.HttpClientError | SchemaError>
 }
 
-const authorizationHeader = (config: JiraApiConfigShape): string =>
-  config.auth.type === "basic"
-    ? `Basic ${Encoding.encodeBase64(`${config.auth.email}:${Redacted.value(config.auth.apiToken)}`)}`
-    : `Bearer ${Redacted.value(config.auth.accessToken)}`
+const authorizationHeader = (auth: JiraApiCredential): string =>
+  auth.type === "basic"
+    ? `Basic ${Base64.encode(`${auth.email}:${Redacted.value(auth.apiToken)}`)}`
+    : `Bearer ${Redacted.value(auth.accessToken)}`
 
-const apiBaseUrl = (config: JiraApiConfigShape): string =>
-  config.auth.type === "oauth2"
-    ? `https://api.atlassian.com/ex/jira/${config.auth.cloudId}`
-    : config.baseUrl
+const apiBaseUrl = (baseUrl: string, auth: JiraApiCredential): string =>
+  auth.type === "oauth2" ? `https://api.atlassian.com/ex/jira/${auth.cloudId}` : baseUrl
+
+/**
+ * Where the credential is turned into a header.
+ *
+ * Both the host and the `Authorization` header come from `auth`, so they are derived together from
+ * one value rather than separately from two reads that could disagree about which site is being
+ * addressed. When `resolveAuth` is present that pair is recomputed per request, which is the only
+ * way a token refreshed mid-run reaches the wire — `mapRequest` would capture the startup value.
+ */
+const addressAndAuthorize = (
+  config: JiraApiConfigContract
+): (client: HttpClient.HttpClient) => HttpClient.HttpClient => {
+  const resolve = config.resolveAuth
+  if (resolve === undefined) {
+    return HttpClient.mapRequest(flow(
+      HttpClientRequest.prependUrl(apiBaseUrl(config.baseUrl, config.auth)),
+      HttpClientRequest.setHeader("Authorization", authorizationHeader(config.auth))
+    ))
+  }
+  return HttpClient.mapRequestEffect((request) =>
+    Effect.map(resolve, (auth) =>
+      request.pipe(
+        HttpClientRequest.prependUrl(apiBaseUrl(config.baseUrl, auth)),
+        HttpClientRequest.setHeader("Authorization", authorizationHeader(auth))
+      ))
+  )
+}
 
 export const make = (
   httpClient: HttpClient.HttpClient,
-  config: JiraApiConfigShape
+  config: JiraApiConfigContract
 ): Generated.JiraApi =>
   Generated.make(httpClient.pipe(
-    HttpClient.mapRequest(flow(
-      HttpClientRequest.prependUrl(apiBaseUrl(config)),
-      HttpClientRequest.setHeader("Authorization", authorizationHeader(config)),
-      HttpClientRequest.setHeader("Accept", "application/json")
-    ))
+    addressAndAuthorize(config),
+    HttpClient.mapRequest(HttpClientRequest.setHeader("Accept", "application/json"))
   ))
 
 const makeUploadAttachment =
-  (api: Generated.JiraApi): JiraApiClientShape["uploadAttachment"] => (issueIdOrKey, input) => {
+  (api: Generated.JiraApi): JiraApiClientContract["uploadAttachment"] => (issueIdOrKey, input) => {
     const buffer = new ArrayBuffer(input.bytes.byteLength)
     new Uint8Array(buffer).set(input.bytes)
     const form = new FormData()
@@ -77,7 +99,7 @@ const makeUploadAttachment =
     )
   }
 
-export class JiraApiClient extends Context.Service<JiraApiClient, JiraApiClientShape>()(
+export class JiraApiClient extends Context.Service<JiraApiClient, JiraApiClientContract>()(
   "@knpkv/jira-api-client/JiraApiClient"
 ) {
   static readonly layer: Layer.Layer<

package/src/JiraApiConfig.ts

@@ -7,22 +7,42 @@
  *   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.
+ * - **`auth` is a snapshot; `resolveAuth` is a subscription.** A credential that can expire needs the
+ *   second one — see its own note.
  *
  * @module
  */
 import * as Context from "effect/Context"
+import type * as Effect from "effect/Effect"
 import type * as Redacted from "effect/Redacted"
 
+/** How a request proves who is asking. */
+export type JiraApiCredential =
+  | { readonly type: "basic"; readonly email: string; readonly apiToken: Redacted.Redacted<string> }
+  | { readonly type: "oauth2"; readonly accessToken: Redacted.Redacted<string>; readonly cloudId: string }
+
 /**
  * Configuration shape for Jira API client.
  *
  * @category Config
  */
-export interface JiraApiConfigShape {
+export interface JiraApiConfigContract {
   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 }
+  readonly auth: JiraApiCredential
+  /**
+   * Re-read before every request, when supplied. Otherwise `auth` is used as given.
+   *
+   * A `Redacted` token is a value, so a client built from one is pinned to it for as long as the
+   * client lives. That is invisible in a command that exits in seconds and fatal in one that does
+   * not: an Atlassian access token lasts about an hour, after which every request 401s and no amount
+   * of retrying inside the process can recover, because the expired token is baked into the header.
+   * `jcf watch` is meant to run all day, so it supplies this and a refresh reaches the next request.
+   *
+   * Typed as infallible on purpose. This runs inside request preprocessing, where a new error would
+   * widen every operation's error channel; a resolver that cannot read its credential yields
+   * whatever it has, and the 401 that follows is the same one an absent login already produces.
+   */
+  readonly resolveAuth?: Effect.Effect<JiraApiCredential> | undefined
 }
 
 /**
@@ -46,6 +66,6 @@ export interface JiraApiConfigShape {
  *
  * @category Config
  */
-export class JiraApiConfig extends Context.Service<JiraApiConfig, JiraApiConfigShape>()(
+export class JiraApiConfig extends Context.Service<JiraApiConfig, JiraApiConfigContract>()(
   "@knpkv/jira-api-client/JiraApiConfig"
 ) {}

package/src/OwnOptionalKey.ts

@@ -0,0 +1,36 @@
+/**
+ * Optional struct keys that shadow `Object.prototype` members.
+ *
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Schema from "effect/Schema"
+import * as SchemaGetter from "effect/SchemaGetter"
+
+/** `Object.prototype` members that Jira payloads use as ordinary field names. */
+export type PrototypeKey = "toString"
+
+/**
+ * Optional key for a field named after an `Object.prototype` member, such as Jira's `toString`.
+ *
+ * Effect resolves declared struct keys with `in`, so a JSON object that omits `toString` presents the inherited
+ * `Object.prototype.toString`. Only that exact inherited function decodes as an absent key; any other value must
+ * satisfy `schema`. Use it in place of `Schema.optionalKey(schema)` for these keys; the encoded and decoded types
+ * stay those of `Schema.optionalKey(schema)`.
+ */
+export const ownOptionalKey = <S extends Schema.Top>(key: PrototypeKey, schema: S) => {
+  const inherited = Object.prototype[key]
+  // Typed `never`: the inherited member is not a domain value and never survives decoding.
+  const isInherited = Predicate.compose(
+    Predicate.isFunction,
+    (member: Function): member is never => member === inherited
+  )
+  const InheritedMember = Schema.declare(isInherited, { expected: `the inherited Object.prototype.${key}` })
+  return Schema.optionalKey(Schema.Union([schema, InheritedMember])).pipe(
+    Schema.decodeTo(Schema.optionalKey(Schema.toType(schema)), {
+      decode: SchemaGetter.transformOptional(Option.filter(Predicate.not(isInherited))),
+      encode: SchemaGetter.passthrough()
+    })
+  )
+}