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

```ts
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`.

```ts
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](https://sailfork.com/docs/api#paging).

```ts
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:

```ts
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](https://sailfork.com/docs/api-ci#watch-a-run-live). The sandbox event routes are NDJSON; see [Follow events](https://sailfork.com/docs/api-sandboxes#follow-events).

`core.paginate` follows `nextCursor` until it is `null`:

```ts
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](https://sailfork.com/docs/sdk-python-calls).

---

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