sailfork 0.3.4 → 0.3.6

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.4";
609
+ var VERSION = "0.3.6";
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.4";
503
+ var VERSION = "0.3.6";
504
504
  var API_VERSION = "2026-12-01";
505
505
 
506
506
  // src/core/client.ts
package/dist/tools.cjs CHANGED
@@ -2341,7 +2341,7 @@ var specs = [
2341
2341
  description: "Open a pull request from a caisson's branch. Answers 409 when one is already open.",
2342
2342
  properties: {
2343
2343
  body: {
2344
- description: "The description, one paragraph per item.",
2344
+ description: "The description, one line per item.",
2345
2345
  items: {
2346
2346
  type: "string"
2347
2347
  },
@@ -3381,7 +3381,7 @@ repository's review requirement is not met.`,
3381
3381
  properties: {
3382
3382
  body: {
3383
3383
  default: [],
3384
- description: "The pull request description, one paragraph per item.",
3384
+ description: "The pull request description, one line per item.",
3385
3385
  items: {
3386
3386
  type: "string"
3387
3387
  },
@@ -7031,7 +7031,7 @@ answers 409.`,
7031
7031
  },
7032
7032
  body: {
7033
7033
  default: [],
7034
- description: "The description, one paragraph per item.",
7034
+ description: "The description, one line per item.",
7035
7035
  items: {
7036
7036
  type: "string"
7037
7037
  },
@@ -7724,7 +7724,7 @@ or lock. Only the fields sent change.`,
7724
7724
  },
7725
7725
  body: {
7726
7726
  default: null,
7727
- description: "A new description, one paragraph per item.",
7727
+ description: "A new description, one line per item.",
7728
7728
  items: {
7729
7729
  type: "string"
7730
7730
  },
package/dist/tools.js CHANGED
@@ -2294,7 +2294,7 @@ var specs = [
2294
2294
  description: "Open a pull request from a caisson's branch. Answers 409 when one is already open.",
2295
2295
  properties: {
2296
2296
  body: {
2297
- description: "The description, one paragraph per item.",
2297
+ description: "The description, one line per item.",
2298
2298
  items: {
2299
2299
  type: "string"
2300
2300
  },
@@ -3334,7 +3334,7 @@ repository's review requirement is not met.`,
3334
3334
  properties: {
3335
3335
  body: {
3336
3336
  default: [],
3337
- description: "The pull request description, one paragraph per item.",
3337
+ description: "The pull request description, one line per item.",
3338
3338
  items: {
3339
3339
  type: "string"
3340
3340
  },
@@ -6984,7 +6984,7 @@ answers 409.`,
6984
6984
  },
6985
6985
  body: {
6986
6986
  default: [],
6987
- description: "The description, one paragraph per item.",
6987
+ description: "The description, one line per item.",
6988
6988
  items: {
6989
6989
  type: "string"
6990
6990
  },
@@ -7677,7 +7677,7 @@ or lock. Only the fields sent change.`,
7677
7677
  },
7678
7678
  body: {
7679
7679
  default: null,
7680
- description: "A new description, one paragraph per item.",
7680
+ description: "A new description, one line per item.",
7681
7681
  items: {
7682
7682
  type: "string"
7683
7683
  },
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "0.3.4";
1
+ export declare const VERSION = "0.3.6";
2
2
  export declare const API_VERSION = "2026-12-01";
@@ -2558,7 +2558,7 @@ export type CaissonsPolicyOutput = CaissonPolicy;
2558
2558
  * Open a pull request from a caisson's branch. Answers 409 when one is already open.
2559
2559
  */
2560
2560
  export type CaissonsPullInput = {
2561
- /** The description, one paragraph per item. */
2561
+ /** The description, one line per item. */
2562
2562
  body?: string[] | null;
2563
2563
  /** The caisson's id. */
2564
2564
  id: string;
@@ -2648,7 +2648,7 @@ export type CaissonsReviewSubmitOutput = CaissonReview;
2648
2648
  * Commit a caisson's pending changes and open its pull request in one call. Safe to repeat after a half-done attempt: nothing pending skips the commit, and an open pull request is reused. Refused with 409 while the repository's review requirement is not met.
2649
2649
  */
2650
2650
  export type CaissonsShipInput = {
2651
- /** The pull request description, one paragraph per item. */
2651
+ /** The pull request description, one line per item. */
2652
2652
  body?: string[];
2653
2653
  /** Issues the pull request closes, linked in `Closes` lines. */
2654
2654
  closes?: number[];
@@ -4029,7 +4029,7 @@ export type PullsConflictsOutput = PullConflicts;
4029
4029
  export type PullsCreateInput = {
4030
4030
  /** The branch they should land on, or another pull request's branch to stack on it. */
4031
4031
  base: string;
4032
- /** The description, one paragraph per item. */
4032
+ /** The description, one line per item. */
4033
4033
  body?: string[];
4034
4034
  /** The branch with the changes. */
4035
4035
  branch: string;
@@ -4243,7 +4243,7 @@ export type PullsStackOutput = StackEntry[];
4243
4243
  export type PullsUpdateInput = {
4244
4244
  /** Retarget an open pull request onto this branch; onto another open pull request's branch it stacks on that one. */
4245
4245
  base?: string | null;
4246
- /** A new description, one paragraph per item. */
4246
+ /** A new description, one line per item. */
4247
4247
  body?: string[] | null;
4248
4248
  /** true locks the conversation to people with write access, false unlocks it. */
4249
4249
  locked?: boolean | null;
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "0.3.4";
1
+ export declare const VERSION = "0.3.6";
2
2
  export declare const API_VERSION = "2026-12-01";
@@ -2558,7 +2558,7 @@ export type CaissonsPolicyOutput = CaissonPolicy;
2558
2558
  * Open a pull request from a caisson's branch. Answers 409 when one is already open.
2559
2559
  */
2560
2560
  export type CaissonsPullInput = {
2561
- /** The description, one paragraph per item. */
2561
+ /** The description, one line per item. */
2562
2562
  body?: string[] | null;
2563
2563
  /** The caisson's id. */
2564
2564
  id: string;
@@ -2648,7 +2648,7 @@ export type CaissonsReviewSubmitOutput = CaissonReview;
2648
2648
  * Commit a caisson's pending changes and open its pull request in one call. Safe to repeat after a half-done attempt: nothing pending skips the commit, and an open pull request is reused. Refused with 409 while the repository's review requirement is not met.
2649
2649
  */
2650
2650
  export type CaissonsShipInput = {
2651
- /** The pull request description, one paragraph per item. */
2651
+ /** The pull request description, one line per item. */
2652
2652
  body?: string[];
2653
2653
  /** Issues the pull request closes, linked in `Closes` lines. */
2654
2654
  closes?: number[];
@@ -4029,7 +4029,7 @@ export type PullsConflictsOutput = PullConflicts;
4029
4029
  export type PullsCreateInput = {
4030
4030
  /** The branch they should land on, or another pull request's branch to stack on it. */
4031
4031
  base: string;
4032
- /** The description, one paragraph per item. */
4032
+ /** The description, one line per item. */
4033
4033
  body?: string[];
4034
4034
  /** The branch with the changes. */
4035
4035
  branch: string;
@@ -4243,7 +4243,7 @@ export type PullsStackOutput = StackEntry[];
4243
4243
  export type PullsUpdateInput = {
4244
4244
  /** Retarget an open pull request onto this branch; onto another open pull request's branch it stacks on that one. */
4245
4245
  base?: string | null;
4246
- /** A new description, one paragraph per item. */
4246
+ /** A new description, one line per item. */
4247
4247
  body?: string[] | null;
4248
4248
  /** true locks the conversation to people with write access, false unlocks it. */
4249
4249
  locked?: boolean | null;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "sailfork",
3
- "version": "0.3.4",
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.6",
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",