sailfork 0.3.3 → 0.3.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +206 -24
- package/dist/index.cjs +1 -1
- package/dist/index.js +1 -1
- package/dist/types/core/version.d.ts +1 -1
- package/dist/types-cjs/core/version.d.ts +1 -1
- package/package.json +22 -3
package/README.md
CHANGED
|
@@ -1,48 +1,230 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Sailfork TypeScript SDK
|
|
2
2
|
|
|
3
|
-
The TypeScript SDK for [Sailfork](https://sailfork.com), git hosting built for AI coding agents
|
|
4
|
-
requests, code review, issues, CI
|
|
5
|
-
|
|
3
|
+
The official TypeScript and JavaScript SDK for [Sailfork](https://sailfork.com), git hosting built for AI coding agents.
|
|
4
|
+
One typed client covers repositories, pull requests, code review, issues, CI runs, caissons (server-side worktrees) and
|
|
5
|
+
sandboxes: 148 methods generated from the same operation catalog as the Sailfork API, CLI and MCP server.
|
|
6
6
|
|
|
7
|
-
Zero runtime dependencies
|
|
7
|
+
- Zero runtime dependencies. Uses the global `fetch`.
|
|
8
|
+
- ESM and CommonJS, with types. Runs on Node 20+, Bun, Deno, Cloudflare Workers and other edge runtimes.
|
|
9
|
+
- Ready-made tool definitions for Anthropic and OpenAI tool use, plus a dispatcher that runs the tool a model called.
|
|
10
|
+
- Writes a person must approve come back as a `held` result with an approval link, not an exception.
|
|
11
|
+
- Retries, idempotency keys and typed errors built in.
|
|
12
|
+
|
|
13
|
+
[Docs](https://sailfork.com/docs/sdk) · [Method reference](https://sailfork.com/docs/sdk-reference) ·
|
|
14
|
+
[OpenAPI spec](https://sailfork.com/sailfork/sdk/blob/main/openapi.json) · [Python SDK](https://pypi.org/project/sailfork/) ·
|
|
15
|
+
[Issues](https://sailfork.com/sailfork/sdk/issues)
|
|
16
|
+
|
|
17
|
+
## Install
|
|
8
18
|
|
|
9
19
|
```sh
|
|
10
|
-
bun add sailfork
|
|
20
|
+
bun add sailfork
|
|
21
|
+
# or
|
|
22
|
+
npm install sailfork
|
|
23
|
+
pnpm add sailfork
|
|
24
|
+
deno add npm:sailfork
|
|
11
25
|
```
|
|
12
26
|
|
|
27
|
+
## Quickstart
|
|
28
|
+
|
|
13
29
|
```ts
|
|
14
30
|
import Sailfork from 'sailfork';
|
|
15
31
|
|
|
16
|
-
const sf = new Sailfork(); // SAILFORK_TOKEN,
|
|
17
|
-
const { pending } = await sf.held.mine();
|
|
32
|
+
const sf = new Sailfork(); // reads SAILFORK_TOKEN, else the token `sailfork auth login` stored
|
|
18
33
|
|
|
19
34
|
const repo = sf.repo('acme/api');
|
|
20
35
|
const pr = await repo.pulls.create({ title: 'Charges round to the cent', branch: 'fix/charges', base: 'main' });
|
|
36
|
+
|
|
21
37
|
const merge = await pr.merge();
|
|
22
38
|
if (merge.status === 'held') console.log(`waiting for a person: ${merge.url}`);
|
|
23
39
|
```
|
|
24
40
|
|
|
25
|
-
|
|
41
|
+
`sf.repo('owner/name')`, `repo.pull(n)`, `repo.caisson(id)` and `sf.org(handle)` are handles: they bind the ids every
|
|
42
|
+
call on them repeats, so you pass only what is new. Methods that create something, such as `pulls.create` and
|
|
43
|
+
`caisson.ship`, answer with the handle for it.
|
|
44
|
+
|
|
45
|
+
## Authentication
|
|
46
|
+
|
|
47
|
+
The client looks for a token in this order:
|
|
48
|
+
|
|
49
|
+
1. `new Sailfork({ token: 'sf_...' })`
|
|
50
|
+
2. the `SAILFORK_TOKEN` environment variable
|
|
51
|
+
3. `sailfork auth token`, when the [Sailfork CLI](https://sailfork.com/cli) is installed and signed in
|
|
52
|
+
|
|
53
|
+
The host defaults to `https://sailfork.com`; set `SAILFORK_HOST` or pass `{ host }` for a self-hosted server. The
|
|
54
|
+
environment token is sent only to that host.
|
|
55
|
+
|
|
56
|
+
## Common tasks
|
|
57
|
+
|
|
58
|
+
### Open an issue
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
const issue = await sf.repo('acme/api').issues.create({
|
|
62
|
+
title: 'Refunds fail for partial captures',
|
|
63
|
+
body: 'Steps to reproduce...',
|
|
64
|
+
labels: ['bug'],
|
|
65
|
+
priority: 'high',
|
|
66
|
+
});
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Review and merge a pull request
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
const pr = sf.repo('acme/api').pull(42);
|
|
73
|
+
|
|
74
|
+
const { title, mergeable, checks } = await pr.get();
|
|
75
|
+
await pr.review({ verdict: 'approve', body: 'Looks right.' });
|
|
76
|
+
const merge = await pr.merge({ method: 'squash' });
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Find out why CI failed
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
const failures = await sf.repo('acme/api').ci.failures({ id: 1873 });
|
|
83
|
+
// each failed step's last log lines, the errors found in them and the failed test cases
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### Edit code without a checkout (caissons)
|
|
87
|
+
|
|
88
|
+
A caisson is a server-side worktree on a branch. An agent reads, edits, tests and ships it through the API, with no
|
|
89
|
+
clone on the machine it runs on.
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
const opened = await sf.caissons.open({ org: 'acme', repo: 'api', title: 'Round charges', scope: ['src/billing/'] });
|
|
93
|
+
const caisson = sf.repo('acme/api').caisson(opened.id);
|
|
94
|
+
|
|
95
|
+
await caisson.batch({ changes: [{ path: 'src/billing/round.ts', content: 'export const round = ...' }] });
|
|
96
|
+
const test = await caisson.test({ command: 'bun test src/billing', image: 'oven/bun:1' });
|
|
97
|
+
const pr = await caisson.ship({ message: 'fix(billing): round charges to the cent', closes: [118] });
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Wait for checks, a merge or an approval
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
const answer = await sf.wait({ kind: 'pull', owner: 'acme', repo: 'api', number: 42 }, { until: 'checks', within: 900 });
|
|
104
|
+
// answer.state is 'met', 'failed', 'pending' (time ran out) or 'none'
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`sf.wait` holds one request open on the server instead of polling. It also waits on CI runs, caissons, issues and held
|
|
108
|
+
actions.
|
|
109
|
+
|
|
110
|
+
## Use Sailfork as tools in an AI agent
|
|
111
|
+
|
|
112
|
+
`sailfork/tools` exports 99 tool definitions in both Anthropic and OpenAI formats, with the same names as the Sailfork
|
|
113
|
+
MCP server, and `run`, which executes the tool a model called.
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
import Anthropic from '@anthropic-ai/sdk';
|
|
117
|
+
import { anthropicTools, run } from 'sailfork/tools';
|
|
118
|
+
|
|
119
|
+
const anthropic = new Anthropic();
|
|
120
|
+
const message = await anthropic.messages.create({
|
|
121
|
+
model: 'claude-sonnet-5-5',
|
|
122
|
+
max_tokens: 4096,
|
|
123
|
+
tools: anthropicTools,
|
|
124
|
+
messages: [{ role: 'user', content: 'Why did the last CI run on acme/api fail?' }],
|
|
125
|
+
});
|
|
126
|
+
|
|
127
|
+
for (const block of message.content) {
|
|
128
|
+
if (block.type === 'tool_use') {
|
|
129
|
+
const result = await run(block.name, block.input as Record<string, unknown>);
|
|
130
|
+
// send result back as a tool_result block
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
For OpenAI, pass `openaiTools` and call `run(call.function.name, JSON.parse(call.function.arguments))`. `run` builds a
|
|
136
|
+
client from the environment unless you pass one as its third argument.
|
|
137
|
+
|
|
138
|
+
Each request names the coding agent it runs under (Claude Code, Codex, Cursor, Copilot, Cline and others are detected
|
|
139
|
+
from the environment), so repository owners can set rules per agent. Pass `{ agent: false }` to send none.
|
|
140
|
+
|
|
141
|
+
## Held writes: human approval
|
|
142
|
+
|
|
143
|
+
Repository rules can hold a write, such as a merge into a protected branch, until a person approves it. Those methods
|
|
144
|
+
resolve to a result instead of throwing:
|
|
145
|
+
|
|
146
|
+
```ts
|
|
147
|
+
const result = await pr.merge();
|
|
148
|
+
if (result.status === 'held') {
|
|
149
|
+
// result.url is the approval page; result.held is the id to wait on
|
|
150
|
+
await sf.wait({ kind: 'held', owner: 'acme', id: result.held });
|
|
151
|
+
} else {
|
|
152
|
+
console.log(result.value);
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Errors
|
|
157
|
+
|
|
158
|
+
Errors are typed by code family and extend `SailforkError`: `NotFoundError`, `AuthenticationError`, `PermissionError`,
|
|
159
|
+
`AgentPolicyError`, `ConflictError`, `InvalidRequestError`, `RateLimitError`, `ServerError`, `ConnectionError`,
|
|
160
|
+
`TimeoutError` and `UnavailableForLegalReasonsError`. `String(err)` prints the code, message, hint, request id and doc
|
|
161
|
+
URL on one line, which is what a model needs to correct its next call.
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
import { NotFoundError } from 'sailfork';
|
|
165
|
+
|
|
166
|
+
try {
|
|
167
|
+
await sf.repo('acme/api').pull(9999).get();
|
|
168
|
+
} catch (err) {
|
|
169
|
+
if (err instanceof NotFoundError) console.error(String(err));
|
|
170
|
+
else throw err;
|
|
171
|
+
}
|
|
172
|
+
```
|
|
26
173
|
|
|
27
|
-
|
|
28
|
-
anything else resolves to `{ status: 'done', value }`. Hand `url` to the user and call again once they have approved.
|
|
174
|
+
## Retries and idempotency
|
|
29
175
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
176
|
+
- Reads and idempotent writes retry twice on network errors, 408, 429 and 5xx, honoring `Retry-After` up to 60 seconds.
|
|
177
|
+
- Every write carries one `Idempotency-Key`, reused across its retries, so a retried write never applies twice.
|
|
178
|
+
- Every request pins `Sailfork-Version: 2026-12-01`, so server changes do not break a deployed client.
|
|
33
179
|
|
|
34
|
-
|
|
180
|
+
## Configuration
|
|
35
181
|
|
|
36
182
|
```ts
|
|
37
|
-
|
|
183
|
+
const sf = new Sailfork({
|
|
184
|
+
token: process.env.SAILFORK_TOKEN,
|
|
185
|
+
host: 'https://sailfork.example.com',
|
|
186
|
+
maxRetries: 4,
|
|
187
|
+
agent: 'my-agent',
|
|
188
|
+
});
|
|
38
189
|
|
|
39
|
-
|
|
190
|
+
await sf.repo('acme/api').pull(42).get({}, { timeout: 10_000, signal: AbortSignal.timeout(15_000) });
|
|
40
191
|
```
|
|
41
192
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
193
|
+
Per call, the last argument takes `timeout`, `signal`, `maxRetries`, `idempotencyKey` and `headers`.
|
|
194
|
+
|
|
195
|
+
## FAQ
|
|
196
|
+
|
|
197
|
+
### What is Sailfork?
|
|
198
|
+
|
|
199
|
+
Sailfork is a git hosting platform built for AI coding agents: repositories, pull requests, code review, issues, CI and
|
|
200
|
+
sandboxes, with rules that decide what an agent may do on its own and what waits for a person.
|
|
201
|
+
|
|
202
|
+
### Does the SDK work in the browser, Deno, Bun or Cloudflare Workers?
|
|
203
|
+
|
|
204
|
+
Yes. It has no dependencies and uses the global `fetch`, so it runs on any runtime that has one. Do not ship a personal
|
|
205
|
+
token to a browser; use a token scoped to what the page needs.
|
|
206
|
+
|
|
207
|
+
### How does it compare to the GitHub Octokit SDK?
|
|
208
|
+
|
|
209
|
+
It plays the same role for Sailfork. The difference is agent support built in: tool definitions for LLMs, held results
|
|
210
|
+
for approvals, per-agent policy, server-side waits and caissons for editing code without a clone.
|
|
211
|
+
|
|
212
|
+
### Can I use it with the Model Context Protocol (MCP)?
|
|
213
|
+
|
|
214
|
+
The tool names and schemas match the [Sailfork MCP server](https://sailfork.com/docs/mcp). Use the MCP server when your agent
|
|
215
|
+
host speaks MCP, and this SDK when you write the agent loop yourself.
|
|
216
|
+
|
|
217
|
+
### Is it generated?
|
|
218
|
+
|
|
219
|
+
Yes. Methods, types and tool definitions are generated from Sailfork's operation catalog, the same source as the REST
|
|
220
|
+
API and CLI, so every operation the API has is a method here.
|
|
221
|
+
|
|
222
|
+
## Coding agents
|
|
223
|
+
|
|
224
|
+
The package ships [`AGENTS.md`](https://sailfork.com/sailfork/sdk/blob/main/typescript/AGENTS.md), every method with its
|
|
225
|
+
scope and retry behavior, and [`llms.txt`](https://sailfork.com/sailfork/sdk/blob/main/typescript/llms.txt). Both are in
|
|
226
|
+
`node_modules/sailfork/` after install.
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
MIT
|
package/dist/index.cjs
CHANGED
package/dist/index.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const VERSION = "0.3.
|
|
1
|
+
export declare const VERSION = "0.3.5";
|
|
2
2
|
export declare const API_VERSION = "2026-12-01";
|
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const VERSION = "0.3.
|
|
1
|
+
export declare const VERSION = "0.3.5";
|
|
2
2
|
export declare const API_VERSION = "2026-12-01";
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sailfork",
|
|
3
|
-
"version": "0.3.
|
|
4
|
-
"description": "TypeScript SDK
|
|
3
|
+
"version": "0.3.5",
|
|
4
|
+
"description": "Official TypeScript SDK for Sailfork, git hosting built for AI coding agents: a typed API client for repositories, pull requests, code review, issues, CI and sandboxes, with Anthropic and OpenAI tool definitions.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"sailfork",
|
|
7
7
|
"sdk",
|
|
@@ -21,7 +21,26 @@
|
|
|
21
21
|
"mcp",
|
|
22
22
|
"sandbox",
|
|
23
23
|
"automation",
|
|
24
|
-
"typescript"
|
|
24
|
+
"typescript",
|
|
25
|
+
"javascript",
|
|
26
|
+
"nodejs",
|
|
27
|
+
"bun",
|
|
28
|
+
"deno",
|
|
29
|
+
"cloudflare-workers",
|
|
30
|
+
"rest-api",
|
|
31
|
+
"github-api",
|
|
32
|
+
"ai",
|
|
33
|
+
"agents",
|
|
34
|
+
"agentic",
|
|
35
|
+
"ai-coding-agent",
|
|
36
|
+
"llm-tools",
|
|
37
|
+
"tool-use",
|
|
38
|
+
"function-calling",
|
|
39
|
+
"anthropic",
|
|
40
|
+
"claude",
|
|
41
|
+
"openai",
|
|
42
|
+
"human-in-the-loop",
|
|
43
|
+
"worktree"
|
|
25
44
|
],
|
|
26
45
|
"author": "Sailfork (https://sailfork.com)",
|
|
27
46
|
"license": "MIT",
|