@knpkv/clockify-api-client 0.2.0 → 1.0.0

package/dist/index.d.ts

@@ -1,12 +1,10 @@
 /**
- * Root barrel export for `@knpkv/clockify-api-client` -- openapi-fetch + Effect Clockify REST client.
+ * Root barrel export for the Schema-validated Effect Clockify 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 { ClockifyApiClient, type ClockifyApiClientShape, type ClockifyClientError, layer, make } from "./ClockifyApiClient.js";
+export type { AuthenticatedClockifyApi, 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";
+export * as ClockifyApi from "./generated/ClockifyApi.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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,EACL,IAAI,EACL,MAAM,wBAAwB,CAAA;AAE/B,YAAY,EACV,wBAAwB,EACxB,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,KAAK,WAAW,MAAM,4BAA4B,CAAA"}

package/dist/index.js

@@ -1,10 +1,9 @@
 /**
- * Root barrel export for `@knpkv/clockify-api-client` -- openapi-fetch + Effect Clockify REST client.
+ * Root barrel export for the Schema-validated Effect Clockify client.
  *
  * @packageDocumentation
  */
-export { ClockifyApiClient, layer } from "./ClockifyApiClient.js";
+export { ClockifyApiClient, layer, make } from "./ClockifyApiClient.js";
 export { ClockifyApiConfig } from "./ClockifyApiConfig.js";
-export { ClockifyApiError } from "./ClockifyApiError.js";
-export { FetchClientError, makeOpenApiFetchClient, toEffect } from "./OpenApiFetchClient.js";
+export * as ClockifyApi from "./generated/ClockifyApi.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,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,iBAAiB,EAGjB,KAAK,EACL,IAAI,EACL,MAAM,wBAAwB,CAAA;AAgB/B,OAAO,EAAE,iBAAiB,EAA+B,MAAM,wBAAwB,CAAA;AAEvF,OAAO,KAAK,WAAW,MAAM,4BAA4B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knpkv/clockify-api-client",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Effect-based Clockify REST API client",
   "license": "MIT",
   "author": "knpkv",
@@ -26,33 +26,27 @@
       "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"
+      "import": "./dist/generated/ClockifyApi.js",
+      "types": "./dist/generated/ClockifyApi.d.ts"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "effect": "^3.19.3"
-  },
-  "dependencies": {
-    "openapi-fetch": "^0.17.0"
+    "effect": "4.0.0-beta.98"
   },
   "devDependencies": {
-    "@effect/vitest": "latest",
+    "@effect/openapi-generator": "4.0.0-beta.98",
+    "@effect/platform-node": "4.0.0-beta.98",
+    "@effect/vitest": "4.0.0-beta.98",
     "@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"
+    "effect": "4.0.0-beta.98",
+    "prettier": "^3.9.5",
+    "tsx": "^4.23.0",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.10"
   },
   "keywords": [
     "effect",
@@ -63,11 +57,12 @@
     "openapi"
   ],
   "scripts": {
-    "build": "tsc && cp src/generated/schema.d.ts dist/generated/schema.d.ts",
-    "check": "tsc --noEmit",
+    "build": "tsc",
+    "check": "tsc --noEmit && tsc -p scripts/tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src",
-    "regenerate": "tsx scripts/regenerate.ts"
+    "regenerate": "tsx scripts/regenerate.ts",
+    "regenerate:check": "tsx scripts/regenerate.ts --check"
   }
 }

package/scripts/regenerate.ts

@@ -1,138 +1,230 @@
 #!/usr/bin/env tsx
 /**
- * Regeneration script for Clockify API client.
+ * Fetch, compare, patch, and regenerate the 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
+ * The committed OpenAPI document is the unmodified upstream document. RFC 6902
+ * patches are applied in memory before Effect's OpenAPI generator runs.
  */
+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 Console from "effect/Console"
+import * as Data from "effect/Data"
 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")
+import * as FileSystem from "effect/FileSystem"
+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://docs.clockify.me/openapi.json"
 
-interface SpecInfo {
-  version: string
-  title: string
-}
+class RegenerateError extends Data.TaggedError("RegenerateError")<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}
 
-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 JsonString = Schema.fromJsonString(Schema.Json)
 
-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}`)
-  })
+const OpenApiDocument = Schema.declare<OpenAPISpec>(
+  (value): value is OpenAPISpec =>
+    Predicate.hasProperty(value, "paths") &&
+    Predicate.isObject(value.paths) &&
+    (Predicate.hasProperty(value, "openapi") || Predicate.hasProperty(value, "swagger")),
+  { identifier: "OpenApiDocument" }
+)
 
-/**
- * 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
-          }
-        }
+const SpecInfo = Schema.Struct({
+  info: Schema.Struct({ version: Schema.String })
+})
 
-        // Set required fields
-        if (patch.required) {
-          schema.required = patch.required
-        }
-      }
+interface ScriptPaths {
+  readonly packageDir: string
+  readonly specFile: string
+  readonly patchFile: string
+  readonly outputFile: string
+  readonly versionFile: string
+}
 
-      fs.writeFileSync(SPEC_FILE, JSON.stringify(spec, null, 2), "utf-8")
-    },
-    catch: (e) => new Error(`Patch failed: ${e}`)
-  })
+const paths = Effect.gen(function*() {
+  const path = yield* Path.Path
+  const scriptFile = yield* path.fromFileUrl(new URL(import.meta.url)).pipe(
+    Effect.mapError((cause) => new RegenerateError({ message: "Could not resolve script path", cause }))
+  )
+  const packageDir = path.join(path.dirname(scriptFile), "..")
+  const specsDir = path.join(packageDir, ".specs")
+  return {
+    packageDir,
+    specFile: path.join(specsDir, "clockify-v1.json"),
+    patchFile: path.join(specsDir, "clockify-v1.patch.json"),
+    outputFile: path.join(packageDir, "src", "generated", "ClockifyApi.ts"),
+    versionFile: path.join(specsDir, "VERSION")
+  } satisfies ScriptPaths
+})
 
-const generateTypes = (): Effect.Effect<void, Error> =>
-  Effect.try({
-    try: () => {
-      execSync(`npx openapi-typescript "${SPEC_FILE}" -o "${OUTPUT_FILE}"`, {
-        cwd: path.join(__dirname, ".."),
-        stdio: "inherit"
+const fetchUpstream = HttpClient.get(SPEC_URL).pipe(
+  Effect.flatMap((response) =>
+    response.status >= 200 && response.status < 300
+      ? response.text.pipe(
+        Effect.mapError((cause) => new RegenerateError({ message: "Could not read Clockify response", cause }))
+      )
+      : Effect.fail(
+        new RegenerateError({
+          message: `Clockify spec request failed with status ${response.status}`
+        })
+      )
+  ),
+  Effect.flatMap(Schema.decodeUnknownEffect(JsonString)),
+  Effect.mapError((cause) => new RegenerateError({ message: "Could not fetch or decode Clockify spec", cause }))
+)
+
+const canonicalJson = (value: Schema.Json) =>
+  Schema.encodeEffect(JsonString)(value).pipe(
+    Effect.map((json) => `${json}\n`),
+    Effect.mapError((cause) => new RegenerateError({ message: "Could not encode Clockify spec", cause }))
+  )
+
+const formattedJson = (value: Schema.Json) =>
+  Schema.encodeEffect(JsonString)(value).pipe(
+    Effect.flatMap((source) =>
+      Effect.tryPromise({
+        try: () => formatSource(source, { parser: "json", printWidth: 120, trailingComma: "none", semi: false }),
+        catch: (cause) => new RegenerateError({ message: "Could not format Clockify spec", cause })
       })
-    },
-    catch: (e) => new Error(`Generation failed: ${e}`)
-  })
-
-const program = Effect.gen(function*() {
-  yield* Console.log("Fetching Clockify API spec version...")
+    ),
+    Effect.mapError((cause) => new RegenerateError({ message: "Could not format Clockify spec", cause }))
+  )
 
-  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}`)
+const stripUnreliableMetadata = (schema: JsonSchema.JsonSchema): JsonSchema.JsonSchema => {
+  const { default: _default, examples: _examples, ...normalized } = schema
+  return normalized
+}
 
-  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 })
+const stripTrailingWhitespace = (source: string): string => source.replace(/[ \t]+$/gm, "")
 
-    yield* Console.log(`Fetching spec (${info.version})...`)
-    yield* fetchAndSaveSpec()
-    fs.writeFileSync(VERSION_FILE, info.version, "utf-8")
+/**
+ * The pinned Effect generator emits an unused decoder when a spec declares no typed error bodies.
+ * Remove only that exact unused block; fail if the generator shape changes.
+ */
+const removeUnusedErrorDecoder = (source: string): string => {
+  const marker = "  const decodeError ="
+  if (!source.includes(marker)) return source
+  const cleaned = source.replace(/\n {2}const decodeError =[\s\S]*?\n {2}return \{/m, "\n  return {")
+  if (cleaned === source || cleaned.includes(marker)) {
+    throw new RegenerateError({ message: "Effect generator output changed around decodeError" })
   }
+  return cleaned
+}
 
-  yield* Console.log("Applying patches...")
-  yield* applyPatches()
-
-  yield* Console.log("Generating types...")
-  yield* generateTypes()
-
-  yield* Console.log("Done.")
+/**
+ * The generator currently passes record-shaped multipart payloads to
+ * `bodyFormData`, which expects an already-built Web FormData value. Use the
+ * record-aware Effect helper so strings and Blob/File values are serialized
+ * with a real multipart boundary by the runtime.
+ */
+const normalizeMultipartBodies = (source: string): string =>
+  source.replaceAll("HttpClientRequest.bodyFormData(", "HttpClientRequest.bodyFormDataRecord(")
+
+const generate = Effect.fn("Clockify.regenerate.generate")(function*(
+  scriptPaths: ScriptPaths,
+  upstream: Schema.Json
+) {
+  const fs = yield* FileSystem.FileSystem
+  const patch = yield* OpenApiPatch.parsePatchInput(scriptPaths.patchFile).pipe(
+    Effect.mapError((cause) => new RegenerateError({ message: "Could not parse Clockify JSON patch", cause }))
+  )
+  const patched = yield* OpenApiPatch.applyPatches(
+    [{ source: scriptPaths.patchFile, patch }],
+    upstream
+  ).pipe(
+    Effect.mapError((cause) => new RegenerateError({ message: "Could not apply Clockify JSON patch", cause }))
+  )
+  const document = yield* Schema.decodeUnknownEffect(OpenApiDocument)(patched).pipe(
+    Effect.mapError((cause) => new RegenerateError({ message: "Patched Clockify document is not OpenAPI", cause }))
+  )
+  const generator = yield* OpenApiGenerator.OpenApiGenerator
+  const warnings: Array<OpenApiGenerator.OpenApiGeneratorWarning> = []
+  const generated = yield* generator.generate(document, {
+    name: "ClockifyApi",
+    format: "httpclient",
+    onEnter: stripUnreliableMetadata,
+    onWarning: (warning) => warnings.push(warning)
+  })
+  yield* Effect.forEach(
+    warnings,
+    (warning) => Console.warn(`[${warning.code}] ${warning.method ?? ""} ${warning.path ?? ""}: ${warning.message}`),
+    { discard: true }
+  )
+  yield* fs.writeFileString(
+    scriptPaths.outputFile,
+    stripTrailingWhitespace(normalizeMultipartBodies(removeUnusedErrorDecoder(generated)))
+  ).pipe(
+    Effect.mapError((cause) => new RegenerateError({ message: "Could not write generated Clockify client", cause }))
+  )
 })
 
-Effect.runPromise(program).catch(console.error)
+const check = Flag.boolean("check").pipe(
+  Flag.withDescription("Exit non-zero when the committed upstream spec differs from Clockify")
+)
+
+const local = Flag.boolean("local").pipe(
+  Flag.withDescription("Regenerate from the committed spec without contacting Clockify")
+)
+
+const root = Command.make("clockify-api-regenerate", { check, local }).pipe(
+  Command.withHandler(
+    Effect.fn("Clockify.regenerate")(function*({ check, local }) {
+      const fs = yield* FileSystem.FileSystem
+      const scriptPaths = yield* paths
+      const upstream = local
+        ? yield* fs.readFileString(scriptPaths.specFile).pipe(
+          Effect.flatMap(Schema.decodeUnknownEffect(JsonString)),
+          Effect.mapError((cause) => new RegenerateError({ message: "Could not read committed Clockify spec", cause }))
+        )
+        : yield* fetchUpstream
+      const encoded = yield* canonicalJson(upstream)
+      const current = yield* fs.readFileString(scriptPaths.specFile).pipe(
+        Effect.flatMap(Schema.decodeUnknownEffect(JsonString)),
+        Effect.flatMap(canonicalJson),
+        Effect.orElseSucceed(() => "")
+      )
+
+      if (check) {
+        if (local) {
+          return yield* new RegenerateError({ message: "--check and --local cannot be combined" })
+        }
+        if (current === encoded) {
+          return yield* Console.log("Clockify OpenAPI spec is current.")
+        }
+        return yield* new RegenerateError({
+          message: "Clockify OpenAPI spec changed; run `pnpm --filter @knpkv/clockify-api-client regenerate`"
+        })
+      }
+
+      const { info } = yield* Schema.decodeUnknownEffect(SpecInfo)(upstream).pipe(
+        Effect.mapError((cause) => new RegenerateError({ message: "Clockify spec has no version", cause }))
+      )
+      yield* fs.writeFileString(scriptPaths.specFile, yield* formattedJson(upstream))
+      yield* fs.writeFileString(scriptPaths.versionFile, `${info.version}\n`)
+      yield* generate(scriptPaths, upstream)
+      yield* Console.log(`Generated Clockify ${info.version} client from ${SPEC_URL}`)
+    })
+  )
+)
+
+const MainLayer = Layer.mergeAll(
+  OpenApiGenerator.layerTransformerSchema,
+  NodeHttpClient.layerFetch,
+  NodeServices.layer
+)
+
+Command.run(root, { version: "1.0.0" }).pipe(
+  Effect.provide(MainLayer),
+  NodeRuntime.runMain
+)

package/scripts/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../tsconfig.base.jsonc",
+  "compilerOptions": {
+    "composite": false,
+    "declaration": false,
+    "declarationMap": false,
+    "incremental": false,
+    "noEmit": true,
+    "rootDir": "..",
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"]
+}