connectbase-client 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.1.0] - 2026-04-29
+
+### Added — Endpoint API (로컬 모델 터널 dumb pipe)
+
+사용자 PC GPU 모델 (ComfyUI / A1111 / Hunyuan3D / vLLM / 자체 FastAPI 등) 을
+`cb_pk_*` 한 키로 호출하는 새 모듈. ConnectBase 는 모델·API·워크플로우를
+알지 않고, 라벨 → tunnel 매핑만 들고 페이로드/응답을 그대로 통과시킵니다.
+
+- **`cb.endpoint.call(label, init)`** — fetch() 시그니처 호환 (path, method,
+  headers, body, signal). URL 은 `${baseUrl}/v1/proxy/${label}${path}` 로
+  자동 조립, `X-Public-Key` 헤더 자동 주입. SSE / chunked 스트리밍은
+  `res.body.getReader()` 로 그대로 읽기.
+- 신규 export: `EndpointAPI`, `EndpointCallInit`.
+
+### Added — CLI
+
+- **`connectbase tunnel <port> --label <name>`** — tunnel 발급 후 endpoint
+  binding 을 자동 등록. SDK 사용자가 즉시 `cb.endpoint.call("<label>", { ... })`
+  로 호출 가능. 인증은 User Secret Key (`cb_sk_*`) — dual-auth 라우트
+  `POST /v1/apps/:appID/endpoints/cli`.
+- **`--description <text>`** — endpoint binding 의 설명 (`--label` 동반 시만).
+- 이미 등록된 라벨이면 경고 후 진행 (다른 tunnel_id 로 갱신은 콘솔에서 PATCH).
+
+### Fixed
+
+- JSDoc 안 중첩 블록주석으로 빌드가 깨지던 회귀 수정 (`*/` 가 주석을 조기
+  종료시키던 케이스).
+
+## [3.0.1] - 2026-04-28
+
+### Fixed
+
+- `npx connectbase docs` 가 인증 없이 곧장 문서를 받도록 수정. 백엔드 `/v1/storages/webs/claude-md`
+  는 public 라우트인데 CLI 가 불필요하게 브라우저 인증 → 앱 선택 → Public Key 발급을 강제하던
+  흐름을 제거. 캐시된 publicKey 가 있으면 문서에 박아주고, 없으면 백엔드가 placeholder
+  (`YOUR_PUBLIC_KEY_HERE`) 로 대체해 그대로 다운로드.
+
 ## [3.0.0] - 2026-04-28 — BREAKING
 
 게임 서버 mechanism-only 재설계. ConnectBase 가 박아두던 게임 룰 (파티/로비/랭킹/매치메이킹/

package/README.md

@@ -79,6 +79,7 @@ const state = await gameClient.createRoom({
 - **WebRTC**: Real-time audio/video communication
 - **Payments**: Subscription and one-time payment support
 - **AI Streaming**: Real-time AI text generation via WebSocket (Gemini)
+- **Endpoint**: Call your own GPU models on your own PC through one `cb_pk_*` key — ConnectBase forwards the payload as-is (dumb pipe)
 - **CLI**: Command-line tool for deploying web storage and tunneling local services
 
 ## CLI
@@ -127,6 +128,8 @@ npx connectbase deploy ./dist -s <storage-id> -k <public-key>
 | `--base-url <url>` | `-u` | Custom server URL |
 | `--timeout <sec>` | `-t` | Tunnel request timeout in seconds (tunnel only) |
 | `--max-body <MB>` | | Tunnel max body size in MB (tunnel only) |
+| `--label <name>` | | Auto-register the issued tunnel as an endpoint binding (tunnel only). Requires Secret Key. SDK callers can then use `cb.endpoint.call(label, …)` |
+| `--description <text>` | | Endpoint binding description (only valid with `--label`) |
 | `--help` | `-h` | Show help |
 | `--version` | `-v` | Show version |
 
@@ -164,6 +167,23 @@ Features:
 - Graceful shutdown with Ctrl+C
 - No external dependencies (uses Node.js built-in modules)
 
+#### Auto-register an endpoint binding (`--label`)
+
+For workflows where you want the SDK to call your local model by a stable name
+(`cb.endpoint.call("comfyui-main", …)`) instead of a random tunnel URL, pass
+`--label <name>`. The CLI registers the issued `tunnel_id` as an endpoint binding
+on the server, so your SDK only needs the Public Key.
+
+```bash
+# Start ComfyUI on port 8188, expose it as endpoint label "comfyui-main"
+npx connectbase tunnel 8188 --label comfyui-main --description "ComfyUI on my desktop"
+```
+
+Authentication uses your User Secret Key (`cb_sk_*`); the CLI calls the dual-auth
+route `POST /v1/apps/:appID/endpoints/cli`. If the label already exists, the CLI
+warns and keeps the tunnel running — update the binding to the new `tunnel_id`
+from the console if needed.
+
 ### Configuration File
 
 The `init` command creates `.connectbaserc` automatically. You can also create it manually:
@@ -791,6 +811,78 @@ await session.stop()
 | `promptTokens` | `number` | Input prompt tokens |
 | `duration` | `number` | Generation time in ms |
 
+### Endpoint (Local Model Tunnel)
+
+`cb.endpoint.*` is a dumb pipe to your own GPU/model server running behind a
+ConnectBase tunnel. ConnectBase doesn't know your model, payload, or response
+shape — it routes a `cb_pk_*` call by label to the registered tunnel and forwards
+the body and headers as-is.
+
+**Setup**: run `connectbase tunnel <port> --label <name>` once on the machine
+hosting the model (see [Tunnel](#tunnel)) — that registers the binding. Then any
+client with the app's Public Key can call it.
+
+#### `cb.endpoint.call(label, init): Promise<Response>`
+
+`fetch()`-compatible signature. Returns the raw `Response` — read the body as
+JSON, text, or stream as needed.
+
+```typescript
+const cb = new ConnectBase({ publicKey: 'cb_pk_...' })
+
+// ComfyUI prompt graph
+const res = await cb.endpoint.call('comfyui-main', {
+  method: 'POST',
+  path: '/prompt',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ prompt: { /* ComfyUI node graph */ } }),
+})
+const data = await res.json()
+```
+
+```typescript
+// Streaming response (SSE / chunked) — vLLM chat completions
+const res = await cb.endpoint.call('vllm-local', {
+  method: 'POST',
+  path: '/v1/chat/completions',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ stream: true, messages: [/* { role, content } */] }),
+})
+if (!res.body) throw new Error('no stream')
+const reader = res.body.getReader()
+while (true) {
+  const { done, value } = await reader.read()
+  if (done) break
+  // value is a Uint8Array — decode and process chunk
+}
+```
+
+```typescript
+// Cancel an in-flight request
+const ctrl = new AbortController()
+setTimeout(() => ctrl.abort(), 30_000)
+await cb.endpoint.call('hunyuan-laptop', {
+  method: 'POST',
+  path: '/generate',
+  signal: ctrl.signal,
+  body: JSON.stringify({ /* model input */ }),
+})
+```
+
+**`EndpointCallInit`**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `path` | `string` | yes | Path on your model server, must start with `/` (e.g. `/prompt`, `/v1/chat/completions`) |
+| `method` | `string` | no (`GET`) | HTTP method |
+| `headers` | `HeadersInit` | no | Extra request headers; `X-Public-Key` is auto-injected unless you set it |
+| `body` | `BodyInit \| null` | no | Request body — `string`, `Blob`, `ArrayBuffer`, `FormData`, or `ReadableStream` |
+| `signal` | `AbortSignal` | no | Abort signal for cancellation |
+
+The SDK assembles the URL as `${baseUrl}/v1/proxy/${label}${path}` and forwards
+the request. Because the response is the raw `fetch` `Response`, streaming
+formats (SSE, chunked, NDJSON) work out of the box.
+
 ### Push Notifications
 
 ```typescript

package/dist/cli.js

@@ -952,70 +952,6 @@ function detectMonorepo(gitRoot) {
   }
   return result;
 }
-async function ensureDocsPublicKey(config) {
-  if (config.publicKey) return config.publicKey;
-  const rcPath = path2.join(process.cwd(), ".connectbaserc");
-  const baseUrl = config.baseUrl || DEFAULT_BASE_URL;
-  const readRc = () => {
-    if (!fs2.existsSync(rcPath)) return {};
-    try {
-      return JSON.parse(fs2.readFileSync(rcPath, "utf-8"));
-    } catch {
-      return {};
-    }
-  };
-  const writeRc = (data) => {
-    fs2.writeFileSync(rcPath, JSON.stringify(data, null, 2) + "\n");
-    addToGitignore(".connectbaserc");
-  };
-  let secretKey = config.secretKey;
-  if (!secretKey) {
-    info("Public Key \uBC1C\uAE09\uC744 \uC704\uD574 \uBE0C\uB77C\uC6B0\uC800 \uC778\uC99D\uC744 \uC2DC\uC791\uD569\uB2C8\uB2E4...");
-    secretKey = await browserAuthFlow();
-    const rc2 = readRc();
-    rc2.secretKey = secretKey;
-    writeRc(rc2);
-    config.secretKey = secretKey;
-  }
-  const savedAppId = readRc().tunnelAppId || "";
-  const resolved = await resolveApp(secretKey, baseUrl, savedAppId);
-  let publicKey = resolved.publicKey;
-  if (!publicKey) {
-    info("Public Key \uBC1C\uAE09 \uC911...");
-    const res = await makeRequest(
-      `${baseUrl}/v1/public/cli/apps/${resolved.appId}/public-keys`,
-      "POST",
-      { "X-Public-Key": secretKey },
-      JSON.stringify({ name: "CLI Docs Key" })
-    );
-    if (res.status !== 201) {
-      const data2 = res.data;
-      const detail = data2?.error || data2?.message || `HTTP ${res.status}`;
-      error(`Public Key \uBC1C\uAE09 \uC2E4\uD328: ${detail}`);
-      process.exit(1);
-    }
-    const data = res.data;
-    if (!data.key) {
-      error("Public Key \uBC1C\uAE09 \uC751\uB2F5\uC774 \uBE44\uC5B4 \uC788\uC2B5\uB2C8\uB2E4");
-      process.exit(1);
-    }
-    publicKey = data.key;
-    success("Public Key \uBC1C\uAE09 \uC644\uB8CC");
-  }
-  const rc = readRc();
-  let changed = false;
-  if (rc.publicKey !== publicKey) {
-    rc.publicKey = publicKey;
-    changed = true;
-  }
-  if (rc.tunnelAppId !== resolved.appId) {
-    rc.tunnelAppId = resolved.appId;
-    changed = true;
-  }
-  if (changed) writeRc(rc);
-  config.publicKey = publicKey;
-  return publicKey;
-}
 async function downloadDocs(publicKey, templates, baseDir) {
   if (!baseDir) {
     baseDir = getProjectRoot();
@@ -1629,6 +1565,41 @@ ${colors.blue}?${colors.reset} \uC571 \uC120\uD0DD (\uBC88\uD638): `);
   success(`\uC571 \uC0DD\uC131 \uC644\uB8CC: ${createData.app_name}`);
   return { appId: createData.app_id, publicKey: createData.public_key };
 }
+async function registerEndpointBinding(baseUrl, appId, secretKey, tunnelUrl, label, description) {
+  try {
+    const u = new URL(tunnelUrl);
+    const host = u.hostname;
+    const tunnelId = host.replace(/\.tunnel\.connectbase\.world$/, "");
+    if (!tunnelId || tunnelId === host) {
+      log(`${colors.yellow}\u26A0  tunnel_id \uCD94\uCD9C \uC2E4\uD328 (${tunnelUrl}) \u2014 endpoint \uC790\uB3D9 \uB4F1\uB85D skip${colors.reset}`);
+      return;
+    }
+    const apiBase = baseUrl.replace(/\/+$/, "");
+    const res = await fetch(`${apiBase}/v1/apps/${encodeURIComponent(appId)}/endpoints/cli`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${secretKey}`
+      },
+      body: JSON.stringify({
+        label,
+        tunnel_id: tunnelId,
+        description: description ?? `CLI tunnel start (${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)})`
+      })
+    });
+    if (res.status === 201) {
+      success(`Endpoint "${label}" \uC790\uB3D9 \uB4F1\uB85D \uC644\uB8CC`);
+      log(`${colors.green}\u2192${colors.reset} SDK: ${colors.cyan}cb.endpoint.call("${label}", { path: "/...", method: "POST", body: ... })${colors.reset}`);
+    } else if (res.status === 409) {
+      log(`${colors.yellow}\u26A0  "${label}" \uB77C\uBCA8\uC774 \uC774\uBBF8 \uB4F1\uB85D\uB418\uC5B4 \uC788\uC2B5\uB2C8\uB2E4.${colors.reset} \uC0C8 tunnel_id \uB85C \uAC31\uC2E0\uD558\uB824\uBA74 \uCF58\uC194\uC5D0\uC11C \uC218\uB3D9 PATCH.`);
+    } else {
+      const text = await res.text().catch(() => "");
+      log(`${colors.yellow}\u26A0  endpoint \uB4F1\uB85D \uC2E4\uD328 (status ${res.status}): ${text}${colors.reset}`);
+    }
+  } catch (err) {
+    log(`${colors.yellow}\u26A0  endpoint \uB4F1\uB85D \uC911 \uC5D0\uB7EC: ${err instanceof Error ? err.message : err}${colors.reset}`);
+  }
+}
 function acquireTunnelLock2(appID, port, force) {
   const result = acquireTunnelLock(appID, port, force, VERSION);
   if (result && result.startsWith("LOCKED:")) {
@@ -1860,6 +1831,16 @@ ${colors.dim}\uC678\uBD80 \uC9C1\uC811 \uD638\uCD9C \uC2DC \uB2E4\uC74C \uD5E4\u
           log(`${colors.dim}  $ curl -H "X-Proxy-Token: ${proxyToken}" ${tunnelUrl}/${colors.reset}`);
           log(`${colors.dim}  $ curl "${tunnelUrl}/?proxy_token=${proxyToken}"${colors.reset}`);
         }
+        if (tunnelOpts?.label && tunnelUrl) {
+          void registerEndpointBinding(
+            config.baseUrl,
+            appId,
+            tunnelKey,
+            tunnelUrl,
+            tunnelOpts.label,
+            tunnelOpts.description
+          );
+        }
         log(`
 ${colors.dim}Ctrl+C\uB85C \uC885\uB8CC${colors.reset}
 `);
@@ -2032,6 +2013,8 @@ ${colors.yellow}\uC635\uC158:${colors.reset}
   --force               \uD130\uB110 lockfile \uBB34\uC2DC (\uC911\uBCF5 \uC2E4\uD589 \uAC15\uC81C, tunnel \uC804\uC6A9)
   --public              proxy_token \uAC80\uC99D \uBE44\uD65C\uC131\uD654 \u2014 \uC6F9\uD6C5/\uC678\uBD80 \uC9C1\uC811 \uD638\uCD9C\uC6A9 (tunnel \uC804\uC6A9)
   --show-token          proxy_token \uACFC curl \uC608\uC2DC\uB97C \uCD9C\uB825 (--public \uC544\uB2CC \uACBD\uC6B0)
+  --label <name>        Endpoint binding \uC790\uB3D9 \uB4F1\uB85D (tunnel \uC804\uC6A9) \u2014 SDK \uC758 cb.endpoint.call(label) \uD638\uCD9C \uAC00\uB2A5
+  --description <text>  Endpoint binding \uC124\uBA85 (--label \uB3D9\uBC18 \uC2DC\uB9CC)
   -d, --dev             Dev \uD658\uACBD\uC5D0 \uBC30\uD3EC (deploy \uC804\uC6A9)
   --check               \uBC84\uC804\uB9CC \uD655\uC778 (update \uC804\uC6A9)
   --skip-docs           \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8 \uAC74\uB108\uB6F0\uAE30 (update \uC804\uC6A9)
@@ -2165,8 +2148,7 @@ async function main() {
       setupRoot: parsed.options.setupRoot === "true"
     });
   } else if (parsed.command === "docs") {
-    const docsPublicKey = await ensureDocsPublicKey(config);
-    await downloadDocs(docsPublicKey);
+    await downloadDocs(config.publicKey || "");
   } else if (parsed.command === "mcp") {
     await setupMcp();
   } else if (parsed.command === "deploy") {
@@ -2213,6 +2195,12 @@ async function main() {
     if (parsed.options.showToken === "true") {
       tunnelOpts.showToken = true;
     }
+    if (parsed.options.label) {
+      tunnelOpts.label = parsed.options.label;
+    }
+    if (parsed.options.description) {
+      tunnelOpts.description = parsed.options.description;
+    }
     await startTunnel(port, config, tunnelOpts);
   } else {
     error(`\uC54C \uC218 \uC5C6\uB294 \uBA85\uB839\uC5B4: ${parsed.command}`);