connectbase-client 3.0.1 → 3.2.0

package/CHANGELOG.md

@@ -3,6 +3,63 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.2.0] - 2026-04-29
+
+### Added — Endpoint API 헬퍼 (`pollUntil` / `url`)
+
+ComfyUI × 웹스토리지 같은 e2e 통합 패턴 (작업 제출 → 폴링 → 결과 저장) 을
+단일 진입점으로 묶기 위한 헬퍼 2개. `cb.endpoint.call()` 만으로도 가능했지만
+사용자가 매번 직접 작성하던 보일러플레이트를 SDK 가 흡수.
+
+- **`cb.endpoint.pollUntil<T>(label, init, predicate, opts)`** — long-poll 한 줄
+  처리. ComfyUI `/history/{id}`, A1111 `/sdapi/v1/progress`, 자체 큐 API 처럼
+  "작업 제출 → 폴링" 패턴 전용. `predicate` 가 값을 반환할 때까지 반복 호출,
+  HTTP 5xx/네트워크 오류는 재시도, 4xx 는 즉시 reject, `AbortSignal`/`timeoutMs`
+  지원. `parse: "json" | "text" | "none"` 으로 본문 파싱 방식 선택.
+- **`cb.endpoint.url(label, path)`** — 라벨 + path 의 최종 호출 URL 을 조립해서
+  반환. WebSocket / `<img src>` / `new Image()` 같이 SDK 의 `call()` 이 아닌
+  직접 호출이 필요할 때. `X-Public-Key` 는 자동 주입되지 않으므로 모델 서버가
+  자체 토큰으로 인증을 별도 처리해야 함 (ConnectBase 는 dumb pipe).
+- 신규 export: `PollUntilOptions` 타입.
+
+### Docs
+
+- `examples/ai-image-generator/` — UMD CDN 한 줄 + 빌드 도구 0 으로 동작하는
+  ComfyUI × 웹스토리지 스타터. SDK 로딩 실패 감지, pre-flight 키 검증, 모든
+  KSampler seed 랜덤화, cache-bust 워크플로우 fetch, AbortController 일괄 취소,
+  step indicator, localStorage 갤러리, ⌘/Ctrl+Enter 단축키 등 11가지
+  베스트프랙티스 채택.
+- `docs/integration/comfyui-web-storage.md` — e2e 통합 가이드 + "왜 이 구조가
+  정답인가" / "안티패턴 7가지".
+
+## [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

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,143 @@ 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.
+
+#### `cb.endpoint.pollUntil<T>(label, init, predicate, opts?): Promise<T>`
+
+One-line "submit job → poll for result" pattern. Repeatedly calls the same
+endpoint until `predicate` returns a value. Designed for ComfyUI `/history/{id}`,
+A1111 `/sdapi/v1/progress`, or any custom queue API.
+
+Behavior:
+- Calls `cb.endpoint.call(label, init)` and passes the parsed body to `predicate`
+- Returns `undefined` from `predicate` → wait `intervalMs` and retry
+- Returns a value from `predicate` → resolve immediately with that value
+- HTTP `5xx` / network error → retry. HTTP `4xx` → reject (job-level error)
+- `timeoutMs` exceeded or `signal` aborted → reject
+
+```typescript
+type Hist = Record<
+  string,
+  { outputs: Record<string, { images?: { filename: string }[] }> }
+>
+
+const filename = await cb.endpoint.pollUntil<string>(
+  'comfyui-main',
+  { path: `/history/${promptId}` },
+  (data: Hist) => {
+    const entry = data[promptId]
+    if (!entry) return undefined // still queued
+    for (const out of Object.values(entry.outputs)) {
+      const img = out.images?.[0]
+      if (img) return img.filename
+    }
+    return undefined
+  },
+  { intervalMs: 1000, timeoutMs: 5 * 60_000 },
+)
+```
+
+**`PollUntilOptions`**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `intervalMs` | `number` | `1500` | Poll interval in ms |
+| `timeoutMs` | `number` | `300000` (5 min) | Total timeout in ms — reject if exceeded |
+| `parse` | `'json' \| 'text' \| 'none'` | `'json'` | Body parser. `'json'` falls back to `undefined` on parse error |
+| `signal` | `AbortSignal` | — | External cancel signal — reject immediately on abort |
+
+#### `cb.endpoint.url(label, path): string`
+
+Returns the assembled call URL (`${baseUrl}/v1/proxy/${label}${path}`) for cases
+where the SDK's `call()` doesn't fit — `<img src>`, `new Image()`, native
+`WebSocket`, etc.
+
+⚠️ Direct calls do **not** get automatic `X-Public-Key` injection. If your model
+server requires authentication, your model server must validate a token of its
+own (ConnectBase is a dumb pipe, not an auth gate).
+
+```typescript
+// Render a ComfyUI output image directly into <img>
+img.src =
+  cb.endpoint.url('comfyui-main', `/view?filename=${encodeURIComponent(name)}`)
+```
+
+```typescript
+// Native WebSocket to a tunneled service
+const ws = new WebSocket(cb.endpoint.url('my-ws-server', '/socket'))
+```
+
 ### Push Notifications
 
 ```typescript

package/dist/cli.js

@@ -1565,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:")) {
@@ -1796,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}
 `);
@@ -1968,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)
@@ -2148,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}`);