typeship-ax

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

Generated by typeship 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

npm install typeship-ax

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

Related MCP server: cod-api MCP Server

Quickstart

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:

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

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

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:

{
  "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

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