@knpkv/clockify-api-client 1.0.2 → 1.1.1

package/dist/index.d.ts

@@ -3,8 +3,8 @@
  *
  * @packageDocumentation
  */
-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 { ClockifyApiClient, type ClockifyApiClientContract, type ClockifyClientError, layer, make } from "./ClockifyApiClient.js";
+export type { AuthenticatedClockifyApi, CreateTimeEntryParams, GetTimeEntriesParams, GetTimeEntryParams, Project, StopTimeEntryParams, Tag, TimeEntry, TimeInterval, UpdateTimeEntryParams, User, Workspace, WorkspaceUser } from "./ClockifyApiClient.js";
+export { ClockifyApiConfig, type ClockifyApiConfigContract } from "./ClockifyApiConfig.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,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,EACL,IAAI,EACL,MAAM,wBAAwB,CAAA;AAE/B,YAAY,EACV,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,OAAO,EACP,mBAAmB,EACnB,GAAG,EACH,SAAS,EACT,YAAY,EACZ,qBAAqB,EACrB,IAAI,EACJ,SAAS,EACT,aAAa,EACd,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,iBAAiB,EAAE,KAAK,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAE1F,OAAO,KAAK,WAAW,MAAM,4BAA4B,CAAA"}

package/dist/index.js.map

@@ -1 +1 @@
-{"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"}
+{"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;AAkB/B,OAAO,EAAE,iBAAiB,EAAkC,MAAM,wBAAwB,CAAA;AAE1F,OAAO,KAAK,WAAW,MAAM,4BAA4B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knpkv/clockify-api-client",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Effect-based Clockify REST API client",
   "license": "MIT",
   "author": "knpkv",
@@ -35,17 +35,17 @@
     "access": "public"
   },
   "peerDependencies": {
-    "effect": "4.0.0-beta.98"
+    "effect": "4.0.0-rc.109"
   },
   "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-rc.109",
+    "@effect/platform-node": "4.0.0-rc.109",
+    "@effect/vitest": "4.0.0-rc.109",
     "@types/node": "latest",
-    "effect": "4.0.0-beta.98",
-    "prettier": "^3.9.5",
-    "tsx": "^4.23.0",
-    "typescript": "~6.0.3",
+    "effect": "4.0.0-rc.109",
+    "prettier": "^3.9.6",
+    "tsx": "^4.23.12",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vitest": "^4.1.10"
   },
   "keywords": [

package/src/ClockifyApiClient.ts

@@ -23,6 +23,7 @@ import * as Generated from "./generated/ClockifyApi.js"
 export type ClockifyClientError = HttpClientError.HttpClientError | SchemaError
 
 export type User = Generated.GetLoggedUser200
+export type WorkspaceUser = Generated.GetUsersOfWorkspace200[number]
 export type Workspace = Generated.GetWorkspacesOfUser200[number]
 export type Project = Generated.GetProjects200[number]
 export type Tag = Generated.GetTags200[number]
@@ -39,12 +40,25 @@ export type AuthenticatedClockifyApi = Omit<Generated.ClockifyApi, "uploadImage"
 export interface GetTimeEntriesParams {
   readonly start?: string | undefined
   readonly end?: string | undefined
+  readonly hydrated?: boolean | undefined
   readonly page?: number | undefined
   readonly pageSize?: number | undefined
 }
 
-export interface ClockifyApiClientShape {
+export interface GetTimeEntryParams {
+  readonly hydrated?: boolean | undefined
+}
+
+export interface ClockifyApiClientContract {
   readonly getUser: () => Effect.Effect<User, ClockifyClientError>
+  readonly getWorkspaceUsers?: (
+    workspaceId: string
+  ) => Effect.Effect<ReadonlyArray<WorkspaceUser>, ClockifyClientError>
+  readonly getWorkspaceUsersPage?: (
+    workspaceId: string,
+    page: number,
+    pageSize: number
+  ) => Effect.Effect<ReadonlyArray<WorkspaceUser>, ClockifyClientError>
   readonly getWorkspaces: () => Effect.Effect<ReadonlyArray<Workspace>, ClockifyClientError>
   readonly getProjects: (workspaceId: string) => Effect.Effect<ReadonlyArray<Project>, ClockifyClientError>
   readonly getProjectByName: (workspaceId: string, name: string) => Effect.Effect<Project | null, ClockifyClientError>
@@ -77,7 +91,8 @@ export interface ClockifyApiClientShape {
   ) => Effect.Effect<Generated.GetTags200[number] | Generated.CreateNewTag201, ClockifyClientError>
   readonly getTimeEntry: (
     workspaceId: string,
-    timeEntryId: string
+    timeEntryId: string,
+    params?: GetTimeEntryParams
   ) => Effect.Effect<Generated.GetTimeEntry200, ClockifyClientError>
   readonly deleteTimeEntry: (workspaceId: string, timeEntryId: string) => Effect.Effect<void, ClockifyClientError>
   readonly updateTimeEntry: (
@@ -112,7 +127,7 @@ export const make = (
   }
 }
 
-export class ClockifyApiClient extends Context.Service<ClockifyApiClient, ClockifyApiClientShape>()(
+export class ClockifyApiClient extends Context.Service<ClockifyApiClient, ClockifyApiClientContract>()(
   "@knpkv/clockify-api-client/ClockifyApiClient"
 ) {
   static readonly layer: Layer.Layer<ClockifyApiClient, never, ClockifyApiConfig | HttpClient.HttpClient> = Layer
@@ -129,8 +144,36 @@ export class ClockifyApiClient extends Context.Service<ClockifyApiClient, Clocki
         const getTags = (workspaceId: string) =>
           api.getTags(workspaceId, { params: { archived: false, "page-size": 200 } })
 
+        const getWorkspaceUsersPage = Effect.fn("ClockifyApiClient.getWorkspaceUsersPage")(function*(
+          workspaceId: string,
+          page: number,
+          pageSize: number
+        ) {
+          return yield* api.getUsersOfWorkspace(workspaceId, {
+            params: {
+              "account-statuses": "ACTIVE,PENDING_EMAIL_VERIFICATION,DELETED,NOT_REGISTERED,LIMITED,LIMITED_DELETED",
+              "include-roles": "false",
+              memberships: "ALL",
+              page,
+              "page-size": pageSize,
+              status: "ALL"
+            }
+          })
+        })
+        const getWorkspaceUsers = Effect.fn("ClockifyApiClient.getWorkspaceUsers")(function*(workspaceId: string) {
+          const users: Array<WorkspaceUser> = []
+          for (let page = 1;; page++) {
+            const batch = yield* getWorkspaceUsersPage(workspaceId, page, 500)
+            for (const user of batch) users.push(user)
+            if (batch.length < 500) break
+          }
+          return users
+        })
+
         return ClockifyApiClient.of({
           getUser: () => api.getLoggedUser(undefined),
+          getWorkspaceUsers,
+          getWorkspaceUsersPage,
           getWorkspaces: () => api.getWorkspacesOfUser(undefined),
           getProjects,
           getProjectByName: (workspaceId, name) =>
@@ -144,10 +187,11 @@ export class ClockifyApiClient extends Context.Service<ClockifyApiClient, Clocki
           getTimeEntries: (workspaceId, userId, params) =>
             api.getTimeEntries(workspaceId, userId, {
               params: {
-                ...(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 } : {})
+                ...((params?.start !== undefined) && { start: params.start }),
+                ...((params?.end !== undefined) && { end: params.end }),
+                ...(!(params?.hydrated === undefined) && { hydrated: params.hydrated }),
+                ...((params?.page !== undefined) && { page: params.page }),
+                ...((params?.pageSize !== undefined) && { "page-size": params.pageSize })
               }
             }),
           getRunningTimer: (workspaceId, userId) =>
@@ -165,7 +209,12 @@ export class ClockifyApiClient extends Context.Service<ClockifyApiClient, Clocki
                   : Effect.succeed(existing)
               })
             ),
-          getTimeEntry: (workspaceId, timeEntryId) => api.getTimeEntry(workspaceId, timeEntryId, undefined),
+          getTimeEntry: (workspaceId, timeEntryId, params) =>
+            api.getTimeEntry(workspaceId, timeEntryId, {
+              params: {
+                ...(!(params?.hydrated === undefined) && { hydrated: params.hydrated })
+              }
+            }),
           deleteTimeEntry: (workspaceId, timeEntryId) => api.deleteTimeEntry(workspaceId, timeEntryId, undefined),
           updateTimeEntry: (workspaceId, timeEntryId, payload) =>
             api.updateTimeEntry(workspaceId, timeEntryId, { payload })

package/src/ClockifyApiConfig.ts

@@ -13,13 +13,13 @@
 import * as Context from "effect/Context"
 import type * as Redacted from "effect/Redacted"
 
-export interface ClockifyApiConfigShape {
+export interface ClockifyApiConfigContract {
   readonly apiKey: Redacted.Redacted<string>
   readonly workspaceId: string
   readonly userId: string
   readonly baseUrl: string
 }
 
-export class ClockifyApiConfig extends Context.Service<ClockifyApiConfig, ClockifyApiConfigShape>()(
+export class ClockifyApiConfig extends Context.Service<ClockifyApiConfig, ClockifyApiConfigContract>()(
   "@knpkv/clockify-api-client/ClockifyApiConfig"
 ) {}

package/src/index.ts

@@ -6,7 +6,7 @@
 
 export {
   ClockifyApiClient,
-  type ClockifyApiClientShape,
+  type ClockifyApiClientContract,
   type ClockifyClientError,
   layer,
   make
@@ -16,6 +16,7 @@ export type {
   AuthenticatedClockifyApi,
   CreateTimeEntryParams,
   GetTimeEntriesParams,
+  GetTimeEntryParams,
   Project,
   StopTimeEntryParams,
   Tag,
@@ -23,9 +24,10 @@ export type {
   TimeInterval,
   UpdateTimeEntryParams,
   User,
-  Workspace
+  Workspace,
+  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,6 +1,7 @@
 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 * as HttpClient from "effect/unstable/http/HttpClient"
 import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
@@ -80,6 +81,107 @@ describe("ClockifyApiClient", () => {
     )
   })
 
+  it.effect("requests hydrated time-entry details when required by the caller", () => {
+    const requests: Array<HttpClientRequest.HttpClientRequest> = []
+    return Effect.gen(function*() {
+      const client = yield* ClockifyApiClient
+      const entry = yield* client.getTimeEntry("workspace-1", "entry-1", { hydrated: true })
+      yield* client.getTimeEntry("workspace-1", "entry-1")
+      yield* client.getTimeEntry("workspace-1", "entry-1", { hydrated: false })
+      expect(entry.id).toBe("entry-1")
+      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*() {
+      const client = yield* ClockifyApiClient
+      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*() {
+      const client = yield* ClockifyApiClient
+      if (client.getWorkspaceUsers === undefined) return assert.fail("expected workspace user discovery")
+      const users = yield* client.getWorkspaceUsers("workspace-1")
+      expect(users).toHaveLength(10_001)
+      expect(users.at(-1)?.id).toBe("configured-user")
+      expect(requests).toHaveLength(21)
+      expect(new Map(requests[0]?.urlParams ?? []).get("page")).toBe("1")
+      expect(new Map(requests[20]?.urlParams ?? []).get("page")).toBe("21")
+      expect(new Map(requests[0]?.urlParams ?? []).get("account-statuses")).toBe(
+        "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*() {
@@ -172,8 +274,7 @@ describe("ClockifyApiClient", () => {
       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")
+      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")
     })