@apps-in-toss/native-modules 1.0.2 → 1.1.0

package/dist/private.d.cts

@@ -0,0 +1,17 @@
+import { EmitterSubscription } from 'react-native';
+import { E as EventEmitterSchema, a as VisibilityChangedByTransparentServiceWebOptions } from './VisibilityChangedByTransparentServiceWebEvent-D6XJvPVh.cjs';
+import '@granite-js/react-native';
+
+interface OnVisibilityChangedByTransparentServiceWebSubscription extends EmitterSubscription {
+    remove: () => void;
+}
+type OnVisibilityChangedByTransparentServiceWebEventEmitter = EventEmitterSchema<'visibilityChangedByTransparentServiceWeb', [
+    boolean
+]>;
+declare function onVisibilityChangedByTransparentServiceWeb(eventParams: {
+    options: VisibilityChangedByTransparentServiceWebOptions;
+    onEvent: (isVisible: boolean) => void;
+    onError: (error: unknown) => void;
+}): () => void;
+
+export { type OnVisibilityChangedByTransparentServiceWebEventEmitter, type OnVisibilityChangedByTransparentServiceWebSubscription, onVisibilityChangedByTransparentServiceWeb };

package/dist/private.d.ts

@@ -0,0 +1,17 @@
+import { EmitterSubscription } from 'react-native';
+import { E as EventEmitterSchema, a as VisibilityChangedByTransparentServiceWebOptions } from './VisibilityChangedByTransparentServiceWebEvent-D6XJvPVh.js';
+import '@granite-js/react-native';
+
+interface OnVisibilityChangedByTransparentServiceWebSubscription extends EmitterSubscription {
+    remove: () => void;
+}
+type OnVisibilityChangedByTransparentServiceWebEventEmitter = EventEmitterSchema<'visibilityChangedByTransparentServiceWeb', [
+    boolean
+]>;
+declare function onVisibilityChangedByTransparentServiceWeb(eventParams: {
+    options: VisibilityChangedByTransparentServiceWebOptions;
+    onEvent: (isVisible: boolean) => void;
+    onError: (error: unknown) => void;
+}): () => void;
+
+export { type OnVisibilityChangedByTransparentServiceWebEventEmitter, type OnVisibilityChangedByTransparentServiceWebSubscription, onVisibilityChangedByTransparentServiceWeb };

package/dist/private.js

@@ -0,0 +1,11 @@
+import {
+  appsInTossEvent
+} from "./chunk-YS54L7RG.js";
+
+// src/AppsInTossModule/native-event-emitter/internal/onVisibilityChangedByTransparentServiceWeb.ts
+function onVisibilityChangedByTransparentServiceWeb(eventParams) {
+  return appsInTossEvent.addEventListener("onVisibilityChangedByTransparentServiceWeb", eventParams);
+}
+export {
+  onVisibilityChangedByTransparentServiceWeb
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apps-in-toss/native-modules",
   "type": "module",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Native Modules for Apps In Toss",
   "scripts": {
     "prepack": "yarn build",
@@ -43,6 +43,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
+    "@apps-in-toss/types": "^1.1.0",
     "es-toolkit": "^1.39.3"
   },
   "peerDependencies": {
@@ -53,5 +54,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6bcca89699f84625d384052501b8ea0d28cabccc"
+  "gitHead": "614cfd1ee039b44cd6efeb94cefac18ed3c0e6c3"
 }

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

@@ -0,0 +1 @@
+export { StartUpdateLocationPermissionError } from '@apps-in-toss/types';

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

@@ -1,5 +1,6 @@
 import { GraniteEvent } from '@granite-js/react-native';
 import { EntryMessageExitedEvent } from './event-plugins/EntryMessageExitedEvent';
+import { HomeIconButtonClickHandleEvent } from './event-plugins/HomeIconButtonClickHandleEvent';
 import { UpdateLocationEvent } from './event-plugins/UpdateLocationEvent';
 import { AppBridgeCallbackEvent } from './internal/AppBridgeCallbackEvent';
 import { VisibilityChangedByTransparentServiceWebEvent } from './internal/VisibilityChangedByTransparentServiceWebEvent';
@@ -7,6 +8,7 @@ import { VisibilityChangedByTransparentServiceWebEvent } from './internal/Visibi
 export const appsInTossEvent = new GraniteEvent([
   new UpdateLocationEvent(),
   new EntryMessageExitedEvent(),
+  new HomeIconButtonClickHandleEvent(),
   // Internal events
   new AppBridgeCallbackEvent(),
   new VisibilityChangedByTransparentServiceWebEvent(),

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

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

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

@@ -1,7 +1,7 @@
+import { Accuracy, GetCurrentLocationPermissionError, Location } from '@apps-in-toss/types';
 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 { requestPermission } from '../../native-modules/permissions/requestPermission';
 import { nativeEventEmitter } from '../nativeEventEmitter';
 
 export interface StartUpdateLocationOptions {
@@ -42,7 +42,7 @@ export class UpdateLocationEvent extends GraniteEventDefinition<StartUpdateLocat
     requestPermission({ name: 'geolocation', access: 'access' })
       .then((permissionStatus) => {
         if (permissionStatus === 'denied') {
-          onError(new Error('위치 권한이 거부되었어요.'));
+          onError(new GetCurrentLocationPermissionError());
           return;
         }
 

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

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

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

@@ -27,8 +27,14 @@ function invokeAppBridgeMethod<Result = any, Params = any>(
 ) {
   const { onSuccess, onError, ...appBridgeCallbacks } = callbacks;
   const { callbackMap, unregisterAll } = registerCallbacks(appBridgeCallbacks);
+  const method = AppsInTossModuleInstance[methodName];
 
-  const promise = AppsInTossModuleInstance[methodName]({
+  if (method == null) {
+    onError(new Error(`'${methodName}' is not defined in AppsInTossModule`));
+    return unregisterAll;
+  }
+
+  const promise = method({
     params,
     callbacks: callbackMap,
   }) as Promise<Result>;

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

@@ -1,26 +1,7 @@
-import type { EmitterSubscription } from 'react-native';
+import { Location, StartUpdateLocationEventParams } from '@apps-in-toss/types';
 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>;
-}
+import { EventEmitterSchema } from './types';
+import { getCurrentLocation } from '../native-modules';
 
 /**
  * @name UpdateLocationEventEmitter
@@ -38,26 +19,46 @@ export type UpdateLocationEventEmitter = EventEmitterSchema<'updateLocation', [L
  * 실시간 위치 추적이 필요한 기능을 구현할 때 사용할 수 있어요. 예를 들어 지도 앱에서 사용자의 현재 위치를 실시간으로 업데이트할 때, 운동 앱에서 사용자의 이동 거리를 기록할 때 등이에요.
  * 위치 업데이트 주기와 정확도를 조정해 배터리 소모를 최소화하면서도 필요한 정보를 얻을 수 있어요.
  *
+ *
+ * @param {(error: unknown) => void} onError 위치 정보 감지에 실패했을 때 호출되는 콜백 함수예요.
+ * @param {(location: Location) => void} onEvent 위치 정보가 변경될 때 호출되는 콜백 함수예요. 자세한 내용은 [Location](/react-native/reference/native-modules/Types/Location.html)을 참고해주세요.
  * @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)을 참고해주세요.
+ *
+ * @property [openPermissionDialog] - 위치 정보 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 `allowed`를 반환하고, "안하기"를 선택하면 `denied`를 반환해요.
+ * @property [getPermission] - 위치 정보 권한의 현재 상태를 반환해요. `allowed`는 사용자가 위치 정보 권한을 허용한 상태예요. `denied`는 사용자가 위치 정보 권한을 거부한 상태예요. `notDetermined`는 위치 정보 권한 요청을 한 번도 하지 않은 상태예요.
+ *
+ * @signature
+ * ```typescript
+ * function startUpdateLocation(options: {
+ *   onError: (error: unknown) => void;
+ *   onEvent: (location: Location) => void;
+ *   options: StartUpdateLocationOptions;
+ * }): () => void;
+ * ```
  *
  * @example
  * ### 위치 정보 변경 감지하기
  *
+ * 위치 정보가 변경되는것을 감지하는 예제예요. "위치 정보 변경 감지하기"를 눌러서 감지할 수 있어요.
+ *
+ * "권한 확인하기"버튼을 눌러서 현재 위치 정보 변경 감지 권한을 확인해요.
+ * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`StartUpdateLocationPermissionError`](/react-native/reference/types/권한/StartUpdateLocationPermissionError)를 반환해요.
+ * "권한 요청하기"버튼을 눌러서 위치 정보 변경 감지 권한을 요청할 수 있어요.
+ *
  * ```tsx
- * import React, { useState, useEffect } from 'react';
- * import { View, Text, Button } from 'react-native';
- * import { startUpdateLocation } from '@apps-in-toss/framework';
+ * import { Accuracy, Location, startUpdateLocation, StartUpdateLocationPermissionError } from '@apps-in-toss/framework';
+ * import { useCallback, useState } from 'react';
+ * import { Alert, Button, Text, View } from 'react-native';
  *
  * // 위치 정보 변경 감지하기
  * function LocationWatcher() {
- *   const [location, setLocation] = useState(null);
+ *   const [location, setLocation] = useState<Location | null>(null);
  *
- *   useEffect(() => {
- *     return startUpdateLocation({
+ *   const handlePress = useCallback(() => {
+ *     startUpdateLocation({
  *       options: {
  *         accuracy: Accuracy.Balanced,
  *         timeInterval: 3000,
@@ -67,32 +68,51 @@ export type UpdateLocationEventEmitter = EventEmitterSchema<'updateLocation', [L
  *         setLocation(location);
  *       },
  *       onError: (error) => {
+ *         if (error instanceof StartUpdateLocationPermissionError) {
+ *           // 위치 정보 변경 감지 권한 없음
+ *         }
  *         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>
+ *       {location != null && (
+ *         <>
+ *           <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>
+ *         </>
+ *       )}
+ *
+ *       <Button title="위치 정보 변경 감지하기" onPress={handlePress} />
+ *
+ *       <Button
+ *         title="권한 확인하기"
+ *         onPress={async () => {
+ *           const permission = await startUpdateLocation.getPermission();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
+ *       <Button
+ *         title="권한 요청하기"
+ *         onPress={async () => {
+ *           const permission = await startUpdateLocation.openPermissionDialog();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
  *     </View>
  *   );
  * }
  * ```
  */
-export function startUpdateLocation(eventParams: {
-  onEvent: (response: Location) => void;
-  onError: (error: unknown) => void;
-  options: StartUpdateLocationOptions;
-}): () => void {
+export function startUpdateLocation(eventParams: StartUpdateLocationEventParams): () => void {
   return appsInTossEvent.addEventListener('updateLocationEvent', eventParams);
 }
+
+startUpdateLocation.openPermissionDialog = getCurrentLocation.openPermissionDialog;
+startUpdateLocation.getPermission = getCurrentLocation.getPermission;

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

@@ -1,22 +1,29 @@
+import type {
+  CompatiblePlaceholderArgument,
+  ContactResult,
+  FetchAlbumPhotosOptions,
+  FetchContactsOptions,
+  GetCurrentLocationOptions,
+  ImageResponse,
+  Location,
+  OpenCameraOptions,
+  PermissionAccess,
+  PermissionName,
+  PermissionStatus,
+  SetClipboardTextOptions,
+} from '@apps-in-toss/types';
 import { TurboModuleRegistry, type TurboModule as __TurboModule } from 'react-native';
 import type { CheckoutPaymentOptions, CheckoutPaymentResult } from './checkoutPayment';
-import type { FetchAlbumPhotosOptions } from './fetchAlbumPhotos';
-import type { ContactEntity } from './fetchContacts';
-import type { GetCurrentLocationOptions } from './getCurrentLocation';
 import type { GameCenterGameProfileResponse } from './getGameCenterGameProfile';
 import type {
   IapCreateOneTimePurchaseOrderOptions,
   IapCreateOneTimePurchaseOrderResult,
   IapProductListItem,
 } from './iap';
-import type { OpenCameraOptions } from './openCamera';
 import type { SaveBase64DataParams } from './saveBase64Data';
 import type { SubmitGameCenterLeaderBoardScoreResponse } from './submitGameCenterLeaderBoardScore';
-import type { ImageResponse, Location, PermissionAccess, PermissionName, PermissionStatus } from '../../types';
 import type { ContactsViralParams } from '../native-event-emitter/contactsViral';
 
-type CompatiblePlaceholderArgument = object;
-
 /**
  * TurboModule 타입 별칭 사용하는 이유?
  * React Native Codegen 에 의해 코드젠 되는 것이 아니라 추후 내부 모듈 체계에 의해 처리될 것이기 때문에 RN Codegen에 본 파일을 코드젠 하지 않도록 함
@@ -27,32 +34,20 @@ interface Spec extends __TurboModule {
   operationalEnvironment: 'sandbox' | 'toss';
   tossAppVersion: string;
   deviceId: string;
-  getWebBundleURL: (arg: CompatiblePlaceholderArgument) => { url: string };
+
   getClipboardText: (arg: CompatiblePlaceholderArgument) => Promise<string>;
-  setClipboardText: (option: { text: string }) => Promise<void>;
+  setClipboardText: (option: SetClipboardTextOptions) => Promise<void>;
+  fetchContacts: (option: FetchContactsOptions) => Promise<ContactResult>;
+  fetchAlbumPhotos: (options: FetchAlbumPhotosOptions) => Promise<ImageResponse[]>;
+  getCurrentLocation: (options: GetCurrentLocationOptions) => Promise<Location>;
+  openCamera: (options: OpenCameraOptions) => Promise<ImageResponse>;
+
+  getWebBundleURL: (arg: CompatiblePlaceholderArgument) => { url: string };
   getPermission: (permission: { name: PermissionName; access: PermissionAccess }) => Promise<PermissionStatus>;
   openPermissionDialog: (permission: {
     name: PermissionName;
     access: PermissionAccess;
   }) => Promise<Exclude<PermissionStatus, 'notDetermined'>>;
-  fetchContacts: ({
-    size,
-    offset,
-    query,
-  }: {
-    size: number;
-    offset: number;
-    query?: {
-      contains?: string;
-    };
-  }) => Promise<{
-    result: ContactEntity[];
-    nextOffset: number | undefined;
-    done: boolean;
-  }>;
-  fetchAlbumPhotos: (options: FetchAlbumPhotosOptions) => Promise<ImageResponse[]>;
-  getCurrentLocation: (options: GetCurrentLocationOptions) => Promise<Location>;
-  openCamera: (options: OpenCameraOptions) => Promise<ImageResponse>;
   appLogin: (
     arg: CompatiblePlaceholderArgument
   ) => Promise<{ authorizationCode: string; referrer: 'DEFAULT' | 'SANDBOX' }>;

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

@@ -17,7 +17,7 @@ export interface LoadAdMobOptions {
  * @public
  * @category 광고
  * @name LoadAdMobEvent
- * @description 광고를 불러오는 함수에서 발생하는 이벤트 타입이에요. `loaded` 이벤트가 발생하면 광고를 성공적으로 불러온 거예요. 이때 [AdMobLoadResult](/react-native/reference/framework/광고/AdMobLoadResult.html) 객체가 함께 반환돼요.
+ * @description 광고를 불러오는 함수에서 발생하는 이벤트 타입이에요. `loaded` 이벤트가 발생하면 광고를 성공적으로 불러온 거예요. 이때 [AdMobLoadResult](/react-native/reference/native-modules/광고/AdMobLoadResult.html) 객체가 함께 반환돼요.
  */
 export type LoadAdMobEvent = {
   type: 'loaded';
@@ -40,7 +40,7 @@ export type LoadAdMobParams = AdMobHandlerParams<LoadAdMobOptions, LoadAdMobEven
  * @param {LoadAdMobParams} params 광고를 불러올 때 사용할 설정 값이에요. 광고 그룹 ID와 광고의 동작에 대한 콜백을 설정할 수 있어요.
  * @param {LoadAdMobOptions} params.options 광고를 불러올 때 전달할 옵션 객체예요.
  * @param {string} params.options.adGroupId 광고 그룹 단위 ID예요. 콘솔에서 발급받은 ID를 입력해요.
- * @param {(event: LoadAdMobEvent) => void} [params.onEvent] 광고 관련 이벤트가 발생했을 때 호출돼요. (예시: 광고가 닫히거나 클릭됐을 때). 자세한 이벤트 타입은 [LoadAdMobEvent](/react-native/reference/framework/광고/LoadAdMobEvent.html)를 참고하세요.
+ * @param {(event: LoadAdMobEvent) => void} [params.onEvent] 광고 관련 이벤트가 발생했을 때 호출돼요. (예시: 광고가 닫히거나 클릭됐을 때). 자세한 이벤트 타입은 [LoadAdMobEvent](/react-native/reference/native-modules/광고/LoadAdMobEvent.html)를 참고하세요.
  * @param {(reason: unknown) => void} [params.onError] 광고를 불러오지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
  * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
  *
@@ -197,7 +197,7 @@ export type ShowAdMobParams = AdMobHandlerParams<ShowAdMobOptions, ShowAdMobEven
  * @param {ShowAdMobParams} params 광고를 보여주기 위해 사용할 설정 값이에요. 광고 그룹 ID와과 광고의 동작에 대한 콜백을 설정할 수 있어요.
  * @param {ShowAdMobOptions} params.options 광고를 보여줄 때 전달할 옵션 객체예요.
  * @param {string} params.options.adUnitId 광고 그룹 단위 ID예요. `loadAppsInTossAdMob` 로 불러온 광고용 그룹 ID를 입력해요.
- * @param {(event: ShowAdMobEvent) => void} [params.onEvent] 광고 관련 이벤트가 발생했을 때 호출돼요. (예시: 광고 노출을 요청했을 때). 자세한 이벤트 타입은 [ShowAdMobEvent](/react-native/reference/framework/광고/ShowAdMobEvent.html)를 참고하세요.
+ * @param {(event: ShowAdMobEvent) => void} [params.onEvent] 광고 관련 이벤트가 발생했을 때 호출돼요. (예시: 광고 노출을 요청했을 때). 자세한 이벤트 타입은 [ShowAdMobEvent](/react-native/reference/native-modules/광고/ShowAdMobEvent.html)를 참고하세요.
  * @param {(reason: unknown) => void} [params.onError] 광고를 노출하지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
  * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
  *

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

@@ -114,7 +114,7 @@ export interface RewardedAd {
  * @description 광고의 ID와 응답 정보를 담고 있는 객체예요. 광고를 로드한 뒤, 관련 정보를 확인할 때 유용해요.
  * @property {string} adGroupId 광고 그룹 ID예요.
  * @property {string} adUnitId 광고 ID예요.
- * @property {ResponseInfo} responseInfo 광고 로드 응답 정보예요. 자세한 내용은 [ResponseInfo](/react-native/reference/framework/광고/ResponseInfo.html)를 참고하세요.
+ * @property {ResponseInfo} responseInfo 광고 로드 응답 정보예요. 자세한 내용은 [ResponseInfo](/react-native/reference/native-modules/광고/ResponseInfo.html)를 참고하세요.
  */
 export interface AdMobLoadResult {
   adGroupId: string;

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

@@ -1,5 +1,5 @@
+import type { PermissionAccess, PermissionName, PermissionStatus } from '@apps-in-toss/types';
 import { AppsInTossModule } from './AppsInTossModule';
-import { PermissionAccess, PermissionName, PermissionStatus } from '../../types';
 
 /**
  * @category AppsInTossModules

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

@@ -32,19 +32,22 @@ export { AppsInTossModule } from './AppsInTossModule';
 
 export * from './appLogin';
 export * from './eventLog';
-export * from './fetchAlbumPhotos';
-export * from './fetchContacts';
-export * from './getClipboardText';
-export * from './getCurrentLocation';
+
+/** permission functions */
+export * from './permissions/fetchAlbumPhotos/fetchAlbumPhotos';
+export * from './permissions/fetchContacts/fetchContacts';
+export * from './permissions/getClipboardText/getClipboardText';
+export * from './permissions/getCurrentLocation/getCurrentLocation';
+export * from './permissions/setClipboardText/setClipboardText';
+export * from './permissions/openCamera/openCamera';
+
 export * from './getDeviceId';
 export * from './getOperationalEnvironment';
 export * from './getTossAppVersion';
 export * from './getTossShareLink';
 export * from './iap';
 export * from './isMinVersionSupported';
-export * from './openCamera';
 export * from './saveBase64Data';
-export * from './setClipboardText';
 export * from './setDeviceOrientation';
 export * from './storage';
 export * from './openGameCenterLeaderboard';

package/src/AppsInTossModule/native-modules/permissions/createPermissionFunction.ts

@@ -0,0 +1,25 @@
+import { CreatePermissionFunctionOptions, PermissionFunctionWithDialog } from '@apps-in-toss/types';
+import { openPermissionDialog } from './openPermissionDialog';
+import { requestPermission } from './requestPermission';
+import { getPermission } from '../getPermission';
+
+export function createPermissionFunction<T extends (...args: any[]) => any>({
+  handler,
+  permission,
+  error,
+}: CreatePermissionFunctionOptions<T>): PermissionFunctionWithDialog<T> {
+  const permissionFunction = async (...args: Parameters<T>): Promise<Awaited<ReturnType<T>>> => {
+    const permissionStatus = await requestPermission(permission);
+
+    if (permissionStatus === 'denied') {
+      throw new error();
+    }
+
+    return handler(...args);
+  };
+
+  permissionFunction.getPermission = () => getPermission(permission);
+  permissionFunction.openPermissionDialog = () => openPermissionDialog(permission);
+
+  return permissionFunction as any;
+}

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

@@ -0,0 +1,109 @@
+import { FetchAlbumPhotos, FetchAlbumPhotosPermissionError } from '@apps-in-toss/types';
+import { AppsInTossModule } from '../../AppsInTossModule';
+import { createPermissionFunction } from '../createPermissionFunction';
+
+const DEFAULT_MAX_COUNT = 10;
+const DEFAULT_MAX_WIDTH = 1024;
+
+/**
+ * @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`예요.
+ * @property [openPermissionDialog] - 사진첩 읽기 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 `allowed`를 반환하고, "안하기"를 선택하면 `denied`를 반환해요.
+ * @property [getPermission] - 사진첩 읽기 권한의 현재 상태를 반환해요. `allowed`는 사용자가 사진첩 읽기 권한을 허용한 상태예요. `denied`는 사용자가 사진첩 읽기 권한을 거부한 상태예요. `notDetermined`는 사진첩 읽기 권한 요청을 한 번도 하지 않은 상태예요.
+ * @returns {Promise<ImageResponse[]>}
+ * 앨범 사진의 고유 ID와 데이터 URI를 포함한 배열을 반환해요.
+ *
+ * @signature
+ * ```typescript
+ * function fetchAlbumPhotos(options: {
+ *   maxCount: number;
+ *   maxWidth: number;
+ *   base64: boolean;
+ * }): Promise<ImageResponse[]>;
+ * ```
+ *
+ * @example
+ * ### 사진의 최대 폭을 360px로 제한하여 가져오기
+ *
+ * 사진을 가져오는 예제예요.
+ * "권한 확인하기"버튼을 눌러서 현재 사진첩 읽기 권한을 확인해요.
+ * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`FetchAlbumPhotosPermissionError`](/react-native/reference/types/권한/FetchAlbumPhotosPermissionError)를 반환해요.
+ * "권한 요청하기"버튼을 눌러서 사진첩 읽기 권한을 요청할 수 있어요.
+ *
+ * ```tsx
+ * import { fetchAlbumPhotos, FetchAlbumPhotosPermissionError, ImageResponse } from '@apps-in-toss/framework';
+ * import { useState } from 'react';
+ * import { Alert, Button, Image, View } from 'react-native';
+ *
+ * const base64 = true;
+ *
+ * // 앨범 사진 목록을 가져와 화면에 표시하는 컴포넌트
+ * function AlbumPhotoList() {
+ *   const [albumPhotos, setAlbumPhotos] = useState<ImageResponse[]>([]);
+ *
+ *   const handlePress = async () => {
+ *     try {
+ *       const response = await fetchAlbumPhotos({
+ *         base64,
+ *         maxWidth: 360,
+ *       });
+ *       setAlbumPhotos((prev) => [...prev, ...response]);
+ *     } catch (error) {
+ *       if (error instanceof FetchAlbumPhotosPermissionError) {
+ *         // 앨범 읽기 권한 없음
+ *       }
+ *       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} />
+ *       <Button
+ *         title="권한 확인하기"
+ *         onPress={async () => {
+ *           const permission = await fetchAlbumPhotos.getPermission();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
+ *       <Button
+ *         title="권한 요청하기"
+ *         onPress={async () => {
+ *           const permission = await fetchAlbumPhotos.openPermissionDialog();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export const fetchAlbumPhotos = createPermissionFunction<FetchAlbumPhotos>({
+  handler: async (options) => {
+    return AppsInTossModule.fetchAlbumPhotos({
+      ...options,
+      maxCount: options?.maxCount ?? DEFAULT_MAX_COUNT,
+      maxWidth: options?.maxWidth ?? DEFAULT_MAX_WIDTH,
+    });
+  },
+  permission: {
+    name: 'photos',
+    access: 'read',
+  },
+  error: FetchAlbumPhotosPermissionError,
+});