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

package/src/client/types/plugins.ts

@@ -0,0 +1,136 @@
+// Types for /v8/management/plugins.
+// Derived from CLIProxyAPI v8.0.43; see docs/api-coverage.md.
+
+// ---------- plugins ----------
+export type PluginConfigFieldType = "string" | "number" | "integer" | "boolean" | "enum" | "array" | "object";
+export interface PluginConfigFieldInfo {
+  default: unknown;
+  name: string;
+  type: PluginConfigFieldType | string;
+  enum_values: string[] | null;
+  description: string;
+}
+export interface PluginMenuInfo { path: string; menu: string; description: string }
+export interface PluginMetadataInfo {
+  name: string;
+  version: string;
+  author: string;
+  github_repository: string;
+  logo: string;
+  config_fields: PluginConfigFieldInfo[];
+}
+export interface PluginListEntry {
+  id: string;
+  path: string;
+  configured: boolean;
+  registered: boolean;
+  enabled: boolean;
+  effective_enabled: boolean;
+  supports_oauth: boolean;
+  oauth_provider: string;
+  supports_quota: boolean;
+  quota_provider?: string;
+  logo: string;
+  config_fields: PluginConfigFieldInfo[];
+  menus: PluginMenuInfo[];
+  metadata: PluginMetadataInfo | null;
+}
+export interface PluginListResponse { plugins_enabled: boolean; plugins_dir: string; plugins: PluginListEntry[] }
+
+export interface DeletePluginResponse {
+  status: "deleted";
+  id: string;
+  path: string;
+  file_deleted: boolean;
+  configured_removed: boolean;
+  restart_required: false;
+}
+
+// ---------- plugins/store ----------
+export interface PluginStoreSource { id: string; name: string; url: string }
+export interface PluginStoreSourceError { source_id: string; source_name: string; source_url: string; message: string }
+export interface PluginStorePlatform { goos: string; goarch: string }
+export type PluginInstallType = "github-release" | "direct";
+export interface PluginStoreListEntry {
+  store_id: string; // "<source_id>/<id>"
+  source_id: string;
+  source_name: string;
+  source_url: string;
+  id: string;
+  name: string;
+  description: string;
+  author: string;
+  version: string;
+  repository: string;
+  install_type: PluginInstallType | string;
+  auth_required: boolean;
+  auth_configured: boolean;
+  platforms?: PluginStorePlatform[];
+  logo?: string;
+  homepage?: string;
+  license?: string;
+  tags?: string[];
+  installed: boolean;
+  installed_version: string;
+  installed_source_id?: string;
+  install_source_status?: "matched" | "different" | "unknown" | "assumed";
+  path: string;
+  configured: boolean;
+  registered: boolean;
+  enabled: boolean;
+  effective_enabled: boolean;
+  update_available: boolean;
+}
+export interface PluginStoreListResponse {
+  plugins_enabled: boolean;
+  plugins_dir: string;
+  sources: PluginStoreSource[];
+  source_errors?: PluginStoreSourceError[];
+  plugins: PluginStoreListEntry[];
+}
+export interface PluginInstallQuery { source?: string; version?: string }
+export interface PluginInstallRequest { version?: string }
+export interface PluginInstallResponse {
+  status: "installed";
+  source_id: string;
+  source_name: string;
+  source_url: string;
+  id: string;
+  version: string;
+  install_type: PluginInstallType | string;
+  path: string;
+  plugins_enabled: boolean;
+  restart_required: boolean; // currently always false on success
+}
+export interface PluginStoreRateLimitedError {
+  error: "plugin_store_rate_limited";
+  message: string;
+  retry_after: number;
+  retry_at: string;
+}
+
+// ---------- plugins/:id/quota ----------
+export interface PluginQuotaQuery { auth_index: string } // "authIndex" also accepted
+export interface PluginQuotaBody {                        // POST / DELETE body
+  auth_index?: string;
+  authIndex?: string;
+  AuthIndex?: string;
+}
+export interface QuotaSubscription { plan?: string; tierName?: string; tierId?: string }
+export interface QuotaBucket { window?: string; remainingFraction: number; resetTime?: string; description?: string }
+export interface QuotaGroup { displayName?: string; buckets?: QuotaBucket[] }
+export interface QuotaMetric {
+  key: string;
+  label: string;
+  value: number;
+  unit?: string;
+  format?: "number" | "currency";
+  currency?: string;
+}
+export interface QuotaFetchResponse {
+  subscription?: QuotaSubscription;
+  summary?: QuotaMetric[];
+  serverTimeOffsetMs?: number;
+  groups?: QuotaGroup[];
+}
+export interface PluginQuotaResetResponse { status: "ok"; auth_index: string; message?: string }

package/src/client/types/requests.ts

@@ -0,0 +1,19 @@
+// Types for /v8/management/requests.
+// Derived from CLIProxyAPI v8.0.43; see docs/api-coverage.md.
+
+// ---------- requests/api-call ----------
+export interface ApiCallRequest {
+  auth_index?: string;   // also accepted: authIndex, AuthIndex
+  authIndex?: string;
+  AuthIndex?: string;
+  method: string;        // required
+  url: string;           // required, absolute
+  proxy_url?: string;    // http(s)://, socks5://, socks5h://, "direct", "none"
+  header?: Record<string, string>; // "$TOKEN$" substituted; "Host" overrides req.Host
+  data?: string;         // raw body; "$TOKEN$" substituted
+}
+export interface ApiCallResponse {
+  status_code: number;
+  header: Record<string, string[]>;
+  body: string;
+}

package/src/client/types/routing.ts

@@ -0,0 +1,44 @@
+// Types for /v8/management/routing.
+// Derived from CLIProxyAPI v8.0.43; see docs/api-coverage.md.
+
+// ---------- routing/cooldown/reset ----------
+export interface CooldownResetRequest { auth_index: string }
+export interface CooldownResetResponse { status: "ok"; auth_index: string; models: string[] }
+
+// ---------- routing/model-definitions/:channel ----------
+export type StaticModelChannel =
+  | "claude" | "gemini" | "gemini-interactions" | "vertex" | "aistudio" | "codex"
+  | "kimi" | "kimi-ai" | "kimi.ai" | "kimi.com" | "antigravity"
+  | "xai" | "x-ai" | "grok" | "devin" | "meta" | "muse";
+export interface ThinkingSupport {
+  min?: number;
+  max?: number;
+  zero_allowed?: boolean;
+  dynamic_allowed?: boolean;
+  disable_type?: string;
+  levels?: string[];
+}
+export interface ModelInfo {
+  id: string;
+  object: string;
+  created: number;
+  owned_by: string;
+  type: string;
+  display_name?: string;
+  name?: string;
+  version?: string;
+  description?: string;
+  inputTokenLimit?: number;
+  outputTokenLimit?: number;
+  supportedGenerationMethods?: string[];
+  context_length?: number;
+  max_completion_tokens?: number;
+  supported_parameters?: string[];
+  supportedInputModalities?: string[];
+  supportedOutputModalities?: string[];
+  supports_web_search?: boolean;
+  thinking?: ThinkingSupport;
+  config?: { override_header?: Record<string, string> };
+}
+export interface ModelDefinitionsResponse { channel: string; models: ModelInfo[] }
+export interface UnknownChannelError { error: "unknown channel"; channel: string }

package/src/client/types/server.ts

@@ -0,0 +1,18 @@
+// Types for /healthz and /v8/management/server.
+// Derived from CLIProxyAPI v8.0.43; see docs/api-coverage.md.
+
+// ---------- /healthz ----------
+export interface HealthzResponse { status: "ok" }
+
+// ---------- server/latest-version ----------
+export interface LatestVersionResponse { "latest-version": string } // raw GitHub tag, e.g. "v8.0.43"
+export type LatestVersionErrorCode =
+  | "request_create_failed" | "request_failed" | "unexpected_status" | "decode_failed" | "invalid_response";
+
+/** Response headers set by the management auth middleware (handler.go:325-328). */
+export interface ServerInfo {
+  version: string;        // X-CPA-VERSION (e.g. "8.0.43"; "dev" for unversioned builds)
+  commit: string;         // X-CPA-COMMIT
+  buildDate: string;      // X-CPA-BUILD-DATE ("unknown" when not stamped)
+  supportPlugin: boolean; // X-CPA-SUPPORT-PLUGIN === "1"
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './client/index.ts';
+export * from './server/index.ts';

package/src/server/binary.ts

@@ -0,0 +1,128 @@
+import { accessSync, chmodSync, constants, existsSync, readdirSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { CpaBinaryError } from './errors.ts';
+import { TARGETS, UNSUPPORTED_PLATFORMS, binaryName, packageName, type Target } from './targets.ts';
+
+const require = createRequire(import.meta.url);
+
+export type Libc = 'glibc' | 'musl';
+
+export interface HostPlatform {
+  os: NodeJS.Platform;
+  cpu: NodeJS.Architecture;
+  /** Only meaningful on Linux. */
+  libc?: Libc;
+}
+
+export interface ResolvedBinary {
+  path: string;
+  /** The platform package the binary came from, or undefined for `binaryPath` overrides. */
+  packageName?: string;
+  target?: Target;
+}
+
+/** Detects the C library of the running Linux system. */
+export function detectLibc(): Libc | undefined {
+  if (process.platform !== 'linux') return undefined;
+  try {
+    const report = process.report?.getReport() as { header?: { glibcVersionRuntime?: string } } | undefined;
+    if (report?.header) return report.header.glibcVersionRuntime ? 'glibc' : 'musl';
+  } catch {
+    // Fall through to the filesystem probe; some runtimes do not implement process.report.
+  }
+  try {
+    if (readdirSync('/lib').some((name) => name.startsWith('ld-musl-'))) return 'musl';
+  } catch {
+    // Ignore unreadable /lib.
+  }
+  return 'glibc';
+}
+
+export function currentPlatform(): HostPlatform {
+  const libc = detectLibc();
+  return libc ? { os: process.platform, cpu: process.arch, libc } : { os: process.platform, cpu: process.arch };
+}
+
+/**
+ * Returns the targets that can run on a host, best match first.
+ *
+ * On Linux the libc-specific build is preferred, followed by the static
+ * portable build of the other libc, which runs anywhere on the same CPU.
+ */
+export function candidateTargets(host: HostPlatform): Target[] {
+  const matches = TARGETS.filter((t) => t.os === host.os && t.cpu === host.cpu);
+  const score = (t: Target): number => {
+    if (t.libc === undefined || t.libc === host.libc) return 0;
+    return t.build === 'portable' ? 1 : Number.POSITIVE_INFINITY;
+  };
+  return matches.filter((t) => Number.isFinite(score(t))).sort((a, b) => score(a) - score(b));
+}
+
+function ensureExecutable(path: string, source: string): void {
+  if (!existsSync(path)) {
+    throw new CpaBinaryError('missing', `CLIProxyAPI binary not found at ${path} (${source}).`);
+  }
+  if (!statSync(path).isFile()) {
+    throw new CpaBinaryError('missing', `CLIProxyAPI binary path ${path} is not a file (${source}).`);
+  }
+  if (process.platform === 'win32') return;
+  try {
+    accessSync(path, constants.X_OK);
+  } catch {
+    // Some package managers drop the executable bit on extraction; restore it once.
+    try {
+      chmodSync(path, 0o755);
+      accessSync(path, constants.X_OK);
+    } catch {
+      throw new CpaBinaryError('not-executable', `CLIProxyAPI binary at ${path} is not executable (${source}).`);
+    }
+  }
+}
+
+/**
+ * Locates the CLIProxyAPI executable.
+ *
+ * `binaryPath` overrides the lookup. Otherwise the platform package installed
+ * through the main package's optionalDependencies is used.
+ */
+export function resolveBinary(options: { binaryPath?: string; platform?: HostPlatform } = {}): ResolvedBinary {
+  if (options.binaryPath) {
+    ensureExecutable(options.binaryPath, 'binaryPath option');
+    return { path: options.binaryPath };
+  }
+
+  const host = options.platform ?? currentPlatform();
+  const candidates = candidateTargets(host);
+  const hostLabel = `${host.os}-${host.cpu}${host.libc ? ` (${host.libc})` : ''}`;
+  if (candidates.length === 0) {
+    const supported = TARGETS.map((t) => t.id).join(', ');
+    const reason = UNSUPPORTED_PLATFORMS[`${host.os}-${host.cpu}`] ?? UNSUPPORTED_PLATFORMS[`${host.os}-*`];
+    throw new CpaBinaryError(
+      'unsupported-platform',
+      `No prebuilt CLIProxyAPI binary for ${hostLabel}${reason ? ` (${reason})` : ''}. ` +
+        `Supported targets: ${supported}. Pass binaryPath to use your own build.`,
+    );
+  }
+
+  for (const target of candidates) {
+    const name = packageName(target);
+    let manifest: string;
+    try {
+      manifest = require.resolve(`${name}/package.json`);
+    } catch {
+      continue;
+    }
+    const path = join(dirname(manifest), 'bin', binaryName(target));
+    ensureExecutable(path, name);
+    return { path, packageName: name, target };
+  }
+
+  const expected = candidates.map(packageName).join(' or ');
+  throw new CpaBinaryError(
+    'package-not-installed',
+    `The CLIProxyAPI binary package for ${hostLabel} is not installed (expected ${expected}). ` +
+      'It is an optional dependency of @cpajs/cpa; reinstall without --no-optional / --omit=optional, ' +
+      'make sure your lockfile was not created on another platform without it, or pass binaryPath.',
+  );
+}

package/src/server/config.ts

@@ -0,0 +1,128 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import type { CpaConfig } from '../client/types/config.ts';
+import { CpaStartError } from './errors.ts';
+
+export const DEFAULT_PORT = 8317;
+export const MANAGED_CONFIG_FILE = 'config.yaml';
+
+export interface ListenSettings {
+  /** The `server.host` value as configured; empty means all interfaces. */
+  host: string;
+  port: number;
+  tls: boolean;
+}
+
+type Json = Record<string, unknown>;
+
+function isRecord(value: unknown): value is Json {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Reads listener settings from a parsed config document. The v8 `server.*`
+ * keys win over the legacy top-level `host`/`port`/`tls` keys, mirroring CPA.
+ */
+export function readListenSettings(doc: unknown): ListenSettings {
+  const root = isRecord(doc) ? doc : {};
+  const server = isRecord(root.server) ? root.server : {};
+  const pick = (key: string): unknown => (key in server ? server[key] : root[key]);
+
+  const host = pick('host');
+  const port = pick('port');
+  const tls = pick('tls');
+  const parsedPort = typeof port === 'number' ? port : typeof port === 'string' ? Number(port) : Number.NaN;
+  return {
+    host: typeof host === 'string' ? host.trim() : '',
+    // CPA falls back to 8317 when the port is missing or not positive.
+    port: Number.isInteger(parsedPort) && parsedPort > 0 ? parsedPort : port === 0 ? 0 : DEFAULT_PORT,
+    tls: isRecord(tls) && tls.enable === true,
+  };
+}
+
+const SECRET_FIELDS = new Set(['secret-key', 'api-key', 'github-token', 'credential', 'access_token', 'refresh_token']);
+const SECRET_LISTS = new Set(['api-keys']);
+
+/** Secrets that appear in a config document and must never reach logs. */
+export function configSecrets(doc: unknown): string[] {
+  const out: string[] = [];
+  const walk = (value: unknown, key: string | undefined): void => {
+    if (typeof value === 'string') {
+      if (key !== undefined && SECRET_FIELDS.has(key) && value !== '') out.push(value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (typeof item === 'string' && key !== undefined && SECRET_LISTS.has(key) && item !== '') out.push(item);
+        else walk(item, undefined);
+      }
+      return;
+    }
+    if (isRecord(value)) for (const [k, v] of Object.entries(value)) walk(v, k);
+  };
+  walk(doc, undefined);
+  return out;
+}
+
+export interface PreparedConfig {
+  configPath: string;
+  listen: ListenSettings;
+  secrets: string[];
+  /** True when the file was written by this package. */
+  managed: boolean;
+}
+
+/**
+ * Writes a `config` object to the managed config file in `stateDir`.
+ *
+ * The object is serialised as JSON, which is valid YAML and is read by CPA's
+ * YAML loader unchanged. Listener and auth directory defaults are filled in so
+ * the process stays inside `stateDir` and binds to loopback unless told otherwise.
+ */
+export async function writeManagedConfig(
+  config: CpaConfig,
+  stateDir: string,
+  listen: { host: string; port: number },
+): Promise<PreparedConfig> {
+  const doc = structuredClone(config) as Json;
+  const server = isRecord(doc.server) ? doc.server : {};
+  doc.server = { ...server, host: listen.host, port: listen.port };
+  if (doc['config-version'] === undefined) doc['config-version'] = 8;
+  const oauth = isRecord(doc.oauth) ? doc.oauth : {};
+  // Keep credentials inside stateDir unless the config chooses a location (v8 or legacy key).
+  if (oauth['auth-dir'] === undefined && doc['auth-dir'] === undefined) {
+    const authDir = join(stateDir, 'auths');
+    await mkdir(authDir, { recursive: true });
+    doc.oauth = { ...oauth, 'auth-dir': authDir };
+  }
+
+  const configPath = join(stateDir, MANAGED_CONFIG_FILE);
+  await writeFile(configPath, `${JSON.stringify(doc, null, 2)}\n`, { mode: 0o600 });
+  return { configPath, listen: readListenSettings(doc), secrets: configSecrets(doc), managed: true };
+}
+
+/** Reads an existing config file without modifying it. */
+export async function inspectConfigFile(configPath: string): Promise<PreparedConfig> {
+  const absolute = resolve(configPath);
+  let text: string;
+  try {
+    text = await readFile(absolute, 'utf8');
+  } catch (cause) {
+    throw new CpaStartError('invalid-options', `Cannot read configPath ${absolute}.`, { cause });
+  }
+  let doc: unknown;
+  try {
+    doc = parseYaml(text);
+  } catch (cause) {
+    throw new CpaStartError('invalid-options', `configPath ${absolute} is not valid YAML.`, { cause });
+  }
+  const listen = readListenSettings(doc);
+  if (listen.port === 0) {
+    throw new CpaStartError(
+      'invalid-options',
+      `configPath ${absolute} sets port 0. CLIProxyAPI does not report the port it picks, so set a fixed port or pass a config object instead.`,
+    );
+  }
+  return { configPath: absolute, listen, secrets: configSecrets(doc), managed: false };
+}

package/src/server/cpa-version.ts

@@ -0,0 +1,11 @@
+/** The CLIProxyAPI release this package version is built and verified against. */
+export const CPA_RELEASE = {
+  version: '8.0.43',
+  tag: 'v8.0.43',
+  commit: '307803510bce87f986fcf7b1a84190f105c7b4aa',
+  /** Commit timestamp, used as the reproducible build date. */
+  commitDate: '2026-10-25T14:45:00Z',
+  repository: 'https://github.com/router-for-me/CLIProxyAPI',
+  /** Go toolchain required by the pinned go.mod. */
+  goVersion: '1.26.10',
+} as const;

package/src/server/errors.ts

@@ -0,0 +1,48 @@
+export type CpaBinaryErrorCode = 'unsupported-platform' | 'package-not-installed' | 'missing' | 'not-executable';
+
+/** The CLIProxyAPI executable could not be located or used. */
+export class CpaBinaryError extends Error {
+  override readonly name = 'CpaBinaryError';
+  readonly code: CpaBinaryErrorCode;
+
+  constructor(code: CpaBinaryErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export type CpaStartErrorCode =
+  /** Invalid `startServer` options. */
+  | 'invalid-options'
+  /** The configured port is already taken. */
+  | 'port-in-use'
+  /** The process exited before it became ready. */
+  | 'exited'
+  /** The process could not be spawned. */
+  | 'spawn-failed'
+  /** Readiness was not reached within `startupTimeoutMs`. */
+  | 'timeout'
+  /** The `signal` passed to `startServer` was aborted. */
+  | 'aborted';
+
+/** `startServer` failed. Secrets are redacted from `message` and `output`. */
+export class CpaStartError extends Error {
+  override readonly name = 'CpaStartError';
+  readonly code: CpaStartErrorCode;
+  /** Recent process output (redacted), useful for diagnosing failures. */
+  readonly output: string;
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+
+  constructor(
+    code: CpaStartErrorCode,
+    message: string,
+    details: { output?: string; exitCode?: number | null; signal?: NodeJS.Signals | null; cause?: unknown } = {},
+  ) {
+    super(message, details.cause === undefined ? undefined : { cause: details.cause });
+    this.code = code;
+    this.output = details.output ?? '';
+    this.exitCode = details.exitCode ?? null;
+    this.signal = details.signal ?? null;
+  }
+}