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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@apps-in-toss/native-modules",
   "type": "module",
-  "version": "1.0.3",
+  "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": "380ad5f697a176bcc6adae409153fa43e700d053"
+  "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/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,4 +1,5 @@
 export * from './startUpdateLocation';
+export * from './StartUpdateLocationPermissionError';
 export * from './contactsViral';
 
 export { appsInTossEvent } from './appsInTossEvent';

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/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,
+});

package/src/AppsInTossModule/native-modules/{fetchContacts.ts → permissions/fetchContacts/fetchContacts.ts}

@@ -1,21 +1,6 @@
-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;
-}
+import { FetchContactsPermissionError, type FetchContacts } from '@apps-in-toss/types';
+import { AppsInTossModule } from '../../AppsInTossModule';
+import { createPermissionFunction } from '../createPermissionFunction';
 
 /**
  * @public
@@ -27,6 +12,9 @@ export interface ContactResult {
  * @param options.offset - 가져올 연락처의 시작 지점이에요. 처음 호출할 때는 `0`을 전달해야 해요. 이후에는 이전 호출에서 반환된 `nextOffset` 값을 사용해요.
  * @param options.query - 추가적인 필터링 옵션이에요.
  * @param options.query.contains - 이름에 특정 문자열이 포함된 연락처만 가져오고 싶을 때 사용해요. 이 값을 전달하지 않으면 모든 연락처를 가져와요.
+ * @property [openPermissionDialog] - 연락처 읽기 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 `allowed`를 반환하고, "안하기"를 선택하면 `denied`를 반환해요.
+ * @property [getPermission] - 연락처 읽기 권한의 현재 상태를 반환해요. `allowed`는 사용자가 연락처 읽기 권한을 허용한 상태예요. `denied`는 사용자가 연락처 읽기 권한을 거부한 상태예요. `notDetermined`는 연락처 읽기 권한 요청을 한 번도 하지 않은 상태예요.
+ *
  * @returns {Promise<ContactResult>}
  * 연락처 목록과 페이지네이션 정보를 포함한 객체를 반환해요.
  * - `result`: 가져온 연락처 목록이에요.
@@ -47,10 +35,15 @@ export interface ContactResult {
  * @example
  * ### 특정 문자열이 포함된 연락처 목록 가져오기
  *
+ * 연락처 목록을 가져오는 예제예요.
+ * "권한 확인하기"버튼을 눌러서 현재 연락처 읽기 권한을 확인해요.
+ * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`FetchContactsPermissionError`](/react-native/reference/types/권한/FetchContactsPermissionError)를 반환해요.
+ * "권한 요청하기"버튼을 눌러서 연락처 읽기 권한을 요청할 수 있어요.
+ *
  * ```tsx
- * import React, { useState } from 'react';
- * import { View, Text, Button } from 'react-native';
- * import { fetchContacts, ContactEntity } from '@apps-in-toss/framework';
+ * import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/framework';
+ * import { useState } from 'react';
+ * import { Alert, Button, Text, View } from 'react-native';
  *
  * // 특정 문자열을 포함한 연락처 목록을 가져와 화면에 표시하는 컴포넌트
  * function ContactsList() {
@@ -82,6 +75,9 @@ export interface ContactResult {
  *         done: response.done,
  *       }));
  *     } catch (error) {
+ *       if (error instanceof FetchContactsPermissionError) {
+ *         // 연락처 읽기 권한 없음
+ *       }
  *       console.error('연락처를 가져오는 데 실패했어요:', error);
  *     }
  *   };
@@ -89,33 +85,48 @@ export interface ContactResult {
  *   return (
  *     <View>
  *       {contacts.result.map((contact, index) => (
- *         <Text key={index}>{contact.name}: {contact.phoneNumber}</Text>
+ *         <Text key={index}>
+ *           {contact.name}: {contact.phoneNumber}
+ *         </Text>
  *       ))}
  *       <Button
  *         title={contacts.done ? '모든 연락처를 가져왔어요.' : '다음 연락처 가져오기'}
  *         disabled={contacts.done}
  *         onPress={handlePress}
  *       />
+ *       <Button
+ *         title="권한 확인하기"
+ *         onPress={async () => {
+ *           const permission = await fetchContacts.getPermission();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
+ *       <Button
+ *         title="권한 요청하기"
+ *         onPress={async () => {
+ *           const permission = await fetchContacts.openPermissionDialog();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
  *     </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,
-  };
-}
+
+export const fetchContacts = createPermissionFunction<FetchContacts>({
+  handler: async (options) => {
+    const contacts = await AppsInTossModule.fetchContacts(options);
+
+    return {
+      result: contacts.result,
+      nextOffset: contacts.nextOffset ?? null,
+      done: contacts.done,
+    };
+  },
+  permission: {
+    name: 'contacts',
+    access: 'read',
+  },
+  error: FetchContactsPermissionError,
+});