connectbase-client 3.54.0 → 4.0.0

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [4.0.0] - 2026-07-23
+
+### Changed — ⚠️ BREAKING: MoR 결제 필드 프로바이더 중립화 + Dodo Payments 지원
+
+Paddle 전용이던 결제/구독 필드를 프로바이더 중립(MoR = Merchant of Record) 이름으로 정규화하고,
+`dodo`(Dodo Payments)를 새 MoR 프로바이더로 추가했다. 결제 엔진을 Paddle↔Dodo(향후 Polar/Lemon
+Squeezy) 간에 코드 변경 없이 바꿀 수 있다.
+
+**필드 리네임 (subscription / payment 응답·요청):**
+
+| 이전 (`paddle_*`) | 이후 (중립) |
+|---|---|
+| `paddle_price_id` | `provider_price_ref` |
+| `paddle_transaction_id` | `provider_ref` |
+| `paddle_client_token` | `client_token` |
+| `paddle_environment` | `environment` |
+| `paddle_checkout_url` | `checkout_url` |
+| `new_paddle_price_id` | `new_provider_price_ref` |
+
+**추가:**
+- checkout 응답에 `launch_mode`(`"overlay"` | `"redirect"`) — 프론트가 결제창 여는 방식을 결정
+  (Paddle=오버레이 client_token, Dodo=리다이렉트 checkout_url).
+- provider 유니온에 `"dodo"`.
+
+**마이그레이션:** `cb.subscription.create/changePlan/previewChangePlan`, `cb.payment.prepare/confirm`
+사용부에서 `paddle_price_id`→`provider_price_ref`, `paddle_transaction_id`→`provider_ref`,
+`paddle_client_token`→`client_token`, `paddle_environment`→`environment`,
+`paddle_checkout_url`→`checkout_url` 로 교체. `proration_mode`/`on_payment_failure` 값 어휘는 그대로
+(프로바이더 중립 어휘로 문서화).
+
 ## [3.54.0] - 2026-07-23
 
 ### Added — 구독 요금제 스왑 + Paddle proration (`cb.subscription.changePlan` / `previewChangePlan`)

package/dist/index.d.mts

@@ -5173,7 +5173,7 @@ declare class OAuthAPI {
     } | null>;
 }
 
-type PaymentProvider = "toss" | "stripe" | "payapp" | "paypal" | "paddle";
+type PaymentProvider = "toss" | "stripe" | "payapp" | "paypal" | "paddle" | "dodo";
 type PaymentStatus = "pending" | "ready" | "in_progress" | "done" | "canceled" | "partial_canceled" | "aborted" | "expired" | "failed";
 interface PreparePaymentRequest {
     amount: number;
@@ -5200,10 +5200,11 @@ interface PreparePaymentResponse {
     payapp_mul_no?: string;
     paypal_approve_url?: string;
     paypal_order_id?: string;
-    paddle_transaction_id?: string;
-    paddle_client_token?: string;
-    paddle_environment?: string;
-    paddle_checkout_url?: string;
+    provider_ref?: string;
+    client_token?: string;
+    environment?: string;
+    checkout_url?: string;
+    launch_mode?: "overlay" | "redirect";
 }
 interface CreateCheckoutSessionRequest {
     amount: number;
@@ -5230,7 +5231,7 @@ interface ConfirmPaymentRequest {
     amount: number;
     stripe_payment_intent_id?: string;
     paypal_order_id?: string;
-    paddle_transaction_id?: string;
+    provider_ref?: string;
 }
 interface ConfirmPaymentResponse {
     payment_id: string;
@@ -7290,7 +7291,7 @@ interface CreateSubscriptionRequest {
     /** payapp 정기결제 만료일 yyyy-mm-dd (미입력시 +10년) */
     expire_date?: string;
     /** paddle 필수: Paddle 카탈로그의 recurring price ID (pri_*) */
-    paddle_price_id?: string;
+    provider_price_ref?: string;
     /** 메타데이터 */
     metadata?: Record<string, unknown>;
 }
@@ -7300,21 +7301,22 @@ interface SubscriptionResponse {
     /** 구독 ID (문자열) */
     subscription_id: string;
     /** 결제 프로바이더 */
-    provider?: "toss" | "stripe" | "payapp" | "paypal" | "paddle";
+    provider?: "toss" | "stripe" | "payapp" | "paypal" | "paddle" | "dodo";
     /** payapp: 카드등록+1회차 결제창 URL. 이 URL로 사용자를 redirect 시킨다 (위젯 불필요) */
     payapp_pay_url?: string;
     /** paypal: 구독 승인+결제수단 등록 URL. 이 URL로 사용자를 redirect 시킨다 (위젯 불필요) */
     paypal_approve_url?: string;
     /** paddle: Paddle.js Checkout.open({transactionId})로 오버레이. 확정은 웹훅이 SoT */
-    paddle_transaction_id?: string;
+    provider_ref?: string;
     /** paddle: Paddle.js 초기화용 client-side token */
-    paddle_client_token?: string;
+    client_token?: string;
     /** paddle: sandbox | production */
-    paddle_environment?: string;
+    environment?: string;
     /** paddle: 호스티드 결제 페이지 URL (fallback) */
-    paddle_checkout_url?: string;
+    checkout_url?: string;
+    launch_mode?: "overlay" | "redirect";
     /** paddle: 현재 구독이 물린 recurring price ID (pri_*) */
-    paddle_price_id?: string;
+    provider_price_ref?: string;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -7407,7 +7409,7 @@ type OnPaymentFailure = "prevent_change" | "apply_change";
  */
 interface ChangePlanRequest {
     /** 새 recurring price ID (pri_*) — 필수 */
-    paddle_price_id: string;
+    provider_price_ref: string;
     /** 우리 표시용 플랜명 (선택) */
     plan_name?: string;
     /** 우리 표시용 플랜 설명 (선택) */
@@ -7441,7 +7443,7 @@ interface ChangePlanPreview {
     /** 다음 청구 예정일 */
     next_billed_at?: string | null;
     /** 미리보기가 반영한 새 price ID */
-    new_paddle_price_id?: string;
+    new_provider_price_ref?: string;
 }
 interface ListSubscriptionsRequest {
     /** 상태 필터 */
@@ -7755,7 +7757,7 @@ declare class SubscriptionAPI {
      * @example
      * ```typescript
      * await client.subscription.changePlan(subscriptionId, {
-     *     paddle_price_id: 'pri_family_monthly',
+     *     provider_price_ref: 'pri_family_monthly',
      *     plan_name: '가족 플랜',
      *     amount: 24900,
      *     proration_mode: 'prorated_immediately',
@@ -7777,7 +7779,7 @@ declare class SubscriptionAPI {
      * @example
      * ```typescript
      * const preview = await client.subscription.previewChangePlan(subscriptionId, {
-     *     paddle_price_id: 'pri_family_monthly',
+     *     provider_price_ref: 'pri_family_monthly',
      * })
      * // preview.immediate_charge_amount, preview.recurring_amount, preview.next_billed_at
      * ```

package/dist/index.d.ts

@@ -5173,7 +5173,7 @@ declare class OAuthAPI {
     } | null>;
 }
 
-type PaymentProvider = "toss" | "stripe" | "payapp" | "paypal" | "paddle";
+type PaymentProvider = "toss" | "stripe" | "payapp" | "paypal" | "paddle" | "dodo";
 type PaymentStatus = "pending" | "ready" | "in_progress" | "done" | "canceled" | "partial_canceled" | "aborted" | "expired" | "failed";
 interface PreparePaymentRequest {
     amount: number;
@@ -5200,10 +5200,11 @@ interface PreparePaymentResponse {
     payapp_mul_no?: string;
     paypal_approve_url?: string;
     paypal_order_id?: string;
-    paddle_transaction_id?: string;
-    paddle_client_token?: string;
-    paddle_environment?: string;
-    paddle_checkout_url?: string;
+    provider_ref?: string;
+    client_token?: string;
+    environment?: string;
+    checkout_url?: string;
+    launch_mode?: "overlay" | "redirect";
 }
 interface CreateCheckoutSessionRequest {
     amount: number;
@@ -5230,7 +5231,7 @@ interface ConfirmPaymentRequest {
     amount: number;
     stripe_payment_intent_id?: string;
     paypal_order_id?: string;
-    paddle_transaction_id?: string;
+    provider_ref?: string;
 }
 interface ConfirmPaymentResponse {
     payment_id: string;
@@ -7290,7 +7291,7 @@ interface CreateSubscriptionRequest {
     /** payapp 정기결제 만료일 yyyy-mm-dd (미입력시 +10년) */
     expire_date?: string;
     /** paddle 필수: Paddle 카탈로그의 recurring price ID (pri_*) */
-    paddle_price_id?: string;
+    provider_price_ref?: string;
     /** 메타데이터 */
     metadata?: Record<string, unknown>;
 }
@@ -7300,21 +7301,22 @@ interface SubscriptionResponse {
     /** 구독 ID (문자열) */
     subscription_id: string;
     /** 결제 프로바이더 */
-    provider?: "toss" | "stripe" | "payapp" | "paypal" | "paddle";
+    provider?: "toss" | "stripe" | "payapp" | "paypal" | "paddle" | "dodo";
     /** payapp: 카드등록+1회차 결제창 URL. 이 URL로 사용자를 redirect 시킨다 (위젯 불필요) */
     payapp_pay_url?: string;
     /** paypal: 구독 승인+결제수단 등록 URL. 이 URL로 사용자를 redirect 시킨다 (위젯 불필요) */
     paypal_approve_url?: string;
     /** paddle: Paddle.js Checkout.open({transactionId})로 오버레이. 확정은 웹훅이 SoT */
-    paddle_transaction_id?: string;
+    provider_ref?: string;
     /** paddle: Paddle.js 초기화용 client-side token */
-    paddle_client_token?: string;
+    client_token?: string;
     /** paddle: sandbox | production */
-    paddle_environment?: string;
+    environment?: string;
     /** paddle: 호스티드 결제 페이지 URL (fallback) */
-    paddle_checkout_url?: string;
+    checkout_url?: string;
+    launch_mode?: "overlay" | "redirect";
     /** paddle: 현재 구독이 물린 recurring price ID (pri_*) */
-    paddle_price_id?: string;
+    provider_price_ref?: string;
     /** 플랜 이름 */
     plan_name: string;
     /** 플랜 설명 */
@@ -7407,7 +7409,7 @@ type OnPaymentFailure = "prevent_change" | "apply_change";
  */
 interface ChangePlanRequest {
     /** 새 recurring price ID (pri_*) — 필수 */
-    paddle_price_id: string;
+    provider_price_ref: string;
     /** 우리 표시용 플랜명 (선택) */
     plan_name?: string;
     /** 우리 표시용 플랜 설명 (선택) */
@@ -7441,7 +7443,7 @@ interface ChangePlanPreview {
     /** 다음 청구 예정일 */
     next_billed_at?: string | null;
     /** 미리보기가 반영한 새 price ID */
-    new_paddle_price_id?: string;
+    new_provider_price_ref?: string;
 }
 interface ListSubscriptionsRequest {
     /** 상태 필터 */
@@ -7755,7 +7757,7 @@ declare class SubscriptionAPI {
      * @example
      * ```typescript
      * await client.subscription.changePlan(subscriptionId, {
-     *     paddle_price_id: 'pri_family_monthly',
+     *     provider_price_ref: 'pri_family_monthly',
      *     plan_name: '가족 플랜',
      *     amount: 24900,
      *     proration_mode: 'prorated_immediately',
@@ -7777,7 +7779,7 @@ declare class SubscriptionAPI {
      * @example
      * ```typescript
      * const preview = await client.subscription.previewChangePlan(subscriptionId, {
-     *     paddle_price_id: 'pri_family_monthly',
+     *     provider_price_ref: 'pri_family_monthly',
      * })
      * // preview.immediate_charge_amount, preview.recurring_amount, preview.next_billed_at
      * ```

package/dist/index.js

@@ -8873,7 +8873,7 @@ var SubscriptionAPI = class {
    * @example
    * ```typescript
    * await client.subscription.changePlan(subscriptionId, {
-   *     paddle_price_id: 'pri_family_monthly',
+   *     provider_price_ref: 'pri_family_monthly',
    *     plan_name: '가족 플랜',
    *     amount: 24900,
    *     proration_mode: 'prorated_immediately',
@@ -8901,7 +8901,7 @@ var SubscriptionAPI = class {
    * @example
    * ```typescript
    * const preview = await client.subscription.previewChangePlan(subscriptionId, {
-   *     paddle_price_id: 'pri_family_monthly',
+   *     provider_price_ref: 'pri_family_monthly',
    * })
    * // preview.immediate_charge_amount, preview.recurring_amount, preview.next_billed_at
    * ```

package/dist/index.mjs

@@ -8827,7 +8827,7 @@ var SubscriptionAPI = class {
    * @example
    * ```typescript
    * await client.subscription.changePlan(subscriptionId, {
-   *     paddle_price_id: 'pri_family_monthly',
+   *     provider_price_ref: 'pri_family_monthly',
    *     plan_name: '가족 플랜',
    *     amount: 24900,
    *     proration_mode: 'prorated_immediately',
@@ -8855,7 +8855,7 @@ var SubscriptionAPI = class {
    * @example
    * ```typescript
    * const preview = await client.subscription.previewChangePlan(subscriptionId, {
-   *     paddle_price_id: 'pri_family_monthly',
+   *     provider_price_ref: 'pri_family_monthly',
    * })
    * // preview.immediate_charge_amount, preview.recurring_amount, preview.next_billed_at
    * ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "connectbase-client",
-	"version": "3.54.0",
+	"version": "4.0.0",
 	"description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
 	"repository": {
 		"type": "git",