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

package/dist/index.d.ts

@@ -1,131 +1,14 @@
-import { EmitterSubscription, TurboModule } from 'react-native';
+import * as _apps_in_toss_types from '@apps-in-toss/types';
+import { Location, StartUpdateLocationEventParams, Accuracy, CompatiblePlaceholderArgument, SetClipboardTextOptions, FetchContactsOptions, ContactResult, FetchAlbumPhotosOptions, ImageResponse, GetCurrentLocationOptions, OpenCameraOptions, PermissionName, PermissionAccess, PermissionStatus, FetchAlbumPhotos, FetchContacts, GetClipboardText, GetCurrentLocation, SetClipboardText, OpenCamera } from '@apps-in-toss/types';
+export { StartUpdateLocationPermissionError } from '@apps-in-toss/types';
 import { GraniteEventDefinition, GraniteEvent } from '@granite-js/react-native';
+import { EmitterSubscription, TurboModule } from 'react-native';
 
 interface EventEmitterSchema<K extends string, P extends unknown[]> {
     name: K;
     params: P;
 }
 
-type PermissionStatus = 'notDetermined' | 'denied' | 'allowed';
-type PermissionAccess = 'read' | 'write' | 'access';
-type PermissionName = 'clipboard' | 'contacts' | 'photos' | 'geolocation' | 'camera';
-type Primitive = string | number | boolean | null | undefined | symbol;
-/**
- * @public
- * @category 위치 정보
- * @name Accuracy
- * @description 위치 정확도 옵션이에요.
- */
-declare enum Accuracy {
-    /**
-     * 오차범위 3KM 이내
-     */
-    Lowest = 1,
-    /**
-     * 오차범위 1KM 이내
-     */
-    Low = 2,
-    /**
-     * 오차범위 몇 백미터 이내
-     */
-    Balanced = 3,
-    /**
-     * 오차범위 10M 이내
-     */
-    High = 4,
-    /**
-     * 가장 높은 정확도
-     */
-    Highest = 5,
-    /**
-     * 네비게이션을 위한 최고 정확도
-     */
-    BestForNavigation = 6
-}
-/**
- * @public
- * @category 위치 정보
- * @name Location
- * @description 위치 정보를 나타내는 객체예요.
- */
-interface Location {
-    /**
-     * Android에서만 지원하는 옵션이에요.
-     *
-     * - `FINE`: 정확한 위치
-     * - `COARSE`: 대략적인 위치
-     *
-     * @see https://developer.android.com/codelabs/approximate-location
-     */
-    accessLocation?: 'FINE' | 'COARSE';
-    /**
-     * 위치가 업데이트된 시점의 유닉스 타임스탬프예요.
-     */
-    timestamp: number;
-    /**
-     * @description 위치 정보를 나타내는 객체예요. 자세한 내용은 [LocationCoords](/react-native/reference/native-modules/Types/LocationCoords.html)을 참고해주세요.
-     */
-    coords: LocationCoords;
-}
-/**
- * @public
- * @category 위치 정보
- * @name LocationCoords
- * @description 세부 위치 정보를 나타내는 객체예요.
- */
-interface LocationCoords {
-    /**
-     * 위도
-     */
-    latitude: number;
-    /**
-     * 경도
-     */
-    longitude: number;
-    /**
-     * 높이
-     */
-    altitude: number;
-    /**
-     * 위치 정확도
-     */
-    accuracy: number;
-    /**
-     * 고도 정확도
-     */
-    altitudeAccuracy: number;
-    /**
-     * 방향
-     */
-    heading: number;
-}
-/**
- * 사진 조회 결과를 나타내는 타입이에요.
- */
-interface ImageResponse {
-    /** 가져온 사진의 고유 ID예요. */
-    id: string;
-    /** 사진의 데이터 URI예요. `base64` 옵션이 `true`인 경우 Base64 문자열로 반환돼요. */
-    dataUri: string;
-}
-
-interface StartUpdateLocationOptions$1 {
-    /**
-     * 위치 정확도를 설정해요.
-     */
-    accuracy: Accuracy;
-    /**
-     * 위치 업데이트 주기를 밀리초(ms) 단위로 설정해요.
-     */
-    timeInterval: number;
-    /**
-     * 위치 변경 거리를 미터(m) 단위로 설정해요.
-     */
-    distanceInterval: number;
-}
-interface StartUpdateLocationSubscription extends EmitterSubscription {
-    remove: () => Promise<void>;
-}
 /**
  * @name UpdateLocationEventEmitter
  * @kind typedef
@@ -141,26 +24,46 @@ type UpdateLocationEventEmitter = EventEmitterSchema<'updateLocation', [Location
  * 실시간 위치 추적이 필요한 기능을 구현할 때 사용할 수 있어요. 예를 들어 지도 앱에서 사용자의 현재 위치를 실시간으로 업데이트할 때, 운동 앱에서 사용자의 이동 거리를 기록할 때 등이에요.
  * 위치 업데이트 주기와 정확도를 조정해 배터리 소모를 최소화하면서도 필요한 정보를 얻을 수 있어요.
  *
+ *
+ * @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,
@@ -170,33 +73,53 @@ type UpdateLocationEventEmitter = EventEmitterSchema<'updateLocation', [Location
  *         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>
  *   );
  * }
  * ```
  */
-declare function startUpdateLocation(eventParams: {
-    onEvent: (response: Location) => void;
-    onError: (error: unknown) => void;
-    options: StartUpdateLocationOptions$1;
-}): () => void;
+declare function startUpdateLocation(eventParams: StartUpdateLocationEventParams): () => void;
+declare namespace startUpdateLocation {
+    var openPermissionDialog: _apps_in_toss_types.PermissionDialogFunction;
+    var getPermission: _apps_in_toss_types.GetPermissionFunction;
+}
 
 /**
  * @public
@@ -1439,358 +1362,130 @@ interface CheckoutPaymentResult {
 declare function checkoutPayment(options: CheckoutPaymentOptions): Promise<CheckoutPaymentResult>;
 
 /**
- * 앨범 사진을 조회할 때 사용하는 옵션 타입이에요.
+ * @category 게임센터
+ * @name GameCenterGameProfileResponse
+ * @description 토스게임센터 프로필을 가져온 결과 타입이에요.
+ * 앱에 프로필이 없는 경우, `statusCode`가 `'PROFILE_NOT_FOUND'`이고 다른 정보는 없어요.
+ * 프로필이 있는 경우 `statusCode`가 `'SUCCESS'`이고, 닉네임과 프로필 이미지 주소가 함께 제공돼요.
+ * @property {string} statusCode 프로필 조회 결과 상태예요. `'SUCCESS'` 또는 `'PROFILE_NOT_FOUND'` 중 하나예요.
+ * @property {string} [nickname] 프로필 닉네임이에요. `statusCode`가 `'SUCCESS'`일 때만 있어요.
+ * @property {string} [profileImageUri] 프로필 이미지 URL이에요. `statusCode`가 `'SUCCESS'`일 때만 있어요.
  */
-interface FetchAlbumPhotosOptions {
-    /** 가져올 사진의 최대 개수를 설정해요. 숫자를 입력하고 기본값은 10이에요. */
-    maxCount?: number;
-    /** 사진의 최대 폭을 제한해요. 단위는 픽셀이고 기본값은 1024이에요. */
-    maxWidth?: number;
-    /** 이미지를 base64 형식으로 반환할지 설정해요. 기본값은 `false`예요. */
-    base64?: boolean;
-}
+type GameCenterGameProfileResponse = {
+    statusCode: 'PROFILE_NOT_FOUND';
+} | {
+    statusCode: 'SUCCESS';
+    nickname: string;
+    profileImageUri: string;
+};
 /**
- * @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를 포함한 배열을 반환해요.
+ * @category 게임센터
+ * @name getGameCenterGameProfile
+ * @description 토스게임센터 프로필 정보를 가져와요.
+ * 사용자가 프로필을 만들지 않았다면 `statusCode`가 `'PROFILE_NOT_FOUND'`인 응답이 반환돼요.
+ * 앱 버전이 최소 지원 버전(안드로이드 5.221.0, iOS 5.221.0)보다 낮으면 `undefined`를 반환해요.
+ * @returns {Promise<GameCenterGameProfileResponse | undefined>} 프로필 정보 또는 `undefined`를 반환해요.
  *
  * @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;
+ * import { getGameCenterGameProfile } from './getGameCenterGameProfile';
+ * import { useState } from 'react';
+ * import { View, Button } from 'react-native';
  *
- * // 앨범 사진 목록을 가져와 화면에 표시하는 컴포넌트
- * function AlbumPhotoList() {
- *   const [albumPhotos, setAlbumPhotos] = useState([]);
+ * function GameProfile() {
+ *   const [profile, setProfile] = useState<GameCenterGameProfileResponse | null>(null);
  *
  *   const handlePress = async () => {
  *     try {
- *       const response = await fetchAlbumPhotos({
- *         base64,
- *         maxWidth: 360,
- *       });
- *       setAlbumPhotos((prev) => ([...prev, ...response]));
+ *       const result = await getGameCenterGameProfile();
+ *       if (result) {
+ *         setProfile(result);
+ *       }
  *     } catch (error) {
- *       console.error('앨범을 가져오는 데 실패했어요:', 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} />
+ *       <Button title="게임센터 프로필 가져오기" onPress={handlePress} />
  *     </View>
  *   );
  * }
  * ```
  */
-declare function fetchAlbumPhotos(options: FetchAlbumPhotosOptions): Promise<ImageResponse[]>;
+declare function getGameCenterGameProfile(): Promise<GameCenterGameProfileResponse | undefined>;
 
 /**
- * 연락처 정보를 나타내는 타입이에요.
+ * @public
+ * @category 인앱결제
+ * @name IapCreateOneTimePurchaseOrderOptions
+ * @description 인앱결제 1건을 요청할 때 필요한 정보예요.
+ * @property {string} productId - 주문할 상품의 ID예요.
  */
-interface ContactEntity {
-    /** 연락처 이름이에요. */
-    name: string;
-    /** 연락처 전화번호로, 문자열 형식이에요. */
-    phoneNumber: string;
+interface IapCreateOneTimePurchaseOrderOptions {
+    productId: string;
 }
-interface ContactResult {
-    result: ContactEntity[];
-    nextOffset: number | null;
-    done: boolean;
+/**
+ * @public
+ * @category 인앱결제
+ * @name IapCreateOneTimePurchaseOrderResult
+ * @description 인앱결제 1건이 완료되면 결제 세부 정보와 상품 정보를 담아 반환해요. 반환된 정보로 결제한 상품의 정보를 화면에 표시할 수 있어요.
+ * @property {string} orderId - 결제 주문 ID이에요. 결제 완료 후 [결제 상태를 조회](https://developers-apps-in-toss.toss.im/api/getIapOrderStatus.html)할 때 사용해요.
+ * @property {string} displayName - 화면에 표시할 상품 이름이에요.
+ * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
+ * @property {number} amount - 상품 가격 숫자 값이에요. 화폐 단위와 쉼표를 제외한 순수 숫자예요. 예를 들어 `1000`으로 표시돼요.
+ * @property {string} currency - [ISO 4217 표준](https://ko.wikipedia.org/wiki/ISO_4217)에 따른 상품 가격 통화 단위예요. 예를 들어 원화는 `KRW`, 달러는 `USD`로 표시돼요.
+ * @property {number} fraction - 가격을 표시할 때 소수점 아래 몇 자리까지 보여줄지 정하는 값이에요. 예를 들어 달러는 소수점 둘째 자리까지 보여줘서 `2`, 원화는 소수점이 필요 없어서 `0`이에요
+ * @property {string | null} miniAppIconUrl - 미니앱 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요. 콘솔에서 아이콘을 등록하지 않았다면 `null`로 반환돼요.
+ */
+interface IapCreateOneTimePurchaseOrderResult {
+    orderId: string;
+    displayName: string;
+    displayAmount: string;
+    amount: number;
+    currency: string;
+    fraction: number;
+    miniAppIconUrl: string | null;
 }
 /**
  * @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`예요.
+ * @category 인앱결제
+ * @name iapCreateOneTimePurchaseOrder
+ * @description
+ * 특정 인앱결제 주문서 페이지로 이동해요. 사용자가 상품 구매 버튼을 누르는 상황 등에 사용할 수 있어요. 사용자의 결제는 이동한 페이지에서 진행돼요. 만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.
+ * @param {IapCreateOneTimePurchaseOrderOptions} params - 인앱결제를 생성할 때 필요한 정보예요.
+ * @param {string} params.productId - 주문할 상품의 ID예요.
+ * @returns {Promise<IapCreateOneTimePurchaseOrderResult | undefined>} 결제에 성공하면 결제 결과 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.219.0, iOS 5.219.0)보다 낮으면 인앱결제를 실행할 수 없어서 `undefined`를 반환해요.
  *
- * @signature
- * ```typescript
- * function fetchContacts(options: {
- *   size: number;
- *   offset: number;
- *   query?: {
- *     contains?: string;
- *   };
- * }): Promise<ContactResult>;
- * ```
+ * @throw {code: "INVALID_PRODUCT_ID"} - 유효하지 않은 상품 ID이거나, 해당 상품이 존재하지 않을 때 발생해요.
+ * @throw {code: "PAYMENT_PENDING"} - 사용자가 요청한 결제가 아직 승인을 기다리고 있을 때 발생해요.
+ * @throw {code: "NETWORK_ERROR"} - 서버 내부 문제로 요청을 처리할 수 없을 때 발생해요.
+ * @throw {code: "INVALID_USER_ENVIRONMENT"} - 특정 기기, 계정 또는 설정 환경에서 구매할 수 없는 상품일 때 발생해요.
+ * @throw {code: "ITEM_ALREADY_OWNED"} - 사용자가 이미 구매한 상품을 다시 구매하려고 할 때 발생해요.
+ * @throw {code: "APP_MARKET_VERIFICATION_FAILED"} - 사용자가 결제를 완료했지만, 앱스토어에서 사용자 정보 검증에 실패했을 때 발생해요. 사용자가 앱스토어에 문의해서 환불을 요청해야해요.
+ * @throw {code: "TOSS_SERVER_VERIFICATION_FAILED"} - 사용자가 결제를 완료했지만, 서버 전송에 실패해서 결제 정보를 저장할 수 없을 때 발생해요.
+ * @throw {code: "INTERNAL_ERROR"} - 서버 내부 문제로 요청을 처리할 수 없을 때 발생해요.
+ * @throw {code: "KOREAN_ACCOUNT_ONLY"} - iOS 환경에서 사용자의 계정이 한국 계정이 아닐 때 발생해요.
+ * @throw {code: "USER_CANCELED"} - 사용자가 결제를 완료하지 않고 주문서 페이지를 이탈했을 때 발생해요.
  *
  * @example
- * ### 특정 문자열이 포함된 연락처 목록 가져오기
+ * ### 특정 인앱결제 주문서 페이지로 이동하기
  *
  * ```tsx
- * import React, { useState } from 'react';
- * import { View, Text, Button } from 'react-native';
- * import { fetchContacts, ContactEntity } from '@apps-in-toss/framework';
+ * import { IAP } from "@apps-in-toss/web-framework";
+ * import { Button } from "@toss-design-system/react-native";
  *
- * // 특정 문자열을 포함한 연락처 목록을 가져와 화면에 표시하는 컴포넌트
- * function ContactsList() {
- *   const [contacts, setContacts] = useState<{
- *     result: ContactEntity[];
- *     nextOffset: number | null;
- *     done: boolean;
- *   }>({
- *     result: [],
- *     nextOffset: null,
- *     done: false,
- *   });
+ * interface Props {
+ *   productId: string;
+ * }
  *
- *   const handlePress = async () => {
+ * function IapCreateOneTimePurchaseOrderButton({ productId }: Props) {
+ *   async function handleClick() {
  *     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>
- *   );
- * }
- * ```
- */
-declare function fetchContacts(options: {
-    size: number;
-    offset: number;
-    query?: {
-        contains?: string;
-    };
-}): Promise<ContactResult>;
-
-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>
- *   );
- * }
- * ```
- */
-declare function getCurrentLocation(options: GetCurrentLocationOptions): Promise<Location>;
-
-/**
- * @category 게임센터
- * @name GameCenterGameProfileResponse
- * @description 토스게임센터 프로필을 가져온 결과 타입이에요.
- * 앱에 프로필이 없는 경우, `statusCode`가 `'PROFILE_NOT_FOUND'`이고 다른 정보는 없어요.
- * 프로필이 있는 경우 `statusCode`가 `'SUCCESS'`이고, 닉네임과 프로필 이미지 주소가 함께 제공돼요.
- * @property {string} statusCode 프로필 조회 결과 상태예요. `'SUCCESS'` 또는 `'PROFILE_NOT_FOUND'` 중 하나예요.
- * @property {string} [nickname] 프로필 닉네임이에요. `statusCode`가 `'SUCCESS'`일 때만 있어요.
- * @property {string} [profileImageUri] 프로필 이미지 URL이에요. `statusCode`가 `'SUCCESS'`일 때만 있어요.
- */
-type GameCenterGameProfileResponse = {
-    statusCode: 'PROFILE_NOT_FOUND';
-} | {
-    statusCode: 'SUCCESS';
-    nickname: string;
-    profileImageUri: string;
-};
-/**
- * @category 게임센터
- * @name getGameCenterGameProfile
- * @description 토스게임센터 프로필 정보를 가져와요.
- * 사용자가 프로필을 만들지 않았다면 `statusCode`가 `'PROFILE_NOT_FOUND'`인 응답이 반환돼요.
- * 앱 버전이 최소 지원 버전(안드로이드 5.221.0, iOS 5.221.0)보다 낮으면 `undefined`를 반환해요.
- * @returns {Promise<GameCenterGameProfileResponse | undefined>} 프로필 정보 또는 `undefined`를 반환해요.
- *
- * @example
- * ### 게임센터 프로필 가져오기
- * ```tsx
- * import { getGameCenterGameProfile } from './getGameCenterGameProfile';
- * import { useState } from 'react';
- * import { View, Button } from 'react-native';
- *
- * function GameProfile() {
- *   const [profile, setProfile] = useState<GameCenterGameProfileResponse | null>(null);
- *
- *   const handlePress = async () => {
- *     try {
- *       const result = await getGameCenterGameProfile();
- *       if (result) {
- *         setProfile(result);
- *       }
- *     } catch (error) {
- *       console.error('게임센터 프로필 가져오기에 실패했어요.', error);
- *     }
- *   };
- *
- *   return (
- *     <View>
- *       <Button title="게임센터 프로필 가져오기" onPress={handlePress} />
- *     </View>
- *   );
- * }
- * ```
- */
-declare function getGameCenterGameProfile(): Promise<GameCenterGameProfileResponse | undefined>;
-
-/**
- * @public
- * @category 인앱결제
- * @name IapCreateOneTimePurchaseOrderOptions
- * @description 인앱결제 1건을 요청할 때 필요한 정보예요.
- * @property {string} productId - 주문할 상품의 ID예요.
- */
-interface IapCreateOneTimePurchaseOrderOptions {
-    productId: string;
-}
-/**
- * @public
- * @category 인앱결제
- * @name IapCreateOneTimePurchaseOrderResult
- * @description 인앱결제 1건이 완료되면 결제 세부 정보와 상품 정보를 담아 반환해요. 반환된 정보로 결제한 상품의 정보를 화면에 표시할 수 있어요.
- * @property {string} orderId - 결제 주문 ID이에요. 결제 완료 후 [결제 상태를 조회](https://developers-apps-in-toss.toss.im/api/getIapOrderStatus.html)할 때 사용해요.
- * @property {string} displayName - 화면에 표시할 상품 이름이에요.
- * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
- * @property {number} amount - 상품 가격 숫자 값이에요. 화폐 단위와 쉼표를 제외한 순수 숫자예요. 예를 들어 `1000`으로 표시돼요.
- * @property {string} currency - [ISO 4217 표준](https://ko.wikipedia.org/wiki/ISO_4217)에 따른 상품 가격 통화 단위예요. 예를 들어 원화는 `KRW`, 달러는 `USD`로 표시돼요.
- * @property {number} fraction - 가격을 표시할 때 소수점 아래 몇 자리까지 보여줄지 정하는 값이에요. 예를 들어 달러는 소수점 둘째 자리까지 보여줘서 `2`, 원화는 소수점이 필요 없어서 `0`이에요
- * @property {string | null} miniAppIconUrl - 미니앱 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요. 콘솔에서 아이콘을 등록하지 않았다면 `null`로 반환돼요.
- */
-interface IapCreateOneTimePurchaseOrderResult {
-    orderId: string;
-    displayName: string;
-    displayAmount: string;
-    amount: number;
-    currency: string;
-    fraction: number;
-    miniAppIconUrl: string | null;
-}
-/**
- * @public
- * @category 인앱결제
- * @name iapCreateOneTimePurchaseOrder
- * @description
- * 특정 인앱결제 주문서 페이지로 이동해요. 사용자가 상품 구매 버튼을 누르는 상황 등에 사용할 수 있어요. 사용자의 결제는 이동한 페이지에서 진행돼요. 만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.
- * @param {IapCreateOneTimePurchaseOrderOptions} params - 인앱결제를 생성할 때 필요한 정보예요.
- * @param {string} params.productId - 주문할 상품의 ID예요.
- * @returns {Promise<IapCreateOneTimePurchaseOrderResult | undefined>} 결제에 성공하면 결제 결과 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.219.0, iOS 5.219.0)보다 낮으면 인앱결제를 실행할 수 없어서 `undefined`를 반환해요.
- *
- * @throw {code: "INVALID_PRODUCT_ID"} - 유효하지 않은 상품 ID이거나, 해당 상품이 존재하지 않을 때 발생해요.
- * @throw {code: "PAYMENT_PENDING"} - 사용자가 요청한 결제가 아직 승인을 기다리고 있을 때 발생해요.
- * @throw {code: "NETWORK_ERROR"} - 서버 내부 문제로 요청을 처리할 수 없을 때 발생해요.
- * @throw {code: "INVALID_USER_ENVIRONMENT"} - 특정 기기, 계정 또는 설정 환경에서 구매할 수 없는 상품일 때 발생해요.
- * @throw {code: "ITEM_ALREADY_OWNED"} - 사용자가 이미 구매한 상품을 다시 구매하려고 할 때 발생해요.
- * @throw {code: "APP_MARKET_VERIFICATION_FAILED"} - 사용자가 결제를 완료했지만, 앱스토어에서 사용자 정보 검증에 실패했을 때 발생해요. 사용자가 앱스토어에 문의해서 환불을 요청해야해요.
- * @throw {code: "TOSS_SERVER_VERIFICATION_FAILED"} - 사용자가 결제를 완료했지만, 서버 전송에 실패해서 결제 정보를 저장할 수 없을 때 발생해요.
- * @throw {code: "INTERNAL_ERROR"} - 서버 내부 문제로 요청을 처리할 수 없을 때 발생해요.
- * @throw {code: "KOREAN_ACCOUNT_ONLY"} - iOS 환경에서 사용자의 계정이 한국 계정이 아닐 때 발생해요.
- * @throw {code: "USER_CANCELED"} - 사용자가 결제를 완료하지 않고 주문서 페이지를 이탈했을 때 발생해요.
- *
- * @example
- * ### 특정 인앱결제 주문서 페이지로 이동하기
- *
- * ```tsx
- * import { IAP } from "@apps-in-toss/web-framework";
- * import { Button } from "@toss-design-system/react-native";
- *
- * interface Props {
- *   productId: string;
- * }
- *
- * function IapCreateOneTimePurchaseOrderButton({ productId }: Props) {
- *   async function handleClick() {
- *     try {
- *       await IAP.createOneTimePurchaseOrder({
- *         productId,
+ *       await IAP.createOneTimePurchaseOrder({
+ *         productId,
  *       });
  *       console.error("인앱결제에 성공했어요");
  *     } catch (error) {
@@ -1908,74 +1603,6 @@ declare const IAP: {
     getProductItemList: typeof getProductItemList;
 };
 
-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>
- *   );
- * }
- * ```
- */
-declare function openCamera(options?: OpenCameraOptions): Promise<ImageResponse>;
-
 interface SaveBase64DataParams {
     data: string;
     fileName: string;
@@ -2081,7 +1708,6 @@ declare function submitGameCenterLeaderBoardScore(params: {
     score: string;
 }): Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>;
 
-type CompatiblePlaceholderArgument = object;
 /**
  * TurboModule 타입 별칭 사용하는 이유?
  * React Native Codegen 에 의해 코드젠 되는 것이 아니라 추후 내부 모듈 체계에 의해 처리될 것이기 때문에 RN Codegen에 본 파일을 코드젠 하지 않도록 함
@@ -2092,13 +1718,15 @@ interface Spec extends TurboModule {
     operationalEnvironment: 'sandbox' | 'toss';
     tossAppVersion: string;
     deviceId: string;
+    getClipboardText: (arg: CompatiblePlaceholderArgument) => Promise<string>;
+    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;
     };
-    getClipboardText: (arg: CompatiblePlaceholderArgument) => Promise<string>;
-    setClipboardText: (option: {
-        text: string;
-    }) => Promise<void>;
     getPermission: (permission: {
         name: PermissionName;
         access: PermissionAccess;
@@ -2107,20 +1735,6 @@ interface Spec extends TurboModule {
         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';
@@ -2195,6 +1809,8 @@ declare function appLogin(): Promise<{
     referrer: 'DEFAULT' | 'SANDBOX';
 }>;
 
+type Primitive = string | number | boolean | null | undefined | symbol;
+
 interface EventLogParams {
     log_name: string;
     log_type: 'debug' | 'info' | 'warn' | 'error' | 'screen' | 'impression' | 'click';
@@ -2237,44 +1853,505 @@ interface EventLogParams {
  */
 declare function eventLog(params: EventLogParams): Promise<void>;
 
+/**
+ * @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>
+ *   );
+ * }
+ * ```
+ */
+declare const fetchAlbumPhotos: _apps_in_toss_types.PermissionFunctionWithDialog<FetchAlbumPhotos>;
+
+/**
+ * @public
+ * @category 연락처
+ * @name fetchContacts
+ * @description 사용자의 연락처 목록을 페이지 단위로 가져오는 함수예요.
+ * @param options - 연락처를 가져올 때 지정하는 옵션 객체예요.
+ * @param options.size - 한 번에 가져올 연락처 개수예요. 예를 들어, 10을 전달하면 최대 10개의 연락처를 가져와요.
+ * @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`: 가져온 연락처 목록이에요.
+ * - `nextOffset`: 다음 호출에 사용할 오프셋 값이에요. 더 가져올 연락처가 없으면 `null`이에요.
+ * - `done`: 모든 연락처를 다 가져왔는지 여부를 나타내요. 모두 가져왔다면 `true`예요.
+ *
+ * @signature
+ * ```typescript
+ * function fetchContacts(options: {
+ *   size: number;
+ *   offset: number;
+ *   query?: {
+ *     contains?: string;
+ *   };
+ * }): Promise<ContactResult>;
+ * ```
+ *
+ * @example
+ * ### 특정 문자열이 포함된 연락처 목록 가져오기
+ *
+ * 연락처 목록을 가져오는 예제예요.
+ * "권한 확인하기"버튼을 눌러서 현재 연락처 읽기 권한을 확인해요.
+ * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`FetchContactsPermissionError`](/react-native/reference/types/권한/FetchContactsPermissionError)를 반환해요.
+ * "권한 요청하기"버튼을 눌러서 연락처 읽기 권한을 요청할 수 있어요.
+ *
+ * ```tsx
+ * import { ContactEntity, fetchContacts, FetchContactsPermissionError } from '@apps-in-toss/framework';
+ * import { useState } from 'react';
+ * import { Alert, Button, Text, View } from 'react-native';
+ *
+ * // 특정 문자열을 포함한 연락처 목록을 가져와 화면에 표시하는 컴포넌트
+ * 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) {
+ *       if (error instanceof FetchContactsPermissionError) {
+ *         // 연락처 읽기 권한 없음
+ *       }
+ *       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}
+ *       />
+ *       <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>
+ *   );
+ * }
+ * ```
+ */
+declare const fetchContacts: _apps_in_toss_types.PermissionFunctionWithDialog<FetchContacts>;
+
 /**
  * @public
  * @category 클립보드
  * @name getClipboardText
  * @description 클립보드에 저장된 텍스트를 가져오는 함수예요. 복사된 텍스트를 읽어서 다른 작업에 활용할 수 있어요.
+ * @property [openPermissionDialog] - 클립보드 읽기 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 `allowed`를 반환하고, "안하기"를 선택하면 `denied`를 반환해요.
+ * @property [getPermission] - 클립보드 읽기 권한의 현재 상태를 반환해요. `allowed`는 사용자가 클립보드 읽기 권한을 허용한 상태예요. `denied`는 사용자가 클립보드 읽기 권한을 거부한 상태예요. `notDetermined`는 클립보드 읽기 권한 요청을 한 번도 하지 않은 상태예요.
  * @returns {Promise<string>} - 클립보드에 저장된 텍스트를 반환해요. 클립보드에 텍스트가 없으면 빈 문자열을 반환해요.
  *
+ * @signature
+ * ```typescript
+ * function getClipboardText(): Promise<string>;
+ * ```
+ *
  * @example
  * ### 클립보드의 텍스트 가져오기
  *
- * ```tsx
- * import React, { useState } from 'react';
- * import { View, Text, Button } from 'react-native';
- * import { getClipboardText } from '@apps-in-toss/framework';
+ * 클립보드의 텍스트를 가져오는 예제예요.
+ * "권한 확인하기"버튼을 눌러서 현재 클립보드 읽기 권한을 확인해요.
+ * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`GetClipboardTextPermissionError`](/react-native/reference/types/권한/GetClipboardTextPermissionError)를 반환해요.
+ * "권한 요청하기"버튼을 눌러서 클립보드 읽기 권한을 요청할 수 있어요.
  *
+ * ```tsx
+ * import {
+ *   getClipboardText,
+ *   GetClipboardTextPermissionError,
+ *   SetClipboardTextPermissionError,
+ * } from '@apps-in-toss/framework';
+ * import { useState } from 'react';
+ * import { Alert, Button, Text, View } from 'react-native'; *
+
  * // '붙여넣기' 버튼을 누르면 클립보드에 저장된 텍스트를 가져와 화면에 표시해요.
  * function PasteButton() {
- *   const [text, setText] = useState('');
- *
+ *   const [text, setText] = useState(''); *
+
  *   const handlePress = async () => {
  *     try {
  *       const clipboardText = await getClipboardText();
  *       setText(clipboardText || '클립보드에 텍스트가 없어요.');
  *     } catch (error) {
- *       console.error('클립보드에서 텍스트를 가져오지 못했어요:', error);
+ *       if (error instanceof GetClipboardTextPermissionError) {
+ *         // 클립보드 읽기 권한 없음
+ *       } *
+
+ *       if (error instanceof SetClipboardTextPermissionError) {
+ *         // 클립보드 쓰기 권한 없음
+ *       }
  *     }
- *   };
- *
+ *   }; *
+
  *   return (
  *     <View>
  *       <Text>{text}</Text>
  *       <Button title="붙여넣기" onPress={handlePress} />
+ *       <Button
+ *         title="권한 확인하기"
+ *         onPress={async () => {
+ *           const permission = await getClipboardText.getPermission();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
+ *       <Button
+ *         title="권한 요청하기"
+ *         onPress={async () => {
+ *           const permission = await getClipboardText.openPermissionDialog();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
  *     </View>
  *   );
  * }
  * ```
  */
-declare function getClipboardText(): Promise<string>;
+declare const getClipboardText: _apps_in_toss_types.PermissionFunctionWithDialog<GetClipboardText>;
+
+/**
+ * @public
+ * @category 위치 정보
+ * @name getCurrentLocation
+ * @description 디바이스의 현재 위치 정보를 가져오는 함수예요.
+ * 위치 기반 서비스를 구현할 때 사용되고, 한 번만 호출되어 현재 위치를 즉시 반환해요.
+ * 예를 들어 지도 앱에서 사용자의 현재 위치를 한 번만 가져올 때, 날씨 앱에서 사용자의 위치를 기반으로 기상 정보를 제공할 때, 매장 찾기 기능에서 사용자의 위치를 기준으로 가까운 매장을 검색할 때 사용하면 유용해요.
+ *
+ * @param {GetCurrentLocationOptions} options 위치 정보를 가져올 때 사용하는 옵션 객체예요.
+ * @param {Accuracy} [options.accuracy] 위치 정보의 정확도 수준이에요. 정확도는 `Accuracy` 타입으로 설정돼요.
+ * @property [openPermissionDialog] - 위치 정보 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 `allowed`를 반환하고, "안하기"를 선택하면 `denied`를 반환해요.
+ * @property [getPermission] - 위치 정보 권한의 현재 상태를 반환해요. `allowed`는 사용자가 위치 정보 권한을 허용한 상태예요. `denied`는 사용자가 위치 정보 권한을 거부한 상태예요. `notDetermined`는 위치 정보 권한 요청을 한 번도 하지 않은 상태예요.
+ * @returns {Promise<Location>} 디바이스의 위치 정보가 담긴 객체를 반환해요. 자세한 내용은 [Location](/react-native/reference/native-modules/Types/Location.html)을 참고해주세요.
+ *
+ * @signature
+ * ```typescript
+ * function getCurrentLocation(options: {
+ *   accuracy: Accuracy;
+ * }): Promise<Location>;
+ * ```
+ *
+ * @example
+ * ### 디바이스의 현재 위치 정보 가져오기
+ *
+ * "권한 확인하기"버튼을 눌러서 현재 위치정보 권한을 확인해요.
+ * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`GetCurrentLocationPermissionError`](/react-native/reference/types/권한/GetCurrentLocationPermissionError)를 반환해요.
+ * "권한 요청하기"버튼을 눌러서 위치정보 권한을 요청할 수 있어요.
+ *
+ * ```tsx
+ * import { Accuracy, getCurrentLocation, Location } from '@apps-in-toss/framework';
+ * import { useState } from 'react';
+ * import { Alert, Button, Text, View } from 'react-native';
+ *
+ * // 현재 위치 정보를 가져와 화면에 표시하는 컴포넌트
+ * function CurrentPosition() {
+ *   const [position, setPosition] = useState<Location | null>(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} />
+ *       <Button
+ *         title="권한 확인하기"
+ *         onPress={async () => {
+ *           Alert.alert(await getCurrentLocation.getPermission());
+ *         }}
+ *       />
+ *       <Button
+ *         title="권한 요청하기"
+ *         onPress={async () => {
+ *           Alert.alert(await getCurrentLocation.openPermissionDialog());
+ *         }}
+ *       />
+ *     </View>
+ *   );
+ * }
+ *
+ * ```
+ */
+declare const getCurrentLocation: _apps_in_toss_types.PermissionFunctionWithDialog<GetCurrentLocation>;
+
+/**
+ * @public
+ * @category 클립보드
+ * @name setClipboardText
+ * @description 텍스트를 클립보드에 복사해서 사용자가 다른 곳에 붙여 넣기 할 수 있어요.
+ * @param {Promise<void>} text - 클립보드에 복사할 텍스트예요. 문자열 형식으로 입력해요.
+ * @property [openPermissionDialog] - 클립보드 쓰기 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 `allowed`를 반환하고, "안하기"를 선택하면 `denied`를 반환해요.
+ * @property [getPermission] - 클립보드 쓰기 권한의 현재 상태를 반환해요. `allowed`는 사용자가 클립보드 쓰기 권한을 허용한 상태예요. `denied`는 사용자가 클립보드 쓰기 권한을 거부한 상태예요. `notDetermined`는 클립보드 쓰기 권한 요청을 한 번도 하지 않은 상태예요.
+ *
+ * @signature
+ * ```typescript
+ * function setClipboardText(text: string): Promise<void>;
+ * ```
+ *
+ * @example
+ * ### 텍스트를 클립보드에 복사하기
+ *
+ * 텍스트를 클립보드에 복사하는 예제예요.
+ * "권한 확인하기"버튼을 눌러서 현재 클립보드 쓰기 권한을 확인해요.
+ * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`SetClipboardTextPermissionError`](/react-native/reference/types/권한/SetClipboardTextPermissionError)를 반환해요.
+ * "권한 요청하기"버튼을 눌러서 클립보드 쓰기 권한을 요청할 수 있어요.
+ *
+ * ```tsx
+ * import { setClipboardText, SetClipboardTextPermissionError } from '@apps-in-toss/framework';
+ * import { Alert, Button } from 'react-native';
+ *
+ * // '복사' 버튼을 누르면 "복사할 텍스트"가 클립보드에 복사돼요.
+ * function CopyButton() {
+ *   const handleCopy = async () => {
+ *     try {
+ *       await setClipboardText('복사할 텍스트');
+ *       console.log('텍스트가 복사됐어요!');
+ *     } catch (error) {
+ *       if (error instanceof SetClipboardTextPermissionError) {
+ *         // 텍스트 쓰기 권한 거부됨
+ *       }
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <Button title="복사" onPress={handleCopy} />
+ *       <Button
+ *         title="권한 확인하기"
+ *         onPress={async () => {
+ *           const permission = await setClipboardText.getPermission();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
+ *       <Button
+ *         title="권한 요청하기"
+ *         onPress={async () => {
+ *           const permission = await setClipboardText.openPermissionDialog();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare const setClipboardText: _apps_in_toss_types.PermissionFunctionWithDialog<SetClipboardText>;
+
+/**
+ * @public
+ * @category 카메라
+ * @name openCamera
+ * @description 카메라를 실행해서 촬영된 이미지를 반환하는 함수예요.
+ * @param {OpenCameraOptions} options - 카메라 실행 시 사용되는 옵션 객체예요.
+ * @param {boolean} [options.base64=false] - 이미지를 Base64 형식으로 반환할지 여부를 나타내는 불리언 값이에요. 기본값은 `false`예요. `true`로 설정하면 `dataUri` 대신 Base64 인코딩된 문자열을 반환해요.
+ * @param {number} [options.maxWidth=1024] - 이미지의 최대 너비를 나타내는 숫자 값이에요. 기본값은 `1024`예요.
+ * @property [openPermissionDialog] - 카메라 접근 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 `allowed`를 반환하고, "안하기"를 선택하면 `denied`를 반환해요.
+ * @property [getPermission] - 카메라 접근 권한의 현재 상태를 반환해요. `allowed`는 사용자가 카메라 접근 권한을 허용한 상태예요. `denied`는 사용자가 카메라 접근 권한을 거부한 상태예요. `notDetermined`는 카메라 접근 권한 요청을 한 번도 하지 않은 상태예요.
+ * @returns {Promise<ImageResponse>}
+ * 촬영된 이미지 정보를 포함한 객체를 반환해요. 반환 객체의 구성은 다음과 같아요:
+ * - `id`: 이미지의 고유 식별자예요.
+ * - `dataUri`: 이미지 데이터를 표현하는 데이터 URI예요.
+ *
+ * @signature
+ * ```typescript
+ * function openCamera(options: {
+ *   base64: boolean;
+ *   maxWidth: number;
+ * }): Promise<ImageResponse>;
+ * ```
+ *
+ * @example
+ * ### 카메라 실행 후 촬영된 사진 가져오기
+ *
+ * 카메라로 사진을 찍고 결과를 가져오는 예제예요.
+ * 이 과정에서 현재 카메라 권한 상태를 확인할 수 있고, 권한이 없으면 권한을 요청해요.
+ * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`OpenCameraPermissionError`](/react-native/reference/types/권한/OpenCameraPermissionError)를 반환해요.
+ *
+ * ```tsx
+ * import { ImageResponse, openCamera, OpenCameraPermissionError } from '@apps-in-toss/framework';
+ * import { useState } from 'react';
+ * import { Alert, Button, Image, Text, View } from 'react-native';
+ *
+ * const base64 = true;
+ *
+ * // 카메라를 실행하고 촬영된 이미지를 화면에 표시하는 컴포넌트
+ * function Camera() {
+ *   const [image, setImage] = useState<ImageResponse | null>(null);
+ *
+ *   const handlePress = async () => {
+ *     try {
+ *       const response = await openCamera({ base64 });
+ *       setImage(response);
+ *     } catch (error) {
+ *       if (error instanceof OpenCameraPermissionError) {
+ *         console.log('권한 에러');
+ *       }
+ *
+ *       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} />
+ *       <Button
+ *         title="권한 확인하기"
+ *         onPress={async () => {
+ *           const permission = await openCamera.getPermission();
+ *           Alert.alert(permission);
+ *         }}
+ *       />
+ *
+ *       <Button
+ *         title="권한 요청하기"
+ *         onPress={async () => {
+ *           const currentPermission = await openCamera.openPermissionDialog();
+ *           Alert.alert(currentPermission);
+ *         }}
+ *       />
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+declare const openCamera: _apps_in_toss_types.PermissionFunctionWithDialog<OpenCamera>;
 
 /**
  * @public
@@ -2444,37 +2521,6 @@ declare function isMinVersionSupported(minVersions: {
     ios: `${number}.${number}.${number}` | 'always' | 'never';
 }): boolean;
 
-/**
- * @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} />;
- * }
- * ```
- */
-declare function setClipboardText(text: string): Promise<void>;
-
 /**
  * @public
  * @category 화면 제어
@@ -3143,4 +3189,4 @@ declare const INTERNAL__module: {
     tossCoreEventLog: typeof tossCoreEventLog;
 };
 
-export { Accuracy, AppsInTossModule, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type ContactEntity, type ContactResult, type ContactsViralParams, type EventLogParams, type FetchAlbumPhotosOptions, type GameCenterGameProfileResponse, type GetCurrentLocationOptions, GoogleAdMob, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type ImageResponse, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type Location, type LocationCoords, type NetworkStatus, type OpenCameraOptions, type PermissionAccess, type PermissionName, type PermissionStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, type StartUpdateLocationOptions$1 as StartUpdateLocationOptions, type StartUpdateLocationSubscription, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };
+export { AppsInTossModule, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type ContactsViralParams, type EventLogParams, type GameCenterGameProfileResponse, GoogleAdMob, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapProductListItem, type LoadAdMobEvent, type LoadAdMobInterstitialAdEvent, type LoadAdMobInterstitialAdOptions, type LoadAdMobOptions, type LoadAdMobParams, type LoadAdMobRewardedAdEvent, type LoadAdMobRewardedAdOptions, type NetworkStatus, type Primitive, type SaveBase64DataParams, type ShowAdMobEvent, type ShowAdMobInterstitialAdEvent, type ShowAdMobInterstitialAdOptions, type ShowAdMobOptions, type ShowAdMobParams, type ShowAdMobRewardedAdEvent, type ShowAdMobRewardedAdOptions, Storage, type SubmitGameCenterLeaderBoardScoreResponse, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getTossAppVersion, getTossShareLink, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };