Skip to content

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.

TypeScriptPython
Packagesailfork on npmsailfork on PyPI
Runs onNode 20+, Bun, Deno, Workers; ESM and CJSPython 3.11+, sync and async
Depends onnothing; uses the global fetchhttpx, 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 (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.
  • 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 tell an agent from a person.

Loading Sailfork