@apps-in-toss/native-modules 1.14.1 → 2.0.0

package/dist/index.d.ts

@@ -1,1044 +1,826 @@
 import * as _apps_in_toss_types from '@apps-in-toss/types';
-import { Location, StartUpdateLocationEventParams, Accuracy, LoadAdMobParams, ShowAdMobParams, IsAdMobLoadedOptions, CompatiblePlaceholderArgument, SetClipboardTextOptions, FetchContactsOptions, ContactResult, FetchAlbumPhotosOptions, ImageResponse, GetCurrentLocationOptions, OpenCameraOptions, PermissionName, PermissionAccess, PermissionStatus, FetchAlbumPhotos, FetchContacts, GetClipboardText, GetCurrentLocation, SetClipboardText, OpenCamera } from '@apps-in-toss/types';
+import { CompatiblePlaceholderArgument, PermissionName, PermissionAccess, PermissionStatus, ContactResult, ImageResponse, Location, StartUpdateLocationEventParams, Accuracy, LoadAdMobParams, ShowAdMobParams, IsAdMobLoadedOptions, FetchAlbumPhotos, FetchContacts, GetClipboardText, GetCurrentLocation, SetClipboardText, OpenCamera } from '@apps-in-toss/types';
 export { IsAdMobLoadedOptions, LoadAdMobEvent, LoadAdMobOptions, LoadAdMobParams, ShowAdMobEvent, ShowAdMobOptions, ShowAdMobParams, StartUpdateLocationPermissionError } from '@apps-in-toss/types';
 import { GraniteEventDefinition, GraniteEvent } from '@granite-js/react-native';
-import { EmitterSubscription, TurboModule } from 'react-native';
+import { AnyObject } from 'brick-module';
 
-interface EventEmitterSchema<K extends string, P extends unknown[]> {
-    name: K;
-    params: P;
+interface AppsInTossSignTossCertParams {
+    txId: string;
 }
-
-/**
- * @name UpdateLocationEventEmitter
- * @kind typedef
- * @description
- * 디바이스의 위치 정보 변경을 감지해요
- */
-type UpdateLocationEventEmitter = EventEmitterSchema<'updateLocation', [Location]>;
 /**
  * @public
- * @category 위치 정보
- * @name startUpdateLocation
- * @description  디바이스의 위치 정보를 지속적으로 감지하고, 위치가 변경되면 콜백을 실행하는 함수예요. 콜백 함수를 등록하면 위치가 변경될 때마다 자동으로 호출돼요.
- * 실시간 위치 추적이 필요한 기능을 구현할 때 사용할 수 있어요. 예를 들어 지도 앱에서 사용자의 현재 위치를 실시간으로 업데이트할 때, 운동 앱에서 사용자의 이동 거리를 기록할 때 등이에요.
- * 위치 업데이트 주기와 정확도를 조정해 배터리 소모를 최소화하면서도 필요한 정보를 얻을 수 있어요.
- *
- *
- * @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) 단위로 설정해요.
- *
- * @property [openPermissionDialog] - 위치 정보 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 `allowed`를 반환하고, "안하기"를 선택하면 `denied`를 반환해요.
- * @property [getPermission] - 위치 정보 권한의 현재 상태를 반환해요. `allowed`는 사용자가 위치 정보 권한을 허용한 상태예요. `denied`는 사용자가 위치 정보 권한을 거부한 상태예요. `notDetermined`는 위치 정보 권한 요청을 한 번도 하지 않은 상태예요.
+ * @category 토스인증
+ * @name appsInTossSignTossCert
+ * @description 토스 인증서를 사용해 서명하는 기능을 제공해요. 이 함수를 사용하면 앱인토스에서 제공하는 인증서를 활용해 서명을 할 수 있어요.
  *
- * @signature
- * ```typescript
- * function startUpdateLocation(options: {
- *   onError: (error: unknown) => void;
- *   onEvent: (location: Location) => void;
- *   options: StartUpdateLocationOptions;
- * }): () => void;
- * ```
+ * @param {AppsInTossSignTossCertParams} params - 서명에 필요한 파라미터를 포함하는 객체예요.
+ * @param {string} params.txId - 토스인증서를 사용한 본인확인이나 간편인증, 전자서명에서 사용하는 Transaction Id예요.
  *
  * @example
- * ### 위치 정보 변경 감지하기
- *
- * 위치 정보가 변경되는것을 감지하는 예제예요. "위치 정보 변경 감지하기"를 눌러서 감지할 수 있어요.
- *
- * "권한 확인하기"버튼을 눌러서 현재 위치 정보 변경 감지 권한을 확인해요.
- * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`StartUpdateLocationPermissionError`](/react-native/reference/types/권한/StartUpdateLocationPermissionError)를 반환해요.
- * "권한 요청하기"버튼을 눌러서 위치 정보 변경 감지 권한을 요청할 수 있어요.
- *
  * ```tsx
- * 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<Location | null>(null);
- *
- *   const handlePress = useCallback(() => {
- *     startUpdateLocation({
- *       options: {
- *         accuracy: Accuracy.Balanced,
- *         timeInterval: 3000,
- *         distanceInterval: 10,
- *       },
- *       onEvent: (location) => {
- *         setLocation(location);
- *       },
- *       onError: (error) => {
- *         if (error instanceof StartUpdateLocationPermissionError) {
- *           // 위치 정보 변경 감지 권한 없음
- *         }
- *         console.error('위치 정보를 가져오는데 실패했어요:', error);
- *       },
- *     });
- *   }, []);
- *
- *   return (
- *     <View>
- *       {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>
- *         </>
- *       )}
+ * import { appsInTossSignTossCert } from '@apps-in-toss/framework';
  *
- *       <Button title="위치 정보 변경 감지하기" onPress={handlePress} />
+ *  // 서명에 필요한 파라미터를 정의해요.
+ *  const params = {
+ *    txId: "f2e1a6df..."
+ *  };
  *
- *       <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>
- *   );
- * }
+ * appsInTossSignTossCert(params)
+ *   .then(() => {
+ *     console.log('서명 작업이 성공적으로 완료되었어요.');
+ *   })
+ *   .catch((error) => {
+ *     console.error('서명 작업 중 에러가 발생했어요:', error);
+ *   });
  * ```
  */
-declare function startUpdateLocation(eventParams: StartUpdateLocationEventParams): () => void;
-declare namespace startUpdateLocation {
-    var openPermissionDialog: _apps_in_toss_types.PermissionDialogFunction;
-    var getPermission: _apps_in_toss_types.GetPermissionFunction;
-}
+declare function appsInTossSignTossCert(params: AppsInTossSignTossCertParams): Promise<void>;
 
 /**
  * @public
- * @category 친구초대
- * @name RewardFromContactsViralEvent
- * @description 친구에게 공유하기를 완료했을 때 지급할 리워드 정보를 담는 타입이에요. 이 타입을 사용하면 공유가 완료됐을 때 지급할 리워드 정보를 확인할 수 있어요.
- * @property {'sendViral'} type - 이벤트의 타입이에요. `'sendViral'`은 사용자가 친구에게 공유를 완료했을 때 돌아와요.
- * @property {Object} data - 지급할 리워드 관련 정보를 담고 있어요.
- * @property {number} data.rewardAmount - 지급할 리워드 수량이에요. 앱인토스 콘솔에서 설정한 수량 및 금액 값이에요.
- * @property {string} data.rewardUnit - 리워드의 단위예요. 앱인토스 콘솔에 설정된 리워드 이름인 '하트', '보석' 등이 리워드 단위예요.
- */
-type RewardFromContactsViralEvent = {
-    type: 'sendViral';
-    data: {
-        rewardAmount: number;
-        rewardUnit: string;
-    };
-};
-/**
- * @public
- * @category 친구초대
- * @name ContactsViralSuccessEvent
- * @description 연락처 공유 모듈이 정상적으로 종료됐을 때 전달되는 이벤트 객체예요. 종료 이유와 함께 리워드 상태 및 남은 친구 수 등 관련 정보를 제공해요.
- * @property {'close'} type - 이벤트의 타입이에요. `'close'`는 공유 모듈이 종료됐을 때 돌아와요.
- * @property {Object} data - 모듈 종료와 관련된 세부 정보를 담고 있어요.
- * @property {'clickBackButton' | 'noReward'} data.closeReason - 모듈이 종료된 이유예요. `'clickBackButton'`은 사용자가 뒤로 가기 버튼을 눌러 종료한 경우이고, `'noReward'`는 받을 수 있는 리워드가 없어서 종료된 경우예요.
- * @property {number} data.sentRewardAmount - 사용자가 받은 전체 리워드 수량이에요.
- * @property {number} data.sendableRewardsCount - 아직 공유할 수 있는 친구 수예요.
- * @property {number} data.sentRewardsCount - 사용자가 공유를 완료한 친구 수예요.
- * @property {string} data.rewardUnit - 리워드의 단위예요. 앱인토스 콘솔에 설정된 리워드 이름인 '하트', '보석' 등이 리워드 단위예요.
- */
-type ContactsViralSuccessEvent = {
-    type: 'close';
-    data: {
-        closeReason: 'clickBackButton' | 'noReward';
-        sentRewardAmount?: number;
-        sendableRewardsCount?: number;
-        sentRewardsCount: number;
-        rewardUnit?: string;
-    };
-};
-type ContactsViralEvent = RewardFromContactsViralEvent | ContactsViralSuccessEvent;
-/**
- * @public
- * @category 친구초대
- * @name ContactsViralOption
- * @description [연락처 공유 기능](/react-native/reference/native-modules/친구초대/contactsViral.html)을 사용할 때 필요한 옵션이에요.
- * @property {string} moduleId - 공유 리워드를 구분하는 UUID 형식의 고유 ID예요. 앱인토스 콘솔의 미니앱 > 공유 리워드 메뉴에서 확인할 수 있어요.
+ * @category 토스페이
+ * @name CheckoutPaymentOptions
+ * @description 토스페이 결제창을 띄울 때 필요한 옵션이에요.
+ * @property {string} payToken 결제 토큰이에요.
  */
-type ContactsViralOption = {
-    moduleId: string;
-};
+interface CheckoutPaymentOptions {
+    /**
+     * 결제 토큰이에요.
+     */
+    payToken: string;
+}
 /**
  * @public
- * @category 친구초대
- * @name ContactsViralParams
- * @description `ContactsViralParams`는 연락처 공유 기능을 사용할 때 전달해야 하는 파라미터 타입이에요. 옵션을 설정하고, 이벤트 및 에러 처리 콜백을 지정할 수 있어요.
- * @property {ContactsViralOption} options - 공유 기능에 사용할 옵션 객체예요.
- * @property {(event: ContactsViralEvent) => void} onEvent - 공유 이벤트가 발생했을 때 실행되는 함수예요. [`RewardFromContactsViralEvent`](/bedrock/reference/native-modules/친구초대/RewardFromContactsViralEvent.html) 또는 [`ContactsViralSuccessEvent`](/react-native/reference/native-modules/친구초대/ContactsViralSuccessEvent.html) 타입의 이벤트 객체가 전달돼요.
- * @property {(error: unknown) => void} onError - 예기치 않은 에러가 발생했을 때 실행되는 함수예요.
+ * @category 토스페이
+ * @name CheckoutPaymentResult
+ * @description 토스페이 결제창에서 사용자가 인증에 성공했는지 여부예요.
+ * @property {boolean} success 인증이 성공했는지 여부예요.
+ * @property {string} [reason] 인증이 실패했을 경우의 이유예요.
  */
-interface ContactsViralParams {
-    options: ContactsViralOption;
-    onEvent: (event: ContactsViralEvent) => void;
-    onError: (error: unknown) => void;
+interface CheckoutPaymentResult {
+    /**
+     * 인증이 성공했는지 여부예요.
+     */
+    success: boolean;
+    /**
+     * 인증이 실패했을 경우의 이유예요.
+     */
+    reason?: string;
 }
 /**
  * @public
- * @category 친구초대
- * @name contactsViral
- * @description 친구에게 공유하고 리워드를 받을 수 있는 기능을 제공해요. 사용자가 친구에게 공유를 완료하면 앱브릿지가 이벤트를 통해 리워드 정보를 전달해요.
- * @param {ContactsViralParams} params - 연락처 공유 기능을 실행할 때 사용하는 파라미터예요. 옵션 설정과 이벤트 핸들러를 포함해요. 자세한 내용은 [ContactsViralParams](/bedrock/reference/native-modules/친구초대/ContactsViralParams.html) 문서를 참고하세요.
- * @returns {() => void} 앱브릿지 cleanup 함수를 반환해요. 공유 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.
+ * @category 토스페이
+ * @name checkoutPayment
+ * @description 토스페이 결제창을 띄우고, 사용자 인증을 수행해요. 인증이 완료되면 성공 여부를 반환해요.
+ *
+ * 이 함수는 결제창을 통해 사용자 인증만 해요. 실제 결제 처리는 인증 성공 후 서버에서 별도로 해야 해요.
+ *
+ * @param {CheckoutPaymentOptions} options 결제창을 띄울 때 필요한 옵션이에요.
+ * @returns {Promise<CheckoutPaymentResult>} 인증 성공 여부를 포함한 결과를 반환해요.
  *
  * @example
- * ### 친구에게 공유하고 리워드 받기
+ *
+ * ### 토스페이 결제창 띄우고 인증 처리하기
  *
  * ```tsx
- * import { useCallback } from 'react';
- * import { Button } from 'react-native';
- * import { contactsViral } from '@apps-in-toss/framework';
+ * import { TossPay } from '@apps-in-toss/framework';
  *
- * function ContactsViralButton({ moduleId }: { moduleId: string }) {
- *   const handleContactsViral = useCallback(() => {
- *     try {
- *       const cleanup = contactsViral({
- *         options: { moduleId: moduleId.trim() },
- *         onEvent: (event) => {
- *           if (event.type === 'sendViral') {
- *             console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
- *           } else if (event.type === 'close') {
- *             console.log('모듈 종료:', event.data.closeReason);
- *           }
- *         },
- *         onError: (error) => {
- *           console.error('에러 발생:', error);
- *         },
- *       });
+ * async function handlePayment() {
+ *   try {
+ *     // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해주세요.
+ *     const { payToken } = await fetch('/my-api/payment/create').then(res => res.json());
  *
- *       return cleanup;
- *     } catch (error) {
- *       console.error('실행 중 에러:', error);
- *     }
- *   }, [moduleId]);
+ *     const { success, reason } = await TossPay.checkoutPayment({ payToken });
  *
- *   return <Button title="친구에게 공유하고 리워드 받기" onPress={handleContactsViral} />;
- * }
- * ```
+ *     if (success) {
+ *       // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해주세요.
+ *       await fetch('/my-api/payment/execute', {
+ *         method: 'POST',
+ *         body: JSON.stringify({ payToken }),
+ *         headers: { 'Content-Type': 'application/json' },
+ *       });
+ *     } else {
+ *       console.log('인증 실패:', reason);
+ *     }
+ *   } catch (error) {
+ *     console.error('결제 인증 중 오류가 발생했어요:', error);
+ *   }
+ * }
+ * ```
  */
-declare function contactsViral(params: ContactsViralParams): () => void;
+declare function checkoutPayment(options: {
+    params: CheckoutPaymentOptions;
+}): Promise<CheckoutPaymentResult>;
 
-interface StartUpdateLocationOptions {
-    /**
-     * 위치 정확도를 설정해요.
-     */
-    accuracy: Accuracy;
-    /**
-     * 위치 업데이트 주기를 밀리초(ms) 단위로 설정해요.
-     */
-    timeInterval: number;
-    /**
-     * 위치 변경 거리를 미터(m) 단위로 설정해요.
-     */
-    distanceInterval: number;
-}
-declare class UpdateLocationEvent extends GraniteEventDefinition<StartUpdateLocationOptions, Location> {
-    name: "updateLocationEvent";
-    subscriptionCount: number;
-    ref: {
-        remove: () => void;
-    };
-    remove(): void;
-    listener(options: StartUpdateLocationOptions, onEvent: (response: Location) => void, onError: (error: unknown) => void): void;
-}
-
-interface AppBridgeCallbackResult {
-    name: string;
-    params?: any;
-}
-declare class AppBridgeCallbackEvent extends GraniteEventDefinition<void, AppBridgeCallbackResult> {
-    private static INTERNAL__appBridgeSubscription?;
-    name: "appBridgeCallbackEvent";
-    constructor();
-    remove(): void;
-    listener(): void;
-    private registerAppBridgeCallbackEventListener;
-    private ensureInvokeAppBridgeCallback;
-}
+/**
+ * @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>;
 
-interface VisibilityChangedByTransparentServiceWebOptions {
-    callbackId: string;
-}
-declare class VisibilityChangedByTransparentServiceWebEvent extends GraniteEventDefinition<VisibilityChangedByTransparentServiceWebOptions, boolean> {
-    name: "onVisibilityChangedByTransparentServiceWeb";
-    subscription: EmitterSubscription | null;
-    remove(): void;
-    listener(options: VisibilityChangedByTransparentServiceWebOptions, onEvent: (isVisible: boolean) => void, onError: (error: unknown) => void): void;
-    private isVisibilityChangedByTransparentServiceWebResult;
+interface GetUserKeyForGameSuccessResponse {
+    hash: string;
+    type: 'HASH';
 }
-
-declare const appsInTossEvent: GraniteEvent<UpdateLocationEvent | AppBridgeCallbackEvent | VisibilityChangedByTransparentServiceWebEvent>;
-
-declare function onVisibilityChangedByTransparentServiceWeb(eventParams: {
-    options: {
-        callbackId: string;
-    };
-    onEvent: (isVisible: boolean) => void;
-    onError: (error: unknown) => void;
-}): () => void;
-
-interface AppBridgeCompatCallbacks<Result> {
-    onSuccess: (result: Result) => void;
-    onError: (reason: unknown) => void;
+interface GetUserKeyForGameErrorResponse {
+    type: 'NOT_AVAILABLE';
 }
-type AppBridgeCallback = (...args: any[]) => void;
-declare function invokeAppBridgeCallback(id: string, ...args: any[]): boolean;
-declare function invokeAppBridgeMethod<Result = any, Params = any>(methodName: string, params: Params, callbacks: AppBridgeCompatCallbacks<Result> & Record<string, AppBridgeCallback>): () => void;
-declare function registerCallback(callback: AppBridgeCallback, name?: string): string;
-declare function unregisterCallback(id: string): void;
-declare function getCallbackIds(): string[];
-declare const INTERNAL__appBridgeHandler: {
-    invokeAppBridgeCallback: typeof invokeAppBridgeCallback;
-    invokeAppBridgeMethod: typeof invokeAppBridgeMethod;
-    registerCallback: typeof registerCallback;
-    unregisterCallback: typeof unregisterCallback;
-    getCallbackIds: typeof getCallbackIds;
-};
-
+type GetUserKeyForGameResponse = GetUserKeyForGameSuccessResponse | GetUserKeyForGameErrorResponse;
 /**
  * @public
- * @category 광고
- * @name loadAppsInTossAdMob
- * @description 광고를 미리 불러와서, 광고가 필요한 시점에 바로 보여줄 수 있도록 준비하는 함수예요.
- * @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/native-modules/광고/LoadAdMobEvent.html)를 참고하세요.
- * @param {(reason: unknown) => void} [params.onError] 광고를 불러오지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
- * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
+ * @category 게임
+ * @name getUserKeyForGame
+ * @description
+ * 게임 카테고리 미니앱에서 사용자의 고유 키를 가져와요. 이 키를 사용해서 사용자를 식별하고 게임 데이터를 관리할 수 있어요.
+ * 게임 카테고리가 아닌 미니앱에서 호출하면 `'INVALID_CATEGORY'`를 반환해요.
+ * @returns {Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>}
+ * 사용자 키 조회 결과를 반환해요.
+ * - `GetUserKeyForGameSuccessResponse`: 사용자 키 조회에 성공했어요. `{ type: 'HASH', hash: string }` 형태로 반환돼요.
+ * - `'INVALID_CATEGORY'`: 게임 카테고리가 아닌 미니앱에서 호출했어요.
+ * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
+ * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
  *
  * @example
- * ### 버튼 눌러 불러온 광고 보여주기
  * ```tsx
- * import { GoogleAdMob } from '@apps-in-toss/framework';
- * import { useFocusEffect } from '@react-native-bedrock/native/@react-navigation/native';
- * import { useCallback, useState } from 'react';
- * import { Button, Text, View } from 'react-native';
- * import { useNavigation } from 'react-native-bedrock';
- *
- * const AD_GROUP_ID = '<AD_GROUP_ID>';
+ * // react-native
+ * import { Button } from 'react-native';
+ * import { getUserKeyForGame } from '@apps-in-toss/framework';
  *
- * export function GoogleAdmobExample() {
- *   const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
- *   const navigation = useNavigation();
+ * function GameUserKeyButton() {
+ *   async function handlePress() {
+ *       const result = await getUserKeyForGame();
  *
- *   const loadAd = useCallback(() => {
- *     if (GoogleAdMob.loadAppsInTossAdMob.isSupported() !== true) {
- *       return;
- *     }
-
- *     const cleanup = GoogleAdMob.loadAppsInTossAdMob({
- *       options: {
- *         adGroupId: AD_GROUP_ID,
- *       },
- *       onEvent: (event) => {
- *         switch (event.type) {
- *           case 'loaded':
- *             console.log('광고 로드 성공', event.data);
- *             setAdLoadStatus('loaded');
- *             break;
- *         }
- *       },
- *       onError: (error) => {
- *         console.error('광고 불러오기 실패', error);
- *       },
- *     });
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
  *
- *     return cleanup;
- *   }, [navigation]);
+ *       if (result === 'INVALID_CATEGORY') {
+ *         console.error('게임 카테고리가 아닌 미니앱이에요.');
+ *         return;
+ *       }
  *
- *   const showAd = useCallback(() => {
- *     if (GoogleAdMob.showAppsInTossAdMob.isSupported() !== true) {
- *       return;
- *     }
+ *       if (result === 'ERROR') {
+ *         console.error('사용자 키 조회 중 오류가 발생했어요.');
+ *         return;
+ *       }
  *
- *     GoogleAdMob.showAppsInTossAdMob({
- *       options: {
- *         adGroupId: AD_GROUP_ID,
- *       },
- *       onEvent: (event) => {
- *         switch (event.type) {
- *           case 'requested':
- *             console.log('광고 보여주기 요청 완료');
- *             break;
+ *       if (result.type === 'HASH') {
+ *         console.log('사용자 키:', result.hash);
+ *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
+ *       }
+ *   }
  *
- *           case 'clicked':
- *             console.log('광고 클릭');
- *             break;
+ *   return (
+ *     <Button onPress={handlePress} title="유저 키 가져오기" />
+ *   );
+ * }
+ * ```
  *
- *           case 'dismissed':
- *             console.log('광고 닫힘');
- *             navigation.navigate('/examples/google-admob-interstitial-ad-landing');
- *             break;
+ * @example
+ * ```tsx
+ * // webview
+ * import { getUserKeyForGame } from '@apps-in-toss/web-framework';
  *
- *           case 'failedToShow':
- *             console.log('광고 보여주기 실패');
- *             break;
+ * function GameUserKeyButton() {
+ *   async function handleClick() {
+ *       const result = await getUserKeyForGame();
  *
- *           case 'impression':
- *             console.log('광고 노출');
- *             break;
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
  *
- *           case 'userEarnedReward':
- *             console.log('광고 보상 획득 unitType:', event.data.unitType);
- *             console.log('광고 보상 획득 unitAmount:', event.data.unitAmount);
- *             break;
+ *       if (result === 'INVALID_CATEGORY') {
+ *         console.error('게임 카테고리가 아닌 미니앱이에요.');
+ *         return;
+ *       }
  *
- *           case 'show':
- *             console.log('광고 컨텐츠 보여졌음');
- *             break;
- *         }
- *       },
- *       onError: (error) => {
- *         console.error('광고 보여주기 실패', error);
- *       },
- *     });
- *   }, []);
+ *       if (result === 'ERROR') {
+ *         console.error('사용자 키 조회 중 오류가 발생했어요.');
+ *         return;
+ *       }
  *
- *   useFocusEffect(loadAd);
+ *       if (result.type === 'HASH') {
+ *         console.log('사용자 키:', result.hash);
+ *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
+ *       }
+ *   }
  *
  *   return (
- *     <View>
- *       <Text>
- *         {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
- *         {adLoadStatus === 'loaded' && '광고 로드 완료'}
- *         {adLoadStatus === 'failed' && '광고 로드 실패'}
- *       </Text>
- *
- *       <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
- *     </View>
+ *     <button onClick={handleClick}>유저 키 가져오기</button>
  *   );
  * }
  * ```
  */
-declare function loadAppsInTossAdMob(params: LoadAdMobParams): () => void;
-declare namespace loadAppsInTossAdMob {
-    var isSupported: () => boolean;
-}
+declare function getUserKeyForGame(): Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>;
 
+interface GrantPromotionRewardForGameSuccessResponse {
+    key: string;
+}
+interface GrantPromotionRewardForGameErrorResponse {
+    code: string;
+    [key: string]: any;
+}
+interface GrantPromotionRewardForGameErrorResult {
+    errorCode: string;
+    message: string;
+}
+type GrantPromotionRewardForGameResponse = GrantPromotionRewardForGameSuccessResponse | GrantPromotionRewardForGameErrorResponse;
+type GrantPromotionRewardForGameResult = GrantPromotionRewardForGameResponse | GrantPromotionRewardForGameErrorResult | 'ERROR' | undefined;
 /**
  * @public
- * @category 광고
- * @name showAppsInTossAdMob
- * @description 광고를 사용자에게 노출해요. 이 함수는 `loadAppsInTossAdMob` 로 미리 불러온 광고를 실제로 사용자에게 노출해요.
- * @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/native-modules/광고/ShowAdMobEvent.html)를 참고하세요.
- * @param {(reason: unknown) => void} [params.onError] 광고를 노출하지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
- * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
- *
- * @example
- * ### 버튼 눌러 불러온 광고 보여주기
- * ```tsx
- * import { GoogleAdMob } from '@apps-in-toss/framework';
- * import { useFocusEffect } from '@react-native-bedrock/native/@react-navigation/native';
- * import { useCallback, useState } from 'react';
- * import { Button, Text, View } from 'react-native';
- * import { useNavigation } from 'react-native-bedrock';
- *
- * const AD_GROUP_ID = '<AD_GROUP_ID>';
- *
- * export function GoogleAdmobExample() {
- *   const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
- *   const navigation = useNavigation();
- *
- *   const loadAd = useCallback(() => {
- *     if (GoogleAdMob.loadAppsInTossAdMob.isSupported() !== true) {
- *       return;
- *     }
-
- *     const cleanup = GoogleAdMob.loadAppsInTossAdMob({
- *       options: {
- *         adGroupId: AD_GROUP_ID,
- *       },
- *       onEvent: (event) => {
- *         switch (event.type) {
- *           case 'loaded':
- *             console.log('광고 로드 성공', event.data);
- *             setAdLoadStatus('loaded');
- *             break;
- *         }
- *       },
- *       onError: (error) => {
- *         console.error('광고 불러오기 실패', error);
- *       },
- *     });
+ * @category 게임
+ * @name grantPromotionRewardForGame
+ * @description
+ * 이 함수를 사용하면 게임 카테고리 미니앱에서 프로모션 코드를 사용해서 유저에게 리워드를 지급할 수 있어요.
+ * 게임 카테고리가 아닌 미니앱에서 호출할 수 없어요.
+ * @param {{ params: { promotionCode: string; amount: number } }} params - 포인트를 지급하기 위해 필요한 정보예요.
+ * @param {string} params.promotionCode - 프로모션 코드예요.
+ * @param {number} params.amount - 지급할 포인트 금액이에요.
+ * @returns {Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>}
+ * 포인트 지급 결과를 반환해요.
+ * - `{ key: string }`: 포인트 지급에 성공했어요. key는 리워드 키를 의미해요.
+ * - `{ errorCode: string, message: string }`: 포인트 지급에 실패했어요. 에러 코드는 다음과 같아요.
+ *   - `"40000"`: 게임이 아닌 미니앱에서 호출했을 때
+ *   - `"4100"`: 프로모션 정보를 찾을 수 없을 때
+ *   - `"4104"`: 프로모션이 중지되었을 때
+ *   - `"4105"`: 프로모션이 종료되었을 때
+ *   - `"4108"`: 프로모션이 승인되지 않았을 때
+ *   - `"4109"`: 프로모션이 실행중이 아닐 때
+ *   - `"4110"`: 리워드를 지급/회수할 수 없을 때
+ *   - `"4112"`: 프로모션 머니가 부족할 때
+ *   - `"4113"`: 이미 지급/회수된 내역일 때
+ *   - `"4114"`: 프로모션에 설정된 1회 지급 금액을 초과할 때
+ * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
+ * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
+ * @example
+ * ```tsx
+ * // react-native
+ * import { Button } from 'react-native';
+ * import { grantPromotionRewardForGame } from '@apps-in-toss/framework';
  *
- *     return cleanup;
- *   }, [navigation]);
+ * function GrantRewardButton() {
+ *   async function handlePress() {
+ *       const result = await grantPromotionRewardForGame({
+ *         params: {
+ *           promotionCode: 'GAME_EVENT_2024',
+ *           amount: 1000,
+ *         },
+ *       });
  *
- *   const showAd = useCallback(() => {
- *     if (GoogleAdMob.showAppsInTossAdMob.isSupported() !== true) {
- *       return;
- *     }
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
  *
- *     GoogleAdMob.showAppsInTossAdMob({
- *       options: {
- *         adGroupId: AD_GROUP_ID,
- *       },
- *       onEvent: (event) => {
- *         switch (event.type) {
- *           case 'requested':
- *             console.log('광고 보여주기 요청 완료');
- *             break;
+ *       if (result === 'ERROR') {
+ *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
+ *         return;
+ *       }
  *
- *           case 'clicked':
- *             console.log('광고 클릭');
- *             break;
+ *       if ('key' in result) {
+ *         console.log('포인트 지급 성공!', result.key);
+ *       } else if ('errorCode' in result) {
+ *         console.error('포인트 지급 실패:', result.errorCode, result.message);
+ *       }
+ *   }
  *
- *           case 'dismissed':
- *             console.log('광고 닫힘');
- *             navigation.navigate('/examples/google-admob-interstitial-ad-landing');
- *             break;
+ *   return <Button onPress={handlePress} title="포인트 지급하기" />;
+ * }
+ * ```
  *
- *           case 'failedToShow':
- *             console.log('광고 보여주기 실패');
- *             break;
+ * @example
+ * ```tsx
+ * // webview
+ * import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';
  *
- *           case 'impression':
- *             console.log('광고 노출');
- *             break;
+ * function GrantRewardButton() {
+ *   async function handleClick() {
+ *       const result = await grantPromotionRewardForGame({
+ *         params: {
+ *           promotionCode: 'GAME_EVENT_2024',
+ *           amount: 1000,
+ *         },
+ *       });
  *
- *           case 'userEarnedReward':
- *             console.log('광고 보상 획득 unitType:', event.data.unitType);
- *             console.log('광고 보상 획득 unitAmount:', event.data.unitAmount);
- *             break;
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
  *
- *           case 'show':
- *             console.log('광고 컨텐츠 보여졌음');
- *             break;
- *         }
- *       },
- *       onError: (error) => {
- *         console.error('광고 보여주기 실패', error);
- *       },
- *     });
- *   }, []);
+ *       if (result === 'ERROR') {
+ *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
+ *         return;
+ *       }
  *
- *   useFocusEffect(loadAd);
+ *       if ('key' in result) {
+ *         console.log('포인트 지급 성공!', result.key);
+ *       } else if ('errorCode' in result) {
+ *         console.error('포인트 지급 실패:', result.errorCode, result.message);
+ *       }
+ *   }
  *
  *   return (
- *     <View>
- *       <Text>
- *         {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
- *         {adLoadStatus === 'loaded' && '광고 로드 완료'}
- *         {adLoadStatus === 'failed' && '광고 로드 실패'}
- *       </Text>
- *
- *       <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
- *     </View>
+ *     <button onClick={handleClick}>포인트 지급하기</button>
  *   );
  * }
  * ```
  */
-declare function showAppsInTossAdMob(params: ShowAdMobParams): () => void;
-declare namespace showAppsInTossAdMob {
-    var isSupported: () => boolean;
-}
+declare function grantPromotionRewardForGame(params: {
+    params: {
+        promotionCode: string;
+        amount: number;
+    };
+}): Promise<GrantPromotionRewardForGameResult>;
 
+type Sku = {
+    /**
+     * @deprecated `productId`는 더 이상 사용하지 않아요. 대신 `sku`를 사용해요.
+     */
+    productId: string;
+    sku?: string;
+} | {
+    productId?: never;
+    sku: string;
+};
 /**
  * @public
- * @category 광고
- * @name showAppsInTossAdMob
- * @description 이 함수는 `loadAppsInTossAdMob` 로 광고가 잘 불러와졌는지 확인해요.
- * @param {string} params.adUnitId 광고 그룹 단위 ID예요.
- * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 `isAppsInTossAdMobLoaded` 를 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
+ * @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`로 반환돼요.
  */
-declare function isAppsInTossAdMobLoaded(params: IsAdMobLoadedOptions): Promise<boolean>;
-declare namespace isAppsInTossAdMobLoaded {
-    var isSupported: typeof isAppsInTossAdMobLoadedSupported;
+interface IapCreateOneTimePurchaseOrderResult {
+    orderId: string;
+    displayName: string;
+    displayAmount: string;
+    amount: number;
+    currency: string;
+    fraction: number;
+    miniAppIconUrl: string | null;
 }
-declare function isAppsInTossAdMobLoadedSupported(): boolean;
-
-/**
- * @public
- * @category 토스페이
- * @name CheckoutPaymentOptions
- * @description 토스페이 결제창을 띄울 때 필요한 옵션이에요.
- * @property {string} payToken 결제 토큰이에요.
- */
-interface CheckoutPaymentOptions {
-    /**
-     * 결제 토큰이에요.
-     */
-    payToken: string;
+interface OneTimePurchaseSuccessEvent {
+    type: 'success';
+    data: IapCreateOneTimePurchaseOrderResult;
+}
+interface PurchasedEvent {
+    type: 'purchased';
+    data: {
+        orderId: string;
+    };
 }
 /**
  * @public
- * @category 토스페이
- * @name CheckoutPaymentResult
- * @description 토스페이 결제창에서 사용자가 인증에 성공했는지 여부예요.
- * @property {boolean} success 인증이 성공했는지 여부예요.
- * @property {string} [reason] 인증이 실패했을 경우의 이유예요.
+ * @category 인앱결제
+ * @name IapCreateOneTimePurchaseOrderOptions
+ * @property {Sku} options - 결제할 상품의 정보예요.
+ * @property {string} options.sku - 주문할 상품의 고유 ID예요.
+ * @property {(params: { orderId: string }) => boolean | Promise<boolean>} processProductGrant - 주문이 만들어진 뒤 실제로 상품을 지급할 때 호출해요. `orderId`를 받아서 지급 성공 여부를 `true` 또는 `Promise<true>`로 반환해요. 지급에 실패하면 `false`를 반환해요.
+ * @property {(event: SuccessEvent) => void | Promise<void>} onEvent - 결제가 성공했을 때 호출해요. `event.type`이 `'success'`이고, `event.data`에 `IapCreateOneTimePurchaseOrderResult`가 들어 있어요.
+ * @property {(error: unknown) => void | Promise<void>} onError - 결제 과정에서 에러가 발생했을 때 호출해요. 에러 객체를 받아서 로깅하거나 복구 절차를 실행할 수 있어요.
  */
-interface CheckoutPaymentResult {
-    /**
-     * 인증이 성공했는지 여부예요.
-     */
-    success: boolean;
-    /**
-     * 인증이 실패했을 경우의 이유예요.
-     */
-    reason?: string;
+interface IapCreateOneTimePurchaseOrderOptions {
+    options: Sku & {
+        processProductGrant: (params: {
+            orderId: string;
+        }) => boolean | Promise<boolean>;
+    };
+    onEvent: (event: OneTimePurchaseSuccessEvent) => void | Promise<void>;
+    onError: (error: unknown) => void | Promise<void>;
+}
+interface IapRequestOneTimePurchaseOptions {
+    options: Sku;
+    onEvent: (event: PurchasedEvent | OneTimePurchaseSuccessEvent) => void | Promise<void>;
+    onError: (error: unknown) => void | Promise<void>;
 }
+declare function iapCreateOneTimePurchaseOrder(params: Sku): Promise<IapCreateOneTimePurchaseOrderResult>;
+declare function processProductGrant(params: {
+    orderId: string;
+    isProductGranted: boolean;
+}): Promise<void>;
+declare function requestOneTimePurchase(params: IapRequestOneTimePurchaseOptions): () => void;
 /**
  * @public
- * @category 토스페이
- * @name checkoutPayment
- * @description 토스페이 결제창을 띄우고, 사용자 인증을 수행해요. 인증이 완료되면 성공 여부를 반환해요.
- *
- * 이 함수는 결제창을 통해 사용자 인증만 해요. 실제 결제 처리는 인증 성공 후 서버에서 별도로 해야 해요.
+ * @category 인앱결제
+ * @name createOneTimePurchaseOrder
+ * @description
+ * 특정 인앱결제 주문서 페이지로 이동해요. 사용자가 상품 구매 버튼을 누르는 상황 등에 사용할 수 있어요. 사용자의 결제는 이동한 페이지에서 진행돼요. 만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.
+ * @param {IapCreateOneTimePurchaseOrderOptions} params - 인앱결제를 생성할 때 필요한 정보예요.
+ * @returns {() => void} 앱브릿지 cleanup 함수를 반환해요. 인앱결제 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.
  *
- * @param {CheckoutPaymentOptions} options 결제창을 띄울 때 필요한 옵션이에요.
- * @returns {Promise<CheckoutPaymentResult>} 인증 성공 여부를 포함한 결과를 반환해요.
+ * @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"} - 사용자가 결제를 완료하지 않고 주문서 페이지를 이탈했을 때 발생해요.
+ * @throw {code: "PRODUCT_NOT_GRANTED_BY_PARTNER"} - 파트너사의 상품 지급이 실패했을 때 발생해요.
  *
  * @example
+ * ### 특정 인앱결제 주문서 페이지로 이동하기
  *
- * ### 토스페이 결제창 띄우고 인증 처리하기
+ * ```tsx
+ * import { IAP } from "@apps-in-toss/web-framework";
+ * import { Button } from "@toss/tds-react-native";
+ * import { useCallback } from "react";
+ *
+ * interface Props {
+ *   sku: string;
+ * }
  *
- * ```tsx
- * import { TossPay } from '@apps-in-toss/framework';
+ * function IapCreateOneTimePurchaseOrderButton({ sku }: Props) {
+ *   const handleClick = useCallback(async () => {
  *
- * async function handlePayment() {
- *   try {
- *     // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해주세요.
- *     const { payToken } = await fetch('/my-api/payment/create').then(res => res.json());
+ *     const cleanup = await IAP.createOneTimePurchaseOrder({
+ *       options: {
+ *        sku,
+ *        processProductGrant: ({ orderId }) => {
+ *         // 상품 지급 로직 작성
+ *          return true; // 상품 지급 여부
+ *        }
+ *        },
+ *       onEvent: (event) => {
+ *         console.log(event);
+ *       },
+ *       onError: (error) => {
+ *         console.error(error);
+ *       },
+ *     });
  *
- *     const { success, reason } = await TossPay.checkoutPayment({ payToken });
+ *     return cleanup;
+ *   }, []);
  *
- *     if (success) {
- *       // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해주세요.
- *       await fetch('/my-api/payment/execute', {
- *         method: 'POST',
- *         body: JSON.stringify({ payToken }),
- *         headers: { 'Content-Type': 'application/json' },
- *       });
- *     } else {
- *       console.log('인증 실패:', reason);
- *     }
- *   } catch (error) {
- *     console.error('결제 인증 중 오류가 발생했어요:', error);
- *   }
+ *   return <Button onClick={handleClick}>구매하기</Button>;
  * }
  * ```
  */
-declare function checkoutPayment(options: CheckoutPaymentOptions): Promise<CheckoutPaymentResult>;
-
-interface AppsInTossSignTossCertParams {
-    txId: string;
-    skipConfirmDoc?: boolean;
+declare function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): () => void;
+interface BasicProductListItem {
+    sku: string;
+    displayAmount: string;
+    displayName: string;
+    iconUrl: string;
+    description: string;
 }
+type Offer = {
+    type: 'FREE_TRIAL';
+    offerId: string;
+    period: string;
+} | {
+    type: 'NEW_SUBSCRIPTION';
+    offerId: string;
+    period: string;
+    displayAmount: string;
+} | {
+    type: 'RETURNING';
+    offerId: string;
+    period: string;
+    displayAmount: string;
+};
 /**
  * @public
- * @category 토스인증
- * @name appsInTossSignTossCert
- * @description 토스 인증서를 사용해 서명하는 기능을 제공해요. 이 함수를 사용하면 앱인토스에서 제공하는 인증서를 활용해 서명을 할 수 있어요.
- *
- * @param {AppsInTossSignTossCertParams} params - 서명에 필요한 파라미터를 포함하는 객체예요.
- * @param {string} params.txId - 토스인증서를 사용한 본인확인이나 간편인증, 전자서명에서 사용하는 Transaction Id예요.
- * @param {boolean} params.skipConfirmDoc - (선택) 토스 원터치 인증방식을 사용하기 위한 옵션이예요. true 설정 시 최소 버전: Android 5.236.0, iOS 5.236.0 (default: false)
- *
- * @example
- * ```tsx
- * import { appsInTossSignTossCert } from '@apps-in-toss/framework';
- *
- *  // 서명에 필요한 파라미터를 정의해요.
- *  const params = {
- *    txId: "f2e1a6df..."
- *  };
- *
- * appsInTossSignTossCert(params)
- *   .then(() => {
- *     console.log('서명 작업이 성공적으로 완료되었어요.');
- *   })
- *   .catch((error) => {
- *     console.error('서명 작업 중 에러가 발생했어요:', error);
- *   });
- * ```
+ * @category 인앱결제
+ * @name ConsumableProductListItem
+ * @description 소모품 상품 정보를 담은 객체예요.
+ * @property {string} sku - 상품의 고유 ID예요.
+ * @property {string} type - 상품의 유형이에요. `CONSUMABLE`을 나타내요.
+ * @property {string} displayName - 화면에 표시할 상품 이름이에요. 상품 이름은 앱인토스 콘솔에서 설정한 값이에요.
+ * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
+ * @property {string} iconUrl - 상품 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요.
+ * @property {string} description - 상품에 대한 설명이에요. 설명은 앱인토스 콘솔에서 설정한 값이에요.
  */
-declare function appsInTossSignTossCert(params: AppsInTossSignTossCertParams): Promise<void>;
-
+interface ConsumableProductListItem extends BasicProductListItem {
+    type: 'CONSUMABLE';
+}
 /**
- * @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'`일 때만 있어요.
+ * @public
+ * @category 인앱결제
+ * @name NonConsumableProductListItem
+ * @description 비소모품 상품 정보를 담은 객체예요.
+ * @property {string} sku - 상품의 고유 ID예요.
+ * @property {string} type - 상품의 유형이에요. `NON_CONSUMABLE`을 나타내요.
+ * @property {string} displayName - 화면에 표시할 상품 이름이에요. 상품 이름은 앱인토스 콘솔에서 설정한 값이에요.
+ * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
+ * @property {string} iconUrl - 상품 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요.
+ * @property {string} description - 상품에 대한 설명이에요. 설명은 앱인토스 콘솔에서 설정한 값이에요.
  */
-type GameCenterGameProfileResponse = {
-    statusCode: 'PROFILE_NOT_FOUND';
-} | {
-    statusCode: 'SUCCESS';
-    nickname: string;
-    profileImageUri: string;
-};
+interface NonConsumableProductListItem extends BasicProductListItem {
+    type: 'NON_CONSUMABLE';
+}
 /**
- * @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>
- *   );
- * }
- * ```
+ * @public
+ * @category 인앱결제
+ * @name SubscriptionProductListItem
+ * @description 자동 갱신 구독 상품 정보를 담은 객체예요.
+ * @property {string} sku - 상품의 고유 ID예요.
+ * @property {string} type - 상품의 유형이에요. `SUBSCRIPTION`을 나타내요.
+ * @property {string} displayName - 화면에 표시할 상품 이름이에요. 상품 이름은 앱인토스 콘솔에서 설정한 값이에요.
+ * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
+ * @property {string} iconUrl - 상품 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요.
+ * @property {string} description - 상품에 대한 설명이에요. 설명은 앱인토스 콘솔에서 설정한 값이에요.
+ * @property {string} renewalCycle - 구독 갱신 주기이에요. `WEEKLY`, `MONTHLY`, `YEARLY` 중 하나를 나타내요.
+ * @property {Offer[]} offers - 구독 혜택 옵션 목록이에요. 각 옵션은 하나의 구독 혜택을 나타내요.
+ * @property {string} offers[].type - 구독 혜택 옵션 유형이에요. `FREE_TRIAL`, `NEW_SUBSCRIPTION`, `RETURNING` 중 하나를 나타내요.
+ * @property {string} offers[].offerId - 구독 혜택 옵션의 고유 ID예요.
+ * @property {string} offers[].period - 구독 혜택 옵션의 적용 기간이에요.
+ * @property {string} offers[].displayAmount - 통화 단위가 포함된 구독 혜택 옵션의 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
  */
-declare function getGameCenterGameProfile(): Promise<GameCenterGameProfileResponse | undefined>;
-
-interface GetUserKeyForGameSuccessResponse {
-    hash: string;
-    type: 'HASH';
-}
-interface GetUserKeyForGameErrorResponse {
-    type: 'NOT_AVAILABLE';
+interface SubscriptionProductListItem extends BasicProductListItem {
+    type: 'SUBSCRIPTION';
+    renewalCycle: 'WEEKLY' | 'MONTHLY' | 'YEARLY';
+    offers?: Offer[];
 }
-type GetUserKeyForGameResponse = GetUserKeyForGameSuccessResponse | GetUserKeyForGameErrorResponse;
 /**
  * @public
- * @category 게임
- * @name getUserKeyForGame
- * @description
- * 게임 카테고리 미니앱에서 사용자의 고유 키를 가져와요. 이 키를 사용해서 사용자를 식별하고 게임 데이터를 관리할 수 있어요.
- * 게임 카테고리가 아닌 미니앱에서 호출하면 `'INVALID_CATEGORY'`를 반환해요.
- * @returns {Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>}
- * 사용자 키 조회 결과를 반환해요.
- * - `GetUserKeyForGameSuccessResponse`: 사용자 키 조회에 성공했어요. `{ type: 'HASH', hash: string }` 형태로 반환돼요.
- * - `'INVALID_CATEGORY'`: 게임 카테고리가 아닌 미니앱에서 호출했어요.
- * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
- * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
+ * @category 인앱결제
+ * @name IapProductListItem
+ * @description 인앱결제로 구매할 수 있는 상품 하나의 정보를 담은 객체예요. 상품 목록을 화면에 표시할 때 사용해요.
+ */
+type IapProductListItem = ConsumableProductListItem | NonConsumableProductListItem | SubscriptionProductListItem;
+/**
+ * @public
+ * @category 인앱결제
+ * @name getProductItemList
+ * @description 인앱결제로 구매할 수 있는 상품 목록을 가져와요. 상품 목록 화면에 진입할 때 호출해요.
+ * @returns {Promise<{ products: IapProductListItem[] } | undefined>} 상품 목록을 포함한 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.219.0, iOS 5.219.0)보다 낮으면 `undefined`를 반환해요.
  *
  * @example
- * ```tsx
- * // react-native
- * import { Button } from 'react-native';
- * import { getUserKeyForGame } from '@apps-in-toss/framework';
- *
- * function GameUserKeyButton() {
- *   async function handlePress() {
- *       const result = await getUserKeyForGame();
- *
- *       if (!result) {
- *         console.warn('지원하지 않는 앱 버전이에요.');
- *         return;
- *       }
- *
- *       if (result === 'INVALID_CATEGORY') {
- *         console.error('게임 카테고리가 아닌 미니앱이에요.');
- *         return;
- *       }
- *
- *       if (result === 'ERROR') {
- *         console.error('사용자 키 조회 중 오류가 발생했어요.');
- *         return;
- *       }
- *
- *       if (result.type === 'HASH') {
- *         console.log('사용자 키:', result.hash);
- *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
- *       }
- *   }
- *
- *   return (
- *     <Button onPress={handlePress} title="유저 키 가져오기" />
- *   );
- * }
- * ```
+ * ### 구매 가능한 인앱결제 상품목록 가져오기
  *
- * @example
  * ```tsx
- * // webview
- * import { getUserKeyForGame } from '@apps-in-toss/web-framework';
+ * import { IAP, IapProductListItem } from "@apps-in-toss/framework";
+ * import { Button, List, ListRow } from "@toss/tds-react-native";
+ * import { useEffect, useState } from "react";
  *
- * function GameUserKeyButton() {
- *   async function handleClick() {
- *       const result = await getUserKeyForGame();
+ * function IapProductList() {
+ *   const [products, setProducts] = useState<IapProductListItem[]>([]);
  *
- *       if (!result) {
- *         console.warn('지원하지 않는 앱 버전이에요.');
- *         return;
- *       }
+ *   async function buyIapProduct(productId: string) {
+ *     try {
+ *       await IAP.createOneTimePurchaseOrder({
+ *         productId,
+ *       });
  *
- *       if (result === 'INVALID_CATEGORY') {
- *         console.error('게임 카테고리가 아닌 미니앱이에요.');
- *         return;
- *       }
+ *       console.error("인앱결제에 성공했어요");
+ *     } catch (error) {
+ *       console.error("인앱결제에 실패했어요:", error);
+ *     }
+ *   }
  *
- *       if (result === 'ERROR') {
- *         console.error('사용자 키 조회 중 오류가 발생했어요.');
- *         return;
+ *   useEffect(() => {
+ *     async function fetchProducts() {
+ *       try {
+ *         const response = await IAP.getProductItemList();
+ *         setProducts(response?.products ?? []);
+ *       } catch (error) {
+ *         console.error("상품 목록을 가져오는 데 실패했어요:", error);
  *       }
+ *     }
  *
- *       if (result.type === 'HASH') {
- *         console.log('사용자 키:', result.hash);
- *         // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
- *       }
- *   }
+ *     fetchProducts();
+ *   }, []);
  *
  *   return (
- *     <button onClick={handleClick}>유저 키 가져오기</button>
+ *     <List>
+ *       {products.map((product) => (
+ *         <ListRow
+ *           key={product.sku}
+ *           left={
+ *             <ListRow.Image type="square" source={{ uri: product.iconUrl }} />
+ *           }
+ *           right={
+ *             <Button size="medium" onPress={() => buyIapProduct(product.sku)}>
+ *               구매하기
+ *             </Button>
+ *           }
+ *           contents={
+ *             <ListRow.Texts
+ *               type="3RowTypeA"
+ *               top={product.displayName}
+ *               middle={product.description}
+ *               bottom={product.displayAmount}
+ *             />
+ *           }
+ *         />
+ *       ))}
+ *     </List>
  *   );
  * }
  * ```
  */
-declare function getUserKeyForGame(): Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>;
-
-interface GrantPromotionRewardForGameSuccessResponse {
-    key: string;
-}
-interface GrantPromotionRewardForGameErrorResponse {
-    code: string;
-    [key: string]: any;
-}
-interface GrantPromotionRewardForGameErrorResult {
-    errorCode: string;
-    message: string;
-}
-type GrantPromotionRewardForGameResponse = GrantPromotionRewardForGameSuccessResponse | GrantPromotionRewardForGameErrorResponse;
-type GrantPromotionRewardForGameResult = GrantPromotionRewardForGameResponse | GrantPromotionRewardForGameErrorResult | 'ERROR' | undefined;
+declare function getProductItemList(): Promise<{
+    products: any[];
+} | undefined>;
 /**
  * @public
- * @category 게임
- * @name grantPromotionRewardForGame
- * @description
- * 이 함수를 사용하면 게임 카테고리 미니앱에서 프로모션 코드를 사용해서 유저에게 리워드를 지급할 수 있어요.
- * 게임 카테고리가 아닌 미니앱에서 호출할 수 없어요.
- * @param {{ params: { promotionCode: string; amount: number } }} params - 포인트를 지급하기 위해 필요한 정보예요.
- * @param {string} params.promotionCode - 프로모션 코드예요.
- * @param {number} params.amount - 지급할 포인트 금액이에요.
- * @returns {Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>}
- * 포인트 지급 결과를 반환해요.
- * - `{ key: string }`: 포인트 지급에 성공했어요. key는 리워드 키를 의미해요.
- * - `{ errorCode: string, message: string }`: 포인트 지급에 실패했어요. 에러 코드는 다음과 같아요.
- *   - `"40000"`: 게임이 아닌 미니앱에서 호출했을 때
- *   - `"4100"`: 프로모션 정보를 찾을 수 없을 때
- *   - `"4104"`: 프로모션이 중지되었을 때
- *   - `"4105"`: 프로모션이 종료되었을 때
- *   - `"4108"`: 프로모션이 승인되지 않았을 때
- *   - `"4109"`: 프로모션이 실행중이 아닐 때
- *   - `"4110"`: 리워드를 지급/회수할 수 없을 때
- *   - `"4112"`: 프로모션 머니가 부족할 때
- *   - `"4113"`: 이미 지급/회수된 내역일 때
- *   - `"4114"`: 프로모션에 설정된 1회 지급 금액을 초과할 때
- * - `'ERROR'`: 알 수 없는 오류가 발생했어요.
- * - `undefined`: 앱 버전이 최소 지원 버전보다 낮아요.
- * @example
- * ```tsx
- * // react-native
- * import { Button } from 'react-native';
- * import { grantPromotionRewardForGame } from '@apps-in-toss/framework';
- *
- * function GrantRewardButton() {
- *   async function handlePress() {
- *       const result = await grantPromotionRewardForGame({
- *         params: {
- *           promotionCode: 'GAME_EVENT_2024',
- *           amount: 1000,
- *         },
- *       });
- *
- *       if (!result) {
- *         console.warn('지원하지 않는 앱 버전이에요.');
- *         return;
- *       }
+ * @category 인앱결제
+ * @name getPendingOrders
+ * @description 대기 중인 주문 목록을 가져와요. 이 함수를 사용하면 결제가 아직 완료되지 않은 주문 정보를 확인할 수 있어요.
+ * @returns {Promise<{ orders: { orderId: string; sku: string; paymentCompletedDate: string; }[]}>} 대기 중인 주문의 배열을 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.234.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.
  *
- *       if (result === 'ERROR') {
- *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
- *         return;
- *       }
+ * @example
+ * ### 대기 중인 주문 목록 가져오기
+ * ```typescript
+ * import { IAP } from '@apps-in-toss/framework';
  *
- *       if ('key' in result) {
- *         console.log('포인트 지급 성공!', result.key);
- *       } else if ('errorCode' in result) {
- *         console.error('포인트 지급 실패:', result.errorCode, result.message);
- *       }
+ * async function fetchOrders() {
+ *   try {
+ *     const pendingOrders = await IAP.getPendingOrders();
+ *     return pendingOrders;
+ *   } catch (error) {
+ *     console.error(error);
  *   }
- *
- *   return <Button onPress={handlePress} title="포인트 지급하기" />;
  * }
  * ```
+ */
+declare function getPendingOrders(): Promise<{
+    orders: Array<{
+        orderId: string;
+        sku: string;
+    }>;
+} | undefined>;
+/**
+ * @public
+ * @category 인앱결제
+ * @name CompletedOrRefundedOrdersResult
+ * @description 인앱결제로 구매하거나 환불한 주문 목록을 나타내는 객체예요. 페이지네이션 정보를 포함해요.
+ * @property {boolean} hasNext 다음 페이지가 있는지 여부예요. `true`면 더 많은 주문이 남아 있어요.
+ * @property {string | null} [nextKey] 다음 주문 목록을 조회할 때 사용할 키예요. 마지막 페이지라면 `null`이거나 생략될 수 있어요.
+ * @property {Array} orders 주문 정보를 담은 배열이에요. 각 요소는 하나의 주문을 나타내요.
+ * @property {string} orders[].orderId 주문의 고유 ID예요.
+ * @property {string} orders[].sku 주문 상품의 고유 ID예요.
+ * @property {'COMPLETED' | 'REFUNDED'} orders[].status 주문의 상태예요. 'COMPLETED'는 주문이 완료된 상태, 'REFUNDED'는 환불된 상태를 의미해요.
+ * @property {string} orders[].date 주문의 날짜 정보예요. ISO 8601 형식(YYYY-MM-DDTHH:mm:ss)을 사용해요. 예를 들어 "2025-09-22T00:00:00" 형식으로 제공돼요. 주문 상태가 `COMPLETED`라면 주문한 날짜를, `REFUNDED`라면 환불한 날짜를 나타내요.
+ */
+interface CompletedOrRefundedOrdersResult {
+    hasNext: boolean;
+    nextKey?: string | null;
+    orders: {
+        orderId: string;
+        sku: string;
+        status: 'COMPLETED' | 'REFUNDED';
+        date: string;
+    }[];
+}
+/**
+ * @public
+ * @category 인앱결제
+ * @name getCompletedOrRefundedOrders
+ * @description 인앱결제로 구매하거나 환불한 주문 목록을 가져와요.
+ * @returns {Promise<CompletedOrRefundedOrdersResult>} 페이지네이션을 포함한 주문 목록 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.
  *
  * @example
- * ```tsx
- * // webview
- * import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';
- *
- * function GrantRewardButton() {
- *   async function handleClick() {
- *       const result = await grantPromotionRewardForGame({
- *         params: {
- *           promotionCode: 'GAME_EVENT_2024',
- *           amount: 1000,
- *         },
- *       });
- *
- *       if (!result) {
- *         console.warn('지원하지 않는 앱 버전이에요.');
- *         return;
- *       }
- *
- *       if (result === 'ERROR') {
- *         console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.');
- *         return;
- *       }
+ * ```typescript
+ * import { IAP } from "@apps-in-toss/framework";
  *
- *       if ('key' in result) {
- *         console.log('포인트 지급 성공!', result.key);
- *       } else if ('errorCode' in result) {
- *         console.error('포인트 지급 실패:', result.errorCode, result.message);
- *       }
+ * async function fetchOrders() {
+ *   try {
+ *     const response =  await IAP.getCompletedOrRefundedOrders();
+ *     return response;
+ *   } catch (error) {
+ *     console.error(error);
  *   }
- *
- *   return (
- *     <button onClick={handleClick}>포인트 지급하기</button>
- *   );
  * }
  * ```
  */
-declare function grantPromotionRewardForGame({ params, }: {
-    params: {
-        promotionCode: string;
-        amount: number;
-    };
-}): Promise<GrantPromotionRewardForGameResult>;
-
-type Sku = {
-    /**
-     * @deprecated `productId`는 더 이상 사용하지 않아요. 대신 `sku`를 사용해요.
-     */
-    productId: string;
-    sku?: string;
-} | {
-    productId?: never;
-    sku: string;
-};
+declare function getCompletedOrRefundedOrders(params?: {
+    key?: string | null;
+}): Promise<any>;
 /**
- * @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`로 반환돼요.
+ * @public
+ * @category 인앱결제
+ * @name completeProductGrant
+ * @description 상품 지급 처리를 완료했다는 메시지를 앱에 전달해요. 이 함수를 사용하면 결제가 완료된 주문의 상품 지급이 정상적으로 완료되었음을 알릴 수 있어요.
+ * @param {{ params: { orderId: string } }} params 결제가 완료된 주문 정보를 담은 객체예요.
+ * @param {string} params.orderId 주문의 고유 ID예요. 상품 지급을 완료할 주문을 지정할 때 사용해요.
+ * @returns {Promise<boolean>} 상품 지급이 완료됐는지 여부를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.233.0, iOS 5.233.0)보다 낮으면 `undefined`를 반환해요.
+ *
+ * @example
+ * ### 결제를 성공한 뒤 상품을 지급하는 예시
+ * ```typescript
+ * import { IAP } from '@apps-in-toss/framework';
+ *
+ * async function handleGrantProduct(orderId: string) {
+ *   try {
+ *     await IAP.completeProductGrant({ params: { orderId } });
+ *   } catch (error) {
+ *     console.error(error);
+ *   }
+ * }
+ * ```
  */
-interface IapCreateOneTimePurchaseOrderResult {
-    orderId: string;
-    displayName: string;
-    displayAmount: string;
-    amount: number;
-    currency: string;
-    fraction: number;
-    miniAppIconUrl: string | null;
-}
-interface OneTimePurchaseSuccessEvent {
-    type: 'success';
-    data: IapCreateOneTimePurchaseOrderResult;
-}
-interface PurchasedEvent {
-    type: 'purchased';
-    data: {
+declare function completeProductGrant(params: {
+    params: {
         orderId: string;
     };
-}
+}): Promise<boolean | undefined>;
 /**
  * @public
  * @category 인앱결제
- * @name IapCreateOneTimePurchaseOrderOptions
- * @property {Sku} options - 결제할 상품의 정보예요.
- * @property {string} options.sku - 주문할 상품의 고유 ID예요.
- * @property {(params: { orderId: string }) => boolean | Promise<boolean>} processProductGrant - 주문이 만들어진 뒤 실제로 상품을 지급할 때 호출해요. `orderId`를 받아서 지급 성공 여부를 `true` 또는 `Promise<true>`로 반환해요. 지급에 실패하면 `false`를 반환해요.
- * @property {(event: SuccessEvent) => void | Promise<void>} onEvent - 결제가 성공했을 때 호출해요. `event.type`이 `'success'`이고, `event.data`에 `IapCreateOneTimePurchaseOrderResult`가 들어 있어요.
- * @property {(error: unknown) => void | Promise<void>} onError - 결제 과정에서 에러가 발생했을 때 호출해요. 에러 객체를 받아서 로깅하거나 복구 절차를 실행할 수 있어요.
+ * @name CreateSubscriptionPurchaseOrderOptions
+ * @description 구독 인앱결제를 생성할 때 필요한 옵션이에요.
+ * @property {object} options - 결제할 구독 상품의 정보예요.
+ * @property {string} options.sku - 주문할 구독 상품의 고유 ID예요.
+ * @property {string | null} [options.offerId] - 적용할 offer ID예요. 없으면 기본 가격이 적용돼요.
+ * @property {(params: { orderId: string, subscriptionId?: string }) => boolean | Promise<boolean>} options.processProductGrant - 주문이 만들어진 뒤 실제로 상품을 지급할 때 호출해요.
+ * @property {(event: SubscriptionSuccessEvent) => void | Promise<void>} onEvent - 결제가 성공했을 때 호출해요.
+ * @property {(error: unknown) => void | Promise<void>} onError - 결제 과정에서 에러가 발생했을 때 호출해요.
  */
-interface IapCreateOneTimePurchaseOrderOptions {
-    options: Sku & {
+interface CreateSubscriptionPurchaseOrderOptions {
+    options: {
+        sku: string;
+        offerId?: string | null;
         processProductGrant: (params: {
             orderId: string;
+            subscriptionId?: string;
         }) => boolean | Promise<boolean>;
     };
-    onEvent: (event: OneTimePurchaseSuccessEvent) => void | Promise<void>;
+    onEvent: (event: SubscriptionSuccessEvent) => void | Promise<void>;
     onError: (error: unknown) => void | Promise<void>;
 }
-interface IapRequestOneTimePurchaseOptions {
-    options: Sku;
-    onEvent: (event: PurchasedEvent | OneTimePurchaseSuccessEvent) => void | Promise<void>;
-    onError: (error: unknown) => void | Promise<void>;
+/**
+ * @public
+ * @category 인앱결제
+ * @name IapCreateSubscriptionPurchaseOrderResult
+ * @description 구독 인앱결제가 완료되면 결제 세부 정보와 상품 정보를 담아 반환해요. `IapCreateOneTimePurchaseOrderResult`와 동일한 구조예요.
+ */
+type IapCreateSubscriptionPurchaseOrderResult = IapCreateOneTimePurchaseOrderResult;
+interface SubscriptionSuccessEvent {
+    type: 'success';
+    data: IapCreateSubscriptionPurchaseOrderResult;
 }
-declare function iapCreateOneTimePurchaseOrder(params: Sku): Promise<IapCreateOneTimePurchaseOrderResult>;
-declare function processProductGrant(params: {
-    orderId: string;
-    isProductGranted: boolean;
-}): Promise<void>;
-declare function requestOneTimePurchase(params: IapRequestOneTimePurchaseOptions): () => void;
 /**
  * @public
  * @category 인앱결제
- * @name createOneTimePurchaseOrder
+ * @name createSubscriptionPurchaseOrder
  * @description
- * 특정 인앱결제 주문서 페이지로 이동해요. 사용자가 상품 구매 버튼을 누르는 상황 등에 사용할 수 있어요. 사용자의 결제는 이동한 페이지에서 진행돼요. 만약 결제 중에 에러가 발생하면 에러 유형에 따라 에러 페이지로 이동해요.
- * @param {IapCreateOneTimePurchaseOrderOptions} params - 인앱결제를 생성할 때 필요한 정보예요.
+ * 구독 인앱결제 주문서 페이지로 이동해요. 사용자가 구독 상품 구매 버튼을 누르는 상황 등에 사용할 수 있어요.
+ * @param {CreateSubscriptionPurchaseOrderOptions} params - 구독 인앱결제를 생성할 때 필요한 정보예요.
  * @returns {() => void} 앱브릿지 cleanup 함수를 반환해요. 인앱결제 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.
  *
- * @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"} - 사용자가 결제를 완료하지 않고 주문서 페이지를 이탈했을 때 발생해요.
- * @throw {code: "PRODUCT_NOT_GRANTED_BY_PARTNER"} - 파트너사의 상품 지급이 실패했을 때 발생해요.
- *
  * @example
- * ### 특정 인앱결제 주문서 페이지로 이동하기
+ * ### 구독 인앱결제 주문서 페이지로 이동하기
  *
  * ```tsx
  * import { IAP } from "@apps-in-toss/web-framework";
@@ -1047,19 +829,20 @@ declare function requestOneTimePurchase(params: IapRequestOneTimePurchaseOptions
  *
  * interface Props {
  *   sku: string;
+ *   offerId?: string;
  * }
  *
- * function IapCreateOneTimePurchaseOrderButton({ sku }: Props) {
+ * function SubscriptionPurchaseButton({ sku, offerId }: Props) {
  *   const handleClick = useCallback(async () => {
- *
- *     const cleanup = await IAP.createOneTimePurchaseOrder({
+ *     const cleanup = IAP.createSubscriptionPurchaseOrder({
  *       options: {
- *        sku,
- *        processProductGrant: ({ orderId }) => {
- *         // 상품 지급 로직 작성
- *          return true; // 상품 지급 여부
- *        }
- *        },
+ *         sku,
+ *         offerId,
+ *         processProductGrant: ({ orderId, subscriptionId }) => {
+ *           // 상품 지급 로직 작성
+ *           return true; // 상품 지급 여부
+ *         },
+ *       },
  *       onEvent: (event) => {
  *         console.log(event);
  *       },
@@ -1069,606 +852,854 @@ declare function requestOneTimePurchase(params: IapRequestOneTimePurchaseOptions
  *     });
  *
  *     return cleanup;
- *   }, []);
+ *   }, [sku, offerId]);
  *
- *   return <Button onClick={handleClick}>구매하기</Button>;
+ *   return <Button onClick={handleClick}>구독하기</Button>;
  * }
  * ```
  */
-declare function createOneTimePurchaseOrder(params: IapCreateOneTimePurchaseOrderOptions): () => void;
-interface BasicProductListItem {
-    sku: string;
-    displayAmount: string;
-    displayName: string;
-    iconUrl: string;
-    description: string;
-}
-type Offer = {
-    type: 'FREE_TRIAL';
-    offerId: string;
-    period: string;
-} | {
-    type: 'NEW_SUBSCRIPTION';
-    offerId: string;
-    period: string;
-    displayAmount: string;
-} | {
-    type: 'RETURNING';
-    offerId: string;
-    period: string;
-    displayAmount: string;
+declare function createSubscriptionPurchaseOrder(params: CreateSubscriptionPurchaseOrderOptions): () => void;
+/**
+ * @public
+ * @category 인앱결제
+ * @name IAP
+ * @description 인앱결제 관련 기능을 모은 객체예요. 단건 인앱결제 주문서 이동과 상품 목록 조회 기능을 제공해요.
+ * @property {typeof createOneTimePurchaseOrder} [createOneTimePurchaseOrder] 특정 인앱결제 주문서 페이지로 이동해요. 자세한 내용은 [createOneTimePurchaseOrder](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/createOneTimePurchaseOrder.html) 문서를 참고하세요.
+ * @property {typeof getProductItemList} [getProductItemList] 인앱결제로 구매할 수 있는 상품 목록을 가져와요. 자세한 내용은 [getProductItemList](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/getProductItemList.html) 문서를 참고하세요.
+ * @property {typeof getPendingOrders} [getPendingOrders] 대기 중인 주문 목록을 가져와요. 자세한 내용은 [getPendingOrders](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/getPendingOrders.htm) 문서를 참고하세요.
+ * @property {typeof getCompletedOrRefundedOrders} [getCompletedOrRefundedOrders] 인앱결제로 구매하거나 환불한 주문 목록을 가져와요. 자세한 내용은 [getCompletedOrRefundedOrders](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/getCompletedOrRefundedOrders.html) 문서를 참고하세요.
+ * @property {typeof completeProductGrant} [completeProductGrant] 상품 지급 처리를 완료했다는 메시지를 앱에 전달해요. 자세한 내용은 [completeProductGrant](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/completeProductGrant.html) 문서를 참고하세요.
+ */
+declare const IAP: {
+    createOneTimePurchaseOrder: typeof createOneTimePurchaseOrder;
+    createSubscriptionPurchaseOrder: typeof createSubscriptionPurchaseOrder;
+    getProductItemList: typeof getProductItemList;
+    getPendingOrders: typeof getPendingOrders;
+    getCompletedOrRefundedOrders: typeof getCompletedOrRefundedOrders;
+    completeProductGrant: typeof completeProductGrant;
 };
+
+interface SaveBase64DataParams {
+    data: string;
+    fileName: string;
+    mimeType: string;
+}
+/**
+ * @public
+ * @category 데이터
+ * @name saveBase64Data
+ * @description 문자열로 인코딩된 Base64 데이터를 지정한 파일 이름과 MIME 타입으로 사용자 기기에 저장해요. 이미지, 텍스트, PDF 등 다양한 형식의 데이터를 저장할 수 있어요.
+ * @param {SaveBase64DataParams} params - 저장할 데이터와 파일 정보를 담은 객체예요.
+ * @param {string} params.data - Base64 형식으로 인코딩된 데이터 문자열이에요.
+ * @param {string} params.fileName - 저장할 파일 이름이에요. 확장자도 같이 붙여줘야해요. 예를 들어, 'example.png'로 저장할 수 있어요.
+ * @param {string} params.mimeType - 저장할 파일의 MIME 타입이에요. 예를 들어 'image/png' 로 지정하면 이미지, 'application/pdf'는 PDF 파일이에요. 자세한 내용은 [MIME 문서](https://developer.mozilla.org/ko/docs/Web/HTTP/Guides/MIME_types)를 참고해주세요.
+ *
+ * @example
+ * ### Base64 이미지 데이터를 사용자 기기에 저장하기
+ *
+ * ```tsx
+ * import { Button } from 'react-native';
+ * import { saveBase64Data } from '@apps-in-toss/framework';
+ *
+ * // '저장' 버튼을 누르면 이미지가 사용자 기기에 저장돼요.
+ * function SaveButton() {
+ *   const handleSave = async () => {
+ *     try {
+ *       await saveBase64Data({
+ *         data: 'iVBORw0KGgo...',
+ *         fileName: 'some-photo.png',
+ *         mimeType: 'image/png',
+ *       });
+ *     } catch (error) {
+ *       console.error('데이터 저장에 실패했어요:', error);
+ *     }
+ *   };
+ *
+ *   return <Button title="저장" onPress={handleSave} />;
+ * }
+ * ```
+ */
+declare function saveBase64Data(params: SaveBase64DataParams): Promise<void>;
+
+/**
+ * @public
+ * @category 게임센터
+ * @name SubmitGameCenterLeaderBoardScoreResponse
+ * @description
+ * 토스게임센터 리더보드에 점수를 제출한 결과 정보를 담아서 반환해요. 반환된 정보를 사용해서 점수 제출 결과에 따라 적절한 에러 처리를 할 수 있어요.
+ * @property {'SUCCESS' | 'LEADERBOARD_NOT_FOUND' | 'PROFILE_NOT_FOUND' | 'UNPARSABLE_SCORE'} statusCode
+ * 점수 제출 결과를 나타내는 상태 코드예요.
+ * - `'SUCCESS'`: 점수 제출이 성공했어요.
+ * - `'LEADERBOARD_NOT_FOUND'`: `gameId`에 해당하는 리더보드를 찾을 수 없어요.
+ * - `'PROFILE_NOT_FOUND'`: 사용자의 프로필이 없어요.
+ * - `'UNPARSABLE_SCORE'`: 점수를 해석할 수 없어요. 점수는 실수(float) 형태의 문자열로 전달해야 해요.
+ */
+interface SubmitGameCenterLeaderBoardScoreResponse {
+    statusCode: 'SUCCESS' | 'LEADERBOARD_NOT_FOUND' | 'PROFILE_NOT_FOUND' | 'UNPARSABLE_SCORE';
+}
+/**
+ * @public
+ * @category 게임센터
+ * @name submitGameCenterLeaderBoardScore
+ * @description
+ * 사용자의 게임 점수를 토스게임센터 리더보드에 제출해요. 이 기능으로 사용자의 점수를 공식 리더보드에 기록하고 다른 사용자와 비교할 수 있어요.
+ * @param {string} params.score
+ * 제출할 게임 점수예요. 실수 형태의 숫자를 문자열로 전달해야 해요. 예를들어 `"123.45"` 또는 `"9999"` 예요.
+ * @returns {Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>}
+ * 점수 제출 결과를 반환해요. 앱 버전이 최소 지원 버전보다 낮으면 아무 동작도 하지 않고 `undefined`를 반환해요.
+ *
+ * @example
+ * ### 게임 점수를 토스게임센터 리더보드에 제출하기
+ * ```tsx
+ * import { Button } from 'react-native';
+ * import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/framework';
+ *
+ * function GameCenterLeaderBoardScoreSubmitButton() {
+ *   async function handlePress() {
+ *     try {
+ *       const result = await submitGameCenterLeaderBoardScore({ score: '123.45' });
+ *
+ *       if (!result) {
+ *         console.warn('지원하지 않는 앱 버전이에요.');
+ *         return;
+ *       }
+ *
+ *       if (result.statusCode === 'SUCCESS') {
+ *         console.log('점수 제출 성공!');
+ *       } else {
+ *         console.error('점수 제출 실패:', result.statusCode);
+ *       }
+ *     } catch (error) {
+ *       console.error('점수 제출 중 오류가 발생했어요.', error);
+ *     }
+ *   }
+ *
+ *   return (
+ *     <Button onPress={handlePress}>점수 제출하기</Button>
+ *   );
+ * }
+ * ```
+ */
+declare function submitGameCenterLeaderBoardScore(params: {
+    score: string;
+}): Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>;
+
 /**
- * @public
- * @category 인앱결제
- * @name ConsumableProductListItem
- * @description 소모품 상품 정보를 담은 객체예요.
- * @property {string} sku - 상품의 고유 ID예요.
- * @property {string} type - 상품의 유형이에요. `CONSUMABLE`을 나타내요.
- * @property {string} displayName - 화면에 표시할 상품 이름이에요. 상품 이름은 앱인토스 콘솔에서 설정한 값이에요.
- * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
- * @property {string} iconUrl - 상품 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요.
- * @property {string} description - 상품에 대한 설명이에요. 설명은 앱인토스 콘솔에서 설정한 값이에요.
+ * Async Methods Map
+ * Type definitions for all async methods accessed via postMessage
  */
-interface ConsumableProductListItem extends BasicProductListItem {
-    type: 'CONSUMABLE';
+interface AsyncMethodsMap {
+    getStorageItem: (params: {
+        key: string;
+    }) => Promise<string | null>;
+    setStorageItem: (params: {
+        key: string;
+        value: string;
+    }) => Promise<void>;
+    removeStorageItem: (params: {
+        key: string;
+    }) => Promise<void>;
+    clearStorage: (params: CompatiblePlaceholderArgument) => Promise<void>;
+    getPermission: (params: {
+        name: PermissionName;
+        access: PermissionAccess;
+    }) => Promise<PermissionStatus>;
+    openPermissionDialog: (params: {
+        name: PermissionName;
+        access: PermissionAccess;
+    }) => Promise<'allowed' | 'denied'>;
+    getClipboardText: (params: CompatiblePlaceholderArgument) => Promise<string>;
+    setClipboardText: (params: {
+        text: string;
+    }) => Promise<void>;
+    fetchContacts: (params: {
+        size: number;
+        offset: number;
+        query?: {
+            contains?: string;
+        };
+    }) => Promise<ContactResult>;
+    fetchAlbumPhotos: (params: {
+        base64?: boolean;
+        maxCount?: number;
+        maxWidth?: number;
+    }) => Promise<ImageResponse[]>;
+    openCamera: (params: {
+        base64?: boolean;
+        maxWidth?: number;
+    }) => Promise<ImageResponse>;
+    startUpdateLocation: (params: {
+        accuracy: number;
+        timeInterval: number;
+        distanceInterval: number;
+    }) => Promise<void>;
+    getCurrentLocation: (params: {
+        accuracy: number;
+    }) => Promise<Location>;
+    iapCreateOneTimePurchaseOrder: (params: {
+        productId: string;
+    }) => Promise<IapCreateOneTimePurchaseOrderResult>;
+    processProductGrant: (params: {
+        orderId: string;
+        isProductGranted: boolean;
+    }) => Promise<void>;
+    iapGetProductItemList: (params: CompatiblePlaceholderArgument) => Promise<{
+        products: any[];
+    }>;
+    getPendingOrders: (params: CompatiblePlaceholderArgument) => Promise<{
+        orders: Array<{
+            orderId: string;
+            sku: string;
+        }>;
+    }>;
+    getCompletedOrRefundedOrders: (params: {
+        key?: string | null;
+    }) => Promise<any>;
+    completeProductGrant: (params: {
+        orderId: string;
+    }) => Promise<boolean>;
+    eventLog: (params: {
+        log_name: string;
+        log_type: string;
+        params: Record<string, string>;
+    }) => Promise<void>;
+    getTossShareLink: (params: CompatiblePlaceholderArgument) => Promise<{
+        shareLink: string;
+    }>;
+    appLogin: (params: CompatiblePlaceholderArgument) => Promise<{
+        authorizationCode: string;
+        referrer: 'DEFAULT' | 'SANDBOX';
+    }>;
+    checkoutPayment: (params: CheckoutPaymentOptions) => Promise<CheckoutPaymentResult>;
+    setDeviceOrientation: (params: {
+        type: 'portrait' | 'landscape';
+    }) => Promise<void>;
+    saveBase64Data: (params: SaveBase64DataParams) => Promise<void>;
+    appsInTossSignTossCert: (params: AppsInTossSignTossCertParams) => Promise<void>;
+    getGameCenterGameProfile: (params: CompatiblePlaceholderArgument) => Promise<GameCenterGameProfileResponse | undefined>;
+    getUserKeyForGame: (params: CompatiblePlaceholderArgument) => Promise<GetUserKeyForGameResponse | undefined>;
+    grantPromotionRewardForGame: (params: {
+        promotionCode: string;
+        amount: number;
+    }) => Promise<GrantPromotionRewardForGameResponse | undefined>;
+    submitGameCenterLeaderBoardScore: (params: {
+        score: string;
+    }) => Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>;
+    requestOneTimePurchase: (params: {
+        sku: string;
+    }) => Promise<void>;
+    contactsViral: (params: {
+        moduleId: string;
+    }) => Promise<void>;
+    getMiniAppsSupportContact: (params: object) => Promise<void>;
+    loadAdMobInterstitialAd: (params: {
+        adUnitId: string;
+    }) => Promise<void>;
+    showAdMobInterstitialAd: (params: {
+        adUnitId: string;
+    }) => Promise<void>;
+    loadAdMobRewardedAd: (params: {
+        adUnitId: string;
+    }) => Promise<void>;
+    showAdMobRewardedAd: (params: {
+        adUnitId: string;
+    }) => Promise<void>;
+    loadAppsInTossAdmob: (params: {
+        adGroupId: string;
+        referrer: string;
+    }) => Promise<void>;
+    showAppsInTossAdmob: (params: {
+        adGroupId: string;
+        referrer: string;
+    }) => Promise<void>;
+    getIsTossLoginIntegratedService: (params: object) => Promise<boolean | undefined>;
+    getServerTime: (params: CompatiblePlaceholderArgument) => Promise<{
+        serverTime: number;
+    }>;
 }
 /**
- * @public
- * @category 인앱결제
- * @name NonConsumableProductListItem
- * @description 비소모품 상품 정보를 담은 객체예요.
- * @property {string} sku - 상품의 고유 ID예요.
- * @property {string} type - 상품의 유형이에요. `NON_CONSUMABLE`을 나타내요.
- * @property {string} displayName - 화면에 표시할 상품 이름이에요. 상품 이름은 앱인토스 콘솔에서 설정한 값이에요.
- * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
- * @property {string} iconUrl - 상품 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요.
- * @property {string} description - 상품에 대한 설명이에요. 설명은 앱인토스 콘솔에서 설정한 값이에요.
+ * Sync Methods Map
+ * Type definitions for all sync methods accessed via postMessageSync
  */
-interface NonConsumableProductListItem extends BasicProductListItem {
-    type: 'NON_CONSUMABLE';
+interface SyncMethodsMap {
+    getWebBundleURL: (params: CompatiblePlaceholderArgument) => {
+        url: string;
+    };
+    shareWithScheme: (params: {
+        schemeURL: string;
+    }) => void;
+    stopUpdateLocation: (params: object) => void;
 }
 /**
- * @public
- * @category 인앱결제
- * @name SubscriptionProductListItem
- * @description 자동 갱신 구독 상품 정보를 담은 객체예요.
- * @property {string} sku - 상품의 고유 ID예요.
- * @property {string} type - 상품의 유형이에요. `SUBSCRIPTION`을 나타내요.
- * @property {string} displayName - 화면에 표시할 상품 이름이에요. 상품 이름은 앱인토스 콘솔에서 설정한 값이에요.
- * @property {string} displayAmount - 통화 단위가 포함된 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
- * @property {string} iconUrl - 상품 아이콘 이미지의 URL이에요. 아이콘은 앱인토스 콘솔에서 설정한 이미지예요.
- * @property {string} description - 상품에 대한 설명이에요. 설명은 앱인토스 콘솔에서 설정한 값이에요.
- * @property {string} renewalCycle - 구독 갱신 주기이에요. `WEEKLY`, `MONTHLY`, `YEARLY` 중 하나를 나타내요.
- * @property {Offer[]} offers - 구독 혜택 옵션 목록이에요. 각 옵션은 하나의 구독 혜택을 나타내요.
- * @property {string} offers[].type - 구독 혜택 옵션 유형이에요. `FREE_TRIAL`, `NEW_SUBSCRIPTION`, `RETURNING` 중 하나를 나타내요.
- * @property {string} offers[].offerId - 구독 혜택 옵션의 고유 ID예요.
- * @property {string} offers[].period - 구독 혜택 옵션의 적용 기간이에요.
- * @property {string} offers[].displayAmount - 통화 단위가 포함된 구독 혜택 옵션의 가격 정보예요. 예를 들어 `1,000원`으로 가격과 통화가 함께 표시돼요.
+ * Type-safe postMessage wrapper
+ * Provides type inference for async method calls without requiring 'as unknown' casts
  */
-interface SubscriptionProductListItem extends BasicProductListItem {
-    type: 'SUBSCRIPTION';
-    renewalCycle: 'WEEKLY' | 'MONTHLY' | 'YEARLY';
-    offers?: Offer[];
+declare function safePostMessage<K extends keyof AsyncMethodsMap>(method: K, params: Parameters<AsyncMethodsMap[K]>[0]): ReturnType<AsyncMethodsMap[K]>;
+/**
+ * Type-safe postMessageSync wrapper
+ * Provides type inference for sync method calls without requiring 'as unknown' casts
+ */
+declare function safeSyncPostMessage<K extends keyof SyncMethodsMap>(method: K, params: Parameters<SyncMethodsMap[K]>[0]): ReturnType<SyncMethodsMap[K]>;
+
+interface EventEmitterSchema<K extends string, P extends unknown[]> {
+    name: K;
+    params: P;
 }
+
 /**
- * @public
- * @category 인앱결제
- * @name IapProductListItem
- * @description 인앱결제로 구매할 수 있는 상품 하나의 정보를 담은 객체예요. 상품 목록을 화면에 표시할 때 사용해요.
+ * @name UpdateLocationEventEmitter
+ * @kind typedef
+ * @description
+ * 디바이스의 위치 정보 변경을 감지해요
  */
-type IapProductListItem = ConsumableProductListItem | NonConsumableProductListItem | SubscriptionProductListItem;
+type UpdateLocationEventEmitter = EventEmitterSchema<'updateLocation', [Location]>;
 /**
  * @public
- * @category 인앱결제
- * @name getProductItemList
- * @description 인앱결제로 구매할 수 있는 상품 목록을 가져와요. 상품 목록 화면에 진입할 때 호출해요.
- * @returns {Promise<{ products: IapProductListItem[] } | undefined>} 상품 목록을 포함한 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.219.0, iOS 5.219.0)보다 낮으면 `undefined`를 반환해요.
+ * @category 위치 정보
+ * @name startUpdateLocation
+ * @description  디바이스의 위치 정보를 지속적으로 감지하고, 위치가 변경되면 콜백을 실행하는 함수예요. 콜백 함수를 등록하면 위치가 변경될 때마다 자동으로 호출돼요.
+ * 실시간 위치 추적이 필요한 기능을 구현할 때 사용할 수 있어요. 예를 들어 지도 앱에서 사용자의 현재 위치를 실시간으로 업데이트할 때, 운동 앱에서 사용자의 이동 거리를 기록할 때 등이에요.
+ * 위치 업데이트 주기와 정확도를 조정해 배터리 소모를 최소화하면서도 필요한 정보를 얻을 수 있어요.
  *
- * @example
- * ### 구매 가능한 인앱결제 상품목록 가져오기
  *
- * ```tsx
- * import { IAP, IapProductListItem } from "@apps-in-toss/framework";
- * import { Button, List, ListRow } from "@toss/tds-react-native";
- * import { useEffect, useState } from "react";
+ * @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) 단위로 설정해요.
  *
- * function IapProductList() {
- *   const [products, setProducts] = useState<IapProductListItem[]>([]);
+ * @property [openPermissionDialog] - 위치 정보 권한을 다시 요청하는 다이얼로그를 표시해요. 사용자는 "허용", "한 번만 허용", "안하기" 중 하나를 선택할 수 있어요. "허용"이나 "한 번만 허용"을 선택하면 `allowed`를 반환하고, "안하기"를 선택하면 `denied`를 반환해요.
+ * @property [getPermission] - 위치 정보 권한의 현재 상태를 반환해요. `allowed`는 사용자가 위치 정보 권한을 허용한 상태예요. `denied`는 사용자가 위치 정보 권한을 거부한 상태예요. `notDetermined`는 위치 정보 권한 요청을 한 번도 하지 않은 상태예요.
  *
- *   async function buyIapProduct(productId: string) {
- *     try {
- *       await IAP.createOneTimePurchaseOrder({
- *         productId,
- *       });
+ * @signature
+ * ```typescript
+ * function startUpdateLocation(options: {
+ *   onError: (error: unknown) => void;
+ *   onEvent: (location: Location) => void;
+ *   options: StartUpdateLocationOptions;
+ * }): () => void;
+ * ```
  *
- *       console.error("인앱결제에 성공했어요");
- *     } catch (error) {
- *       console.error("인앱결제에 실패했어요:", error);
- *     }
- *   }
+ * @example
+ * ### 위치 정보 변경 감지하기
  *
- *   useEffect(() => {
- *     async function fetchProducts() {
- *       try {
- *         const response = await IAP.getProductItemList();
- *         setProducts(response?.products ?? []);
- *       } catch (error) {
- *         console.error("상품 목록을 가져오는 데 실패했어요:", error);
- *       }
- *     }
+ * 위치 정보가 변경되는것을 감지하는 예제예요. "위치 정보 변경 감지하기"를 눌러서 감지할 수 있어요.
  *
- *     fetchProducts();
- *   }, []);
+ * "권한 확인하기"버튼을 눌러서 현재 위치 정보 변경 감지 권한을 확인해요.
+ * 사용자가 권한을 거부했거나 시스템에서 권한이 제한된 경우에는 [`StartUpdateLocationPermissionError`](/react-native/reference/types/권한/StartUpdateLocationPermissionError)를 반환해요.
+ * "권한 요청하기"버튼을 눌러서 위치 정보 변경 감지 권한을 요청할 수 있어요.
  *
- *   return (
- *     <List>
- *       {products.map((product) => (
- *         <ListRow
- *           key={product.sku}
- *           left={
- *             <ListRow.Image type="square" source={{ uri: product.iconUrl }} />
- *           }
- *           right={
- *             <Button size="medium" onPress={() => buyIapProduct(product.sku)}>
- *               구매하기
- *             </Button>
- *           }
- *           contents={
- *             <ListRow.Texts
- *               type="3RowTypeA"
- *               top={product.displayName}
- *               middle={product.description}
- *               bottom={product.displayAmount}
- *             />
- *           }
- *         />
- *       ))}
- *     </List>
+ * ```tsx
+ * 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<Location | null>(null);
+ *
+ *   const handlePress = useCallback(() => {
+ *     startUpdateLocation({
+ *       options: {
+ *         accuracy: Accuracy.Balanced,
+ *         timeInterval: 3000,
+ *         distanceInterval: 10,
+ *       },
+ *       onEvent: (location) => {
+ *         setLocation(location);
+ *       },
+ *       onError: (error) => {
+ *         if (error instanceof StartUpdateLocationPermissionError) {
+ *           // 위치 정보 변경 감지 권한 없음
+ *         }
+ *         console.error('위치 정보를 가져오는데 실패했어요:', error);
+ *       },
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <View>
+ *       {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 getProductItemList(): Promise<{
-    products: IapProductListItem[];
-} | undefined>;
+declare function startUpdateLocation(eventParams: StartUpdateLocationEventParams): () => void;
+declare namespace startUpdateLocation {
+    var openPermissionDialog: _apps_in_toss_types.PermissionDialogFunction;
+    var getPermission: _apps_in_toss_types.GetPermissionFunction;
+}
+
 /**
  * @public
- * @category 인앱결제
- * @name getPendingOrders
- * @description 대기 중인 주문 목록을 가져와요. 이 함수를 사용하면 결제가 아직 완료되지 않은 주문 정보를 확인할 수 있어요.
- * @returns {Promise<{ orders: { orderId: string; sku: string; paymentCompletedDate: string; }[]}>} 대기 중인 주문의 배열을 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.234.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.
- *
- * @example
- * ### 대기 중인 주문 목록 가져오기
- * ```typescript
- * import { IAP } from '@apps-in-toss/framework';
- *
- * async function fetchOrders() {
- *   try {
- *     const pendingOrders = await IAP.getPendingOrders();
- *     return pendingOrders;
- *   } catch (error) {
- *     console.error(error);
- *   }
- * }
- * ```
+ * @category 친구초대
+ * @name RewardFromContactsViralEvent
+ * @description 친구에게 공유하기를 완료했을 때 지급할 리워드 정보를 담는 타입이에요. 이 타입을 사용하면 공유가 완료됐을 때 지급할 리워드 정보를 확인할 수 있어요.
+ * @property {'sendViral'} type - 이벤트의 타입이에요. `'sendViral'`은 사용자가 친구에게 공유를 완료했을 때 돌아와요.
+ * @property {Object} data - 지급할 리워드 관련 정보를 담고 있어요.
+ * @property {number} data.rewardAmount - 지급할 리워드 수량이에요. 앱인토스 콘솔에서 설정한 수량 및 금액 값이에요.
+ * @property {string} data.rewardUnit - 리워드의 단위예요. 앱인토스 콘솔에 설정된 리워드 이름인 '하트', '보석' 등이 리워드 단위예요.
  */
-declare function getPendingOrders(): Promise<{
-    orders: {
-        orderId: string;
-        sku: string;
-        paymentCompletedDate: string;
-    }[];
-} | undefined>;
+type RewardFromContactsViralEvent = {
+    type: 'sendViral';
+    data: {
+        rewardAmount: number;
+        rewardUnit: string;
+    };
+};
 /**
  * @public
- * @category 인앱결제
- * @name CompletedOrRefundedOrdersResult
- * @description 인앱결제로 구매하거나 환불한 주문 목록을 나타내는 객체예요. 페이지네이션 정보를 포함해요.
- * @property {boolean} hasNext 다음 페이지가 있는지 여부예요. `true`면 더 많은 주문이 남아 있어요.
- * @property {string | null} [nextKey] 다음 주문 목록을 조회할 때 사용할 키예요. 마지막 페이지라면 `null`이거나 생략될 수 있어요.
- * @property {Array} orders 주문 정보를 담은 배열이에요. 각 요소는 하나의 주문을 나타내요.
- * @property {string} orders[].orderId 주문의 고유 ID예요.
- * @property {string} orders[].sku 주문 상품의 고유 ID예요.
- * @property {'COMPLETED' | 'REFUNDED'} orders[].status 주문의 상태예요. 'COMPLETED'는 주문이 완료된 상태, 'REFUNDED'는 환불된 상태를 의미해요.
- * @property {string} orders[].date 주문의 날짜 정보예요. ISO 8601 형식(YYYY-MM-DDTHH:mm:ss)을 사용해요. 예를 들어 "2025-09-22T00:00:00" 형식으로 제공돼요. 주문 상태가 `COMPLETED`라면 주문한 날짜를, `REFUNDED`라면 환불한 날짜를 나타내요.
+ * @category 친구초대
+ * @name ContactsViralSuccessEvent
+ * @description 연락처 공유 모듈이 정상적으로 종료됐을 때 전달되는 이벤트 객체예요. 종료 이유와 함께 리워드 상태 및 남은 친구 수 등 관련 정보를 제공해요.
+ * @property {'close'} type - 이벤트의 타입이에요. `'close'`는 공유 모듈이 종료됐을 때 돌아와요.
+ * @property {Object} data - 모듈 종료와 관련된 세부 정보를 담고 있어요.
+ * @property {'clickBackButton' | 'noReward'} data.closeReason - 모듈이 종료된 이유예요. `'clickBackButton'`은 사용자가 뒤로 가기 버튼을 눌러 종료한 경우이고, `'noReward'`는 받을 수 있는 리워드가 없어서 종료된 경우예요.
+ * @property {number} data.sentRewardAmount - 사용자가 받은 전체 리워드 수량이에요.
+ * @property {number} data.sendableRewardsCount - 아직 공유할 수 있는 친구 수예요.
+ * @property {number} data.sentRewardsCount - 사용자가 공유를 완료한 친구 수예요.
+ * @property {string} data.rewardUnit - 리워드의 단위예요. 앱인토스 콘솔에 설정된 리워드 이름인 '하트', '보석' 등이 리워드 단위예요.
  */
-interface CompletedOrRefundedOrdersResult {
-    hasNext: boolean;
-    nextKey?: string | null;
-    orders: {
-        orderId: string;
-        sku: string;
-        status: 'COMPLETED' | 'REFUNDED';
-        date: string;
-    }[];
-}
+type ContactsViralSuccessEvent = {
+    type: 'close';
+    data: {
+        closeReason: 'clickBackButton' | 'noReward';
+        sentRewardAmount?: number;
+        sendableRewardsCount?: number;
+        sentRewardsCount: number;
+        rewardUnit?: string;
+    };
+};
+type ContactsViralEvent = RewardFromContactsViralEvent | ContactsViralSuccessEvent;
 /**
  * @public
- * @category 인앱결제
- * @name getCompletedOrRefundedOrders
- * @description 인앱결제로 구매하거나 환불한 주문 목록을 가져와요.
- * @returns {Promise<CompletedOrRefundedOrdersResult>} 페이지네이션을 포함한 주문 목록 객체를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.231.0, iOS 5.231.0)보다 낮으면 `undefined`를 반환해요.
- *
- * @example
- * ```typescript
- * import { IAP } from "@apps-in-toss/framework";
- *
- * async function fetchOrders() {
- *   try {
- *     const response =  await IAP.getCompletedOrRefundedOrders();
- *     return response;
- *   } catch (error) {
- *     console.error(error);
- *   }
- * }
- * ```
+ * @category 친구초대
+ * @name ContactsViralOption
+ * @description [연락처 공유 기능](/react-native/reference/native-modules/친구초대/contactsViral.html)을 사용할 때 필요한 옵션이에요.
+ * @property {string} moduleId - 공유 리워드를 구분하는 UUID 형식의 고유 ID예요. 앱인토스 콘솔의 미니앱 > 공유 리워드 메뉴에서 확인할 수 있어요.
  */
-declare function getCompletedOrRefundedOrders(params?: {
-    key?: string | null;
-}): Promise<CompletedOrRefundedOrdersResult | undefined>;
+type ContactsViralOption = {
+    moduleId: string;
+};
 /**
  * @public
- * @category 인앱결제
- * @name completeProductGrant
- * @description 상품 지급 처리를 완료했다는 메시지를 앱에 전달해요. 이 함수를 사용하면 결제가 완료된 주문의 상품 지급이 정상적으로 완료되었음을 알릴 수 있어요.
- * @param {{ params: { orderId: string } }} params 결제가 완료된 주문 정보를 담은 객체예요.
- * @param {string} params.orderId 주문의 고유 ID예요. 상품 지급을 완료할 주문을 지정할 때 사용해요.
- * @returns {Promise<boolean>} 상품 지급이 완료됐는지 여부를 반환해요. 앱 버전이 최소 지원 버전(안드로이드 5.233.0, iOS 5.233.0)보다 낮으면 `undefined`를 반환해요.
+ * @category 친구초대
+ * @name ContactsViralParams
+ * @description `ContactsViralParams`는 연락처 공유 기능을 사용할 때 전달해야 하는 파라미터 타입이에요. 옵션을 설정하고, 이벤트 및 에러 처리 콜백을 지정할 수 있어요.
+ * @property {ContactsViralOption} options - 공유 기능에 사용할 옵션 객체예요.
+ * @property {(event: ContactsViralEvent) => void} onEvent - 공유 이벤트가 발생했을 때 실행되는 함수예요. [`RewardFromContactsViralEvent`](/bedrock/reference/native-modules/친구초대/RewardFromContactsViralEvent.html) 또는 [`ContactsViralSuccessEvent`](/react-native/reference/native-modules/친구초대/ContactsViralSuccessEvent.html) 타입의 이벤트 객체가 전달돼요.
+ * @property {(error: unknown) => void} onError - 예기치 않은 에러가 발생했을 때 실행되는 함수예요.
+ */
+interface ContactsViralParams {
+    options: ContactsViralOption;
+    onEvent: (event: ContactsViralEvent) => void;
+    onError: (error: unknown) => void;
+}
+/**
+ * @public
+ * @category 친구초대
+ * @name contactsViral
+ * @description 친구에게 공유하고 리워드를 받을 수 있는 기능을 제공해요. 사용자가 친구에게 공유를 완료하면 앱브릿지가 이벤트를 통해 리워드 정보를 전달해요.
+ * @param {ContactsViralParams} params - 연락처 공유 기능을 실행할 때 사용하는 파라미터예요. 옵션 설정과 이벤트 핸들러를 포함해요. 자세한 내용은 [ContactsViralParams](/bedrock/reference/native-modules/친구초대/ContactsViralParams.html) 문서를 참고하세요.
+ * @returns {() => void} 앱브릿지 cleanup 함수를 반환해요. 공유 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.
  *
  * @example
- * ### 결제를 성공한 뒤 상품을 지급하는 예시
- * ```typescript
- * import { IAP } from '@apps-in-toss/framework';
+ * ### 친구에게 공유하고 리워드 받기
  *
- * async function handleGrantProduct(orderId: string) {
- *   try {
- *     await IAP.completeProductGrant({ params: { orderId } });
- *   } catch (error) {
- *     console.error(error);
- *   }
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { Button } from 'react-native';
+ * import { contactsViral } from '@apps-in-toss/framework';
+ *
+ * function ContactsViralButton({ moduleId }: { moduleId: string }) {
+ *   const handleContactsViral = useCallback(() => {
+ *     try {
+ *       const cleanup = contactsViral({
+ *         options: { moduleId: moduleId.trim() },
+ *         onEvent: (event) => {
+ *           if (event.type === 'sendViral') {
+ *             console.log('리워드 지급:', event.data.rewardAmount, event.data.rewardUnit);
+ *           } else if (event.type === 'close') {
+ *             console.log('모듈 종료:', event.data.closeReason);
+ *           }
+ *         },
+ *         onError: (error) => {
+ *           console.error('에러 발생:', error);
+ *         },
+ *       });
+ *
+ *       return cleanup;
+ *     } catch (error) {
+ *       console.error('실행 중 에러:', error);
+ *     }
+ *   }, [moduleId]);
+ *
+ *   return <Button title="친구에게 공유하고 리워드 받기" onPress={handleContactsViral} />;
  * }
  * ```
  */
-declare function completeProductGrant(params: {
-    params: {
-        orderId: string;
-    };
-}): Promise<boolean | undefined>;
-/**
- * @public
- * @category 인앱결제
- * @name CreateSubscriptionPurchaseOrderOptions
- * @description 구독 인앱결제를 생성할 때 필요한 옵션이에요.
- * @property {object} options - 결제할 구독 상품의 정보예요.
- * @property {string} options.sku - 주문할 구독 상품의 고유 ID예요.
- * @property {string | null} [options.offerId] - 적용할 offer ID예요. 없으면 기본 가격이 적용돼요.
- * @property {(params: { orderId: string, subscriptionId?: string }) => boolean | Promise<boolean>} options.processProductGrant - 주문이 만들어진 뒤 실제로 상품을 지급할 때 호출해요.
- * @property {(event: SubscriptionSuccessEvent) => void | Promise<void>} onEvent - 결제가 성공했을 때 호출해요.
- * @property {(error: unknown) => void | Promise<void>} onError - 결제 과정에서 에러가 발생했을 때 호출해요.
- */
-interface CreateSubscriptionPurchaseOrderOptions {
-    options: {
-        sku: string;
-        offerId?: string | null;
-        processProductGrant: (params: {
-            orderId: string;
-            subscriptionId?: string;
-        }) => boolean | Promise<boolean>;
+declare function contactsViral(params: ContactsViralParams): () => void;
+
+interface StartUpdateLocationOptions {
+    /**
+     * 위치 정확도를 설정해요.
+     */
+    accuracy: Accuracy;
+    /**
+     * 위치 업데이트 주기를 밀리초(ms) 단위로 설정해요.
+     */
+    timeInterval: number;
+    /**
+     * 위치 변경 거리를 미터(m) 단위로 설정해요.
+     */
+    distanceInterval: number;
+}
+declare class UpdateLocationEvent extends GraniteEventDefinition<StartUpdateLocationOptions, Location> {
+    name: "updateLocationEvent";
+    subscriptionCount: number;
+    ref: {
+        remove: () => void;
     };
-    onEvent: (event: SubscriptionSuccessEvent) => void | Promise<void>;
-    onError: (error: unknown) => void | Promise<void>;
+    remove(): void;
+    listener(options: StartUpdateLocationOptions, onEvent: (response: Location) => void, onError: (error: unknown) => void): void;
 }
-/**
- * @public
- * @category 인앱결제
- * @name IapCreateSubscriptionPurchaseOrderResult
- * @description 구독 인앱결제가 완료되면 결제 세부 정보와 상품 정보를 담아 반환해요. `IapCreateOneTimePurchaseOrderResult`와 동일한 구조예요.
- */
-type IapCreateSubscriptionPurchaseOrderResult = IapCreateOneTimePurchaseOrderResult;
-interface SubscriptionSuccessEvent {
-    type: 'success';
-    data: IapCreateSubscriptionPurchaseOrderResult;
+
+interface AppBridgeCallbackResult {
+    name: string;
+    params?: any;
+}
+declare class AppBridgeCallbackEvent extends GraniteEventDefinition<void, AppBridgeCallbackResult> {
+    private static INTERNAL__appBridgeSubscription?;
+    name: "appBridgeCallbackEvent";
+    constructor();
+    remove(): void;
+    listener(): void;
+    private registerAppBridgeCallbackEventListener;
+    private ensureInvokeAppBridgeCallback;
+}
+
+interface VisibilityChangedByTransparentServiceWebOptions {
+    callbackId: string;
 }
+declare class VisibilityChangedByTransparentServiceWebEvent extends GraniteEventDefinition<VisibilityChangedByTransparentServiceWebOptions, boolean> {
+    name: "onVisibilityChangedByTransparentServiceWeb";
+    unsubscribe: (() => void) | null;
+    remove(): void;
+    listener(options: VisibilityChangedByTransparentServiceWebOptions, onEvent: (isVisible: boolean) => void, onError: (error: unknown) => void): void;
+    private isVisibilityChangedByTransparentServiceWebResult;
+}
+
+declare const appsInTossEvent: GraniteEvent<UpdateLocationEvent | AppBridgeCallbackEvent | VisibilityChangedByTransparentServiceWebEvent>;
+
+declare function onVisibilityChangedByTransparentServiceWeb(eventParams: {
+    options: {
+        callbackId: string;
+    };
+    onEvent: (isVisible: boolean) => void;
+    onError: (error: unknown) => void;
+}): () => void;
+
+interface AppBridgeCompatCallbacks<Result> {
+    onSuccess: (result: Result) => void;
+    onError: (reason: unknown) => void;
+}
+type AppBridgeCallback = (...args: any[]) => void;
+declare function invokeAppBridgeCallback(id: string, ...args: any[]): boolean;
+declare function invokeAppBridgeMethod<Result = any, Params extends AnyObject = any>(methodName: string, params: Params, callbacks: AppBridgeCompatCallbacks<Result> & Record<string, AppBridgeCallback>): () => void;
+declare function registerCallback(callback: AppBridgeCallback, name?: string): string;
+declare function unregisterCallback(id: string): void;
+declare function getCallbackIds(): string[];
+declare const INTERNAL__appBridgeHandler: {
+    invokeAppBridgeCallback: typeof invokeAppBridgeCallback;
+    invokeAppBridgeMethod: typeof invokeAppBridgeMethod;
+    registerCallback: typeof registerCallback;
+    unregisterCallback: typeof unregisterCallback;
+    getCallbackIds: typeof getCallbackIds;
+};
+
 /**
  * @public
- * @category 인앱결제
- * @name createSubscriptionPurchaseOrder
- * @description
- * 구독 인앱결제 주문서 페이지로 이동해요. 사용자가 구독 상품 구매 버튼을 누르는 상황 등에 사용할 수 있어요.
- * @param {CreateSubscriptionPurchaseOrderOptions} params - 구독 인앱결제를 생성할 때 필요한 정보예요.
- * @returns {() => void} 앱브릿지 cleanup 함수를 반환해요. 인앱결제 기능이 끝나면 반드시 이 함수를 호출해서 리소스를 해제해야 해요.
+ * @category 광고
+ * @name loadAppsInTossAdMob
+ * @description 광고를 미리 불러와서, 광고가 필요한 시점에 바로 보여줄 수 있도록 준비하는 함수예요.
+ * @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/native-modules/광고/LoadAdMobEvent.html)를 참고하세요.
+ * @param {(reason: unknown) => void} [params.onError] 광고를 불러오지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
+ * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
  *
  * @example
- * ### 구독 인앱결제 주문서 페이지로 이동하기
- *
+ * ### 버튼 눌러 불러온 광고 보여주기
  * ```tsx
- * import { IAP } from "@apps-in-toss/web-framework";
- * import { Button } from "@toss/tds-react-native";
- * import { useCallback } from "react";
+ * import { GoogleAdMob } from '@apps-in-toss/framework';
+ * import { useFocusEffect } from '@react-native-bedrock/native/@react-navigation/native';
+ * import { useCallback, useState } from 'react';
+ * import { Button, Text, View } from 'react-native';
+ * import { useNavigation } from 'react-native-bedrock';
  *
- * interface Props {
- *   sku: string;
- *   offerId?: string;
- * }
+ * const AD_GROUP_ID = '<AD_GROUP_ID>';
  *
- * function SubscriptionPurchaseButton({ sku, offerId }: Props) {
- *   const handleClick = useCallback(async () => {
- *     const cleanup = IAP.createSubscriptionPurchaseOrder({
+ * export function GoogleAdmobExample() {
+ *   const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
+ *   const navigation = useNavigation();
+ *
+ *   const loadAd = useCallback(() => {
+ *     if (GoogleAdMob.loadAppsInTossAdMob.isSupported() !== true) {
+ *       return;
+ *     }
+
+ *     const cleanup = GoogleAdMob.loadAppsInTossAdMob({
  *       options: {
- *         sku,
- *         offerId,
- *         processProductGrant: ({ orderId, subscriptionId }) => {
- *           // 상품 지급 로직 작성
- *           return true; // 상품 지급 여부
- *         },
+ *         adGroupId: AD_GROUP_ID,
  *       },
  *       onEvent: (event) => {
- *         console.log(event);
+ *         switch (event.type) {
+ *           case 'loaded':
+ *             console.log('광고 로드 성공', event.data);
+ *             setAdLoadStatus('loaded');
+ *             break;
+ *         }
  *       },
  *       onError: (error) => {
- *         console.error(error);
+ *         console.error('광고 불러오기 실패', error);
  *       },
  *     });
  *
  *     return cleanup;
- *   }, [sku, offerId]);
+ *   }, [navigation]);
  *
- *   return <Button onClick={handleClick}>구독하기</Button>;
- * }
- * ```
- */
-declare function createSubscriptionPurchaseOrder(params: CreateSubscriptionPurchaseOrderOptions): () => void;
-/**
- * @public
- * @category 인앱결제
- * @name IAP
- * @description 인앱결제 관련 기능을 모은 객체예요. 단건 인앱결제 주문서 이동과 상품 목록 조회 기능을 제공해요.
- * @property {typeof createOneTimePurchaseOrder} [createOneTimePurchaseOrder] 특정 인앱결제 주문서 페이지로 이동해요. 자세한 내용은 [createOneTimePurchaseOrder](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/createOneTimePurchaseOrder.html) 문서를 참고하세요.
- * @property {typeof getProductItemList} [getProductItemList] 인앱결제로 구매할 수 있는 상품 목록을 가져와요. 자세한 내용은 [getProductItemList](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/getProductItemList.html) 문서를 참고하세요.
- * @property {typeof getPendingOrders} [getPendingOrders] 대기 중인 주문 목록을 가져와요. 자세한 내용은 [getPendingOrders](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/getPendingOrders.htm) 문서를 참고하세요.
- * @property {typeof getCompletedOrRefundedOrders} [getCompletedOrRefundedOrders] 인앱결제로 구매하거나 환불한 주문 목록을 가져와요. 자세한 내용은 [getCompletedOrRefundedOrders](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/getCompletedOrRefundedOrders.html) 문서를 참고하세요.
- * @property {typeof completeProductGrant} [completeProductGrant] 상품 지급 처리를 완료했다는 메시지를 앱에 전달해요. 자세한 내용은 [completeProductGrant](https://developers-apps-in-toss.toss.im/bedrock/reference/framework/%EC%9D%B8%EC%95%B1%20%EA%B2%B0%EC%A0%9C/completeProductGrant.html) 문서를 참고하세요.
- */
-declare const IAP: {
-    createOneTimePurchaseOrder: typeof createOneTimePurchaseOrder;
-    createSubscriptionPurchaseOrder: typeof createSubscriptionPurchaseOrder;
-    getProductItemList: typeof getProductItemList;
-    getPendingOrders: typeof getPendingOrders;
-    getCompletedOrRefundedOrders: typeof getCompletedOrRefundedOrders;
-    completeProductGrant: typeof completeProductGrant;
-};
-
-interface SaveBase64DataParams {
-    data: string;
-    fileName: string;
-    mimeType: string;
-}
-/**
- * @public
- * @category 데이터
- * @name saveBase64Data
- * @description 문자열로 인코딩된 Base64 데이터를 지정한 파일 이름과 MIME 타입으로 사용자 기기에 저장해요. 이미지, 텍스트, PDF 등 다양한 형식의 데이터를 저장할 수 있어요.
- * @param {SaveBase64DataParams} params - 저장할 데이터와 파일 정보를 담은 객체예요.
- * @param {string} params.data - Base64 형식으로 인코딩된 데이터 문자열이에요.
- * @param {string} params.fileName - 저장할 파일 이름이에요. 확장자도 같이 붙여줘야해요. 예를 들어, 'example.png'로 저장할 수 있어요.
- * @param {string} params.mimeType - 저장할 파일의 MIME 타입이에요. 예를 들어 'image/png' 로 지정하면 이미지, 'application/pdf'는 PDF 파일이에요. 자세한 내용은 [MIME 문서](https://developer.mozilla.org/ko/docs/Web/HTTP/Guides/MIME_types)를 참고해주세요.
+ *   const showAd = useCallback(() => {
+ *     if (GoogleAdMob.showAppsInTossAdMob.isSupported() !== true) {
+ *       return;
+ *     }
  *
- * @example
- * ### Base64 이미지 데이터를 사용자 기기에 저장하기
+ *     GoogleAdMob.showAppsInTossAdMob({
+ *       options: {
+ *         adGroupId: AD_GROUP_ID,
+ *       },
+ *       onEvent: (event) => {
+ *         switch (event.type) {
+ *           case 'requested':
+ *             console.log('광고 보여주기 요청 완료');
+ *             break;
  *
- * ```tsx
- * import { Button } from 'react-native';
- * import { saveBase64Data } from '@apps-in-toss/framework';
+ *           case 'clicked':
+ *             console.log('광고 클릭');
+ *             break;
  *
- * // '저장' 버튼을 누르면 이미지가 사용자 기기에 저장돼요.
- * function SaveButton() {
- *   const handleSave = async () => {
- *     try {
- *       await saveBase64Data({
- *         data: 'iVBORw0KGgo...',
- *         fileName: 'some-photo.png',
- *         mimeType: 'image/png',
- *       });
- *     } catch (error) {
- *       console.error('데이터 저장에 실패했어요:', error);
- *     }
- *   };
+ *           case 'dismissed':
+ *             console.log('광고 닫힘');
+ *             navigation.navigate('/examples/google-admob-interstitial-ad-landing');
+ *             break;
  *
- *   return <Button title="저장" onPress={handleSave} />;
- * }
- * ```
- */
-declare function saveBase64Data(params: SaveBase64DataParams): Promise<void>;
-
-/**
- * @public
- * @category 게임센터
- * @name SubmitGameCenterLeaderBoardScoreResponse
- * @description
- * 토스게임센터 리더보드에 점수를 제출한 결과 정보를 담아서 반환해요. 반환된 정보를 사용해서 점수 제출 결과에 따라 적절한 에러 처리를 할 수 있어요.
- * @property {'SUCCESS' | 'LEADERBOARD_NOT_FOUND' | 'PROFILE_NOT_FOUND' | 'UNPARSABLE_SCORE'} statusCode
- * 점수 제출 결과를 나타내는 상태 코드예요.
- * - `'SUCCESS'`: 점수 제출이 성공했어요.
- * - `'LEADERBOARD_NOT_FOUND'`: `gameId`에 해당하는 리더보드를 찾을 수 없어요.
- * - `'PROFILE_NOT_FOUND'`: 사용자의 프로필이 없어요.
- * - `'UNPARSABLE_SCORE'`: 점수를 해석할 수 없어요. 점수는 실수(float) 형태의 문자열로 전달해야 해요.
+ *           case 'failedToShow':
+ *             console.log('광고 보여주기 실패');
+ *             break;
+ *
+ *           case 'impression':
+ *             console.log('광고 노출');
+ *             break;
+ *
+ *           case 'userEarnedReward':
+ *             console.log('광고 보상 획득 unitType:', event.data.unitType);
+ *             console.log('광고 보상 획득 unitAmount:', event.data.unitAmount);
+ *             break;
+ *
+ *           case 'show':
+ *             console.log('광고 컨텐츠 보여졌음');
+ *             break;
+ *         }
+ *       },
+ *       onError: (error) => {
+ *         console.error('광고 보여주기 실패', error);
+ *       },
+ *     });
+ *   }, []);
+ *
+ *   useFocusEffect(loadAd);
+ *
+ *   return (
+ *     <View>
+ *       <Text>
+ *         {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
+ *         {adLoadStatus === 'loaded' && '광고 로드 완료'}
+ *         {adLoadStatus === 'failed' && '광고 로드 실패'}
+ *       </Text>
+ *
+ *       <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
+ *     </View>
+ *   );
+ * }
+ * ```
  */
-interface SubmitGameCenterLeaderBoardScoreResponse {
-    statusCode: 'SUCCESS' | 'LEADERBOARD_NOT_FOUND' | 'PROFILE_NOT_FOUND' | 'UNPARSABLE_SCORE';
+declare function loadAppsInTossAdMob(params: LoadAdMobParams): () => void;
+declare namespace loadAppsInTossAdMob {
+    var isSupported: () => boolean;
 }
+
 /**
  * @public
- * @category 게임센터
- * @name submitGameCenterLeaderBoardScore
- * @description
- * 사용자의 게임 점수를 토스게임센터 리더보드에 제출해요. 이 기능으로 사용자의 점수를 공식 리더보드에 기록하고 다른 사용자와 비교할 수 있어요.
- * @param {string} params.score
- * 제출할 게임 점수예요. 실수 형태의 숫자를 문자열로 전달해야 해요. 예를들어 `"123.45"` 또는 `"9999"` 예요.
- * @returns {Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>}
- * 점수 제출 결과를 반환해요. 앱 버전이 최소 지원 버전보다 낮으면 아무 동작도 하지 않고 `undefined`를 반환해요.
+ * @category 광고
+ * @name showAppsInTossAdMob
+ * @description 광고를 사용자에게 노출해요. 이 함수는 `loadAppsInTossAdMob` 로 미리 불러온 광고를 실제로 사용자에게 노출해요.
+ * @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/native-modules/광고/ShowAdMobEvent.html)를 참고하세요.
+ * @param {(reason: unknown) => void} [params.onError] 광고를 노출하지 못했을 때 호출돼요. (예시: 네트워크 오류나 지원하지 않는 환경일 때)
+ * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 Google AdMob 광고 기능을 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
  *
  * @example
- * ### 게임 점수를 토스게임센터 리더보드에 제출하기
+ * ### 버튼 눌러 불러온 광고 보여주기
  * ```tsx
- * import { Button } from 'react-native';
- * import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/framework';
+ * import { GoogleAdMob } from '@apps-in-toss/framework';
+ * import { useFocusEffect } from '@react-native-bedrock/native/@react-navigation/native';
+ * import { useCallback, useState } from 'react';
+ * import { Button, Text, View } from 'react-native';
+ * import { useNavigation } from 'react-native-bedrock';
  *
- * function GameCenterLeaderBoardScoreSubmitButton() {
- *   async function handlePress() {
- *     try {
- *       const result = await submitGameCenterLeaderBoardScore({ score: '123.45' });
+ * const AD_GROUP_ID = '<AD_GROUP_ID>';
  *
- *       if (!result) {
- *         console.warn('지원하지 않는 앱 버전이에요.');
- *         return;
- *       }
+ * export function GoogleAdmobExample() {
+ *   const [adLoadStatus, setAdLoadStatus] = useState<'not_loaded' | 'loaded' | 'failed'>('not_loaded');
+ *   const navigation = useNavigation();
  *
- *       if (result.statusCode === 'SUCCESS') {
- *         console.log('점수 제출 성공!');
- *       } else {
- *         console.error('점수 제출 실패:', result.statusCode);
- *       }
- *     } catch (error) {
- *       console.error('점수 제출 중 오류가 발생했어요.', error);
+ *   const loadAd = useCallback(() => {
+ *     if (GoogleAdMob.loadAppsInTossAdMob.isSupported() !== true) {
+ *       return;
  *     }
- *   }
+
+ *     const cleanup = GoogleAdMob.loadAppsInTossAdMob({
+ *       options: {
+ *         adGroupId: AD_GROUP_ID,
+ *       },
+ *       onEvent: (event) => {
+ *         switch (event.type) {
+ *           case 'loaded':
+ *             console.log('광고 로드 성공', event.data);
+ *             setAdLoadStatus('loaded');
+ *             break;
+ *         }
+ *       },
+ *       onError: (error) => {
+ *         console.error('광고 불러오기 실패', error);
+ *       },
+ *     });
+ *
+ *     return cleanup;
+ *   }, [navigation]);
+ *
+ *   const showAd = useCallback(() => {
+ *     if (GoogleAdMob.showAppsInTossAdMob.isSupported() !== true) {
+ *       return;
+ *     }
+ *
+ *     GoogleAdMob.showAppsInTossAdMob({
+ *       options: {
+ *         adGroupId: AD_GROUP_ID,
+ *       },
+ *       onEvent: (event) => {
+ *         switch (event.type) {
+ *           case 'requested':
+ *             console.log('광고 보여주기 요청 완료');
+ *             break;
+ *
+ *           case 'clicked':
+ *             console.log('광고 클릭');
+ *             break;
+ *
+ *           case 'dismissed':
+ *             console.log('광고 닫힘');
+ *             navigation.navigate('/examples/google-admob-interstitial-ad-landing');
+ *             break;
+ *
+ *           case 'failedToShow':
+ *             console.log('광고 보여주기 실패');
+ *             break;
+ *
+ *           case 'impression':
+ *             console.log('광고 노출');
+ *             break;
+ *
+ *           case 'userEarnedReward':
+ *             console.log('광고 보상 획득 unitType:', event.data.unitType);
+ *             console.log('광고 보상 획득 unitAmount:', event.data.unitAmount);
+ *             break;
+ *
+ *           case 'show':
+ *             console.log('광고 컨텐츠 보여졌음');
+ *             break;
+ *         }
+ *       },
+ *       onError: (error) => {
+ *         console.error('광고 보여주기 실패', error);
+ *       },
+ *     });
+ *   }, []);
+ *
+ *   useFocusEffect(loadAd);
  *
  *   return (
- *     <Button onPress={handlePress}>점수 제출하기</Button>
+ *     <View>
+ *       <Text>
+ *         {adLoadStatus === 'not_loaded' && '광고 로드 하지 않음 '}
+ *         {adLoadStatus === 'loaded' && '광고 로드 완료'}
+ *         {adLoadStatus === 'failed' && '광고 로드 실패'}
+ *       </Text>
+ *
+ *       <Button title="Show Ad" onPress={showAd} disabled={adLoadStatus !== 'loaded'} />
+ *     </View>
  *   );
  * }
  * ```
  */
-declare function submitGameCenterLeaderBoardScore(params: {
-    score: string;
-}): Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>;
+declare function showAppsInTossAdMob(params: ShowAdMobParams): () => void;
+declare namespace showAppsInTossAdMob {
+    var isSupported: () => boolean;
+}
 
 /**
- * TurboModule 타입 별칭 사용하는 이유?
- * React Native Codegen 에 의해 코드젠 되는 것이 아니라 추후 내부 모듈 체계에 의해 처리될 것이기 때문에 RN Codegen에 본 파일을 코드젠 하지 않도록 함
- * (코드젠 내부에서 "extends TurboModule" 문자열을 찾기 때문에 패턴에 매칭되지 않도록 함)
- */
-interface Spec extends TurboModule {
-    groupId: string;
-    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;
-    };
-    getPermission: (permission: {
-        name: PermissionName;
-        access: PermissionAccess;
-    }) => Promise<PermissionStatus>;
-    openPermissionDialog: (permission: {
-        name: PermissionName;
-        access: PermissionAccess;
-    }) => Promise<Exclude<PermissionStatus, 'notDetermined'>>;
-    appLogin: (arg: CompatiblePlaceholderArgument) => Promise<{
-        authorizationCode: string;
-        referrer: 'DEFAULT' | 'SANDBOX';
-    }>;
-    checkoutPayment: (options: {
-        params: CheckoutPaymentOptions;
-    }) => Promise<CheckoutPaymentResult>;
-    /** Storage */
-    getStorageItem: (params: {
-        key: string;
-    }) => Promise<string | null>;
-    setStorageItem: (params: {
-        key: string;
-        value: string;
-    }) => Promise<void>;
-    removeStorageItem: (params: {
-        key: string;
-    }) => Promise<void>;
-    clearStorage: (arg: CompatiblePlaceholderArgument) => Promise<void>;
-    eventLog: (params: {
-        log_name: string;
-        log_type: 'debug' | 'info' | 'warn' | 'error' | 'event' | 'screen' | 'impression' | 'click';
-        params: Record<string, string>;
-    }) => Promise<void>;
-    getTossShareLink: (params: object) => Promise<{
-        shareLink: string;
-    }>;
-    setDeviceOrientation: (options: {
-        type: 'portrait' | 'landscape';
-    }) => Promise<void>;
-    saveBase64Data: (params: SaveBase64DataParams) => Promise<void>;
-    /** IAP */
-    iapGetProductItemList: (arg: CompatiblePlaceholderArgument) => Promise<{
-        products: IapProductListItem[];
-    }>;
-    /** @deprecated `requestOneTimePurchase`를 사용해주세요. */
-    iapCreateOneTimePurchaseOrder: (params: {
-        productId: string;
-    }) => Promise<IapCreateOneTimePurchaseOrderResult>;
-    requestOneTimePurchase: (params: {
-        sku: string;
-    }, fallbacks: {
-        onPurchased: (params: {
-            orderId: string;
-        }) => void;
-    }) => () => void;
-    requestSubscriptionPurchase: (params: {
-        sku: string;
-        offerId: string | null;
-    }, fallbacks: {
-        onPurchased: (params: {
-            orderId: string;
-            subscriptionId?: string;
-        }) => void;
-    }) => () => void;
-    processProductGrant: (params: {
-        orderId: string;
-        isProductGranted: boolean;
-    }) => Promise<void>;
-    getPendingOrders: (params: CompatiblePlaceholderArgument) => Promise<{
-        orders: {
-            orderId: string;
-            sku: string;
-            paymentCompletedDate: string;
-        }[];
-    }>;
-    getCompletedOrRefundedOrders: (params: {
-        key?: string | null;
-    }) => Promise<CompletedOrRefundedOrdersResult>;
-    completeProductGrant: (params: {
-        params: {
-            orderId: string;
-        };
-    }) => Promise<boolean>;
-    getGameCenterGameProfile: (params: CompatiblePlaceholderArgument) => Promise<GameCenterGameProfileResponse>;
-    getUserKeyForGame: (params: CompatiblePlaceholderArgument) => Promise<GetUserKeyForGameResponse>;
-    getIsTossLoginIntegratedService: (params: CompatiblePlaceholderArgument) => Promise<boolean>;
-    grantPromotionRewardForGame: (params: {
-        params: {
-            promotionCode: string;
-            amount: number;
-        };
-    }) => Promise<GrantPromotionRewardForGameResponse>;
-    submitGameCenterLeaderBoardScore: (params: {
-        score: string;
-    }) => Promise<SubmitGameCenterLeaderBoardScoreResponse>;
-    contactsViral: (params: ContactsViralParams) => () => void;
-    /** 토스인증 */
-    appsInTossSignTossCert: (params: {
-        params: AppsInTossSignTossCertParams;
-    }) => void;
-    getServerTime: (arg: CompatiblePlaceholderArgument) => Promise<{
-        serverTime: number;
-    }>;
+ * @public
+ * @category 광고
+ * @name showAppsInTossAdMob
+ * @description 이 함수는 `loadAppsInTossAdMob` 로 광고가 잘 불러와졌는지 확인해요.
+ * @param {string} params.adUnitId 광고 그룹 단위 ID예요.
+ * @property {() => boolean} [isSupported] 현재 실행 중인 앱(예: 토스 앱, 개발용 샌드박스 앱 등)에서 `isAppsInTossAdMobLoaded` 를 지원하는지 확인하는 함수예요. 기능을 사용하기 전에 지원 여부를 확인해야 해요.
+ */
+declare function isAppsInTossAdMobLoaded(params: IsAdMobLoadedOptions): Promise<boolean>;
+declare namespace isAppsInTossAdMobLoaded {
+    var isSupported: typeof isAppsInTossAdMobLoadedSupported;
 }
-declare const AppsInTossModuleInstance: any;
-declare const AppsInTossModule: Spec;
+declare function isAppsInTossAdMobLoadedSupported(): boolean;
 
 /**
  * @public
@@ -2343,34 +2374,30 @@ declare function getTossAppVersion(): string;
  * @kind function
  * @name getTossShareLink
  * @description
- * 사용자가 지정한 경로를 토스 앱에서 열 수 있는 공유 링크를 생성해요.
+ * `getTossShareLink` 함수는 사용자가 지정한 경로를 토스 앱에서 열 수 있는 공유 링크를 반환해요.
+ * 이 링크를 다른 사람과 공유하면 토스 앱이 실행되면서 지정한 경로로 진입해요. 토스앱이 없는 사람은 iOS 일 때는 앱스토어로 이동하고, Android 일 때는 플레이스토어로 이동해요.
+ *
+ * 경로는 토스 앱 내부 특정 화면을 나타내는 딥링크(deep link) 형식이어야 해요.
+ * 예를 들어 `intoss://<앱 이름>`이나 `intoss://<앱 이름>/about?name=test`처럼 작성해요.
  *
- * 생성된 링크를 다른 사람과 공유하면:
- * - 토스 앱이 설치되어 있으면: 토스 앱이 실행되면서 지정한 경로로 이동해요.
- * - 토스 앱이 없으면: iOS는 앱스토어로, Android는 플레이스토어로 이동해요.
+ * 이 함수를 사용하면 `deep_link_value`를 포함한 완성된 공유 링크를 만들 수 있어요.
  *
- * @param path - 딥링크 경로예요. `intoss://`로 시작하는 문자열이어야 해요. (예: `intoss://my-app`, `intoss://my-app/detail?id=123`)
- * @param ogImageUrl - (선택) 공유 시 표시될 커스텀 OG 이미지 URL이에요. 최소 버전: Android 5.240.0, iOS 5.239.0
- * @returns {Promise<string>} 생성된 토스 공유 링크
+ * @param path - 딥링크로 열고 싶은 경로예요. `intoss://`로 시작하는 문자열이어야 해요.
+ * @returns {Promise<string>} `deep_link_value`가 포함된 토스 공유 링크를 반환해요.
  *
  * @example
  * ```tsx
  * import { share } from '@granite-js/react-native';
  * import { getTossShareLink } from '@apps-in-toss/framework';
  *
- * // 기본 사용법
+ * // '/' 경로를 딥링크로 포함한 토스 공유 링크를 생성해요.
  * const tossLink = await getTossShareLink('intoss://my-app');
- * await share({ message: tossLink });
  *
- * // 커스텀 OG 이미지와 함께 사용
- * const linkWithImage = await getTossShareLink(
- *   'intoss://my-app/event',
- *   'https://example.com/og-image.png'
- * );
- * await share({ message: linkWithImage });
+ * // 생성한 링크를 메시지로 공유해요.
+ * await share({ message: tossLink });
  * ```
  */
-declare function getTossShareLink(path: string, ogImageUrl?: string): Promise<string>;
+declare function getTossShareLink(path: string): Promise<string>;
 
 /**
  * @public
@@ -2636,6 +2663,45 @@ declare function openGameCenterLeaderboard(): Promise<void>;
  */
 declare function getIsTossLoginIntegratedService(): Promise<boolean | undefined>;
 
+/**
+ * @public
+ * @category Constants
+ * @name getGroupId
+ * @description 앱인토스에서 제공하는 그룹 ID를 가져와요.
+ * @returns {string} 그룹 ID
+ *
+ * @example
+ * ```typescript
+ * import { getGroupId } from '@apps-in-toss/native-modules';
+ *
+ * const groupId = getGroupId();
+ * console.log('Group ID:', groupId);
+ * ```
+ */
+declare function getGroupId(): string;
+
+/**
+ * @public
+ * @category 공유
+ * @kind function
+ * @name shareWithScheme
+ * @description
+ * `shareWithScheme` 함수는 지정한 스킴 URL을 다른 앱과 공유해요.
+ *
+ * @param params - 공유할 스킴 URL 정보
+ * @param params.schemeURL - 공유할 스킴 URL
+ *
+ * @example
+ * ```tsx
+ * import { shareWithScheme } from '@apps-in-toss/native-modules';
+ *
+ * shareWithScheme({ schemeURL: 'intoss://my-app?referrer=share' });
+ * ```
+ */
+declare function shareWithScheme(params: {
+    schemeURL: string;
+}): void;
+
 /**
  * @public
  * @category 시간
@@ -2682,6 +2748,7 @@ declare namespace getServerTime {
 declare const TossPay: {
     checkoutPayment: typeof checkoutPayment;
 };
+
 /**
  * @public
  * @category 광고
@@ -3118,48 +3185,14 @@ declare function openURL(url: string): Promise<any>;
  */
 declare function getPlatformOS(): 'ios' | 'android';
 
-interface BedrockModule {
-    closeView: () => void;
-    generateHapticFeedback: (options: HapticFeedbackOptions) => Promise<void>;
-    share: (message: {
-        message: string;
-    }) => void;
-    setSecureScreen: (options: {
-        enabled: boolean;
-    }) => Promise<{
-        enabled: boolean;
-    }>;
-    setScreenAwakeMode: (options: {
-        enabled: boolean;
-    }) => Promise<{
-        enabled: boolean;
-    }>;
-    getNetworkStatus: () => Promise<NetworkStatus>;
-    setIosSwipeGestureEnabled: ({ isEnabled }: {
-        isEnabled: boolean;
-    }) => Promise<void>;
-    deviceId: string;
-    DeviceInfo: {
-        locale: string;
-    };
-    schemeUri: string;
-}
-declare const BedrockModule: BedrockModule;
-
-interface BedrockCoreModule {
-    addListener: (eventType: string) => void;
-    removeListeners: (count: number) => void;
-}
-declare const BedrockCoreModule: BedrockCoreModule;
-
 declare function tossCoreEventLog(params: {
     log_name: string;
     log_type: string;
     params: Record<string, unknown>;
-}): void;
+}): Promise<void> | undefined;
 
 declare const INTERNAL__module: {
     tossCoreEventLog: typeof tossCoreEventLog;
 };
 
-export { AppsInTossModule, type AppsInTossSignTossCertParams, BedrockCoreModule, BedrockModule, type CheckoutPaymentOptions, type CheckoutPaymentResult, type CompletedOrRefundedOrdersResult, type ConsumableProductListItem, type ContactsViralParams, type CreateSubscriptionPurchaseOrderOptions, type EventLogParams, type GameCenterGameProfileResponse, type GetUserKeyForGameErrorResponse, type GetUserKeyForGameResponse, type GetUserKeyForGameSuccessResponse, GoogleAdMob, type GrantPromotionRewardForGameErrorResponse, type GrantPromotionRewardForGameErrorResult, type GrantPromotionRewardForGameResponse, type GrantPromotionRewardForGameSuccessResponse, type HapticFeedbackType, IAP, AppsInTossModuleInstance as INTERNAL__AppsInTossModule, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapCreateSubscriptionPurchaseOrderResult, type IapProductListItem, type NetworkStatus, type NonConsumableProductListItem, type Primitive, type SaveBase64DataParams, Storage, type SubmitGameCenterLeaderBoardScoreResponse, type SubscriptionProductListItem, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, appsInTossSignTossCert, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getIsTossLoginIntegratedService, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getServerTime, getTossAppVersion, getTossShareLink, getUserKeyForGame, grantPromotionRewardForGame, iapCreateOneTimePurchaseOrder, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, processProductGrant, requestOneTimePurchase, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, startUpdateLocation, submitGameCenterLeaderBoardScore };
+export { type AppsInTossSignTossCertParams, type CheckoutPaymentOptions, type CheckoutPaymentResult, type CompletedOrRefundedOrdersResult, type ConsumableProductListItem, type ContactsViralParams, type CreateSubscriptionPurchaseOrderOptions, type EventLogParams, type GameCenterGameProfileResponse, type GetUserKeyForGameErrorResponse, type GetUserKeyForGameResponse, type GetUserKeyForGameSuccessResponse, GoogleAdMob, type GrantPromotionRewardForGameErrorResponse, type GrantPromotionRewardForGameErrorResult, type GrantPromotionRewardForGameResponse, type GrantPromotionRewardForGameSuccessResponse, type HapticFeedbackType, IAP, INTERNAL__appBridgeHandler, INTERNAL__module, type IapCreateOneTimePurchaseOrderOptions, type IapCreateOneTimePurchaseOrderResult, type IapCreateSubscriptionPurchaseOrderResult, type IapProductListItem, type NetworkStatus, type NonConsumableProductListItem, type Primitive, type SaveBase64DataParams, Storage, type SubmitGameCenterLeaderBoardScoreResponse, type SubscriptionProductListItem, TossPay, type UpdateLocationEventEmitter, appLogin, appsInTossEvent, appsInTossSignTossCert, checkoutPayment, closeView, contactsViral, eventLog, fetchAlbumPhotos, fetchContacts, generateHapticFeedback, getClipboardText, getCurrentLocation, getDeviceId, getGameCenterGameProfile, getGroupId, getIsTossLoginIntegratedService, getLocale, getNetworkStatus, getOperationalEnvironment, getPlatformOS, getSchemeUri, getServerTime, getTossAppVersion, getTossShareLink, getUserKeyForGame, grantPromotionRewardForGame, iapCreateOneTimePurchaseOrder, isMinVersionSupported, onVisibilityChangedByTransparentServiceWeb, openCamera, openGameCenterLeaderboard, openURL, processProductGrant, requestOneTimePurchase, safePostMessage, safeSyncPostMessage, saveBase64Data, setClipboardText, setDeviceOrientation, setIosSwipeGestureEnabled, setScreenAwakeMode, setSecureScreen, share, shareWithScheme, startUpdateLocation, submitGameCenterLeaderBoardScore };