@apps-in-toss/native-modules 0.0.0-dev.1752115036458 → 0.0.0-dev.1757056983098

package/src/AppsInTossModule/native-modules/eventLog.spec.ts

@@ -0,0 +1,300 @@
+import { describe, beforeEach, it, expect, vi, afterEach } from 'vitest';
+
+describe('eventLog', () => {
+  const mockEventLog = vi.fn();
+  let originalConsoleLog: typeof console.log;
+
+  // 테스트 전에 모킹 설정
+  beforeEach(() => {
+    // 각 테스트 전 모듈 캐시 초기화
+    vi.resetModules();
+
+    // 기본 모킹 설정
+    vi.doMock('react-native', () => ({
+      NativeModules: {
+        AppsInTossModule: {
+          eventLog: mockEventLog,
+          tossAppVersion: '5.208.0',
+          operationalEnvironment: 'toss',
+        },
+      },
+      Platform: {
+        OS: 'ios',
+      },
+    }));
+
+    originalConsoleLog = console.log;
+    console.log = vi.fn();
+  });
+
+  afterEach(() => {
+    console.log = originalConsoleLog;
+    vi.restoreAllMocks();
+    mockEventLog.mockReset();
+  });
+
+  it('샌드박스 환경에서는 콘솔에 로그를 출력하고 네이티브 모듈을 호출하지 않아야 한다', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '5.208.0',
+        operationalEnvironment: 'sandbox',
+      },
+    }));
+
+    const { eventLog } = await import('./eventLog.js');
+
+    const params = {
+      log_name: 'test_log',
+      log_type: 'info' as const,
+      params: {
+        key1: 'value1',
+        key2: 123,
+        key3: true,
+        key4: undefined,
+      },
+    };
+
+    await eventLog(params);
+
+    expect(console.log).toHaveBeenCalledWith('[eventLogDebug]', {
+      log_name: 'test_log',
+      log_type: 'info',
+      params: {
+        key1: 'value1',
+        key2: '123',
+        key3: 'true',
+      },
+    });
+    expect(mockEventLog).not.toHaveBeenCalled();
+  });
+
+  it('토스 환경에서는 네이티브 모듈을 호출해야 한다', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        eventLog: mockEventLog,
+        tossAppVersion: '5.208.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    const { eventLog } = await import('./eventLog.js');
+
+    const params = {
+      log_name: 'test_log',
+      log_type: 'error' as const,
+      params: {
+        key1: 'value1',
+        key2: 123,
+        key3: true,
+        key4: null,
+        key5: undefined,
+      },
+    };
+
+    await eventLog(params);
+
+    expect(mockEventLog).toHaveBeenCalledWith({
+      log_name: 'test_log',
+      log_type: 'error',
+      params: {
+        key1: 'value1',
+        key2: '123',
+        key3: 'true',
+        key4: 'null',
+      },
+    });
+    expect(console.log).not.toHaveBeenCalled();
+  });
+
+  it('undefined 값은 정규화된 파라미터에서 제외되어야 한다', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        eventLog: mockEventLog,
+        tossAppVersion: '5.208.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    const { eventLog } = await import('./eventLog.js');
+
+    const params = {
+      log_name: 'test_log',
+      log_type: 'debug' as const,
+      params: {
+        key1: 'value1',
+        key2: undefined,
+      },
+    };
+
+    await eventLog(params);
+
+    expect(mockEventLog).toHaveBeenCalledWith({
+      log_name: 'test_log',
+      log_type: 'debug',
+      params: {
+        key1: 'value1',
+      },
+    });
+  });
+
+  it('모든 값은 문자열로 변환되어야 한다', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        eventLog: mockEventLog,
+        tossAppVersion: '5.208.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    const { eventLog } = await import('./eventLog.js');
+
+    const params = {
+      log_name: 'test_log',
+      log_type: 'warn' as const,
+      params: {
+        number: 123,
+        boolean: false,
+        nullValue: null,
+        symbol: Symbol('test').toString(),
+      },
+    };
+
+    await eventLog(params);
+
+    expect(mockEventLog).toHaveBeenCalledWith({
+      log_name: 'test_log',
+      log_type: 'warn',
+      params: {
+        number: '123',
+        boolean: 'false',
+        nullValue: 'null',
+        symbol: 'Symbol(test)',
+      },
+    });
+  });
+
+  it('빈 객체가 전달되면 빈 객체를 반환해야 한다', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        eventLog: mockEventLog,
+        tossAppVersion: '5.208.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    const { eventLog } = await import('./eventLog.js');
+
+    const params = {
+      log_name: 'test_log',
+      log_type: 'info' as const,
+      params: {},
+    };
+
+    await eventLog(params);
+
+    expect(mockEventLog).toHaveBeenCalledWith({
+      log_name: 'test_log',
+      log_type: 'info',
+      params: {},
+    });
+  });
+
+  it('여러 개의 undefined 값이 있는 경우 모두 제외되어야 한다', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        eventLog: mockEventLog,
+        tossAppVersion: '5.208.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    const { eventLog } = await import('./eventLog.js');
+
+    const params = {
+      log_name: 'test_log',
+      log_type: 'debug' as const,
+      params: {
+        key1: undefined,
+        key2: undefined,
+        key3: 'value3',
+        key4: undefined,
+      },
+    };
+
+    await eventLog(params);
+
+    expect(mockEventLog).toHaveBeenCalledWith({
+      log_name: 'test_log',
+      log_type: 'debug',
+      params: {
+        key3: 'value3',
+      },
+    });
+  });
+
+  it('숫자 0과 빈 문자열은 정상적으로 문자열로 변환되어야 한다', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        eventLog: mockEventLog,
+        tossAppVersion: '5.208.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    const { eventLog } = await import('./eventLog.js');
+
+    const params = {
+      log_name: 'test_log',
+      log_type: 'info' as const,
+      params: {
+        zeroNumber: 0,
+        emptyString: '',
+        falseValue: false,
+      },
+    };
+
+    await eventLog(params);
+
+    expect(mockEventLog).toHaveBeenCalledWith({
+      log_name: 'test_log',
+      log_type: 'info',
+      params: {
+        zeroNumber: '0',
+        emptyString: '',
+        falseValue: 'false',
+      },
+    });
+  });
+
+  it('복잡한 심볼 값도 문자열로 적절히 변환되어야 한다', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        eventLog: mockEventLog,
+        tossAppVersion: '5.208.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    const { eventLog } = await import('./eventLog.js');
+
+    const testSymbol = Symbol('복잡한_테스트');
+
+    const params = {
+      log_name: 'test_log',
+      log_type: 'debug' as const,
+      params: {
+        symbolValue: testSymbol.toString(),
+      },
+    };
+
+    await eventLog(params);
+
+    expect(mockEventLog).toHaveBeenCalledWith({
+      log_name: 'test_log',
+      log_type: 'debug',
+      params: {
+        symbolValue: 'Symbol(복잡한_테스트)',
+      },
+    });
+  });
+});

package/src/AppsInTossModule/native-modules/eventLog.ts

@@ -0,0 +1,77 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { isMinVersionSupported } from './isMinVersionSupported';
+import { Primitive } from '../../types';
+
+function normalizeParams(params: Record<string, Primitive>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(params)
+      .filter(([, value]) => value !== undefined)
+      .map(([key, value]) => [key, String(value)])
+  );
+}
+
+export interface EventLogParams {
+  log_name: string;
+  log_type: 'debug' | 'info' | 'warn' | 'error' | 'screen' | 'impression' | 'click';
+  params: Record<string, Primitive>;
+}
+
+/**
+ * @category 로깅
+ * @kind function
+ * @name eventLog
+ * @description
+ * 이벤트 로그를 기록하는 함수예요.
+ *
+ * 이 함수는 앱 내에서 발생하는 다양한 이벤트를 로깅하는 데 사용돼요. 디버깅, 정보 제공, 경고, 오류 등 다양한 유형의 로그를 기록할 수 있어요. 샌드박스 환경에서는 콘솔에 로그가 출력되고, 실제 환경에서는 로그 시스템에 기록돼요.
+ *
+ * @param {Object} params 로그 기록에 필요한 매개변수 객체예요.
+ * @param {string} params.log_name 로그의 이름이에요.
+ * @param {'debug' | 'info' | 'warn' | 'error' | 'screen' | 'impression' | 'click'} params.log_type 로그의 유형이에요.
+ * @param {Record<string, Primitive>} params.params 로그에 포함할 추가 매개변수 객체예요.
+ *
+ * @returns {Promise<void>} 로그 기록이 완료되면 해결되는 Promise예요.
+ *
+ * @example
+ * ### 이벤트 로그 기록하기
+ *
+ * ```tsx
+ * import { eventLog } from '@apps-in-toss/framework';
+ *
+ * function logUserAction() {
+ *   eventLog({
+ *     log_name: 'user_action',
+ *     log_type: 'info',
+ *     params: {
+ *       action: 'button_click',
+ *       screen: 'main',
+ *       userId: 12345
+ *     }
+ *   });
+ * }
+ * ```
+ */
+export async function eventLog(params: EventLogParams) {
+  if (AppsInTossModule.operationalEnvironment === 'sandbox') {
+    console.log('[eventLogDebug]', {
+      log_name: params.log_name,
+      log_type: params.log_type,
+      params: normalizeParams(params.params),
+    });
+    return;
+  }
+
+  const isSupported = isMinVersionSupported({
+    android: '5.208.0',
+    ios: '5.208.0',
+  });
+  if (!isSupported) {
+    return;
+  }
+
+  return AppsInTossModule.eventLog({
+    log_name: params.log_name,
+    log_type: params.log_type,
+    params: normalizeParams(params.params),
+  });
+}

package/src/AppsInTossModule/native-modules/fetchAlbumPhotos.ts

@@ -0,0 +1,88 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { requestPermission } from './requestPermission';
+import { ImageResponse } from '../../types';
+
+const DEFAULT_MAX_COUNT = 10;
+const DEFAULT_MAX_WIDTH = 1024;
+
+/**
+ * 앨범 사진을 조회할 때 사용하는 옵션 타입이에요.
+ */
+export interface FetchAlbumPhotosOptions {
+  /** 가져올 사진의 최대 개수를 설정해요. 숫자를 입력하고 기본값은 10이에요. */
+  maxCount?: number;
+  /** 사진의 최대 폭을 제한해요. 단위는 픽셀이고 기본값은 1024이에요. */
+  maxWidth?: number;
+  /** 이미지를 base64 형식으로 반환할지 설정해요. 기본값은 `false`예요. */
+  base64?: boolean;
+}
+
+/**
+ * @public
+ * @category 사진
+ * @name fetchAlbumPhotos
+ * @description
+ * 사용자의 앨범에서 사진 목록을 불러오는 함수예요.
+ * 최대 개수와 해상도를 설정할 수 있고 갤러리 미리보기, 이미지 선택 기능 등에 활용할 수 있어요.
+ *
+ * @param options - 조회 옵션을 담은 객체예요.
+ * @param {number} [options.maxCount=10] 가져올 사진의 최대 개수를 설정해요. 숫자로 입력하며 기본값은 10이에요.
+ * @param {number} [options.maxWidth=1024] 사진의 최대 폭을 제한해요. 단위는 픽셀이며 기본값은 `1024`이에요.
+ * @param {boolean} [options.base64=false] 이미지를 base64 형식으로 반환할지 설정해요. 기본값은 `false`예요.
+ * @returns {Promise<ImageResponse[]>}
+ * 앨범 사진의 고유 ID와 데이터 URI를 포함한 배열을 반환해요.
+ *
+ * @example
+ * ### 사진의 최대 폭을 360px로 제한하여 가져오기
+ *
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Image, Button } from 'react-native';
+ * import { fetchAlbumPhotos } from '@apps-in-toss/framework';
+ *
+ * const base64 = true;
+ *
+ * // 앨범 사진 목록을 가져와 화면에 표시하는 컴포넌트
+ * function AlbumPhotoList() {
+ *   const [albumPhotos, setAlbumPhotos] = useState([]);
+ *
+ *   const handlePress = async () => {
+ *     try {
+ *       const response = await fetchAlbumPhotos({
+ *         base64,
+ *         maxWidth: 360,
+ *       });
+ *       setAlbumPhotos((prev) => ([...prev, ...response]));
+ *     } catch (error) {
+ *       console.error('앨범을 가져오는 데 실패했어요:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       {albumPhotos.map((image) => {
+ *         // base64 형식으로 반환된 이미지를 표시하려면 데이터 URL 스키마 Prefix를 붙여야해요.
+ *         const imageUri = base64 ? 'data:image/jpeg;base64,' + image.dataUri : image.dataUri;
+ *
+ *         return <Image source={{ uri: imageUri }} key={image.id} />;
+ *       })}
+ *       <Button title="앨범 가져오기" onPress={handlePress} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export async function fetchAlbumPhotos(options: FetchAlbumPhotosOptions): Promise<ImageResponse[]> {
+  const permissionStatus = await requestPermission({ name: 'photos', access: 'read' });
+  if (permissionStatus === 'denied') {
+    throw new Error('사진첩 권한이 거부되었어요.');
+  }
+
+  const albumPhotos = await AppsInTossModule.fetchAlbumPhotos({
+    ...options,
+    maxCount: options.maxCount ?? DEFAULT_MAX_COUNT,
+    maxWidth: options.maxWidth ?? DEFAULT_MAX_WIDTH,
+  });
+
+  return albumPhotos;
+}

package/src/AppsInTossModule/native-modules/fetchContacts.ts

@@ -0,0 +1,121 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { requestPermission } from './requestPermission';
+
+/**
+ * 연락처 정보를 나타내는 타입이에요.
+ */
+export interface ContactEntity {
+  /** 연락처 이름이에요. */
+  name: string;
+  /** 연락처 전화번호로, 문자열 형식이에요. */
+  phoneNumber: string;
+}
+
+export interface ContactResult {
+  result: ContactEntity[];
+  nextOffset: number | null;
+  done: boolean;
+}
+
+/**
+ * @public
+ * @category 연락처
+ * @name fetchContacts
+ * @description 사용자의 연락처 목록을 페이지 단위로 가져오는 함수예요.
+ * @param options - 연락처를 가져올 때 지정하는 옵션 객체예요.
+ * @param options.size - 한 번에 가져올 연락처 개수예요. 예를 들어, 10을 전달하면 최대 10개의 연락처를 가져와요.
+ * @param options.offset - 가져올 연락처의 시작 지점이에요. 처음 호출할 때는 `0`을 전달해야 해요. 이후에는 이전 호출에서 반환된 `nextOffset` 값을 사용해요.
+ * @param options.query - 추가적인 필터링 옵션이에요.
+ * @param options.query.contains - 이름에 특정 문자열이 포함된 연락처만 가져오고 싶을 때 사용해요. 이 값을 전달하지 않으면 모든 연락처를 가져와요.
+ * @returns {Promise<ContactResult>}
+ * 연락처 목록과 페이지네이션 정보를 포함한 객체를 반환해요.
+ * - `result`: 가져온 연락처 목록이에요.
+ * - `nextOffset`: 다음 호출에 사용할 오프셋 값이에요. 더 가져올 연락처가 없으면 `null`이에요.
+ * - `done`: 모든 연락처를 다 가져왔는지 여부를 나타내요. 모두 가져왔다면 `true`예요.
+ *
+ * @signature
+ * ```typescript
+ * function fetchContacts(options: {
+ *   size: number;
+ *   offset: number;
+ *   query?: {
+ *     contains?: string;
+ *   };
+ * }): Promise<ContactResult>;
+ * ```
+ *
+ * @example
+ * ### 특정 문자열이 포함된 연락처 목록 가져오기
+ *
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Text, Button } from 'react-native';
+ * import { fetchContacts, ContactEntity } from '@apps-in-toss/framework';
+ *
+ * // 특정 문자열을 포함한 연락처 목록을 가져와 화면에 표시하는 컴포넌트
+ * function ContactsList() {
+ *   const [contacts, setContacts] = useState<{
+ *     result: ContactEntity[];
+ *     nextOffset: number | null;
+ *     done: boolean;
+ *   }>({
+ *     result: [],
+ *     nextOffset: null,
+ *     done: false,
+ *   });
+ *
+ *   const handlePress = async () => {
+ *     try {
+ *       if (contacts.done) {
+ *         console.log('모든 연락처를 가져왔어요.');
+ *         return;
+ *       }
+ *
+ *       const response = await fetchContacts({
+ *         size: 10,
+ *         offset: contacts.nextOffset ?? 0,
+ *         query: { contains: '김' },
+ *       });
+ *       setContacts((prev) => ({
+ *         result: [...prev.result, ...response.result],
+ *         nextOffset: response.nextOffset,
+ *         done: response.done,
+ *       }));
+ *     } catch (error) {
+ *       console.error('연락처를 가져오는 데 실패했어요:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       {contacts.result.map((contact, index) => (
+ *         <Text key={index}>{contact.name}: {contact.phoneNumber}</Text>
+ *       ))}
+ *       <Button
+ *         title={contacts.done ? '모든 연락처를 가져왔어요.' : '다음 연락처 가져오기'}
+ *         disabled={contacts.done}
+ *         onPress={handlePress}
+ *       />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export async function fetchContacts(options: {
+  size: number;
+  offset: number;
+  query?: {
+    contains?: string;
+  };
+}): Promise<ContactResult> {
+  const permissionStatus = await requestPermission({ name: 'contacts', access: 'read' });
+  if (permissionStatus === 'denied') {
+    throw new Error('연락처 권한이 거부되었어요.');
+  }
+  const contacts = await AppsInTossModule.fetchContacts(options);
+  return {
+    result: contacts.result,
+    nextOffset: contacts.nextOffset ?? null,
+    done: contacts.done,
+  };
+}

package/src/AppsInTossModule/native-modules/getClipboardText.ts

@@ -0,0 +1,47 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { requestPermission } from './requestPermission';
+
+/**
+ * @public
+ * @category 클립보드
+ * @name getClipboardText
+ * @description 클립보드에 저장된 텍스트를 가져오는 함수예요. 복사된 텍스트를 읽어서 다른 작업에 활용할 수 있어요.
+ * @returns {Promise<string>} - 클립보드에 저장된 텍스트를 반환해요. 클립보드에 텍스트가 없으면 빈 문자열을 반환해요.
+ *
+ * @example
+ * ### 클립보드의 텍스트 가져오기
+ *
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Text, Button } from 'react-native';
+ * import { getClipboardText } from '@apps-in-toss/framework';
+ *
+ * // '붙여넣기' 버튼을 누르면 클립보드에 저장된 텍스트를 가져와 화면에 표시해요.
+ * function PasteButton() {
+ *   const [text, setText] = useState('');
+ *
+ *   const handlePress = async () => {
+ *     try {
+ *       const clipboardText = await getClipboardText();
+ *       setText(clipboardText || '클립보드에 텍스트가 없어요.');
+ *     } catch (error) {
+ *       console.error('클립보드에서 텍스트를 가져오지 못했어요:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       <Text>{text}</Text>
+ *       <Button title="붙여넣기" onPress={handlePress} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export async function getClipboardText(): Promise<string> {
+  const permissionStatus = await requestPermission({ name: 'clipboard', access: 'read' });
+  if (permissionStatus === 'denied') {
+    throw new Error('클립보드 읽기 권한이 거부되었어요.');
+  }
+  return AppsInTossModule.getClipboardText({});
+}

package/src/AppsInTossModule/native-modules/getCurrentLocation.ts

@@ -0,0 +1,65 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { requestPermission } from './requestPermission';
+import type { Accuracy, Location } from '../../types';
+
+export interface GetCurrentLocationOptions {
+  /**
+   * 위치 정보를 가져올 정확도 수준이에요.
+   */
+  accuracy: Accuracy;
+}
+/**
+ * @public
+ * @category 위치 정보
+ * @name getCurrentLocation
+ * @description 디바이스의 현재 위치 정보를 가져오는 함수예요.
+ * 위치 기반 서비스를 구현할 때 사용되고, 한 번만 호출되어 현재 위치를 즉시 반환해요.
+ * 예를 들어 지도 앱에서 사용자의 현재 위치를 한 번만 가져올 때, 날씨 앱에서 사용자의 위치를 기반으로 기상 정보를 제공할 때, 매장 찾기 기능에서 사용자의 위치를 기준으로 가까운 매장을 검색할 때 사용하면 유용해요.
+ *
+ * @param {GetCurrentLocationOptions} options 위치 정보를 가져올 때 사용하는 옵션 객체예요.
+ * @param {Accuracy} [options.accuracy] 위치 정보의 정확도 수준이에요. 정확도는 `Accuracy` 타입으로 설정돼요.
+ * @returns {Promise<Location>} 디바이스의 위치 정보가 담긴 객체를 반환해요. 자세한 내용은 [Location](/react-native/reference/native-modules/Types/Location.html)을 참고해주세요.
+ *
+ * @example
+ * ### 디바이스의 현재 위치 정보 가져오기
+ *
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Text, Button } from 'react-native';
+ * import { getCurrentLocation } from '@apps-in-toss/framework';
+ *
+ * // 현재 위치 정보를 가져와 화면에 표시하는 컴포넌트
+ * function CurrentPosition() {
+ *   const [position, setPosition] = useState(null);
+ *
+ *   const handlePress = async () => {
+ *     try {
+ *       const response = await getCurrentLocation({ accuracy: Accuracy.Balanced });
+ *       setPosition(response);
+ *     } catch (error) {
+ *       console.error('위치 정보를 가져오는 데 실패했어요:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       {position ? (
+ *         <Text>위치: {position.coords.latitude}, {position.coords.longitude}</Text>
+ *       ) : (
+ *         <Text>위치 정보를 아직 가져오지 않았어요</Text>
+ *       )}
+ *       <Button title="현재 위치 정보 가져오기" onPress={handlePress} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export async function getCurrentLocation(options: GetCurrentLocationOptions): Promise<Location> {
+  const permissionStatus = await requestPermission({ name: 'geolocation', access: 'access' });
+  if (permissionStatus === 'denied') {
+    throw new Error('위치 권한이 거부되었어요.');
+  }
+  const position = await AppsInTossModule.getCurrentLocation(options);
+
+  return position;
+}