typeship-ax

Typisiertes, abhängigkeitsfreies TypeScript SDK + CLI + MCP-Server für typeship (v0.1.0).

Generiert von typeship aus der OpenAPI-Spezifikation — nicht von Hand bearbeiten; stattdessen neu generieren.

• Keine Laufzeitabhängigkeiten — basiert auf der Plattform-fetch (Node 18+, Browser, Edge-Runtimes)

• Typisierte Fehler-Unionen — jeder Aufruf gibt ApiResult<T, E> zurück, wobei E jeden dokumentierten Fehler für genau diese Operation auflistet

• Automatische Paginierung — for await bei jedem Listenaufruf, um jedes Element über alle Seiten zu streamen

• Eingebaute Wiederholungen — idempotente Anfragen werden mit exponentiellem Backoff und Retry-After-Unterstützung wiederholt

• Optionale Laufzeitvalidierung — validate: true prüft Anfrage- und Antwortkörper schema-basiert gegen die Spezifikation, weiterhin ohne Abhängigkeiten

• Tree-shakeable — Module pro Ressource, sideEffects: false

Install

npm install typeship-ax

Vor der ersten Veröffentlichung installieren Sie es stattdessen aus dem generierten Ordner: npm install ./typeship-ax.

Related MCP server: @typeship-ax/mcp

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 (ein String oder ein Callback für ablaufende Tokens), gesendet als Authorization: Bearer <token>.

defaultHeaders fügt jeder Anfrage Header hinzu (API-Versions-Header, Mandanten-IDs); onRequest kann jede Anfrage vor dem Senden umschreiben.

Error handling

Bei HTTP-Fehlern wird nichts geworfen. Jeder Aufruf gibt ein diskriminiertes Ergebnis zurück, und die Fehlerseite ist eine Union der dokumentierten Fehlerklassen für diese 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

Exceptions bevorzugt? unwrap(result) gibt die Daten zurück oder wirft den typisierten Fehler.

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

Das Paket enthält ein Befehlszeilenwerkzeug, typeship: jede Operation als Befehl mit typisierten Flags, JSON auf stdout, Exit-Codes 0/1/2 (ok / fehlgeschlagen / Verwendung). Installieren Sie es global oder führen Sie es aus einem Klon aus (npm install && npm run build, dann 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

Pfadparameter sind positionell; alles andere ist ein Flag, das nach dem Wire-Feld benannt ist (--name, --limit). Array-Felder akzeptieren eine Komma-Liste oder das wiederholte Flag, Objektfelder akzeptieren JSON, und --data '<json>' (oder --data @file, --data -) setzt den gesamten Body. --fields id,name behält nur diese Felder des Ergebnisses. Datums-Flags akzeptieren relative Formen (-7d, "7 days ago", today) sowie ISO 8601. Paginierte Befehle geben eine Seite aus, zusammen mit dem Befehl, der die nächste abruft; --all streamt jedes Element als NDJSON. Destruktive Befehle fragen nach oder akzeptieren --force. Fehler sind ein JSON-Envelope auf stderr ({status, issues[{code}], next_steps}) bei Pipe, Prosa auf einem Terminal.

Auth: typeship login speichert eine Anmeldeinformation unter ~/.config/typeship/; die Umgebung (TYPESHIP_TOKEN) und Flags (--token) haben Vorrang. TYPESHIP_BASE_URL / --base-url wählen den Endpunkt.

Außerdem: typeship init verbindet eine Maschine: Anmeldeinformation, MCP-Konfiguration für die gefundenen Agent-Clients, einen AGENTS.md-Block; typeship mcp install --all registriert den MCP-Server bei Claude Code, Cursor, Codex, VS Code und dem Rest; typeship docs <resource> <command> gibt die vollständige Referenz aus, typeship docs search <term> durchsucht sie; typeship completion bash|zsh, typeship doctor, typeship upgrade, typeship agent-guide und typeship help --json für Agenten. Führen Sie typeship --help für die Übersicht aus.

MCP server

Ein abhängigkeitsfreier stdio-MCP-Server, der jede Operation als Tool bereitstellt. Fügen Sie zu Ihrer MCP-Client-Konfiguration hinzu:

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

Tool-Eingabeschemas werden aus der Spezifikation abgeleitet, sodass Agenten echte Parametertypen und Pflichtfelder sehen. Argumente werden geprüft, bevor etwas die API erreicht (unbekannte oder falsch typisierte werden als ein isError-Ergebnis zurückgegeben, nichts wird verworfen), jedes Tool akzeptiert fields, um nur die benötigten Ergebnis-Schlüssel zu behalten, und Fehler tragen einen stabilen code und next_steps.

Fügen Sie --read-only zu args hinzu (oder setzen Sie TYPESHIP_MCP_READ_ONLY=1) für einen Server, der nicht schreiben kann, --tools accounts,reports (oder TYPESHIP_MCP_TOOLS), um eine Teilmenge bereitzustellen, und TYPESHIP_MCP_MAX_RESULT_CHARS, um das Ergebnisgrößenlimit (64.000) zu ändern. typeship mcp install --claude --read-only schreibt den Nur-Lese-Eintrag für Sie.

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

Überschreibungen pro Aufruf erfolgen über das letzte Argument: { timeoutMs, maxRetries, headers, signal }.