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

package/src/client/types/config.ts

@@ -0,0 +1,248 @@
+// Types for the CLIProxyAPI v8 configuration document, as read and written by
+// `/v8/management/config`. Keys are the native dash-case YAML keys.
+//
+// All fields are optional: GET returns only what is stored, without defaults.
+// `null` may appear wherever a value was explicitly set to null (PATCH keeps
+// nulls; on per-key overrides null means "inherit from the group").
+// Derived from CLIProxyAPI v8.0.43 internal/config; see docs/api-coverage.md.
+
+/** Duration string ("30s", "1h") – some fields also accept integer seconds. */
+export type CpaDuration = string | number;
+
+export interface CpaThinkingSupport {            // registry/model_registry.go:144
+  min?: number; max?: number;
+  "zero-allowed"?: boolean; "dynamic-allowed"?: boolean;
+  "disable-type"?: string; levels?: string[];
+}
+
+export interface CpaRequestScopedErrorRule {      // config_types.go:16
+  status?: number; match?: string[]; "match-regexr"?: string[];
+  action?: "stop" | "stop-and-cooldown" | "continue" | "continue-and-cooldown" | (string & {});
+}
+
+export interface CpaModelBase {
+  name: string; alias: string; "display-name"?: string; "force-mapping"?: boolean;
+  thinking?: CpaThinkingSupport | null;
+}
+export interface CpaGeminiModel extends CpaModelBase { "max-context-length"?: number; "is-compat"?: boolean }       // :885
+export interface CpaClaudeModel extends CpaGeminiModel {}                                                            // :678
+export interface CpaCodexModel extends CpaGeminiModel { "support-configuration-update"?: boolean }                   // :778
+export interface CpaVertexModel extends CpaModelBase { openapi?: boolean }                                           // vertex_compat.go:77
+export interface CpaOpenAICompatModel extends CpaGeminiModel {                                                        // :978
+  image?: boolean; "input-modalities"?: string[]; "output-modalities"?: string[]; "use-max-completion-tokens"?: boolean;
+}
+
+/** Fields shared by a group and (as overrides; null = inherit) by each key. C:353-357 */
+export interface CpaKeyShared<M> {
+  priority?: number | null; prefix?: string | null; "proxy-url"?: string | null;
+  headers?: Record<string, string> | null; models?: M[] | null; "excluded-models"?: string[] | null;
+  "disable-cooling"?: boolean | null; "request-retry"?: number | null;
+  "request-scoped-errors"?: CpaRequestScopedErrorRule[] | null;
+}
+export interface CpaKeyBase<M> extends CpaKeyShared<M> {
+  "api-key": string;
+  weight?: number | null;            // weighted-round-robin share, max 1_000_000
+  /** Injected by GET JSON only; stripped on write. */
+  readonly auth_index?: string;
+}
+export interface CpaGeminiKey extends CpaKeyBase<CpaGeminiModel> {}                                                   // GeminiKey :834
+export interface CpaVertexKey extends Omit<CpaKeyBase<CpaVertexModel>, "request-scoped-errors"> {                     // vertex_compat.go:15
+  interactions?: boolean | null; openapi?: boolean | null; "openapi-location"?: string | null;
+}
+export interface CpaCodexKey extends CpaKeyBase<CpaCodexModel> {                                                      // CodexKey :716 (xai, meta alias it)
+  websockets?: boolean | null; "alpha-search"?: boolean | null; "disable-codex-cloaking"?: boolean | null;
+}
+export interface CpaClaudeCloak {                                                                                     // :572
+  mode?: string; "strict-mode"?: boolean; "sensitive-words"?: string[]; "cache-user-id"?: boolean;
+}
+export interface CpaClaudeKey extends CpaKeyBase<CpaClaudeModel> {                                                    // :596
+  "rebuild-mid-system-message"?: boolean | null; "native-tool-search"?: boolean | null;
+  cloak?: CpaClaudeCloak | null; "fingerprint-profile"?: string | null; "experimental-cch-signing"?: boolean | null;
+}
+export interface CpaKeyGroup<K, M> extends CpaKeyShared<M> {
+  name?: string; "base-url"?: string; keys: K[];
+}
+export interface CpaOpenAICompatKey {                                                                                 // :964
+  "api-key": string; weight?: number | null; "proxy-url"?: string; readonly auth_index?: string;
+}
+export interface CpaOpenAICompatGroup {                                                                               // :922 (keys replaces api-key-entries)
+  name: string; priority?: number; disabled?: boolean; prefix?: string; "base-url": string;
+  keys?: CpaOpenAICompatKey[]; models?: CpaOpenAICompatModel[]; headers?: Record<string, string>;
+  "support-prompt-cache-key"?: boolean; "disable-cooling"?: boolean | null; "request-retry"?: number | null;
+  "request-scoped-errors"?: CpaRequestScopedErrorRule[];
+  /** Injected on the group by GET JSON when it has no keys. */
+  readonly auth_index?: string;
+}
+
+export interface CpaPayloadModelRule {                                                                                 // :551
+  name?: string; protocol?: string; headers?: Record<string, string>; "from-protocol"?: string;
+  match?: Record<string, unknown>[]; "not-match"?: Record<string, unknown>[]; exist?: string[]; "not-exist"?: string[];
+}
+export interface CpaPayloadRule { models?: CpaPayloadModelRule[]; params?: Record<string, unknown> }                  // :542
+export interface CpaPayloadFilterRule { models?: CpaPayloadModelRule[]; params?: string[] }                           // :534
+
+export interface CpaOAuthModelAlias {                                                                                  // :455
+  name: string; alias: string; openapi?: boolean; fork?: boolean; "display-name"?: string; "force-mapping"?: boolean;
+}
+export interface CpaOAuthModelSetting { name: string; alias?: string; openapi?: boolean; "max-context-length"?: number } // :470
+
+export interface CpaICEServer {                                                                                        // :329
+  urls: string[];
+  /** Redacted (absent) in GET JSON; omit on write to keep the stored value; "" or null clears it. */
+  username?: string | null; credential?: string | null;
+}
+
+export interface CpaClaudeHeaderDefaults {                                                                             // :162
+  "user-agent"?: string; "package-version"?: string; "runtime-version"?: string; os?: string; arch?: string;
+  timeout?: string; timezone?: string; "stabilize-device-profile"?: boolean;
+  "anthropic-beta-strip"?: string[]; "anthropic-beta-append"?: string[];
+  "inject-diagnostics"?: boolean; "client-request-id"?: string;
+}
+
+export interface CpaPluginStoreAuth {                                                                                  // internal/pluginstore/auth.go:27
+  match?: string; "apply-to"?: string[]; type?: string; "token-env"?: string; "username-env"?: string;
+  "password-env"?: string; "header-name"?: string; "header-value-env"?: string; "allow-insecure"?: boolean;
+}
+export interface CpaPluginInstanceConfig { enabled?: boolean; priority?: number; [option: string]: unknown }          // :44
+
+export interface CpaConfig {
+  "config-version"?: 8;
+
+  models?: { catalog?: string; "codex-catalog"?: string; "devin-catalog"?: string };      // registry/catalog_config.go:11
+
+  server?: {
+    host?: string; port?: number; "max-request-body-bytes"?: number; "github-token"?: string;
+    "trusted-proxies"?: string[];                         // IP/CIDR, validated (422)
+    tls?: { enable?: boolean; cert?: string; key?: string };                              // :336
+    "commercial-mode"?: boolean;
+    discovery?: {                                                                         // :360
+      enabled?: boolean; "service-name"?: string; "service-type"?: string; subtypes?: string[];
+      interfaces?: { include?: string[]; exclude?: string[] };
+      "auth-required"?: boolean | null; "advertise-management"?: boolean;
+    };
+  };
+
+  management?: {                                                                          // RemoteManagement :384
+    "allow-remote"?: boolean;
+    /** NOT redacted by GET. Plaintext on write; persisted as bcrypt hash after watcher reload. */
+    "secret-key"?: string;
+    "disable-control-panel"?: boolean; "disable-auto-update-panel"?: boolean;
+    "panel-github-repository"?: string; "base-url"?: string;
+  };
+
+  access?: { "api-keys"?: string[] };
+
+  credentials?: {
+    concurrency?: {                                                                       // credential_concurrency.go:23
+      /** read-only (400 read_only_field) */ readonly "lifecycle-config-revision"?: number;
+      /** read-only */ readonly "observation-barrier-revision"?: number;
+      "cpa-heartbeat-timeout"?: CpaDuration; "cpa-cancel-bound"?: CpaDuration; "reclaim-grace"?: CpaDuration;
+      "cleanup-interval"?: CpaDuration; "release-flush-interval"?: CpaDuration; "release-max-backoff"?: CpaDuration;
+      "busy-retry-min"?: CpaDuration; "busy-retry-max"?: CpaDuration; "max-limit"?: number;
+    };
+    "in-flight"?: {                                                                       // credential_in_flight.go:18
+      "snapshot-interval"?: string; "stale-after"?: string; "max-part-bytes"?: number; "max-part-count"?: number;
+      "max-revision-bytes"?: number; "max-aggregate-groups"?: number; "max-details"?: number;
+      "max-string-bytes"?: number; "staging-retention"?: string;
+    };
+  };
+
+  routing?: {                                                                             // RoutingConfig :417 + remaps
+    strategy?: "round-robin" | "weighted-round-robin" | "fill-first" | (string & {});
+    "session-affinity"?: boolean; "session-affinity-ttl"?: string; "session-affinity-subagents"?: boolean;
+    "session-affinity-rebind-on"?: string;
+    "force-model-prefix"?: boolean;
+    retry?: { "request-retry"?: number; "max-retry-credentials"?: number; "max-retry-interval"?: number };
+    cooldown?: { "disable-cooling"?: boolean; "save-cooldown-status"?: boolean; "transient-error-cooldown-seconds"?: number };
+  };
+
+  requests?: {
+    "proxy-url"?: string; "tls-handshake-timeout-seconds"?: number; "passthrough-headers"?: boolean;
+    "nonstream-keepalive-interval"?: number;
+    streaming?: { "keepalive-seconds"?: number; "bootstrap-retries"?: number; "send-keepalive-before-ft"?: boolean }; // sdk_config.go:353
+    payload?: {                                                                           // :520
+      default?: CpaPayloadRule[]; "default-raw"?: CpaPayloadRule[];
+      override?: CpaPayloadRule[]; "override-raw"?: CpaPayloadRule[]; filter?: CpaPayloadFilterRule[];
+    };
+  };
+
+  client?: {                                                                              // sdk_config.go:123
+    codex?: {
+      "optimize-multi-agent-v2"?: boolean; "enable-apply-patch"?: boolean;
+      "web-search-result-cache"?: { enabled?: boolean; ttl?: string | number; limit?: number } | null;
+    };
+  };
+
+  upstream?: {
+    codex?: {                                                                             // CodexConfig :230 (subset)
+      "disable-codex-cloaking"?: boolean; "stream-bootstrap-buffering"?: boolean;
+      "stream-bootstrap-timeout"?: string; "orphan-delegation-compatibility"?: boolean;
+      "model-level-cooling"?: boolean; "response-steering"?: boolean;
+    };
+    claude?: {                                                                            // ClaudeConfig :115 + ClaudeCodeConfig + remaps
+      "model-level-cooling"?: boolean; "tool-search"?: boolean; "session-date-pin-days"?: number | null;
+      "disable-claude-cloak-mode"?: boolean; "disable-cloaking-model-list"?: boolean;
+      "header-defaults"?: CpaClaudeHeaderDefaults;
+    };
+    xai?: { "inject-x-search"?: boolean };                                                // :194
+  };
+
+  "api-keys"?: {
+    gemini?: CpaKeyGroup<CpaGeminiKey, CpaGeminiModel>[];
+    interactions?: CpaKeyGroup<CpaGeminiKey, CpaGeminiModel>[];
+    vertex?: CpaKeyGroup<CpaVertexKey, CpaVertexModel>[];
+    codex?: CpaKeyGroup<CpaCodexKey, CpaCodexModel>[];
+    claude?: CpaKeyGroup<CpaClaudeKey, CpaClaudeModel>[];
+    xai?: CpaKeyGroup<CpaCodexKey, CpaCodexModel>[];
+    meta?: CpaKeyGroup<CpaCodexKey, CpaCodexModel>[];
+    "openai-compatibility"?: CpaOpenAICompatGroup[];
+  };
+
+  oauth?: {
+    "auth-dir"?: string; "auth-auto-refresh-workers"?: number;
+    /** keyed by channel: vertex, aistudio, antigravity, claude, codex, kimi, xai, meta, or plugin provider keys */
+    "model-alias"?: Record<string, CpaOAuthModelAlias[]>;
+    "excluded-models"?: Record<string, string[]>;
+    "request-scoped-errors"?: Record<string, CpaRequestScopedErrorRule[]>;
+    settings?: Record<string, CpaOAuthModelSetting[]>;
+    providers?: {
+      aistudio?: { "ws-auth"?: boolean };
+      codex?: {
+        "live-media-relay"?: {                                                            // :318
+          enabled?: boolean; "max-sessions"?: number; "disable-private-remote-ips"?: boolean;
+          "public-ip"?: string; "udp-port-min"?: number; "udp-port-max"?: number;
+          "ice-servers"?: CpaICEServer[];
+        };
+        "signin-with-chatgpt-identifier"?: string;
+        "header-defaults"?: { "user-agent"?: string; "beta-features"?: string };          // :188
+      };
+      antigravity?: {                                                                     // :206 + remaps
+        "sensitive-words"?: string[];
+        "connection-pool"?: { enabled?: boolean; "idle-conn-timeout"?: string; "max-idle-conns-per-host"?: number };
+        "antigravity-credits"?: boolean;
+        "signature-cache-enabled"?: boolean; "signature-bypass-strict"?: boolean;
+      };
+      devin?: { "sensitive-words"?: string[] };
+    };
+  };
+
+  multimedia?: {
+    "disable-image-generation"?: boolean | "chat" | "passthrough";
+    "gpt-image-2-base-model"?: string; "video-result-auth-cache-ttl"?: string;
+  };
+
+  observability?: {
+    logs?: { debug?: boolean; "logging-to-file"?: boolean; "logs-max-total-size-mb"?: number;
+             "error-logs-max-files"?: number; "request-log"?: boolean };
+    usage?: { "usage-statistics-enabled"?: boolean; "redis-usage-queue-retention-seconds"?: number };
+    pprof?: { enable?: boolean; addr?: string };
+  };
+
+  plugins?: {                                                                             // :28
+    enabled?: boolean; dir?: string; "store-sources"?: string[]; "store-auth"?: CpaPluginStoreAuth[];
+    /** read-only */ readonly "auth-revision"?: number;
+    configs?: Record<string, CpaPluginInstanceConfig>;
+  };
+
+  "quota-exceeded"?: { "switch-project"?: boolean; "switch-preview-model"?: boolean };   // :403 (antigravity-credits moved)
+}

package/src/client/types/credentials.ts

@@ -0,0 +1,195 @@
+// Types for /v8/management/credentials.
+// Derived from CLIProxyAPI v8.0.43; see docs/api-coverage.md.
+
+import type { AuthStatus, CooldownReason, OkStatus, PartialFailure, RecentRequestBucket, SIWCStatus } from './common.ts';
+
+// ---------- GET /credentials ----------
+export interface ListCredentialsQuery {
+  name?: string;
+  auth_index?: string;
+  page?: number;      // >= 1; presence of page or page_size enables pagination
+  page_size?: number; // >= 1, default 50
+}
+
+export interface QuotaObservation {
+  observed_at?: string;
+  signals: Record<string, string>;
+}
+
+export interface CooldownView {
+  scope: 'credential' | 'model';
+  model_key?: string;
+  reason: CooldownReason | (string & {});
+  retry_at: string;
+  remaining_seconds: number;
+  backoff_level?: number;
+  http_status?: number;
+}
+
+export interface CodexIdTokenClaims {
+  chatgpt_account_id?: string;
+  plan_type?: string;
+  chatgpt_subscription_active_start?: unknown;
+  chatgpt_subscription_active_until?: unknown;
+}
+
+export interface AuthFileEntry {
+  id: string;
+  auth_index: string;
+  name: string;
+  type: string;
+  provider: string;
+  label: string;
+  status: AuthStatus;
+  status_message: string;
+  disabled: boolean;
+  unavailable: boolean;
+  runtime_only: boolean;
+  source: 'file' | 'memory';
+  size: number;
+  success: number;
+  failed: number;
+  recent_requests: RecentRequestBucket[];
+  quota: QuotaObservation;
+  cooldowns: CooldownView[] | null;
+
+  model_quotas?: Record<string, QuotaObservation>;
+  supports_quota?: true;
+  quota_provider?: string;
+  quota_plugin_id?: string;
+  email?: string;
+  project_id?: string;
+  account_type?: 'oauth' | 'api_key';
+  account?: string;
+  created_at?: string;
+  modtime?: string;
+  updated_at?: string;
+  last_refresh?: string;
+  next_retry_after?: string;
+  path?: string;
+  id_token?: CodexIdTokenClaims;
+  priority?: number;
+  note?: string;
+  weight?: number;
+  websockets?: boolean;
+  request_retry?: number;
+  // codex only (v8)
+  siwc_bind_supported?: boolean;
+  use_siwc?: boolean;
+  siwc_status?: SIWCStatus;
+  siwc_bound?: boolean;
+  siwc_expires_at?: string;
+}
+
+export interface ListCredentialsResponse {
+  observed_at: string;
+  files: AuthFileEntry[];
+  total?: number;
+  page?: number;
+  page_size?: number;
+  has_more?: boolean;
+}
+
+// ---------- POST /credentials ----------
+// multipart: any field names, one or more .json files; or raw JSON body + ?name=<file>.json
+export interface UploadCredentialRawQuery { name: string }
+export type UploadCredentialsResponse =
+  | { status: 'ok' }                                              // single file / raw
+  | { status: 'ok'; uploaded: number; files: string[] }           // multi, 200
+  | { status: 'partial'; uploaded: number; files: string[]; failed: PartialFailure[] }; // 207
+
+// ---------- DELETE /credentials ----------
+export interface DeleteCredentialsQuery { name?: string | string[]; all?: 'true' | '1' | '*' }
+export type DeleteCredentialsBody = string[] | { name?: string; names?: string[] };
+export type DeleteCredentialsResponse =
+  | { status: 'ok' }                                              // single
+  | { status: 'ok'; deleted: number }                             // all=true
+  | { status: 'ok'; deleted: number; files: string[] }            // multi, 200
+  | { status: 'partial'; deleted: number; files: string[]; failed: PartialFailure[] }; // 207
+
+// ---------- GET /credentials/models ----------
+export interface CredentialModelsQuery { name: string }
+export interface CredentialModel { id: string; display_name?: string; type?: string; owned_by?: string }
+export interface CredentialModelsResponse { models: CredentialModel[] }
+
+// ---------- GET /credentials/download ----------
+export interface DownloadCredentialQuery { name: string } // must end with .json
+// response: raw credential JSON (Record<string, unknown>)
+
+// ---------- PATCH /credentials/status ----------
+export interface PatchCredentialStatusRequest { name: string; auth_index?: string; disabled: boolean }
+export type PatchCredentialStatusResponse =
+  | { status: 'ok'; disabled: boolean }
+  | { status: 'ok'; disabled: boolean; via: 'config:excluded-models'; excluded_pattern: string };
+
+// ---------- PATCH /credentials/fields ----------
+export interface PatchCredentialFieldsRequest {
+  name: string;
+  priority?: number | null;
+  note?: string | null;
+  weight?: number | null;
+  request_retry?: number | null;
+  websockets?: boolean | null;
+  disabled?: boolean | null;
+  prefix?: string | null;
+  proxy_url?: string | null;
+  headers?: Record<string, string> | null; // merged; "" deletes a header
+  excluded_models?: string[] | null;
+  [fieldPath: string]: unknown;            // arbitrary metadata, dotted paths allowed
+}
+export type PatchCredentialFieldsResponse = OkStatus;
+
+// ---------- POST /credentials/refresh ----------
+export interface RefreshCredentialsQuery { all?: 'true'; name?: string; auth_index?: string }
+export interface RefreshCredentialsRequest { name?: string; auth_index?: string; all?: boolean }
+export interface ForceRefreshResult { id: string; success: boolean; error?: string }
+
+export interface CoreAuthQuotaState {
+  exceeded: boolean;
+  reason?: string;
+  next_recover_at: string;
+  backoff_level?: number;
+  observed_at?: string;
+  signals?: Record<string, string>;
+}
+export interface CoreAuthError { code?: string; message: string; retryable: boolean; http_status?: number }
+export interface CoreModelState {
+  status: AuthStatus;
+  status_message?: string;
+  unavailable: boolean;
+  next_retry_after: string;
+  last_error?: CoreAuthError;
+  quota: CoreAuthQuotaState;
+  updated_at: string;
+}
+export interface CoreAuth {
+  id: string;
+  registration_epoch?: number;
+  credential_version?: number;
+  generation?: number;
+  provider: string;
+  prefix?: string;
+  label?: string;
+  status: AuthStatus;
+  status_message?: string;
+  disabled: boolean;
+  unavailable: boolean;
+  proxy_url?: string;
+  attributes?: Record<string, string>;
+  metadata?: Record<string, unknown>; // contains raw tokens
+  quota: CoreAuthQuotaState;
+  last_error?: CoreAuthError;
+  created_at: string;
+  updated_at: string;
+  last_refreshed_at: string;
+  next_refresh_after: string;
+  next_retry_after: string;
+  model_states?: Record<string, CoreModelState>;
+}
+export type RefreshCredentialsResponse =
+  | { ok: true; results: ForceRefreshResult[] }
+  | { ok: true; auth: CoreAuth };
+
+// ---------- GET /credentials/siwc/status, GET /oauth/siwc/status ----------
+export interface SIWCStatusQuery { name?: string; id?: string; auth_index?: string; authIndex?: string }
+export interface SIWCStatusResponse { status: SIWCStatus }

package/src/client/types/index.ts

@@ -0,0 +1,9 @@
+export type * from './common.ts';
+export type * from './config.ts';
+export type * from './credentials.ts';
+export type * from './oauth.ts';
+export type * from './observability.ts';
+export type * from './plugins.ts';
+export type * from './requests.ts';
+export type * from './routing.ts';
+export type * from './server.ts';

package/src/client/types/oauth.ts

@@ -0,0 +1,71 @@
+// Types for /v8/management/oauth.
+// Derived from CLIProxyAPI v8.0.43; see docs/api-coverage.md.
+
+import type { OkStatus, StatusErrorBody } from './common.ts';
+
+// ---------- POST /oauth/import ----------
+export interface OAuthImportQuery { provider: 'vertex'; location?: string }
+// multipart: field "file" (service account JSON), optional field "location"
+export interface VertexImportResponse {
+  status: 'ok';
+  'auth-file': string;
+  project_id: string;
+  email: string;
+  location: string;
+}
+
+// ---------- GET|POST /oauth/auth-url ----------
+export type BuiltinOAuthProvider =
+  | 'claude' | 'codex' | 'antigravity' | 'kimi' | 'kimi-ai' | 'xai' | 'devin' | 'meta';
+export interface OAuthAuthUrlQuery {
+  provider?: BuiltinOAuthProvider | (string & {});
+  is_webui?: '1' | 'true' | 'yes' | 'on' | '0' | 'false' | 'no' | 'off';
+  domain?: string;  // kimi
+  channel?: string; // kimi
+  [pluginMeta: string]: string | undefined;
+}
+export interface OAuthAuthUrlRequest {     // POST only
+  provider?: BuiltinOAuthProvider | (string & {});
+  proxy_url?: string;
+  'proxy-url'?: string;
+  domain?: string;
+  channel?: string;
+  is_webui?: boolean | string;
+  [pluginMeta: string]: unknown;
+}
+export interface OAuthAuthUrlRedirectResponse { status: 'ok'; url: string; state: string }
+export interface OAuthAuthUrlDeviceResponse {
+  status: 'ok'; url: string; state: string; flow: 'device';
+  user_code?: string; expires_in?: number;
+}
+export type OAuthAuthUrlResponse = OAuthAuthUrlRedirectResponse | OAuthAuthUrlDeviceResponse;
+
+// ---------- POST /oauth/siwc/bind ----------
+export interface SIWCBindRequest { name: string }
+export interface SIWCBindResponse { status: 'ok'; url: string; state: string; flow: 'siwc_bind'; expires_in: number }
+
+// ---------- GET /oauth/status ----------
+export interface OAuthStatusQuery { state?: string }
+export type OAuthStatusResponse =
+  | { status: 'ok' }
+  | { status: 'wait' }
+  | { status: 'error'; error: string };
+
+// ---------- DELETE /oauth/session ----------
+export interface CancelOAuthSessionQuery { state: string }
+export interface CancelOAuthSessionResponse { status: 'ok'; cancelled: boolean }
+
+// ---------- GET|POST /oauth/callback (unauthenticated) ----------
+export interface OAuthCallbackQuery {
+  provider?: string; state?: string; code?: string;
+  error?: string; error_description?: string; client_id?: string;
+}
+export interface OAuthCallbackRequest {
+  provider?: string;
+  redirect_url?: string;
+  code?: string;
+  state?: string;
+  error?: string;
+  client_id?: string; // required for SIWC bind callbacks
+}
+export type OAuthCallbackResponse = OkStatus | StatusErrorBody;

package/src/client/types/observability.ts

@@ -0,0 +1,93 @@
+// Types for /v8/management/observability.
+// Derived from CLIProxyAPI v8.0.43; see docs/api-coverage.md.
+
+import type { RecentRequestBucket } from './common.ts';
+
+// ---------- observability/logs ----------
+export interface GetLogsQuery {
+  limit?: number;   // positive integer
+  after?: number;   // unix seconds; ignored when cursor is set
+  cursor?: string;  // opaque, from next-cursor
+}
+export interface GetLogsResponse {
+  lines: string[];
+  "line-count": number;       // returned count (cursor/tail) or total scanned (legacy after-scan)
+  "latest-timestamp": number; // unix seconds
+  "next-cursor": string;      // opaque base64url; may be ""
+  "cursor-reset"?: true;      // present only when the supplied cursor was invalid/stale
+}
+export interface DeleteLogsResponse { success: true; message: string; removed: number }
+
+export interface RequestErrorLogFile { name: string; size: number; modified: number /* unix seconds */ }
+export interface RequestErrorLogsResponse { files: RequestErrorLogFile[] }
+// GET logs/errors/:name and logs/requests/:id return a file attachment (text). Client should return Blob/ArrayBuffer/text + filename from Content-Disposition.
+
+// ---------- observability/usage/api-keys ----------
+export interface ApiKeyUsageEntry { success: number; failed: number; recent_requests: RecentRequestBucket[] /* 20 x 10min */ }
+/** provider -> "<base_url>|<api_key>" -> entry */
+export type ApiKeyUsageResponse = Record<string, Record<string, ApiKeyUsageEntry>>;
+
+// ---------- observability/usage/queue (DESTRUCTIVE pop) ----------
+export interface UsageQueueQuery { count?: number /* positive int, default 1 */ }
+export interface UsageTokenStats {
+  input_tokens: number;
+  output_tokens: number;
+  reasoning_tokens: number;
+  cached_tokens: number;
+  cache_read_tokens: number;
+  cache_read_tokens_present: boolean;
+  cache_creation_tokens: number;
+  total_tokens: number;
+}
+export interface UsageTokenBreakdown {
+  schema_version: number; // 2
+  quality: "complete" | "inconsistent" | "unclassified";
+  total_tokens: number;
+  input: { total_tokens: number; uncached_tokens: number; cache_read_tokens: number; cache_write_tokens: number };
+  output: { total_tokens: number; non_reasoning_tokens: number; reasoning_tokens: number };
+  unclassified_tokens: number;
+}
+export interface UsageQueueRecord {
+  timestamp: string;              // RFC3339
+  latency_ms: number;
+  ttft_ms: number;
+  source: string;
+  auth_index: string;
+  access_token_sha256?: string;
+  client_ip: string;
+  resolved_client_ip: string;
+  x_forwarded_for: string;
+  user_agent: string;
+  tokens: UsageTokenStats;
+  failed: boolean;
+  generate: boolean;
+  stream: boolean;
+  fail: { status_code: number; body: string }; // status_code 200 when not failed
+  response_headers?: Record<string, string[]>;
+  accounting_version: number;
+  token_breakdown: UsageTokenBreakdown;
+  provider: string;
+  executor_type: string;
+  model: string;
+  alias: string;
+  endpoint: string;
+  auth_type: string;
+  api_key: string;
+  is_native_key: boolean;
+  access_provider?: string;
+  request_id: string;
+  execution_id?: string;
+  trace_id?: string;
+  session_id?: string;
+  parent_session_id?: string;
+  node_kind?: string;
+  is_fork?: boolean;
+  is_compaction?: boolean;
+  reasoning_effort: string;
+  service_tier: string;
+  effective_service_tier?: string;
+  response_service_tier?: string;
+  response_model?: string;
+}
+/** Elements are verbatim queued JSON; non-JSON payloads come back as strings. */
+export type UsageQueueResponse = Array<UsageQueueRecord | string>;