# 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

```bash
npm i
```

## Build

```bash
npm run build
```

## Exports

```ts
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)

```ts
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)

```ts
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):
```json
{
  "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):
```json
{
  "error": {
    "message": "Invalid request: Missing model",
    "type": "invalid_request_error",
    "code": "invalid_request_error"
  }
}
```

Claude Messages (OK, non-stream):
```json
{
  "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):
```json
{ "error": "invalid request" }
```

Gemini GenerateContent (OK, non-stream):
```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "hello" }]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ]
}
```

Gemini GenerateContent (Failed):
```json
{ "error": "invalid request" }
```

Management (Failed):
```json
{ "error": "invalid management key" }
```

## Image + Text in One Message

```ts
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.