connectbase-client 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -3,6 +3,81 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [4.4.0] - 2026-07-25
+
+### Changed — `cb.publicKey.*` 를 service_role 함수에서 호출 가능 (`publickey:read` / `publickey:manage`)
+
+퍼블릭 키 단위 `payment_mode`(4.3.0)가 생긴 뒤에도 **키를 만드는 경로가 콘솔뿐**이라, "QA 빌드에는
+test 결제 키" 를 배포 파이프라인이 자동화할 수 없었다(platform-issue 019f9961). 키 관리 REST 를
+service_role 함수(`ctx.cbAdmin`)에 열고, 최소권한 스코프를 추가했다.
+
+- 함수 `management_scopes` 에 `publickey:read`(목록/모드 조회) / `publickey:manage`(생성·수정·삭제)
+  를 opt-in 하면 `ctx.cbAdmin.publicKey.*` 가 동작한다. 스코프가 없으면 403.
+- `cb.publicKey.*` 에 위임 인증 가드 추가 — Public Key(cb_pk_) 단독 인스턴스(브라우저)에서
+  호출하면 즉시 에러를 던진다(키가 자기 자신을 발급/수정하는 경로 차단). 콘솔 JWT 와
+  service_role 경로는 그대로 동작한다.
+- `cb_sk_`(시크릿 키) 단독 호출은 여전히 401 — 시크릿을 자동화/AI 컨텍스트로 흘리지 않는 정책 유지.
+
+AI 도구를 쓰는 경우 MCP `create_public_key`(`payment_mode` 파라미터 추가) /
+`list_public_keys`(신규) / `update_public_key`(신규) 로 같은 작업을 할 수 있고, 생성 응답과 목록에
+`payment_mode` 가 포함돼 "QA 키가 정말 test 인지" 되읽어 검증할 수 있다.
+
+## [4.3.0] - 2026-07-25
+
+### Added — 퍼블릭 키 단위 결제 모드 (`payment_mode`)
+
+키마다 결제 자격증명 모드를 고정할 수 있다: `inherit`(기본, 앱 설정을 따름) | `test` | `live`.
+같은 앱에서 QA 빌드는 테스트 결제, 프로덕션 빌드는 라이브 결제로 **동시에** 운영할 수 있다 —
+지금까지는 모드가 앱×프로바이더 단위 단일 값이라, 라이브 전환 이후 결제 회귀 테스트를 하려면
+콘솔에서 모드를 되돌려야 했고 그동안 실고객 결제가 테스트로 처리됐다.
+
+모드를 정하는 주체가 서버에 저장된 키 설정이라 클라이언트는 고를 수 없다 — 브라우저가 test 를
+골라 무료로 "결제 성공"을 만드는 우회는 여전히 불가능하다.
+
+- `CreatePublicKeyRequest.payment_mode`, `UpdatePublicKeyRequest.payment_mode`
+- `PublicKeyItem.payment_mode`, `CreatePublicKeyResponse.payment_mode`,
+  `UpdatePublicKeyResponse.payment_mode`
+- `PublicKeyPaymentMode` 타입 export
+
+### Added — 구독의 결제 모드 (단건결제와 대칭)
+
+구독에는 모드 필드가 아예 없어 **어떤 경로로도 테스트 구독을 만들 수 없었다** — 유일한 스위치가
+콘솔의 프로바이더 모드였고, 그것을 되돌린 사이 실고객 결제가 테스트로 처리됐다.
+
+- `CreateSubscriptionRequest.payment_mode` — 단건결제 `prepare()` 의 `payment_mode` 와 적용
+  조건이 완전히 동일하다(서버 시크릿 키 호출에서만 적용, 브라우저 공개 키 호출에서는 무시).
+- `SubscriptionResponse.payment_mode` — 이 구독이 고정한 모드. 프로바이더 중립 필드라 목록에서
+  테스트 구독과 실구독을 가를 수 있다(`environment` 는 Paddle 전용이라 쓸 수 없었다).
+- 키 단위 결제 모드는 결제뿐 아니라 **구독 생성·빌링키 발급에도 동일하게 적용**된다.
+
+### Added — 결제 금액의 통화·정산·국가 정보
+
+MoR(Paddle/Dodo)은 고객에게 **표시통화**로 청구하고 머천트에게는 환산된 **정산통화**로 지급한다.
+지금까지는 정산통화 금액이 표시통화 라벨을 달고 나가 앱이 거짓 금액을 표시할 수 있었다
+(예: `$10.10` 이 `₩1,010` 으로).
+
+- `PaymentDetail.settlement_amount` / `.settlement_currency` / `.country`
+- `PaymentListItem.currency` (기존에는 금액만 있고 통화가 없었다)
+- `SubscriptionResponse.country` / `.mode`
+- `SubscriptionPaymentResponse.provider` / `.settlement_amount` / `.settlement_currency` / `.country`
+- `ChangePlanPreview.recurring_currency` / `.settlement_amount` / `.settlement_currency`
+
+### Added — Dodo 요금제 변경 미리보기
+
+`cb.subscription.previewChangePlan()` 이 Dodo 구독에서도 동작한다(기존에는 Paddle 전용).
+
+- `ProrationMode` 에 `difference_immediately` 추가 (Dodo 전용 — 차액만 즉시 청구)
+
+### Changed
+
+- `ChangePlanPreview.currency` 는 **즉시청구액의 통화**로 명확해졌다. 새 정기 단가의 통화는
+  `recurring_currency` 를 쓴다(비어 있으면 `currency` 와 동일).
+- 프로바이더가 지원하지 않는 `proration_mode` 는 근사 대체 없이 400 `invalid_proration_mode` 다.
+  이전에는 Dodo 에서 `prorated_next_billing_period`("다음 청구일에 부과")가
+  `difference_immediately`("지금 차액 청구")로 조용히 바뀌어, 요청하지 않은 즉시 출금이 발생했다.
+- 미리보기 미지원 프로바이더의 에러 코드가 `plan_change_unsupported` → `plan_change_preview_unsupported`
+  로 분리됐다. 전자는 "요금제 변경 자체가 불가", 후자는 "미리보기만 없고 `changePlan` 은 동작"이다.
+
 ## [4.2.0] - 2026-07-25
 
 ### Added — 패키징 앱 네이티브 API 보강 (`cb.native.*`)