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 오류가 발생해도 아무것도 throw되지 않습니다. 모든 호출은 판별된(discriminated) 결과를 반환하며, 오류 쪽은 해당 작업에 문서화된 오류 클래스들의 유니언입니다:

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)는 데이터를 반환하거나 타입 기반 오류를 throw합니다.

페이지네이션

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

경로 매개변수는 위치 기반(positional)이며, 그 외의 모든 것은 와이어 필드 이름을 딴 플래그입니다(--name, --limit). 배열 필드는 쉼표 목록 또는 플래그 반복을 받고, 객체 필드는 JSON을 받으며, --data '<json>'(또는 --data @file, --data -)는 전체 본문을 설정합니다. --fields id,name은 결과에서 해당 필드만 유지합니다. 날짜 플래그는 ISO 8601뿐 아니라 상대 형식(-7d, "7 days ago", today)도 받습니다. 페이지네이션 명령은 다음 페이지를 가져오는 명령과 함께 한 페이지를 출력하며, --all은 모든 항목을 NDJSON으로 스트리밍합니다. 파괴적 명령은 확인을 묻거나 --force를 받습니다. 오류는 파이프로 연결될 때 stderr에 하나의 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에 도달하기 전에 검사되며(알 수 없거나 잘못 입력된 인수는 하나의 isError 결과로 반환되고, 아무것도 버려지지 않습니다), 모든 도구는 필요한 결과 키만 유지하기 위해 fields를 받으며, 오류에는 안정적인 code와 next_steps가 포함됩니다.

쓰기가 불가능한 서버를 원하면 args에 --read-only를 추가하고(또는 TYPESHIP_MCP_READ_ONLY=1 설정), 하위 집합만 노출하려면 --tools accounts,reports(또는 TYPESHIP_MCP_TOOLS)를 사용하며, 결과 크기 상한(64,000)을 변경하려면 TYPESHIP_MCP_MAX_RESULT_CHARS를 사용합니다. 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 }.