connectbase-client 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 본 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)

package/README.md

@@ -883,6 +883,71 @@ 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