typeship-ax

typeship (v0.1.0) 向けの型付き・依存関係ゼロの TypeScript SDK + CLI + MCP サーバー。

typeship が OpenAPI 仕様から生成 — 手動で編集せず、再生成してください。

• ランタイム依存関係ゼロ — プラットフォームの fetch 上に構築 (Node 18+、ブラウザ、エッジランタイム)

• 型付きエラーユニオン — すべての呼び出しは ApiResult<T, E> を返し、E はその操作について文書化された各エラーを列挙します

• 自動ページネーション — 任意のリスト呼び出しを for await で処理し、全ページの全項目をストリーム出力

• リトライ内蔵 — 冪等なリクエストは指数バックオフと Retry-After 対応でリトライします

• オプションのランタイム検証 — validate: true でリクエスト・レスポンス本文を仕様に対してスキーマ検証。それでも依存関係はゼロ

• ツリーシェイク可能 — リソースごとのモジュール、sideEffects: false

インストール

npm install typeship-ax

初回公開前は、生成されたフォルダからインストールしてください: npm install ./typeship-ax。

Related MCP server: @typeship-ax/mcp

クイックスタート

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

認証

• Bearer トークン — bearerToken (文字列、または期限切れトークン用のコールバック)。Authorization: Bearer <token> として送信されます。

defaultHeaders はすべてのリクエストにヘッダーを追加します (API バージョンヘッダー、テナント ID)。onRequest は送信前に任意のリクエストを書き換えられます。

エラー処理

HTTP エラーで例外は発生しません。すべての呼び出しは判別可能な結果を返し、 エラー側はその操作について文書化されたエラークラスのユニオンです:

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

例外のほうが好みですか? unwrap(result) はデータを返すか、型付きエラーをスローします。

ページネーション

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

このパッケージにはコマンドラインツール typeship が同梱されています。すべての操作が型付きフラグ付きのコマンドとして提供され、stdout に JSON を出力し、終了コードは 0/1/2 (成功 / 失敗 / 使用方法) です。グローバルにインストールするか、クローンから実行します (npm install && npm run build、その後 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

パスパラメータは位置引数です。それ以外はすべてワイヤーフィールド名のフラグ (--name、--limit) です。配列フィールドはカンマ区切りリストまたはフラグの繰り返し、オブジェクトフィールドは JSON を受け取り、--data '<json>' (または --data @file、--data -) で本文全体を設定します。--fields id,name は結果のうち指定したフィールドだけを保持します。日付フラグは ISO 8601 に加えて相対形式 (-7d、"7 days ago"、today) も受け付けます。ページネーション対応コマンドは 1 ページを出力し、次のページを取得するコマンドも表示します。--all はすべての項目を NDJSON としてストリーム出力します。破壊的なコマンドは確認を求めるか、--force を受け付けます。エラーはパイプ時には stderr に 1 つの JSON エンベロープ ({status, issues[{code}], next_steps})、ターミナルでは散文で出力されます。

認証: typeship login は ~/.config/typeship/ の下に資格情報を保存します。環境変数 (TYPESHIP_TOKEN) とフラグ (--token) がそれより優先されます。TYPESHIP_BASE_URL / --base-url でエンドポイントを選択します。

その他: typeship init はマシンを接続します。資格情報、検出したエージェントクライアント用の MCP 設定、AGENTS.md ブロックを設定します。typeship mcp install --all は MCP サーバーを Claude Code、Cursor、Codex、VS Code などに登録します。typeship docs <resource> <command> は完全なリファレンスを出力し、typeship docs search <term> はそれを検索します。typeship completion bash|zsh、typeship doctor、typeship upgrade、typeship agent-guide、エージェント向けの typeship help --json もあります。全体像は typeship --help を実行してください。

MCP サーバー

依存関係ゼロの stdio MCP サーバーで、すべての操作をツールとして公開します。MCP クライアント設定に追加してください:

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

ツールの入力スキーマは仕様から導出されるため、エージェントは実際のパラメータ型と必須フィールドを確認できます。引数は API に到達する前にチェックされます (不明または型違いの引数は 1 つの isError 結果として返され、何も破棄されません)。すべてのツールは必要な結果キーだけを保持する fields を受け取り、エラーは安定した code と next_steps を保持します。

書き込み不可のサーバーにするには args に --read-only を追加し (または TYPESHIP_MCP_READ_ONLY=1 を設定)、サブセットを公開するには --tools accounts,reports (または TYPESHIP_MCP_TOOLS)、結果サイズの上限を変更するには TYPESHIP_MCP_MAX_RESULT_CHARS (64,000) を使用します。typeship mcp install --claude --read-only は読み取り専用エントリを自動で書き込みます。

設定

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

呼び出しごとの上書きは最後の引数で指定します: { timeoutMs, maxRetries, headers, signal }。