TypeScript
Generate packages and manage Typeship Projects from TypeScript.
@typeship-ax/sdk is the TypeScript SDK for the Typeship API. Use it to generate packages, manage Projects, and inspect results from your application.
The package has zero runtime dependencies, typed responses and errors, pagination, and retries. The Typeship CLI and Typeship MCP server have separate packages and release streams.
Install
npm install @typeship-ax/sdkNode 20 or newer. ESM only.
Create a client
import { TypeshipClient } from "@typeship-ax/sdk";
const client = new TypeshipClient({ bearerToken: process.env.TYPESHIP_TOKEN! });Create a key in the Console under API keys and pass it explicitly. The Typeship SDK does not read environment variables for credentials.
TypeshipClient accepts baseUrl, timeoutMs, maxRetries, defaultHeaders, fetch, hooks, debugging, and validation options. See Client options.
Generate a package
packages.generate returns one generated package without creating a Project. Anonymous and Free requests generate 25 operations.
In a new directory, initialize a package and install the Typeship SDK:
npm init -y
npm install @typeship-ax/sdkSave this as generate.mjs. It uses the hosted Petstore sample and needs no API key. Set TYPESHIP_TOKEN to use your organization's plan.
import { mkdir, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { TypeshipClient } from "@typeship-ax/sdk";
const client = new TypeshipClient({ bearerToken: process.env.TYPESHIP_TOKEN });
const result = await client.packages.generate({
spec: { url: "https://typeship.dev/examples/petstore/openapi.yaml" },
target: { type: "typescript_sdk" },
});
for (const file of result.files) {
const destination = join("out", file.path);
await mkdir(dirname(destination), { recursive: true });
await writeFile(destination, file.content, "utf8");
}
console.log(result.coverage.generated, "operations written to out/");Run it from a directory where out/ can be created or replaced:
node generate.mjs
cd out
npm install
npm testThe call throws a typed error if generation fails. File-system errors also stop the script with a nonzero exit status. The script creates nested directories and overwrites matching files in out/.
Work with projects
import { TypeshipClient } from "@typeship-ax/sdk";
const client = new TypeshipClient({ bearerToken: process.env.TYPESHIP_TOKEN! });
const project = await client.projects.create({
name: "Parcel API",
spec: { source: { type: "url", url: { url: "https://api.parcel.example/openapi.json" } } },
targets: [
{
name: "Parcel TypeScript SDK",
type: "typescript_sdk",
deliveries: [{
type: "repository",
repository: { provider: "github", identifier: "parcel/typescript", package_name: "@parcel/sdk" },
}],
},
{ name: "Parcel CLI", type: "cli" },
{ name: "Parcel MCP", type: "mcp", deliveries: [{ type: "hosted_mcp" }] },
],
auto_generate: true,
});
// Start every selected Target, then wait for its generated files.
const generations = await client.projects.generate(project.id);
for (const generation of generations.data) {
const completed = await client.generations.wait(generation.id);
console.log(completed.target_id, completed.status, completed.errors);
}
// Walk history.
for await (const generation of client.generations.list({ project_id: project.id })) {
console.log(generation.created_at, generation.trigger, generation.status);
}Every method
| Resource | Methods |
|---|---|
projects | create, list, get, update, delete, generate |
specs | get, update, refresh |
specRevisions | list, get, listFiles |
targets | create, list, get, update, delete, adopt |
deliveries | create, list, get, update, delete |
generations | get, list, listFiles, wait |
drafts | list, get, update, listFiles, resolve, recover |
releases | list, get, retry |
files | get |
packages | generate, download |
organization | get |
apiKeys | list, get, revoke |
Bodies, query parameters, and responses use the API's snake_case names. api.md is the readable package reference; api.json carries the same operations, nested schemas, examples, authentication, and safety for agents and tooling. The API reference has every schema.
Errors
Every call resolves to response data or throws. Each status family (400, 401, 403, 404, 409, 422, 429, and 5xx) has one subclass of ApiError, raised whether or not the operation documents the status. Other statuses the API documents, such as 402, have their own class; other failures use UnexpectedApiError, ResponseParseError, TransportError, or ValidationError. ResponseParseError means a successful response declared JSON but its body was malformed. Every error has code, status, requestId, body, and a message with the next step.
import { NotFoundError, PaymentRequiredError, ResponseParseError } from "@typeship-ax/sdk";
try {
await client.projects.generate("prj_...");
} catch (error) {
if (error instanceof PaymentRequiredError) {
// free plan allowance used up; error.body.errors[0].message says so
}
if (error instanceof NotFoundError) {
// no such project in this Organization
}
if (error instanceof ResponseParseError) {
console.error(error.status, error.body);
}
throw error;
}A successful response body carries request_id. On an error, error.requestId holds the envelope's request_id, or the Request-Id header for a response without a JSON body. Local validation and transport failures that received no response have none.
See Errors for the envelope and codes.