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 CHANGED
@@ -1,48 +1,230 @@
1
- # sailfork
1
+ # Sailfork TypeScript SDK
2
2
 
3
- The TypeScript SDK for [Sailfork](https://sailfork.com), git hosting built for AI coding agents: repositories, pull
4
- requests, code review, issues, CI and sandboxes from one typed client. Full reference at
5
- [sailfork.com/docs/sdk](https://sailfork.com/docs/sdk).
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; uses the global `fetch`. ESM and CJS, Node 20+, Bun, Deno and Workers.
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 # or npm install 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, SAILFORK_HOST, or the token `sailfork auth login` stored
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
- Auth: pass `{ token }`, else the client reads `SAILFORK_TOKEN`, else runs `sailfork auth token` when the CLI is installed.
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
- A write that needs a person's approval (a merge a branch rule holds, say) resolves to `{ status: 'held', held, url, message }`;
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
- Every operation in the catalog is a method: `sf.<area>.<verb>(input)`, or on a handle the call is bound to (`sf.repo(...)`,
31
- `sf.org(...)`, `repo.pull(n)`). A method marked `returns` in the catalog answers with the next handle, as `pulls.create`
32
- does. The handles and methods are generated by `crates/sdk-gen`; `scripts/ops-drift.sh --write` refreshes them.
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
- Tool definitions for a model's tool-use loop, and a dispatcher bound to a client built from the environment:
180
+ ## Configuration
35
181
 
36
182
  ```ts
37
- import { anthropicTools, openaiTools, run } from 'sailfork/tools';
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
- const result = await run(toolCall.name, toolCall.input);
190
+ await sf.repo('acme/api').pull(42).get({}, { timeout: 10_000, signal: AbortSignal.timeout(15_000) });
40
191
  ```
41
192
 
42
- - The environment token is sent only to `SAILFORK_HOST` (default `https://sailfork.com`).
43
- - Every request pins `Sailfork-Version: 2026-12-01` and names the coding agent the environment shows.
44
- - Reads and idempotent writes retry twice on network errors, 408, 429 and 5xx, honoring `Retry-After` up to 60 s. Every
45
- write carries one `Idempotency-Key`, reused across its retries.
46
- - Errors are typed by code family (`NotFoundError`, `AgentPolicyError`, ...); `String(err)` prints the code, message, hint,
47
- request id and doc URL on one line.
48
- - A write a person must approve returns `{ status: 'held', held, url, message }` instead of throwing.
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
@@ -606,7 +606,7 @@ async function resolveToken(host, option) {
606
606
  }
607
607
 
608
608
  // src/core/version.ts
609
- var VERSION = "0.3.3";
609
+ var VERSION = "0.3.5";
610
610
  var API_VERSION = "2026-12-01";
611
611
 
612
612
  // src/core/client.ts
package/dist/index.js CHANGED
@@ -500,7 +500,7 @@ async function resolveToken(host, option) {
500
500
  }
501
501
 
502
502
  // src/core/version.ts
503
- var VERSION = "0.3.3";
503
+ var VERSION = "0.3.5";
504
504
  var API_VERSION = "2026-12-01";
505
505
 
506
506
  // src/core/client.ts
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "0.3.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.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.3",
4
- "description": "TypeScript SDK and API client for Sailfork, git hosting built for AI coding agents: repositories, pull requests, code review, issues, CI and sandboxes.",
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",