Skip to content

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.

HandleGet oneBindsHolds
Reposf.repo('owner/name')owner, repoEvery 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
Orgsf.org('handle')orgcaissons (list, open, policy), held.org, sandboxes (create, list)
PullRequestrepo.pull(number), or returned by a methodowner, repo, numberget, update, merge, autoMergeEnable, autoMergeDisable, checks, comment, review, resolveThread, dismiss, stack, updateBranch, approvePull and the comment edits
Caissonrepo.caisson(id), or returned by a methodidread, 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:

CallReturns
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.

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:

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.

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

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.

Loading Sailfork