typeship-ax

Типизированный TypeScript SDK, CLI и MCP-сервер без зависимостей для typeship (v0.1.0).

Сгенерировано typeship из спецификации OpenAPI — не редактируйте вручную, а перегенерируйте.

• Ноль зависимостей во время выполнения — построено на платформенном fetch (Node 18+, браузеры, edge-рантаймы)

• Типизированные объединения ошибок — каждый вызов возвращает ApiResult<T, E>, где E перечисляет каждую документированную ошибку для этой конкретной операции

• Автопагинация — используйте for await с любым списковым вызовом, чтобы потоково получать каждый элемент на всех страницах

• Встроенные повторы — идемпотентные запросы повторяются с экспоненциальной задержкой и поддержкой Retry-After

• Опциональная проверка во время выполнения — validate: true сверяет тела запросов и ответов со схемой из спецификации, по-прежнему без зависимостей

• Tree-shakeable — модули по отдельным ресурсам, sideEffects: false

Установка

npm install typeship-ax

До первой публикации установите его из сгенерированной папки: npm install ./typeship-права.

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, идентификаторы тенантов); 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: каждая операция — команда с типизированными флагами, JSON на stdout, коды завершения 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 оставляет у результата только указанные поля. Флаги дат принимают относительные формы (-7d, "7 days ago", today), а также ISO 8601. Команды с пагинацией выводят одну страницу и команду, которая получит следующую; --all выводит все элементы потоковом в формате NDJSON. Деструктивные команды запрашивают подтверждение или принимают --force. При передаче в конвейер ошибки — это один JSON-конверт на stderr ({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-сервер

MCP-сервер на stdio без зависимостей, предоставляющий каждую операцию как инструмент. Добавьте его в конфигурацию MCP-клиента:

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

Схемы входящих данных инструментов выводятся из спецификации, поэтому агенты видят реальные типы параметров и обязательные поля. Аргументы проверяются до того, как что-либо достигает API (неизвестные или напечатанные с ошибкой возвращаются одним результатом isError, ничего не теряется); каждый инструмент принимает fields, чтобы оставить только нужные ключи результата, а ошибки содержат стабильные code и next_steps.

Добавьте --read-only к args (или установите TYPESHIP_MCP_READ_ONLY=1) для сервера, который не может писать; --tools methods,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 }.