@knpkv/clockify-api-client 1.0.3 → 2.0.0

package/src/index.ts

@@ -6,7 +6,7 @@
 
 export {
   ClockifyApiClient,
-  type ClockifyApiClientShape,
+  type ClockifyApiClientContract,
   type ClockifyClientError,
   layer,
   make
@@ -28,6 +28,6 @@ export type {
   WorkspaceUser
 } from "./ClockifyApiClient.js"
 
-export { ClockifyApiConfig, type ClockifyApiConfigShape } from "./ClockifyApiConfig.js"
+export { ClockifyApiConfig, type ClockifyApiConfigContract } from "./ClockifyApiConfig.js"
 
 export * as ClockifyApi from "./generated/ClockifyApi.js"

package/test/ClockifyApiClient.test.ts

@@ -1,44 +1,67 @@
-import { describe, expect, it } from "@effect/vitest"
+import { assert, describe, expect, it } from "@effect/vitest"
 import * as Effect from "effect/Effect"
+import * as HttpClient from "effect/http/HttpClient"
+import type * as HttpClientRequest from "effect/http/HttpClientRequest"
+import * as HttpClientResponse from "effect/http/HttpClientResponse"
 import * as Layer from "effect/Layer"
+import * as Predicate from "effect/Predicate"
 import * as Redacted from "effect/Redacted"
-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 { ClockifyApiClient, ClockifyApiConfig, make } from "../src/index.js"
 
-const clientLayer = (
-  response: { readonly status: number; readonly body: unknown },
-  requests: Array<HttpClientRequest.HttpClientRequest>
-) =>
-  ClockifyApiClient.layer.pipe(
-    Layer.provide(Layer.succeed(ClockifyApiConfig, {
-      apiKey: Redacted.make("secret"),
-      workspaceId: "workspace-1",
-      userId: "user-1",
-      baseUrl: "https://clockify.test/api"
-    })),
-    Layer.provide(Layer.succeed(
-      HttpClient.HttpClient,
-      HttpClient.make((request) =>
-        Effect.sync(() => {
-          requests.push(request)
-          return HttpClientResponse.fromWeb(
-            request,
-            new Response(JSON.stringify(response.body), {
-              status: response.status,
-              headers: { "content-type": "application/json" }
-            })
-          )
-        })
-      )
-    ))
-  )
+/**
+ * What the fake transport answers next, and what it was asked.
+ *
+ * Held at module scope rather than built per test so the client can be composed once, by
+ * `it.layer`, instead of provided inside each test body. Each test calls {@link reply} first, which
+ * both sets its response and clears the recorded requests, so no test can read another's.
+ */
+let requests: Array<HttpClientRequest.HttpClientRequest> = []
+let respond: (request: HttpClientRequest.HttpClientRequest, callIndex: number) => Response = () =>
+  new Response("null", { status: 200, headers: { "content-type": "application/json" } })
 
-describe("ClockifyApiClient", () => {
-  it.effect("authenticates requests and decodes responses with Schema", () => {
-    const requests: Array<HttpClientRequest.HttpClientRequest> = []
-    return Effect.gen(function*() {
+const json = <ResponseBody>(status: number, body: ResponseBody): Response =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } })
+
+/** Answer every request in this test the same way. */
+const reply = <ResponseBody>(status: number, body: ResponseBody): void => {
+  requests = []
+  respond = () => json(status, body)
+}
+
+/** Answer request `n` of this test from a function of its index — for paging. */
+const replyPerCall = <ResponseBody>(
+  answer: (callIndex: number) => { status: number; body: ResponseBody }
+): void => {
+  requests = []
+  respond = (_request, callIndex) => {
+    const { body, status } = answer(callIndex)
+    return json(status, body)
+  }
+}
+
+const suite = ClockifyApiClient.layer.pipe(
+  Layer.provide(Layer.succeed(ClockifyApiConfig, {
+    apiKey: Redacted.make("secret"),
+    workspaceId: "workspace-1",
+    userId: "user-1",
+    baseUrl: "https://clockify.test/api"
+  })),
+  Layer.provide(Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.sync(() => {
+        const callIndex = requests.length
+        requests.push(request)
+        return HttpClientResponse.fromWeb(request, respond(request, callIndex))
+      })
+    )
+  ))
+)
+
+it.layer(suite)("ClockifyApiClient", (it) => {
+  it.effect("authenticates requests and decodes responses with Schema", () =>
+    Effect.gen(function*() {
+      reply(200, { id: "user-1", name: "Ada", email: "ada@example.com", status: "ACTIVE" })
       const client = yield* ClockifyApiClient
       const user = yield* client.getUser()
       expect(user.id).toBe("user-1")
@@ -46,43 +69,38 @@ describe("ClockifyApiClient", () => {
       expect(requests).toHaveLength(1)
       expect(requests[0]?.url).toBe("https://clockify.test/api/v1/user")
       expect(requests[0]?.headers["x-api-key"]).toBe("secret")
-    }).pipe(
-      Effect.provide(clientLayer({
-        status: 200,
-        body: { id: "user-1", name: "Ada", email: "ada@example.com", status: "ACTIVE" }
-      }, requests))
-    )
-  })
+    }))
 
-  it.effect("decodes nullable interval fields for a running time entry", () => {
-    const requests: Array<HttpClientRequest.HttpClientRequest> = []
-    return Effect.gen(function*() {
+  it.effect("decodes nullable interval fields for a running time entry", () =>
+    Effect.gen(function*() {
+      reply(200, [{
+        id: "entry-1",
+        description: "In progress",
+        billable: false,
+        userId: "user-1",
+        workspaceId: "workspace-1",
+        timeInterval: { start: "2026-07-11T08:00:00Z", end: null, duration: null }
+      }])
       const client = yield* ClockifyApiClient
       const entry = yield* client.getRunningTimer("workspace-1", "user-1")
       expect(entry?.timeInterval?.end).toBeNull()
       expect(entry?.timeInterval?.duration).toBeNull()
-    }).pipe(
-      Effect.provide(clientLayer({
-        status: 200,
-        body: [{
-          id: "entry-1",
-          description: "In progress",
-          billable: false,
-          userId: "user-1",
-          workspaceId: "workspace-1",
-          timeInterval: {
-            start: "2026-07-11T08:00:00Z",
-            end: null,
-            duration: null
-          }
-        }]
-      }, requests))
-    )
-  })
+    }))
 
-  it.effect("requests hydrated time-entry details when required by the caller", () => {
-    const requests: Array<HttpClientRequest.HttpClientRequest> = []
-    return Effect.gen(function*() {
+  it.effect("requests hydrated time-entry details when required by the caller", () =>
+    Effect.gen(function*() {
+      reply(200, {
+        id: "entry-1",
+        workspaceId: "workspace-1",
+        userId: "user-1",
+        description: "Review payment safeguards",
+        billable: true,
+        customFieldValues: [],
+        projectId: "project-1",
+        taskId: "task-1",
+        tagIds: ["delivery"],
+        timeInterval: { start: "2026-07-11T08:00:00Z", end: "2026-07-11T09:00:00Z", duration: "PT1H" }
+      })
       const client = yield* ClockifyApiClient
       const entry = yield* client.getTimeEntry("workspace-1", "entry-1", { hydrated: true })
       yield* client.getTimeEntry("workspace-1", "entry-1")
@@ -91,81 +109,33 @@ describe("ClockifyApiClient", () => {
       expect(new Map(requests[0]?.urlParams ?? []).get("hydrated")).toBe("true")
       expect(new Map(requests[1]?.urlParams ?? []).has("hydrated")).toBe(false)
       expect(new Map(requests[2]?.urlParams ?? []).get("hydrated")).toBe("false")
-    }).pipe(
-      Effect.provide(clientLayer({
-        status: 200,
-        body: {
-          id: "entry-1",
-          workspaceId: "workspace-1",
-          userId: "user-1",
-          description: "Review payment safeguards",
-          billable: true,
-          customFieldValues: [],
-          projectId: "project-1",
-          taskId: "task-1",
-          tagIds: ["delivery"],
-          timeInterval: {
-            start: "2026-07-11T08:00:00Z",
-            end: "2026-07-11T09:00:00Z",
-            duration: "PT1H"
-          }
-        }
-      }, requests))
-    )
-  })
+    }))
 
-  it.effect("forwards hydration when listing canonical time-entry snapshots", () => {
-    const requests: Array<HttpClientRequest.HttpClientRequest> = []
-    return Effect.gen(function*() {
+  it.effect("forwards hydration when listing canonical time-entry snapshots", () =>
+    Effect.gen(function*() {
+      reply(200, [])
       const client = yield* ClockifyApiClient
-      yield* client.getTimeEntries("workspace-1", "user-1", {
-        hydrated: true,
-        page: 2,
-        pageSize: 10
-      })
+      yield* client.getTimeEntries("workspace-1", "user-1", { hydrated: true, page: 2, pageSize: 10 })
       expect(new Map(requests[0]?.urlParams ?? []).get("hydrated")).toBe("true")
       expect(new Map(requests[0]?.urlParams ?? []).get("page")).toBe("2")
       expect(new Map(requests[0]?.urlParams ?? []).get("page-size")).toBe("10")
-    }).pipe(
-      Effect.provide(clientLayer({ status: 200, body: [] }, requests))
-    )
-  })
-
-  it.effect("pages through the complete workspace user directory", () => {
-    const requests: Array<HttpClientRequest.HttpClientRequest> = []
-    const firstPage = Array.from({ length: 500 }, (_, index) => ({
-      id: `user-${index}`,
-      name: `User ${index}`,
-      email: `user-${index}@example.test`,
-      status: "ACTIVE"
     }))
-    const layer = ClockifyApiClient.layer.pipe(
-      Layer.provide(Layer.succeed(ClockifyApiConfig, {
-        apiKey: Redacted.make("secret"),
-        workspaceId: "workspace-1",
-        userId: "user-1",
-        baseUrl: "https://clockify.test/api"
-      })),
-      Layer.provide(Layer.succeed(
-        HttpClient.HttpClient,
-        HttpClient.make((request) =>
-          Effect.sync(() => {
-            requests.push(request)
-            const body = requests.length <= 20
-              ? firstPage
-              : [{ id: "configured-user", name: "Configured User", email: "configured@example.test", status: "ACTIVE" }]
-            return HttpClientResponse.fromWeb(
-              request,
-              new Response(JSON.stringify(body), {
-                status: 200,
-                headers: { "content-type": "application/json" }
-              })
-            )
-          })
-        )
-      ))
-    )
-    return Effect.gen(function*() {
+
+  it.effect("pages through the complete workspace user directory", () =>
+    Effect.gen(function*() {
+      const firstPage = Array.from({ length: 500 }, (_, index) => ({
+        id: `user-${index}`,
+        name: `User ${index}`,
+        email: `user-${index}@example.test`,
+        status: "ACTIVE"
+      }))
+      // Twenty full pages, then a short one — the only thing that ends the walk.
+      replyPerCall((callIndex) => ({
+        status: 200,
+        body: callIndex < 20
+          ? firstPage
+          : [{ id: "configured-user", name: "Configured User", email: "configured@example.test", status: "ACTIVE" }]
+      }))
       const client = yield* ClockifyApiClient
       if (client.getWorkspaceUsers === undefined) return assert.fail("expected workspace user discovery")
       const users = yield* client.getWorkspaceUsers("workspace-1")
@@ -178,16 +148,26 @@ describe("ClockifyApiClient", () => {
         "ACTIVE,PENDING_EMAIL_VERIFICATION,DELETED,NOT_REGISTERED,LIMITED,LIMITED_DELETED"
       )
       expect(new Map(requests[0]?.urlParams ?? []).get("memberships")).toBe("ALL")
-    }).pipe(Effect.provide(layer))
-  })
+    }))
 
-  it.effect("decodes a created time entry whose optional id references are null", () => {
-    const requests: Array<HttpClientRequest.HttpClientRequest> = []
-    return Effect.gen(function*() {
-      const client = yield* ClockifyApiClient
+  it.effect("decodes a created time entry whose optional id references are null", () =>
+    Effect.gen(function*() {
       // Clockify returns kioskId/projectId/taskId as explicit null (not absent) when unset.
+      reply(201, {
+        id: "entry-1",
+        description: "[ENG-6169] review transaction mapper",
+        billable: true,
+        userId: "user-1",
+        workspaceId: "workspace-1",
+        kioskId: null,
+        projectId: null,
+        taskId: null,
+        tagIds: null,
+        timeInterval: { start: "2026-07-20T09:00:00Z", end: null, duration: null }
+      })
+      const client = yield* ClockifyApiClient
       const entry = yield* client.createTimeEntry("workspace-1", {
-        description: "[RPS-6169] review transaction mapper",
+        description: "[ENG-6169] review transaction mapper",
         start: "2026-07-20T09:00:00Z"
       })
       expect(entry.id).toBe("entry-1")
@@ -195,69 +175,55 @@ describe("ClockifyApiClient", () => {
       expect(entry.projectId).toBeNull()
       expect(entry.taskId).toBeNull()
       expect(entry.tagIds).toBeNull()
-    }).pipe(
-      Effect.provide(clientLayer({
-        status: 201,
-        body: {
-          id: "entry-1",
-          description: "[RPS-6169] review transaction mapper",
-          billable: true,
-          userId: "user-1",
-          workspaceId: "workspace-1",
-          kioskId: null,
-          projectId: null,
-          taskId: null,
-          tagIds: null,
-          timeInterval: {
-            start: "2026-07-20T09:00:00Z",
-            end: null,
-            duration: null
-          }
-        }
-      }, requests))
-    )
-  })
+    }))
 
-  it.effect("decodes a time-entries list whose entries have null tagIds", () => {
-    const requests: Array<HttpClientRequest.HttpClientRequest> = []
-    return Effect.gen(function*() {
-      const client = yield* ClockifyApiClient
+  it.effect("decodes a time-entries list whose entries have null tagIds", () =>
+    Effect.gen(function*() {
       // `jcf sync reconcile` fetches time entries; Clockify returns tagIds as
       // null (not an empty array) for entries with no tags.
+      reply(200, [{
+        id: "entry-1",
+        description: "[ENG-6169] review transaction mapper",
+        billable: true,
+        userId: "user-1",
+        workspaceId: "workspace-1",
+        tagIds: null,
+        timeInterval: { start: "2026-07-20T09:00:00Z", end: "2026-07-20T11:00:00Z", duration: "PT2H" }
+      }])
+      const client = yield* ClockifyApiClient
       const entries = yield* client.getTimeEntries("workspace-1", "user-1")
       expect(entries).toHaveLength(1)
       expect(entries[0]?.tagIds).toBeNull()
-    }).pipe(
-      Effect.provide(clientLayer({
-        status: 200,
-        body: [{
-          id: "entry-1",
-          description: "[RPS-6169] review transaction mapper",
-          billable: true,
-          userId: "user-1",
-          workspaceId: "workspace-1",
-          tagIds: null,
-          timeInterval: {
-            start: "2026-07-20T09:00:00Z",
-            end: "2026-07-20T11:00:00Z",
-            duration: "PT2H"
-          }
-        }]
-      }, requests))
-    )
-  })
+    }))
 
+  it.effect("fails when a successful response violates the generated schema", () =>
+    Effect.gen(function*() {
+      reply(200, { id: "user-1" })
+      const client = yield* ClockifyApiClient
+      const result = yield* Effect.result(client.getUser())
+      expect(result._tag).toBe("Failure")
+    }))
+
+  it.effect("fails on non-success status codes", () =>
+    Effect.gen(function*() {
+      reply(401, { message: "Unauthorized" })
+      const client = yield* ClockifyApiClient
+      const result = yield* Effect.result(client.getUser())
+      expect(result._tag).toBe("Failure")
+    }))
+})
+
+// Builds its own client rather than taking the suite's: the boundary under test is `make` itself,
+// which is where the multipart request is constructed.
+describe("ClockifyApiClient multipart", () => {
   it.effect("leaves multipart content type unset so the transport can add its boundary", () => {
-    const requests: Array<HttpClientRequest.HttpClientRequest> = []
+    const seen: Array<HttpClientRequest.HttpClientRequest> = []
     const httpClient = HttpClient.make((request) =>
       Effect.sync(() => {
-        requests.push(request)
+        seen.push(request)
         return HttpClientResponse.fromWeb(
           request,
-          new Response(JSON.stringify({ name: "avatar.png", url: "https://clockify.test/avatar.png" }), {
-            status: 200,
-            headers: { "content-type": "application/json" }
-          })
+          json(200, { name: "avatar.png", url: "https://clockify.test/avatar.png" })
         )
       })
     )
@@ -268,29 +234,14 @@ describe("ClockifyApiClient", () => {
 
     return Effect.gen(function*() {
       yield* client.uploadImage({ file: new Blob(["avatar bytes"], { type: "image/png" }) })
-      expect(requests[0]?.headers["content-type"]).toBeUndefined()
-      expect(requests[0]?.body._tag).toBe("FormData")
-      if (requests[0]?.body._tag !== "FormData") throw new Error("Expected a FormData request body")
-      const file = requests[0].body.formData.get("file")
-      expect(requests[0].body.formData).toBeInstanceOf(FormData)
-      expect(typeof file).not.toBe("string")
-      if (file === null || typeof file === "string") throw new Error("Expected a file field")
+      expect(seen[0]?.headers["content-type"]).toBeUndefined()
+      expect(seen[0]?.body._tag).toBe("FormData")
+      if (seen[0]?.body._tag !== "FormData") throw new Error("Expected a FormData request body")
+      const file = seen[0].body.formData.get("file")
+      expect(seen[0].body.formData).toBeInstanceOf(FormData)
+      if (file === null || Predicate.isString(file)) throw new Error("Expected a file field")
       expect(yield* Effect.promise(() => file.text())).toBe("avatar bytes")
-      expect(requests[0]?.headers["x-api-key"]).toBe("secret")
+      expect(seen[0]?.headers["x-api-key"]).toBe("secret")
     })
   })
-
-  it.effect("fails when a successful response violates the generated schema", () =>
-    Effect.gen(function*() {
-      const client = yield* ClockifyApiClient
-      const result = yield* Effect.result(client.getUser())
-      expect(result._tag).toBe("Failure")
-    }).pipe(Effect.provide(clientLayer({ status: 200, body: { id: "user-1" } }, []))))
-
-  it.effect("fails on non-success status codes", () =>
-    Effect.gen(function*() {
-      const client = yield* ClockifyApiClient
-      const result = yield* Effect.result(client.getUser())
-      expect(result._tag).toBe("Failure")
-    }).pipe(Effect.provide(clientLayer({ status: 401, body: { message: "Unauthorized" } }, []))))
 })

package/test/CustomFieldValues.test.ts

@@ -0,0 +1,18 @@
+import { assert, describe, it } from "@effect/vitest"
+import * as Schema from "effect/Schema"
+import { ClockifyApi } from "../src/index.js"
+
+// The spec declares custom-field values as objects, but Clockify sends and accepts scalars and arrays.
+describe("custom field values", () => {
+  it("decode the scalar values Clockify returns", () => {
+    for (const value of ["new value", 42, true, ["a", "b"]]) {
+      const decoded = Schema.decodeUnknownSync(ClockifyApi.CustomFieldValueDtoV1)({ customFieldId: "cf", value })
+      assert.deepStrictEqual(decoded.value, value)
+    }
+  })
+
+  it("encode a scalar update value", () => {
+    const encoded = Schema.encodeSync(ClockifyApi.UpdateCustomFieldRequest)({ customFieldId: "cf", value: "new value" })
+    assert.strictEqual(encoded.value, "new value")
+  })
+})

package/test/GeneratedSchemas.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "@effect/vitest"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import { type FeaturePlan, WorkspaceDtoV1 } from "../src/generated/ClockifyApi.js"
+
+describe("generated workspace schema", () => {
+  // Preserve both upstream spellings in responses without rewriting either value.
+  it.effect.each(["ADMINS", "ADMINS_AND_PROJECT_MANAGERS", "ANYONE", "EVERYONE"])(
+    "preserves scheduling assignment creator %s in workspace responses",
+    (creator) =>
+      Effect.gen(function*() {
+        const workspace = yield* Schema.decodeUnknownEffect(WorkspaceDtoV1)({
+          id: "workspace-1",
+          name: "Delivery",
+          workspaceSettings: {
+            schedulingSettings: { whoCanCreateAssignments: creator }
+          }
+        })
+        expect(workspace.workspaceSettings?.schedulingSettings?.whoCanCreateAssignments).toBe(creator)
+      })
+  )
+
+  it.effect("rejects undocumented scheduling assignment creators", () =>
+    Effect.gen(function*() {
+      const failure = yield* Schema.decodeUnknownEffect(WorkspaceDtoV1)({
+        id: "workspace-1",
+        name: "Delivery",
+        workspaceSettings: {
+          schedulingSettings: { whoCanCreateAssignments: "OWNER_ONLY" }
+        }
+      }).pipe(Effect.flip)
+      expect(failure._tag).toBe("SchemaError")
+    }))
+
+  it.effect("decodes feature plans after removing the upstream recursive oneOf", () =>
+    Effect.gen(function*() {
+      const plan: FeaturePlan = {
+        addonSubscriptionPlan: "PRO",
+        featurePermissions: ["AUDIT_LOG"],
+        paidPlan: true,
+        weight: 3
+      }
+      const workspace = yield* Schema.decodeUnknownEffect(WorkspaceDtoV1)({
+        id: "workspace-1",
+        name: "Delivery",
+        featureSubscriptionType: plan
+      })
+      expect(workspace.featureSubscriptionType).toEqual(plan)
+    }))
+
+  it.effect("rejects feature plans with a fractional weight", () =>
+    Effect.gen(function*() {
+      const failure = yield* Schema.decodeUnknownEffect(WorkspaceDtoV1)({
+        id: "workspace-1",
+        name: "Delivery",
+        featureSubscriptionType: { weight: 1.5 }
+      }).pipe(Effect.flip)
+      expect(failure._tag).toBe("SchemaError")
+    }))
+})