connectbase-client 3.1.0 → 3.2.1

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.2.1] - 2026-04-29
+
+### Fixed — Docs
+
+`cb.endpoint.url(label, path)` 의 README/JSDoc 예제와 CHANGELOG `[3.2.0]` 설명을
+ConnectBase 프록시 인증 모델에 맞춰 정정. 코드 동작 변화 없음 (JSDoc / README /
+CHANGELOG 만 수정).
+
+- 3.2.0 의 `<img src={cb.endpoint.url(...)}>` / `new WebSocket(cb.endpoint.url(...))`
+  예제는 실제로는 401 — `/v1/proxy/:label/*` 가 `X-Public-Key` 헤더를 강제하고
+  쿼리 파라미터 폴백이 없어, 커스텀 헤더를 못 보내는 브라우저 네이티브 API
+  (`<img>`, native `WebSocket`, `<script src>`, `EventSource`) 는 인증 자체가
+  불가능. 잘못된 시연 코드를 제거.
+- 정정된 사용 사례:
+  - **이미지 렌더링**: `cb.endpoint.call(...)` 로 받아
+    `URL.createObjectURL(await res.blob())` 패턴 사용. 영구 URL 이 필요하면
+    `cb.storage.uploadByPath` 로 업로드.
+  - **URL 전달**: Service Worker / 백엔드 워커 / 커스텀 fetch wrapper 처럼 호출자가
+    `X-Public-Key` 헤더를 직접 부착할 수 있는 환경.
+  - **로깅·디버깅**: 라벨 → 최종 URL 매핑 확인.
+- `EndpointAPI` 클래스 / `cb.endpoint.{call,url,pollUntil}` 동작은 3.2.0 과 동일.
+
+## [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
+  (`${baseUrl}/v1/proxy/${label}${path}`) 만 조립해서 반환. URL 을 Service
+  Worker / 백엔드 워커로 넘기거나 로깅·디버깅 용도. ⚠️ `<img src>` / 네이티브
+  `WebSocket` / `<script src>` / `EventSource` 처럼 커스텀 헤더를 못 보내는
+  브라우저 API 에 직접 넘기면 401 — ConnectBase 프록시는 항상 `X-Public-Key`
+  헤더를 요구하고 쿼리 파라미터 폴백이 없음. 그 경우엔 `call()` 로 받아
+  `URL.createObjectURL(await res.blob())` 패턴 사용.
+- 신규 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)

package/README.md

@@ -883,6 +883,89 @@ 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
+URL-passing scenarios where you control the request and can attach the
+`X-Public-Key` header yourself.
+
+⚠️ **Browser-native APIs that cannot set custom headers will fail with `401`.**
+ConnectBase's proxy requires `X-Public-Key` on every call (header-only — no
+`?api_key=` fallback), so `<img src>`, `new Image()`, native `WebSocket`,
+`<script src>`, EventSource, etc. **cannot authenticate** through this URL.
+Use `cb.endpoint.call()` instead for those cases:
+
+```typescript
+// ✅ Render an image: download via call(), then convert to a blob URL
+const res = await cb.endpoint.call('comfyui-main', {
+  path: `/view?filename=${encodeURIComponent(name)}`,
+})
+img.src = URL.createObjectURL(await res.blob())
+// ...later: URL.revokeObjectURL(img.src)
+```
+
+For permanent images (works across CDN, survives tunnel restarts), upload the
+blob to `cb.storage` and use `saved.url` — see
+[`examples/ai-image-generator/`](https://github.com/connectbase-world/connectbase/tree/release/examples/ai-image-generator).
+
+When `cb.endpoint.url()` IS the right tool:
+
+- Logging / debugging the resolved tunnel URL
+- Passing the URL to a backend service or worker that will make the call with proper headers
+- Building a `RequestInfo` for a custom `fetch()` wrapper (you control headers)
+
+```typescript
+console.log(cb.endpoint.url('comfyui-main', '/prompt'))
+// → https://api.connectbase.world/v1/proxy/comfyui-main/prompt
+
+// Hand the URL to a Service Worker that injects X-Public-Key
+sw.postMessage({ url: cb.endpoint.url('comfyui-main', '/prompt'), key: PK })
+```
+
 ### Push Notifications
 
 ```typescript