typeship-ax

SDK de TypeScript tipado, sin dependencias, + CLI + servidor MCP para typeship (v0.1.0).

Generado por typeship a partir de la especificación OpenAPI — no lo edites a mano; regenéralo en su lugar.

• Cero dependencias en tiempo de ejecución — construido sobre fetch de la plataforma (Node 18+, navegadores, runtimes de borde)

• Uniones de error tipadas — cada llamada devuelve ApiResult<T, E> donde E enumera cada error documentado para esa operación exacta

• Paginación automática — for await en cualquier llamada de lista para transmitir cada elemento de cada página

• Reintentos integrados — las solicitudes idempotentes se reintentan con retroceso exponencial y soporte de Retry-After

• Validación opcional en tiempo de ejecución — validate: true verifica el esquema de los cuerpos de solicitud y respuesta contra la especificación, sin dependencias

• Tree-shakeable — módulos por recurso, sideEffects: false

Instalación

npm install typeship-ax

Antes de la primera publicación, instálalo desde la carpeta generada: npm install ./typeship-ax.

Related MCP server: @typeship-ax/mcp

Inicio rápido

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);
}

Autenticación

• Token Bearer — bearerToken (una cadena, o un callback para tokens que expiran), enviado como Authorization: Bearer <token>.

defaultHeaders añade cabeceras a cada solicitud (cabeceras de versión de API, ids de tenant); onRequest puede reescribir cualquier solicitud antes de que se envíe.

Manejo de errores

Nada lanza excepciones en errores HTTP. Cada llamada devuelve un resultado discriminado, y el lado de error es una unión de las clases de error documentadas para esa operación:

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

¿Prefieres excepciones? unwrap(result) devuelve los datos o lanza el error tipado.

Paginación

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

El paquete incluye una herramienta de línea de comandos, typeship: cada operación como un comando con banderas tipadas, JSON en stdout, códigos de salida 0/1/2 (ok / fallo / uso). Instálalo globalmente, o ejecútalo desde un clon (npm install && npm run build, luego 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

Los parámetros de ruta son posicionales; todo lo demás es una bandera con el nombre del campo de la API (--name, --limit). Los campos de matriz aceptan una lista separada por comas o la bandera repetida, los campos de objeto aceptan JSON, y --data '<json>' (o --data @file, --data -) establece todo el cuerpo. --fields id,name conserva solo esos campos del resultado. Las banderas de fecha aceptan formas relativas (-7d, "7 days ago", today) además de ISO 8601. Los comandos paginados imprimen una página con el comando que obtiene la siguiente; --all transmite cada elemento como NDJSON. Los comandos destructivos preguntan, o aceptan --force. Los errores son un sobre JSON en stderr ({status, issues[{code}], next_steps}) cuando se canalizan, prosa en una terminal.

Autenticación: typeship login guarda una credencial en ~/.config/typeship/; el entorno (TYPESHIP_TOKEN) y las banderas (--token) tienen prioridad sobre ella. TYPESHIP_BASE_URL / --base-url eligen el endpoint.

También: typeship init conecta una máquina: credencial, configuración MCP para los clientes de agente que encuentre, un bloque AGENTS.md; typeship mcp install --all registra el servidor MCP con Claude Code, Cursor, Codex, VS Code y los demás; typeship docs <resource> <command> imprime la referencia completa, typeship docs search <term> la busca; typeship completion bash|zsh, typeship doctor, typeship upgrade, typeship agent-guide y typeship help --json para agentes. Ejecuta typeship --help para el mapa.

Servidor MCP

Un servidor MCP stdio sin dependencias que expone cada operación como una herramienta. Añádelo a la configuración de tu cliente MCP:

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

Los esquemas de entrada de las herramientas se derivan de la especificación, por lo que los agentes ven tipos de parámetros reales y campos obligatorios. Los argumentos se verifican antes de que cualquier cosa llegue a la API (los desconocidos o mal escritos devuelven un resultado isError, no se descarta nada), cada herramienta acepta fields para conservar solo las claves del resultado que necesita, y los errores llevan un code estable y next_steps.

Añade --read-only a args (o establece TYPESHIP_MCP_READ_ONLY=1) para un servidor que no puede escribir, --tools accounts,reports (o TYPESHIP_MCP_TOOLS) para exponer un subconjunto, y TYPESHIP_MCP_MAX_RESULT_CHARS para cambiar el límite de tamaño del resultado (64,000). typeship mcp install --claude --read-only escribe la entrada de solo lectura por ti.

Configuración

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
});

Las anulaciones por llamada van en el último argumento: { timeoutMs, maxRetries, headers, signal }.