connectbase-client 5.1.1 → 5.2.0

package/dist/index.d.mts

@@ -5511,6 +5511,29 @@ interface PreparePaymentRequest {
      * 상품별로 세금 카테고리를 달리 할 때만 지정한다. Paddle 은 무시한다.
      */
     provider_price_ref?: string;
+    /**
+     * 이 결제에 미리 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드(Dodo Discounts / Paddle Discounts)에서 발행한다 — ConnectBase 는 코드를
+     * 전달만 하고 발행/한도/유효기간은 PG 설정이 권위다. Paddle 은 API 가 코드 대신 내부 ID 를
+     * 받으므로 서버가 코드를 조회해 해소한다.
+     *
+     * 실패는 조용히 정가로 넘어가지 않고 400 으로 거절된다:
+     * - `discount_code_invalid` — 없거나 만료/비활성 코드
+     * - `discount_code_unsupported` — 할인 코드를 지원하지 않는 프로바이더(toss/stripe/payapp/paypal)
+     *
+     * 할인이 적용되면 확정 응답의 `amount` 는 **실제 청구액**(할인 후)이고 차감분은
+     * `discount_amount` 로 온다.
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 **고객이 직접** 쿠폰을 입력하도록 허용할지(선택).
+     *
+     * 미지정이면 프로바이더 기본값을 따른다. Dodo 는 결제창마다 켜고 끌 수 있다.
+     * Paddle 오버레이는 입력칸을 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
     amount: number;
     order_name: string;
     order_id?: string;
@@ -5573,7 +5596,10 @@ interface ConfirmPaymentRequest {
 interface ConfirmPaymentResponse {
     payment_id: string;
     order_id: string;
+    /** **실제 청구된** 금액. 할인이 적용되면 준비 금액보다 작다. */
     amount: number;
+    /** 할인으로 차감된 금액(준비 금액 − 실제 청구액). 할인이 없으면 생략된다. */
+    discount_amount?: number;
     status: PaymentStatus;
     method: string;
     receipt_url?: string;
@@ -5610,6 +5636,13 @@ interface PaymentDetail {
     settlement_currency?: string;
     /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
     country?: string;
+    /** 적용된 할인 코드 (준비 시 지정한 경우). */
+    discount_code?: string;
+    /**
+     * 할인으로 차감된 금액. `amount` 는 이미 할인이 반영된 실제 청구액이므로,
+     * 정가를 표시하려면 `amount + discount_amount` 로 복원한다.
+     */
+    discount_amount?: number;
     status: PaymentStatus;
     payment_provider?: PaymentProvider;
     /** 이 결제가 사용한 자격증명 모드 (test | live). */
@@ -5719,10 +5752,23 @@ declare class PaymentAPI {
      * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
      *   window.location.href = result.payapp_pay_url
      * }
+     *
+     * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+     * const discounted = await cb.payment.prepare({
+     *   amount: 10000,
+     *   order_name: '프리미엄 1개월',
+     *   discount_code: 'LAUNCH50',   // 미리 적용
+     *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+     * })
+     * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+     * // discount_amount 는 차감분이다.
      * ```
      *
      * @remarks
      * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+     *
+     * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+     * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
      */
     prepare(data: PreparePaymentRequest): Promise<PreparePaymentResponse>;
     /**
@@ -7687,8 +7733,31 @@ interface CreateSubscriptionRequest {
     billing_cycle: BillingCycle;
     /** 결제일 (monthly: 1-28일, weekly: 0-6 요일) */
     billing_day?: number;
-    /** 트라이얼 기간 (일) */
+    /**
+     * 트라이얼(무료 체험) 기간 (일).
+     *
+     * 빌링키 모델(toss/stripe)에서는 ConnectBase 스케줄러가 체험 종료일에 첫 청구를 건다.
+     * MoR 은 PG 가 정기청구를 소유하므로 결제창 생성 시 체험 일수를 함께 보낸다:
+     * - **Dodo**: 구독마다 지정 가능(0~10000일)
+     * - **Paddle**: 트라이얼이 요금제(price)에 붙는 속성이라 구독마다 지정할 수 없다 →
+     *   400 `trial_days_unsupported`. 체험이 설정된 price 를 Paddle 대시보드에서 따로 만들어 쓴다.
+     */
     trial_days?: number;
+    /**
+     * 첫 결제에 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드에서 발행하며, 몇 주기까지 할인할지도 그쪽 설정이 정한다
+     * (예: Dodo `subscription_cycles` 로 "3개월간 50%"). ConnectBase 는 코드만 전달한다.
+     *
+     * 400 `discount_code_invalid`(없거나 만료) / `discount_code_unsupported`(미지원 프로바이더).
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 고객이 직접 쿠폰을 입력하도록 허용할지(선택).
+     * Paddle 오버레이는 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
     /** 고객 이메일 */
     customer_email?: string;
     /** 고객 이름 */
@@ -8124,7 +8193,27 @@ declare class SubscriptionAPI {
      *     billing_day: 15,  // 매월 15일 결제
      *     trial_days: 7     // 7일 무료 체험
      * })
+     *
+     * // MoR(dodo/paddle) 구독 + 할인 코드
+     * const promo = await client.subscription.create({
+     *     plan_name: '프리미엄 플랜',
+     *     amount: 9900,
+     *     billing_cycle: 'monthly',
+     *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+     *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+     *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+     * })
      * ```
+     *
+     * @remarks
+     * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+     * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+     * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+     *   체험은 요금제(price) 속성이라 구독별 지정 불가
+     * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+     *
+     * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+     * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
      */
     create(data: CreateSubscriptionRequest): Promise<SubscriptionResponse>;
     /**

package/dist/index.d.ts

@@ -5511,6 +5511,29 @@ interface PreparePaymentRequest {
      * 상품별로 세금 카테고리를 달리 할 때만 지정한다. Paddle 은 무시한다.
      */
     provider_price_ref?: string;
+    /**
+     * 이 결제에 미리 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드(Dodo Discounts / Paddle Discounts)에서 발행한다 — ConnectBase 는 코드를
+     * 전달만 하고 발행/한도/유효기간은 PG 설정이 권위다. Paddle 은 API 가 코드 대신 내부 ID 를
+     * 받으므로 서버가 코드를 조회해 해소한다.
+     *
+     * 실패는 조용히 정가로 넘어가지 않고 400 으로 거절된다:
+     * - `discount_code_invalid` — 없거나 만료/비활성 코드
+     * - `discount_code_unsupported` — 할인 코드를 지원하지 않는 프로바이더(toss/stripe/payapp/paypal)
+     *
+     * 할인이 적용되면 확정 응답의 `amount` 는 **실제 청구액**(할인 후)이고 차감분은
+     * `discount_amount` 로 온다.
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 **고객이 직접** 쿠폰을 입력하도록 허용할지(선택).
+     *
+     * 미지정이면 프로바이더 기본값을 따른다. Dodo 는 결제창마다 켜고 끌 수 있다.
+     * Paddle 오버레이는 입력칸을 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
     amount: number;
     order_name: string;
     order_id?: string;
@@ -5573,7 +5596,10 @@ interface ConfirmPaymentRequest {
 interface ConfirmPaymentResponse {
     payment_id: string;
     order_id: string;
+    /** **실제 청구된** 금액. 할인이 적용되면 준비 금액보다 작다. */
     amount: number;
+    /** 할인으로 차감된 금액(준비 금액 − 실제 청구액). 할인이 없으면 생략된다. */
+    discount_amount?: number;
     status: PaymentStatus;
     method: string;
     receipt_url?: string;
@@ -5610,6 +5636,13 @@ interface PaymentDetail {
     settlement_currency?: string;
     /** 청구 국가 ISO 3166-1 alpha-2 (MoR 제공 시) */
     country?: string;
+    /** 적용된 할인 코드 (준비 시 지정한 경우). */
+    discount_code?: string;
+    /**
+     * 할인으로 차감된 금액. `amount` 는 이미 할인이 반영된 실제 청구액이므로,
+     * 정가를 표시하려면 `amount + discount_amount` 로 복원한다.
+     */
+    discount_amount?: number;
     status: PaymentStatus;
     payment_provider?: PaymentProvider;
     /** 이 결제가 사용한 자격증명 모드 (test | live). */
@@ -5719,10 +5752,23 @@ declare class PaymentAPI {
      * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
      *   window.location.href = result.payapp_pay_url
      * }
+     *
+     * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+     * const discounted = await cb.payment.prepare({
+     *   amount: 10000,
+     *   order_name: '프리미엄 1개월',
+     *   discount_code: 'LAUNCH50',   // 미리 적용
+     *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+     * })
+     * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+     * // discount_amount 는 차감분이다.
      * ```
      *
      * @remarks
      * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+     *
+     * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+     * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
      */
     prepare(data: PreparePaymentRequest): Promise<PreparePaymentResponse>;
     /**
@@ -7687,8 +7733,31 @@ interface CreateSubscriptionRequest {
     billing_cycle: BillingCycle;
     /** 결제일 (monthly: 1-28일, weekly: 0-6 요일) */
     billing_day?: number;
-    /** 트라이얼 기간 (일) */
+    /**
+     * 트라이얼(무료 체험) 기간 (일).
+     *
+     * 빌링키 모델(toss/stripe)에서는 ConnectBase 스케줄러가 체험 종료일에 첫 청구를 건다.
+     * MoR 은 PG 가 정기청구를 소유하므로 결제창 생성 시 체험 일수를 함께 보낸다:
+     * - **Dodo**: 구독마다 지정 가능(0~10000일)
+     * - **Paddle**: 트라이얼이 요금제(price)에 붙는 속성이라 구독마다 지정할 수 없다 →
+     *   400 `trial_days_unsupported`. 체험이 설정된 price 를 Paddle 대시보드에서 따로 만들어 쓴다.
+     */
     trial_days?: number;
+    /**
+     * 첫 결제에 적용할 할인/쿠폰 코드(MoR 전용, 선택).
+     *
+     * 쿠폰은 PG 대시보드에서 발행하며, 몇 주기까지 할인할지도 그쪽 설정이 정한다
+     * (예: Dodo `subscription_cycles` 로 "3개월간 50%"). ConnectBase 는 코드만 전달한다.
+     *
+     * 400 `discount_code_invalid`(없거나 만료) / `discount_code_unsupported`(미지원 프로바이더).
+     */
+    discount_code?: string;
+    /**
+     * 호스티드 결제창에서 고객이 직접 쿠폰을 입력하도록 허용할지(선택).
+     * Paddle 오버레이는 항상 노출해 숨길 수 없으므로 `false` 는 400
+     * `discount_code_entry_unsupported` 로 거절된다.
+     */
+    allow_discount_code?: boolean;
     /** 고객 이메일 */
     customer_email?: string;
     /** 고객 이름 */
@@ -8124,7 +8193,27 @@ declare class SubscriptionAPI {
      *     billing_day: 15,  // 매월 15일 결제
      *     trial_days: 7     // 7일 무료 체험
      * })
+     *
+     * // MoR(dodo/paddle) 구독 + 할인 코드
+     * const promo = await client.subscription.create({
+     *     plan_name: '프리미엄 플랜',
+     *     amount: 9900,
+     *     billing_cycle: 'monthly',
+     *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+     *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+     *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+     * })
      * ```
+     *
+     * @remarks
+     * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+     * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+     * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+     *   체험은 요금제(price) 속성이라 구독별 지정 불가
+     * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+     *
+     * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+     * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
      */
     create(data: CreateSubscriptionRequest): Promise<SubscriptionResponse>;
     /**

package/dist/index.js

@@ -6138,10 +6138,23 @@ var PaymentAPI = class {
    * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
    *   window.location.href = result.payapp_pay_url
    * }
+   *
+   * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+   * const discounted = await cb.payment.prepare({
+   *   amount: 10000,
+   *   order_name: '프리미엄 1개월',
+   *   discount_code: 'LAUNCH50',   // 미리 적용
+   *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+   * })
+   * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+   * // discount_amount 는 차감분이다.
    * ```
    *
    * @remarks
    * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+   *
+   * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+   * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
    */
   async prepare(data) {
     const prefix = this.getPublicPrefix();
@@ -9023,7 +9036,27 @@ var SubscriptionAPI = class {
    *     billing_day: 15,  // 매월 15일 결제
    *     trial_days: 7     // 7일 무료 체험
    * })
+   *
+   * // MoR(dodo/paddle) 구독 + 할인 코드
+   * const promo = await client.subscription.create({
+   *     plan_name: '프리미엄 플랜',
+   *     amount: 9900,
+   *     billing_cycle: 'monthly',
+   *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+   *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+   *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+   * })
    * ```
+   *
+   * @remarks
+   * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+   * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+   * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+   *   체험은 요금제(price) 속성이라 구독별 지정 불가
+   * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+   *
+   * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+   * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
    */
   async create(data) {
     const prefix = this.getPublicPrefix();

package/dist/index.mjs

@@ -6089,10 +6089,23 @@ var PaymentAPI = class {
    * if (result.payment_provider === 'payapp' && result.payapp_pay_url) {
    *   window.location.href = result.payapp_pay_url
    * }
+   *
+   * // 할인 코드 (MoR: dodo/paddle) — PG 대시보드에서 발행한 코드를 그대로 넘긴다.
+   * const discounted = await cb.payment.prepare({
+   *   amount: 10000,
+   *   order_name: '프리미엄 1개월',
+   *   discount_code: 'LAUNCH50',   // 미리 적용
+   *   allow_discount_code: true,   // 결제창에서 고객이 직접 입력하는 것도 허용 (Dodo)
+   * })
+   * // 확정 후 confirm 응답의 amount 는 할인이 반영된 실제 청구액,
+   * // discount_amount 는 차감분이다.
    * ```
    *
    * @remarks
    * PayApp 은 `customer_phone` 이 필수입니다(결제요청 수신 번호). 미지정 시 서버가 거부합니다.
+   *
+   * 할인 코드는 MoR 프로바이더(dodo/paddle)에서만 지원됩니다. 그 외 프로바이더에 넘기면
+   * 정가로 조용히 청구되지 않고 400 `discount_code_unsupported` 로 거절됩니다.
    */
   async prepare(data) {
     const prefix = this.getPublicPrefix();
@@ -8974,7 +8987,27 @@ var SubscriptionAPI = class {
    *     billing_day: 15,  // 매월 15일 결제
    *     trial_days: 7     // 7일 무료 체험
    * })
+   *
+   * // MoR(dodo/paddle) 구독 + 할인 코드
+   * const promo = await client.subscription.create({
+   *     plan_name: '프리미엄 플랜',
+   *     amount: 9900,
+   *     billing_cycle: 'monthly',
+   *     provider_price_ref: 'pdt_xxxxx', // PG 카탈로그의 recurring 상품
+   *     discount_code: 'LAUNCH50',       // 첫 결제에 적용 (몇 주기까지인지는 PG 쿠폰 설정이 결정)
+   *     trial_days: 14,                  // Dodo 만 지원 — Paddle 은 400 trial_days_unsupported
+   * })
    * ```
+   *
+   * @remarks
+   * 할인 코드(`discount_code`)와 `trial_days` 의 프로바이더 지원 범위가 다릅니다:
+   * - **Dodo**: 할인 코드 O, 결제창 쿠폰 입력 토글 O, 구독별 체험 일수 O
+   * - **Paddle**: 할인 코드 O(코드→내부 ID 자동 해소), 쿠폰 입력칸은 항상 노출(숨김 불가),
+   *   체험은 요금제(price) 속성이라 구독별 지정 불가
+   * - **toss/stripe/payapp/paypal**: 할인 코드 미지원(400), 체험은 ConnectBase 스케줄러가 처리
+   *
+   * 지원하지 않는 조합은 무시되지 않고 400 으로 거절됩니다 — "쿠폰을 넣었는데 정가 청구",
+   * "체험을 줬는데 즉시 청구" 를 만들지 않기 위함입니다.
    */
   async create(data) {
     const prefix = this.getPublicPrefix();

package/package.json

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