# Work SDK

> Agent-safe TypeScript SDK for GitHub Issues, GitLab, Linear, Jira, and Azure DevOps.

## Primary documentation

- [Documentation](https://work-sdk.vercel.app/docs): guided documentation index
- [Getting started](https://work-sdk.vercel.app/docs/getting-started): first read and safe write
- [Example apps](https://work-sdk.vercel.app/docs/examples): runnable approval CLI and signed webhook bot with fake credentials
- [Safe writes](https://work-sdk.vercel.app/docs/concepts/safe-writes): integrity, concurrency, warnings, and idempotency
- [Providers](https://work-sdk.vercel.app/docs/providers): capability and semantic comparison
- [GitHub](https://work-sdk.vercel.app/docs/providers/github): permissions, identifiers, mappings, and safe writes
- [GitLab](https://work-sdk.vercel.app/docs/providers/gitlab): GitLab.com, Self-Managed, auth, guarded labels, types, and concurrency
- [Linear](https://work-sdk.vercel.app/docs/providers/linear): teams, workflow states, priorities, and safe writes
- [Jira Cloud](https://work-sdk.vercel.app/docs/providers/jira): authentication, transitions, ADF, and workflow limits
- [Azure DevOps](https://work-sdk.vercel.app/docs/providers/azure-devops): auth, custom processes, WIQL, and JSON Patch
- [Client reference](https://work-sdk.vercel.app/docs/reference/client): methods and normalized types
- [Errors](https://work-sdk.vercel.app/docs/reference/errors): error classes and retry policy
- [Agent guide](https://work-sdk.vercel.app/docs/guides/agents): safe tool and approval boundaries
- [Testing guide](https://work-sdk.vercel.app/docs/guides/testing): memory adapter and protocol tests
- [Markdown homepage](https://work-sdk.vercel.app/index.md): concise project overview and quick example
- [Agent guide](https://work-sdk.vercel.app/agents.md): operational rules for coding agents
- [Full machine context](https://work-sdk.vercel.app/llms-full.txt): combined project and agent documentation

## Project

- [Source](https://github.com/arturict/work-sdk)
- [npm package](https://www.npmjs.com/package/work-sdk)

Work SDK is a local library, not a hosted service. Applications bring their own provider credentials.

---

# Work SDK

> The agent-safe TypeScript SDK for GitHub Issues, GitLab, Linear, Jira, and Azure DevOps.

Work SDK is an open-source TypeScript library for GitHub Issues, GitLab, Linear, Jira, and Azure DevOps. It provides one normalized API for reading and writing work items, with inspectable prepared changes, atomic idempotency coordination, explicit concurrency guarantees, capability discovery, and normalized errors.

## Install

```bash
npm install work-sdk
```

## Quick example

```ts
import { createWorkClient } from "work-sdk";
import { github } from "work-sdk/github";

const work = createWorkClient({
  adapter: github({
    owner: "acme",
    repo: "api",
    token: process.env.GITHUB_TOKEN!,
  }),
});

const change = await work.prepareUpdate("481", { state: "closed" });
console.log(change.changes, change.warnings);

await work.commit(change, {
  idempotencyKey: "merge:acme/api#481",
});
```

## Why prepared changes?

Direct provider calls combine intent, provider mapping, and an irreversible side effect. Work SDK separates them:

1. **Prepare** validates input, reads current state, and produces a fingerprinted change plan.
2. **Inspect** lets a human or policy check exact field changes and provider warnings.
3. **Commit** verifies the fingerprint and expected revision before writing.

## Supported providers

- GitHub Issues via `work-sdk/github`
- GitLab via `work-sdk/gitlab`
- Linear via `work-sdk/linear`
- Jira Cloud via `work-sdk/jira`
- Azure DevOps via `work-sdk/azure-devops`

## Links

- Website: https://work-sdk.vercel.app
- Documentation: https://work-sdk.vercel.app/docs
- Getting started: https://work-sdk.vercel.app/docs/getting-started
- Provider comparison: https://work-sdk.vercel.app/docs/providers
- Example apps: https://work-sdk.vercel.app/docs/examples
- Source: https://github.com/arturict/work-sdk
- npm: https://www.npmjs.com/package/work-sdk
- Machine index: https://work-sdk.vercel.app/llms.txt
- Agent guide: https://work-sdk.vercel.app/agents.md

---

# Work SDK — Agent Guide

Work SDK is an open-source TypeScript library for safely reading and writing GitHub Issues, GitLab issues, Linear issues, Jira work items, and Azure DevOps work items. It is not a hosted API. The application supplies provider credentials, and requests go directly to the selected tracker.

## Use Work SDK when

- A coding agent must create, update, comment on, or transition work items.
- Application code needs to support multiple trackers without provider conditionals at every call site.
- A side effect should be inspectable before it is committed.
- Duplicate-risk must be coordinated across workers and uncertain outcomes must stop blind retries.
- A write must fail if an item changed after it was inspected.

## Safe write rules

1. Call `prepareCreate`, `prepareUpdate`, or `prepareComment`.
2. Inspect every entry in `change.changes` and `change.warnings`.
3. Require human approval when the application policy calls for it. The SDK does not replace approval.
4. Never mutate a prepared change. Its fingerprint protects the reviewed plan.
5. Commit externally visible writes with a stable `idempotencyKey`.
6. On `WorkConflictError`, re-read and prepare a new change. Do not force the stale write.
7. Check `work.capabilities` before exposing provider-dependent actions.
8. On `WorkAmbiguousCommitError`, reconcile provider state before any retry.

## Credentials

Keep GitHub and GitLab tokens, Linear API keys, Jira API tokens, Azure DevOps Entra/PAT tokens, and all other credentials in environment variables. Never include them in prompts, prepared-change logs, error reports, or source control.

## Provider imports

- `work-sdk/github`
- `work-sdk/gitlab`
- `work-sdk/linear`
- `work-sdk/jira`
- `work-sdk/azure-devops`

## Error classes

- `WorkAuthenticationError`
- `WorkAuthorizationError`
- `WorkNotFoundError`
- `WorkRateLimitError`
- `WorkConflictError`
- `WorkInFlightError`
- `WorkAmbiguousCommitError`
- `WorkUnsupportedError`
- `WorkValidationError`

Read the complete documentation at https://work-sdk.vercel.app/docs.