@typeship-ax/mcp 0.10.0 → 0.20.0

package/src/core/http.ts

@@ -1,6 +1,6 @@
 /**
  * Runtime core. Generated by typeship — https://typeship.dev
- * Zero dependencies: built on the platform fetch API (Node 18+, browsers, edge).
+ * Zero dependencies: built on the platform fetch API (Node 20+, browsers, edge).
  */
 
 export interface RequestOptions {
@@ -19,7 +19,7 @@ export interface ResponseMeta {
   headers: Headers;
   /** Parsed wire body before it is narrowed to the generated response type.
    * Use this escape hatch for additive fields or variants introduced after
-   * this generator edition. */
+   * this generator version. */
   rawBody?: unknown;
   /** Request identifier from the JSON response body, or from headers for
    * raw and bodyless responses. */
@@ -43,11 +43,7 @@ export interface RequestContext {
 }
 
 
-/**
- * Every SDK call returns a discriminated result instead of throwing.
- * Narrow on `ok` and the error side is a typed union of the documented
- * error responses for that exact operation.
- */
+/** Internal result used by CLI and MCP consumers of the shared core. */
 export type ApiResult<T, E> =
   | { ok: true; data: T; response: ResponseMeta }
   | { ok: false; error: E; response?: ResponseMeta };
@@ -59,15 +55,80 @@ export function unwrap<T, E>(result: ApiResult<T, E>): T {
   throw new Error(String(result.error));
 }
 
+/** Adapter for generated CLI and MCP entry points that consume result objects. */
+export async function asApiResult<T>(call: PromiseLike<T>): Promise<{ ok: boolean; data?: T; error?: unknown; response?: ResponseMeta }> {
+  try {
+    const data = await call;
+    const pageResponse = data && typeof data === "object" && "response" in data
+      ? (data as { response?: ResponseMeta }).response : undefined;
+    const response = pageResponse ?? {
+      status: 0,
+      headers: new Headers(),
+      rawBody: data,
+      requestId: requestIdFromBody(data),
+    };
+    return { ok: true, data, response };
+  } catch (error) {
+    const response = error && typeof error === "object" && "response" in error
+      ? (error as { response?: ResponseMeta }).response : undefined;
+    return { ok: false, error, response };
+  }
+}
+
+/** Common fields on every failure. A missing response has status null. */
+export class SdkError extends Error {
+  readonly code: string;
+  readonly status: number | null;
+  readonly requestId?: string;
+  readonly body: unknown;
+
+  constructor(message: string, code: string, status: number | null = null, body?: unknown, requestId?: string) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.status = status;
+    this.body = body;
+    this.requestId = requestId;
+  }
+}
+
+function errorCode(body: unknown, fallback: string): string {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    const value = body as Record<string, unknown>;
+    const first = Array.isArray(value.errors) ? value.errors[0] as { code?: unknown } | undefined : undefined;
+    const code = value.code ?? first?.code;
+    if (typeof code === "string" && code.trim()) return code;
+  }
+  return fallback;
+}
+
+function errorDetail(body: unknown): string {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return "";
+  const value = body as Record<string, unknown>;
+  const first = Array.isArray(value.errors) ? value.errors[0] as { message?: unknown } | undefined : undefined;
+  const detail = value.message ?? value.error ?? value.detail ?? first?.message;
+  return typeof detail === "string" && detail.trim() ? ": " + detail : "";
+}
+
+function nextStep(status: number): string {
+  if (status === 401) return "Check the credential and retry.";
+  if (status === 403) return "Check the credential's permissions and retry.";
+  if (status === 404) return "Check the requested identifier or path.";
+  if (status === 409) return "Refresh the resource and retry the change.";
+  if (status === 422 || status === 400) return "Correct the request and retry.";
+  if (status === 429) return "Wait before retrying the request.";
+  if (status >= 500) return "Retry later; contact the API provider if this continues.";
+  return "Inspect the error body and correct the request before retrying.";
+}
+
 /** Base class for every HTTP error response. */
-export class ApiError<S extends number = number, B = unknown> extends Error {
+export class ApiError<S extends number = number, B = unknown> extends SdkError {
   readonly status: S;
   readonly body: B;
   readonly response: ResponseMeta;
 
   constructor(message: string, status: S, body: B, response: ResponseMeta) {
-    super(message);
-    this.name = new.target.name;
+    super(message + errorDetail(body) + ". " + nextStep(status), errorCode(body, "http_" + status), status, body, response.requestId);
     this.status = status;
     this.body = body;
     this.response = response;
@@ -82,15 +143,14 @@ export class UnexpectedApiError extends ApiError<number, unknown> {
 }
 
 /** A successful response declared JSON but carried a body that could not be parsed. */
-export class ResponseParseError extends Error {
+export class ResponseParseError extends SdkError {
   readonly status: number;
   readonly body: string;
   readonly response: ResponseMeta;
   override readonly cause?: unknown;
 
   constructor(body: string, response: ResponseMeta, cause?: unknown) {
-    super("HTTP " + response.status + " response body was not valid JSON");
-    this.name = "ResponseParseError";
+    super("HTTP " + response.status + " response body was not valid JSON. Check the API response or contact its provider.", "response_parse_error", response.status, body, response.requestId);
     this.status = response.status;
     this.body = body;
     this.response = response;
@@ -105,18 +165,18 @@ export class ResponseParseError extends Error {
 
 export interface Violation { path: string; message: string }
 
-/** Request or response data did not match the spec's schema (opt-in via the
- * client's validate option). Never thrown: returned as the error side of
- * ApiResult, like every other failure. */
-export class ValidationError extends Error {
+/** Request or response data did not match the spec's schema. */
+export class ValidationError extends SdkError {
   readonly direction: "request" | "response";
+  readonly target: "body" | "parameters";
   readonly violations: Violation[];
-  constructor(direction: "request" | "response", violations: Violation[]) {
+  constructor(direction: "request" | "response", violations: Violation[], target: "body" | "parameters" = "body") {
     const shown = violations.slice(0, 3).map((v) => v.path + " " + v.message).join("; ");
-    super(direction + " body failed schema validation: " + shown
-      + (violations.length > 3 ? " (+" + (violations.length - 3) + " more)" : ""));
-    this.name = "ValidationError";
+    super(direction + " " + target + " failed schema validation: " + shown
+      + (violations.length > 3 ? " (+" + (violations.length - 3) + " more)" : "")
+      + ". Correct the " + (direction === "request" ? "request" : "API response or update the spec") + ".", "validation_error");
     this.direction = direction;
+    this.target = target;
     this.violations = violations;
   }
 }
@@ -153,7 +213,16 @@ export function validateAgainstSchema(value: unknown, schema: unknown, path: str
 
   if (Array.isArray(s.allOf)) for (const sub of s.allOf) validateAgainstSchema(value, sub, path, out, defs);
   const variants = s.anyOf ?? s.oneOf;
-  if (Array.isArray(variants) && variants.length > 0) {
+  const discriminator = s.responseDiscriminator;
+  const tag = typeof discriminator?.propertyName === "string" && value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)[discriminator.propertyName] : undefined;
+  if (typeof tag === "string") {
+    if (Object.hasOwn(discriminator.mapping, tag)) {
+      validateAgainstSchema(value, discriminator.mapping[tag], path, out, defs);
+    }
+    // Unknown variants remain raw data. Callers must handle their tag before
+    // interpreting fields or taking an action based on workflow state.
+  } else if (Array.isArray(variants) && variants.length > 0) {
     const matched = variants.some((sub: unknown) => {
       const scratch: Violation[] = [];
       validateAgainstSchema(value, sub, path, scratch, defs);
@@ -240,13 +309,14 @@ function transportFailureMessage(method: string, url: string, cause: unknown): s
 }
 
 /** The request failed before a complete HTTP response arrived (network failure, timeout, abort, or truncated body). */
-export class TransportError extends Error {
+export class TransportError extends SdkError {
   override readonly cause?: unknown;
+  readonly response?: ResponseMeta;
 
-  constructor(message: string, cause?: unknown) {
-    super(message);
-    this.name = "TransportError";
+  constructor(message: string, cause?: unknown, response?: ResponseMeta) {
+    super(message + ". Check the connection and retry.", "transport_error", response?.status ?? null, undefined, response?.requestId);
     this.cause = cause;
+    this.response = response;
   }
 }
 
@@ -510,6 +580,7 @@ export class HttpCore {
           const error = (parseError ?? new TransportError(
             "The response body read failed before completing",
             cause,
+            meta(response),
           )) as unknown as E;
           await this.config.onError?.(error, { method: req.method, path: req.path });
           return { ok: false, error, response: parseError?.response ?? meta(response) };
@@ -556,8 +627,8 @@ export class HttpCore {
       let body: unknown;
       try {
         body = await parseBody(response, req.method);
-      } catch {
-        body = undefined; // error responses keep their status even if the body read aborts
+      } catch (cause) {
+        body = cause instanceof ResponseParseError ? cause.body : undefined;
       }
       emitResponseDebug(response, body);
       const responseMeta = meta(response, body);
@@ -578,6 +649,11 @@ export class HttpCore {
     return { ok: false, error };
   }
 
+  /** SDK-facing call: resolve to the payload or throw its typed error. */
+  async requestData<T, E>(req: CoreRequest): Promise<T> {
+    return unwrap(await this.request<T, E>(req));
+  }
+
   private async send(
     req: CoreRequest,
     timeoutMs: number,
@@ -806,8 +882,8 @@ function meta(response: Response, body?: unknown): ResponseMeta {
   };
 }
 
-/** AbortSignal.any reached Node in 18.17. Keep the package's Node 18 floor
- * honest for earlier 18.x releases and for web runtimes without it. */
+/** AbortSignal.any is missing from some web and edge runtimes; compose the
+ * signals by hand there. */
 function composeSignals(signals: AbortSignal[]): AbortSignal {
   const nativeAny = (AbortSignal as typeof AbortSignal & { any?: (items: AbortSignal[]) => AbortSignal }).any;
   if (nativeAny) return nativeAny.call(AbortSignal, signals);

package/src/core/pagination.ts

@@ -1,13 +1,12 @@
 /**
  * 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.
+ * List operations return a PagePromise: `await` it for one page, or
+ * `for await` it to stream every item across every page.
  */
 
 import {
   HttpCore,
-  type ApiResult,
   type CoreRequest,
   type ResponseMeta,
 } from "./http.js";
@@ -29,7 +28,7 @@ export interface PageConfig {
 
 type FetchPage<Item, E> = (
   query: Record<string, unknown>,
-) => Promise<ApiResult<Page<Item, E>, E>>;
+) => Promise<Page<Item, E>>;
 
 export class Page<Item, E = unknown> {
   private readonly fetchPage: FetchPage<Item, E>;
@@ -85,11 +84,7 @@ export class Page<Item, E = unknown> {
   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;
+    return this.fetchPage(next);
   }
 
   /** Iterate every item on this page and all following pages. */
@@ -114,28 +109,24 @@ export class Page<Item, E = unknown> {
 }
 
 /**
- * Awaitable (one page, as a typed ApiResult) and async-iterable (all items,
+ * Awaitable (one page) 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>>) {
+export class PagePromise<Item, E> implements PromiseLike<Page<Item, E>>, AsyncIterable<Item> {
+  private readonly first: Promise<Page<Item, E>>;
+  constructor(first: Promise<Page<Item, E>>) {
     this.first = first;
   }
 
-  then<R1 = ApiResult<Page<Item, E>, E>, R2 = never>(
-    onfulfilled?: ((value: ApiResult<Page<Item, E>, E>) => R1 | PromiseLike<R1>) | null,
+  then<R1 = Page<Item, E>, R2 = never>(
+    onfulfilled?: ((value: Page<Item, 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;
+    yield* await this.first;
   }
 }
 
@@ -149,9 +140,8 @@ export function paginate<Item, E>(
   const fetchPage: FetchPage<Item, E> = async (params) => {
     let nextReq: CoreRequest = { ...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 };
+    if (!result.ok) throw result.error instanceof Error ? result.error : new Error(String(result.error));
+    return new Page<Item, E>(fetchPage, config, params, result.data, result.response);
   };
   const initial: Record<string, unknown> = {};
   let seed = req.query ?? {};

package/src/errors.ts

@@ -1,18 +1,18 @@
 // typeship — typed error classes.
-// Generated by typeship — https://typeship.dev — do not edit by hand.
+// Generated by typeship — https://typeship.dev
 
 import { ApiError, type ResponseMeta } from "./core/http.js";
 import type { ErrorModel, ErrorModelRead } from "./types.js";
 
-export { ApiError, ResponseParseError, TransportError, UnexpectedApiError, ValidationError, type Violation, unwrap } from "./core/http.js";
+export { ApiError, SdkError, ResponseParseError, TransportError, UnexpectedApiError, ValidationError, type Violation } from "./core/http.js";
 
 /**
- * The request body, Definition source, target selection, or package name is invalid.
+ * The request body, Spec source, target selection, or package name is invalid.
  * Raised for HTTP 400 responses.
  */
 export class BadRequestError extends ApiError<400, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The request body, Definition source, target selection, or package name is invalid.", 400, body, response);
+    super("The request body, Spec source, target selection, or package name is invalid.", 400, body, response);
   }
 }
 
@@ -57,12 +57,12 @@ export class PayloadTooLargeError extends ApiError<413, ErrorModelRead> {
 }
 
 /**
- * The Definition could not be resolved or understood.
+ * The Spec could not be resolved or understood.
  * Raised for HTTP 422 responses.
  */
 export class UnprocessableEntityError extends ApiError<422, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The Definition could not be resolved or understood.", 422, body, response);
+    super("The Spec could not be resolved or understood.", 422, body, response);
   }
 }
 
@@ -77,6 +77,16 @@ export class RateLimitedError extends ApiError<429, ErrorModelRead> {
   }
 }
 
+/**
+ * An unexpected error prevented the request from completing.
+ * Raised for HTTP 500 responses.
+ */
+export class InternalServerError extends ApiError<500, ErrorModelRead> {
+  constructor(body: ErrorModelRead, response: ResponseMeta) {
+    super("An unexpected error prevented the request from completing.", 500, body, response);
+  }
+}
+
 /**
  * Unexpected error.
  * Raised for "default" responses.
@@ -88,41 +98,41 @@ export class ApiResponseError extends ApiError<number, ErrorModelRead> {
 }
 
 /**
- * The plan does not include another project or the requested target configuration.
- * Raised for HTTP 402 responses.
+ * No such resource in this organization.
+ * Raised for HTTP 404 responses.
  */
-export class PaymentRequiredError extends ApiError<402, ErrorModelRead> {
+export class NotFoundError extends ApiError<404, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The plan does not include another project or the requested target configuration.", 402, body, response);
+    super("No such resource in this organization.", 404, body, response);
   }
 }
 
 /**
- * Project setup failed unexpectedly; the key reservation is released.
- * Raised for HTTP 500 responses.
+ * The plan does not include another project or the requested target configuration.
+ * Raised for HTTP 402 responses.
  */
-export class InternalServerError extends ApiError<500, ErrorModelRead> {
+export class PaymentRequiredError extends ApiError<402, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("Project setup failed unexpectedly; the key reservation is released.", 500, body, response);
+    super("The plan does not include another project or the requested target configuration.", 402, body, response);
   }
 }
 
 /**
- * No such resource in this account.
- * Raised for HTTP 404 responses.
+ * The resource changed since the ETag supplied in If-Match. No write was applied.
+ * Raised for HTTP 412 responses.
  */
-export class NotFoundError extends ApiError<404, ErrorModelRead> {
+export class PreconditionFailedError extends ApiError<412, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("No such resource in this account.", 404, body, response);
+    super("The resource changed since the ETag supplied in If-Match. No write was applied.", 412, body, response);
   }
 }
 
 /**
- * The Project was saved, but an obsolete release pull request could not be retired.
+ * Dependent work failed while completing the request.
  * Raised for HTTP 502 responses.
  */
 export class BadGatewayError extends ApiError<502, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The Project was saved, but an obsolete release pull request could not be retired.", 502, body, response);
+    super("Dependent work failed while completing the request.", 502, body, response);
   }
 }

package/src/index.ts

@@ -1,5 +1,5 @@
 // typeship — client entry point.
-// Generated by typeship — https://typeship.dev — do not edit by hand.
+// Generated by typeship — https://typeship.dev
 
 import {
   HttpCore,
@@ -14,16 +14,21 @@ import { DEFS, SCHEMAS } from "./schemas.js";
 
 import { GenerateResource } from "./resources/generate.js";
 import { ProjectsResource } from "./resources/projects.js";
-import { DefinitionsResource } from "./resources/definitions.js";
+import { SpecsResource } from "./resources/specs.js";
+import { SpecRevisionsResource } from "./resources/spec-revisions.js";
 import { TargetsResource } from "./resources/targets.js";
+import { DraftsResource } from "./resources/drafts.js";
+import { ReleasesResource } from "./resources/releases.js";
+import { DeliveriesResource } from "./resources/deliveries.js";
+import { PublicationsResource } from "./resources/publications.js";
 import { GenerationsResource } from "./resources/generations.js";
-import { DefinitionRevisionsResource } from "./resources/definition-revisions.js";
-import { AccountResource } from "./resources/account.js";
+import { FilesResource } from "./resources/files.js";
+import { OrganizationResource } from "./resources/organization.js";
 import { ApiKeysResource } from "./resources/api-keys.js";
 
 /** This package's version, also sent as the `User-Agent`. */
-export const VERSION = "0.10.0";
-const USER_AGENT = "@typeship-ax/mcp/0.10.0 (typeship)";
+export const VERSION = "0.20.0";
+const USER_AGENT = "@typeship-ax/mcp/0.20.0";
 
 export interface ClientOptions {
   /** Override the server URL. Default: `https://typeship.dev/api/v1` */
@@ -34,8 +39,8 @@ export interface ClientOptions {
    */
   bearerToken?: string | (() => string | Promise<string>);
   /**
-   * Credentials keyed by the Definition's security scheme names. Only one complete alternative is
-   * sent for each operation. Named values take precedence over convenience options.
+   * Credentials keyed by the Spec's security scheme names. Only one complete alternative is sent
+   * for each operation. Named values take precedence over convenience options.
    */
   credentials?: {
     "apiKey"?: AuthValue;
@@ -71,18 +76,17 @@ export interface ClientOptions {
   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.
+   * checks requests and responses and throws ValidationError on mismatch; 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.10.0
+ * typeship — v0.20.0
  *
- * Resolve an OpenAPI or GraphQL Definition, diagnose it, and keep every
- * selected SDK, CLI, and MCP Target current.
+ * Resolve an OpenAPI or GraphQL Spec, diagnose it, and keep every
+ * selected CLI, MCP, and SDK Target current.
  *
  * Every operation but one requires a bearer credential: an organization
  * API key from the console, or an OAuth access token carrying the operation's
@@ -90,15 +94,24 @@ export interface ClientOptions {
  * consent. OAuth grants cannot switch organizations after consent. A browser
  * session is not a credential for this API. The exception is POST /generate,
  * which works anonymously with the free plan's limits.
+ *
+ * Examples use Parcel, a fictional delivery service. Replace its domains,
+ * repository names, and resource identifiers with your own. The hosted
+ * petstore Spec is a runnable sample.
  */
 export class TypeshipClient {
   readonly generate: GenerateResource;
   readonly projects: ProjectsResource;
-  readonly definitions: DefinitionsResource;
+  readonly specs: SpecsResource;
+  readonly specRevisions: SpecRevisionsResource;
   readonly targets: TargetsResource;
+  readonly drafts: DraftsResource;
+  readonly releases: ReleasesResource;
+  readonly deliveries: DeliveriesResource;
+  readonly publications: PublicationsResource;
   readonly generations: GenerationsResource;
-  readonly definitionRevisions: DefinitionRevisionsResource;
-  readonly account: AccountResource;
+  readonly files: FilesResource;
+  readonly organization: OrganizationResource;
   readonly apiKeys: ApiKeysResource;
 
   constructor(options: ClientOptions = {}) {
@@ -156,11 +169,16 @@ export class TypeshipClient {
     });
     this.generate = new GenerateResource(core);
     this.projects = new ProjectsResource(core);
-    this.definitions = new DefinitionsResource(core);
+    this.specs = new SpecsResource(core);
+    this.specRevisions = new SpecRevisionsResource(core);
     this.targets = new TargetsResource(core);
+    this.drafts = new DraftsResource(core);
+    this.releases = new ReleasesResource(core);
+    this.deliveries = new DeliveriesResource(core);
+    this.publications = new PublicationsResource(core);
     this.generations = new GenerationsResource(core);
-    this.definitionRevisions = new DefinitionRevisionsResource(core);
-    this.account = new AccountResource(core);
+    this.files = new FilesResource(core);
+    this.organization = new OrganizationResource(core);
     this.apiKeys = new ApiKeysResource(core);
   }
 }
@@ -169,7 +187,6 @@ export * from "./types.js";
 export * from "./errors.js";
 export {
   formatDebugEvent,
-  type ApiResult,
   type AuthValue,
   type DebugEvent,
   type RequestContext,
@@ -180,9 +197,14 @@ export { Page, PagePromise } from "./core/pagination.js";
 
 export * from "./resources/generate.js";
 export * from "./resources/projects.js";
-export * from "./resources/definitions.js";
+export * from "./resources/specs.js";
+export * from "./resources/spec-revisions.js";
 export * from "./resources/targets.js";
+export * from "./resources/drafts.js";
+export * from "./resources/releases.js";
+export * from "./resources/deliveries.js";
+export * from "./resources/publications.js";
 export * from "./resources/generations.js";
-export * from "./resources/definition-revisions.js";
-export * from "./resources/account.js";
+export * from "./resources/files.js";
+export * from "./resources/organization.js";
 export * from "./resources/api-keys.js";