Operations and types (TypeScript)
How catalog operations become typed methods in the TypeScript SDK, how to import input and output types, how paging works, and how streams and long operations behave.
Every operation in the catalog is a method with one input object. This page covers the naming, the types, paging, and the long and streaming operations.
The areas on sf are caissons, check_runs, ci, events, github, held, inbox, issues, keys, labels, me, merge_queue, milestones, notes, pulls, repos, sandboxes, search, symbols, tokens and waits.
| Catalog id | Method | Input type |
|---|---|---|
issues.create_batch | sf.issues.createBatch | types.IssuesCreateBatchInput |
pulls.auto_merge_enable | sf.pulls.autoMergeEnable | types.PullsAutoMergeEnableInput |
caissons.review_submit | sf.caissons.reviewSubmit | types.CaissonsReviewSubmitInput |
check_runs.create | sf.check_runs.create | types.CheckRunsCreateInput |
Call an operation
Every operation in the catalog is a method named sf.<area>.<verb>(input, options?). The area is the catalog's: issues, pulls, caissons, ci, held, sandboxes, and areas with an underscore such as check_runs and merge_queue, which keep it. The verb is camel-cased: issues.create_batch is sf.issues.createBatch, pulls.auto_merge_enable is sf.pulls.autoMergeEnable, caissons.review_submit is sf.caissons.reviewSubmit.
The input is one object. Path, query and body fields all go in it, with the names the API documents. A method returns a promise of the operation's answer.
import Sailfork, { type types } from 'sailfork';
const sf = new Sailfork();
const page: types.PullPage = await sf.pulls.list({ owner: 'acme', repo: 'api', limit: 10 });
const created = await sf.check_runs.create({
owner: 'acme',
repo: 'api',
headSha: '0123456789abcdef0123456789abcdef01234567',
name: 'lint',
});
const note: types.CheckRun = created; The types namespace holds the input and output of every operation. The names are the area and verb in PascalCase, then Input or Output: types.PullsListInput, types.PullsListOutput, types.CheckRunsCreateInput. The shared shapes they use are there too: types.Pull, types.Issue, types.Caisson, types.HeldRequest.
import type { types } from 'sailfork';
function mergeInput(number: number): types.PullsMergeInput {
return { owner: 'acme', repo: 'api', number, method: 'squash', deleteBranch: true };
} A path parameter missing from the input throws a TypeError (pulls.get needs the path parameter \number``) before any request is made.
Pages
A list answers { items, nextCursor }, and nextCursor is null on the last page. Pass it back as cursor. The limit bounds are in Paging.
import Sailfork, { type types } from 'sailfork';
const sf = new Sailfork();
const repo = sf.repo('acme/api');
const open: types.Issue[] = [];
let cursor: string | undefined;
do {
const page = await repo.issues.list({ state: 'open', limit: 100, ...(cursor === undefined ? {} : { cursor }) });
open.push(...page.items);
cursor = page.nextCursor ?? undefined;
} while (cursor !== undefined); Streams and long operations
Five operations are long: caissons.bash, caissons.ship, caissons.test, issues.start and sandboxes.exec. Their default timeout is 300 seconds, not 60. waits.wait is long too, and sf.wait sets its own timeout per window.
The client can also read server-sent events and newline-delimited JSON, but no generated method uses it yet. sf.core has the methods, and you describe the route with an OpMeta, a type the package exports.
Core method | Reads | Yields |
|---|---|---|
core.stream(op, params, options?) | A text/event-stream route | StreamEvent<T>: { id, event, data }. data is parsed JSON when it parses, else the text. event is message when the server names none |
core.ndjson(op, params, options?) | An application/x-ndjson route | One parsed value per line |
core.paginate(op, params, options?) | A route that answers { items, nextCursor } | An async iterable of items, with page() for one page |
A CI run's live route is a stream. This follows a run until it ends:
import Sailfork, { type OpMeta, type StreamEvent } from 'sailfork';
const sf = new Sailfork();
const live = {
id: 'ci.live',
method: 'GET',
path: '/api/repos/{owner}/{repo}/runs/{id}/live',
pathParams: ['owner', 'repo', 'id'],
queryParams: ['logs'],
bodyParams: [],
effect: 'read',
retry: 'safe',
held: false,
long: true,
paginated: false,
} as const satisfies OpMeta;
for await (const event of sf.core.stream<unknown>(live, { owner: 'acme', repo: 'api', id: 1804, logs: false })) {
const typed: StreamEvent = event;
console.log(typed.id, typed.event, typed.data);
} The loop finishes after the server sends end. When the connection closes without it, the stream reconnects with Last-Event-ID set to the last id it saw, and after a connection error it retries up to maxRetries failures in a row. Pass signal in the options to stop early: aborting it cancels the read at any point and rejects with the signal's reason.
The route, its events and its have cursor are in Watch a run live. The sandbox event routes are NDJSON; see Follow events.
core.paginate follows nextCursor until it is null:
import Sailfork, { type OpMeta, type types } from 'sailfork';
const sf = new Sailfork();
const issuesList = {
id: 'issues.list',
method: 'GET',
path: '/api/repos/{owner}/{repo}/issues',
pathParams: ['owner', 'repo'],
queryParams: ['state', 'limit', 'cursor'],
bodyParams: [],
effect: 'read',
retry: 'safe',
held: false,
long: false,
paginated: true,
} as const satisfies OpMeta;
let count = 0;
for await (const issue of sf.core.paginate<types.Issue>(issuesList, { owner: 'acme', repo: 'api', state: 'open', limit: 100 })) {
if (issue.number > 0) count++;
} The same topic for Python: Python operations and types.