@knpkv/clockify-api-client 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Root barrel export for `@knpkv/clockify-api-client` -- openapi-fetch + Effect Clockify REST client.
+ *
+ * @packageDocumentation
+ */
+export { ClockifyApiClient, type ClockifyApiClientShape, layer } from "./ClockifyApiClient.js";
+export type { CreateTimeEntryParams, GetTimeEntriesParams, Project, StopTimeEntryParams, Tag, TimeEntry, TimeInterval, UpdateTimeEntryParams, User, Workspace } from "./ClockifyApiClient.js";
+export { ClockifyApiConfig, type ClockifyApiConfigShape } from "./ClockifyApiConfig.js";
+export { ClockifyApiError } from "./ClockifyApiError.js";
+export { FetchClientError, makeOpenApiFetchClient, type OpenApiFetchClient, type SuccessData, toEffect } from "./OpenApiFetchClient.js";
+export type * as V1 from "./generated/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;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAE9F,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,OAAO,EACP,mBAAmB,EACnB,GAAG,EACH,SAAS,EACT,YAAY,EACZ,qBAAqB,EACrB,IAAI,EACJ,SAAS,EACV,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAA;AAEvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,QAAQ,EACT,MAAM,yBAAyB,CAAA;AAGhC,YAAY,KAAK,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Root barrel export for `@knpkv/clockify-api-client` -- openapi-fetch + Effect Clockify REST client.
+ *
+ * @packageDocumentation
+ */
+export { ClockifyApiClient, layer } from "./ClockifyApiClient.js";
+export { ClockifyApiConfig } from "./ClockifyApiConfig.js";
+export { ClockifyApiError } from "./ClockifyApiError.js";
+export { FetchClientError, makeOpenApiFetchClient, 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;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAA+B,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAe9F,OAAO,EAAE,iBAAiB,EAA+B,MAAM,wBAAwB,CAAA;AAEvF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EAGtB,QAAQ,EACT,MAAM,yBAAyB,CAAA"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@knpkv/clockify-api-client",
+  "version": "0.2.0",
+  "description": "Effect-based Clockify REST API client",
+  "license": "MIT",
+  "author": "knpkv",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/knpkv/npm.git",
+    "directory": "packages/clockify-api-client"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./ClockifyApiClient": {
+      "import": "./dist/ClockifyApiClient.js",
+      "types": "./dist/ClockifyApiClient.d.ts"
+    },
+    "./ClockifyApiConfig": {
+      "import": "./dist/ClockifyApiConfig.js",
+      "types": "./dist/ClockifyApiConfig.d.ts"
+    },
+    "./ClockifyApiError": {
+      "import": "./dist/ClockifyApiError.js",
+      "types": "./dist/ClockifyApiError.d.ts"
+    },
+    "./generated": {
+      "import": "./dist/generated/index.js",
+      "types": "./dist/generated/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "effect": "^3.19.3"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.17.0"
+  },
+  "devDependencies": {
+    "@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",
+    "clockify",
+    "time-tracking",
+    "api-client",
+    "openapi"
+  ],
+  "scripts": {
+    "build": "tsc && cp src/generated/schema.d.ts dist/generated/schema.d.ts",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "regenerate": "tsx scripts/regenerate.ts"
+  }
+}

package/scripts/regenerate.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env tsx
+/**
+ * Regeneration script for Clockify API client.
+ *
+ * 1. Fetches latest OpenAPI spec from Clockify docs
+ * 2. Applies local patches (.specs/clockify-v1.patch.json) to fix incomplete DTOs
+ * 3. Generates TypeScript types via openapi-typescript
+ */
+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"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const SPECS_DIR = path.join(__dirname, "..", ".specs")
+const SPEC_FILE = path.join(SPECS_DIR, "clockify-v1.json")
+const PATCH_FILE = path.join(SPECS_DIR, "clockify-v1.patch.json")
+const OUTPUT_FILE = path.join(__dirname, "..", "src", "generated", "schema.d.ts")
+const VERSION_FILE = path.join(SPECS_DIR, "VERSION")
+const SPEC_URL = "https://docs.clockify.me/openapi.json"
+
+interface SpecInfo {
+  version: string
+  title: string
+}
+
+const fetchSpecInfo = (): Effect.Effect<SpecInfo, Error> =>
+  Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(SPEC_URL)
+      if (!response.ok) throw new Error(`Failed to fetch: ${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 = (): Effect.Effect<void, Error> =>
+  Effect.tryPromise({
+    try: async () => {
+      const response = await fetch(SPEC_URL)
+      if (!response.ok) throw new Error(`Failed to fetch: ${response.status}`)
+      fs.writeFileSync(SPEC_FILE, await response.text(), "utf-8")
+    },
+    catch: (e) => new Error(`Fetch/save failed: ${e}`)
+  })
+
+/**
+ * Apply patches from clockify-v1.patch.json to the spec in-place.
+ * Keeps original spec clean — patches add missing fields and required arrays.
+ */
+const applyPatches = (): Effect.Effect<void, Error> =>
+  Effect.try({
+    try: () => {
+      if (!fs.existsSync(PATCH_FILE)) return
+
+      const spec = JSON.parse(fs.readFileSync(SPEC_FILE, "utf-8"))
+      const patches = JSON.parse(fs.readFileSync(PATCH_FILE, "utf-8"))
+      const schemas = spec.components?.schemas ?? {}
+
+      for (const [schemaName, patch] of Object.entries(patches.schemas ?? {}) as Array<[string, Record<string, unknown>]>) {
+        const schema = schemas[schemaName]
+        if (!schema) continue
+
+        // Rename properties (e.g. get_id → id)
+        if (patch.renameProperties) {
+          for (const [from, to] of Object.entries(patch.renameProperties as Record<string, string>)) {
+            if (schema.properties?.[from]) {
+              schema.properties[to] = schema.properties[from]
+              delete schema.properties[from]
+            }
+          }
+        }
+
+        // Add new properties
+        if (patch.addProperties) {
+          schema.properties = { ...schema.properties, ...patch.addProperties }
+        }
+
+        // Patch existing properties (overwrite)
+        if (patch.patchProperties) {
+          for (const [name, value] of Object.entries(patch.patchProperties as Record<string, unknown>)) {
+            schema.properties[name] = value
+          }
+        }
+
+        // Set required fields
+        if (patch.required) {
+          schema.required = patch.required
+        }
+      }
+
+      fs.writeFileSync(SPEC_FILE, JSON.stringify(spec, null, 2), "utf-8")
+    },
+    catch: (e) => new Error(`Patch failed: ${e}`)
+  })
+
+const generateTypes = (): Effect.Effect<void, Error> =>
+  Effect.try({
+    try: () => {
+      execSync(`npx openapi-typescript "${SPEC_FILE}" -o "${OUTPUT_FILE}"`, {
+        cwd: path.join(__dirname, ".."),
+        stdio: "inherit"
+      })
+    },
+    catch: (e) => new Error(`Generation failed: ${e}`)
+  })
+
+const program = Effect.gen(function*() {
+  yield* Console.log("Fetching Clockify API spec version...")
+
+  const info = yield* fetchSpecInfo()
+  const current = fs.existsSync(VERSION_FILE) ? fs.readFileSync(VERSION_FILE, "utf-8").trim() : null
+
+  yield* Console.log(`Current: ${current ?? "none"}, Remote: ${info.version}`)
+
+  if (current === info.version) {
+    yield* Console.log("Spec up to date, regenerating types...")
+  } else {
+    if (!fs.existsSync(SPECS_DIR)) fs.mkdirSync(SPECS_DIR, { recursive: true })
+
+    yield* Console.log(`Fetching spec (${info.version})...`)
+    yield* fetchAndSaveSpec()
+    fs.writeFileSync(VERSION_FILE, info.version, "utf-8")
+  }
+
+  yield* Console.log("Applying patches...")
+  yield* applyPatches()
+
+  yield* Console.log("Generating types...")
+  yield* generateTypes()
+
+  yield* Console.log("Done.")
+})
+
+Effect.runPromise(program).catch(console.error)

package/src/ClockifyApiClient.ts

@@ -0,0 +1,278 @@
+/**
+ * Effect Layer wrapping openapi-fetch Clockify v1 client with auth and base URL.
+ *
+ * **Mental model**
+ *
+ * - **Auth via X-Api-Key**: The layer reads {@link ClockifyApiConfig} to build the
+ *   `X-Api-Key` header and derive the base URL.
+ * - **openapi-fetch wrapper**: Uses {@link OpenApiFetchClient} for type-safe HTTP calls.
+ * - **Method-based interface**: Exposes convenience methods (getUser, createTimeEntry, etc.)
+ *   for backwards compatibility with jira-clockify consumers.
+ * - **Raw API access**: `.api` exposes the raw `OpenApiFetchClient<paths>` for direct access.
+ *
+ * **Common tasks**
+ *
+ * - Use the client: `const clockify = yield* ClockifyApiClient`
+ * - Call a method: `clockify.getProjects(workspaceId)`
+ * - Raw access: `toEffect(clockify.api.client.GET("/v1/user"))`
+ * - Provide the layer: `Effect.provide(ClockifyApiClient.layer)`
+ *
+ * @module
+ */
+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 { ClockifyApiConfig } from "./ClockifyApiConfig.js"
+import type { components, paths } from "./generated/schema.js"
+import {
+  type FetchClientError,
+  makeOpenApiFetchClient,
+  type OpenApiFetchClient,
+  toEffect
+} from "./OpenApiFetchClient.js"
+
+// ---------------------------------------------------------------------------
+// Domain types — derived from patched OpenAPI spec schema
+// ---------------------------------------------------------------------------
+
+export type User = components["schemas"]["UserDto"]
+export type Workspace = components["schemas"]["WorkspaceDtoV1"]
+export type Project = components["schemas"]["ProjectDtoV1"]
+export type Tag = components["schemas"]["TagDto"]
+export type TimeInterval = components["schemas"]["TimeIntervalDto"]
+export type TimeEntry = components["schemas"]["TimeEntryDto"]
+export type CreateTimeEntryParams = components["schemas"]["CreateTimeEntryRequest"]
+export type StopTimeEntryParams = components["schemas"]["StopTimeEntryRequest"]
+export type UpdateTimeEntryParams = components["schemas"]["UpdateTimeEntryRequest"]
+
+export interface GetTimeEntriesParams {
+  readonly start?: string | undefined
+  readonly end?: string | undefined
+  readonly page?: number | undefined
+  readonly pageSize?: number | undefined
+}
+
+// ---------------------------------------------------------------------------
+// Client shape
+// ---------------------------------------------------------------------------
+
+export interface ClockifyApiClientShape {
+  /** Raw openapi-fetch client for direct type-safe API access. */
+  readonly api: OpenApiFetchClient<paths>
+
+  readonly getUser: () => Effect.Effect<User, FetchClientError>
+  readonly getWorkspaces: () => Effect.Effect<ReadonlyArray<Workspace>, FetchClientError>
+  readonly getProjects: (workspaceId: string) => Effect.Effect<ReadonlyArray<Project>, FetchClientError>
+  readonly getProjectByName: (workspaceId: string, name: string) => Effect.Effect<Project | null, FetchClientError>
+  readonly createTimeEntry: (
+    workspaceId: string,
+    params: CreateTimeEntryParams
+  ) => Effect.Effect<TimeEntry, FetchClientError>
+  readonly stopTimer: (
+    workspaceId: string,
+    userId: string,
+    params: StopTimeEntryParams
+  ) => Effect.Effect<TimeEntry, FetchClientError>
+  readonly getTimeEntries: (
+    workspaceId: string,
+    userId: string,
+    params?: GetTimeEntriesParams
+  ) => Effect.Effect<ReadonlyArray<TimeEntry>, FetchClientError>
+  readonly getRunningTimer: (
+    workspaceId: string,
+    userId: string
+  ) => Effect.Effect<TimeEntry | null, FetchClientError>
+  readonly getTags: (workspaceId: string) => Effect.Effect<ReadonlyArray<Tag>, FetchClientError>
+  readonly createTag: (workspaceId: string, name: string) => Effect.Effect<Tag, FetchClientError>
+  readonly findOrCreateTag: (workspaceId: string, name: string) => Effect.Effect<Tag, FetchClientError>
+  readonly getTimeEntry: (
+    workspaceId: string,
+    timeEntryId: string
+  ) => Effect.Effect<TimeEntry, FetchClientError>
+  readonly deleteTimeEntry: (workspaceId: string, timeEntryId: string) => Effect.Effect<void, FetchClientError>
+  readonly updateTimeEntry: (
+    workspaceId: string,
+    timeEntryId: string,
+    params: UpdateTimeEntryParams
+  ) => Effect.Effect<TimeEntry, FetchClientError>
+}
+
+// ---------------------------------------------------------------------------
+// Service tag + layer
+// ---------------------------------------------------------------------------
+
+export class ClockifyApiClient extends Context.Tag(
+  "@knpkv/clockify-api-client/ClockifyApiClient"
+)<ClockifyApiClient, ClockifyApiClientShape>() {
+  static readonly layer: Layer.Layer<ClockifyApiClient, never, ClockifyApiConfig> = Layer.effect(
+    ClockifyApiClient,
+    Effect.gen(function*() {
+      const config = yield* ClockifyApiConfig
+
+      const headers = {
+        "X-Api-Key": Redacted.value(config.apiKey),
+        "Content-Type": "application/json"
+      }
+
+      const api = makeOpenApiFetchClient<paths>(config.baseUrl, headers)
+      const { client } = api
+
+      return {
+        api,
+
+        getUser: () => toEffect(client.GET("/v1/user")) as Effect.Effect<User, FetchClientError>,
+
+        getWorkspaces: () =>
+          toEffect(client.GET("/v1/workspaces")) as unknown as Effect.Effect<
+            ReadonlyArray<Workspace>,
+            FetchClientError
+          >,
+
+        getProjects: (workspaceId) =>
+          toEffect(
+            client.GET("/v1/workspaces/{workspaceId}/projects", {
+              params: {
+                path: { workspaceId },
+                query: { archived: false, "page-size": 500 }
+              }
+            })
+          ) as Effect.Effect<ReadonlyArray<Project>, FetchClientError>,
+
+        getProjectByName: (workspaceId, name) =>
+          Effect.gen(function*() {
+            const projects = yield* toEffect(
+              client.GET("/v1/workspaces/{workspaceId}/projects", {
+                params: {
+                  path: { workspaceId },
+                  query: { name, archived: false }
+                }
+              })
+            ) as Effect.Effect<ReadonlyArray<Project>, FetchClientError>
+            return projects.find((p) => p.name.toLowerCase() === name.toLowerCase()) ?? null
+          }),
+
+        createTimeEntry: (workspaceId, params) =>
+          toEffect(
+            client.POST("/v1/workspaces/{workspaceId}/time-entries", {
+              params: { path: { workspaceId } },
+              body: {
+                description: params.description,
+                start: params.start,
+                ...(params.end ? { end: params.end } : {}),
+                ...(params.projectId ? { projectId: params.projectId } : {}),
+                ...(params.taskId ? { taskId: params.taskId } : {}),
+                ...(params.billable !== undefined ? { billable: params.billable } : {}),
+                ...(params.tagIds !== undefined ? { tagIds: [...params.tagIds] } : {})
+              }
+            })
+          ) as Effect.Effect<TimeEntry, FetchClientError>,
+
+        stopTimer: (workspaceId, userId, params) =>
+          toEffect(
+            client.PATCH("/v1/workspaces/{workspaceId}/user/{userId}/time-entries", {
+              params: { path: { workspaceId, userId } },
+              body: { end: params.end }
+            })
+          ) as Effect.Effect<TimeEntry, FetchClientError>,
+
+        getTimeEntries: (workspaceId, userId, params) =>
+          toEffect(
+            client.GET("/v1/workspaces/{workspaceId}/user/{userId}/time-entries", {
+              params: {
+                path: { workspaceId, userId },
+                query: {
+                  ...(params?.start !== undefined ? { start: params.start } : {}),
+                  ...(params?.end !== undefined ? { end: params.end } : {}),
+                  ...(params?.page !== undefined ? { page: params.page } : {}),
+                  ...(params?.pageSize !== undefined ? { "page-size": params.pageSize } : {})
+                }
+              }
+            })
+          ) as Effect.Effect<ReadonlyArray<TimeEntry>, FetchClientError>,
+
+        getRunningTimer: (workspaceId, userId) =>
+          Effect.gen(function*() {
+            const entries = yield* toEffect(
+              client.GET("/v1/workspaces/{workspaceId}/user/{userId}/time-entries", {
+                params: {
+                  path: { workspaceId, userId },
+                  query: { "in-progress": true, "page-size": 1 }
+                }
+              })
+            ) as Effect.Effect<ReadonlyArray<TimeEntry>, FetchClientError>
+            return entries.length > 0 ? entries[0]! : null
+          }),
+
+        getTimeEntry: (workspaceId, timeEntryId) =>
+          toEffect(
+            client.GET("/v1/workspaces/{workspaceId}/time-entries/{id}", {
+              params: { path: { workspaceId, id: timeEntryId } }
+            })
+          ) as Effect.Effect<TimeEntry, FetchClientError>,
+
+        updateTimeEntry: (workspaceId, timeEntryId, params) =>
+          toEffect(
+            client.PUT("/v1/workspaces/{workspaceId}/time-entries/{id}", {
+              params: { path: { workspaceId, id: timeEntryId } },
+              body: {
+                start: params.start,
+                ...(params.end !== undefined ? { end: params.end } : {}),
+                ...(params.description !== undefined ? { description: params.description } : {}),
+                ...(params.projectId !== undefined ? { projectId: params.projectId } : {}),
+                ...(params.billable !== undefined ? { billable: params.billable } : {}),
+                ...(params.tagIds !== undefined ? { tagIds: [...params.tagIds] } : {})
+              }
+            })
+          ) as Effect.Effect<TimeEntry, FetchClientError>,
+
+        getTags: (workspaceId) =>
+          toEffect(
+            client.GET("/v1/workspaces/{workspaceId}/tags", {
+              params: {
+                path: { workspaceId },
+                query: { archived: false, "page-size": 200 }
+              }
+            })
+          ) as Effect.Effect<ReadonlyArray<Tag>, FetchClientError>,
+
+        createTag: (workspaceId, name) =>
+          toEffect(
+            client.POST("/v1/workspaces/{workspaceId}/tags", {
+              params: { path: { workspaceId } },
+              body: { name }
+            })
+          ) as Effect.Effect<Tag, FetchClientError>,
+
+        findOrCreateTag: (workspaceId, name) =>
+          Effect.gen(function*() {
+            const tags = yield* toEffect(
+              client.GET("/v1/workspaces/{workspaceId}/tags", {
+                params: {
+                  path: { workspaceId },
+                  query: { name, archived: false }
+                }
+              })
+            ) as Effect.Effect<ReadonlyArray<Tag>, FetchClientError>
+            const existing = tags.find((t) => t.name.toLowerCase() === name.toLowerCase())
+            if (existing) return existing
+            return yield* toEffect(
+              client.POST("/v1/workspaces/{workspaceId}/tags", {
+                params: { path: { workspaceId } },
+                body: { name }
+              })
+            ) as Effect.Effect<Tag, FetchClientError>
+          }),
+
+        deleteTimeEntry: (workspaceId, timeEntryId) =>
+          toEffect(
+            client.DELETE("/v1/workspaces/{workspaceId}/time-entries/{id}", {
+              params: { path: { workspaceId, id: timeEntryId } }
+            })
+          ) as Effect.Effect<void, FetchClientError>
+      }
+    })
+  )
+}
+
+export const layer = ClockifyApiClient.layer

package/src/ClockifyApiConfig.ts

@@ -0,0 +1,25 @@
+/**
+ * Configuration service tag for the Clockify API client.
+ *
+ * **Mental model**
+ *
+ * - **Context.Tag for DI**: {@link ClockifyApiConfig} carries API key (as `Redacted`),
+ *   workspace ID, user ID, and base URL. Provided via `Layer.succeed` by the consumer.
+ * - **Redacted API key**: The `apiKey` field uses Effect's `Redacted` type to prevent
+ *   accidental logging of credentials.
+ *
+ * @module
+ */
+import * as Context from "effect/Context"
+import type * as Redacted from "effect/Redacted"
+
+export interface ClockifyApiConfigShape {
+  readonly apiKey: Redacted.Redacted<string>
+  readonly workspaceId: string
+  readonly userId: string
+  readonly baseUrl: string
+}
+
+export class ClockifyApiConfig extends Context.Tag(
+  "@knpkv/clockify-api-client/ClockifyApiConfig"
+)<ClockifyApiConfig, ClockifyApiConfigShape>() {}

package/src/ClockifyApiError.ts

@@ -0,0 +1,17 @@
+/**
+ * Tagged error for Clockify API failures.
+ *
+ * **Mental model**
+ *
+ * - **Catch by tag**: `Effect.catchTag("ClockifyApiError", ...)` handles all API errors.
+ *   The `status` field distinguishes HTTP errors (>0) from network errors (0).
+ *
+ * @module
+ */
+import * as Data from "effect/Data"
+
+export class ClockifyApiError extends Data.TaggedError("ClockifyApiError")<{
+  readonly status: number
+  readonly message: string
+  readonly cause?: unknown
+}> {}

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/index.ts

@@ -0,0 +1 @@
+export type { paths, components, operations } from "./schema.js"