Client API reference

The complete normalized client surface. Provider adapters implement transport and mapping; WorkClient adds validation, plans, revisions, warning acknowledgement, and idempotency.

`createWorkClient`

function createWorkClient(options: {
  adapter: WorkAdapter;
  idempotencyStore?: IdempotencyStore;
  now?: () => Date;
}): WorkClient;

adapter is required. The default idempotency store is process-local memory. now exists for deterministic testing and should normally be omitted.

Read methods

`get(id, options?)`

get(id: string, options?: { signal?: AbortSignal }): Promise<WorkItem>

Returns one normalized item or throws WorkNotFoundError. IDs are adapter-native: a GitHub issue number, Linear ID or identifier, Jira key, or Azure work-item ID.

`list(input?, options?)`

list(input?: {
  project?: string; assignee?: string;
  state?: WorkItemState | WorkItemState[];
  labels?: string[]; query?: string;
  limit?: number; cursor?: string;
}, options?: { signal?: AbortSignal }): Promise<WorkPage<WorkItem>>

Returns an opaque provider cursor. Never construct or parse cursors; pass nextCursor back unchanged.

Prepare methods

prepareCreate(input)Plan a new item without writing it.prepareUpdate(id, input, options?)Read current state and calculate a changed-field diff.prepareComment(id, input, options?)Read the target and plan a comment.

Create plans do not have an expected revision. Update and comment plans capture the current item and opaque revision.

`commit(change, options?)`

commit(change: PreparedWorkChange, options?: {
  idempotencyKey?: string;
  acceptWarnings?: boolean;
  signal?: AbortSignal;
}): Promise<CommitResult>

Commit validates provider identity, fingerprint integrity, warning acknowledgement, idempotency state, and revision before calling the adapter.

A successful provider write followed by a failed durable-store write can still be ambiguous. Use transactional infrastructure or provider-specific reconciliation when exactly-once effects are a hard requirement.

Core types

Type	Purpose
`WorkItem`	Normalized item plus provider state name, opaque revision, URL, and optional raw payload.
`WorkComment`	Normalized body, author, timestamps, and raw payload.
`PreparedWorkChange`	Serializable, fingerprinted plan for one create, update, or comment.
`CommitResult`	Receipt containing the resulting item, optional comment, replay flag, and commit time.
`WorkPage<T>`	Items plus an optional opaque next cursor.
`WorkWarning`	Structured provider limitation or lossy/ambiguous mapping notice.

Capabilities

work.capabilities is an immutable snapshot. Inspect it when building tools or UIs so unsupported actions are absent rather than offered and rejected later.

if (work.capabilities.parentLinks) {
  tools.push(updateParentTool(work));
}

if (!work.capabilities.multipleAssignees) {
  schema.assigneeIds = z.array(z.string()).max(1);
}

`IdempotencyStore`

interface IdempotencyStore {
  get(key: string): Promise<CommitResult | undefined> | CommitResult | undefined;
  set(key: string, result: CommitResult): Promise<void> | void;
}

The client prefixes keys with the provider. Your implementation should make values durable, serialize complete receipts, and coordinate concurrent writers.

NextErrors →Handle authentication, rate limits, conflicts, validation, and provider failures.