@apps-in-toss/native-modules 0.0.0-dev.1752049503789 → 0.0.0-dev.1757040677030

package/src/AppsInTossModule/native-event-emitter/contactsViral.ts

@@ -0,0 +1,140 @@
+import { INTERNAL__appBridgeHandler } from './internal/appBridge';
+import { isMinVersionSupported } from '../native-modules/isMinVersionSupported';
+
+/**
+ * @public
+ * @category 친구초대
+ * @name RewardFromContactsViralEvent
+ * @description 친구에게 공유하기를 완료했을 때 지급할 리워드 정보를 담는 타입이에요. 이 타입을 사용하면 공유가 완료됐을 때 지급할 리워드 정보를 확인할 수 있어요.
+ * @property {'sendViral'} type - 이벤트의 타입이에요. `'sendViral'`은 사용자가 친구에게 공유를 완료했을 때 돌아와요.
+ * @property {Object} data - 지급할 리워드 관련 정보를 담고 있어요.
+ * @property {number} data.rewardAmount - 지급할 리워드 수량이에요. 앱인토스 콘솔에서 설정한 수량 및 금액 값이에요.
+ * @property {string} data.rewardUnit - 리워드의 단위예요. 앱인토스 콘솔에 설정된 리워드 이름인 '하트', '보석' 등이 리워드 단위예요.
+ */
+type RewardFromContactsViralEvent = {
+  type: 'sendViral';
+  data: {
+    rewardAmount: number;
+    rewardUnit: string;
+  };
+};
+
+/**
+ * @public
+ * @category 친구초대
+ * @name ContactsViralSuccessEvent
+ * @description 연락처 공유 모듈이 정상적으로 종료됐을 때 전달되는 이벤트 객체예요. 종료 이유와 함께 리워드 상태 및 남은 친구 수 등 관련 정보를 제공해요.
+ * @property {'close'} type - 이벤트의 타입이에요. `'close'`는 공유 모듈이 종료됐을 때 돌아와요.
+ * @property {Object} data - 모듈 종료와 관련된 세부 정보를 담고 있어요.
+ * @property {'clickBackButton' | 'noReward'} data.closeReason - 모듈이 종료된 이유예요. `'clickBackButton'`은 사용자가 뒤로 가기 버튼을 눌러 종료한 경우이고, `'noReward'`는 받을 수 있는 리워드가 없어서 종료된 경우예요.
+ * @property {number} data.sentRewardAmount - 사용자가 받은 전체 리워드 수량이에요.
+ * @property {number} data.sendableRewardsCount - 아직 공유할 수 있는 친구 수예요.
+ * @property {number} data.sentRewardsCount - 사용자가 공유를 완료한 친구 수예요.
+ * @property {string} data.rewardUnit - 리워드의 단위예요. 앱인토스 콘솔에 설정된 리워드 이름인 '하트', '보석' 등이 리워드 단위예요.
+ */
+type ContactsViralSuccessEvent = {
+  type: 'close';
+  data: {
+    closeReason: 'clickBackButton' | 'noReward';
+    sentRewardAmount?: number;
+    sendableRewardsCount?: number;
+    sentRewardsCount: number;
+    rewardUnit?: string;
+  };
+};
+
+type ContactsViralEvent = RewardFromContactsViralEvent | ContactsViralSuccessEvent;
+
+/**
+ * @public
+ * @category 친구초대
+ * @name ContactsViralOption
+ * @description [연락처 공유 기능](/react-native/reference/native-modules/친구초대/contactsViral.html)을 사용할 때 필요한 옵션이에요.
+ * @property {string} moduleId - 공유 리워드를 구분하는 UUID 형식의 고유 ID예요. 앱인토스 콘솔의 미니앱 > 공유 리워드 메뉴에서 확인할 수 있어요.
+ */
+type ContactsViralOption = {
+  moduleId: string;
+};
+
+/**
+ * @public
+ * @category 친구초대
+ * @name ContactsViralParams
+ * @description `ContactsViralParams`는 연락처 공유 기능을 사용할 때 전달해야 하는 파라미터 타입이에요. 옵션을 설정하고, 이벤트 및 에러 처리 콜백을 지정할 수 있어요.
+ * @property {ContactsViralOption} options - 공유 기능에 사용할 옵션 객체예요.
+ * @property {(event: ContactsViralEvent) => void} onEvent - 공유 이벤트가 발생했을 때 실행되는 함수예요. [`RewardFromContactsViralEvent`](/bedrock/reference/native-modules/친구초대/RewardFromContactsViralEvent.html) 또는 [`ContactsViralSuccessEvent`](/react-native/reference/native-modules/친구초대/ContactsViralSuccessEvent.html) 타입의 이벤트 객체가 전달돼요.
+ * @property {(error: unknown) => void} onError - 예기치 않은 에러가 발생했을 때 실행되는 함수예요.
+ */
+export interface ContactsViralParams {
+  options: ContactsViralOption;
+  onEvent: (event: ContactsViralEvent) => void;
+  onError: (error: unknown) => void;
+}
+
+/**
+ * @public
+ * @category 친구초대
+ * @name contactsViral
+ * @description 친구에게 공유하고 리워드를 받을 수 있는 기능을 제공해요. 사용자가 친구에게 공유를 완료하면 앱브릿지가 이벤트를 통해 리워드 정보를 전달해요.
+ * @param {ContactsViralParams} params - 연락처 공유 기능을 실행할 때 사용하는 파라미터예요. 옵션 설정과 이벤트 핸들러를 포함해요. 자세한 내용은 [ContactsViralParams](/bedrock/reference/native-modules/친구초대/ContactsViralParams.html) 문서를 참고하세요.
+ * @returns {() => void} 앱브릿지 cleanup 함수를 반환해요. 공유 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.
+ *
+ * @example
+ * ### 친구에게 공유하고 리워드 받기
+ *
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { Button } from 'react-native';
+ * import { contactsViral } from '@apps-in-toss/framework';
+ *
+ * function ContactsViralButton({ moduleId }: { moduleId: string }) {
+ *   const handleContactsViral = useCallback(() => {
+ *     try {
+ *       const cleanup = contactsViral({
+ *         options: { moduleId: moduleId.trim() },
+ *         onEvent: (event) => {
+ *           if (event.type === 'sendViral') {
+ *             console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
+ *           } else if (event.type === 'close') {
+ *             console.log('모듈 종료:', event.data.closeReason);
+ *           }
+ *         },
+ *         onError: (error) => {
+ *           console.error('에러 발생:', error);
+ *         },
+ *       });
+ *
+ *       return cleanup;
+ *     } catch (error) {
+ *       console.error('실행 중 에러:', error);
+ *     }
+ *   }, [moduleId]);
+ *
+ *   return <Button title="친구에게 공유하고 리워드 받기" onPress={handleContactsViral} />;
+ * }
+ * ```
+ */
+export function contactsViral(params: ContactsViralParams) {
+  const isSupported = isMinVersionSupported({
+    android: '5.223.0',
+    ios: '5.223.0',
+  });
+
+  if (!isSupported) {
+    return () => {};
+  }
+
+  const { onEvent, onError, options } = params;
+
+  const unregisterCallbacks = INTERNAL__appBridgeHandler.invokeAppBridgeMethod('contactsViral', options, {
+    onRewardFromContactsViral: (result: RewardFromContactsViralEvent['data']) => {
+      onEvent({ type: 'sendViral', data: result });
+    },
+    onSuccess: (result: ContactsViralSuccessEvent['data']) => {
+      onEvent({ type: 'close', data: result });
+    },
+    onError,
+  });
+
+  return unregisterCallbacks;
+}

package/src/AppsInTossModule/native-event-emitter/event-plugins/EntryMessageExitedEvent.ts

@@ -0,0 +1,10 @@
+import { GraniteEventDefinition } from '@granite-js/react-native';
+
+export class EntryMessageExitedEvent extends GraniteEventDefinition<undefined, undefined> {
+  name = 'entryMessageExited' as const;
+
+  remove() {}
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  listener(_: undefined) {}
+}

package/src/AppsInTossModule/native-event-emitter/event-plugins/UpdateLocationEvent.ts

@@ -0,0 +1,60 @@
+import { GraniteEventDefinition } from '@granite-js/react-native';
+import { Accuracy, Location } from '../../../types';
+import { AppsInTossModuleInstance } from '../../native-modules/AppsInTossModule';
+import { requestPermission } from '../../native-modules/requestPermission';
+import { nativeEventEmitter } from '../nativeEventEmitter';
+
+export interface StartUpdateLocationOptions {
+  /**
+   * 위치 정확도를 설정해요.
+   */
+  accuracy: Accuracy;
+  /**
+   * 위치 업데이트 주기를 밀리초(ms) 단위로 설정해요.
+   */
+  timeInterval: number;
+  /**
+   * 위치 변경 거리를 미터(m) 단위로 설정해요.
+   */
+  distanceInterval: number;
+}
+
+export class UpdateLocationEvent extends GraniteEventDefinition<StartUpdateLocationOptions, Location> {
+  name = 'updateLocationEvent' as const;
+
+  subscriptionCount = 0;
+
+  ref = {
+    remove: () => {},
+  };
+  remove() {
+    if (--this.subscriptionCount === 0) {
+      AppsInTossModuleInstance.stopUpdateLocation({});
+    }
+    this.ref.remove();
+  }
+
+  listener(
+    options: StartUpdateLocationOptions,
+    onEvent: (response: Location) => void,
+    onError: (error: unknown) => void
+  ): void {
+    requestPermission({ name: 'geolocation', access: 'access' })
+      .then((permissionStatus) => {
+        if (permissionStatus === 'denied') {
+          onError(new Error('위치 권한이 거부되었어요.'));
+          return;
+        }
+
+        // @internal
+        void AppsInTossModuleInstance.startUpdateLocation(options).catch(onError);
+        const subscription = nativeEventEmitter.addListener('updateLocation', onEvent);
+
+        this.ref = {
+          remove: () => subscription?.remove(),
+        };
+        this.subscriptionCount++;
+      })
+      .catch(onError);
+  }
+}

package/src/AppsInTossModule/native-event-emitter/index.ts

@@ -0,0 +1,5 @@
+export * from './startUpdateLocation';
+export * from './contactsViral';
+
+export { appsInTossEvent } from './appsInTossEvent';
+export { onVisibilityChangedByTransparentServiceWeb } from './internal/onVisibilityChangedByTransparentServiceWeb';

package/src/AppsInTossModule/native-event-emitter/internal/AppBridgeCallbackEvent.ts

@@ -0,0 +1,45 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import { GraniteEventDefinition } from '@granite-js/react-native';
+import { EmitterSubscription, NativeEventEmitter } from 'react-native';
+import { INTERNAL__appBridgeHandler } from './appBridge';
+import { nativeEventEmitter } from '../nativeEventEmitter';
+
+export interface AppBridgeCallbackResult {
+  name: string;
+  params?: any;
+}
+
+const UNSAFE__nativeEventEmitter = nativeEventEmitter as unknown as NativeEventEmitter;
+
+export class AppBridgeCallbackEvent extends GraniteEventDefinition<void, AppBridgeCallbackResult> {
+  private static INTERNAL__appBridgeSubscription?: EmitterSubscription;
+
+  name = 'appBridgeCallbackEvent' as const;
+
+  constructor() {
+    super();
+    this.registerAppBridgeCallbackEventListener();
+  }
+
+  remove() {}
+  listener() {}
+
+  private registerAppBridgeCallbackEventListener() {
+    if (AppBridgeCallbackEvent.INTERNAL__appBridgeSubscription != null) {
+      return;
+    }
+
+    AppBridgeCallbackEvent.INTERNAL__appBridgeSubscription = UNSAFE__nativeEventEmitter.addListener(
+      'appBridgeCallback',
+      this.ensureInvokeAppBridgeCallback
+    );
+  }
+
+  private ensureInvokeAppBridgeCallback(result: AppBridgeCallbackResult) {
+    if (typeof result === 'object' && typeof result.name === 'string') {
+      INTERNAL__appBridgeHandler.invokeAppBridgeCallback(result.name, result.params);
+    } else {
+      console.warn('Invalid app bridge callback result:', result);
+    }
+  }
+}

package/src/AppsInTossModule/native-event-emitter/internal/VisibilityChangedByTransparentServiceWebEvent.ts

@@ -0,0 +1,50 @@
+import { GraniteEventDefinition } from '@granite-js/react-native';
+import type { EmitterSubscription } from 'react-native';
+import { nativeEventEmitter } from '../nativeEventEmitter';
+
+export interface VisibilityChangedByTransparentServiceWebOptions {
+  callbackId: string;
+}
+
+export interface VisibilityChangedByTransparentServiceWebResult {
+  callbackId: string;
+  isVisible: boolean;
+}
+
+export class VisibilityChangedByTransparentServiceWebEvent extends GraniteEventDefinition<
+  VisibilityChangedByTransparentServiceWebOptions,
+  boolean
+> {
+  name = 'onVisibilityChangedByTransparentServiceWeb' as const;
+
+  subscription: EmitterSubscription | null = null;
+
+  remove() {
+    this.subscription?.remove();
+    this.subscription = null;
+  }
+
+  listener(
+    options: VisibilityChangedByTransparentServiceWebOptions,
+    onEvent: (isVisible: boolean) => void,
+    onError: (error: unknown) => void
+  ) {
+    const subscription = nativeEventEmitter.addListener('visibilityChangedByTransparentServiceWeb', (params) => {
+      if (this.isVisibilityChangedByTransparentServiceWebResult(params)) {
+        if (params.callbackId === options.callbackId) {
+          onEvent(params.isVisible);
+        }
+      } else {
+        onError(new Error('Invalid visibility changed by transparent service web result'));
+      }
+    });
+
+    this.subscription = subscription;
+  }
+
+  private isVisibilityChangedByTransparentServiceWebResult(
+    params: any
+  ): params is VisibilityChangedByTransparentServiceWebResult {
+    return typeof params === 'object' && typeof params.callbackId === 'string' && typeof params.isVisible === 'boolean';
+  }
+}

package/src/AppsInTossModule/native-event-emitter/internal/appBridge.spec.ts

@@ -0,0 +1,135 @@
+import { beforeEach, describe, expect, it, vi, type Mock } from 'vitest';
+import { INTERNAL__appBridgeHandler } from './appBridge.js';
+
+const mocks = vi.hoisted(() => {
+  const mockedNativeMethodName = 'mockedNativeMethod';
+  const mockedReturnValue = new Date().getTime();
+  const mockedNativeMethod = vi.fn().mockImplementation(async () => ({ value: mockedReturnValue }));
+
+  return { mockedNativeMethodName, mockedReturnValue, mockedNativeMethod };
+});
+
+vi.mock('react-native', () => {
+  return {
+    NativeModules: {
+      AppsInTossModule: {
+        [mocks.mockedNativeMethodName]: mocks.mockedNativeMethod,
+      },
+    },
+  };
+});
+
+describe('appBridge', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('invokeAppBridgeMethod', () => {
+    it('should register callbacks', async () => {
+      await new Promise((resolve, reject) => {
+        INTERNAL__appBridgeHandler.invokeAppBridgeMethod(
+          mocks.mockedNativeMethodName,
+          {},
+          {
+            onSuccess: resolve,
+            onError: reject,
+            onFoo: () => {},
+            onBar: () => {},
+            onBaz: () => {},
+          }
+        );
+      });
+
+      // `onSuccess` and `onError` aren't registered as callbacks
+      // because they are used as the resolve and reject of the promise.
+      //
+      // `onFoo`, `onBar`, `onBaz` are registered as callbacks (length = 3)
+      expect(INTERNAL__appBridgeHandler.getCallbackIds()).toHaveLength(3);
+    });
+
+    it('should invoke the native method with the correct parameters', async () => {
+      const task = new Promise((resolve, reject) => {
+        INTERNAL__appBridgeHandler.invokeAppBridgeMethod(
+          mocks.mockedNativeMethodName,
+          {
+            value_1: 1,
+            value_2: 2,
+            value_3: 3,
+          },
+          {
+            onSuccess: resolve,
+            onError: reject,
+            onFoo: () => {},
+            onBar: () => {},
+            onBaz: () => {},
+          }
+        );
+      });
+
+      await expect(task).resolves.toEqual({ value: mocks.mockedReturnValue });
+      expect(mocks.mockedNativeMethod).toHaveBeenCalledTimes(1);
+      expect(mocks.mockedNativeMethod).toHaveBeenCalledWith({
+        params: {
+          value_1: 1,
+          value_2: 2,
+          value_3: 3,
+        },
+        callbacks: {
+          // Callbacks are replaced with their unique IDs
+          onFoo: expect.any(String),
+          onBar: expect.any(String),
+          onBaz: expect.any(String),
+        },
+      });
+    });
+
+    it('when the native method is rejected, the error callback is called', async () => {
+      mocks.mockedNativeMethod.mockImplementationOnce(() => Promise.reject(new Error('Mocked error')));
+
+      const task = new Promise((resolve, reject) => {
+        INTERNAL__appBridgeHandler.invokeAppBridgeMethod(
+          mocks.mockedNativeMethodName,
+          {},
+          {
+            onSuccess: resolve,
+            onError: reject,
+          }
+        );
+      });
+
+      await expect(task).rejects.toThrowErrorMatchingInlineSnapshot(`[Error: Mocked error]`);
+    });
+  });
+
+  describe('invokeAppBridgeCallback', () => {
+    const CALLBACK_NAME = 'onTest';
+    let mockedCallback: Mock;
+
+    // Register a callback before invoking the callback by its ID.
+    beforeEach(() => {
+      mockedCallback = vi.fn();
+
+      return new Promise<void>((resolve, reject) => {
+        INTERNAL__appBridgeHandler.invokeAppBridgeMethod(
+          mocks.mockedNativeMethodName,
+          {},
+          {
+            onSuccess: resolve,
+            onError: reject,
+            [CALLBACK_NAME]: mockedCallback,
+          }
+        );
+      });
+    });
+
+    it('should invoke the callback with the correct parameters', async () => {
+      const callbackId = INTERNAL__appBridgeHandler.getCallbackIds().pop()!;
+      const mockedValue = new Date().getTime();
+
+      INTERNAL__appBridgeHandler.invokeAppBridgeCallback(callbackId, { value: mockedValue });
+
+      expect(mockedCallback).toHaveBeenCalledTimes(1);
+      expect(mockedCallback).toHaveBeenCalledWith({ value: mockedValue });
+    });
+  });
+});

package/src/AppsInTossModule/native-event-emitter/internal/appBridge.ts

@@ -0,0 +1,79 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import { generateUUID } from '../../../utils/generateUUID';
+import { AppsInTossModuleInstance } from '../../native-modules/AppsInTossModule';
+
+export interface AppBridgeCompatCallbacks<Result> {
+  onSuccess: (result: Result) => void;
+  onError: (reason: unknown) => void;
+}
+
+type AppBridgeCallback = (...args: any[]) => void;
+type AppBridgeCallbackId = string;
+
+const INTERNAL__callbacks = new Map<AppBridgeCallbackId, AppBridgeCallback>();
+
+function invokeAppBridgeCallback(id: string, ...args: any[]): boolean {
+  const callback = INTERNAL__callbacks.get(id);
+
+  callback?.call(null, ...args);
+
+  return Boolean(callback);
+}
+
+function invokeAppBridgeMethod<Result = any, Params = any>(
+  methodName: string,
+  params: Params,
+  callbacks: AppBridgeCompatCallbacks<Result> & Record<string, AppBridgeCallback>
+) {
+  const { onSuccess, onError, ...appBridgeCallbacks } = callbacks;
+  const { callbackMap, unregisterAll } = registerCallbacks(appBridgeCallbacks);
+
+  const promise = AppsInTossModuleInstance[methodName]({
+    params,
+    callbacks: callbackMap,
+  }) as Promise<Result>;
+
+  void promise.then(onSuccess).catch(onError);
+
+  return unregisterAll;
+}
+
+function registerCallbacks(callbacks: Record<string, AppBridgeCallback>) {
+  const callbackMap: Record<string, AppBridgeCallbackId> = {};
+
+  for (const [callbackName, callback] of Object.entries(callbacks)) {
+    const id = registerCallback(callback, callbackName);
+    callbackMap[callbackName] = id;
+  }
+
+  const unregisterAll = () => {
+    Object.values(callbackMap).forEach(unregisterCallback);
+  };
+
+  return { callbackMap, unregisterAll };
+}
+
+function registerCallback(callback: AppBridgeCallback, name = 'unnamed') {
+  const uniqueId = generateUUID();
+  const callbackId = `${uniqueId}__${name}`;
+
+  INTERNAL__callbacks.set(callbackId, callback);
+
+  return callbackId;
+}
+
+function unregisterCallback(id: string) {
+  INTERNAL__callbacks.delete(id);
+}
+
+function getCallbackIds() {
+  return Array.from(INTERNAL__callbacks.keys());
+}
+
+export const INTERNAL__appBridgeHandler = {
+  invokeAppBridgeCallback,
+  invokeAppBridgeMethod,
+  registerCallback,
+  unregisterCallback,
+  getCallbackIds,
+};

package/src/AppsInTossModule/native-event-emitter/internal/onVisibilityChangedByTransparentServiceWeb.ts

@@ -0,0 +1,20 @@
+import type { EmitterSubscription } from 'react-native';
+import { appsInTossEvent } from '../appsInTossEvent';
+import type { EventEmitterSchema } from '../types';
+
+export interface OnVisibilityChangedByTransparentServiceWebSubscription extends EmitterSubscription {
+  remove: () => void;
+}
+
+export type OnVisibilityChangedByTransparentServiceWebEventEmitter = EventEmitterSchema<
+  'visibilityChangedByTransparentServiceWeb',
+  [boolean]
+>;
+
+export function onVisibilityChangedByTransparentServiceWeb(eventParams: {
+  options: { callbackId: string };
+  onEvent: (isVisible: boolean) => void;
+  onError: (error: unknown) => void;
+}): () => void {
+  return appsInTossEvent.addEventListener('onVisibilityChangedByTransparentServiceWeb', eventParams);
+}

package/src/AppsInTossModule/native-event-emitter/nativeEventEmitter.ts

@@ -0,0 +1,35 @@
+import { NativeEventEmitter, type EmitterSubscription } from 'react-native';
+import type { OnVisibilityChangedByTransparentServiceWebEventEmitter } from './internal/onVisibilityChangedByTransparentServiceWeb';
+import type { UpdateLocationEventEmitter } from './startUpdateLocation';
+import type { EventEmitterSchema } from './types';
+import { AppsInTossModuleInstance } from '../native-modules/AppsInTossModule';
+
+type EventEmitters = UpdateLocationEventEmitter | OnVisibilityChangedByTransparentServiceWebEventEmitter;
+
+type MapOf<T> = T extends EventEmitterSchema<infer K, any> ? { [key in K]: T } : never;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type EventEmittersMap = UnionToIntersection<MapOf<EventEmitters>>;
+type EventKeys = keyof EventEmittersMap;
+type ParamOf<K extends EventKeys> = EventEmittersMap[K]['params'];
+/**
+ * @interface AppsInTossEventEmitter
+ * @description
+ * 네이티브 플랫폼에서 발생하는 이벤트들을 처리하는 NativeEventEmitter를 App In Toss 프레임워크에서 사용하는 형태에 맞게 정의한 인터페이스에요.
+ * @property {(event: EventKeys, callback: (...params: ParamOf<E>) => void) => EmitterSubscription} addListener - 이벤트 리스너를 추가하는 함수
+ * @property {(subscription: EmitterSubscription) => void} removeSubscription - 이벤트 구독을 제거하는 함수
+ */
+interface AppsInTossEventEmitter {
+  addListener<Event extends EventKeys>(
+    event: Event,
+    callback: (...params: ParamOf<Event>) => void
+  ): EmitterSubscription;
+}
+
+/**
+ * @kind constant
+ * @name nativeEventEmitter
+ * @description
+ * App In Toss 프레임워크에서 제공하는 react-native의 NativeEventEmitter instance에요.
+ * @type {AppsInTossEventEmitter}
+ */
+export const nativeEventEmitter = new NativeEventEmitter(AppsInTossModuleInstance) as unknown as AppsInTossEventEmitter;

package/src/AppsInTossModule/native-event-emitter/startUpdateLocation.ts

@@ -0,0 +1,98 @@
+import type { EmitterSubscription } from 'react-native';
+import { appsInTossEvent } from './appsInTossEvent';
+import type { EventEmitterSchema } from './types';
+import type { Accuracy, Location } from '../../types';
+
+export interface StartUpdateLocationOptions {
+  /**
+   * 위치 정확도를 설정해요.
+   */
+  accuracy: Accuracy;
+  /**
+   * 위치 업데이트 주기를 밀리초(ms) 단위로 설정해요.
+   */
+  timeInterval: number;
+  /**
+   * 위치 변경 거리를 미터(m) 단위로 설정해요.
+   */
+  distanceInterval: number;
+}
+
+export interface StartUpdateLocationSubscription extends EmitterSubscription {
+  remove: () => Promise<void>;
+}
+
+/**
+ * @name UpdateLocationEventEmitter
+ * @kind typedef
+ * @description
+ * 디바이스의 위치 정보 변경을 감지해요
+ */
+export type UpdateLocationEventEmitter = EventEmitterSchema<'updateLocation', [Location]>;
+
+/**
+ * @public
+ * @category 위치 정보
+ * @name startUpdateLocation
+ * @description  디바이스의 위치 정보를 지속적으로 감지하고, 위치가 변경되면 콜백을 실행하는 함수예요. 콜백 함수를 등록하면 위치가 변경될 때마다 자동으로 호출돼요.
+ * 실시간 위치 추적이 필요한 기능을 구현할 때 사용할 수 있어요. 예를 들어 지도 앱에서 사용자의 현재 위치를 실시간으로 업데이트할 때, 운동 앱에서 사용자의 이동 거리를 기록할 때 등이에요.
+ * 위치 업데이트 주기와 정확도를 조정해 배터리 소모를 최소화하면서도 필요한 정보를 얻을 수 있어요.
+ *
+ * @param {StartUpdateLocationOptions} options - 위치 정보 감지에 필요한 설정 객체에요.
+ * @param {number} [options.accuracy] 위치 정확도를 설정해요.
+ * @param {number} [options.timeInterval] 위치 정보를 업데이트하는 최소 주기로, 단위는 밀리초(ms)예요. 이 값은 위치 업데이트가 발생하는 가장 짧은 간격을 설정하지만, 시스템이나 환경의 영향을 받아 지정한 주기보다 더 긴 간격으로 업데이트될 수 있어요.
+ * @param {number} [options.distanceInterval] 위치 변경 거리를 미터(m) 단위로 설정해요.
+ * @param {(location: Location) => void} [options.callback] 위치 정보가 변경될 때 호출되는 콜백 함수예요. 자세한 내용은 [Location](/react-native/reference/native-modules/Types/Location.html)을 참고해주세요.
+ *
+ * @example
+ * ### 위치 정보 변경 감지하기
+ *
+ * ```tsx
+ * import React, { useState, useEffect } from 'react';
+ * import { View, Text, Button } from 'react-native';
+ * import { startUpdateLocation } from '@apps-in-toss/framework';
+ *
+ * // 위치 정보 변경 감지하기
+ * function LocationWatcher() {
+ *   const [location, setLocation] = useState(null);
+ *
+ *   useEffect(() => {
+ *     return startUpdateLocation({
+ *       options: {
+ *         accuracy: Accuracy.Balanced,
+ *         timeInterval: 3000,
+ *         distanceInterval: 10,
+ *       },
+ *       onEvent: (location) => {
+ *         setLocation(location);
+ *       },
+ *       onError: (error) => {
+ *         console.error('위치 정보를 가져오는데 실패했어요:', error);
+ *       },
+ *     });
+ *   }, []);
+ *
+ *   if (location == null) {
+ *     return <Text>위치 정보를 가져오는 중이에요...</Text>;
+ *   }
+ *
+ *   return (
+ *     <View>
+ *       <Text>위도: {location.coords.latitude}</Text>
+ *       <Text>경도: {location.coords.longitude}</Text>
+ *       <Text>위치 정확도: {location.coords.accuracy}m</Text>
+ *       <Text>높이: {location.coords.altitude}m</Text>
+ *       <Text>고도 정확도: {location.coords.altitudeAccuracy}m</Text>
+ *       <Text>방향: {location.coords.heading}°</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function startUpdateLocation(eventParams: {
+  onEvent: (response: Location) => void;
+  onError: (error: unknown) => void;
+  options: StartUpdateLocationOptions;
+}): () => void {
+  return appsInTossEvent.addEventListener('updateLocationEvent', eventParams);
+}