@cpajs/cpa 0.0.0-stage → 0.0.1-alpha-2

package/src/client/errors.ts

@@ -0,0 +1,104 @@
+/** Base class for every error thrown by the client. */
+export class CpaClientError extends Error {
+  override readonly name: string = 'CpaClientError';
+  readonly method: string;
+  readonly url: string;
+
+  constructor(message: string, request: { method: string; url: string }, options?: { cause?: unknown }) {
+    super(message, options);
+    this.method = request.method;
+    this.url = request.url;
+  }
+}
+
+/**
+ * The server answered with a non-2xx status.
+ *
+ * `body` is the raw response text. `data` is the parsed JSON body when there
+ * was one; CPA errors usually look like `{ "error": "<code>", "message"?: "..." }`.
+ */
+export class CpaHttpError extends CpaClientError {
+  override readonly name = 'CpaHttpError';
+  readonly status: number;
+  readonly statusText: string;
+  readonly headers: Headers;
+  readonly body: string;
+  readonly data: unknown;
+
+  constructor(
+    request: { method: string; url: string },
+    response: { status: number; statusText: string; headers: Headers },
+    body: string,
+  ) {
+    const data = parseJsonOrUndefined(body);
+    const detail = describeErrorBody(data) ?? (body.trim().slice(0, 200) || response.statusText);
+    super(`${request.method} ${request.url} failed with ${response.status}${detail ? `: ${detail}` : ''}`, request);
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.headers = response.headers;
+    this.body = body;
+    this.data = data;
+  }
+
+  /** The `error` field of a CPA error body, e.g. `"not_found"` or `"invalid management key"`. */
+  get errorCode(): string | undefined {
+    const value = (this.data as { error?: unknown } | undefined)?.error;
+    return typeof value === 'string' ? value : undefined;
+  }
+
+  /** The `message` field of a CPA error body, when present. */
+  get errorMessage(): string | undefined {
+    const value = (this.data as { message?: unknown } | undefined)?.message;
+    return typeof value === 'string' ? value : undefined;
+  }
+}
+
+/** The request could not be sent or the response could not be read. */
+export class CpaNetworkError extends CpaClientError {
+  override readonly name = 'CpaNetworkError';
+}
+
+/** The request exceeded its timeout. */
+export class CpaTimeoutError extends CpaClientError {
+  override readonly name = 'CpaTimeoutError';
+  readonly timeoutMs: number;
+
+  constructor(request: { method: string; url: string }, timeoutMs: number, options?: { cause?: unknown }) {
+    super(`${request.method} ${request.url} timed out after ${timeoutMs} ms`, request, options);
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/** The caller's AbortSignal was aborted. `cause` is the signal's reason. */
+export class CpaAbortError extends CpaClientError {
+  override readonly name = 'CpaAbortError';
+}
+
+/** A 2xx response body did not match the expected format (e.g. invalid JSON). */
+export class CpaResponseError extends CpaClientError {
+  override readonly name = 'CpaResponseError';
+  readonly status: number;
+  readonly body: string;
+
+  constructor(message: string, request: { method: string; url: string }, status: number, body: string, options?: { cause?: unknown }) {
+    super(message, request, options);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function parseJsonOrUndefined(text: string): unknown {
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function describeErrorBody(data: unknown): string | undefined {
+  if (typeof data !== 'object' || data === null) return undefined;
+  const { error, message } = data as { error?: unknown; message?: unknown };
+  const parts = [error, message].filter((v): v is string => typeof v === 'string' && v !== '');
+  return parts.length ? parts.join(': ') : undefined;
+}

package/src/client/index.ts

@@ -0,0 +1,95 @@
+import { ConfigResource } from './resources/config.ts';
+import { CredentialsResource } from './resources/credentials.ts';
+import { LogsResource } from './resources/logs.ts';
+import { OAuthResource } from './resources/oauth.ts';
+import { PluginsResource } from './resources/plugins.ts';
+import { RequestsResource } from './resources/requests.ts';
+import { RoutingResource } from './resources/routing.ts';
+import { ServerResource } from './resources/server.ts';
+import { UsageResource } from './resources/usage.ts';
+import { Transport, type ClientOptions, type RawRequest, type TransportResponse } from './transport.ts';
+
+export {
+  CpaAbortError,
+  CpaClientError,
+  CpaHttpError,
+  CpaNetworkError,
+  CpaResponseError,
+  CpaTimeoutError,
+} from './errors.ts';
+export type { ClientOptions, FetchLike, Query, QueryValue, RawRequest, RequestOptions, ResponseType, TransportResponse } from './transport.ts';
+export type { ConfigPath, ConfigWriteOptions, ConfigWriteResult, Versioned } from './resources/config.ts';
+export type { CredentialContent, CredentialFile, CredentialSelector } from './resources/credentials.ts';
+export type { DownloadedFile } from './resources/download.ts';
+export type { WaitForOAuthOptions } from './resources/oauth.ts';
+export {
+  ConfigResource,
+  CredentialsResource,
+  LogsResource,
+  OAuthResource,
+  PluginsResource,
+  RequestsResource,
+  RoutingResource,
+  ServerResource,
+  UsageResource,
+};
+export type * from './types/index.ts';
+
+/** Typed client for the CLIProxyAPI v8 management API (`/v8/management`). */
+export class CpaClient {
+  readonly #transport: Transport;
+  readonly config: ConfigResource;
+  readonly credentials: CredentialsResource;
+  readonly oauth: OAuthResource;
+  readonly logs: LogsResource;
+  readonly usage: UsageResource;
+  readonly routing: RoutingResource;
+  readonly requests: RequestsResource;
+  readonly plugins: PluginsResource;
+  readonly server: ServerResource;
+
+  constructor(options: ClientOptions) {
+    this.#transport = new Transport(options);
+    this.config = new ConfigResource(this.#transport);
+    this.credentials = new CredentialsResource(this.#transport);
+    this.oauth = new OAuthResource(this.#transport);
+    this.logs = new LogsResource(this.#transport);
+    this.usage = new UsageResource(this.#transport);
+    this.routing = new RoutingResource(this.#transport);
+    this.requests = new RequestsResource(this.#transport);
+    this.plugins = new PluginsResource(this.#transport);
+    this.server = new ServerResource(this.#transport);
+  }
+
+  /** Server root URL this client talks to. */
+  get baseUrl(): URL {
+    return this.#transport.baseUrl;
+  }
+
+  /**
+   * OpenAI-compatible model API base URL (`<baseUrl>/v1`), for existing SDKs.
+   * Authenticate those requests with a model API key from `access.api-keys`,
+   * not with the management key.
+   */
+  get modelBaseUrl(): string {
+    return modelApiBaseUrl(this.#transport.baseUrl);
+  }
+
+  /** Escape hatch for routes without a typed method. `path` is relative to `/v8/management`. */
+  request<T = unknown>(request: RawRequest): Promise<TransportResponse<T>> {
+    return this.#transport.request<T>(request);
+  }
+}
+
+export function createClient(options: ClientOptions): CpaClient {
+  return new CpaClient(options);
+}
+
+/** `<baseUrl>/v1`, keeping any path prefix. */
+export function modelApiBaseUrl(baseUrl: string | URL): string {
+  const url = new URL(baseUrl);
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/v1`;
+  url.search = '';
+  url.hash = '';
+  return url.toString();
+}

package/src/client/resources/config.ts

@@ -0,0 +1,124 @@
+import type { JsonValue } from '../types/common.ts';
+import type { CpaConfig } from '../types/config.ts';
+import { encodePath, type RequestOptions, type Transport } from '../transport.ts';
+
+/** A value together with the ETag of the config file it was read from or written to. */
+export interface Versioned<T> {
+  data: T;
+  /** Strong ETag of the on-disk file. Pass it as `ifMatch` for optimistic concurrency. */
+  etag: string | undefined;
+}
+
+export interface ConfigWriteOptions extends RequestOptions {
+  /**
+   * Only write if the file still has this ETag (or `*`). A mismatch fails with
+   * a 412 `CpaHttpError` (`errorCode === 'precondition_failed'`).
+   *
+   * Writing a plaintext `management.secret-key` makes CPA rewrite the file
+   * with a bcrypt hash a few seconds later, so read again before the next
+   * conditional write.
+   */
+  ifMatch?: string | undefined;
+}
+
+export interface ConfigWriteResult {
+  status: 'ok';
+  'config-version': 8;
+}
+
+/**
+ * A config path: `'routing/retry'` or `['routing', 'retry']`. Segments are
+ * dash-case YAML keys; list indices are not addressable (lists are replaced whole).
+ */
+export type ConfigPath = string | readonly string[];
+
+function withIfMatch(options: ConfigWriteOptions): RequestOptions {
+  const { ifMatch, ...rest } = options;
+  if (ifMatch === undefined) return rest;
+  const headers = new Headers(rest.headers);
+  headers.set('If-Match', ifMatch);
+  return { ...rest, headers };
+}
+
+function nodePath(path: ConfigPath): string {
+  const encoded = encodePath(path, 'config path');
+  if (encoded === '') throw new TypeError('config path must not be empty; use the whole-document methods instead.');
+  return `/config/${encoded}`;
+}
+
+/** `/v8/management/config*`: the native configuration document. */
+export class ConfigResource {
+  readonly #t: Transport;
+
+  constructor(transport: Transport) {
+    this.#t = transport;
+  }
+
+  async #read<T>(path: string, responseType: 'json' | 'text', options: RequestOptions): Promise<Versioned<T>> {
+    const res = await this.#t.request<T>({ ...options, method: 'GET', path, responseType });
+    return { data: res.data, etag: res.headers.get('ETag') ?? undefined };
+  }
+
+  async #write(method: string, path: string, body: { json: unknown } | { yaml: string } | undefined, options: ConfigWriteOptions) {
+    const res = await this.#t.request<ConfigWriteResult>({
+      ...withIfMatch(options),
+      method,
+      path,
+      ...(body === undefined ? {} : 'json' in body ? { json: body.json } : { body: body.yaml, contentType: 'application/yaml' }),
+    });
+    return { data: res.data, etag: res.headers.get('ETag') ?? undefined } satisfies Versioned<ConfigWriteResult>;
+  }
+
+  /**
+   * The whole config as JSON, migrated to v8 in memory. TURN `username` and
+   * `credential` are removed and `auth_index` is added to API keys; writing it
+   * back is still safe. Use {@link getYaml} for a lossless copy.
+   */
+  get(options: RequestOptions = {}): Promise<Versioned<CpaConfig>> {
+    return this.#read('/config', 'json', options);
+  }
+
+  /** Replaces the whole document. Omitted sections are deleted. */
+  replace(config: CpaConfig, options: ConfigWriteOptions = {}): Promise<Versioned<ConfigWriteResult>> {
+    return this.#write('PUT', '/config', { json: config }, options);
+  }
+
+  /**
+   * Deep-merges into the document. Objects merge key by key; arrays and
+   * scalars replace. `null` is stored as null, it does not delete — use
+   * {@link delete} to remove a key.
+   */
+  patch(partial: CpaConfig, options: ConfigWriteOptions = {}): Promise<Versioned<ConfigWriteResult>> {
+    return this.#write('PATCH', '/config', { json: partial }, options);
+  }
+
+  /** The config file as YAML, with comments and without redaction. */
+  getYaml(options: RequestOptions = {}): Promise<Versioned<string>> {
+    return this.#read('/config.yaml', 'text', options);
+  }
+
+  /** Replaces the whole document with YAML (JSON is accepted too). */
+  replaceYaml(yaml: string, options: ConfigWriteOptions = {}): Promise<Versioned<ConfigWriteResult>> {
+    return this.#write('PUT', '/config.yaml', { yaml }, options);
+  }
+
+  /** Reads one node, e.g. `getPath('server/port')`. A missing node is a 404 `CpaHttpError`. */
+  getPath<T = JsonValue>(path: ConfigPath, options: RequestOptions = {}): Promise<Versioned<T>> {
+    return this.#read(nodePath(path), 'json', options);
+  }
+
+  /** Replaces or creates one node. Missing parent objects are created. */
+  set(path: ConfigPath, value: JsonValue, options: ConfigWriteOptions = {}): Promise<Versioned<ConfigWriteResult>> {
+    return this.#write('PUT', nodePath(path), { json: value }, options);
+  }
+
+  /** Deep-merges into one node (see {@link patch}). */
+  patchPath(path: ConfigPath, value: JsonValue, options: ConfigWriteOptions = {}): Promise<Versioned<ConfigWriteResult>> {
+    return this.#write('PATCH', nodePath(path), { json: value }, options);
+  }
+
+  /** Removes one node and any parents left empty. A missing node is a 404 `CpaHttpError`. */
+  delete(path: ConfigPath, options: ConfigWriteOptions = {}): Promise<Versioned<ConfigWriteResult>> {
+    return this.#write('DELETE', nodePath(path), undefined, options);
+  }
+}

package/src/client/resources/credentials.ts

@@ -0,0 +1,133 @@
+import type {
+  AuthFileEntry,
+  CoreAuth,
+  CredentialModelsResponse,
+  DeleteCredentialsResponse,
+  ForceRefreshResult,
+  ListCredentialsQuery,
+  ListCredentialsResponse,
+  PatchCredentialFieldsRequest,
+  PatchCredentialFieldsResponse,
+  PatchCredentialStatusRequest,
+  PatchCredentialStatusResponse,
+  SIWCStatusResponse,
+  UploadCredentialsResponse,
+} from '../types/credentials.ts';
+import type { RequestOptions, Transport } from '../transport.ts';
+
+/** Credential file content: a parsed JSON object, JSON text, or raw bytes. */
+export type CredentialContent = Record<string, unknown> | string | Blob | Uint8Array<ArrayBuffer> | ArrayBuffer;
+
+export interface CredentialFile {
+  /** File name in the auth directory; must end with `.json`. */
+  name: string;
+  content: CredentialContent;
+}
+
+/** Identifies a credential by auth ID / file name or by `auth_index`. */
+export type CredentialSelector = { name: string; auth_index?: string } | { auth_index: string; name?: string };
+
+function toBlob(content: CredentialContent): Blob {
+  if (content instanceof Blob) return content;
+  if (typeof content === 'string') return new Blob([content], { type: 'application/json' });
+  if (content instanceof ArrayBuffer || content instanceof Uint8Array) return new Blob([content], { type: 'application/json' });
+  return new Blob([JSON.stringify(content)], { type: 'application/json' });
+}
+
+/** `/v8/management/credentials*`: OAuth and API-key credential files. */
+export class CredentialsResource {
+  readonly #t: Transport;
+
+  constructor(transport: Transport) {
+    this.#t = transport;
+  }
+
+  /** Lists credentials. Passing `page` or `page_size` enables pagination fields in the response. */
+  async list(query: ListCredentialsQuery = {}, options: RequestOptions = {}): Promise<ListCredentialsResponse> {
+    return (await this.#t.request<ListCredentialsResponse>({ ...options, method: 'GET', path: '/credentials', query: { ...query } })).data;
+  }
+
+  /** Finds one credential by auth ID / file name, or returns undefined. */
+  async get(name: string, options: RequestOptions = {}): Promise<AuthFileEntry | undefined> {
+    const { files } = await this.list({ name }, options);
+    return files[0];
+  }
+
+  /** Uploads (or overwrites) one credential file. */
+  async upload(file: CredentialFile, options: RequestOptions = {}): Promise<UploadCredentialsResponse> {
+    const res = await this.#t.request<UploadCredentialsResponse>({
+      ...options,
+      method: 'POST',
+      path: '/credentials',
+      query: { name: file.name },
+      body: toBlob(file.content),
+      contentType: 'application/json',
+    });
+    return res.data;
+  }
+
+  /**
+   * Uploads several credential files in one multipart request. When some
+   * files fail the server answers 207 and this resolves with `status: 'partial'`.
+   */
+  async uploadMany(files: readonly CredentialFile[], options: RequestOptions = {}): Promise<UploadCredentialsResponse> {
+    if (files.length === 0) throw new TypeError('uploadMany needs at least one file.');
+    const form = new FormData();
+    for (const file of files) form.append('file', toBlob(file.content), file.name);
+    return (await this.#t.request<UploadCredentialsResponse>({ ...options, method: 'POST', path: '/credentials', body: form })).data;
+  }
+
+  /** Deletes credentials by auth ID or file name. Partial failures resolve with `status: 'partial'`. */
+  async delete(names: string | readonly string[], options: RequestOptions = {}): Promise<DeleteCredentialsResponse> {
+    const list = typeof names === 'string' ? [names] : [...names];
+    if (list.length === 0) throw new TypeError('delete needs at least one name.');
+    return (await this.#t.request<DeleteCredentialsResponse>({ ...options, method: 'DELETE', path: '/credentials', query: { name: list } }))
+      .data;
+  }
+
+  /** Deletes every `*.json` file in the auth directory. */
+  async deleteAll(options: RequestOptions = {}): Promise<{ status: 'ok'; deleted: number }> {
+    return (await this.#t.request<{ status: 'ok'; deleted: number }>({ ...options, method: 'DELETE', path: '/credentials', query: { all: 'true' } }))
+      .data;
+  }
+
+  /** Models available through one credential. */
+  async models(name: string, options: RequestOptions = {}): Promise<CredentialModelsResponse> {
+    return (await this.#t.request<CredentialModelsResponse>({ ...options, method: 'GET', path: '/credentials/models', query: { name } })).data;
+  }
+
+  /** Downloads a credential file by file name. The content includes tokens. */
+  async download(name: string, options: RequestOptions = {}): Promise<Blob> {
+    return (await this.#t.request<Blob>({ ...options, method: 'GET', path: '/credentials/download', query: { name }, responseType: 'blob' })).data;
+  }
+
+  /** Enables or disables a credential. */
+  async setStatus(request: PatchCredentialStatusRequest, options: RequestOptions = {}): Promise<PatchCredentialStatusResponse> {
+    return (await this.#t.request<PatchCredentialStatusResponse>({ ...options, method: 'PATCH', path: '/credentials/status', json: request })).data;
+  }
+
+  /**
+   * Sets metadata fields on a credential file. Keys may be dotted paths;
+   * `headers` is merged and an empty string removes a header.
+   */
+  async patchFields(request: PatchCredentialFieldsRequest, options: RequestOptions = {}): Promise<PatchCredentialFieldsResponse> {
+    return (await this.#t.request<PatchCredentialFieldsResponse>({ ...options, method: 'PATCH', path: '/credentials/fields', json: request })).data;
+  }
+
+  /** Forces a token refresh for one credential. The returned auth record contains raw tokens. */
+  async refresh(selector: CredentialSelector, options: RequestOptions = {}): Promise<{ ok: true; auth: CoreAuth }> {
+    return (await this.#t.request<{ ok: true; auth: CoreAuth }>({ ...options, method: 'POST', path: '/credentials/refresh', json: selector })).data;
+  }
+
+  /** Forces a token refresh for every enabled credential that supports it. */
+  async refreshAll(options: RequestOptions = {}): Promise<{ ok: true; results: ForceRefreshResult[] }> {
+    return (
+      await this.#t.request<{ ok: true; results: ForceRefreshResult[] }>({ ...options, method: 'POST', path: '/credentials/refresh', json: { all: true } })
+    ).data;
+  }
+
+  /** Sign in with ChatGPT binding state of a Codex credential. */
+  async siwcStatus(selector: CredentialSelector, options: RequestOptions = {}): Promise<SIWCStatusResponse> {
+    return (await this.#t.request<SIWCStatusResponse>({ ...options, method: 'GET', path: '/credentials/siwc/status', query: { ...selector } })).data;
+  }
+}

package/src/client/resources/download.ts

@@ -0,0 +1,21 @@
+/** A file returned as an attachment. */
+export interface DownloadedFile {
+  /** File name from `Content-Disposition`, when the server sent one. */
+  filename: string | undefined;
+  blob: Blob;
+}
+
+export function attachmentFilename(headers: Headers): string | undefined {
+  const disposition = headers.get('Content-Disposition');
+  if (!disposition) return undefined;
+  const star = /filename\*\s*=\s*(?:UTF-8'')?([^;]+)/i.exec(disposition);
+  if (star?.[1]) {
+    try {
+      return decodeURIComponent(star[1].trim().replace(/^"|"$/g, ''));
+    } catch {
+      // Fall through to the plain parameter.
+    }
+  }
+  const plain = /filename\s*=\s*("([^"]*)"|[^;]+)/i.exec(disposition);
+  return plain ? (plain[2] ?? plain[1]!).trim() : undefined;
+}

package/src/client/resources/logs.ts

@@ -0,0 +1,46 @@
+import type { DeleteLogsResponse, GetLogsQuery, GetLogsResponse, RequestErrorLogsResponse } from '../types/observability.ts';
+import type { RequestOptions, Transport } from '../transport.ts';
+import { attachmentFilename, type DownloadedFile } from './download.ts';
+
+/** `/v8/management/observability/logs*`. */
+export class LogsResource {
+  readonly #t: Transport;
+
+  constructor(transport: Transport) {
+    this.#t = transport;
+  }
+
+  /**
+   * Reads the main log. Requires `observability.logs.logging-to-file`.
+   * For incremental reads pass the previous `next-cursor` as `cursor`; when
+   * the response has `cursor-reset: true`, replace what you have instead of appending.
+   */
+  async get(query: GetLogsQuery = {}, options: RequestOptions = {}): Promise<GetLogsResponse> {
+    return (await this.#t.request<GetLogsResponse>({ ...options, method: 'GET', path: '/observability/logs', query: { ...query } })).data;
+  }
+
+  /** Truncates the main log and removes rotated main log files. */
+  async clear(options: RequestOptions = {}): Promise<DeleteLogsResponse> {
+    return (await this.#t.request<DeleteLogsResponse>({ ...options, method: 'DELETE', path: '/observability/logs' })).data;
+  }
+
+  /** Lists `error-*.log` request error files, newest first. */
+  async listErrorLogs(options: RequestOptions = {}): Promise<RequestErrorLogsResponse> {
+    return (await this.#t.request<RequestErrorLogsResponse>({ ...options, method: 'GET', path: '/observability/logs/errors' })).data;
+  }
+
+  /** Downloads one request error log by file name. */
+  async downloadErrorLog(name: string, options: RequestOptions = {}): Promise<DownloadedFile> {
+    return this.#download(`/observability/logs/errors/${encodeURIComponent(name)}`, options);
+  }
+
+  /** Downloads the request log for a request ID (CPA matches on its last 8 characters). */
+  async downloadRequestLog(requestId: string, options: RequestOptions = {}): Promise<DownloadedFile> {
+    return this.#download(`/observability/logs/requests/${encodeURIComponent(requestId)}`, options);
+  }
+
+  async #download(path: string, options: RequestOptions): Promise<DownloadedFile> {
+    const res = await this.#t.request<Blob>({ ...options, method: 'GET', path, responseType: 'blob' });
+    return { filename: attachmentFilename(res.headers), blob: res.data };
+  }
+}

package/src/client/resources/oauth.ts

@@ -0,0 +1,105 @@
+import type {
+  CancelOAuthSessionResponse,
+  OAuthAuthUrlRequest,
+  OAuthAuthUrlResponse,
+  OAuthCallbackRequest,
+  OAuthCallbackResponse,
+  OAuthStatusResponse,
+  SIWCBindResponse,
+  VertexImportResponse,
+} from '../types/oauth.ts';
+import type { SIWCStatusResponse } from '../types/credentials.ts';
+import type { RequestOptions, Transport } from '../transport.ts';
+import type { CredentialContent, CredentialSelector } from './credentials.ts';
+
+export interface WaitForOAuthOptions extends RequestOptions {
+  /** Poll interval. Default 2 000 ms. */
+  intervalMs?: number;
+}
+
+/** `/v8/management/oauth/*`: native login flows. */
+export class OAuthResource {
+  readonly #t: Transport;
+
+  constructor(transport: Transport) {
+    this.#t = transport;
+  }
+
+  /**
+   * Starts a login and returns the URL to open. Device flows (xai, meta, kimi)
+   * also return `user_code`. Poll {@link status} with the returned `state`.
+   */
+  async start(request: OAuthAuthUrlRequest, options: RequestOptions = {}): Promise<OAuthAuthUrlResponse> {
+    return (await this.#t.request<OAuthAuthUrlResponse>({ ...options, method: 'POST', path: '/oauth/auth-url', json: request })).data;
+  }
+
+  /** Session state: `wait` while pending, `ok` when done, `error` with a message otherwise. */
+  async status(state: string, options: RequestOptions = {}): Promise<OAuthStatusResponse> {
+    return (await this.#t.request<OAuthStatusResponse>({ ...options, method: 'GET', path: '/oauth/status', query: { state } })).data;
+  }
+
+  /** Polls {@link status} until the session leaves `wait`. Abort with `signal`. */
+  async waitForCompletion(state: string, options: WaitForOAuthOptions = {}): Promise<Exclude<OAuthStatusResponse, { status: 'wait' }>> {
+    const { intervalMs = 2_000, ...requestOptions } = options;
+    while (true) {
+      const result = await this.status(state, requestOptions);
+      if (result.status !== 'wait') return result;
+      await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(resolve, intervalMs);
+        requestOptions.signal?.addEventListener(
+          'abort',
+          () => {
+            clearTimeout(timer);
+            reject(requestOptions.signal!.reason);
+          },
+          { once: true },
+        );
+      });
+    }
+  }
+
+  /** Cancels a pending session. `cancelled` is false if it was unknown or already finished. */
+  async cancel(state: string, options: RequestOptions = {}): Promise<CancelOAuthSessionResponse> {
+    return (await this.#t.request<CancelOAuthSessionResponse>({ ...options, method: 'DELETE', path: '/oauth/session', query: { state } })).data;
+  }
+
+  /**
+   * Completes a browser flow by handing over the final redirect URL (or
+   * `state` + `code`). Useful when the provider's loopback callback cannot
+   * reach the server. This route does not require the management key.
+   */
+  async callback(request: OAuthCallbackRequest, options: RequestOptions = {}): Promise<OAuthCallbackResponse> {
+    return (await this.#t.request<OAuthCallbackResponse>({ ...options, method: 'POST', path: '/oauth/callback', json: request, anonymous: true }))
+      .data;
+  }
+
+  /** Imports a Google Cloud service account key as a Vertex credential. */
+  async importVertex(
+    input: { serviceAccount: CredentialContent; location?: string; fileName?: string },
+    options: RequestOptions = {},
+  ): Promise<VertexImportResponse> {
+    const form = new FormData();
+    const content = input.serviceAccount;
+    const blob =
+      content instanceof Blob
+        ? content
+        : new Blob([typeof content === 'string' || content instanceof ArrayBuffer || content instanceof Uint8Array ? content : JSON.stringify(content)], {
+            type: 'application/json',
+          });
+    form.append('file', blob, input.fileName ?? 'service-account.json');
+    if (input.location !== undefined) form.append('location', input.location);
+    return (
+      await this.#t.request<VertexImportResponse>({ ...options, method: 'POST', path: '/oauth/import', query: { provider: 'vertex' }, body: form })
+    ).data;
+  }
+
+  /** Starts binding Sign in with ChatGPT to a file-backed Codex OAuth credential. */
+  async siwcBind(name: string, options: RequestOptions = {}): Promise<SIWCBindResponse> {
+    return (await this.#t.request<SIWCBindResponse>({ ...options, method: 'POST', path: '/oauth/siwc/bind', json: { name } })).data;
+  }
+
+  /** Same as `credentials.siwcStatus`, via the oauth route. */
+  async siwcStatus(selector: CredentialSelector, options: RequestOptions = {}): Promise<SIWCStatusResponse> {
+    return (await this.#t.request<SIWCStatusResponse>({ ...options, method: 'GET', path: '/oauth/siwc/status', query: { ...selector } })).data;
+  }
+}