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

package/src/client/resources/plugins.ts

@@ -0,0 +1,70 @@
+import type {
+  DeletePluginResponse,
+  PluginInstallQuery,
+  PluginInstallResponse,
+  PluginListResponse,
+  PluginQuotaResetResponse,
+  PluginStoreListResponse,
+  QuotaFetchResponse,
+} from '../types/plugins.ts';
+import type { RequestOptions, Transport } from '../transport.ts';
+
+/** `/v8/management/plugins*`. */
+export class PluginsResource {
+  readonly #t: Transport;
+
+  constructor(transport: Transport) {
+    this.#t = transport;
+  }
+
+  async list(options: RequestOptions = {}): Promise<PluginListResponse> {
+    return (await this.#t.request<PluginListResponse>({ ...options, method: 'GET', path: '/plugins' })).data;
+  }
+
+  /** Deletes the plugin file and its `plugins.configs` entry. */
+  async delete(id: string, options: RequestOptions = {}): Promise<DeletePluginResponse> {
+    return (await this.#t.request<DeletePluginResponse>({ ...options, method: 'DELETE', path: `/plugins/${encodeURIComponent(id)}` })).data;
+  }
+
+  /** Lists plugins from every store source (network access on the server). */
+  async store(options: RequestOptions = {}): Promise<PluginStoreListResponse> {
+    return (await this.#t.request<PluginStoreListResponse>({ ...options, method: 'GET', path: '/plugins/store' })).data;
+  }
+
+  /**
+   * Installs a store plugin by plugin id (not `store_id`) and enables it.
+   * The global `plugins.enabled` switch is left unchanged.
+   */
+  async install(id: string, query: PluginInstallQuery = {}, options: RequestOptions = {}): Promise<PluginInstallResponse> {
+    return (
+      await this.#t.request<PluginInstallResponse>({
+        ...options,
+        method: 'POST',
+        path: `/plugins/store/${encodeURIComponent(id)}/install`,
+        query: { ...query },
+      })
+    ).data;
+  }
+
+  /**
+   * Fetches quota for a credential from the plugin's quota provider.
+   * (`POST /plugins/:id/quota` runs the same handler and is not exposed separately.)
+   */
+  async quota(id: string, authIndex: string, options: RequestOptions = {}): Promise<QuotaFetchResponse> {
+    return (
+      await this.#t.request<QuotaFetchResponse>({ ...options, method: 'GET', path: `/plugins/${encodeURIComponent(id)}/quota`, query: { auth_index: authIndex } })
+    ).data;
+  }
+
+  /** Resets plugin quota state for a credential, then its routing cooldown. */
+  async resetQuota(id: string, authIndex: string, options: RequestOptions = {}): Promise<PluginQuotaResetResponse> {
+    return (
+      await this.#t.request<PluginQuotaResetResponse>({
+        ...options,
+        method: 'DELETE',
+        path: `/plugins/${encodeURIComponent(id)}/quota`,
+        query: { auth_index: authIndex },
+      })
+    ).data;
+  }
+}

package/src/client/resources/requests.ts

@@ -0,0 +1,20 @@
+import type { ApiCallRequest, ApiCallResponse } from '../types/requests.ts';
+import type { RequestOptions, Transport } from '../transport.ts';
+
+/** `/v8/management/requests/*`. */
+export class RequestsResource {
+  readonly #t: Transport;
+
+  constructor(transport: Transport) {
+    this.#t = transport;
+  }
+
+  /**
+   * Makes an HTTP request from the server, optionally with a credential's
+   * proxy and token (`$TOKEN$` in headers or `data`). Resolves whenever the
+   * upstream call completed, whatever its status; check `status_code`.
+   */
+  async apiCall(request: ApiCallRequest, options: RequestOptions = {}): Promise<ApiCallResponse> {
+    return (await this.#t.request<ApiCallResponse>({ ...options, method: 'POST', path: '/requests/api-call', json: request })).data;
+  }
+}

package/src/client/resources/routing.ts

@@ -0,0 +1,29 @@
+import type { CooldownResetResponse, ModelDefinitionsResponse, StaticModelChannel } from '../types/routing.ts';
+import type { RequestOptions, Transport } from '../transport.ts';
+
+/** `/v8/management/routing/*`. */
+export class RoutingResource {
+  readonly #t: Transport;
+
+  constructor(transport: Transport) {
+    this.#t = transport;
+  }
+
+  /** Clears quota and cooldown state for one credential. */
+  async resetCooldown(authIndex: string, options: RequestOptions = {}): Promise<CooldownResetResponse> {
+    return (
+      await this.#t.request<CooldownResetResponse>({ ...options, method: 'POST', path: '/routing/cooldown/reset', json: { auth_index: authIndex } })
+    ).data;
+  }
+
+  /** Built-in model definitions for a channel (or a plugin provider). */
+  async modelDefinitions(channel: StaticModelChannel | (string & {}), options: RequestOptions = {}): Promise<ModelDefinitionsResponse> {
+    return (
+      await this.#t.request<ModelDefinitionsResponse>({
+        ...options,
+        method: 'GET',
+        path: `/routing/model-definitions/${encodeURIComponent(channel)}`,
+      })
+    ).data;
+  }
+}

package/src/client/resources/server.ts

@@ -0,0 +1,52 @@
+import { CpaHttpError } from '../errors.ts';
+import type { HealthzResponse, LatestVersionResponse, ServerInfo } from '../types/server.ts';
+import type { RequestOptions, Transport } from '../transport.ts';
+
+function readInfo(headers: Headers): ServerInfo | undefined {
+  const version = headers.get('X-CPA-VERSION');
+  if (version === null) return undefined;
+  return {
+    version,
+    commit: headers.get('X-CPA-COMMIT') ?? '',
+    buildDate: headers.get('X-CPA-BUILD-DATE') ?? '',
+    supportPlugin: headers.get('X-CPA-SUPPORT-PLUGIN') === '1',
+  };
+}
+
+/** Server information: `/healthz`, version headers and `/v8/management/server/*`. */
+export class ServerResource {
+  readonly #t: Transport;
+
+  constructor(transport: Transport) {
+    this.#t = transport;
+  }
+
+  /** `GET /healthz` (no management key needed). */
+  async health(options: RequestOptions = {}): Promise<HealthzResponse> {
+    return (await this.#t.request<HealthzResponse>({ ...options, method: 'GET', path: '/healthz', root: true, anonymous: true })).data;
+  }
+
+  /**
+   * Version, commit, build date and plugin support of the running server,
+   * read from the `X-CPA-*` headers of a cheap authenticated request.
+   */
+  async info(options: RequestOptions = {}): Promise<ServerInfo> {
+    let headers: Headers;
+    try {
+      headers = (await this.#t.request<unknown>({ ...options, method: 'GET', path: '/config/config-version' })).headers;
+    } catch (error) {
+      // A config without `config-version` answers 404, which still carries the headers.
+      if (!(error instanceof CpaHttpError) || error.status !== 404) throw error;
+      headers = error.headers;
+    }
+    const info = readInfo(headers);
+    if (!info) throw new TypeError('The server did not send X-CPA-VERSION; is management enabled?');
+    return info;
+  }
+
+  /** Latest CLIProxyAPI release tag on GitHub (e.g. `"v8.0.43"`), fetched by the server. */
+  async latestVersion(options: RequestOptions = {}): Promise<string> {
+    const res = await this.#t.request<LatestVersionResponse>({ ...options, method: 'GET', path: '/server/latest-version' });
+    return res.data['latest-version'];
+  }
+}

package/src/client/resources/usage.ts

@@ -0,0 +1,27 @@
+import type { ApiKeyUsageResponse, UsageQueueResponse } from '../types/observability.ts';
+import type { RequestOptions, Transport } from '../transport.ts';
+
+/** `/v8/management/observability/usage/*`. */
+export class UsageResource {
+  readonly #t: Transport;
+
+  constructor(transport: Transport) {
+    this.#t = transport;
+  }
+
+  /** Request counters per config API key. Map keys are `"<base-url>|<api-key>"` with the raw key. */
+  async apiKeys(options: RequestOptions = {}): Promise<ApiKeyUsageResponse> {
+    return (await this.#t.request<ApiKeyUsageResponse>({ ...options, method: 'GET', path: '/observability/usage/api-keys' })).data;
+  }
+
+  /**
+   * Removes and returns up to `count` (default 1) of the oldest queued usage
+   * records. Destructive: concurrent consumers split the records between them.
+   * Records are only queued while `observability.usage.usage-statistics-enabled` is on.
+   */
+  async popQueue(count?: number, options: RequestOptions = {}): Promise<UsageQueueResponse> {
+    return (
+      await this.#t.request<UsageQueueResponse>({ ...options, method: 'GET', path: '/observability/usage/queue', query: { count } })
+    ).data;
+  }
+}

package/src/client/transport.ts

@@ -0,0 +1,215 @@
+import { CpaAbortError, CpaHttpError, CpaNetworkError, CpaResponseError, CpaTimeoutError } from './errors.ts';
+
+export const MANAGEMENT_PREFIX = '/v8/management';
+
+export type FetchLike = (input: Request) => Promise<Response>;
+
+export type QueryValue = string | number | boolean | null | undefined | readonly (string | number | boolean)[];
+export type Query = Readonly<Record<string, QueryValue>>;
+
+export interface ClientOptions {
+  /**
+   * Server root, e.g. `http://127.0.0.1:8317` or `https://example.com/cpa`.
+   * A path prefix (reverse proxy) is kept; `/v8/management` is appended to it.
+   */
+  baseUrl: string | URL;
+  /** Management key (`management.secret-key` or `MANAGEMENT_PASSWORD`), not a model API key. */
+  managementKey: string;
+  /** Custom fetch. Defaults to the global `fetch`. */
+  fetch?: (input: Request) => Promise<Response>;
+  /** Headers sent with every request. */
+  headers?: HeadersInit;
+  /** Default per-request timeout in ms. `0` or omitted disables it. */
+  timeoutMs?: number;
+}
+
+/** Per-call options accepted by every client method. */
+export interface RequestOptions {
+  signal?: AbortSignal | undefined;
+  /** Overrides the client's default timeout; `0` disables it. */
+  timeoutMs?: number | undefined;
+  headers?: HeadersInit | undefined;
+}
+
+export type ResponseType = 'json' | 'text' | 'blob' | 'response';
+
+export interface RawRequest extends RequestOptions {
+  method: string;
+  /** Path below `/v8/management` (e.g. `/config`), already encoded. */
+  path: string;
+  query?: Query;
+  /** Serialised with `JSON.stringify`, including strings and `null`. */
+  json?: unknown;
+  /** Sent as-is. Mutually exclusive with `json`. */
+  body?: BodyInit;
+  /** Content type for `body`. FormData sets its own. */
+  contentType?: string;
+  responseType?: ResponseType;
+  /** Skip the management key, for unauthenticated routes. */
+  anonymous?: boolean;
+  /** Resolve `path` against the server root instead of `/v8/management`. */
+  root?: boolean;
+}
+
+export interface TransportResponse<T> {
+  data: T;
+  status: number;
+  headers: Headers;
+}
+
+function appendQuery(url: URL, query: Query | undefined): void {
+  if (!query) return;
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) for (const item of value) url.searchParams.append(key, String(item));
+    else url.searchParams.append(key, String(value));
+  }
+}
+
+/** Joins the base URL and a management path while keeping any base path prefix. */
+export function managementUrl(baseUrl: string | URL, path: string, root = false): URL {
+  const base = new URL(baseUrl);
+  const prefix = base.pathname.replace(/\/+$/, '');
+  const url = new URL(base.origin);
+  url.pathname = `${prefix}${root ? '' : MANAGEMENT_PREFIX}${path}`;
+  return url;
+}
+
+export class Transport {
+  readonly #baseUrl: URL;
+  readonly #managementKey: string;
+  readonly #fetch: FetchLike;
+  readonly #headers: Headers;
+  readonly #timeoutMs: number;
+
+  constructor(options: ClientOptions) {
+    if (!options.baseUrl) throw new TypeError('baseUrl is required.');
+    if (!options.managementKey) throw new TypeError('managementKey is required.');
+    this.#baseUrl = new URL(options.baseUrl);
+    if (this.#baseUrl.protocol !== 'http:' && this.#baseUrl.protocol !== 'https:') {
+      throw new TypeError(`baseUrl must be http(s), got ${this.#baseUrl.protocol}`);
+    }
+    this.#managementKey = options.managementKey;
+    const custom = options.fetch;
+    this.#fetch = custom ? (request) => custom(request) : (request) => fetch(request);
+    this.#headers = new Headers(options.headers);
+    this.#timeoutMs = options.timeoutMs ?? 0;
+  }
+
+  get baseUrl(): URL {
+    return new URL(this.#baseUrl);
+  }
+
+  async request<T>(req: RawRequest): Promise<TransportResponse<T>> {
+    const url = managementUrl(this.#baseUrl, req.path, req.root);
+    appendQuery(url, req.query);
+    const target = { method: req.method, url: url.toString() };
+
+    const headers = new Headers(this.#headers);
+    new Headers(req.headers).forEach((value, key) => headers.set(key, value));
+    if (!req.anonymous) headers.set('Authorization', `Bearer ${this.#managementKey}`);
+
+    let body: BodyInit | undefined;
+    if ('json' in req) {
+      body = JSON.stringify(req.json);
+      headers.set('Content-Type', 'application/json');
+    } else if (req.body !== undefined) {
+      body = req.body;
+      if (req.contentType) headers.set('Content-Type', req.contentType);
+    }
+    if (!headers.has('Accept')) headers.set('Accept', req.responseType === 'json' || !req.responseType ? 'application/json' : '*/*');
+
+    const timeoutMs = req.timeoutMs ?? this.#timeoutMs;
+    const userSignal = req.signal;
+    let timedOut = false;
+    const classify = (error: unknown): Error => {
+      if (userSignal?.aborted) return new CpaAbortError(`${target.method} ${target.url} was aborted`, target, { cause: userSignal.reason });
+      if (timedOut) return new CpaTimeoutError(target, timeoutMs, { cause: error });
+      return new CpaNetworkError(`${target.method} ${target.url} failed: ${(error as Error)?.message ?? String(error)}`, target, {
+        cause: error,
+      });
+    };
+    if (userSignal?.aborted) throw classify(userSignal.reason);
+
+    // One controller owned by this call, rather than AbortSignal.any/timeout: on some Node
+    // versions signals derived that way can be garbage-collected before they fire.
+    const controller = new AbortController();
+    let rejectAborted: (error: Error) => void = () => {};
+    const aborted = new Promise<never>((_, reject) => {
+      rejectAborted = reject;
+    });
+    aborted.catch(() => {});
+    const abort = (reason: unknown): void => {
+      controller.abort(reason);
+      rejectAborted(classify(reason));
+    };
+    const onUserAbort = (): void => abort(userSignal!.reason);
+    userSignal?.addEventListener('abort', onUserAbort, { once: true });
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        abort(new DOMException(`Timed out after ${timeoutMs} ms`, 'TimeoutError'));
+      }, timeoutMs);
+    }
+    const release = (): void => {
+      clearTimeout(timer);
+      userSignal?.removeEventListener('abort', onUserAbort);
+    };
+    // Every await below races the abort, so a fetch that ignores its signal still settles.
+    const guard = <V>(promise: Promise<V>): Promise<V> => Promise.race([promise, aborted]);
+
+    const init: RequestInit = { method: req.method, headers, redirect: 'manual', signal: controller.signal };
+    if (body !== undefined) init.body = body;
+
+    const responseType = req.responseType ?? 'json';
+    try {
+      let response: Response;
+      try {
+        response = await guard(this.#fetch(new Request(url, init)));
+      } catch (error) {
+        throw error instanceof CpaAbortError || error instanceof CpaTimeoutError ? error : classify(error);
+      }
+
+      if (!response.ok) {
+        throw new CpaHttpError(target, response, await guard(response.text()));
+      }
+      if (responseType === 'response') {
+        return { data: response as T, status: response.status, headers: response.headers };
+      }
+      if (responseType === 'blob') {
+        return { data: (await guard(response.blob())) as T, status: response.status, headers: response.headers };
+      }
+      const text = await guard(response.text());
+      if (responseType === 'text') return { data: text as T, status: response.status, headers: response.headers };
+      if (text === '') return { data: undefined as T, status: response.status, headers: response.headers };
+      try {
+        return { data: JSON.parse(text) as T, status: response.status, headers: response.headers };
+      } catch (cause) {
+        throw new CpaResponseError(`${target.method} ${target.url} returned invalid JSON`, target, response.status, text, { cause });
+      }
+    } catch (error) {
+      if (error instanceof CpaHttpError || error instanceof CpaResponseError || error instanceof CpaAbortError || error instanceof CpaTimeoutError) {
+        throw error;
+      }
+      throw classify(error);
+    } finally {
+      // For `response`, the caller reads the body; the timeout covers the headers only,
+      // while the caller's own signal keeps working through the request's signal.
+      if (responseType === 'response') clearTimeout(timer);
+      else release();
+    }
+  }
+}
+
+/** Encodes `a/b/c` or `['a', 'b', 'c']` as URL path segments. */
+export function encodePath(path: string | readonly string[], what = 'path'): string {
+  const segments = typeof path === 'string' ? path.split('/').filter((s, i, all) => s !== '' || (i > 0 && i < all.length - 1)) : [...path];
+  for (const segment of segments) {
+    if (segment === '') throw new TypeError(`${what} contains an empty segment.`);
+    if (typeof path !== 'string' && segment.includes('/')) {
+      throw new TypeError(`${what} segment "${segment}" contains "/", which CPA cannot address; edit its parent instead.`);
+    }
+  }
+  return segments.map(encodeURIComponent).join('/');
+}

package/src/client/types/common.ts

@@ -0,0 +1,38 @@
+// Shared response types.
+// Derived from CLIProxyAPI v8.0.43; see docs/api-coverage.md.
+
+export interface StatusErrorBody { status: 'error'; error: string }
+export interface OkStatus { status: 'ok' }
+
+export type AuthStatus = 'unknown' | 'active' | 'pending' | 'refreshing' | 'error' | 'disabled';
+export type SIWCStatus = 'off' | 'valid' | 'invalid';
+export type CooldownReason =
+  | 'credential_quota' | 'quota' | 'cloudflare_challenge' | 'model_not_supported'
+  | 'invalid_grant' | 'unauthorized' | 'payment_required' | 'not_found'
+  | 'transient_error' | 'unknown';
+
+/** Any JSON value. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** Ten-minute request bucket; `time` is `"HH:MM-HH:MM"` in the server's local time. */
+export interface RecentRequestBucket { time: string; success: number; failed: number }
+
+export interface PartialFailure { name: string; error: string }
+
+/** Error body from the auth middleware and most ops handlers. */
+export interface CpaSimpleError { error: string }
+/** Error body from latest-version, plugins, plugin store, plugin delete. */
+export interface CpaCodedError {
+  error: string;          // machine code, e.g. "plugin_not_found"
+  message: string;
+  [extra: string]: unknown; // restart_required, path, file_deleted, sources, retry_after, retry_at, ...
+}
+export type CpaErrorBody = CpaSimpleError | CpaCodedError;
+
+/** Auth outcomes: 401 missing/invalid key; 403 banned / remote disabled / key not set; 404 management disabled (empty body). */
+export type ManagementAuthErrorMessage =
+  | "missing management key"
+  | "invalid management key"
+  | "remote management disabled"
+  | "remote management key not set"
+  | `IP banned due to too many failed attempts. Try again in ${string}`;