@typeship-ax/mcp 0.6.0

package/src/core/pagination.ts

@@ -0,0 +1,195 @@
+/**
+ * Auto-pagination. Generated by typeship — https://typeship.dev
+ *
+ * List operations return a PagePromise: `await` it for one page (a typed
+ * ApiResult), or `for await` it to stream every item across every page.
+ */
+
+import {
+  HttpCore,
+  type ApiResult,
+  type CoreRequest,
+  type ResponseMeta,
+} from "./http.js";
+
+export interface PageConfig {
+  style: "cursor" | "cursorFromLastId" | "page" | "offset";
+  /** Response field holding the item array ("data", "items", …). */
+  itemsField: string;
+  cursorParam?: string;
+  /** Dot-path into the response body ("next_cursor", "meta.next_cursor"). */
+  nextCursorField?: string;
+  hasMoreField?: string;
+  /** cursorFromLastId: item field whose value seeds the next request. */
+  idField?: string;
+  pageParam?: string;
+  offsetParam?: string;
+  limitParam?: string;
+}
+
+type FetchPage<Item, E> = (
+  query: Record<string, unknown>,
+) => Promise<ApiResult<Page<Item, E>, E>>;
+
+export class Page<Item, E = unknown> {
+  private readonly fetchPage: FetchPage<Item, E>;
+  private readonly config: PageConfig;
+  private readonly params: Record<string, unknown>;
+  readonly body: unknown;
+  readonly response: ResponseMeta;
+
+  constructor(
+    fetchPage: FetchPage<Item, E>,
+    config: PageConfig,
+    params: Record<string, unknown>,
+    body: unknown,
+    response: ResponseMeta,
+  ) {
+    this.fetchPage = fetchPage;
+    this.config = config;
+    this.params = params;
+    this.body = body;
+    this.response = response;
+  }
+
+  get items(): Item[] {
+    const value = getPath(this.body, this.config.itemsField);
+    return Array.isArray(value) ? (value as Item[]) : [];
+  }
+
+  hasNextPage(): boolean {
+    return this.nextPageParams() !== null;
+  }
+
+  nextPageParams(): Record<string, unknown> | null {
+    const { config, params } = this;
+    const items = this.items;
+
+    if (config.hasMoreField !== undefined) {
+      const hasMore = getPath(this.body, config.hasMoreField);
+      if (hasMore === false) return null;
+    }
+
+    switch (config.style) {
+      case "cursor": {
+        const next = getPath(this.body, config.nextCursorField!);
+        if (next === undefined || next === null || next === "") return null;
+        return { ...params, [config.cursorParam!]: next };
+      }
+      case "cursorFromLastId": {
+        if (items.length === 0) return null;
+        const last = items[items.length - 1] as Record<string, unknown>;
+        const id = last?.[config.idField ?? "id"];
+        if (id === undefined || id === null) return null;
+        return { ...params, [config.cursorParam!]: id };
+      }
+      case "page": {
+        if (!this.looksLikeMore(items)) return null;
+        const current = Number(params[config.pageParam!] ?? 1);
+        return { ...params, [config.pageParam!]: current + 1 };
+      }
+      case "offset": {
+        if (!this.looksLikeMore(items)) return null;
+        const current = Number(params[config.offsetParam!] ?? 0);
+        return { ...params, [config.offsetParam!]: current + items.length };
+      }
+    }
+  }
+
+  /** Fetch the next page, or null when this is the last one. Throws the typed error on failure. */
+  async getNextPage(): Promise<Page<Item, E> | null> {
+    const next = this.nextPageParams();
+    if (next === null) return null;
+    const result = await this.fetchPage(next);
+    if (!result.ok) {
+      throw result.error instanceof Error ? result.error : new Error(String(result.error));
+    }
+    return result.data;
+  }
+
+  /** Iterate every item on this page and all following pages. */
+  async *[Symbol.asyncIterator](): AsyncIterator<Item, void, undefined> {
+    let page: Page<Item, E> | null = this;
+    while (page !== null) {
+      for (const item of page.items) yield item;
+      page = await page.getNextPage();
+    }
+  }
+
+  private looksLikeMore(items: Item[]): boolean {
+    if (items.length === 0) return false;
+    if (this.config.limitParam !== undefined) {
+      const limit = Number(this.params[this.config.limitParam]);
+      if (Number.isFinite(limit) && limit > 0) return items.length >= limit;
+    }
+    // Without a has_more signal or an explicit limit, an empty page is the
+    // only reliable stop condition.
+    return true;
+  }
+}
+
+/**
+ * Awaitable (one page, as a typed ApiResult) and async-iterable (all items,
+ * all pages). Iteration throws the operation's typed error union on failure.
+ */
+export class PagePromise<Item, E> implements PromiseLike<ApiResult<Page<Item, E>, E>>, AsyncIterable<Item> {
+  private readonly first: Promise<ApiResult<Page<Item, E>, E>>;
+  constructor(first: Promise<ApiResult<Page<Item, E>, E>>) {
+    this.first = first;
+  }
+
+  then<R1 = ApiResult<Page<Item, E>, E>, R2 = never>(
+    onfulfilled?: ((value: ApiResult<Page<Item, E>, E>) => R1 | PromiseLike<R1>) | null,
+    onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): Promise<R1 | R2> {
+    return this.first.then(onfulfilled, onrejected);
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<Item, void, undefined> {
+    const result = await this.first;
+    if (!result.ok) {
+      throw result.error instanceof Error ? result.error : new Error(String(result.error));
+    }
+    yield* result.data;
+  }
+}
+
+export function paginate<Item, E>(
+  core: HttpCore,
+  req: CoreRequest,
+  config: PageConfig,
+): PagePromise<Item, E> {
+  const isGraphql = req.graphqlField !== undefined;
+  const fetchPage: FetchPage<Item, E> = async (params) => {
+    const nextReq = isGraphql
+      ? {
+          ...req,
+          body: {
+            ...(req.body as Record<string, unknown>),
+            variables: { ...((req.body as { variables?: Record<string, unknown> })?.variables ?? {}), ...params },
+          },
+        }
+      : { ...req, query: params };
+    const result = await core.request<unknown, E>(nextReq);
+    if (!result.ok) return result;
+    const page = new Page<Item, E>(fetchPage, config, params, result.data, result.response);
+    return { ok: true, data: page, response: result.response };
+  };
+  const initial: Record<string, unknown> = {};
+  const seed = isGraphql
+    ? ((req.body as { variables?: Record<string, unknown> })?.variables ?? {})
+    : (req.query ?? {});
+  for (const [k, v] of Object.entries(seed)) {
+    if (v !== undefined) initial[k] = v;
+  }
+  return new PagePromise<Item, E>(fetchPage(initial));
+}
+
+function getPath(body: unknown, path: string): unknown {
+  let node: unknown = body;
+  for (const key of path.split(".")) {
+    if (typeof node !== "object" || node === null) return undefined;
+    node = (node as Record<string, unknown>)[key];
+  }
+  return node;
+}

package/src/dates.ts

@@ -0,0 +1,126 @@
+/**
+ * Relative dates for date / date-time arguments. Generated by typeship — https://typeship.dev
+ *
+ * Agents rarely know "now" and often do know "a week ago", so date-shaped
+ * arguments of the CLI and the MCP server accept, besides an absolute
+ * ISO 8601 value, a relative form resolved here against the clock:
+ *
+ *   now | today | yesterday | tomorrow
+ *   -P7D, +PT1H           signed ISO 8601 durations (negative = in the past)
+ *   -7d, +2h, -1w         signed shorthand: s m h d w mo y
+ *   7 days ago, in 2 weeks
+ *
+ * An unsigned duration ("7d", "P1D") is ambiguous and rejected with the two
+ * spellings that are not. Anything else passes through untouched; the API
+ * validates absolute values. Zero dependencies.
+ */
+
+export type DateKind = "date" | "date-time";
+
+const UNIT_MS: Record<string, number> = {
+  s: 1000, sec: 1000, second: 1000,
+  m: 60_000, min: 60_000, minute: 60_000,
+  h: 3_600_000, hr: 3_600_000, hour: 3_600_000,
+  d: 86_400_000, day: 86_400_000,
+  w: 604_800_000, wk: 604_800_000, week: 604_800_000,
+};
+const CALENDAR_UNITS = new Set(["mo", "month", "y", "yr", "year"]);
+
+const HINT = "Use a signed form: -7d or -P7D for seven days ago, +7d or +P7D for seven days ahead; or an absolute ISO 8601 value.";
+
+/** The forms a date-shaped argument accepts, for descriptions and help. */
+export const RELATIVE_DATE_HINT = "Accepts ISO 8601 or a relative form: -P7D, -7d, 7 days ago, today, now.";
+
+function shift(base: Date, amount: number, unit: string): Date {
+  const d = new Date(base.getTime());
+  if (CALENDAR_UNITS.has(unit)) {
+    if (unit.startsWith("y")) d.setUTCFullYear(d.getUTCFullYear() + amount);
+    else d.setUTCMonth(d.getUTCMonth() + amount);
+    return d;
+  }
+  return new Date(d.getTime() + amount * (UNIT_MS[unit] ?? 0));
+}
+
+function startOfUtcDay(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+}
+
+function format(d: Date, kind: DateKind): string {
+  return kind === "date" ? d.toISOString().slice(0, 10) : d.toISOString();
+}
+
+/** Apply a signed ISO 8601 duration (P1Y2M3W4DT5H6M7S) to a date. */
+function applyIsoDuration(base: Date, sign: number, body: string): Date | null {
+  const m = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/i.exec(body);
+  if (!m || body.toUpperCase() === "P" || body.toUpperCase() === "PT") return null;
+  let d = new Date(base.getTime());
+  const [, y, mo, w, day, h, min, s] = m;
+  if (y) d = shift(d, sign * Number(y), "y");
+  if (mo) d = shift(d, sign * Number(mo), "mo");
+  if (w) d = shift(d, sign * Number(w), "w");
+  if (day) d = shift(d, sign * Number(day), "d");
+  if (h) d = shift(d, sign * Number(h), "h");
+  if (min) d = shift(d, sign * Number(min), "m");
+  if (s) d = new Date(d.getTime() + sign * Number(s) * 1000);
+  return d;
+}
+
+/**
+ * Resolve a relative date expression. `null` means "not a relative form,
+ * pass the value through"; `{ error }` means it looked relative but is
+ * ambiguous or malformed; `{ value }` is the absolute value in the
+ * argument's format (YYYY-MM-DD for date, ISO instant for date-time).
+ */
+export function relativeDate(text: string, kind: DateKind, now: Date = new Date()): { value: string } | { error: string } | null {
+  const t = text.trim();
+  const lower = t.toLowerCase();
+  if (lower === "now") return { value: format(now, kind) };
+  if (lower === "today") return { value: format(kind === "date" ? now : startOfUtcDay(now), kind) };
+  if (lower === "yesterday") return { value: format(shift(kind === "date" ? now : startOfUtcDay(now), -1, "d"), kind) };
+  if (lower === "tomorrow") return { value: format(shift(kind === "date" ? now : startOfUtcDay(now), 1, "d"), kind) };
+
+  // Signed ISO 8601 duration: -P7D, +PT1H. Unsigned P7D is ambiguous.
+  const iso = /^([+-])?(P[\dYMWDTHS.]+)$/i.exec(t);
+  if (iso) {
+    const d = applyIsoDuration(now, iso[1] === "-" ? -1 : 1, iso[2]!);
+    if (!d) return null; // not a duration after all; let the API judge it
+    if (!iso[1]) return { error: "\"" + t + "\" does not say which direction. " + HINT };
+    return { value: format(d, kind) };
+  }
+
+  // Signed shorthand: -7d, +2h, -1w, -3mo, +1y. Unsigned is ambiguous.
+  const short = /^([+-])?(\d+)\s*(s|sec|seconds?|m|min|minutes?|h|hrs?|hours?|d|days?|w|wks?|weeks?|mo|months?|y|yrs?|years?)$/i.exec(t);
+  if (short) {
+    if (!short[1]) return { error: "\"" + t + "\" does not say which direction. " + HINT };
+    const unit = normalizeUnit(short[3]!);
+    return { value: format(shift(now, (short[1] === "-" ? -1 : 1) * Number(short[2]), unit), kind) };
+  }
+
+  // "7 days ago", "in 2 weeks", "2 hours from now".
+  const ago = /^(\d+)\s*(s|sec|seconds?|m|min|minutes?|h|hrs?|hours?|d|days?|w|wks?|weeks?|mo|months?|y|yrs?|years?)\s+ago$/i.exec(t);
+  if (ago) return { value: format(shift(now, -Number(ago[1]), normalizeUnit(ago[2]!)), kind) };
+  const ahead = /^(?:in\s+(\d+)\s*(s|sec|seconds?|m|min|minutes?|h|hrs?|hours?|d|days?|w|wks?|weeks?|mo|months?|y|yrs?|years?)|(\d+)\s*(s|sec|seconds?|m|min|minutes?|h|hrs?|hours?|d|days?|w|wks?|weeks?|mo|months?|y|yrs?|years?)\s+from\s+now)$/i.exec(t);
+  if (ahead) {
+    const n = Number(ahead[1] ?? ahead[3]);
+    const unit = normalizeUnit((ahead[2] ?? ahead[4])!);
+    return { value: format(shift(now, n, unit), kind) };
+  }
+  return null;
+}
+
+function normalizeUnit(raw: string): string {
+  const u = raw.toLowerCase();
+  if (u.startsWith("mo")) return "mo";
+  if (u.startsWith("y")) return "y";
+  if (u.startsWith("w")) return "w";
+  if (u.startsWith("d")) return "d";
+  if (u.startsWith("h")) return "h";
+  if (u === "m" || u.startsWith("mi")) return "m";
+  if (u.startsWith("s")) return "s";
+  return u;
+}
+
+/** The date kind a JSON Schema `format` names, or null. */
+export function dateKindOf(format: unknown): DateKind | null {
+  return format === "date" ? "date" : format === "date-time" ? "date-time" : null;
+}

package/src/errors.ts

@@ -0,0 +1,117 @@
+// typeship — typed error classes.
+// Generated by typeship — https://typeship.dev — do not edit by hand.
+
+import { ApiError, type ResponseMeta } from "./core/http.js";
+import type { ErrorModel } from "./types.js";
+
+export { ApiError, GraphQLRequestError, TransportError, UnexpectedApiError, ValidationError, type Violation, unwrap } from "./core/http.js";
+
+/**
+ * The request body, specification source, output selection, or package name is invalid.
+ * Raised for HTTP 400 responses.
+ */
+export class BadRequestError extends ApiError<400, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("The request body, specification source, output selection, or package name is invalid.", 400, body, response);
+  }
+}
+
+/**
+ * Missing, invalid, expired, or revoked credentials.
+ * Raised for HTTP 401 responses.
+ */
+export class UnauthorizedError extends ApiError<401, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("Missing, invalid, expired, or revoked credentials.", 401, body, response);
+  }
+}
+
+/**
+ * The credentials are valid but cannot act on the requested organization.
+ * Raised for HTTP 403 responses.
+ */
+export class ForbiddenError extends ApiError<403, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("The credentials are valid but cannot act on the requested organization.", 403, body, response);
+  }
+}
+
+/**
+ * Spec exceeds the 10MB limit.
+ * Raised for HTTP 413 responses.
+ */
+export class PayloadTooLargeError extends ApiError<413, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("Spec exceeds the 10MB limit.", 413, body, response);
+  }
+}
+
+/**
+ * The spec could not be understood.
+ * Raised for HTTP 422 responses.
+ */
+export class UnprocessableEntityError extends ApiError<422, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("The spec could not be understood.", 422, body, response);
+  }
+}
+
+/**
+ * Too many requests. Wait for Retry-After before retrying.
+ * Raised for HTTP 429 responses.
+ */
+export class RateLimitedError extends ApiError<429, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("Too many requests. Wait for Retry-After before retrying.", 429, body, response);
+  }
+}
+
+/**
+ * Unexpected error.
+ * Raised for "default" responses.
+ */
+export class ApiResponseError extends ApiError<number, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("Unexpected error.", response.status, body, response);
+  }
+}
+
+/**
+ * The plan does not include another project or the requested output configuration.
+ * Raised for HTTP 402 responses.
+ */
+export class PaymentRequiredError extends ApiError<402, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("The plan does not include another project or the requested output configuration.", 402, body, response);
+  }
+}
+
+/**
+ * The Idempotency-Key was already used with different request parameters.
+ * Raised for HTTP 409 responses.
+ */
+export class ConflictError extends ApiError<409, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("The Idempotency-Key was already used with different request parameters.", 409, body, response);
+  }
+}
+
+/**
+ * The original idempotent request is temporarily unavailable.
+ * Raised for HTTP 500 responses.
+ */
+export class InternalServerError extends ApiError<500, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("The original idempotent request is temporarily unavailable.", 500, body, response);
+  }
+}
+
+/**
+ * No such resource in this account.
+ * Raised for HTTP 404 responses.
+ */
+export class NotFoundError extends ApiError<404, ErrorModel> {
+  constructor(body: ErrorModel, response: ResponseMeta) {
+    super("No such resource in this account.", 404, body, response);
+  }
+}

package/src/index.ts

@@ -0,0 +1,153 @@
+// typeship — client entry point.
+// Generated by typeship — https://typeship.dev — do not edit by hand.
+
+import {
+  HttpCore,
+  formatDebugEvent,
+  type AuthValue,
+  type DebugEvent,
+  type RequestContext,
+  bearerAuth,
+} from "./core/http.js";
+import { DEFS, SCHEMAS } from "./schemas.js";
+
+import { GenerateResource } from "./resources/generate.js";
+import { ProjectsResource } from "./resources/projects.js";
+import { GenerationsResource } from "./resources/generations.js";
+import { SpecRevisionsResource } from "./resources/spec-revisions.js";
+import { AccountResource } from "./resources/account.js";
+import { ApiKeysResource } from "./resources/api-keys.js";
+
+/** This package's version, also sent as the `User-Agent`. */
+export const VERSION = "0.6.0";
+const USER_AGENT = "@typeship-ax/mcp/0.6.0 (typeship)";
+
+export interface ClientOptions {
+  /** Override the server URL. Default: `https://typeship.dev/api/v1` */
+  baseUrl?: string;
+  /**
+   * Sent as `Authorization: Bearer <token>`. Pass a callback for tokens that expire; it is resolved
+   * before every attempt.
+   */
+  bearerToken?: string | (() => string | Promise<string>);
+  /** Per-attempt timeout in milliseconds. Default: 30000. */
+  timeoutMs?: number;
+  /** Retries after the first attempt (retryable failures only). Default: 2. */
+  maxRetries?: number;
+  /** Custom fetch implementation (proxies, testing, instrumentation). */
+  fetch?: typeof fetch;
+  /** Headers sent with every request. */
+  defaultHeaders?: Record<string, string>;
+  /**
+   * Called before every attempt; mutate context.headers or context.url for logging, tracing, or
+   * custom auth.
+   */
+  onRequest?: (context: RequestContext) => void | Promise<void>;
+  /**
+   * Called after every HTTP response, before parsing and retries. Clone the response before reading
+   * its body.
+   */
+  onResponse?: (response: Response, context: RequestContext) => void | Promise<void>;
+  /**
+   * Called once per failed call, after retries, with the typed error about to be returned.
+   * Observability only.
+   */
+  onError?: (error: unknown, request: { method: string; path: string }) => void | Promise<void>;
+  /**
+   * One redacted line per attempt: true logs to console.error; a function receives the structured
+   * DebugEvent for your own logger. Also enabled by the TYPESHIP_DEBUG=1 env var. Never includes
+   * headers or bodies.
+   */
+  debug?: boolean | ((event: DebugEvent) => void);
+  /**
+   * Opt-in zero-dependency runtime validation of JSON bodies against the spec's schemas: true
+   * checks requests and responses and returns a ValidationError on mismatch (as the ApiResult
+   * error, never thrown); mode "warn" logs via console.warn and lets the call proceed. Catches spec
+   * drift the type system can't see.
+   */
+  validate?: boolean | { requests?: boolean; responses?: boolean; mode?: "throw" | "warn" };
+}
+
+/**
+ * typeship — v0.6.0
+ *
+ * Generate production SDKs, CLIs, and MCP servers from an OpenAPI or
+ * GraphQL spec, and keep every selected output current.
+ *
+ * Every operation but one requires an API key, created in the console and
+ * sent as `Authorization: Bearer ak_...`. A browser session is not a
+ * credential for this API. The exception is POST /generate, which works
+ * anonymously with the free plan's limits.
+ */
+export class TypeshipClient {
+  readonly generate: GenerateResource;
+  readonly projects: ProjectsResource;
+  readonly generations: GenerationsResource;
+  readonly specRevisions: SpecRevisionsResource;
+  readonly account: AccountResource;
+  readonly apiKeys: ApiKeysResource;
+
+  constructor(options: ClientOptions = {}) {
+    // Identifies this package to the API (ignored by browsers, which
+    // control their own User-Agent); override via defaultHeaders.
+    const headers: Record<string, AuthValue> = { "User-Agent": USER_AGENT, ...options.defaultHeaders };
+    const debugOption = options.debug
+      ?? (typeof process !== "undefined" && process.env?.["TYPESHIP_DEBUG"] === "1");
+    const debug = typeof debugOption === "function"
+      ? debugOption
+      : debugOption === true
+        ? (event: DebugEvent) => console.error(formatDebugEvent("typeship", event))
+        : undefined;
+    const query: Record<string, AuthValue> = {};
+    if (options.bearerToken !== undefined) headers["Authorization"] = bearerAuth(options.bearerToken);
+    const v = options.validate;
+    const validate = v
+      ? {
+          requests: typeof v === "object" ? v.requests !== false : true,
+          responses: typeof v === "object" ? v.responses !== false : true,
+          mode: (typeof v === "object" && v.mode) || ("throw" as const),
+        }
+      : undefined;
+    const core = new HttpCore({
+      baseUrl: options.baseUrl ?? "https://typeship.dev/api/v1",
+      headers,
+      query,
+      fetch: options.fetch ?? fetch,
+      timeoutMs: options.timeoutMs ?? 30_000,
+      maxRetries: options.maxRetries ?? 2,
+      onRequest: options.onRequest,
+      onResponse: options.onResponse,
+      onError: options.onError,
+      debug,
+      validate,
+      schemas: validate ? SCHEMAS : undefined,
+      schemaDefs: validate ? DEFS : undefined,
+    });
+    this.generate = new GenerateResource(core);
+    this.projects = new ProjectsResource(core);
+    this.generations = new GenerationsResource(core);
+    this.specRevisions = new SpecRevisionsResource(core);
+    this.account = new AccountResource(core);
+    this.apiKeys = new ApiKeysResource(core);
+  }
+}
+
+export * from "./types.js";
+export * from "./errors.js";
+export {
+  formatDebugEvent,
+  type ApiResult,
+  type AuthValue,
+  type DebugEvent,
+  type RequestContext,
+  type RequestOptions,
+  type ResponseMeta,
+} from "./core/http.js";
+export { Page, PagePromise } from "./core/pagination.js";
+
+export * from "./resources/generate.js";
+export * from "./resources/projects.js";
+export * from "./resources/generations.js";
+export * from "./resources/spec-revisions.js";
+export * from "./resources/account.js";
+export * from "./resources/api-keys.js";