connectbase-client 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -3,6 +3,90 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [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.*`)
+
+앱 패키징(React Native/Electron) 셸이 제공하는 브릿지를 SDK 에서 그대로 쓸 수 있도록 빠져 있던
+네임스페이스를 채웠다. 전부 additive — 기존 코드는 변경 없이 동작한다.
+
+- `cb.native.location.watchPosition(onUpdate, options?)` / 반환된 핸들의 `clear()` — 위치 추적.
+  모바일 패키징 앱에서는 네이티브가 `nativeLocationUpdate` 이벤트로 갱신을 스트리밍하고, 웹/데스크톱은
+  Geolocation `watchPosition` 으로 폴백한다. (기존에는 SDK 에 watch 래퍼가 아예 없었고, 브릿지는
+  위치 갱신을 요청-응답으로 보내 첫 좌표 이후가 전부 유실됐다.)
+- `cb.native.push.*` — `getToken()`(raw APNS/FCM 토큰, `cb.push.registerDevice` 에 그대로 사용) /
+  `requestPermission()` / `scheduleLocal()` / `setBadgeCount()`.
+- `cb.native.getAppInfo()` — 패키징 앱의 플랫폼·OS·앱 버전·웹 URL (웹에서는 `null`).
+- `cb.native.isNativeApp()` — 패키징 앱 안에서 실행 중인지.
+- `NativeAppInfo`, `LocationWatch` 타입 export.
+
+### Changed
+
+- `cb.native.notification.show()` — 모바일 패키징 앱에서 WebView 가 지원하지 않는 Web Notification
+  API 대신 네이티브 로컬 알림으로 전달한다(푸시 기능이 켜진 앱). 기존에는 모바일에서 조용히 실패했다.
+- `cb.native.shell.openExternal()` — 모바일 패키징 앱에서 `window.open` 대신 시스템 브라우저로 연다.
+- `cb.native.filesystem.saveFile()` — 모바일에서 파일명만 넘기면 앱 문서 디렉터리에 저장된다
+  (네이티브 셸이 상대 경로를 해석). 기존에는 절대 URI 가 아니라 저장이 실패했다.
+- `NativeBridgeInterface` 타입에 `os` / `isNative` / `call` / `app.getInfo` / `app.reload` /
+  `browser.openExternal` / `filesystem.getDirectories` / `filesystem.getAppDir` /
+  `push.setBadgeCount` 추가 — 패키징 셸의 실제 브릿지 표면과 일치시켰다.
+
 ## [4.1.0] - 2026-07-25
 
 ### Added — 결제 자격증명 test/live 모드 (`payment_mode`)