# Handles (TypeScript)

The Repo, Org, PullRequest and Caisson handles of the TypeScript SDK, how to get each one, what it binds and which methods return the next handle.

A handle binds the ids a call would repeat, so the input holds only what is left. This page covers the four handles and how they hand you each other.

## Get a handle

`sf.repo(...)` and `sf.org(...)` are synchronous and make no request.

| Handle | Get one | Binds | Holds |
| --- | --- | --- | --- |
| `Repo` | `sf.repo('owner/name')` | `owner`, `repo` | Every repo-scoped area: `issues`, `pulls`, `ci`, `check_runs`, `labels`, `merge_queue`, `milestones`, `notes`, `repos`, `symbols`. `repo.pull(number)` and `repo.caisson(id)` return the two handles below |
| `Org` | `sf.org('handle')` | `org` | `caissons` (`list`, `open`, `policy`), `held.org`, `sandboxes` (`create`, `list`) |
| `PullRequest` | `repo.pull(number)`, or returned by a method | `owner`, `repo`, `number` | `get`, `update`, `merge`, `autoMergeEnable`, `autoMergeDisable`, `checks`, `comment`, `review`, `resolveThread`, `dismiss`, `stack`, `updateBranch`, `approvePull` and the comment edits |
| `Caisson` | `repo.caisson(id)`, or returned by a method | `id` | `read`, `glob`, `grep`, `symbols`, `symbolRefs`, `batch`, `patch`, `diff`, `affected`, `bash`, `test`, `commit`, `pull`, `ship`, `fork`, `stop`, `get`, `locate`, `review`, `reviewStatus`, `reviewSubmit`, `reviewResolve` |

`sf.repo` throws an `Error` unless the name is `owner/name`. A handle exposes `core` and `bound`, so `pr.bound` is `{ owner, repo, number }`, which is the shape `sf.wait` wants for a pull request.

Three methods answer with the next handle in place of data:

| Call | Returns |
| --- | --- |
| `repo.pulls.create(...)`, or `sf.pulls.create(...)` | a `PullRequest` |
| `repo.issues.start({ number })`, or `sf.issues.start(...)` | a `Caisson` on the issue's branch |
| `caisson.ship(...)` | the `PullRequest` it opened |

`PullRequest` methods return data. `pr.get()` returns the `types.PullDetail`.

```ts
import Sailfork from 'sailfork';

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

const pr = await repo.pulls.create({ title: 'Charges round to the cent', branch: 'fix/charges', base: 'main' });
const detail = await pr.get();
console.log(pr.bound.number, detail.state, detail.branch);

const same = repo.pull(pr.bound.number); // a handle for a pull request you already know
```

A caisson that exists already comes from its id. `caissons.open` answers with data, so wrap its id in a handle:

```ts
import Sailfork from 'sailfork';

const sf = new Sailfork();
const opened = await sf.org('acme').caissons.open({
	repo: 'api',
	title: 'Round charges to the cent',
	scope: ['src/'],
	branch: 'fix/charges',
});
const caisson = sf.repo('acme/api').caisson(opened.id);
```

### Caisson methods fill in `org`

A caisson handle binds the `id` and the owner it sits under, so its methods take neither. `ship` also uses the owner to address the pull request it returns. Calls on the unbound `sf.caissons.*` resource still take `org`.

```ts
import Sailfork from 'sailfork';

const sf = new Sailfork();
const caisson = sf.repo('acme/api').caisson('c-z4nwicj7');

const { files } = await caisson.read({ paths: ['src/charge.ts'] });
```

## Org and repo areas

```ts
import Sailfork from 'sailfork';

const sf = new Sailfork();

const org = sf.org('acme');
const caissons = await org.caissons.list({});
const policy = await org.caissons.policy({});
const held = await org.held.org({});
console.log(caissons.items.length, policy, held.pending.length);

const repo = sf.repo('acme/api');
const runs = await repo.ci.runs({});
const labels = await repo.labels.list({});
console.log(runs.runs.length, labels);
```
The same topic for Python: [Python handles](https://sailfork.com/docs/sdk-python-handles).

---

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