@redonvn/event-ws-cliproxyapi-sdk 1.0.3 → 1.0.5

package/README.md

@@ -1,428 +1,258 @@
-# 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'
-});
-
-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`, pass `accessKey` as `Authorization: Bearer ...`.
-- 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.
+# @redonvn/event-ws-cliproxyapi-sdk
+
+TypeScript SDK for CLIProxyAPI with two main capabilities:
+- HTTP clients for OpenAI/Claude/Gemini-compatible and management endpoints
+- Provider-side WebSocket relay for `/v1/ws`
+
+## Why This SDK
+
+- Strong TypeScript types for request/response payloads
+- Unified auth model (`accessKey`, `managementKey`, `localPassword`)
+- Shared error model (`APIError`) across all HTTP clients
+- Explicit client modules by domain: `OpenAIClient`, `ClaudeClient`, `GeminiClient`, `CliproxyClient`, `ManagementClient`, `CliproxyWSProvider`
+
+## Install
+
+```bash
+npm i @redonvn/event-ws-cliproxyapi-sdk
+```
+
+## Requirements
+
+- Node.js with `fetch` support (Node 18+ recommended)
+- TypeScript 5+ (if consuming types in TS)
+
+If your runtime does not provide `fetch`, pass `options.fetch` when creating clients.
+
+## Quick Start
+
+```ts
+import {
+  CliproxyClient,
+  OpenAIClient,
+  ClaudeClient,
+  GeminiClient,
+  ManagementClient,
+  APIError
+} from '@redonvn/event-ws-cliproxyapi-sdk';
+
+const baseUrl = 'http://127.0.0.1:8317';
+
+const cliproxy = new CliproxyClient({
+  baseUrl,
+  accessKey: process.env.ACCESS_KEY,
+  managementKey: process.env.MANAGEMENT_KEY,
+  localPassword: process.env.LOCAL_PASSWORD
+});
+
+const openai = new OpenAIClient({ baseUrl, accessKey: process.env.ACCESS_KEY });
+const claude = new ClaudeClient({ baseUrl, accessKey: process.env.ACCESS_KEY });
+const gemini = new GeminiClient({ baseUrl, accessKey: process.env.ACCESS_KEY });
+const management = new ManagementClient({ baseUrl, managementKey: process.env.MANAGEMENT_KEY });
+
+try {
+  const models = await openai.getModels();
+  console.log(models.data.length);
+} catch (err) {
+  if (err instanceof APIError) {
+    console.error(err.status, err.message, err.payload);
+  }
+}
+```
+
+## Auth Model
+
+- `accessKey`: used for access-protected public inference endpoints
+- `managementKey`: used for `/v0/management/*`
+- `localPassword`: used for local-protected endpoints such as `/keep-alive`
+
+You can update keys at runtime:
+- `setAccessKey(key?)`
+- `setManagementKey(key?)`
+- `setLocalPassword(value?)`
+
+## Exported Modules
+
+From package root (`src/index.ts`):
+- `openai/*`
+- `claude/*`
+- `gemini/*`
+- `cliproxy/*`
+- `management/*`
+- `ws/*`
+- `shared/*`
+
+Core exports:
+- Clients: `OpenAIClient`, `ClaudeClient`, `GeminiClient`, `CliproxyClient`, `ManagementClient`
+- WS relay: `CliproxyWSProvider`, `CliproxyWSClient`
+- WS codec helpers: `decodeRequest`, `encodeResponse`, `decodeResponse`, `encodeChunk`, `decodeChunk`, `encodeError`, `decodeError`
+- Errors: `APIError`, `isOpenAIError`, `isStatusError`, `isManagementError`
+- Full payload types from `shared/types`
+
+## HTTP Clients
+
+### `OpenAIClient`
+
+Methods:
+- `getModels()` -> `GET /v1/models`
+- `postChatCompletions(body)` -> `POST /v1/chat/completions`
+- `postCompletions(body)` -> `POST /v1/completions`
+- `postResponses(body)` -> `POST /v1/responses`
+- `postResponsesCompact(body)` -> `POST /v1/responses/compact`
+
+Example:
+
+```ts
+const res = await openai.postChatCompletions({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'hello' }],
+  stream: false
+});
+
+const json = await res.json();
+console.log(json);
+```
+
+### `ClaudeClient`
+
+Methods:
+- `getModels()` -> `GET /v1/models` (adds `User-Agent: claude-cli`)
+- `postMessages(body)` -> `POST /v1/messages`
+- `postMessagesCountTokens(body)` -> `POST /v1/messages/count_tokens`
+
+### `GeminiClient`
+
+Methods:
+- `getModels()` -> `GET /v1beta/models`
+- `postModelsAction(action, body)` -> `POST /v1beta/models/{action}`
+- `getModelsAction(action, query?)` -> `GET /v1beta/models/{action}`
+- `postV1Internal(method, body)` -> `POST /v1internal:{method}`
+
+### `CliproxyClient`
+
+Methods:
+- `getRoot()` -> `GET /`
+- `getManagementHtml()` -> `GET /management.html`
+- `keepAlive()` -> `GET /keep-alive`
+- OAuth callbacks:
+  - `anthropicCallback(query)` -> `GET /anthropic/callback`
+  - `codexCallback(query)` -> `GET /codex/callback`
+  - `googleCallback(query)` -> `GET /google/callback`
+  - `iflowCallback(query)` -> `GET /iflow/callback`
+  - `antigravityCallback(query)` -> `GET /antigravity/callback`
+- CLIProxy endpoints:
+  - `getCliproxyAuths(query?)` -> `GET /v1/cliproxy/auths`
+  - `getCliproxyModels(query?)` -> `GET /v1/cliproxy/models`
+  - `postCliproxyChat(body)` -> `POST /v1/cliproxy/chat`
+
+### `ManagementClient`
+
+Covers management APIs under `/v0/management/*`, including:
+- usage import/export
+- runtime config and YAML config
+- logging and debug flags
+- key/config CRUD (`api-keys`, `claude-api-key`, `gemini-api-key`, `codex-api-key`, `vertex-api-key`, `openai-compatibility`)
+- routing/retry/quota flags
+- auth files and model definitions
+- OAuth helper flows
+
+Also includes:
+- `getDesktopKeys()` -> `GET /desktop/keys`
+- `getManagementApiKeys()` convenience fallback helper
+
+## Streaming Responses
+
+Many inference methods return raw `Response` for stream compatibility.
+- For SSE/event-stream, read `response.body`
+- For non-stream mode, parse with `await response.json()` or `await response.text()`
+
+## WebSocket Relay (Provider Side)
+
+Use `CliproxyWSProvider` to handle server forwarded requests over `/v1/ws`.
+
+```ts
+import { CliproxyWSProvider } from '@redonvn/event-ws-cliproxyapi-sdk';
+
+const provider = new CliproxyWSProvider({
+  baseUrl: 'http://127.0.0.1:8317',
+  accessKey: process.env.ACCESS_KEY
+});
+
+await provider.connect({
+  onEvent: (ev) => {
+    if (ev.type === 'ws:open') console.log('connected');
+    if (ev.type === 'ws:close') console.log('closed', ev.code, ev.reason);
+    if (ev.type === 'error') console.error(ev.error);
+  },
+  onRequest: async (req, ctx) => {
+    if (req.url === '/health') {
+      ctx.respond({ status: 200, body: 'ok' });
+      return;
+    }
+
+    ctx.streamStart(200, { 'Content-Type': 'text/plain' });
+    ctx.streamChunk('hello ');
+    ctx.streamChunk('world');
+    ctx.streamEnd();
+  }
+});
+
+provider.close();
+```
+
+WS message/event types are exported from `ws/types`.
+
+## Error Handling
+
+All non-2xx HTTP responses throw `APIError`.
+
+```ts
+import { APIError, isOpenAIError, isManagementError } from '@redonvn/event-ws-cliproxyapi-sdk';
+
+try {
+  await management.getConfig();
+} catch (err) {
+  if (err instanceof APIError) {
+    if (isOpenAIError(err.payload)) {
+      console.error('openai error:', err.payload.error.message);
+    } else if (isManagementError(err.payload)) {
+      console.error('management error:', err.payload.error);
+    } else {
+      console.error(err.status, err.message);
+    }
+  }
+}
+```
+
+## Common Types
+
+Selected primary request aliases:
+- `PrimaryOpenAIChatRequest`
+- `PrimaryOpenAICompletionRequest`
+- `PrimaryOpenAIResponsesRequest`
+- `PrimaryClaudeRequest`
+- `PrimaryGeminiRequest`
+- `PrimaryCliproxyRequest`
+
+Protocol and shared types:
+- JSON primitives/objects (`JsonValue`, `JsonObject`)
+- model/config/auth entities
+- OpenAI/Claude/Gemini compatible request/response types
+
+## Development
+
+```bash
+npm i
+npm run build
+```
+
+Build output:
+- JS: `dist/*.js`
+- Declarations: `dist/*.d.ts`
+
+## Notes
+
+- WebSocket auth: if server has `ws-auth: true`, provide `accessKey`.
+- Management endpoints require `managementKey`.
+- `keepAlive()` uses local auth (`localPassword`) if server enforces it.
+- This SDK is transport-oriented; retries/backoff are intentionally left to the consumer.