# Held writes and waits (TypeScript)

Handle writes that wait for a person with the Result, Done and Held types of the TypeScript SDK, and hold for checks, merges and decisions with sf.wait.

Some writes wait for a person, and some code has to wait for the world. This page covers the `Result` type for the first and `sf.wait` for the second.

## Writes held for a person

A few operations can be held. When an organization's [agent permissions](https://sailfork.com/docs/agent-permissions) hold the write, the call does not throw. It resolves to a `Held` result, and the same call without a hold resolves to a `Done` result. Only `pulls.merge` and `pulls.autoMergeEnable` (on `sf.pulls`, `repo.pulls` and `PullRequest`) are typed this way today; every other method returns its data directly.

```ts
import type { Done, HeldOutcome, Result, types } from 'sailfork';

type MergeResult = Result<types.Pull>;
type Merged = Done<types.Pull>; // { status: 'done'; value: types.Pull }
type Waiting = HeldOutcome; // { status: 'held'; held: string; url: string; message: string }
```

| Field | Present on | Holds |
| --- | --- | --- |
| `status` | both | `'done'` or `'held'`; narrow on it |
| `value` | `done` | The operation's usual answer |
| `held` | `held` | The id of the held request |
| `url` | `held` | An absolute address where a person decides it; the server's path resolved against the client's host, `/requests` when the server named none |
| `message` | `held` | The server's sentence, which starts `HELD FOR A PERSON` |

```ts
import Sailfork from 'sailfork';

const sf = new Sailfork();
const pr = sf.repo('acme/api').pull(128);

const merge = await pr.merge();
if (merge.status === 'held') {
	console.log(merge.message);
	console.log(`decide it at ${merge.url} (request ${merge.held})`);
} else {
	console.log(`merged: ${merge.value.state}`);
}
```

An agent cannot approve its own request. Hand `url` to a person, wait for the decision with `sf.wait({ kind: 'held', ... })`, then call again. A decline makes the repeated call throw an `AgentPolicyError` with code `held_declined`. The list of your own requests is `sf.held.mine()`, which answers `{ pending, decided }`.

```ts
import Sailfork from 'sailfork';

const sf = new Sailfork();
const { pending, decided } = await sf.held.mine();
for (const request of pending) console.log(request.id, request.kind, request.summary);
console.log(decided.length);
```

Writes through a caisson that a path rule holds do not use `Result`. They change the caisson's state to `waiting`; see [Writes held for a person](https://sailfork.com/docs/caissons#writes-held-for-a-person).

## Wait for something to happen

`sf.wait(target, options?)` holds until the thing reaches the state you ask for, or `within` seconds pass, and answers a `WaitAnswer`. It is one call to you and several requests underneath: each is a window of at most 55 seconds, and the client carries the server's `baseline` from one window to the next. It does not poll. See [Wait for a change](https://sailfork.com/docs/api-account#wait-for-a-change) for the route.

| `kind` | Target fields | `until` |
| --- | --- | --- |
| `pull` | `owner`, `repo`, `number` | `checks`, `merged` or `reviewed` |
| `run` | `owner`, `repo`, `id` (a number) | not used; a run is waited on until it finishes |
| `caisson` | `owner`, `id` (a string) | the state to reach: `editing`, `waiting`, `review`, `merged` or `stopped` |
| `issue` | `owner`, `repo`, `number` | `open`, `closed`, or a status such as `in-review` or `done` |
| `held` | `owner` (the organization), `id` | not used; a held request is waited on until it is decided |

| Option | Meaning |
| --- | --- |
| `until` | As above |
| `within` | Seconds to wait in all before answering `pending`. Default 600 |
| `signal`, `timeout`, `maxRetries`, `idempotencyKey`, `headers` | The usual [request options](https://sailfork.com/docs/sdk-typescript-errors#request-options). `timeout` is in milliseconds and applies to each window; it defaults to the window plus 15 seconds |

| `WaitAnswer` field | Holds |
| --- | --- |
| `state` | `met`, `failed`, `pending` (`within` ran out first) or `none` (there is nothing to wait for, such as a repository with no CI) |
| `detail` | The target's state in words, such as `merged` or `approved` |
| `condition` | What was waited for, such as `#128 merged` |
| `value` | What the server last read, typed `unknown`: the pull request, the checks summary, the run, the held request |
| `baseline` | What the next window is compared against. The client passes it back for you |

`failed` means the target can no longer reach the state: a pull request closed without merging, a failed check, a failed run. A `pending` answer is not an error.

```ts
import Sailfork from 'sailfork';

const sf = new Sailfork();
const repo = { owner: 'acme', repo: 'api' };

const checks = await sf.wait({ kind: 'pull', ...repo, number: 128 }, { until: 'checks', within: 900 });
const merged = await sf.wait({ kind: 'pull', ...repo, number: 128 }, { until: 'merged', within: 60 });
const reviewed = await sf.wait({ kind: 'pull', ...repo, number: 128 }, { until: 'reviewed', within: 600 });
const run = await sf.wait({ kind: 'run', ...repo, id: 1804 }, { within: 1200 });
const caisson = await sf.wait({ kind: 'caisson', owner: 'acme', id: 'c-z4nwicj7' }, { until: 'review' });
const issue = await sf.wait({ kind: 'issue', ...repo, number: 42 }, { until: 'closed', within: 300 });
const decision = await sf.wait({ kind: 'held', owner: 'acme', id: '31068dbe-d36e-4c70-a706-47fdb8f535ed' }, { within: 3600 });

for (const answer of [checks, merged, reviewed, run, caisson, issue, decision]) {
	console.log(answer.state, answer.condition, answer.detail);
}
```

Stop a long wait with a signal. The aborted call throws the signal's reason.

```ts
import Sailfork from 'sailfork';

const sf = new Sailfork();
const stop = new AbortController();
setTimeout(() => stop.abort(new Error('gave up')), 120_000);

const answer = await sf.wait({ kind: 'pull', owner: 'acme', repo: 'api', number: 128 }, { until: 'checks', within: 900, signal: stop.signal });
```

`sf.waits.wait(input)` is the raw single-window operation, for code that wants to manage `waited` and `baseline` itself.

The same topic for Python: [Python held writes and waits](https://sailfork.com/docs/sdk-python-held-and-waits).

---

Every docs page: https://sailfork.com/llms.txt
