connectbase-client 4.1.0 → 4.2.0

package/dist/index.d.mts

@@ -4440,6 +4440,27 @@ declare global {
 }
 interface NativeBridgeInterface {
     platform?: "electron" | "react-native" | "ios" | "android";
+    /** 실행 OS (react-native: 'ios' | 'android', electron: process.platform) */
+    os?: string;
+    /** 네이티브 셸에서 실행 중인지 (패키징 앱이면 항상 true) */
+    isNative?: boolean;
+    /** 브릿지 원시 호출 (문서화되지 않은 타입 호출용) */
+    call?: (type: string, payload?: unknown, options?: {
+        timeoutMs?: number;
+    }) => Promise<unknown>;
+    app?: {
+        getVersion?: () => Promise<string>;
+        getName?: () => Promise<string>;
+        getInfo?: () => Promise<NativeAppInfo>;
+        getPath?: (name: string) => Promise<string | null>;
+        reload?: () => Promise<void>;
+        quit?: () => Promise<void>;
+    };
+    browser?: {
+        openExternal: (url: string) => Promise<{
+            success: boolean;
+        }>;
+    };
     camera?: {
         takePicture: (options?: CameraOptions) => Promise<ImageResult>;
         pickImage: (options?: PickImageOptions) => Promise<ImageResult[]>;
@@ -4455,6 +4476,9 @@ interface NativeBridgeInterface {
         scheduleLocal: (options: LocalNotificationOptions) => Promise<{
             notificationId: string;
         }>;
+        setBadgeCount?: (count: number) => Promise<{
+            success: boolean;
+        }>;
     };
     speech?: {
         recognize: (options?: SpeechRecognizeOptions) => Promise<SpeechResult>;
@@ -4497,12 +4521,6 @@ interface NativeBridgeInterface {
             rewarded: boolean;
         }>;
     };
-    app?: {
-        getVersion: () => Promise<string>;
-        getName: () => Promise<string>;
-        getPath: (name: string) => Promise<string | null>;
-        quit: () => Promise<void>;
-    };
     system?: {
         getInfo: () => Promise<SystemInfo>;
         getMemory: () => Promise<MemoryInfo>;
@@ -4592,10 +4610,34 @@ interface NativeBridgeInterface {
         saveToGallery?: (uri: string) => Promise<{
             uri: string;
         }>;
+        /** 모바일: 앱 문서/캐시 디렉터리 URI */
+        getDirectories?: () => Promise<{
+            document: string | null;
+            cache: string | null;
+        }>;
+        /** 데스크톱: 접근이 허용된 앱 전용 데이터 폴더 */
+        getAppDir?: () => Promise<string>;
     };
     onDeepLink?: (callback: (url: string) => void) => () => void;
 }
 type Platform = "web" | "mobile" | "desktop";
+/** 패키징 앱 정보 (`cb.native.getAppInfo()`) */
+interface NativeAppInfo {
+    platform: string;
+    os?: string;
+    osVersion?: string;
+    arch?: string;
+    appVersion?: string;
+    electronVersion?: string;
+    webUrl?: string;
+}
+/** 위치 추적 핸들 (`cb.native.location.watchPosition()`) */
+interface LocationWatch {
+    /** 네이티브 watch 식별자 (웹 폴백에서는 geolocation watch id) */
+    watchId: string;
+    /** 추적 중지 */
+    clear: () => Promise<void>;
+}
 interface CameraOptions {
     quality?: number;
     base64?: boolean;
@@ -4748,6 +4790,20 @@ declare class NativeAPI {
      * 현재 플랫폼 감지
      */
     getPlatform(): Platform;
+    /**
+     * 패키징 앱(네이티브 셸) 안에서 실행 중인지
+     */
+    isNativeApp(): boolean;
+    /**
+     * 패키징 앱 정보 조회 (웹에서는 null)
+     *
+     * @example
+     * ```typescript
+     * const info = await cb.native.getAppInfo()
+     * // { platform: 'react-native', os: 'ios', appVersion: '1.0.0', webUrl: '...' }
+     * ```
+     */
+    getAppInfo(): Promise<NativeAppInfo | null>;
     /**
      * 특정 네이티브 기능 지원 여부 확인
      */
@@ -4835,6 +4891,42 @@ declare class NativeAPI {
          * 현재 위치 가져오기
          */
         getCurrentPosition: (options?: LocationOptions) => Promise<Position>;
+        /**
+         * 위치 추적 시작.
+         *
+         * 패키징 앱(모바일)에서는 네이티브가 `nativeLocationUpdate` 이벤트로 갱신을 보내고,
+         * 웹/데스크톱에서는 Geolocation `watchPosition` 을 사용한다.
+         *
+         * @example
+         * ```typescript
+         * const watch = await cb.native.location.watchPosition((pos) => console.log(pos))
+         * // 나중에
+         * await watch.clear()
+         * ```
+         */
+        watchPosition: (onUpdate: (position: Position) => void, options?: LocationOptions) => Promise<LocationWatch>;
+    };
+    /**
+     * 모바일 전용 푸시 API
+     *
+     * 패키징 앱은 raw 디바이스 토큰(iOS=APNS, Android=FCM)을 발급받아
+     * `cb.push.registerDevice()` 로 등록해야 서버 발송이 가능하다.
+     */
+    push: {
+        /**
+         * 네이티브 디바이스 푸시 토큰 조회.
+         * 웹(패키징 앱이 아닌 경우)에서는 null 을 반환한다.
+         */
+        getToken: () => Promise<{
+            token: string;
+            platform?: string;
+        } | null>;
+        /** 알림 권한 요청 (웹은 Web Notification 권한) */
+        requestPermission: () => Promise<boolean>;
+        /** 로컬 알림 예약 (패키징 앱 전용) */
+        scheduleLocal: (options: LocalNotificationOptions) => Promise<string | null>;
+        /** 앱 아이콘 배지 숫자 설정 (미지원 플랫폼에서는 무시) */
+        setBadgeCount: (count: number) => Promise<boolean>;
     };
     /**
      * 크로스 플랫폼 알림 API

package/dist/index.d.ts

@@ -4440,6 +4440,27 @@ declare global {
 }
 interface NativeBridgeInterface {
     platform?: "electron" | "react-native" | "ios" | "android";
+    /** 실행 OS (react-native: 'ios' | 'android', electron: process.platform) */
+    os?: string;
+    /** 네이티브 셸에서 실행 중인지 (패키징 앱이면 항상 true) */
+    isNative?: boolean;
+    /** 브릿지 원시 호출 (문서화되지 않은 타입 호출용) */
+    call?: (type: string, payload?: unknown, options?: {
+        timeoutMs?: number;
+    }) => Promise<unknown>;
+    app?: {
+        getVersion?: () => Promise<string>;
+        getName?: () => Promise<string>;
+        getInfo?: () => Promise<NativeAppInfo>;
+        getPath?: (name: string) => Promise<string | null>;
+        reload?: () => Promise<void>;
+        quit?: () => Promise<void>;
+    };
+    browser?: {
+        openExternal: (url: string) => Promise<{
+            success: boolean;
+        }>;
+    };
     camera?: {
         takePicture: (options?: CameraOptions) => Promise<ImageResult>;
         pickImage: (options?: PickImageOptions) => Promise<ImageResult[]>;
@@ -4455,6 +4476,9 @@ interface NativeBridgeInterface {
         scheduleLocal: (options: LocalNotificationOptions) => Promise<{
             notificationId: string;
         }>;
+        setBadgeCount?: (count: number) => Promise<{
+            success: boolean;
+        }>;
     };
     speech?: {
         recognize: (options?: SpeechRecognizeOptions) => Promise<SpeechResult>;
@@ -4497,12 +4521,6 @@ interface NativeBridgeInterface {
             rewarded: boolean;
         }>;
     };
-    app?: {
-        getVersion: () => Promise<string>;
-        getName: () => Promise<string>;
-        getPath: (name: string) => Promise<string | null>;
-        quit: () => Promise<void>;
-    };
     system?: {
         getInfo: () => Promise<SystemInfo>;
         getMemory: () => Promise<MemoryInfo>;
@@ -4592,10 +4610,34 @@ interface NativeBridgeInterface {
         saveToGallery?: (uri: string) => Promise<{
             uri: string;
         }>;
+        /** 모바일: 앱 문서/캐시 디렉터리 URI */
+        getDirectories?: () => Promise<{
+            document: string | null;
+            cache: string | null;
+        }>;
+        /** 데스크톱: 접근이 허용된 앱 전용 데이터 폴더 */
+        getAppDir?: () => Promise<string>;
     };
     onDeepLink?: (callback: (url: string) => void) => () => void;
 }
 type Platform = "web" | "mobile" | "desktop";
+/** 패키징 앱 정보 (`cb.native.getAppInfo()`) */
+interface NativeAppInfo {
+    platform: string;
+    os?: string;
+    osVersion?: string;
+    arch?: string;
+    appVersion?: string;
+    electronVersion?: string;
+    webUrl?: string;
+}
+/** 위치 추적 핸들 (`cb.native.location.watchPosition()`) */
+interface LocationWatch {
+    /** 네이티브 watch 식별자 (웹 폴백에서는 geolocation watch id) */
+    watchId: string;
+    /** 추적 중지 */
+    clear: () => Promise<void>;
+}
 interface CameraOptions {
     quality?: number;
     base64?: boolean;
@@ -4748,6 +4790,20 @@ declare class NativeAPI {
      * 현재 플랫폼 감지
      */
     getPlatform(): Platform;
+    /**
+     * 패키징 앱(네이티브 셸) 안에서 실행 중인지
+     */
+    isNativeApp(): boolean;
+    /**
+     * 패키징 앱 정보 조회 (웹에서는 null)
+     *
+     * @example
+     * ```typescript
+     * const info = await cb.native.getAppInfo()
+     * // { platform: 'react-native', os: 'ios', appVersion: '1.0.0', webUrl: '...' }
+     * ```
+     */
+    getAppInfo(): Promise<NativeAppInfo | null>;
     /**
      * 특정 네이티브 기능 지원 여부 확인
      */
@@ -4835,6 +4891,42 @@ declare class NativeAPI {
          * 현재 위치 가져오기
          */
         getCurrentPosition: (options?: LocationOptions) => Promise<Position>;
+        /**
+         * 위치 추적 시작.
+         *
+         * 패키징 앱(모바일)에서는 네이티브가 `nativeLocationUpdate` 이벤트로 갱신을 보내고,
+         * 웹/데스크톱에서는 Geolocation `watchPosition` 을 사용한다.
+         *
+         * @example
+         * ```typescript
+         * const watch = await cb.native.location.watchPosition((pos) => console.log(pos))
+         * // 나중에
+         * await watch.clear()
+         * ```
+         */
+        watchPosition: (onUpdate: (position: Position) => void, options?: LocationOptions) => Promise<LocationWatch>;
+    };
+    /**
+     * 모바일 전용 푸시 API
+     *
+     * 패키징 앱은 raw 디바이스 토큰(iOS=APNS, Android=FCM)을 발급받아
+     * `cb.push.registerDevice()` 로 등록해야 서버 발송이 가능하다.
+     */
+    push: {
+        /**
+         * 네이티브 디바이스 푸시 토큰 조회.
+         * 웹(패키징 앱이 아닌 경우)에서는 null 을 반환한다.
+         */
+        getToken: () => Promise<{
+            token: string;
+            platform?: string;
+        } | null>;
+        /** 알림 권한 요청 (웹은 Web Notification 권한) */
+        requestPermission: () => Promise<boolean>;
+        /** 로컬 알림 예약 (패키징 앱 전용) */
+        scheduleLocal: (options: LocalNotificationOptions) => Promise<string | null>;
+        /** 앱 아이콘 배지 숫자 설정 (미지원 플랫폼에서는 무시) */
+        setBadgeCount: (count: number) => Promise<boolean>;
     };
     /**
      * 크로스 플랫폼 알림 API

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();
+  }
   /**
    * 특정 네이티브 기능 지원 여부 확인
    */

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();
+  }
   /**
    * 특정 네이티브 기능 지원 여부 확인
    */

package/package.json

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