tudada-sdk-types 0.0.1-2

package/README.md

@@ -0,0 +1,150 @@
+# tudada-sdk-types
+
+TypeScript type definitions for TudadaSDK - H5 web game SDK for Tudada platform.
+
+## Installation
+
+```bash
+npm install tudada-sdk-types
+```
+
+## Usage
+
+### Global Types (Recommended)
+
+After installing `tudada-sdk-types`, global types are **automatically available** without any import:
+
+```typescript
+// No import needed! Types are automatically recognized
+TudadaSDK.login({
+  success: (res) => console.log('Login code:', res.code),
+  fail: (err) => console.error('Login failed:', err.errMsg),
+});
+
+const systemInfo = TudadaSDK.getSystemInfoSync();
+console.log('Platform:', systemInfo.platform);
+```
+
+This works because the package includes `global.d.ts` which declares the global `TudadaSDK` and `tudadaSDK` variables.
+
+### Import Types
+
+You can also import types directly:
+
+```typescript
+import type {
+  LoginOption,
+  LoginSuccessResult,
+  SystemInfo,
+  UserInfo,
+  RewardedVideoAd,
+} from 'tudada-sdk-types';
+
+// Use types in your code
+const handleLogin = (options: LoginOption) => {
+  TudadaSDK.login(options);
+};
+
+const systemInfo: SystemInfo = TudadaSDK.getSystemInfoSync();
+```
+
+## Available Types
+
+### Auth API
+- `LoginOption`, `LoginSuccessResult`
+- `CheckSessionOption`
+- `GetUserInfoOption`, `GetUserInfoSuccessResult`, `UserInfo`
+
+### Storage API
+- `SetStorageOption`, `GetStorageOption`, `GetStorageSuccessResult`
+- `RemoveStorageOption`, `ClearStorageOption`
+- `StorageInfo`
+- `TudadaStore`, `TudadaStoreGetOption`, `TudadaStoreSaveOption`
+
+### System API
+- `SystemInfo`, `GetSystemInfoOption`
+- `WindowInfo`, `GetWindowInfoOption`
+- `AppBaseInfo`, `GetAppBaseInfoOption`
+- `DeviceInfo`, `GetDeviceInfoOption`
+- `Platform`, `SafeArea`
+
+### UI API
+- `MenuButtonBoundingClientRect`
+
+### Device API
+- `VibrateShortOption`, `VibrateLongOption`, `VibrateType`
+- `ShowKeyboardOption`, `HideKeyboardOption`
+- `OnKeyboardInputCallback`, `OnKeyboardConfirmCallback`, `OnKeyboardCompleteCallback`
+
+### Clipboard API
+- `SetClipboardDataOption`
+- `GetClipboardDataOption`, `GetClipboardDataSuccessResult`
+
+### Ad API
+- `CreateRewardedVideoAdOption`
+- `RewardedVideoAd`
+
+### Lifecycle API
+- `OnShowCallback`, `OnShowCallbackResult`
+- `OnHideCallback`, `OnHideCallbackResult`
+- `ExitMiniProgramOption`, `RestartMiniProgramOption`
+
+### SDK Interface
+- `ITudadaSDK` - Main SDK interface
+
+### Common Types
+- `GeneralCallbackResult`
+- `Mock<T>`
+
+## Global Variables
+
+When TudadaSDK is loaded via script tag, the following global variables are available:
+
+- `TudadaSDK` / `tudadaSDK` - Main SDK instance
+- `window.TudadaSDK` / `window.tudadaSDK`
+
+## Example
+
+```typescript
+import type { SystemInfo, UserInfo, RewardedVideoAd } from 'tudada-sdk-types';
+
+// Get system info
+const systemInfo: SystemInfo = TudadaSDK.getSystemInfoSync();
+console.log('Platform:', systemInfo.platform);
+console.log('Screen size:', systemInfo.screenWidth, 'x', systemInfo.screenHeight);
+
+// Login
+TudadaSDK.login({
+  success: (res) => {
+    console.log('Login code:', res.code);
+
+    // Get user info
+    TudadaSDK.getUserInfo({
+      success: (userRes) => {
+        const user: UserInfo = userRes.userInfo;
+        console.log('Nickname:', user.nickName);
+        console.log('Avatar:', user.avatarUrl);
+      },
+    });
+  },
+});
+
+// Create rewarded video ad
+const ad: RewardedVideoAd = TudadaSDK.createRewardedVideoAd({
+  adUnitId: 'your-ad-unit-id',
+});
+
+ad.onLoad(() => console.log('Ad loaded'));
+ad.onError((err) => console.error('Ad error:', err.errMsg));
+ad.onClose((res) => {
+  if (res.isEnded) {
+    console.log('Ad completed - give reward!');
+  }
+});
+
+ad.load().then(() => ad.show());
+```
+
+## License
+
+MIT

package/global.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TudadaSDK 글로벌 타입 선언
+ *
+ * 이 파일은 import 없이도 TudadaSDK 글로벌 변수의 타입을 자동으로 인식하게 합니다.
+ * npm install tudada-sdk-types 후 별도 설정 없이 바로 사용 가능합니다.
+ *
+ * @example
+ * ```typescript
+ * // import 없이 바로 사용 가능
+ * TudadaSDK.login({
+ *   success: (res) => console.log('Login code:', res.code),
+ *   fail: (err) => console.error('Login failed:', err.errMsg),
+ * });
+ *
+ * const systemInfo = TudadaSDK.getSystemInfoSync();
+ * console.log('Platform:', systemInfo.platform);
+ * ```
+ */
+
+/// <reference path="./index.d.ts" />
+
+declare const TudadaSDK: import('./index').ITudadaSDK;
+declare const tudadaSDK: import('./index').ITudadaSDK;
+
+interface Window {
+    TudadaSDK: import('./index').ITudadaSDK;
+    tudadaSDK: import('./index').ITudadaSDK;
+}

package/index.d.ts

@@ -0,0 +1,1175 @@
+/**
+ * TudadaSDK - H5 웹 게임을 위한 투다다 서비스 연동 SDK
+ *
+ * @description
+ * H5/웹 브라우저 환경에서 게임과 투다다(Tudada) 서비스를 연결하기 위한 SDK입니다.
+ * WeChat Mini Game(wx) API와 호환되는 인터페이스를 제공합니다.
+ *
+ * ## 지원 API
+ *
+ * - **Storage**: 로컬 스토리지 (setStorage, getStorage, removeStorage, clearStorage)
+ * - **System**: 시스템/디바이스 정보 (getSystemInfo, getWindowInfo, getDeviceInfo)
+ * - **Auth**: 로그인/세션 (login, checkSession)
+ * - **UI**: UI 정보 (getMenuButtonBoundingClientRect)
+ * - **Device**: 디바이스 제어 (vibrateShort, vibrateLong, showKeyboard, hideKeyboard, onKeyboardInput, offKeyboardInput, onKeyboardConfirm, offKeyboardConfirm, onKeyboardComplete, offKeyboardComplete)
+ * - **Clipboard**: 클립보드 (setClipboardData, getClipboardData)
+ * - **Ad**: 광고 (createRewardedVideoAd)
+ * - **Lifecycle**: 앱 라이프사이클 (onShow, onHide, exitMiniProgram, restartMiniProgram)
+ *
+ * ## 설치
+ *
+ * tudada-game-sdk는 CDN을 통해 배포됩니다. HTML 파일에 스크립트 태그로 불러오세요.
+ *
+ * ```html
+ * <!-- CDN으로 SDK 로드 -->
+ * <script src="https://your-cdn-url.com/tudadaGameSDK.js"></script>
+ * ```
+ *
+ * ## 사용법
+ *
+ * **⚠️ 중요**: SDK는 스크립트 로드 시 자동으로 초기화됩니다.
+ * 게임 코드는 반드시 `TudadaGameSDK.waitForReady()` 완료를 기다린 후에 실행되어야 합니다.
+ *
+ * ### 기본 사용법 (SDK 초기화 대기 후 게임 로드)
+ *
+ * ```html
+ * <!DOCTYPE html>
+ * <html>
+ * <body>
+ *   <!-- 1. SDK 먼저 로드 (자동으로 초기화됨) -->
+ *   <script src="https://your-cdn-url.com/tudadaGameSDK.js"></script>
+ *
+ *   <!-- 2. SDK 초기화 대기 후 게임 로드 -->
+ *   <script>
+ *     TudadaGameSDK.waitForReady()
+ *       .then(() => {
+ *         console.log('SDK 초기화 완료');
+ *
+ *         // 초기화 완료 후 게임 스크립트 동적 로드
+ *         const gameScript = document.createElement('script');
+ *         gameScript.src = './game.js';
+ *         document.body.appendChild(gameScript);
+ *       })
+ *       .catch((error) => {
+ *         console.error('SDK 초기화 실패:', error);
+ *       });
+ *   </script>
+ * </body>
+ * </html>
+ * ```
+ *
+ * ### API 사용 예시 (game.js 내부)
+ *
+ * ```javascript
+ * // SDK 초기화 완료 후 실행되는 게임 코드
+ *
+ * // Storage API
+ * TudadaSDK.setStorageSync('score', 100);
+ * const score = TudadaSDK.getStorageSync('score');
+ *
+ * // System API
+ * const systemInfo = TudadaSDK.getSystemInfoSync();
+ * console.log('플랫폼:', systemInfo.platform);
+ *
+ * // Ad API
+ * const ad = TudadaSDK.createRewardedVideoAd({ adUnitId: 'your-ad-unit-id' });
+ * ad.onClose((res) => {
+ *   if (res.isEnded) console.log('보상 지급!');
+ * });
+ * ad.load().then(() => ad.show());
+ * ```
+ *
+ * ### Unity WebGL 게임 예시
+ *
+ * ```html
+ * <body>
+ *   <canvas id="unity-canvas"></canvas>
+ *   <script src="https://your-cdn-url.com/tudadaGameSDK.js"></script>
+ *
+ *   <script>
+ *     TudadaGameSDK.waitForReady()
+ *       .then(() => {
+ *         console.log('✅ SDK 초기화 완료');
+ *
+ *         // Unity 로더 동적 로드
+ *         const unityLoader = document.createElement('script');
+ *         unityLoader.src = './Build/UnityLoader.js';
+ *         unityLoader.onload = () => {
+ *           createUnityInstance(document.querySelector("#unity-canvas"), {
+ *             dataUrl: "./Build/webgl.data",
+ *             frameworkUrl: "./Build/webgl.framework.js",
+ *             codeUrl: "./Build/webgl.wasm",
+ *           })
+ *             .then((unityInstance) => {
+ *               console.log('✅ Unity 게임 로드 완료');
+ *
+ *               // Unity 인스턴스를 SDK에 연결
+ *               TudadaGameSDK.connectUnity(unityInstance);
+ *               console.log('✅ Unity 인스턴스 연결 완료');
+ *             });
+ *         };
+ *         document.body.appendChild(unityLoader);
+ *       })
+ *       .catch((error) => {
+ *         console.error('❌ SDK 초기화 실패:', error);
+ *       });
+ *   </script>
+ * </body>
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// ============================================
+// 공통 타입
+// ============================================
+
+/** API 호환을 위해 남겨둔 필드 (고정값 반환) */
+export type Mock<T> = T;
+
+/** 일반 콜백 결과 */
+export interface GeneralCallbackResult {
+    /** 에러 메시지 */
+    errMsg: string;
+    /** 에러 코드 */
+    errCode?: number;
+}
+
+// ============================================
+// Storage API 타입
+// ============================================
+
+/** 스토리지 설정 옵션 */
+export interface SetStorageOption {
+    /** 스토리지 키 */
+    key: string;
+    /**
+     * 저장할 데이터
+     *
+     * JSON으로 직렬화 가능한 데이터만 지원됩니다.
+     * `Blob`, `File`, `Map`, `Set` 등 JSON.stringify()로 직렬화할 수 없는 타입은
+     * 데이터가 손실되거나 에러가 발생할 수 있습니다.
+     */
+    data: any;
+    /** 암호화 사용 여부 (미지원) */
+    encrypt?: boolean;
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/** 스토리지 조회 결과 */
+export interface GetStorageSuccessResult {
+    /** 에러 메시지 */
+    errMsg: string;
+    /** 에러 코드 */
+    errCode?: number;
+    /** 조회된 데이터 */
+    data: any;
+}
+
+/** 스토리지 조회 옵션 */
+export interface GetStorageOption {
+    /** 스토리지 키 */
+    key: string;
+    /** 암호화 사용 여부 (미지원) */
+    encrypt?: boolean;
+    /** 성공 콜백 */
+    success?: (res: GetStorageSuccessResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GetStorageSuccessResult | GeneralCallbackResult) => void;
+}
+
+/** 스토리지 삭제 옵션 */
+export interface RemoveStorageOption {
+    /** 스토리지 키 */
+    key: string;
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/** 스토리지 전체 삭제 옵션 */
+export interface ClearStorageOption {
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/**
+ * 스토리지 정보
+ *
+ * getStorageInfoSync() 함수의 반환 타입입니다.
+ */
+export interface StorageInfo {
+    /** 저장된 모든 키 목록 (접두사 제외) */
+    keys: string[];
+    /** 현재 사용 용량 (KB 단위) */
+    currentSize: number;
+    /** 최대 용량 (KB 단위, 10240KB = 10MB) */
+    limitSize: number;
+}
+
+// ============================================
+// TudadaStore API 타입
+// ============================================
+
+/** TudadaStore get 성공 결과 */
+export interface TudadaStoreGetSuccessResult {
+    /** 에러 메시지 */
+    errMsg: string;
+    /** 조회된 값 (없으면 null) */
+    value: string | null;
+}
+
+/** TudadaStore get 옵션 */
+export interface TudadaStoreGetOption {
+    /** 조회할 키 */
+    key: string;
+    /** 성공 콜백 */
+    success?: (res: TudadaStoreGetSuccessResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: TudadaStoreGetSuccessResult | GeneralCallbackResult) => void;
+}
+
+/**
+ * TudadaStore save 옵션
+ *
+ * ## 용량 제한
+ * - value 최대 크기: **2KB**
+ * - 2KB를 초과하면 fail 콜백이 호출됩니다.
+ * - 에러 메시지: `tudadaStore.save:fail value exceeds maximum size limit (2KB)`
+ */
+export interface TudadaStoreSaveOption {
+    /** 저장할 키 */
+    key: string;
+    /**
+     * 저장할 값
+     *
+     * @remarks
+     * 최대 2KB까지 저장 가능합니다.
+     * 용량을 초과하면 fail 콜백이 호출됩니다.
+     */
+    value: string;
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/** TudadaStore 인터페이스 */
+export interface TudadaStore {
+    /**
+     * 키로 값 조회
+     *
+     * @param options - 조회 옵션
+     *
+     * @example
+     * ```typescript
+     * const store = getTudadaStore();
+     * store.get({
+     *   key: 'userScore',
+     *   success: (res) => {
+     *     console.log('Value:', res.value); // null 또는 string
+     *   },
+     *   fail: (err) => console.error('Failed:', err.errMsg),
+     * });
+     * ```
+     */
+    get(options: TudadaStoreGetOption): void;
+
+    /**
+     * 키와 값 저장
+     *
+     * ## 용량 제한
+     * value는 최대 **2KB**까지 저장 가능합니다.
+     * 초과 시 fail 콜백이 호출됩니다.
+     *
+     * @param options - 저장 옵션
+     *
+     * @example
+     * ```typescript
+     * const store = getTudadaStore();
+     * store.save({
+     *   key: 'userScore',
+     *   value: '1000',
+     *   success: () => console.log('Saved successfully'),
+     *   fail: (err) => console.error('Failed:', err.errMsg),
+     * });
+     * ```
+     */
+    save(options: TudadaStoreSaveOption): void;
+}
+
+// ============================================
+// Device API 타입
+// ============================================
+
+/**
+ * 진동 강도 타입
+ *
+ * @remarks
+ * 현재는 플랫폼에서 지원하지 않지만, 향후 확장을 위해 파라미터로 받을 수 있습니다.
+ * - `heavy`: 강한 진동
+ * - `medium`: 중간 진동 (기본값)
+ * - `light`: 약한 진동
+ *
+ * @defaultValue 'medium'
+ */
+export type VibrateType = 'heavy' | 'medium' | 'light';
+
+/**
+ * vibrateShort 옵션
+ *
+ * 짧은 진동(15ms)을 실행하기 위한 옵션입니다.
+ */
+export interface VibrateShortOption {
+    /**
+     * 진동 강도 타입
+     *
+     * @remarks
+     * 현재는 플랫폼에서 지원하지 않지만, 파라미터로 받을 수 있습니다.
+     * 향후 플랫폼 업데이트 시 지원될 예정입니다.
+     *
+     * @defaultValue 'medium'
+     */
+    type?: VibrateType;
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/**
+ * vibrateLong 옵션
+ *
+ * 긴 진동(400ms)을 실행하기 위한 옵션입니다.
+ */
+export interface VibrateLongOption {
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/**
+ * showKeyboard 옵션
+ *
+ * 키보드를 표시하기 위한 옵션입니다.
+ */
+export interface ShowKeyboardOption {
+    /** 키보드 입력 필드의 기본값 */
+    defaultValue?: string;
+    /** 키보드 텍스트의 최대 길이 */
+    maxLength?: number;
+    /** 여러 줄 입력 여부 */
+    multiple?: boolean;
+    /** 완료 버튼 클릭 시 키보드 유지 여부 */
+    confirmHold?: boolean;
+    /** 키보드 우측 하단 버튼 텍스트 */
+    confirmType?: 'done' | 'next' | 'search' | 'go' | 'send';
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/**
+ * hideKeyboard 옵션
+ *
+ * 키보드를 숨기기 위한 옵션입니다.
+ */
+export interface HideKeyboardOption {
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/**
+ * 키보드 입력 이벤트 결과
+ */
+export interface OnKeyboardInputCallbackResult {
+    /** 키보드 입력의 현재 값 */
+    value: string;
+}
+
+/**
+ * 키보드 입력 이벤트 콜백
+ */
+export type OnKeyboardInputCallback = (res: OnKeyboardInputCallbackResult) => void;
+
+/**
+ * 키보드 확인 버튼 클릭 이벤트 결과
+ */
+export interface OnKeyboardConfirmCallbackResult {
+    /** 키보드 입력의 현재 값 */
+    value: string;
+}
+
+/**
+ * 키보드 확인 버튼 클릭 이벤트 콜백
+ */
+export type OnKeyboardConfirmCallback = (res: OnKeyboardConfirmCallbackResult) => void;
+
+/**
+ * 키보드 입력 완료 이벤트 결과
+ */
+export interface OnKeyboardCompleteCallbackResult {
+    /** 키보드 입력의 현재 값 */
+    value: string;
+}
+
+/**
+ * 키보드 입력 완료 이벤트 콜백
+ */
+export type OnKeyboardCompleteCallback = (res: OnKeyboardCompleteCallbackResult) => void;
+
+// ============================================
+// Clipboard API 타입
+// ============================================
+
+/**
+ * setClipboardData 옵션
+ *
+ * 클립보드에 데이터를 저장하기 위한 옵션입니다.
+ */
+export interface SetClipboardDataOption {
+    /** 클립보드에 저장할 데이터 */
+    data: string;
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/**
+ * getClipboardData 성공 결과
+ */
+export interface GetClipboardDataSuccessResult {
+    /** 에러 메시지 */
+    errMsg: string;
+    /** 에러 코드 */
+    errCode?: number;
+    /** 클립보드의 데이터 */
+    data: string;
+}
+
+/**
+ * getClipboardData 옵션
+ *
+ * 클립보드에서 데이터를 가져오기 위한 옵션입니다.
+ */
+export interface GetClipboardDataOption {
+    /** 성공 콜백 */
+    success?: (res: GetClipboardDataSuccessResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GetClipboardDataSuccessResult | GeneralCallbackResult) => void;
+}
+
+// ============================================
+// System API 타입
+// ============================================
+
+/** 플랫폼 타입 */
+export type Platform = 'ios' | 'android' | 'windows' | 'mac' | 'devtools';
+
+/** 안전 영역 정보 */
+export interface SafeArea {
+    /** 안전 영역 좌상단 X 좌표 */
+    left: number;
+    /** 안전 영역 우하단 X 좌표 */
+    right: number;
+    /** 안전 영역 좌상단 Y 좌표 */
+    top: number;
+    /** 안전 영역 우하단 Y 좌표 */
+    bottom: number;
+    /** 안전 영역 너비 (논리 픽셀) */
+    width: number;
+    /** 안전 영역 높이 (논리 픽셀) */
+    height: number;
+}
+
+
+/** 시스템 정보 */
+export interface SystemInfo {
+    /** 기초 라이브러리 버전 */
+    SDKVersion: string;
+    /** Tudada 서비스 버전 */
+    version: string;
+    /** 디버그 모드 활성화 여부 - 호환용 */
+    enableDebug: boolean;
+    /** 사용자 글꼴 크기 설정 (px) - 호환용 */
+    fontSizeSetting: Mock<16>;
+    /** 호스트 앱 정보 */
+    host: { appId: string };
+    /** 디바이스 픽셀 비율 */
+    pixelRatio: number;
+    /** 화면 너비 (px) */
+    screenWidth: number;
+    /** 화면 높이 (px) */
+    screenHeight: number;
+    /** 사용 가능한 창 너비 (px) */
+    windowWidth: number;
+    /** 사용 가능한 창 높이 (px) */
+    windowHeight: number;
+    /** 상태바 높이 (px) - 호환용 */
+    statusBarHeight: number;
+    /** 안전 영역 정보 */
+    safeArea: SafeArea;
+    /** 디바이스 브랜드 */
+    brand: string;
+    /** 디바이스 모델 */
+    model: string;
+    /** OS 및 버전 */
+    system: string;
+    /** 디바이스 성능 등급 (Android 전용) */
+    benchmarkLevel: number;
+    /** 언어 설정 */
+    language: string;
+    /** 테마 (light/dark) */
+    theme: 'light' | 'dark';
+    /** 디바이스 방향 */
+    deviceOrientation: 'portrait' | 'landscape';
+    /** 플랫폼 */
+    platform: Platform;
+    /** 앨범 접근 권한 (iOS 전용) - 호환용 */
+    albumAuthorized: Mock<false>;
+    /** 카메라 접근 권한 - 호환용 */
+    cameraAuthorized: Mock<false>;
+    /** 위치 정보 접근 권한 - 호환용 */
+    locationAuthorized: Mock<false>;
+    /** 마이크 접근 권한 - 호환용 */
+    microphoneAuthorized: Mock<false>;
+    /** 알림 권한 - 호환용 */
+    notificationAuthorized: Mock<false>;
+    /** 알림 알림창 권한 (iOS 전용) - 호환용 */
+    notificationAlertAuthorized: Mock<false>;
+    /** 알림 뱃지 권한 (iOS 전용) - 호환용 */
+    notificationBadgeAuthorized: Mock<false>;
+    /** 알림 소리 권한 (iOS 전용) - 호환용 */
+    notificationSoundAuthorized: Mock<false>;
+    /** 캘린더 접근 권한 - 호환용 */
+    phoneCalendarAuthorized: Mock<false>;
+    /** 블루투스 활성화 상태 - 호환용 */
+    bluetoothEnabled: Mock<false>;
+    /** 위치 서비스 활성화 상태 - 호환용 */
+    locationEnabled: Mock<false>;
+    /** Wi-Fi 활성화 상태 - 호환용 */
+    wifiEnabled: Mock<false>;
+    /** 정밀도 낮은 위치 사용 여부 - 호환용 */
+    locationReducedAccuracy?: Mock<false>;
+}
+
+/** getSystemInfo 옵션 */
+export interface GetSystemInfoOption {
+    /** 성공 콜백 */
+    success?: (res: SystemInfo & GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: (SystemInfo & GeneralCallbackResult) | GeneralCallbackResult) => void;
+}
+
+/** 창 정보 */
+export interface WindowInfo {
+    /** 디바이스 픽셀 비율 */
+    pixelRatio: number;
+    /** 화면 너비 (px) */
+    screenWidth: number;
+    /** 화면 높이 (px) */
+    screenHeight: number;
+    /** 사용 가능한 창 너비 (px) */
+    windowWidth: number;
+    /** 사용 가능한 창 높이 (px) */
+    windowHeight: number;
+    /** 상태바 높이 (px) - 호환용 */
+    statusBarHeight: number;
+    /** 안전 영역 정보 */
+    safeArea: SafeArea;
+    /** 창 상단 Y 값 */
+    screenTop: number;
+}
+
+/** getWindowInfo 옵션 */
+export interface GetWindowInfoOption {
+    /** 성공 콜백 */
+    success?: (res: WindowInfo & GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: (WindowInfo & GeneralCallbackResult) | GeneralCallbackResult) => void;
+}
+
+/** 앱 기본 정보 */
+export interface AppBaseInfo {
+    /** 기초 라이브러리 버전 */
+    SDKVersion: string;
+    /** Tudada 서비스 버전 */
+    version: string;
+    /** 디버그 모드 활성화 여부 - 호환용 */
+    enableDebug: boolean;
+    /** 사용자 글꼴 크기 설정 (px) - 호환용 */
+    fontSizeSetting: Mock<16>;
+    /** 호스트 앱 정보 */
+    host: { appId: string };
+    /** 글꼴 크기 확대 비율 - 호환용 */
+    fontSizeScaleFactor: Mock<1>;
+    /** 사용자 설정 언어 - 호환용 */
+    language: Mock<'KO'>;
+    /** 테마 설정 */
+    theme?: 'light' | 'dark';
+}
+
+/** getAppBaseInfo 옵션 */
+export interface GetAppBaseInfoOption {
+    /** 성공 콜백 */
+    success?: (res: AppBaseInfo & GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: (AppBaseInfo & GeneralCallbackResult) | GeneralCallbackResult) => void;
+}
+
+/** 디바이스 정보 */
+export interface DeviceInfo {
+    /** 디바이스 브랜드 */
+    brand: string;
+    /** 디바이스 모델 */
+    model: string;
+    /** OS 및 버전 */
+    system: string;
+    /** 디바이스 성능 등급 (Android 전용) */
+    benchmarkLevel: number;
+    /** 앱 바이너리 인터페이스 타입 (Android 전용) - 호환용 */
+    abi: Mock<''>;
+    /** 기기 CPU 타입 (Android 전용) - 호환용 */
+    cpuType: Mock<''>;
+    /** 기기 바이너리 인터페이스 타입 (Android 전용) - 호환용 */
+    deviceAbi: Mock<''>;
+    /** 기기 메모리 크기 - 호환용 */
+    memorySize: Mock<''>;
+    /** 클라이언트 플랫폼 */
+    platform: Platform;
+}
+
+/** getDeviceInfo 옵션 */
+export interface GetDeviceInfoOption {
+    /** 성공 콜백 */
+    success?: (res: DeviceInfo & GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: (DeviceInfo & GeneralCallbackResult) | GeneralCallbackResult) => void;
+}
+
+// ============================================
+// UI API 타입
+// ============================================
+
+/** 메뉴 버튼 위치 정보 */
+export interface MenuButtonBoundingClientRect {
+    /** 너비 (px) */
+    width: number;
+    /** 높이 (px) */
+    height: number;
+    /** 상단 좌표 (px) */
+    top: number;
+    /** 우측 좌표 (px) */
+    right: number;
+    /** 하단 좌표 (px) */
+    bottom: number;
+    /** 좌측 좌표 (px) */
+    left: number;
+}
+
+// ============================================
+// Auth API 타입
+// ============================================
+
+/** 로그인 성공 결과 */
+export interface LoginSuccessResult {
+    /** 에러 메시지 */
+    errMsg: string;
+    /** 에러 코드 */
+    errCode?: number;
+    /** 사용자 로그인 코드 */
+    code: string;
+}
+
+/** 로그인 옵션 */
+export interface LoginOption {
+    /** 타임아웃 (ms) */
+    timeout?: number;
+    /** 성공 콜백 */
+    success?: (res: LoginSuccessResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: LoginSuccessResult | GeneralCallbackResult) => void;
+}
+
+/** 세션 확인 옵션 */
+export interface CheckSessionOption {
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/** 사용자 정보 */
+export interface UserInfo {
+    /** 사용자 닉네임 */
+    nickName: string;
+    /** 사용자 아바타 이미지 URL */
+    avatarUrl: string;
+    /** 사용자 언어 설정 - 호환용 */
+    language: Mock<'KO'>;
+    /** 성별 (0: 알 수 없음) - 호환용 */
+    gender: Mock<0>;
+    /** 국가 코드 - 호환용 */
+    country: Mock<''>;
+    /** 도시 - 호환용 */
+    city: Mock<''>;
+    /** 지역/도 - 호환용 */
+    province: Mock<''>;
+}
+
+/** 사용자 정보 조회 성공 결과 */
+export interface GetUserInfoSuccessResult {
+    /** 에러 메시지 */
+    errMsg: string;
+    /** 에러 코드 */
+    errCode?: number;
+    /** 사용자 정보 객체 */
+    userInfo: UserInfo;
+    /** 암호화된 데이터 (withCredentials가 true인 경우) */
+    encryptedData: string;
+    /** 암호화 초기 벡터 (withCredentials가 true인 경우) */
+    iv: string;
+    /** 데이터 서명 (withCredentials가 true인 경우) */
+    signature: string;
+    /** 원시 데이터 문자열 (withCredentials가 true인 경우) */
+    rawData: string;
+}
+
+/** 사용자 정보 조회 옵션 */
+export interface GetUserInfoOption {
+    /** 암호화 데이터 포함 여부 */
+    withCredentials?: boolean;
+    /** 반환되는 사용자 정보의 언어 */
+    lang?: 'KO';
+    /** 성공 콜백 */
+    success?: (res: GetUserInfoSuccessResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GetUserInfoSuccessResult | GeneralCallbackResult) => void;
+}
+
+// ============================================
+// Ad API 타입
+// ============================================
+
+/** 보상형 비디오 광고 생성 옵션 */
+export interface CreateRewardedVideoAdOption {
+    /** 광고 단위 ID */
+    adUnitId: string;
+    /** 다중 인스턴스 모드 사용 여부 */
+    multiton?: boolean;
+}
+
+/** 보상형 비디오 광고 인스턴스 */
+export interface RewardedVideoAd {
+    /** 광고 로드 */
+    load(): Promise<void>;
+    /** 광고 표시 */
+    show(): Promise<void>;
+    /** 광고 파괴 */
+    destroy(): void;
+    /** 로드 완료 이벤트 */
+    onLoad(callback: () => void): void;
+    /** 에러 이벤트 */
+    onError(callback: (res: { errMsg: string; errCode: number }) => void): void;
+    /** 닫기 버튼 클릭 이벤트 */
+    onClose(callback: (res: { isEnded: boolean }) => void): void;
+    /** 로드 이벤트 리스너 해제 */
+    offLoad(callback?: () => void): void;
+    /** 에러 이벤트 리스너 해제 */
+    offError(callback?: (res: { errMsg: string; errCode: number }) => void): void;
+    /** 닫기 이벤트 리스너 해제 */
+    offClose(callback?: (res: { isEnded: boolean }) => void): void;
+}
+
+// ============================================
+// Lifecycle API 타입
+// ============================================
+
+/** onShow 콜백 결과 */
+export interface OnShowCallbackResult {
+    /** 앱이 표시된 시각 */
+    timestamp: number;
+}
+
+/** onHide 콜백 결과 */
+export interface OnHideCallbackResult {
+    /** 앱이 숨겨진 시각 */
+    timestamp: number;
+}
+
+/** onShow 콜백 함수 타입 */
+export type OnShowCallback = (res: OnShowCallbackResult) => void;
+
+/** onHide 콜백 함수 타입 */
+export type OnHideCallback = (res?: OnHideCallbackResult) => void;
+
+/** exitMiniProgram 옵션 */
+export interface ExitMiniProgramOption {
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+/** restartMiniProgram 옵션 */
+export interface RestartMiniProgramOption {
+    /** 성공 콜백 */
+    success?: (res: GeneralCallbackResult) => void;
+    /** 실패 콜백 */
+    fail?: (res: GeneralCallbackResult) => void;
+    /** 완료 콜백 */
+    complete?: (res: GeneralCallbackResult) => void;
+}
+
+// ============================================
+// TudadaSDK 인터페이스
+// ============================================
+
+/** TudadaSDK 인터페이스 */
+export interface ITudadaSDK {
+    // ============================================
+    // Auth API
+    // ============================================
+
+    /**
+     * 사용자 로그인
+     *
+     * @example
+     * ```typescript
+     * TudadaSDK.login({
+     *   success: (res) => console.log('로그인 코드:', res.code),
+     *   fail: (res) => console.error('로그인 실패:', res.errMsg),
+     * });
+     * ```
+     */
+    login(options: LoginOption): void;
+
+    /**
+     * 세션 유효성 확인
+     *
+     * @example
+     * ```typescript
+     * TudadaSDK.checkSession({
+     *   success: () => console.log('세션 유효'),
+     *   fail: () => console.log('세션 만료, 재로그인 필요'),
+     * });
+     * ```
+     */
+    checkSession(options: CheckSessionOption): void;
+
+    /**
+     * 사용자 정보 조회
+     *
+     * @example
+     * ```typescript
+     * TudadaSDK.getUserInfo({
+     *   success: (res) => {
+     *     console.log('닉네임:', res.userInfo.nickName);
+     *     console.log('아바타:', res.userInfo.avatarUrl);
+     *   },
+     *   fail: (res) => console.error('사용자 정보 조회 실패:', res.errMsg),
+     * });
+     * ```
+     */
+    getUserInfo(options: GetUserInfoOption): void;
+
+    // ============================================
+    // Storage API
+    // ============================================
+
+    /**
+     * 데이터를 로컬 스토리지에 저장 (비동기)
+     */
+    setStorage(options: SetStorageOption): void;
+
+    /**
+     * 데이터를 로컬 스토리지에 저장 (동기)
+     */
+    setStorageSync(key: string, data: any): void;
+    setStorageSync(options: { key: string; data: any }): void;
+
+    /**
+     * 로컬 스토리지에서 데이터 조회 (비동기)
+     */
+    getStorage(options: GetStorageOption): void;
+
+    /**
+     * 로컬 스토리지에서 데이터 조회 (동기)
+     */
+    getStorageSync(key: string): any;
+    getStorageSync(options: { key: string }): any;
+
+    /**
+     * 로컬 스토리지에서 데이터 삭제 (비동기)
+     */
+    removeStorage(options: RemoveStorageOption): void;
+
+    /**
+     * 로컬 스토리지에서 데이터 삭제 (동기)
+     */
+    removeStorageSync(key: string): void;
+    removeStorageSync(options: { key: string }): void;
+
+    /**
+     * 로컬 스토리지 전체 삭제 (비동기)
+     */
+    clearStorage(options?: ClearStorageOption): void;
+
+    /**
+     * 로컬 스토리지 전체 삭제 (동기)
+     */
+    clearStorageSync(): void;
+
+    /**
+     * 스토리지 정보 조회 (동기)
+     */
+    getStorageInfoSync(): StorageInfo;
+
+    /**
+     * TudadaStore 인스턴스 획득
+     */
+    getTudadaStore(): TudadaStore;
+
+    /**
+     * TudadaStore에서 값 조회 (Unity Bridge용)
+     */
+    tudadaStoreGet(options: TudadaStoreGetOption): void;
+
+    /**
+     * TudadaStore에 값 저장 (Unity Bridge용)
+     */
+    tudadaStoreSave(options: TudadaStoreSaveOption): void;
+
+    // ============================================
+    // System API
+    // ============================================
+
+    /**
+     * 시스템 정보 조회 (비동기)
+     */
+    getSystemInfo(options?: GetSystemInfoOption): void;
+
+    /**
+     * 시스템 정보 조회 (동기)
+     */
+    getSystemInfoSync(): SystemInfo;
+
+    /**
+     * 창 정보 조회 (동기)
+     */
+    getWindowInfo(): WindowInfo;
+
+    /**
+     * 창 정보 조회 (비동기)
+     */
+    getWindowInfoAsync(options?: GetWindowInfoOption): void;
+
+    /**
+     * 앱 기본 정보 조회 (동기)
+     */
+    getAppBaseInfo(): AppBaseInfo;
+
+    /**
+     * 앱 기본 정보 조회 (비동기)
+     */
+    getAppBaseInfoAsync(options?: GetAppBaseInfoOption): void;
+
+    /**
+     * 디바이스 정보 조회 (동기)
+     */
+    getDeviceInfo(): DeviceInfo;
+
+    /**
+     * 디바이스 정보 조회 (비동기)
+     */
+    getDeviceInfoAsync(options?: GetDeviceInfoOption): void;
+
+    // ============================================
+    // UI API
+    // ============================================
+
+    /**
+     * 메뉴 버튼 위치 정보 조회
+     */
+    getMenuButtonBoundingClientRect(): MenuButtonBoundingClientRect;
+
+    // ============================================
+    // Device API
+    // ============================================
+
+    /**
+     * 짧은 진동 실행
+     */
+    vibrateShort(options?: VibrateShortOption): void;
+
+    /**
+     * 긴 진동 실행
+     */
+    vibrateLong(options?: VibrateLongOption): void;
+
+    /**
+     * 키보드 표시
+     */
+    showKeyboard(options?: ShowKeyboardOption): void;
+
+    /**
+     * 키보드 숨김
+     */
+    hideKeyboard(options?: HideKeyboardOption): void;
+
+    /**
+     * 키보드 입력 이벤트 리스너 등록
+     */
+    onKeyboardInput(callback: OnKeyboardInputCallback): void;
+
+    /**
+     * 키보드 입력 이벤트 리스너 제거
+     */
+    offKeyboardInput(callback?: OnKeyboardInputCallback): void;
+
+    /**
+     * 키보드 확인 버튼 클릭 이벤트 리스너 등록
+     */
+    onKeyboardConfirm(callback: OnKeyboardConfirmCallback): void;
+
+    /**
+     * 키보드 확인 버튼 클릭 이벤트 리스너 제거
+     */
+    offKeyboardConfirm(callback?: OnKeyboardConfirmCallback): void;
+
+    /**
+     * 키보드 입력 완료 이벤트 리스너 등록
+     */
+    onKeyboardComplete(callback: OnKeyboardCompleteCallback): void;
+
+    /**
+     * 키보드 입력 완료 이벤트 리스너 제거
+     */
+    offKeyboardComplete(callback?: OnKeyboardCompleteCallback): void;
+
+    // ============================================
+    // Clipboard API
+    // ============================================
+
+    /**
+     * 클립보드에 데이터 저장
+     */
+    setClipboardData(options: SetClipboardDataOption): void;
+
+    /**
+     * 클립보드에서 데이터 가져오기
+     */
+    getClipboardData(options?: GetClipboardDataOption): void;
+
+    // ============================================
+    // Ad API
+    // ============================================
+
+    /**
+     * 보상형 비디오 광고 인스턴스 생성
+     */
+    createRewardedVideoAd(options: CreateRewardedVideoAdOption): RewardedVideoAd;
+
+    // ============================================
+    // Lifecycle API
+    // ============================================
+
+    /**
+     * 앱이 포어그라운드로 전환될 때 실행할 콜백 등록
+     */
+    onShow(callback: OnShowCallback): void;
+
+    /**
+     * onShow 콜백 해제
+     */
+    offShow(callback?: OnShowCallback): void;
+
+    /**
+     * 앱이 백그라운드로 전환될 때 실행할 콜백 등록
+     */
+    onHide(callback: OnHideCallback): void;
+
+    /**
+     * onHide 콜백 해제
+     */
+    offHide(callback?: OnHideCallback): void;
+
+    /**
+     * 미니프로그램 종료
+     */
+    exitMiniProgram(options?: ExitMiniProgramOption): void;
+
+    /**
+     * 미니프로그램 재시작
+     */
+    restartMiniProgram(options?: RestartMiniProgramOption): void;
+}
+
+// ============================================
+// 글로벌 선언
+// ============================================
+
+declare global {
+    /** TudadaSDK 글로벌 인스턴스 */
+    const TudadaSDK: ITudadaSDK;
+    /** TudadaSDK 글로벌 인스턴스 (별칭) */
+    const tudadaSDK: ITudadaSDK;
+
+    interface Window {
+        TudadaSDK: ITudadaSDK;
+        tudadaSDK: ITudadaSDK;
+    }
+}
+
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "tudada-sdk-types",
+  "version": "0.0.1-2",
+  "description": "TypeScript type definitions for TudadaSDK - H5 web game SDK for Tudada platform",
+  "keywords": [
+    "tudada",
+    "sdk",
+    "types",
+    "typescript",
+    "h5",
+    "game",
+    "wechat",
+    "minigame"
+  ],
+  "author": "Tudada",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tudada/tudada-sdk-types"
+  },
+  "homepage": "https://github.com/tudada/tudada-sdk-types#readme",
+  "bugs": {
+    "url": "https://github.com/tudada/tudada-sdk-types/issues"
+  },
+  "main": "",
+  "types": "index.d.ts",
+  "files": [
+    "index.d.ts",
+    "global.d.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}