event-ws-cliproxyapi-sdk

v0.1.0

Published

7 days ago

TypeScript SDK for CLIProxyAPI WebSocket relay (provider-side).

0High
0Medium
0Low

andev2005

event-ws-CLIProxyAPI-sdk

TypeScript SDK for CLIProxyAPI covering:

WebSocket relay (provider-side) via /v1/ws
Full HTTP client for public and management APIs

Endpoints (Full List + Function)

WebSocket relay

GET /v1/ws: WebSocket relay endpoint for provider-side request/response and streaming.

Public (no management key)

GET /: Health/info root. Returns server message + key endpoints list.
GET /management.html: Management UI HTML (if enabled on server).
GET /keep-alive: Keep-alive heartbeat (only if server enabled it). Requires local password when set.
OAuth callbacks (used by browser auth flows):
GET /anthropic/callback: Persist Anthropic OAuth callback.
GET /codex/callback: Persist Codex OAuth callback.
GET /google/callback: Persist Gemini OAuth callback.
GET /iflow/callback: Persist iFlow OAuth callback.
GET /antigravity/callback: Persist Antigravity OAuth callback.
POST /v1internal:method: Gemini CLI handler (localhost only). For generateContent / streamGenerateContent.

OpenAI-compatible (/v1)

GET /v1/models: List models (OpenAI or Claude depending on User-Agent).
POST /v1/chat/completions: Chat Completions (OpenAI-compatible, supports stream).
POST /v1/completions: Completions (OpenAI-compatible, supports stream).
POST /v1/messages: Claude-style messages (supports stream).
POST /v1/messages/count_tokens: Claude token counting.
POST /v1/responses: OpenAI Responses API (supports stream).
POST /v1/responses/compact: OpenAI Responses Compact (non-stream).

CLIProxy simplified (/v1/cliproxy)

GET /v1/cliproxy/auths: List authenticated accounts and supported models.
GET /v1/cliproxy/models: List available models (format: openai/claude/gemini/generic).
POST /v1/cliproxy/chat: Simplified chat proxy (maps to OpenAI chat).

Gemini-compatible (/v1beta)

GET /v1beta/models: List Gemini models.
POST /v1beta/models/*action: Gemini generate/stream endpoints (e.g. :generateContent, :streamGenerateContent).
GET /v1beta/models/*action: Gemini GET actions.

Management (/v0/management, requires management key)

GET /v0/management/usage: Usage snapshot (in-memory stats).
GET /v0/management/usage/export: Export usage snapshot.
POST /v0/management/usage/import: Import usage snapshot.
GET /v0/management/config: Full config JSON.
GET /v0/management/config.yaml: Config YAML.
PUT /v0/management/config.yaml: Replace config YAML (validates then saves).
GET /v0/management/latest-version: Latest release version (from GitHub).
GET /v0/management/debug: Debug flag.
PUT /v0/management/debug: Update debug flag.
PATCH /v0/management/debug: Update debug flag.
GET /v0/management/logging-to-file: Logging-to-file flag.
PUT /v0/management/logging-to-file: Update logging-to-file.
PATCH /v0/management/logging-to-file: Update logging-to-file.
GET /v0/management/logs-max-total-size-mb: Logs max size.
PUT /v0/management/logs-max-total-size-mb: Update logs max size.
PATCH /v0/management/logs-max-total-size-mb: Update logs max size.
GET /v0/management/error-logs-max-files: Error logs max files.
PUT /v0/management/error-logs-max-files: Update error logs max files.
PATCH /v0/management/error-logs-max-files: Update error logs max files.
GET /v0/management/usage-statistics-enabled: Usage stats enabled.
PUT /v0/management/usage-statistics-enabled: Update usage stats enabled.
PATCH /v0/management/usage-statistics-enabled: Update usage stats enabled.
GET /v0/management/proxy-url: Proxy URL.
PUT /v0/management/proxy-url: Update proxy URL.
PATCH /v0/management/proxy-url: Update proxy URL.
DELETE /v0/management/proxy-url: Clear proxy URL.
POST /v0/management/api-call: Test outbound API call using an auth entry.
GET /v0/management/quota-exceeded/switch-project: Switch project flag.
PUT /v0/management/quota-exceeded/switch-project: Update switch project flag.
PATCH /v0/management/quota-exceeded/switch-project: Update switch project flag.
GET /v0/management/quota-exceeded/switch-preview-model: Switch preview model flag.
PUT /v0/management/quota-exceeded/switch-preview-model: Update switch preview model flag.
PATCH /v0/management/quota-exceeded/switch-preview-model: Update switch preview model flag.
GET /v0/management/api-keys: List API keys.
PUT /v0/management/api-keys: Replace API keys.
PATCH /v0/management/api-keys: Patch API keys.
DELETE /v0/management/api-keys: Delete API keys.
GET /v0/management/gemini-api-key: List Gemini keys.
PUT /v0/management/gemini-api-key: Replace Gemini keys.
PATCH /v0/management/gemini-api-key: Patch Gemini keys.
DELETE /v0/management/gemini-api-key: Delete Gemini keys.
GET /v0/management/logs: Read log lines.
DELETE /v0/management/logs: Clear logs.
GET /v0/management/request-error-logs: List request error logs.
GET /v0/management/request-error-logs/:name: Download a request error log.
GET /v0/management/request-log-by-id/:id: Download request log by request ID.
GET /v0/management/request-log: Request log enabled flag.
PUT /v0/management/request-log: Update request log enabled flag.
PATCH /v0/management/request-log: Update request log enabled flag.
GET /v0/management/ws-auth: WebSocket auth enabled flag.
PUT /v0/management/ws-auth: Update WebSocket auth enabled flag.
PATCH /v0/management/ws-auth: Update WebSocket auth enabled flag.
GET /v0/management/ampcode: Amp CLI config.
GET /v0/management/ampcode/upstream-url: Amp upstream URL.
PUT /v0/management/ampcode/upstream-url: Update Amp upstream URL.
PATCH /v0/management/ampcode/upstream-url: Update Amp upstream URL.
DELETE /v0/management/ampcode/upstream-url: Clear Amp upstream URL.
GET /v0/management/ampcode/upstream-api-key: Amp upstream API key.
PUT /v0/management/ampcode/upstream-api-key: Update Amp upstream API key.
PATCH /v0/management/ampcode/upstream-api-key: Update Amp upstream API key.
DELETE /v0/management/ampcode/upstream-api-key: Clear Amp upstream API key.
GET /v0/management/ampcode/restrict-management-to-localhost: Restrict Amp management to localhost.
PUT /v0/management/ampcode/restrict-management-to-localhost: Update restriction.
PATCH /v0/management/ampcode/restrict-management-to-localhost: Update restriction.
GET /v0/management/ampcode/model-mappings: List Amp model mappings.
PUT /v0/management/ampcode/model-mappings: Replace Amp model mappings.
PATCH /v0/management/ampcode/model-mappings: Patch Amp model mappings.
DELETE /v0/management/ampcode/model-mappings: Delete Amp model mappings.
GET /v0/management/ampcode/force-model-mappings: Force model mappings flag.
PUT /v0/management/ampcode/force-model-mappings: Update force model mappings.
PATCH /v0/management/ampcode/force-model-mappings: Update force model mappings.
GET /v0/management/ampcode/upstream-api-keys: List Amp upstream API keys.
PUT /v0/management/ampcode/upstream-api-keys: Replace Amp upstream API keys.
PATCH /v0/management/ampcode/upstream-api-keys: Patch Amp upstream API keys.
DELETE /v0/management/ampcode/upstream-api-keys: Delete Amp upstream API keys.
GET /v0/management/request-retry: Request retry count.
PUT /v0/management/request-retry: Update request retry count.
PATCH /v0/management/request-retry: Update request retry count.
GET /v0/management/max-retry-interval: Max retry interval.
PUT /v0/management/max-retry-interval: Update max retry interval.
PATCH /v0/management/max-retry-interval: Update max retry interval.
GET /v0/management/force-model-prefix: Force model prefix flag.
PUT /v0/management/force-model-prefix: Update force model prefix.
PATCH /v0/management/force-model-prefix: Update force model prefix.
GET /v0/management/routing/strategy: Routing strategy.
PUT /v0/management/routing/strategy: Update routing strategy.
PATCH /v0/management/routing/strategy: Update routing strategy.
GET /v0/management/claude-api-key: List Claude keys.
PUT /v0/management/claude-api-key: Replace Claude keys.
PATCH /v0/management/claude-api-key: Patch Claude keys.
DELETE /v0/management/claude-api-key: Delete Claude keys.
GET /v0/management/codex-api-key: List Codex keys.
PUT /v0/management/codex-api-key: Replace Codex keys.
PATCH /v0/management/codex-api-key: Patch Codex keys.
DELETE /v0/management/codex-api-key: Delete Codex keys.
GET /v0/management/openai-compatibility: List OpenAI compatibility configs.
PUT /v0/management/openai-compatibility: Replace OpenAI compatibility configs.
PATCH /v0/management/openai-compatibility: Patch OpenAI compatibility configs.
DELETE /v0/management/openai-compatibility: Delete OpenAI compatibility configs.
GET /v0/management/vertex-api-key: List Vertex compatibility keys.
PUT /v0/management/vertex-api-key: Replace Vertex compatibility keys.
PATCH /v0/management/vertex-api-key: Patch Vertex compatibility keys.
DELETE /v0/management/vertex-api-key: Delete Vertex compatibility keys.
GET /v0/management/oauth-excluded-models: List OAuth excluded models.
PUT /v0/management/oauth-excluded-models: Replace OAuth excluded models.
PATCH /v0/management/oauth-excluded-models: Patch OAuth excluded models.
DELETE /v0/management/oauth-excluded-models: Delete OAuth excluded models.
GET /v0/management/oauth-model-alias: List OAuth model alias.
PUT /v0/management/oauth-model-alias: Replace OAuth model alias.
PATCH /v0/management/oauth-model-alias: Patch OAuth model alias.
DELETE /v0/management/oauth-model-alias: Delete OAuth model alias.
GET /v0/management/auth-files: List auth files.
GET /v0/management/auth-files/models: Get models for an auth file.
GET /v0/management/model-definitions/:channel: Get static model definitions.
GET /v0/management/auth-files/download: Download auth file.
POST /v0/management/auth-files: Upload auth file.
DELETE /v0/management/auth-files: Delete auth file.
PATCH /v0/management/auth-files/status: Enable/disable auth file.
POST /v0/management/vertex/import: Import Vertex credentials.
OAuth token helpers:
GET /v0/management/anthropic-auth-url: Start Anthropic OAuth.
GET /v0/management/codex-auth-url: Start Codex OAuth.
GET /v0/management/gemini-cli-auth-url: Start Gemini CLI OAuth.
GET /v0/management/antigravity-auth-url: Start Antigravity OAuth.
GET /v0/management/qwen-auth-url: Start Qwen OAuth.
GET /v0/management/kimi-auth-url: Start Kimi OAuth.
GET /v0/management/iflow-auth-url: Start iFlow OAuth.
POST /v0/management/iflow-auth-url: Submit iFlow cookie token.
POST /v0/management/oauth-callback: Post OAuth callback data.
GET /v0/management/get-auth-status: Poll OAuth status.

Install

npm i

Build

npm run build

Exports

import {
  // WS relay
  CliproxyWSProvider,
  CliproxyWSClient,
  decodeRequest,
  encodeResponse,
  encodeChunk,
  encodeError,
  type HTTPRequest,
  type HTTPResponse,
  type ProviderOptions,
  type ProviderEvent,
  type WSRequestContext,

  // HTTP clients by service
  CliproxyClient,
  OpenAIClient,
  ClaudeClient,
  GeminiClient,
  ManagementClient,

  // Primary request types
  type PrimaryOpenAIChatRequest,
  type PrimaryClaudeRequest,
  type PrimaryGeminiRequest,
  type PrimaryCliproxyRequest
} from 'event-ws-cliproxyapi-sdk';

Types (Events and Protocol)

Events (SDK level)

ProviderEvent
- ws:open – WebSocket connected
- ws:close – WebSocket closed
- request – server sent an http_request
- error – handler error

Protocol messages (WS level)

WSMessageType
- http_request (server → client)
- http_response (client → server)
- stream_start / stream_chunk / stream_end (client → server)
- error (client → server)
- ping / pong

Request/Response types

HTTPRequest
- method, url, headers, body, sent_at
HTTPResponse
- status, headers, body

Helper context

WSRequestContext
- respond(resp)
- streamStart(status?, headers?)
- streamChunk(chunk)
- streamEnd()
- error(message, status?)

Usage (Provider Relay)

import { CliproxyWSProvider } from 'event-ws-cliproxyapi-sdk';

const provider = new CliproxyWSProvider({
  baseUrl: 'http://127.0.0.1:8317',
  accessKey: 'andev',
  managementKey: 'mgmt_xxx'
});

await provider.connect({
  onEvent: (ev) => {
    if (ev.type === 'ws:open') console.log('ws open');
    if (ev.type === 'ws:close') console.log('ws close', ev.code, ev.reason);
  },
  onRequest: async (req, ctx) => {
    if (req.url === '/v1/cliproxy/chat') {
      ctx.streamStart(200, { 'Content-Type': 'text/plain' });
      ctx.streamChunk('hello ');
      ctx.streamChunk('world');
      ctx.streamEnd();
      return;
    }
    ctx.respond({ status: 404, body: 'not found' });
  }
});

provider.close();

Usage (HTTP Client)

import { CliproxyClient, OpenAIClient, ClaudeClient, GeminiClient, ManagementClient } from 'event-ws-cliproxyapi-sdk';

const cliproxy = new CliproxyClient({
  baseUrl: 'http://127.0.0.1:8317',
  accessKey: 'your-access-key',
  managementKey: 'your-management-key'
});

// Public: list auths
const auths = await cliproxy.getCliproxyAuths();

// OpenAI-compatible chat
const openai = new OpenAIClient({ baseUrl: 'http://127.0.0.1:8317', accessKey: 'your-access-key' });
await openai.postChatCompletions({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'user', content: [{ type: 'text', text: 'hello' }] }
  ]
});

Response Types

OpenAI-compatible

OpenAIChatCompletionResponse (non-stream)
OpenAIChatCompletionChunk (stream)
OpenAICompletionResponse (non-stream)
OpenAICompletionChunk (stream)
OpenAIResponsesResponse (non-stream)
OpenAIResponsesChunk (stream)

Claude-compatible

ClaudeMessagesResponse (non-stream)
ClaudeStreamEvent (stream)

Gemini-compatible

GeminiGenerateContentResponse (non-stream)
GeminiStreamChunk (stream)

Errors

OpenAIErrorResponse (OpenAI-style { error: { message, type, code? } })
ErrorResponse (management { error: string, message?: string })
StatusResponse (status polling { status: "ok" | "error" | "wait", error?: string })
APIError (thrown by service clients on non-2xx)

Response Examples (OK / Failed)

OpenAI Chat Completions (OK, non-stream):

{
  "id": "chatcmpl_123",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "hello" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "total_tokens": 10 }
}

OpenAI Chat Completions (Failed):

{
  "error": {
    "message": "Invalid request: Missing model",
    "type": "invalid_request_error",
    "code": "invalid_request_error"
  }
}

Claude Messages (OK, non-stream):

{
  "id": "msg_123",
  "type": "message",
  "role": "assistant",
  "model": "claude-3-5-sonnet",
  "content": [{ "type": "text", "text": "hello" }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 5, "output_tokens": 5 }
}

Claude Messages (Failed):

{ "error": "invalid request" }

Gemini GenerateContent (OK, non-stream):

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "hello" }]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ]
}

Gemini GenerateContent (Failed):

{ "error": "invalid request" }

Management (Failed):

{ "error": "invalid management key" }

Image + Text in One Message

await openai.postChatCompletions({
  model: 'gpt-4o-mini',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'describe this image' },
        { type: 'image_url', image_url: { url: 'https://example.com/cat.jpg' } }
      ]
    }
  ]
});

Notes

For WS relay, if ws-auth: true, provide accessKey.
SDK handshake sends:
- Authorization: Bearer <accessKey> (backward compatible)
- X-Access-Key: <accessKey>
- X-Management-Key: <managementKey> (if provided)
Management APIs require managementKey (or local password for /keep-alive if enabled).
HTTP client returns Response for streaming endpoints; parse SSE or chunks based on your client.