@typeship-ax/cli 0.6.0 → 0.9.1

package/src/polling-login.ts

@@ -0,0 +1,165 @@
+import { createHash, randomBytes } from "node:crypto";
+import { oauthJsonRequest, oauthDeviceRequest, OAuthResponseError } from "./oauth-request.js";
+
+export class LoginPollingError extends Error {
+  constructor(readonly code: "cancelled" | "expired" | "denied" | "invalid_response" | "request_failed") {
+    super({ cancelled: "Login was cancelled.", expired: "Login expired. Run login again and approve the new request.", denied: "Login was denied. Run login again if you want to retry.", invalid_response: "The login service returned an invalid response. Check its configuration.", request_failed: "The login request failed. Check the service and start a new login." }[code]);
+    this.name = "LoginPollingError";
+  }
+}
+
+export function loginEndpoint(value: string): URL {
+  try {
+    if (typeof value !== "string" || /[\x00-\x20\x7f]/.test(value)) throw new Error();
+    const url = new URL(value);
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && local)) || url.username || url.password || url.hash) throw new Error();
+    return url;
+  } catch { throw new LoginPollingError("invalid_response"); }
+}
+function text(value: unknown, limit = 65_536): value is string {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= limit && !/[\x00-\x1f\x7f]/.test(value);
+}
+function seconds(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && Number.isSafeInteger(Math.ceil(value * 1000));
+}
+function interval(value: unknown, fallback: number): number {
+  if (value === undefined) return fallback * 1000;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || !Number.isSafeInteger(Math.ceil(value * 1000))) throw new LoginPollingError("invalid_response");
+  return Math.max(1, value) * 1000;
+}
+function lifetime(signal: AbortSignal | undefined, timeoutMs: number, maximum: number) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > maximum) throw new LoginPollingError("invalid_response");
+  const controller = new AbortController();
+  let expired = false;
+  const cancel = () => controller.abort();
+  const timer = setTimeout(() => { expired = true; controller.abort(); }, timeoutMs);
+  signal?.addEventListener("abort", cancel, { once: true });
+  if (signal?.aborted) cancel();
+  const check = () => { if (controller.signal.aborted) throw new LoginPollingError(expired ? "expired" : "cancelled"); };
+  return { signal: controller.signal, check, close() { clearTimeout(timer); signal?.removeEventListener("abort", cancel); } };
+}
+async function pause(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) throw new LoginPollingError("cancelled");
+  await new Promise<void>((resolve, reject) => {
+    const done = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); resolve(); };
+    const abort = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); reject(new LoginPollingError("cancelled")); };
+    const timer = setTimeout(done, Math.min(ms, 2_147_483_647));
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+const form = (params: Record<string, string>, signal: AbortSignal): RequestInit => ({ method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" }, body: new URLSearchParams(params), signal });
+
+export interface DeviceLoginConfig {
+  clientId: string; issuer?: string | null; discoveryUrls: string[];
+  deviceUrl?: string | null; tokenUrl?: string | null;
+  scopes: string[]; audience?: string; resource?: string;
+}
+export interface DeviceLoginSession {
+  accessToken: string; refreshToken?: string; expiresAt?: number;
+  tokenUrl: string; issuer?: string; clientId: string; revocationUrl?: string; scopes?: string[];
+}
+
+/** RFC 8628: pending and slow_down are the only responses that keep polling.
+ * All deadlines include response bodies; cancellation also interrupts waits. */
+export async function oauthDeviceLogin(config: DeviceLoginConfig, interaction: {
+  authorize(value: { verificationUri: string; userCode: string; expiresIn: number }): void;
+  signal?: AbortSignal; timeoutMs?: number;
+}): Promise<DeviceLoginSession> {
+  const flow = lifetime(interaction.signal, interaction.timeoutMs ?? 900_000, 900_000);
+  try {
+    flow.check();
+    if (!text(config.clientId)) throw new LoginPollingError("invalid_response");
+    if (config.issuer && loginEndpoint(config.issuer).search) throw new LoginPollingError("invalid_response");
+    let deviceUrl = config.deviceUrl ? loginEndpoint(config.deviceUrl).href : undefined;
+    let tokenUrl = config.tokenUrl ? loginEndpoint(config.tokenUrl).href : undefined;
+    let revocationUrl: string | undefined;
+    for (const url of config.discoveryUrls) {
+      if (deviceUrl && tokenUrl) break;
+      const response = await oauthJsonRequest(loginEndpoint(url), { headers: { Accept: "application/json" }, signal: flow.signal }, 10_000);
+      if (response.status !== 200) continue;
+      const data = response.data!;
+      if (config.issuer && data.issuer !== config.issuer) throw new LoginPollingError("invalid_response");
+      if (!deviceUrl && typeof data.device_authorization_endpoint === "string") deviceUrl = loginEndpoint(data.device_authorization_endpoint).href;
+      if (!tokenUrl && typeof data.token_endpoint === "string") tokenUrl = loginEndpoint(data.token_endpoint).href;
+      if (data.revocation_endpoint !== undefined) revocationUrl = loginEndpoint(data.revocation_endpoint as string).href;
+    }
+    if (!deviceUrl || !tokenUrl) throw new LoginPollingError("invalid_response");
+    const params = { ...(config.audience ? { audience: config.audience } : {}), ...(config.resource ? { resource: config.resource } : {}) };
+    const start = await oauthJsonRequest(deviceUrl, form({ client_id: config.clientId, ...(config.scopes.length ? { scope: config.scopes.join(" ") } : {}), ...params }, flow.signal));
+    const data = start.data;
+    if (start.status !== 200) throw new LoginPollingError("request_failed");
+    if (!data || !text(data.device_code) || !text(data.user_code, 512) || !text(data.verification_uri, 8192) || !seconds(data.expires_in)) throw new LoginPollingError("invalid_response");
+    loginEndpoint(data.verification_uri);
+    const verificationUri = loginEndpoint((data.verification_uri_complete ?? data.verification_uri) as string).href;
+    let intervalMs = interval(data.interval, 5);
+    const expiresIn = Math.min(data.expires_in, 900), deadline = Date.now() + expiresIn * 1000;
+    interaction.authorize({ verificationUri, userCode: data.user_code, expiresIn });
+    while (true) {
+      await pause(Math.min(intervalMs, Math.max(0, deadline - Date.now())), flow.signal);
+      flow.check();
+      if (Date.now() >= deadline) throw new LoginPollingError("expired");
+      let response: Awaited<ReturnType<typeof oauthDeviceRequest>>;
+      try { response = await oauthDeviceRequest(tokenUrl, form({ ...params, grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: data.device_code, client_id: config.clientId }, flow.signal), Math.min(30_000, deadline - Date.now())); }
+      catch (error) {
+        flow.check();
+        if (error instanceof OAuthResponseError && error.code === "timed_out") { intervalMs *= 2; continue; }
+        throw error;
+      }
+      flow.check();
+      if (Date.now() >= deadline) throw new LoginPollingError("expired");
+      if (response.status === 400 && response.error === "authorization_pending") continue;
+      if (response.status === 400 && response.error === "slow_down") { intervalMs += 5000; continue; }
+      if (response.status === 400 && response.error === "access_denied") throw new LoginPollingError("denied");
+      if (response.status === 400 && response.error === "expired_token") throw new LoginPollingError("expired");
+      if (response.status !== 200) throw new LoginPollingError("request_failed");
+      const token = response.data!;
+      if (!text(token.access_token) || typeof token.token_type !== "string" || token.token_type.toLowerCase() !== "bearer" || token.error !== undefined || token.refresh_token !== undefined && !text(token.refresh_token) || token.expires_in !== undefined && !seconds(token.expires_in) || token.scope !== undefined && typeof token.scope !== "string") throw new LoginPollingError("invalid_response");
+      return { accessToken: token.access_token, ...(typeof token.refresh_token === "string" ? { refreshToken: token.refresh_token } : {}), ...(typeof token.expires_in === "number" ? { expiresAt: Date.now() + token.expires_in * 1000 } : {}), clientId: config.clientId, tokenUrl, ...(config.issuer ? { issuer: config.issuer } : {}), ...(revocationUrl ? { revocationUrl } : {}), ...(typeof token.scope === "string" ? { scopes: token.scope.split(/\s+/).filter(Boolean) } : {}) };
+    }
+  } catch (error) { flow.check(); throw error; }
+  finally { flow.close(); }
+}
+
+export interface ApprovedCredential { api_key: string; key_name: string; org_id?: string; revocationUrl: string }
+
+/** This is the owner's custom approval contract, not an OAuth grant. A failed
+ * poll is not replayed: its one-use credential may already have been consumed. */
+export async function customBrowserApproval(config: { authUrl: string; name: string; source: "agent" | "cli" }, interaction: {
+  authorize(value: { verificationUrl: string; expiresIn: number }): void;
+  signal?: AbortSignal; timeoutMs?: number;
+}): Promise<ApprovedCredential> {
+  const flow = lifetime(interaction.signal, interaction.timeoutMs ?? 600_000, 600_000);
+  try {
+    flow.check();
+    const base = loginEndpoint(config.authUrl);
+    if (base.search) throw new LoginPollingError("invalid_response");
+    const url = base.href.replace(/\/$/, "");
+    const verifier = randomBytes(32).toString("base64url"), challenge = createHash("sha256").update(verifier).digest("base64url");
+    const post = (body: unknown): RequestInit => ({ method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json" }, body: JSON.stringify(body), signal: flow.signal });
+    const response = await oauthJsonRequest(url + "/start", post({ code_challenge: challenge, name: config.name, source: config.source }), 15_000);
+    if (response.status !== 200) throw new LoginPollingError("request_failed");
+    const start = response.data!;
+    if (!text(start.session) || !text(start.verification_url, 8192) || start.expires_in !== undefined && !seconds(start.expires_in)) throw new LoginPollingError("invalid_response");
+    const verificationUrl = loginEndpoint(start.verification_url).href;
+    const expiresIn = Math.min(typeof start.expires_in === "number" ? start.expires_in : 600, 600);
+    const intervalMs = interval(start.interval, 3), deadline = Date.now() + expiresIn * 1000;
+    interaction.authorize({ verificationUrl, expiresIn });
+    while (true) {
+      await pause(Math.min(intervalMs, Math.max(0, deadline - Date.now())), flow.signal);
+      flow.check();
+      if (Date.now() >= deadline) throw new LoginPollingError("expired");
+      const result = await oauthJsonRequest(url + "/status", post({ session: start.session, code_verifier: verifier }), Math.min(15_000, deadline - Date.now()));
+      flow.check();
+      if (Date.now() >= deadline) throw new LoginPollingError("expired");
+      if (result.status !== 200) throw new LoginPollingError("request_failed");
+      const poll = result.data!;
+      if (poll.status === "pending") continue;
+      if (poll.status === "denied") throw new LoginPollingError("denied");
+      if (poll.status === "expired") throw new LoginPollingError("expired");
+      if (poll.status !== "complete" || !text(poll.api_key) || poll.key_name !== undefined && !text(poll.key_name, 1024) || poll.org_id !== undefined && !text(poll.org_id, 1024)) throw new LoginPollingError("invalid_response");
+      return { api_key: poll.api_key, key_name: typeof poll.key_name === "string" ? poll.key_name : config.name, ...(typeof poll.org_id === "string" ? { org_id: poll.org_id } : {}), revocationUrl: url + "/revoke" };
+    }
+  } catch (error) { flow.check(); throw error; }
+  finally { flow.close(); }
+}

package/src/resources/account.ts

@@ -3,6 +3,7 @@
 
 import { HttpCore, type ApiResult, type RequestOptions } from "../core/http.js";
 import {
+  ResponseParseError,
   TransportError,
   UnexpectedApiError,
   ValidationError,
@@ -10,7 +11,7 @@ import {
   RateLimitedError,
   UnauthorizedError,
 } from "../errors.js";
-import type { Account } from "../types.js";
+import type { Account, AccountRead } from "../types.js";
 
 export class AccountResource {
   constructor(private readonly _core: HttpCore) {}
@@ -21,10 +22,11 @@ export class AccountResource {
    * identity endpoint the generated typeship CLI's `whoami` calls.
    * `GET /me`
    */
-  async retrieve(options?: RequestOptions): Promise<ApiResult<Account, AccountRetrieveError>> {
-    return this._core.request<Account, AccountRetrieveError>({
+  async retrieve(options?: RequestOptions): Promise<ApiResult<AccountRead, AccountRetrieveError>> {
+    return this._core.request<AccountRead, AccountRetrieveError>({
       method: "GET",
       path: "/me",
+      security: [{"apiKey":[]}],
       errors: { "401": UnauthorizedError, "403": ForbiddenError, "429": RateLimitedError },
       idempotent: true,
       schemaKey: "account.retrieve",
@@ -39,5 +41,6 @@ export type AccountRetrieveError =
   | ForbiddenError
   | RateLimitedError
   | UnexpectedApiError
+  | ResponseParseError
   | TransportError
   | ValidationError;

package/src/resources/api-keys.ts

@@ -4,6 +4,7 @@
 import { HttpCore, type ApiResult, type RequestOptions } from "../core/http.js";
 import { paginate, PagePromise } from "../core/pagination.js";
 import {
+  ResponseParseError,
   TransportError,
   UnexpectedApiError,
   ValidationError,
@@ -13,7 +14,14 @@ import {
   RateLimitedError,
   UnauthorizedError,
 } from "../errors.js";
-import type { ApiKey, ApiKeyList } from "../types.js";
+import type {
+  ApiKey,
+  ApiKeyList,
+  ApiKeyListRead,
+  ApiKeyRead,
+  ApiKeyResponse,
+  ApiKeyResponseRead,
+} from "../types.js";
 
 export class ApiKeysResource {
   constructor(private readonly _core: HttpCore) {}
@@ -26,10 +34,11 @@ export class ApiKeysResource {
    * Auto-paginates: `for await (const item of …)` walks every page.
    * `GET /api_keys`
    */
-  list(params?: ApiKeysListParams, options?: RequestOptions): PagePromise<ApiKey, ApiKeysListError> {
-    return paginate<ApiKey, ApiKeysListError>(this._core, {
+  list(params?: ApiKeysListParams, options?: RequestOptions): PagePromise<ApiKeyRead, ApiKeysListError> {
+    return paginate<ApiKeyRead, ApiKeysListError>(this._core, {
       method: "GET",
       path: "/api_keys",
+      security: [{"apiKey":[]}],
       query: {
         limit: params?.limit,
         cursor: params?.cursor,
@@ -57,13 +66,19 @@ export class ApiKeysResource {
    * Revoke an API key
    *
    * Idempotent: revoking an already-revoked key returns the same body, so a rotation script that
-   * re-runs does not have to special-case having already succeeded.
+   * re-runs does not have to special-case having already succeeded. An OAuth member may revoke a
+   * key they created; an organization admin may revoke any key. Organization API keys retain
+   * account-wide authority.
    * `DELETE /api_keys/{api_key_id}`
    */
-  async revoke(apiKeyId: string, options?: RequestOptions): Promise<ApiResult<ApiKey, ApiKeysRevokeError>> {
-    return this._core.request<ApiKey, ApiKeysRevokeError>({
+  async revoke(
+    apiKeyId: string,
+    options?: RequestOptions,
+  ): Promise<ApiResult<ApiKeyResponseRead, ApiKeysRevokeError>> {
+    return this._core.request<ApiKeyResponseRead, ApiKeysRevokeError>({
       method: "DELETE",
       path: `/api_keys/${encodeURIComponent(String(apiKeyId))}`,
+      security: [{"apiKey":[]}],
       errors: {
         "401": UnauthorizedError,
         "403": ForbiddenError,
@@ -80,7 +95,10 @@ export class ApiKeysResource {
 export interface ApiKeysListParams {
   /** Maximum number of resources to return. */
   limit?: number;
-  /** Opaque cursor from the preceding page's next_cursor. */
+  /**
+   * Opaque cursor from the preceding page's next_cursor. Valid only for the same account,
+   * operation, filters, and ordering that issued it.
+   */
   cursor?: string;
 }
 
@@ -91,6 +109,7 @@ export type ApiKeysListError =
   | ForbiddenError
   | RateLimitedError
   | UnexpectedApiError
+  | ResponseParseError
   | TransportError
   | ValidationError;
 
@@ -101,5 +120,6 @@ export type ApiKeysRevokeError =
   | NotFoundError
   | RateLimitedError
   | UnexpectedApiError
+  | ResponseParseError
   | TransportError
   | ValidationError;

package/src/resources/definition-revisions.ts

@@ -0,0 +1,207 @@
+// typeship — definitionRevisions resource.
+// Generated by typeship — https://typeship.dev — do not edit by hand.
+
+import { HttpCore, type ApiResult, type RequestOptions } from "../core/http.js";
+import { paginate, PagePromise } from "../core/pagination.js";
+import {
+  ResponseParseError,
+  TransportError,
+  UnexpectedApiError,
+  ValidationError,
+  BadRequestError,
+  ForbiddenError,
+  NotFoundError,
+  RateLimitedError,
+  UnauthorizedError,
+} from "../errors.js";
+import type {
+  DefinitionDocumentId,
+  DefinitionId,
+  DefinitionRevision,
+  DefinitionRevisionId,
+  DefinitionRevisionList,
+  DefinitionRevisionListRead,
+  DefinitionRevisionRead,
+  DefinitionRevisionResponse,
+  DefinitionRevisionResponseRead,
+} from "../types.js";
+
+export class DefinitionRevisionsResource {
+  constructor(private readonly _core: HttpCore) {}
+  /**
+   * List Definition Revisions
+   *
+   * Immutable snapshots of the complete resolved document graph this Definition observed, newest
+   * first. Content is available from the revision and document endpoints and is never embedded in a
+   * list response.
+   *
+   * Auto-paginates: `for await (const item of …)` walks every page.
+   * `GET /definitions/{definition_id}/revisions`
+   */
+  list(
+    definitionId: DefinitionId,
+    params?: DefinitionRevisionsListParams,
+    options?: RequestOptions,
+  ): PagePromise<DefinitionRevisionRead, DefinitionRevisionsListError> {
+    return paginate<DefinitionRevisionRead, DefinitionRevisionsListError>(this._core, {
+      method: "GET",
+      path: `/definitions/${encodeURIComponent(String(definitionId))}/revisions`,
+      security: [{"apiKey":[]}],
+      query: {
+        limit: params?.limit,
+        cursor: params?.cursor,
+      },
+      errors: {
+        "400": BadRequestError,
+        "401": UnauthorizedError,
+        "403": ForbiddenError,
+        "404": NotFoundError,
+        "429": RateLimitedError,
+      },
+      idempotent: true,
+      schemaKey: "definitionRevisions.list",
+      options,
+    }, {
+      style: "cursor",
+      itemsField: "data",
+      cursorParam: "cursor",
+      nextCursorField: "next_cursor",
+      hasMoreField: "has_more",
+      limitParam: "limit",
+    });
+  }
+
+  /**
+   * Retrieve a Definition Revision
+   *
+   * Metadata for one immutable resolved document graph. Fetch its canonical content or individual
+   * source documents from the content endpoints.
+   * `GET /definition_revisions/{definition_revision_id}`
+   */
+  async retrieve(
+    definitionRevisionId: DefinitionRevisionId,
+    options?: RequestOptions,
+  ): Promise<ApiResult<DefinitionRevisionResponseRead, DefinitionRevisionsRetrieveError>> {
+    return this._core.request<DefinitionRevisionResponseRead, DefinitionRevisionsRetrieveError>({
+      method: "GET",
+      path: `/definition_revisions/${encodeURIComponent(String(definitionRevisionId))}`,
+      security: [{"apiKey":[]}],
+      errors: {
+        "401": UnauthorizedError,
+        "403": ForbiddenError,
+        "404": NotFoundError,
+        "429": RateLimitedError,
+      },
+      idempotent: true,
+      schemaKey: "definitionRevisions.retrieve",
+      options,
+    });
+  }
+
+  /**
+   * Retrieve a Definition Revision's canonical content
+   *
+   * Returns the exact canonical resolved content identified by the revision's graph digest,
+   * suitable for saving or piping into a diff.
+   * `GET /definition_revisions/{definition_revision_id}/content`
+   */
+  async retrieveContent(
+    definitionRevisionId: DefinitionRevisionId,
+    options?: RequestOptions,
+  ): Promise<ApiResult<string, DefinitionRevisionsRetrieveContentError>> {
+    return this._core.request<string, DefinitionRevisionsRetrieveContentError>({
+      method: "GET",
+      path: `/definition_revisions/${encodeURIComponent(String(definitionRevisionId))}/content`,
+      security: [{"apiKey":[]}],
+      errors: {
+        "401": UnauthorizedError,
+        "403": ForbiddenError,
+        "404": NotFoundError,
+        "429": RateLimitedError,
+      },
+      idempotent: true,
+      schemaKey: "definitionRevisions.retrieveContent",
+      options,
+    });
+  }
+
+  /**
+   * Retrieve one source document from a Definition Revision
+   * `GET /definition_revisions/{definition_revision_id}/documents/{document_id}/content`
+   */
+  async retrieveDocumentContent(
+    definitionRevisionId: DefinitionRevisionId,
+    documentId: DefinitionDocumentId,
+    options?: RequestOptions,
+  ): Promise<ApiResult<string, DefinitionRevisionsRetrieveDocumentContentError>> {
+    return this._core.request<string, DefinitionRevisionsRetrieveDocumentContentError>({
+      method: "GET",
+      path: `/definition_revisions/${encodeURIComponent(String(definitionRevisionId))}/documents/${encodeURIComponent(String(documentId))}/content`,
+      security: [{"apiKey":[]}],
+      errors: {
+        "401": UnauthorizedError,
+        "403": ForbiddenError,
+        "404": NotFoundError,
+        "429": RateLimitedError,
+      },
+      idempotent: true,
+      schemaKey: "definitionRevisions.retrieveDocumentContent",
+      options,
+    });
+  }
+}
+
+export interface DefinitionRevisionsListParams {
+  /** Maximum number of resources to return. */
+  limit?: number;
+  /**
+   * Opaque cursor from the preceding page's next_cursor. Valid only for the same account,
+   * operation, filters, and ordering that issued it.
+   */
+  cursor?: string;
+}
+
+/** Every error `list` can produce, as a discriminated union. */
+export type DefinitionRevisionsListError =
+  | BadRequestError
+  | UnauthorizedError
+  | ForbiddenError
+  | NotFoundError
+  | RateLimitedError
+  | UnexpectedApiError
+  | ResponseParseError
+  | TransportError
+  | ValidationError;
+
+/** Every error `retrieve` can produce, as a discriminated union. */
+export type DefinitionRevisionsRetrieveError =
+  | UnauthorizedError
+  | ForbiddenError
+  | NotFoundError
+  | RateLimitedError
+  | UnexpectedApiError
+  | ResponseParseError
+  | TransportError
+  | ValidationError;
+
+/** Every error `retrieveContent` can produce, as a discriminated union. */
+export type DefinitionRevisionsRetrieveContentError =
+  | UnauthorizedError
+  | ForbiddenError
+  | NotFoundError
+  | RateLimitedError
+  | UnexpectedApiError
+  | ResponseParseError
+  | TransportError
+  | ValidationError;
+
+/** Every error `retrieveDocumentContent` can produce, as a discriminated union. */
+export type DefinitionRevisionsRetrieveDocumentContentError =
+  | UnauthorizedError
+  | ForbiddenError
+  | NotFoundError
+  | RateLimitedError
+  | UnexpectedApiError
+  | ResponseParseError
+  | TransportError
+  | ValidationError;

package/src/resources/definitions.ts

@@ -0,0 +1,122 @@
+// typeship — definitions resource.
+// Generated by typeship — https://typeship.dev — do not edit by hand.
+
+import { HttpCore, type ApiResult, type RequestOptions } from "../core/http.js";
+import {
+  ResponseParseError,
+  TransportError,
+  UnexpectedApiError,
+  ValidationError,
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  NotFoundError,
+  RateLimitedError,
+  UnauthorizedError,
+  UnprocessableEntityError,
+} from "../errors.js";
+import type {
+  Definition,
+  DefinitionId,
+  DefinitionRead,
+  DefinitionUpdateRequest,
+} from "../types.js";
+
+export class DefinitionsResource {
+  constructor(private readonly _core: HttpCore) {}
+  /**
+   * Retrieve a Definition
+   * `GET /definitions/{definition_id}`
+   */
+  async retrieve(
+    definitionId: DefinitionId,
+    options?: RequestOptions,
+  ): Promise<ApiResult<DefinitionRead, DefinitionsRetrieveError>> {
+    return this._core.request<DefinitionRead, DefinitionsRetrieveError>({
+      method: "GET",
+      path: `/definitions/${encodeURIComponent(String(definitionId))}`,
+      security: [{"apiKey":[]}],
+      errors: {
+        "401": UnauthorizedError,
+        "403": ForbiddenError,
+        "404": NotFoundError,
+        "429": RateLimitedError,
+      },
+      idempotent: true,
+      schemaKey: "definitions.retrieve",
+      options,
+    });
+  }
+
+  /**
+   * Update and resolve a Definition
+   *
+   * Resolves the complete document graph and records a new immutable revision before saving.
+   *
+   * A `Idempotency-Key` UUID is generated per call (stable across retries) unless you pass one.
+   * `PATCH /definitions/{definition_id}`
+   */
+  async update(
+    definitionId: DefinitionId,
+    body: DefinitionUpdateRequest,
+    params?: DefinitionsUpdateParams,
+    options?: RequestOptions,
+  ): Promise<ApiResult<DefinitionRead, DefinitionsUpdateError>> {
+    return this._core.request<DefinitionRead, DefinitionsUpdateError>({
+      method: "PATCH",
+      path: `/definitions/${encodeURIComponent(String(definitionId))}`,
+      security: [{"apiKey":[]}],
+      headers: {
+        "Idempotency-Key": params?.idempotencyKey === undefined ? undefined : String(params?.idempotencyKey),
+      },
+      body,
+      errors: {
+        "400": BadRequestError,
+        "401": UnauthorizedError,
+        "403": ForbiddenError,
+        "404": NotFoundError,
+        "409": ConflictError,
+        "422": UnprocessableEntityError,
+        "429": RateLimitedError,
+      },
+      idempotencyKey: "Idempotency-Key",
+      schemaKey: "definitions.update",
+      options,
+    });
+  }
+}
+
+/** Every error `retrieve` can produce, as a discriminated union. */
+export type DefinitionsRetrieveError =
+  | UnauthorizedError
+  | ForbiddenError
+  | NotFoundError
+  | RateLimitedError
+  | UnexpectedApiError
+  | ResponseParseError
+  | TransportError
+  | ValidationError;
+
+export interface DefinitionsUpdateParams {
+  /**
+   * Identifies one logical write for 24 hours. The key is scoped to the authenticated account and
+   * operation; account-less generation uses a hashed network identity. Retrying the same method,
+   * path, query, and JSON body replays the original response. Reusing the key with changed intent
+   * returns 409. After expiry the key starts a new write.
+   */
+  idempotencyKey?: string;
+}
+
+/** Every error `update` can produce, as a discriminated union. */
+export type DefinitionsUpdateError =
+  | BadRequestError
+  | UnauthorizedError
+  | ForbiddenError
+  | NotFoundError
+  | ConflictError
+  | UnprocessableEntityError
+  | RateLimitedError
+  | UnexpectedApiError
+  | ResponseParseError
+  | TransportError
+  | ValidationError;