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

package/src/AppsInTossModule/native-modules/ads/types.ts

@@ -0,0 +1,106 @@
+/**
+ * @public
+ * @category 광고
+ * @name AdMobFullScreenEvent
+ * @description 앱 화면을 덮는 광고(예: 전면 광고, 보상형 광고)를 사용하는 경우에 발생하는 이벤트 타입이에요.
+ * @example
+ * ### 광고 이벤트 처리하기
+ * ```ts
+ * function handleEvent(event: AdMobFullScreenEvent) {
+ *   switch (event.type) {
+ *     case 'clicked':
+ *       console.log('광고가 클릭됐어요.');
+ *       break;
+ *
+ *     case 'dismissed':
+ *       console.log('광고가 닫혔어요.');
+ *       break;
+ *
+ *     case 'failedToShow':
+ *       console.log('광고가 보여지지 않았어요.');
+ *       break;
+ *
+ *     case 'impression':
+ *       console.log('광고가 노출됐어요.');
+ *       break;
+ *
+ *     case 'show':
+ *       console.log('광고가 보여졌어요.');
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type AdMobFullScreenEvent = AdClicked | AdDismissed | AdFailedToShow | AdImpression | AdShow;
+
+type AdClicked = { type: 'clicked' };
+type AdDismissed = { type: 'dismissed' };
+type AdFailedToShow = { type: 'failedToShow' };
+type AdImpression = { type: 'impression' };
+type AdShow = { type: 'show' };
+
+export interface AdMobHandlerParams<Options = void, Event = AdMobFullScreenEvent> {
+  options: Options;
+  onEvent: (event: Event) => void;
+  onError: (error: unknown) => void;
+}
+
+/**
+ * @public
+ * @category 광고
+ * @name ResponseInfo
+ * @description 광고 로드 응답 정보를 담고 있는 객체예요.
+ * @property {Array<AdNetworkResponseInfo>} adNetworkInfoArray 광고 네트워크 응답 정보 배열예요.
+ * @property {AdNetworkResponseInfo | null} loadedAdNetworkInfo 로드된 광고 네트워크 응답 정보예요.
+ * @property {string | null} responseId 광고 응답 ID예요.
+ */
+export interface ResponseInfo {
+  adNetworkInfoArray: Array<AdNetworkResponseInfo>;
+  loadedAdNetworkInfo: AdNetworkResponseInfo | null;
+  responseId: string | null;
+}
+
+/**
+ * @public
+ * @category 광고
+ * @name AdNetworkResponseInfo
+ * @description 광고 네트워크 응답 정보를 담고 있는 객체예요.
+ * @property {string} adSourceId 광고 소스 ID예요.
+ * @property {string} adSourceName 광고 소스 이름이예요.
+ * @property {string} adSourceInstanceId 광고 소스 인스턴스 ID예요.
+ * @property {string} adSourceInstanceName 광고 소스 인스턴스 이름이예요.
+ * @property {string | null} adNetworkClassName 광고 네트워크 클래스 이름이예요.
+ */
+export interface AdNetworkResponseInfo {
+  adSourceId: string;
+  adSourceName: string;
+  adSourceInstanceId: string;
+  adSourceInstanceName: string;
+  adNetworkClassName: string | null;
+}
+
+/**
+ * @public
+ * @category 광고
+ * @name InterstitialAd
+ * @description 전면 광고의 ID와 응답 정보를 담고 있는 객체예요. 광고를 로드한 뒤, 관련 정보를 확인할 때 유용해요.
+ * @property {string} adUnitId 광고 ID예요.
+ * @property {ResponseInfo} responseInfo 광고 로드 응답 정보예요. 자세한 내용은 [ResponseInfo](/react-native/reference/native-modules/광고/ResponseInfo.html)를 참고하세요.
+ */
+export interface InterstitialAd {
+  adUnitId: string;
+  responseInfo: ResponseInfo;
+}
+
+/**
+ * @public
+ * @category 광고
+ * @name RewardedAd
+ * @description 보상형 광고의 ID와 응답 정보를 담고 있는 객체예요. 광고를 로드한 뒤, 관련 정보를 확인할 때 유용해요.
+ * @property {string} adUnitId 광고 ID예요.
+ * @property {ResponseInfo} responseInfo 광고 로드 응답 정보예요. 자세한 내용은 [ResponseInfo](/react-native/reference/native-modules/광고/ResponseInfo.html)를 참고하세요.
+ */
+export interface RewardedAd {
+  adUnitId: string;
+  responseInfo: ResponseInfo;
+}

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

@@ -0,0 +1,29 @@
+import { AppsInTossModule } from './AppsInTossModule';
+
+/**
+ * @public
+ * @category 로그인
+ * @name appLogin
+ * @description 토스 인증으로 로그인해요. 로그인이 완료되면 다시 토스 앱으로 이동해요.
+ * @example
+ *
+ * ### 토스 인증을 통해 로그인을 하는 예제
+ *
+ * ```tsx
+ * import { Button } from 'react-native';
+ * import { appLogin } from '@apps-in-toss/framework';
+ *
+ * function Page() {
+ *   const handleLogin = async () => {
+ *     const { authorizationCode, referrer } = await appLogin();
+ *
+ *     // 획득한 인가 코드(`authorizationCode`)와 `referrer`를 서버로 전달해요.
+ *   }
+ *
+ *   return <Button title="로그인" onPress={handleLogin} />;
+ * }
+ * ```
+ */
+export async function appLogin(): Promise<{ authorizationCode: string; referrer: 'DEFAULT' | 'SANDBOX' }> {
+  return AppsInTossModule.appLogin({});
+}

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

@@ -0,0 +1,80 @@
+import { AppsInTossModule } from './AppsInTossModule';
+
+/**
+ * @public
+ * @category 토스페이
+ * @name CheckoutPaymentOptions
+ * @description 토스페이 결제창을 띄울 때 필요한 옵션이에요.
+ * @property {string} payToken 결제 토큰이에요.
+ */
+export interface CheckoutPaymentOptions {
+  /**
+   * 결제 토큰이에요.
+   */
+  payToken: string;
+}
+
+/**
+ * @public
+ * @category 토스페이
+ * @name CheckoutPaymentResult
+ * @description 토스페이 결제창에서 사용자가 인증에 성공했는지 여부예요.
+ * @property {boolean} success 인증이 성공했는지 여부예요.
+ * @property {string} [reason] 인증이 실패했을 경우의 이유예요.
+ */
+export interface CheckoutPaymentResult {
+  /**
+   * 인증이 성공했는지 여부예요.
+   */
+  success: boolean;
+
+  /**
+   * 인증이 실패했을 경우의 이유예요.
+   */
+  reason?: string;
+}
+
+/**
+ * @public
+ * @category 토스페이
+ * @name checkoutPayment
+ * @description 토스페이 결제창을 띄우고, 사용자 인증을 수행해요. 인증이 완료되면 성공 여부를 반환해요.
+ *
+ * 이 함수는 결제창을 통해 사용자 인증만 해요. 실제 결제 처리는 인증 성공 후 서버에서 별도로 해야 해요.
+ *
+ * @param {CheckoutPaymentOptions} options 결제창을 띄울 때 필요한 옵션이에요.
+ * @returns {Promise<CheckoutPaymentResult>} 인증 성공 여부를 포함한 결과를 반환해요.
+ *
+ * @example
+ *
+ * ### 토스페이 결제창 띄우고 인증 처리하기
+ *
+ * ```tsx
+ * import { TossPay } from '@apps-in-toss/framework';
+ *
+ * async function handlePayment() {
+ *   try {
+ *     // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해주세요.
+ *     const { payToken } = await fetch('/my-api/payment/create').then(res => res.json());
+ *
+ *     const { success, reason } = await TossPay.checkoutPayment({ payToken });
+ *
+ *     if (success) {
+ *       // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해주세요.
+ *       await fetch('/my-api/payment/execute', {
+ *         method: 'POST',
+ *         body: JSON.stringify({ payToken }),
+ *         headers: { 'Content-Type': 'application/json' },
+ *       });
+ *     } else {
+ *       console.log('인증 실패:', reason);
+ *     }
+ *   } catch (error) {
+ *     console.error('결제 인증 중 오류가 발생했어요:', error);
+ *   }
+ * }
+ * ```
+ */
+export async function checkoutPayment(options: CheckoutPaymentOptions): Promise<CheckoutPaymentResult> {
+  return AppsInTossModule.checkoutPayment({ params: options });
+}

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;
+}