typescript

# typeship-ax

Typed, zero-dependency TypeScript SDK + CLI + MCP server for **typeship** (v0.1.0).

Generated by [typeship](https://typeship.dev) from the OpenAPI spec — do not edit by hand; regenerate instead.

- **Zero runtime dependencies** — built on the platform `fetch` (Node 18+, browsers, edge runtimes)
- **Typed error unions** — every call returns `ApiResult<T, E>` where `E` lists each documented error for that exact operation
- **Auto-pagination** — `for await` any list call to stream every item across every page
- **Retries built in** — idempotent requests retry with exponential backoff and `Retry-After` support
- **Optional runtime validation** — `validate: true` schema-checks request and response bodies against the spec, still zero dependencies
- **Tree-shakeable** — per-resource modules, `sideEffects: false`

## Install

```sh
npm install typeship-ax
```

Before the first publish, install it from the generated folder instead: `npm install ./typeship-ax`.

## Quickstart

```ts
import { TypeshipClient } from "typeship-ax";

const client = new TypeshipClient({ bearerToken: process.env.TYPESHIP_TOKEN! });

for await (const item of client.projects.list()) {
  console.log(item);
}
```

## Authentication

- **Bearer token** — `bearerToken` (a string, or a callback for tokens that expire), sent as `Authorization: Bearer <token>`.

`defaultHeaders` adds headers to every request (API version headers, tenant ids); `onRequest` can rewrite any request before it is sent.

## Error handling

Nothing throws on HTTP errors. Every call returns a discriminated result, and the
error side is a union of the documented error classes for that operation:

```ts
import { UnauthorizedError } from "typeship-ax";

const result = await client.projects.list();

if (!result.ok) {
  if (result.error instanceof UnauthorizedError) {
    // result.error.body is fully typed for this status
  }
  throw result.error; // every branch is an Error subclass
}

result.data; // typed success payload
```

Prefer exceptions? `unwrap(result)` returns the data or throws the typed error.

## Pagination

```ts
for await (const item of client.projects.list()) {
  // every item from every page, fetched lazily
}

// or page manually:
const page = await client.projects.list();
if (page.ok) {
  page.data.items;
  await page.data.getNextPage();
}
```

## CLI

The package ships a command-line tool, `typeship`: every operation as a command with typed flags, JSON on stdout, exit codes 0/1/2 (ok / failed / usage). Install it globally, or run it from a clone (`npm install && npm run build`, then `node dist/cli.js`).

```sh
npm install -g typeship-ax
typeship login                      # stores a credential (or set TYPESHIP_TOKEN)
typeship projects list
typeship projects create --name "<name>"
typeship projects list --all | jq -r '.id'   # every page, one item per line
typeship <resource> <command> --help     # flags, types, an example
```

Path parameters are positional; everything else is a flag named after the wire field (`--name`, `--limit`). Array fields take a comma list or the flag repeated, object fields take JSON, and `--data '<json>'` (or `--data @file`, `--data -`) sets the whole body. `--fields id,name` keeps only those fields of the result. Date flags take relative forms (`-7d`, `"7 days ago"`, `today`) as well as ISO 8601. Paginated commands print one page with the command that fetches the next; `--all` streams every item as NDJSON. Destructive commands ask, or take `--force`. Errors are one JSON envelope on stderr (`{status, issues[{code}], next_steps}`) when piped, prose on a terminal.

Auth: `typeship login` stores a credential under `~/.config/typeship/`; the environment (`TYPESHIP_TOKEN`) and flags (`--token`) win over it. `TYPESHIP_BASE_URL` / `--base-url` pick the endpoint.

Also: `typeship init` connects a machine: credential, MCP config for the agent clients it finds, an AGENTS.md block; `typeship mcp install --all` registers the MCP server with Claude Code, Cursor, Codex, VS Code and the rest; `typeship docs <resource> <command>` prints the full reference, `typeship docs search <term>` searches it; `typeship completion bash|zsh`, `typeship doctor`, `typeship upgrade`, `typeship agent-guide` and `typeship help --json` for agents. Run `typeship --help` for the map.

## MCP server

A zero-dependency stdio MCP server exposing every operation as a tool. Add to your MCP client config:

```json
{
  "mcpServers": {
    "typeship": {
      "command": "node",
      "args": [
        "<path-to>/typeship-ax/dist/mcp.js"
      ],
      "env": {
        "TYPESHIP_TOKEN": "…"
      }
    }
  }
}
```

Tool input schemas are derived from the spec, so agents see real parameter types and required fields. Arguments are checked before anything reaches the API (unknown or mistyped ones come back as one `isError` result, nothing is dropped), every tool takes `fields` to keep only the result keys it needs, and errors carry a stable `code` and `next_steps`.

Add `--read-only` to `args` (or set `TYPESHIP_MCP_READ_ONLY=1`) for a server that cannot write, `--tools accounts,reports` (or `TYPESHIP_MCP_TOOLS`) to expose a subset, and `TYPESHIP_MCP_MAX_RESULT_CHARS` to change the result size cap (64,000). `typeship mcp install --claude --read-only` writes the read-only entry for you.

## Configuration

```ts
new TypeshipClient({
  baseUrl: "https://typeship.dev/api/v1", // default
  timeoutMs: 30_000, // per attempt
  maxRetries: 2,     // retryable failures only
  fetch: globalThis.fetch, // or your own: proxies, tests, instrumentation
});
```

Per-call overrides ride on the last argument: `{ timeoutMs, maxRetries, headers, signal }`.