connectbase-client 4.4.1 → 5.1.0

package/CHANGELOG.md

@@ -3,6 +3,95 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [5.1.0] - 2026-07-30
+
+### Added — 앱 멤버 관리자 조회 `cb.appMembers` (이메일 포함)
+
+앱 소유자가 자기 앱 멤버의 이메일을 조회할 경로가 없었다 (platform-issue 019fb13c). 플랫폼은
+이메일을 보관하는데(RLS `auth.email`, 본인 `getMe().email`) 관리자 방향 읽기 경로에서만 빠져
+있었다. `cb.appMembers.list()` / `cb.appMembers.get()` 을 추가했다.
+
+```typescript
+// service_role 함수 안에서 (management_scopes: ["app_member:read"])
+// 문의로 들어온 이메일이 어느 회원인지 대조
+const found = await ctx.cbAdmin.appMembers.list(ctx.appId, { search: 'user@example.com' })
+console.log(found.total_count, found.app_members[0]?.email, found.app_members[0]?.nickname)
+
+// 자체 어드민 회원 목록
+const page = await ctx.cbAdmin.appMembers.list(ctx.appId, { page: 1, pageSize: 50 })
+
+// 회원 상세 — 로그인 수단까지
+const detail = await ctx.cbAdmin.appMembers.get(ctx.appId, found.app_members[0].id)
+console.log(detail.email, detail.identities.map((i) => i.type))  // ['GOOGLE']
+```
+
+- **서버사이드 전용**: 콘솔 JWT 또는 service_role 함수(`ctx.cbAdmin`)가 필요하다. Public Key
+  (`cb_pk_`) 단독 브라우저 인스턴스에서 호출하면 던진다 — 다른 회원의 개인정보를 클라이언트에서
+  읽는 경로를 만들지 않기 위한 의도적 제약이다. 멤버가 **자기** 정보를 볼 때는 `cb.auth.getMe()`.
+- service_role 함수에서 쓰려면 함수 `management_scopes` 에 **`app_member:read`** 를 opt-in 한다
+  (신규 스코프). 이메일을 열어주므로 어드민/CS 흐름에만 부여할 것.
+- `search` 는 **닉네임 · 이메일 · 로그인 identity(email/username)** 를 함께 부분 일치(대소문자
+  무시)한다. `total_count` 도 이 필터를 반영한다.
+- `email` 은 `app_members.email` 컬럼 우선, 비어 있으면 EMAIL identity 의 `provider_uid` 로
+  fallback 한다(backfill 이전 가입 멤버). 이메일이 정말 없는 멤버는 빈 문자열이다.
+- 쓰기(생성/삭제/정지/수정)와 활동 로그 조회는 콘솔 전용이라 이 스코프로 열리지 않는다.
+
+새 타입: `AppMemberList`, `AppMemberListItem`, `AppMemberDetail`, `AppMemberIdentitySummary`,
+`AppMemberIdentityDetail`, `AppMemberProviderType`, `ListAppMembersOptions`.
+
+관련 MCP 도구 `list_members` / `get_member` 도 같은 데이터를 돌려주며, `list_members` 에
+`search` 인자가 추가됐다.
+
+## [5.0.0] - 2026-07-27
+
+### BREAKING — AI 스트리밍 `onError` 가 문자열이 아닌 `AIError` 객체를 전달
+
+`cb.ai.chatStream` 의 `onError` 시그니처가 `(error: string) => void` 에서
+`(error: AIError) => void` 로 바뀌었다. 문자열이 필요하면 `error.message` 를 쓴다.
+`cb.realtime.stream` 의 `onError` 는 이전에도 `Error` 였고 `AIError` 가 그 하위 타입이라
+타입상 호환된다.
+
+```diff
+- onError: (err) => showError(err)
++ onError: (err) => {
++   if (err.code === 'rate_limit_exceeded') backOff(err.retryAfter ?? 30)
++   else if (err.retryable) scheduleRetry()
++   else showError(err.message)
++ }
+```
+
+### Fixed — AI 실패 시 `onError` 페이로드가 비어 있던 문제 (platform-issue 019fa21c)
+
+자체 호스팅 모델이 내려간 동안 AI 호출이 실패하면 `onError` 로 온 값을 `JSON.stringify`
+했을 때 **빈 객체 `{}`** 였다. 문서에 있는 에러 코드(`provider_timeout`,
+`rate_limit_exceeded`, `service_unavailable` …)가 하나도 오지 않아, 대응이 정반대인
+실패들(호출을 줄여야 함 / 기다렸다 재시도 / 재시도 금지)을 구분할 수 없었다.
+
+원인이 세 겹이었고 모두 고쳤다.
+
+1. **서버가 코드를 안 보냈다.** socket-server 는 모든 스트리밍 실패를 단일
+   `STREAM_ERROR` + 고정 문구로 뭉갰다. 이제 `provider_timeout` / `service_unavailable` /
+   `rate_limit_exceeded` / `quota_exceeded` / `provider_error` / `invalid_request` /
+   `config_error` / `unauthorized` / `stream_failed` 로 분류해 보낸다.
+2. **SDK 가 코드를 버렸다.** 서버가 보낸 `code` 를 무시하고 `new Error(message)` 로
+   감쌌다. 이제 `AIError` 로 정규화해 `code` · `retryable` · `status` · `provider` ·
+   `model` · `retryAfter` · `detailCode` 를 모두 보존한다.
+3. **`Error` 는 `{}` 로 직렬화된다.** `message`/`stack` 이 non-enumerable 이기 때문.
+   `AIError` · `ApiError` · `GameError` 에 `toJSON()` 을 추가해 `JSON.stringify(err)` 가
+   구조를 그대로 출력한다.
+
+### Fixed — `cb.ai.chat` 이 거절 사유를 전달하지 못하던 문제
+
+AI 에러 응답 `{"error":"provider_timeout","message":"..."}` 에서 HTTP 클라이언트가
+`error`(머신용 코드)를 사람이 읽을 메시지로 오인해, `ApiError.code` 는 `undefined` 가 되고
+진짜 `message` 는 버려졌다. 이제 코드와 메시지를 모두 보존하며, `provider`/`model` 은
+`details` 에 실린다. `{ error: "사람이 읽는 문장" }` 형태의 레거시 응답은 그대로 동작한다.
+
+### Added
+
+- `AIError` 클래스와 `AIErrorCode` 타입, `toAIError()` 헬퍼를 export.
+- 실시간 연결 종료/유실로 중단된 AI 스트림도 `service_unavailable`(retryable) 로 분류해 전달.
+
 ## [4.4.1] - 2026-07-26
 
 ### Fixed — 로그인·가입 응답의 refresh 쿠키가 저장되지 않아 세션 복구가 항상 실패하던 문제