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 and Python SDK. Every method is listed in the 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
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. 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.
import Sailfork from 'sailfork';
const sf = new Sailfork(); // or new Sailfork({ token, host })
const { pending } = await sf.held.mine(); // writes waiting for a person 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.
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] }); 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 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.
const merge = await pr.merge();
if (merge.status === 'held') {
console.log(`waiting for a person: ${merge.url}`);
} else {
console.log(merge.value.state); // merged
} 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.
const checks = await sf.wait({ kind: 'pull', owner: 'acme', repo: 'api', number: 128 }, { until: 'checks', within: 600 }); 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's, as in pull_merge.
import { anthropicTools, openaiTools, run } from 'sailfork/tools';
const result = await run(toolUse.name, toolUse.input); 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(PermissionDeniedErrorin Python),RateLimitError,AgentPolicyErrorand 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. - Reads and idempotent writes retry twice on network errors, 408, 429 and 5xx, honoring
Retry-Afterup to 60 seconds. PassmaxRetriesto the client or to one call in TypeScript, ormax_retriesto the client or, inRequestOptionsasoptions=, 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 tell an agent from a person.