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

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

@@ -0,0 +1,190 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+describe('isMinVersionSupported per-test mocks with dynamic import', () => {
+  beforeEach(() => {
+    // 각 테스트 전 모듈 캐시 초기화
+    vi.resetModules();
+  });
+
+  it('iOS 환경 테스트: 현재 버전이 최소 버전보다 낮을 때', async () => {
+    // doMock을 사용하여 모킹이 해당 테스트에 국한되도록 함
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '1.0.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    vi.doMock('react-native', () => ({
+      Platform: { OS: 'ios' },
+    }));
+
+    const { isMinVersionSupported } = await import('./isMinVersionSupported.js');
+    const result = isMinVersionSupported({
+      android: '1.0.0',
+      ios: '2.0.0',
+    });
+    expect(result).toBe(false);
+  });
+
+  it('Android 환경 테스트: 현재 버전이 최소 버전보다 높을 때', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '3.0.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    vi.doMock('react-native', () => ({
+      Platform: { OS: 'android' },
+    }));
+
+    const { isMinVersionSupported } = await import('./isMinVersionSupported.js');
+    const result = isMinVersionSupported({
+      android: '2.0.0',
+      ios: '1.0.0',
+    });
+    expect(result).toBe(true);
+  });
+
+  it('iOS 환경 테스트: 현재 버전이 최소 버전과 같을 때', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '2.0.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    vi.doMock('react-native', () => ({
+      Platform: { OS: 'ios' },
+    }));
+
+    const { isMinVersionSupported } = await import('./isMinVersionSupported.js');
+    const result = isMinVersionSupported({
+      android: '1.0.0',
+      ios: '2.0.0',
+    });
+    expect(result).toBe(true);
+  });
+
+  it('iOS 환경 테스트: minVersion이 "always"일 때', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '1.0.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    vi.doMock('react-native', () => ({
+      Platform: { OS: 'ios' },
+    }));
+
+    const { isMinVersionSupported } = await import('./isMinVersionSupported.js');
+    const result = isMinVersionSupported({
+      android: '1.0.0',
+      ios: 'always',
+    });
+    expect(result).toBe(true);
+  });
+
+  it('Android 환경 테스트: minVersion이 "always"일 때', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '1.0.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    vi.doMock('react-native', () => ({
+      Platform: { OS: 'android' },
+    }));
+
+    const { isMinVersionSupported } = await import('./isMinVersionSupported.js');
+    const result = isMinVersionSupported({
+      android: 'always',
+      ios: '1.0.0',
+    });
+    expect(result).toBe(true);
+  });
+
+  it('iOS 환경 테스트: minVersion이 "never"일 때', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '1.0.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    vi.doMock('react-native', () => ({
+      Platform: { OS: 'ios' },
+    }));
+
+    const { isMinVersionSupported } = await import('./isMinVersionSupported.js');
+    const result = isMinVersionSupported({
+      android: '1.0.0',
+      ios: 'never',
+    });
+    expect(result).toBe(false);
+  });
+
+  it('Android 환경 테스트: minVersion이 "never"일 때', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '1.0.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    vi.doMock('react-native', () => ({
+      Platform: { OS: 'android' },
+    }));
+
+    const { isMinVersionSupported } = await import('./isMinVersionSupported.js');
+    const result = isMinVersionSupported({
+      android: 'never',
+      ios: '1.0.0',
+    });
+    expect(result).toBe(false);
+  });
+
+  it('minVersion이 없을 때 false를 반환', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '1.0.0',
+        operationalEnvironment: 'toss',
+      },
+    }));
+
+    vi.doMock('react-native', () => ({
+      Platform: { OS: 'ios' },
+    }));
+
+    const { isMinVersionSupported } = await import('./isMinVersionSupported.js');
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error: ios 값 누락 의도
+    const result = isMinVersionSupported({
+      android: '1.0.0',
+    });
+    expect(result).toBe(false);
+  });
+
+  it('sandbox 환경 테스트: 버전에 상관없이 항상 true를 반환', async () => {
+    vi.doMock('./AppsInTossModule.js', () => ({
+      AppsInTossModule: {
+        tossAppVersion: '1.0.0',
+        operationalEnvironment: 'sandbox',
+      },
+    }));
+
+    vi.doMock('react-native', () => ({
+      Platform: { OS: 'ios' },
+    }));
+
+    const { isMinVersionSupported } = await import('./isMinVersionSupported.js');
+    const result = isMinVersionSupported({
+      android: '5.0.0',
+      ios: '5.0.0',
+    });
+    expect(result).toBe(true);
+  });
+});

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

@@ -0,0 +1,68 @@
+import { Platform } from 'react-native';
+import { AppsInTossModule } from './AppsInTossModule';
+import { compareVersions } from '../../utils/compareVersion';
+
+/**
+ * @public
+ * @category 환경 확인
+ * @kind function
+ * @name isMinVersionSupported
+ * @description
+ * 현재 토스 앱 버전이 지정한 최소 버전 이상인지 확인해요.
+ *
+ * 이 함수는 현재 실행 중인 토스 앱의 버전이 파라미터로 전달된 최소 버전 요구사항을 충족하는지 확인해요. 특정 기능이 최신 버전에서만 동작할 때, 사용자에게 앱 업데이트를 안내할 수 있어요.
+ *
+ * @param {Object} minVersions 플랫폼별 최소 버전 요구사항을 지정하는 객체예요.
+ * @param {(`${number}.${number}.${number}` | 'always' | 'never')} minVersions.android 안드로이드 플랫폼의 최소 버전 요구사항이에요.
+ * @param {(`${number}.${number}.${number}` | 'always' | 'never')} minVersions.ios iOS 플랫폼의 최소 버전 요구사항이에요.
+ * @returns {boolean} 현재 앱 버전이 최소 버전 이상이면 true, 그렇지 않으면 false를 반환해요.
+ *
+ * @example
+ * ### 앱 버전 확인하기
+ *
+ * ```tsx
+ * import { isMinVersionSupported } from '@apps-in-toss/framework';
+ * import { Text, View } from 'react-native';
+ *
+ * function VersionCheck() {
+ *   const isSupported = isMinVersionSupported({
+ *     android: '1.2.0',
+ *     ios: '1.3.0'
+ *   });
+ *
+ *   return (
+ *     <View>
+ *       {!isSupported && (
+ *         <Text>최신 버전으로 업데이트가 필요해요.</Text>
+ *       )}
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function isMinVersionSupported(minVersions: {
+  android: `${number}.${number}.${number}` | 'always' | 'never';
+  ios: `${number}.${number}.${number}` | 'always' | 'never';
+}): boolean {
+  const operationalEnvironment = AppsInTossModule.operationalEnvironment;
+  if (operationalEnvironment === 'sandbox') {
+    return true;
+  }
+
+  const currentVersion = AppsInTossModule.tossAppVersion;
+  const isIOS = Platform.OS === 'ios';
+  const minVersion = isIOS ? minVersions.ios : minVersions.android;
+
+  if (minVersion === undefined) {
+    return false;
+  }
+
+  if (minVersion === 'always') {
+    return true;
+  }
+  if (minVersion === 'never') {
+    return false;
+  }
+
+  return compareVersions(currentVersion, minVersion) >= 0;
+}

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

@@ -0,0 +1,81 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { requestPermission } from './requestPermission';
+import type { ImageResponse } from '../../types';
+
+export interface OpenCameraOptions {
+  /**
+   * 이미지를 Base64 형식으로 반환할지 여부를 나타내는 불리언 값이에요.
+   *
+   * 기본값: `false`.
+   */
+  base64?: boolean;
+  /**
+   * 이미지의 최대 너비를 나타내는 숫자 값이에요.
+   *
+   * 기본값: `1024`.
+   */
+  maxWidth?: number;
+}
+
+/**
+ * @public
+ * @category 카메라
+ * @name openCamera
+ * @description 카메라를 실행해서 촬영된 이미지를 반환하는 함수예요.
+ * @param {OpenCameraOptions} options - 카메라 실행 시 사용되는 옵션 객체예요.
+ * @param {boolean} [options.base64=false] - 이미지를 Base64 형식으로 반환할지 여부를 나타내는 불리언 값이에요. 기본값은 `false`예요. `true`로 설정하면 `dataUri` 대신 Base64 인코딩된 문자열을 반환해요.
+ * @param {number} [options.maxWidth=1024] - 이미지의 최대 너비를 나타내는 숫자 값이에요. 기본값은 `1024`예요.
+ * @returns {Promise<ImageResponse>}
+ * 촬영된 이미지 정보를 포함한 객체를 반환해요. 반환 객체의 구성은 다음과 같아요:
+ * - `id`: 이미지의 고유 식별자예요.
+ * - `dataUri`: 이미지 데이터를 표현하는 데이터 URI예요.
+ *
+ * @example
+ * ### 카메라 실행 후 촬영된 사진 가져오기
+ *
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Text, Button, Image } from 'react-native';
+ * import { openCamera } from '@apps-in-toss/framework';
+ *
+ * const base64 = true;
+ *
+ * // 카메라를 실행하고 촬영된 이미지를 화면에 표시하는 컴포넌트
+ * function Camera() {
+ *   const [image, setImage] = useState(null);
+ *
+ *   const handlePress = async () => {
+ *     try {
+ *       const response = await openCamera({ base64 });
+ *       setImage(response);
+ *     } catch (error) {
+ *       console.error('사진을 가져오는 데 실패했어요:', error);
+ *     }
+ *   };
+ *
+ *   // base64 형식으로 반환된 이미지를 표시하려면 데이터 URL 스키마 Prefix를 붙여야해요.
+ *   const imageUri = base64 ? 'data:image/jpeg;base64,' + image.dataUri : image.dataUri;
+ *
+ *   return (
+ *     <View>
+ *       {image ? (
+ *         <Image source={{ uri: imageUri }} style={{ width: 200, height: 200 }} />
+ *       ) : (
+ *         <Text>사진이 없어요</Text>
+ *       )}
+ *       <Button title="사진 촬영하기" onPress={handlePress} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export async function openCamera(options?: OpenCameraOptions): Promise<ImageResponse> {
+  const permissionStatus = await requestPermission({ name: 'camera', access: 'access' });
+  if (permissionStatus === 'denied') {
+    throw new Error('카메라 권한이 거부되었어요.');
+  }
+
+  const photo = await AppsInTossModule.openCamera({ base64: false, maxWidth: 1024, ...options });
+
+  return photo;
+}

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

@@ -0,0 +1,44 @@
+import { openURL } from '@granite-js/react-native';
+import { isMinVersionSupported } from './isMinVersionSupported';
+import { GAME_CENTER_MIN_VERSION } from '../constants';
+
+/**
+ * @public
+ * @category 게임센터
+ * @name openGameCenterLeaderboard
+ * @description 게임센터 리더보드 웹뷰를 열어요.
+ * 앱 버전이 최소 지원 버전(`5.221.0`)보다 낮으면 아무 동작도 하지 않고 `undefined`를 반환해요.
+ * 게임센터를 사용하는 사용자는 반드시 최소 지원 버전 이상이어야 게임을 실행할 수 있어요.
+ * @returns 리더보드 웹뷰를 호출해요. 앱 버전이 낮으면 아무 동작도 하지 않고 `undefined`를 반환해요.
+ *
+ * @example
+ * import { Button } from 'react-native';
+ * import { openGameCenterLeaderboard } from '@apps-in-toss/framework';
+ *
+ * // '리더보드' 버튼을 누르면 게임센터 리더보드 웹뷰가 열려요.
+ * function LeaderboardButton() {
+ *   const onPress = () => {
+ *     openGameCenterLeaderboard();
+ *   };
+ *
+ *   return <Button title="리더보드 웹뷰 호출" onPress={onPress} />;
+ * }
+ */
+export async function openGameCenterLeaderboard(): Promise<void> {
+  if (!isMinVersionSupported(GAME_CENTER_MIN_VERSION)) {
+    return;
+  }
+
+  const appName = global.__granite?.app?.name;
+
+  if (appName == null) {
+    throw new Error('Cannot get app name');
+  }
+
+  const url = new URL('servicetoss://game-center/leaderboard?_navbar=hide');
+  url.searchParams.set('appName', appName);
+  url.searchParams.set('referrer', `appsintoss.${appName}`);
+  return openURL(url.toString());
+}
+
+declare const global: { __granite: any };

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

@@ -0,0 +1,54 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { PermissionAccess, PermissionName, PermissionStatus } from '../../types';
+
+/**
+ * @category AppsInTossModules
+ * @name openPermissionDialog
+ * @description 권한 요청 다이얼로그를 표시하는 함수예요. 사용자는 이 다이얼로그에서 특정 권한을 허용하거나 거부할 수 있어요.
+ * @param permission.name {PermissionName} 요청할 권한의 이름이에요. 예를 들어 `clipboard`는 클립보드 접근 권한을, `camera`는 카메라 접근 권한을 나타내요.
+ * @param permission.access {PermissionAccess} 요청할 권한의 접근 유형이에요. 예를 들어 `read`는 읽기 권한, `write`는 쓰기 권한을 의미해요.
+ * @returns {Promise<'allowed' | 'denied'>} 권한의 현재 상태를 반환해요. 반환값은 다음 중 하나예요:
+ * - `allowed`: 권한이 허용된 상태예요.
+ * - `denied`: 권한이 거부된 상태예요.
+ *
+ * @example
+ * ### 클립보드 읽기 권한 다이얼로그 열기
+ *
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Text, Button } from 'react-native';
+ * import { openPermissionDialog, type PermissionStatus } from '@apps-in-toss/framework';
+ *
+ * function PermissionRequest() {
+ *   const [permission, setPermission] = useState<PermissionStatus | null>(null);
+ *
+ *   const handleRequestPermission = async () => {
+ *     try {
+ *       // 클립보드 읽기 권한을 요청하는 다이얼로그를 표시해요.
+ *       const status = await openPermissionDialog({
+ *         name: 'clipboard',
+ *         access: 'read',
+ *       });
+ *       setPermission(status); // 권한 상태를 업데이트해요.
+ *     } catch (error) {
+ *       console.error('권한 요청 중 오류가 발생했어요:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       <Text>
+ *         클립보드 읽기 권한 상태: {permission ? permission : '아직 요청하지 않음'}
+ *       </Text>
+ *       <Button title="권한 요청하기" onPress={handleRequestPermission} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function openPermissionDialog(permission: {
+  name: PermissionName;
+  access: PermissionAccess;
+}): Promise<Exclude<PermissionStatus, 'notDetermined'>> {
+  return AppsInTossModule.openPermissionDialog(permission);
+}

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

@@ -0,0 +1,63 @@
+import { getPermission } from './getPermission';
+import { openPermissionDialog } from './openPermissionDialog';
+import { PermissionAccess, PermissionName, PermissionStatus } from '../../types';
+
+/**
+ * @category PermissionManagement
+ * @name requestPermission
+ * @description 특정 권한을 요청하는 함수예요. 이미 허용되었거나 거부된 권한 상태를 확인한 뒤, 필요할 때 권한 요청 다이얼로그를 표시해요.
+ * @param permission.name {PermissionName} 요청할 권한의 이름이에요. 예를 들어 `clipboard`는 클립보드 접근 권한을, `camera`는 카메라 접근 권한을 나타내요.
+ * @param permission.access {PermissionAccess} 요청할 권한의 접근 유형이에요. 예를 들어 `read`는 읽기 권한, `write`는 쓰기 권한을 의미해요.
+ * @returns {Promise<'allowed' | 'denied'>} 사용자가 선택한 최종 권한 상태를 반환해요.
+ * 반환값은 다음 중 하나예요:
+ * - `allowed`: 권한이 허용된 경우
+ * - `denied`: 권한이 거부된 경우
+ *
+ * @example
+ * ### 클립보드 읽기 권한 요청하기
+ *
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { View, Text, Button } from 'react-native';
+ * import { requestPermission, type PermissionStatus } from '@apps-in-toss/framework';
+ *
+ * function PermissionRequest() {
+ *   const [permissionStatus, setPermissionStatus] = useState<PermissionStatus | null>(null);
+ *
+ *   const handleRequestPermission = async () => {
+ *     try {
+ *       // 클립보드 읽기 권한을 요청해요.
+ *       const permissionStatus = await requestPermission({
+ *         name: 'clipboard', // 권한 이름: 클립보드
+ *         access: 'read', // 접근 유형: 읽기
+ *       });
+ *       setPermissionStatus(permissionStatus); // 최종 권한 상태를 저장해요.
+ *     } catch (error) {
+ *       console.error('권한 요청 중 오류가 발생했어요:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <View>
+ *       <Text>
+ *         클립보드 읽기 권한 상태: {permissionStatus ? permissionStatus : '아직 요청하지 않음'}
+ *       </Text>
+ *       <Button title="권한 요청하기" onPress={handleRequestPermission} />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export async function requestPermission(permission: {
+  name: PermissionName;
+  access: PermissionAccess;
+}): Promise<Exclude<PermissionStatus, 'notDetermined'>> {
+  const permissionStatus = await getPermission(permission);
+  switch (permissionStatus) {
+    case 'allowed':
+    case 'denied':
+      return permissionStatus;
+    default:
+      return openPermissionDialog(permission);
+  }
+}

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

@@ -0,0 +1,57 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { isMinVersionSupported } from './isMinVersionSupported';
+
+export interface SaveBase64DataParams {
+  data: string;
+  fileName: string;
+  mimeType: string;
+}
+
+/**
+ * @public
+ * @category 데이터
+ * @name saveBase64Data
+ * @description 문자열로 인코딩된 Base64 데이터를 지정한 파일 이름과 MIME 타입으로 사용자 기기에 저장해요. 이미지, 텍스트, PDF 등 다양한 형식의 데이터를 저장할 수 있어요.
+ * @param {SaveBase64DataParams} params - 저장할 데이터와 파일 정보를 담은 객체예요.
+ * @param {string} params.data - Base64 형식으로 인코딩된 데이터 문자열이에요.
+ * @param {string} params.fileName - 저장할 파일 이름이에요. 확장자도 같이 붙여줘야해요. 예를 들어, 'example.png'로 저장할 수 있어요. 
+ * @param {string} params.mimeType - 저장할 파일의 MIME 타입이에요. 예를 들어 'image/png' 로 지정하면 이미지, 'application/pdf'는 PDF 파일이에요. 자세한 내용은 [MIME 문서](https://developer.mozilla.org/ko/docs/Web/HTTP/Guides/MIME_types)를 참고해주세요.
+ *
+ * @example
+ * ### Base64 이미지 데이터를 사용자 기기에 저장하기
+ *
+ * ```tsx
+ * import { Button } from 'react-native';
+ * import { saveBase64Data } from '@apps-in-toss/framework';
+ *
+ * // '저장' 버튼을 누르면 이미지가 사용자 기기에 저장돼요.
+ * function SaveButton() {
+ *   const handleSave = async () => {
+ *     try {
+ *       await saveBase64Data({
+ *         data: 'iVBORw0KGgo...',
+ *         fileName: 'some-photo.png',
+ *         mimeType: 'image/png',
+ *       });
+ *     } catch (error) {
+ *       console.error('데이터 저장에 실패했어요:', error);
+ *     }
+ *   };
+ *
+ *   return <Button title="저장" onPress={handleSave} />;
+ * }
+ * ```
+ */
+export async function saveBase64Data(params: SaveBase64DataParams) {
+  const isSupported = isMinVersionSupported({
+    android: '5.218.0',
+    ios: '5.216.0',
+  });
+
+  if (!isSupported) {
+    console.warn('saveBase64Data is not supported in this app version');
+    return;
+  }
+
+  await AppsInTossModule.saveBase64Data(params);
+}

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

@@ -0,0 +1,39 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { requestPermission } from './requestPermission';
+
+/**
+ * @public
+ * @category 클립보드
+ * @name setClipboardText
+ * @description 텍스트를 클립보드에 복사해서 사용자가 다른 곳에 붙여 넣기 할 수 있어요.
+ * @param {Promise<void>} text - 클립보드에 복사할 텍스트예요. 문자열 형식으로 입력해요.
+ *
+ * @example
+ * ### 텍스트를 클립보드에 복사하기
+ *
+ * ```tsx
+ * import { Button } from 'react-native';
+ * import { setClipboardText } from '@apps-in-toss/framework';
+ *
+ * // '복사' 버튼을 누르면 "복사할 텍스트"가 클립보드에 복사돼요.
+ * function CopyButton() {
+ *   const handleCopy = async () => {
+ *     try {
+ *       await setClipboardText('복사할 텍스트');
+ *       console.log('텍스트가 복사됐어요!');
+ *     } catch (error) {
+ *       console.error('텍스트 복사에 실패했어요:', error);
+ *     }
+ *   };
+ *
+ *   return <Button title="복사" onPress={handleCopy} />;
+ * }
+ * ```
+ */
+export async function setClipboardText(text: string): Promise<void> {
+  const permissionStatus = await requestPermission({ name: 'clipboard', access: 'write' });
+  if (permissionStatus === 'denied') {
+    throw new Error('클립보드 쓰기 권한이 거부되었어요.');
+  }
+  return AppsInTossModule.setClipboardText({ text });
+}

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

@@ -0,0 +1,74 @@
+import { AppsInTossModule } from './AppsInTossModule';
+import { isMinVersionSupported } from './isMinVersionSupported';
+
+/**
+ * @public
+ * @category 화면 제어
+ * @kind function
+ * @name setDeviceOrientation
+ * @description
+ * `setDeviceOrientation` 함수는 기기의 화면 방향을 설정하는 기능을 제공해요.
+ * 이 기능은 특정 화면에서 가로 모드나 세로 모드를 강제로 지정해야 할 때 유용해요.
+ *
+ * `type` 옵션을 통해 원하는 화면 방향을 지정할 수 있어요. 특히, 이 함수는 앱 전체에 영향을 미치므로
+ * 특정 화면에서만 사용하려면 화면을 벗어날 때 이전 상태로 복구하는 추가 작업이 필요해요.
+ *
+ * 예를 들어, 동영상 감상 화면에서는 가로 모드를 강제하고, 화면을 떠날 때 설정을 복구해서
+ * 다른 화면들의 방향 설정에 영향을 주지 않도록 할 수 있어요.
+ *
+ * @param {object} options 화면 방향 설정 값이에요.
+ * @param {string} options.type 화면 방향을 지정하는 옵션이에요.
+ * 'portrait' | 'landscape' 중 하나를 선택할 수 있어요.
+ *
+ * @returns {Promise<void>} 화면 방향 설정이 완료되면 해결되는 Promise를 반환해요.
+ *
+ * @example
+ * ### 화면 방향 설정하기
+ *
+ * ```tsx
+ * import { Button } from 'react-native';
+ * import { setDeviceOrientation } from '@apps-in-toss/framework';
+ *
+ * function SetDeviceOrientation() {
+ *   return (
+ *     <Button
+ *       title="가로 모드로 변경"
+ *       onPress={() => {
+ *         setDeviceOrientation({ type: 'landscape' });
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * ### 화면 방향 복구하기
+ * 특정 화면을 벗어날 때 이전 상태로 복구하려면 다음과 같이 `useEffect`를 사용하세요.
+ *
+ * ```tsx
+ * import { useEffect } from 'react';
+ * import { setDeviceOrientation } from '@apps-in-toss/framework';
+ *
+ * function VideoScreen() {
+ *   useEffect(() => {
+ *     setDeviceOrientation({ type: 'landscape' });
+ *
+ *     return () => {
+ *       setDeviceOrientation({ type: 'portrait' }); // 설정을 이전 상태로 복구해요.
+ *     };
+ *   }, []);
+ *
+ *   return <Text>동영상을 감상하는 화면</Text>;
+ * }
+ * ```
+ */
+export async function setDeviceOrientation(options: { type: 'portrait' | 'landscape' }): Promise<void> {
+  const isSupported = isMinVersionSupported({
+    android: '5.215.0',
+    ios: '5.215.0',
+  });
+  if (!isSupported) {
+    return;
+  }
+
+  return AppsInTossModule.setDeviceOrientation(options);
+}