connectbase-client 4.1.0 → 4.3.0

package/dist/index.js

@@ -5042,6 +5042,101 @@ var NativeAPI = class {
             }
           );
         });
+      },
+      /**
+       * 위치 추적 시작.
+       *
+       * 패키징 앱(모바일)에서는 네이티브가 `nativeLocationUpdate` 이벤트로 갱신을 보내고,
+       * 웹/데스크톱에서는 Geolocation `watchPosition` 을 사용한다.
+       *
+       * @example
+       * ```typescript
+       * const watch = await cb.native.location.watchPosition((pos) => console.log(pos))
+       * // 나중에
+       * await watch.clear()
+       * ```
+       */
+      watchPosition: async (onUpdate, options) => {
+        const platform = this.getPlatform();
+        const bridge = window.NativeBridge;
+        if (platform === "mobile" && bridge?.location?.watchPosition) {
+          const { watchId } = await bridge.location.watchPosition(options);
+          const handler = (event) => {
+            const detail = event.detail;
+            if (!detail || detail.watchId && detail.watchId !== watchId) return;
+            onUpdate({
+              latitude: detail.latitude,
+              longitude: detail.longitude,
+              altitude: detail.altitude,
+              accuracy: detail.accuracy,
+              timestamp: detail.timestamp
+            });
+          };
+          window.addEventListener("nativeLocationUpdate", handler);
+          return {
+            watchId,
+            clear: async () => {
+              window.removeEventListener("nativeLocationUpdate", handler);
+              await bridge.location?.stopWatch(watchId);
+            }
+          };
+        }
+        const id = navigator.geolocation.watchPosition(
+          (pos) => onUpdate({
+            latitude: pos.coords.latitude,
+            longitude: pos.coords.longitude,
+            altitude: pos.coords.altitude,
+            accuracy: pos.coords.accuracy,
+            timestamp: pos.timestamp
+          }),
+          void 0,
+          {
+            enableHighAccuracy: options?.accuracy === "high",
+            timeout: 1e4,
+            maximumAge: 0
+          }
+        );
+        return {
+          watchId: String(id),
+          clear: async () => navigator.geolocation.clearWatch(id)
+        };
+      }
+    };
+    /**
+     * 모바일 전용 푸시 API
+     *
+     * 패키징 앱은 raw 디바이스 토큰(iOS=APNS, Android=FCM)을 발급받아
+     * `cb.push.registerDevice()` 로 등록해야 서버 발송이 가능하다.
+     */
+    this.push = {
+      /**
+       * 네이티브 디바이스 푸시 토큰 조회.
+       * 웹(패키징 앱이 아닌 경우)에서는 null 을 반환한다.
+       */
+      getToken: async () => {
+        if (this.getPlatform() === "mobile" && window.NativeBridge?.push) {
+          return window.NativeBridge.push.getToken();
+        }
+        return null;
+      },
+      /** 알림 권한 요청 (웹은 Web Notification 권한) */
+      requestPermission: async () => {
+        return this.notification.requestPermission();
+      },
+      /** 로컬 알림 예약 (패키징 앱 전용) */
+      scheduleLocal: async (options) => {
+        if (this.getPlatform() === "mobile" && window.NativeBridge?.push) {
+          const result = await window.NativeBridge.push.scheduleLocal(options);
+          return result.notificationId;
+        }
+        return null;
+      },
+      /** 앱 아이콘 배지 숫자 설정 (미지원 플랫폼에서는 무시) */
+      setBadgeCount: async (count) => {
+        const setter = window.NativeBridge?.push?.setBadgeCount;
+        if (!setter) return false;
+        const result = await setter(count);
+        return result.success;
       }
     };
     /**
@@ -5057,6 +5152,16 @@ var NativeAPI = class {
           const result = await window.NativeBridge.notification.show(options);
           return result.success;
         }
+        if (platform === "mobile" && window.NativeBridge?.push?.scheduleLocal) {
+          const granted = await this.notification.requestPermission();
+          if (!granted) return false;
+          await window.NativeBridge.push.scheduleLocal({
+            title: options.title,
+            body: options.body,
+            trigger: null
+          });
+          return true;
+        }
         if (!("Notification" in window)) return false;
         if (Notification.permission !== "granted") {
           const permission = await Notification.requestPermission();
@@ -5096,6 +5201,10 @@ var NativeAPI = class {
           const result = await window.NativeBridge.shell.openExternal(url);
           return result.success;
         }
+        if (platform === "mobile" && window.NativeBridge?.browser) {
+          const result = await window.NativeBridge.browser.openExternal(url);
+          return result.success;
+        }
         window.open(url, "_blank");
         return true;
       }
@@ -5341,6 +5450,26 @@ var NativeAPI = class {
     if (bridge?.camera || window.ReactNativeWebView) return "mobile";
     return "web";
   }
+  /**
+   * 패키징 앱(네이티브 셸) 안에서 실행 중인지
+   */
+  isNativeApp() {
+    return this.getPlatform() !== "web";
+  }
+  /**
+   * 패키징 앱 정보 조회 (웹에서는 null)
+   *
+   * @example
+   * ```typescript
+   * const info = await cb.native.getAppInfo()
+   * // { platform: 'react-native', os: 'ios', appVersion: '1.0.0', webUrl: '...' }
+   * ```
+   */
+  async getAppInfo() {
+    const getInfo = this.bridge?.app?.getInfo;
+    if (!getInfo) return null;
+    return getInfo();
+  }
   /**
    * 특정 네이티브 기능 지원 여부 확인
    */
@@ -8858,14 +8987,19 @@ var SubscriptionAPI = class {
     );
   }
   /**
-   * 요금제 스왑 (플랜 변경) — Paddle(MoR) 구독 전용
+   * 요금제 스왑 (플랜 변경) — MoR(Paddle · Dodo) 구독 전용
    *
-   * 하나의 구독을 유지한 채(id 동일) 다른 recurring price 로 갈아타고 남은 금액을 Paddle proration 으로
-   * 즉시 정산합니다. 예) 혼자→가족 in-place 업그레이드 — 이미 낸 혼자 미사용분을 Paddle 이 자동 크레딧해
-   * 첫 가족 청구에서 차감합니다. 즉시청구 차액의 결제 확정은 웹훅(SoT)으로 수렴합니다.
+   * 하나의 구독을 유지한 채(id 동일) 다른 recurring price/product 로 갈아타고 남은 금액을 PG 의
+   * proration 으로 즉시 정산합니다. 예) 혼자→가족 in-place 업그레이드 — 이미 낸 혼자 미사용분을
+   * PG 가 자동 크레딧해 첫 가족 청구에서 차감합니다. 즉시청구 차액의 결제 확정은 웹훅(SoT)으로
+   * 수렴합니다.
    *
    * `proration_mode` 미지정 시 `prorated_immediately`(업그레이드 기본)가 적용됩니다.
-   * 확정 전 정산액을 보여주려면 {@link previewChangePlan} 을 먼저 호출하세요.
+   * 프로바이더가 지원하지 않는 정산 모드는 근사 대체 없이 400 `invalid_proration_mode` 입니다
+   * (지원표는 {@link ProrationMode} 참조). 확정 전 정산액을 보여주려면 {@link previewChangePlan}
+   * 을 먼저 호출하세요.
+   *
+   * toss/stripe/payapp/paypal 구독은 400 `plan_change_unsupported` 입니다.
    *
    * @param subscriptionId - 구독 ID
    * @param data - 새 price + 정산 옵션
@@ -8874,7 +9008,7 @@ var SubscriptionAPI = class {
    * @example
    * ```typescript
    * await client.subscription.changePlan(subscriptionId, {
-   *     provider_price_ref: 'pri_family_monthly',
+   *     provider_price_ref: 'pri_family_monthly', // Dodo 는 'pdt_*'
    *     plan_name: '가족 플랜',
    *     amount: 24900,
    *     proration_mode: 'prorated_immediately',
@@ -8889,12 +9023,20 @@ var SubscriptionAPI = class {
     );
   }
   /**
-   * 요금제 스왑 정산 미리보기 — 실제 적용 없이 청구/크레딧 금액만 계산 (Paddle 전용)
+   * 요금제 스왑 정산 미리보기 — 실제 적용 없이 청구/크레딧 금액만 계산 (Paddle · Dodo)
    *
-   * 세금·기존 크레딧 잔액까지 반영된 Paddle 계산값을 반환하므로, 확정 화면에
+   * 세금·기존 크레딧 잔액까지 반영된 PG 계산값을 반환하므로, 확정 화면에
    * "지금 ₩X 청구, 이후 ₩Y/주기 (다음 청구일 …)" 를 그대로 노출하면 됩니다.
    * 직접 차액을 계산하지 마세요 — 이 값이 권위입니다.
    *
+   * **금액은 반드시 짝이 되는 통화와 함께 표시하세요.** 즉시청구는 고객 표시통화
+   * (`currency`), 정기 단가는 상품 통화(`recurring_currency`, 비면 `currency` 와 동일)입니다 —
+   * MoR 의 adaptive currency 에서 둘이 다를 수 있습니다.
+   *
+   * 미리보기를 제공하지 않는 프로바이더는 400 `plan_change_preview_unsupported` 입니다.
+   * 이는 **미리보기만** 없다는 뜻이며 {@link changePlan} 자체는 동작합니다
+   * (요금제 변경 자체가 불가한 경우는 `plan_change_unsupported` 로 구분됩니다).
+   *
    * @param subscriptionId - 구독 ID
    * @param data - 새 price + 정산 옵션 ({@link changePlan} 과 동일 body)
    * @returns 정산 미리보기 (지금 청구/크레딧 · 새 정기 청구액 · 다음 청구일)
@@ -8904,7 +9046,9 @@ var SubscriptionAPI = class {
    * const preview = await client.subscription.previewChangePlan(subscriptionId, {
    *     provider_price_ref: 'pri_family_monthly',
    * })
-   * // preview.immediate_charge_amount, preview.recurring_amount, preview.next_billed_at
+   * // 통화를 함께 포맷한다 — 금액만 쓰면 다통화에서 거짓 금액이 된다
+   * format(preview.immediate_charge_amount, preview.currency)
+   * format(preview.recurring_amount, preview.recurring_currency ?? preview.currency)
    * ```
    */
   async previewChangePlan(subscriptionId, data) {

package/dist/index.mjs

@@ -4996,6 +4996,101 @@ var NativeAPI = class {
             }
           );
         });
+      },
+      /**
+       * 위치 추적 시작.
+       *
+       * 패키징 앱(모바일)에서는 네이티브가 `nativeLocationUpdate` 이벤트로 갱신을 보내고,
+       * 웹/데스크톱에서는 Geolocation `watchPosition` 을 사용한다.
+       *
+       * @example
+       * ```typescript
+       * const watch = await cb.native.location.watchPosition((pos) => console.log(pos))
+       * // 나중에
+       * await watch.clear()
+       * ```
+       */
+      watchPosition: async (onUpdate, options) => {
+        const platform = this.getPlatform();
+        const bridge = window.NativeBridge;
+        if (platform === "mobile" && bridge?.location?.watchPosition) {
+          const { watchId } = await bridge.location.watchPosition(options);
+          const handler = (event) => {
+            const detail = event.detail;
+            if (!detail || detail.watchId && detail.watchId !== watchId) return;
+            onUpdate({
+              latitude: detail.latitude,
+              longitude: detail.longitude,
+              altitude: detail.altitude,
+              accuracy: detail.accuracy,
+              timestamp: detail.timestamp
+            });
+          };
+          window.addEventListener("nativeLocationUpdate", handler);
+          return {
+            watchId,
+            clear: async () => {
+              window.removeEventListener("nativeLocationUpdate", handler);
+              await bridge.location?.stopWatch(watchId);
+            }
+          };
+        }
+        const id = navigator.geolocation.watchPosition(
+          (pos) => onUpdate({
+            latitude: pos.coords.latitude,
+            longitude: pos.coords.longitude,
+            altitude: pos.coords.altitude,
+            accuracy: pos.coords.accuracy,
+            timestamp: pos.timestamp
+          }),
+          void 0,
+          {
+            enableHighAccuracy: options?.accuracy === "high",
+            timeout: 1e4,
+            maximumAge: 0
+          }
+        );
+        return {
+          watchId: String(id),
+          clear: async () => navigator.geolocation.clearWatch(id)
+        };
+      }
+    };
+    /**
+     * 모바일 전용 푸시 API
+     *
+     * 패키징 앱은 raw 디바이스 토큰(iOS=APNS, Android=FCM)을 발급받아
+     * `cb.push.registerDevice()` 로 등록해야 서버 발송이 가능하다.
+     */
+    this.push = {
+      /**
+       * 네이티브 디바이스 푸시 토큰 조회.
+       * 웹(패키징 앱이 아닌 경우)에서는 null 을 반환한다.
+       */
+      getToken: async () => {
+        if (this.getPlatform() === "mobile" && window.NativeBridge?.push) {
+          return window.NativeBridge.push.getToken();
+        }
+        return null;
+      },
+      /** 알림 권한 요청 (웹은 Web Notification 권한) */
+      requestPermission: async () => {
+        return this.notification.requestPermission();
+      },
+      /** 로컬 알림 예약 (패키징 앱 전용) */
+      scheduleLocal: async (options) => {
+        if (this.getPlatform() === "mobile" && window.NativeBridge?.push) {
+          const result = await window.NativeBridge.push.scheduleLocal(options);
+          return result.notificationId;
+        }
+        return null;
+      },
+      /** 앱 아이콘 배지 숫자 설정 (미지원 플랫폼에서는 무시) */
+      setBadgeCount: async (count) => {
+        const setter = window.NativeBridge?.push?.setBadgeCount;
+        if (!setter) return false;
+        const result = await setter(count);
+        return result.success;
       }
     };
     /**
@@ -5011,6 +5106,16 @@ var NativeAPI = class {
           const result = await window.NativeBridge.notification.show(options);
           return result.success;
         }
+        if (platform === "mobile" && window.NativeBridge?.push?.scheduleLocal) {
+          const granted = await this.notification.requestPermission();
+          if (!granted) return false;
+          await window.NativeBridge.push.scheduleLocal({
+            title: options.title,
+            body: options.body,
+            trigger: null
+          });
+          return true;
+        }
         if (!("Notification" in window)) return false;
         if (Notification.permission !== "granted") {
           const permission = await Notification.requestPermission();
@@ -5050,6 +5155,10 @@ var NativeAPI = class {
           const result = await window.NativeBridge.shell.openExternal(url);
           return result.success;
         }
+        if (platform === "mobile" && window.NativeBridge?.browser) {
+          const result = await window.NativeBridge.browser.openExternal(url);
+          return result.success;
+        }
         window.open(url, "_blank");
         return true;
       }
@@ -5295,6 +5404,26 @@ var NativeAPI = class {
     if (bridge?.camera || window.ReactNativeWebView) return "mobile";
     return "web";
   }
+  /**
+   * 패키징 앱(네이티브 셸) 안에서 실행 중인지
+   */
+  isNativeApp() {
+    return this.getPlatform() !== "web";
+  }
+  /**
+   * 패키징 앱 정보 조회 (웹에서는 null)
+   *
+   * @example
+   * ```typescript
+   * const info = await cb.native.getAppInfo()
+   * // { platform: 'react-native', os: 'ios', appVersion: '1.0.0', webUrl: '...' }
+   * ```
+   */
+  async getAppInfo() {
+    const getInfo = this.bridge?.app?.getInfo;
+    if (!getInfo) return null;
+    return getInfo();
+  }
   /**
    * 특정 네이티브 기능 지원 여부 확인
    */
@@ -8812,14 +8941,19 @@ var SubscriptionAPI = class {
     );
   }
   /**
-   * 요금제 스왑 (플랜 변경) — Paddle(MoR) 구독 전용
+   * 요금제 스왑 (플랜 변경) — MoR(Paddle · Dodo) 구독 전용
    *
-   * 하나의 구독을 유지한 채(id 동일) 다른 recurring price 로 갈아타고 남은 금액을 Paddle proration 으로
-   * 즉시 정산합니다. 예) 혼자→가족 in-place 업그레이드 — 이미 낸 혼자 미사용분을 Paddle 이 자동 크레딧해
-   * 첫 가족 청구에서 차감합니다. 즉시청구 차액의 결제 확정은 웹훅(SoT)으로 수렴합니다.
+   * 하나의 구독을 유지한 채(id 동일) 다른 recurring price/product 로 갈아타고 남은 금액을 PG 의
+   * proration 으로 즉시 정산합니다. 예) 혼자→가족 in-place 업그레이드 — 이미 낸 혼자 미사용분을
+   * PG 가 자동 크레딧해 첫 가족 청구에서 차감합니다. 즉시청구 차액의 결제 확정은 웹훅(SoT)으로
+   * 수렴합니다.
    *
    * `proration_mode` 미지정 시 `prorated_immediately`(업그레이드 기본)가 적용됩니다.
-   * 확정 전 정산액을 보여주려면 {@link previewChangePlan} 을 먼저 호출하세요.
+   * 프로바이더가 지원하지 않는 정산 모드는 근사 대체 없이 400 `invalid_proration_mode` 입니다
+   * (지원표는 {@link ProrationMode} 참조). 확정 전 정산액을 보여주려면 {@link previewChangePlan}
+   * 을 먼저 호출하세요.
+   *
+   * toss/stripe/payapp/paypal 구독은 400 `plan_change_unsupported` 입니다.
    *
    * @param subscriptionId - 구독 ID
    * @param data - 새 price + 정산 옵션
@@ -8828,7 +8962,7 @@ var SubscriptionAPI = class {
    * @example
    * ```typescript
    * await client.subscription.changePlan(subscriptionId, {
-   *     provider_price_ref: 'pri_family_monthly',
+   *     provider_price_ref: 'pri_family_monthly', // Dodo 는 'pdt_*'
    *     plan_name: '가족 플랜',
    *     amount: 24900,
    *     proration_mode: 'prorated_immediately',
@@ -8843,12 +8977,20 @@ var SubscriptionAPI = class {
     );
   }
   /**
-   * 요금제 스왑 정산 미리보기 — 실제 적용 없이 청구/크레딧 금액만 계산 (Paddle 전용)
+   * 요금제 스왑 정산 미리보기 — 실제 적용 없이 청구/크레딧 금액만 계산 (Paddle · Dodo)
    *
-   * 세금·기존 크레딧 잔액까지 반영된 Paddle 계산값을 반환하므로, 확정 화면에
+   * 세금·기존 크레딧 잔액까지 반영된 PG 계산값을 반환하므로, 확정 화면에
    * "지금 ₩X 청구, 이후 ₩Y/주기 (다음 청구일 …)" 를 그대로 노출하면 됩니다.
    * 직접 차액을 계산하지 마세요 — 이 값이 권위입니다.
    *
+   * **금액은 반드시 짝이 되는 통화와 함께 표시하세요.** 즉시청구는 고객 표시통화
+   * (`currency`), 정기 단가는 상품 통화(`recurring_currency`, 비면 `currency` 와 동일)입니다 —
+   * MoR 의 adaptive currency 에서 둘이 다를 수 있습니다.
+   *
+   * 미리보기를 제공하지 않는 프로바이더는 400 `plan_change_preview_unsupported` 입니다.
+   * 이는 **미리보기만** 없다는 뜻이며 {@link changePlan} 자체는 동작합니다
+   * (요금제 변경 자체가 불가한 경우는 `plan_change_unsupported` 로 구분됩니다).
+   *
    * @param subscriptionId - 구독 ID
    * @param data - 새 price + 정산 옵션 ({@link changePlan} 과 동일 body)
    * @returns 정산 미리보기 (지금 청구/크레딧 · 새 정기 청구액 · 다음 청구일)
@@ -8858,7 +9000,9 @@ var SubscriptionAPI = class {
    * const preview = await client.subscription.previewChangePlan(subscriptionId, {
    *     provider_price_ref: 'pri_family_monthly',
    * })
-   * // preview.immediate_charge_amount, preview.recurring_amount, preview.next_billed_at
+   * // 통화를 함께 포맷한다 — 금액만 쓰면 다통화에서 거짓 금액이 된다
+   * format(preview.immediate_charge_amount, preview.currency)
+   * format(preview.recurring_amount, preview.recurring_currency ?? preview.currency)
    * ```
    */
   async previewChangePlan(subscriptionId, data) {

package/package.json

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