# SDKs for TypeScript and Python

Call Sailfork from code with the official TypeScript and Python SDKs, hand the same operations to a model as tools, and handle writes a person must approve.

The SDKs are generated from the same operation catalog as the REST API, the CLI and the MCP server, so a method, a command and a tool with the same name do the same thing. This page is the short tour; each language has its own section with client options, handles, an agent workflow, errors, tools and testing: [TypeScript SDK](https://sailfork.com/docs/sdk-typescript) and [Python SDK](https://sailfork.com/docs/sdk-python). Every method is listed in the [SDK reference](https://sailfork.com/docs/sdk-reference).

| | TypeScript | Python |
| --- | --- | --- |
| Package | `sailfork` on npm | `sailfork` on PyPI |
| Runs on | Node 20+, Bun, Deno, Workers; ESM and CJS | Python 3.11+, sync and async |
| Depends on | nothing; uses the global `fetch` | `httpx`, `pydantic` v2 |

## Install

```sh
bun add sailfork      # or npm install sailfork
uv add sailfork       # or pip install sailfork
```

## Sign in

The client takes a token in this order: the one you pass, then `SAILFORK_TOKEN`, then the token the CLI stored at `sailfork auth login`. Create a token with the scopes your code needs on [Access tokens](https://sailfork.com/docs/tokens). The host defaults to `https://sailfork.com`; set `SAILFORK_HOST` or pass `host` for another one. A token from the environment is only ever sent to that host.

```ts
import Sailfork from 'sailfork';

const sf = new Sailfork(); // or new Sailfork({ token, host })
const { pending } = await sf.held.mine(); // writes waiting for a person
```

```python
from sailfork import Sailfork

sf = Sailfork()  # or Sailfork(token=..., host=...)
pending = sf.held.mine().pending  # writes waiting for a person
```

## Call an operation

Every operation is a method named after its catalog id: `issues.create` is `sf.issues.create(...)`. TypeScript takes one input object and camel-cases the verb (`issues.createBatch`); Python takes keyword arguments and keeps the snake case (`issues.create_batch`).

A handle binds the ids a call would repeat. `sf.repo('owner/name')` fills in `owner` and `repo`, `repo.pull(number)` fills in the pull request, `sf.org('handle')` fills in the organization. Some methods answer with the next handle: `pulls.create` returns a pull request, `issues.start` a caisson, and `caissons.ship` the pull request it opened.

```ts
const repo = sf.repo('acme/api');
const issues = await repo.issues.list({ state: 'open' });

const caisson = await repo.issues.start({ number: 42 });
await caisson.batch({ changes: [{ path: 'src/charge.ts', content: fixed }] });
const pr = await caisson.ship({ message: 'Charges round to the cent', closes: [42] });
```

```python
repo = sf.repo("acme/api")
issues = repo.issues.list(state="open")

caisson = repo.issues.start(number=42)
caisson.batch(changes=[{"path": "src/charge.py", "content": fixed}])
pr = caisson.ship(message="Charges round to the cent", closes=[42])
```

`AsyncSailfork` has the same methods as `Sailfork`, each awaitable.

## Writes a person must approve

When an organization's [agent permissions](https://sailfork.com/docs/agent-permissions) hold a write for a person, a merge say, the call does not throw. It returns the request instead, with the address where a person approves it. Only the methods marked "can be held" in the reference do this; their result is one of two shapes.

```ts
const merge = await pr.merge();
if (merge.status === 'held') {
	console.log(`waiting for a person: ${merge.url}`);
} else {
	console.log(merge.value.state); // merged
}
```

```python
merge = pr.merge()
if merge.status == "held":
    print(f"waiting for a person: {merge.url}")
else:
    print(merge.value.state)  # merged
```

Hand `url` to the person, then wait for the request to be decided and call again.

## Wait for something to happen

`sf.wait` holds until a pull request's checks finish, it merges or gets a review, a CI run ends, a caisson or issue reaches a state, or a held request is decided. It answers `met`, `failed`, `pending` when the time ran out, or `none` when there is nothing to wait for, such as a repository with no CI.

```ts
const checks = await sf.wait({ kind: 'pull', owner: 'acme', repo: 'api', number: 128 }, { until: 'checks', within: 600 });
```

```python
checks = sf.wait({"kind": "pull", "owner": "acme", "repo": "api", "number": 128}, until="checks", timeout=600)
```

## Give the operations to a model

`tools` exports every operation as Anthropic and OpenAI tool definitions, and `run` calls the one a model picked with a client built from the environment. Tool names are the same as the [MCP server](https://sailfork.com/docs/mcp)'s, as in `pull_merge`.

```ts
import { anthropicTools, openaiTools, run } from 'sailfork/tools';

const result = await run(toolUse.name, toolUse.input);
```

```python
from sailfork.tools import ANTHROPIC_TOOLS, OPENAI_TOOLS, run

result = run(tool_use.name, tool_use.input)
```

## Errors and retries

- An error is typed by its code family: `NotFoundError`, `PermissionError` (`PermissionDeniedError` in Python), `RateLimitError`, `AgentPolicyError` and the rest. Printing one gives the code, message, hint, request id and a link to the docs on one line. The codes are listed in [Errors](https://sailfork.com/docs/api#errors).
- Reads and idempotent writes retry twice on network errors, 408, 429 and 5xx, honoring `Retry-After` up to 60 seconds. Pass `maxRetries` to the client or to one call in TypeScript, or `max_retries` to the client or, in `RequestOptions` as `options=`, to one call in Python.
- Every write sends one `Idempotency-Key`, reused across its retries, so a retried write runs once.
- Every request pins `Sailfork-Version: 2026-12-01`, so a later API change does not break code written against this one, and names the coding agent the environment shows, which is how [agent permissions](https://sailfork.com/docs/agent-permissions) tell an agent from a person.

---

Every docs page: https://sailfork.com/llms.txt
