connectbase-client 1.8.1 → 1.9.1

package/CHANGELOG.md

@@ -3,6 +3,65 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [1.9.1] - 2026-04-25
+
+문서 정합성 패치. 런타임 동작은 1.9.0 과 동일합니다.
+
+### Fixed — `ConnectBaseConfig.persistence` jsdoc 모순
+
+- `src/index.ts` 의 `persistence?: TokenPersistence` jsdoc 이 `@default 'localStorage'` 로 표기되어 있었지만, 실제 `HttpClient` 동작은 `?? 'none'` (메모리 저장) 으로 fallback (`src/core/http.ts:104-107`). 같은 패키지 내 [src/core/http.ts:21-29](src/core/http.ts) 의 doc-comment 는 `'none' (권장·기본값)` 으로 올바르게 표기되어 있었음.
+- IDE/타입 hint 가 잘못된 정보를 안내해 사용자가 새로고침 시 로그아웃되는 동작을 "버그" 로 오인할 수 있었음.
+- 두 doc-comment 를 일치시켜 `@default 'none'` 으로 정정. 보안·XSS 메모도 함께 명시.
+- **Behavior change 없음** — 기본 동작은 1.6.0 이후 줄곧 `'none'` 이었습니다.
+
+## [1.9.0] - 2026-04-24
+
+런타임 내구성·관측성 강화 릴리스. 공개 API 시그니처는 유지되며 모든 변경은 추가·하드닝 성격(비파괴).
+
+### Added — 요청 타임아웃 & AbortSignal
+
+- `ConnectBaseConfig.requestTimeoutMs` — 모든 HTTP 호출의 기본 타임아웃(ms). 기본 30000ms, 0/음수 시 비활성.
+- 개별 호출에서 `AbortOptions` (`signal`, `timeout`) 지원 — Storage presigned 업로드 등 장시간 호출을 외부에서 취소 가능.
+- `core/abort.ts`: `createTimeoutController`, `DEFAULT_REQUEST_TIMEOUT_MS` 유틸.
+
+### Added — 전역 에러 관찰 훅
+
+- `ConnectBaseConfig.onError` — 모든 `ApiError` / `AuthError` 발생 시 호출되는 옵저버. Sentry/Datadog 등 관측성 파이프라인 연결용.
+- 429 응답 개선: `Retry-After` 헤더(초 또는 HTTP-date)를 파싱해 `ApiError.details.retry_after_seconds` 로 전달.
+
+### Added — 응답 shape 검증 (fail-fast)
+
+- `core/validate.ts`: `assertShape` 도입. 서버가 필수 필드를 누락한 응답을 반환해도 즉시 throw 하여 이후 로직이 `undefined` 로 조용히 실패하지 않게 방어.
+- 적용 지점: `auth.signInMember`, `auth.getMe`, `payment.createCheckoutSession`, `push.registerDevice`, `queue.consume`, `subscription.create`.
+
+### Added — Presigned URL 스킴 검증 (SSRF 하드닝)
+
+- `core/url-validation.ts`: `validateExternalUrl`, `isLocalhostOrigin`.
+- `StorageAPI` presigned PUT 호출 전에 URL 스킴(https)을 검증해 서버 응답을 맹신하는 경로를 차단. localhost 허용 여부는 런타임 오리진 기반으로 자동 결정.
+
+### Changed — 에러 타입 통일
+
+- `FunctionsAPI.invokeAndWait`, `GameAPI.listRooms` / `getRoom` — `throw new Error(...)` → `throw new ApiError(status, message, code)`. `ApiError` 는 `Error` 를 상속하므로 `instanceof Error` / `.message` 로 잡던 기존 코드는 그대로 동작하며, 추가로 `error.code` / `error.statusCode` 로 분기 가능.
+- `VideoAPI` 내부 `request<T>()` — 서버의 구조화 응답 `{ error: { code, message, details } }` 을 완전히 언랩해 `ApiError(status, message, code, details)` 로 변환. timeout 도 함께 적용.
+
+### Changed — Refresh 토큰 회복성
+
+- `HttpClient` 에 지수 백오프 도입 — 연속 refresh 실패 시 500ms × 2^n (최대 30s) 동안 재요청을 차단해 서버에 실패 요청이 쏟아지는 회귀를 막는다. 성공 시 카운터 리셋.
+- Refresh 요청 자체도 `requestTimeoutMs` 로 제한.
+
+### Changed — 로깅
+
+- `RealtimeAPI`: 내부 `console.error` 를 `private logError()` 로 통일. `options.debug` opt-in 일 때만 출력되어 프로덕션 devtools 에 SDK 로그 노출이 0.
+
+### Docs
+
+- `AnalyticsAPI.flush` / `getSession`, `VideoAPI.list` / `getStreamUrl` 에 상세 JSDoc + `@example` 추가.
+
+### Compatibility
+
+- **Non-breaking**: 모든 공개 메서드 시그니처 동일. `Error` → `ApiError` 전환은 상속 관계상 기존 `catch (e: Error)` 경로에 영향 없음.
+- **Runtime behavior change**: 서버가 필수 응답 필드를 누락하는 경우, 이전 버전은 `undefined` 로 조용히 진행했지만 1.9.0 은 즉시 throw 한다. 서버 응답이 정상이라면 차이 없음.
+
 ## [1.8.1] - 2026-04-23
 
 문서 정합성 패치. SDK 런타임 동작은 1.8.0 과 동일합니다.

package/README.md

@@ -892,20 +892,53 @@ interface ConnectionState {
 ## Error Handling
 
 ```typescript
+import ConnectBase, { ApiError, AuthError } from 'connectbase-client'
+
 try {
-  await gameClient.connect()
+  await cb.auth.signInMember({ email, password })
 } catch (error) {
-  if (error instanceof Error) {
-    console.error('Connection failed:', error.message)
+  if (error instanceof ApiError) {
+    // HTTP 응답 기반 에러: status/code/details 로 분기 가능
+    if (error.statusCode === 429) {
+      const details = error.details as { retry_after_seconds?: number } | undefined
+      const retryAfter = details?.retry_after_seconds
+      // ...
+    }
+  } else if (error instanceof AuthError) {
+    // refresh 실패/토큰 만료
   }
 }
 
-// Or use event handlers
+// Game API 는 별도 이벤트 핸들러도 지원
 gameClient.on('onError', (error) => {
   console.error('Game error:', error.message)
 })
 ```
 
+### 전역 에러 관찰자 (v1.9.0+)
+
+`ConnectBase` 초기화 시 `onError` 옵션을 주면 모든 `ApiError` / `AuthError` 가 한 곳으로 모입니다. Sentry/Datadog 등 관측성 툴과 연결하기 쉽습니다.
+
+```typescript
+const cb = new ConnectBase({
+  publicKey: 'cb_pk_...',
+  onError: (error) => {
+    Sentry.captureException(error)
+  },
+})
+```
+
+### 요청 타임아웃 (v1.9.0+)
+
+기본 30초 타임아웃이 모든 HTTP 호출에 적용됩니다. `requestTimeoutMs` 로 전역 기본값을 바꾸거나, 0 이하 값을 주면 비활성화할 수 있습니다.
+
+```typescript
+const cb = new ConnectBase({
+  publicKey: 'cb_pk_...',
+  requestTimeoutMs: 60000, // 60s
+})
+```
+
 ## Best Practices
 
 ### State Synchronization