@momo-cloud/gami-sdk 0.0.68 → 0.0.82

package/README.md

@@ -1,858 +1,256 @@
-# Gami SDK
+# Gami SDK Integration Guide
 
-> A comprehensive TypeScript SDK for building games on the MoMo platform
+`@momo-cloud/gami-sdk` is the integration layer between your web game and MoMo host capabilities.
+It provides:
 
-## 📋 Overview
+- Game backend APIs (spin, shake, mission, leaderboard, balance, exchange)
+- Platform bridge APIs (toast, share, permission, contacts, deep-link, calendar, clipboard, and more)
+- Runtime utilities (server-time sync, storage helpers, SSE, event bus)
 
-Gami SDK is a powerful TypeScript library that provides a unified interface for developing web-based games on the MoMo platform. It abstracts platform-specific APIs and provides consistent access to authentication, game state management, storage, and platform features.
+This document is written for engineering teams integrating a game into the MoMo ecosystem.
 
-### ✨ Key Features
+## 1) Integration Architecture
 
-- 🔐 **Authentication & Authorization** - Seamless token exchange and user authentication
-- 🎮 **Game Lifecycle Management** - Start, end, and manage game sessions
-- 💾 **Storage API** - Client-side storage with automatic key prefixing
-- 📊 **Leaderboard & Rankings** - Built-in support for competitive features
-- 📅 **Calendar Integration** - Schedule reminders and events
-- 🎯 **Mission System** - Track and complete user missions
-- 🎲 **Game Events** - Real-time event handling and tracking
-- 📈 **Analytics & Tracking** - Built-in event tracking and user behavior analytics
-- 🌐 **Cross-Platform** - Works in browser and MoMo app
-- 📦 **TypeScript Support** - Full type definitions included
+At runtime, `GamiSDK` composes two API groups:
 
-## 📦 Installation
+- `platformApi.exposeApi`: host bridge and device/platform functions
+- `gamiApi.exposeApi`: game-domain APIs and session workflow
 
-```bash
-# Using npm
-npm install @momo-cloud/gami-sdk
-
-# Using yarn
-yarn add @momo-cloud/gami-sdk
-
-# Using pnpm
-pnpm add @momo-cloud/gami-sdk
-```
-
-## 🚀 Quick Start
-
-```typescript
-import GamiSDK from '@momo-cloud/gami-sdk';
-
-// Initialize the SDK
-await GamiSDK.init({
-  gameId: 'your-game-id',
-  appjson: '',
-  source: 'game-launch-source'
-});
-
-console.log('User ID:', GamiSDK.userId);
-console.log('Token:', GamiSDK.token);
-
-// Start game session
-await GamiSDK.startGame();
-
-// Your game logic here...
-
-// make spin to get reward
-const result = await GamiSDK.spin();
-
-// End game session
-await GamiSDK.endGame();
-```
-
-## 📖 API Reference
-
-### Initialization
-
-#### `init(options)`
-
-Initialize the SDK with your game configuration.
-
-```typescript
-await GamiSDK.init({
-  gameId: 'demo',
-  appjson?: '',
-  source: 'momo',
-  userId?: '1234567890' // Optional, for testing
-});
-```
-
-**Parameters:**
-- `gameId` (string, optional): Your game identifier. If not provided, uses `featureId` from platform
-- `appjson` (string, required): app.json configuration file
-- `source` (string, optional): Launch source for analytics
-- `userId` (string, optional): Override user ID for testing
-
-**Returns:** `Promise<void>`
-
----
-
-### Game Management
-
-#### `startGame()`
-
-Begin a new game session and notify the backend.
-
-```typescript
-const response = await GamiSDK.startGame();
-console.log('Game started:', response);
-```
-
-**Returns:** `Promise<any>` - Server response with session data
-
----
-
-#### `endGame()`
-
-End the current game session and dismiss the app.
-
-```typescript
-await GamiSDK.endGame();
-// App will be dismissed automatically
-```
-
-**Returns:** `Promise<void>`
-
----
-
-### Configuration & Data
-
-#### `getConfig()`
-
-Fetch game configuration from the backend.
-
-```typescript
-const config = await GamiSDK.getConfig();
-console.log('Game config:', config);
-```
-
-**Returns:** `Promise<any>` - Game configuration object
-
----
-
-#### `getCoinExchangeInfo()`
-
-Load exchange metadata for the current game (coin → turn). The backend uses the fixed action `exchange_coin_to_turn`; the active `gameId` comes from `init`.
-
-```typescript
-const res = await GamiSDK.getCoinExchangeInfo();
-const { balance, exchangeRate, counter, counterLimit, fromCurrency, toCurrency } = res.result;
-```
-
-**Returns:** `Promise<TGetExchangeResponse>` - Standard `response_info` plus `result` with rate, balances, counters, and currency pair
-
----
-
-#### `coinExchange(options)`
-
-Submit a coin-to-turn exchange for the current game.
-
-```typescript
-const res = await GamiSDK.coinExchange({ amount: 100 });
-const { from, to, counter } = res.result;
-```
-
-**Parameters:**
-- `amount` (number): Coin amount to convert
-
-**Returns:** `Promise<TPostExchangeResponse>` - Updated `from` / `to` wallet snapshots and `counter` state
-
----
-
-#### `spin()`
-
-Perform a spinner spin for the current game. Sends `POST` to the twirler service with the active `gameId` (set via `init`).
-
-```typescript
-const result = await GamiSDK.spin();
-console.log('Spin result:', result);
-```
-
-**Returns:** `Promise<any>` - Server response with spin outcome (e.g. prize payload); exact shape follows the backend contract
-
----
-
-#### `getBalance(options)`
-
-Get user's balance for specified balance IDs.
-
-```typescript
-const { result: balance } = await GamiSDK.getBalance({
-  balanceId: ['turn', 'coin', 'gem', 'ticket']
-});
-
-console.log('Coins:', balance.turn);
-```
-
-**Parameters:**
-- `balanceId` (string): Balance Id
-
-**Returns:** `Promise<TBalance>` - Balance data object
-
----
-
-#### `getBalanceConfig()`
-
-Get available balance types (pockets) configuration.
-
-```typescript
-const pockets = await GamiSDK.getBalanceConfig();
-console.log('Available balances:', pockets);
-```
-
-**Returns:** `Promise<any>` - Pocket configuration
-
----
-
-#### `getHistory(options)`
-
-Get user's game history.
-
-```typescript
-const history = await GamiSDK.getHistory({
-  page: 1,
-  limit: 0
-});
-
-console.log('Recent games:', history.items);
-```
-
-**Returns:** `Promise<THistory>` - History records
-
----
-
-### Events & Missions
-
-#### `getEvent()`
-
-Fetch active events for the game.
-
-```typescript
-const events = await GamiSDK.getEvent();
-
-events.forEach(event => {
-  console.log(`Event: ${event.name}, Ends: ${event.endTime}`);
-});
-```
-
-**Returns:** `Promise<TEvent>` - Event data
-
----
-
-#### `mission.get()`
-
-Get user's mission status.
-
-```typescript
-import { mission } from '@momo-cloud/gami-sdk';
-
-const missions = await mission.get();
-
-missions.forEach(m => {
-  console.log(`Mission: ${m.name}, Progress: ${m.progress}/${m.target}`);
-});
+```text
+Game UI (React/Preact/Pixi)
+        |
+        v
+      GamiSDK
+   +-----------+
+   | platform  | -> host bridge (toast, share, permission, refId, app events)
+   | game api  | -> game services (config, balance, spin, shake, mission, ...)
+   +-----------+
+        |
+        v
+MoMo host + backend services
 ```
 
-**Returns:** `Promise<MissionResponse[]>` - Array of missions
-
----
-
-#### `mission.sendEvent(eventName, serviceId?)`
+## 2) Installation
 
-Mark a mission event as completed.
-
-```typescript
-import { mission } from '@momo-cloud/gami-sdk';
-
-await mission.done('level_completed', 'service-123');
+```bash
+npm install @momo-cloud/gami-sdk
 ```
 
-**Parameters:**
-- `eventName` (string): Event identifier
-- `serviceId` (string, optional): Related service ID
-
-**Returns:** `Promise<any>` - Server response
+or
 
----
-
-### Storage
-
-#### `saveItem(key, value)`
-
-Save data to local storage with automatic game ID prefixing.
-
-```typescript
-import { saveItem } from '@momo-cloud/gami-sdk';
-
-// Save JSON object
-await saveItem('userProgress', {
-  level: 5,
-  score: 1200,
-  items: ['sword', 'shield']
-});
-
-// Save string
-await saveItem('playerName', 'MoMoGamer123');
+```bash
+yarn add @momo-cloud/gami-sdk
 ```
 
-**Parameters:**
-- `key` (string): Storage key (will be prefixed with gameId)
-- `value` (any): Data to store (will be JSON stringified)
-
-**Returns:** `Promise<void>`
-
----
-
-#### `getItem(key)`
+## 3) Quick Start (Recommended Bootstrap)
 
-Retrieve data from local storage.
-
-```typescript
-import { getItem } from '@momo-cloud/gami-sdk';
-
-const progress = await getItem('userProgress');
-console.log('Current level:', progress?.level);
-
-const name = await getItem('playerName');
-console.log('Player name:', name);
+```ts
+import GamiSDK from '@momo-cloud/gami-sdk';
+import appJson from '../app.json';
+
+export async function bootstrapGame() {
+  await GamiSDK.init({
+    gameId: import.meta.env.VITE_DEFAULT_GAME_ID,
+    userId: import.meta.env.VITE_USER_ID, // optional in host runtime
+    appjson: JSON.stringify(appJson),
+    source: 'momo', // optional analytics source
+  });
+}
 ```
 
-**Parameters:**
-- `key` (string): Storage key (gameId prefix added automatically)
+## 4) Integration Phases
 
-**Returns:** `Promise<any | null>` - Stored data or null if not found
+### Phase A - Initialize SDK
 
----
+Call once at app startup:
 
-#### `cacheFile(url)`
+- `init({ appjson, gameId?, userId?, source? })`
+- `wait()`
 
-Cache remote files and get blob URL.
+Then rely on runtime properties:
 
-```typescript
-import { cacheFile } from '@momo-cloud/gami-sdk';
+- `GamiSDK.userId`
+- `GamiSDK.userInfo`
+- `GamiSDK.token`
+- `GamiSDK.gameId`
+- `GamiSDK.appProfile`
+- `GamiSDK.deviceInfo`
 
-const imageUrl = 'https://img.mservice.io/game/icon.png';
-const cachedUrl = await cacheFile(imageUrl);
+### Phase B - Start Gameplay Session
 
-// Use cachedUrl in your game
-document.getElementById('avatar').src = cachedUrl;
+```ts
+await GamiSDK.startGame();
 ```
 
-**Parameters:**
-- `url` (string): Remote file URL
-
-**Returns:** `Promise<string>` - Blob URL or original URL if caching fails
-
----
-
-### Calendar
-
-#### `addCalendar(options)`
-
-Add event to device calendar.
-
-```typescript
-import { addCalendar } from '@momo-cloud/gami-sdk';
+Typical game loop calls:
 
-const added = await addCalendar({
-  title: 'Special Event Reminder',
-  startDate: new Date('2025-12-15T10:00:00'),
-  endDate: new Date('2025-12-15T12:00:00'),
-  notes: 'Don\'t miss the limited-time event!',
-  key: 'event-reminder-dec-15',
-  alarm: new Date('2025-12-15T09:30:00'), // 30 min before
-  desc: 'Complete special missions for exclusive rewards',
-  toast: 'Please grant calendar permission to set reminders'
-});
-
-console.log('Calendar event added:', added);
-```
+- `getConfig()`
+- `getBalance({ balanceId })`
+- `getBalanceConfig()`
+- `spin()`
+- `shake()`
+- `getCoinBalance()`
+- `getCoinExchangeInfo()`
+- `coinExchange({ amount })`
+- `getMission({ viewId? })`
+- `getLeaderboard({ boardId, group?, limit?, page? })`
+- `getHistory({ page, limit })`
+- `getEvent({ eventId })`
 
-**Parameters:**
-- `title` (string): Event title
-- `startDate` (Date | number): Event start time
-- `endDate` (Date | number): Event end time
-- `notes` (string): Event notes
-- `key` (string): Unique identifier for the event
-- `alarm` (Date | number): Alarm/notification time
-- `desc` (string): Event description
-- `toast` (string, optional): Permission request message
+### Phase C - Close or Navigate
 
-**Returns:** `Promise<boolean>` - True if added successfully
-
----
+- `await GamiSDK.endGame()` to close session
+- `GamiSDK.closeApp()` to dismiss host view
+- `GamiSDK.goHome()` to return to home
 
-### Platform APIs
+## 5) Platform Bridge APIs (Most Used)
 
-The SDK exposes additional platform-specific APIs through `GamiSDK`:
+The SDK exposes host-native actions directly:
 
-#### `showToast(options)`
+- Feedback: `showToast`, `showAlert`
+- Navigation: `openWeb`, `openURL`, `startRefId`
+- Social: `shareExternal`, `shareFacebook`, `shareMessenger`
+- Device: `scanQRCode`, `copyToClipBoard`, `getImage`, `saveImage`
+- Permissions: `requestPermission`, `checkPermission`
+- Contacts and notifications: `getContacts`, `registerNoti`, `unregisterNoti`
+- Calendar: `saveCalendarEvent`
+- Analytics: `trackingEvent`, `screenTracking`
+- Host lifecycle: `onFocusApp`, `onBlurApp`, `listenShaking`
 
-Display a toast notification to the user.
+Example:
 
-```typescript
+```ts
 GamiSDK.showToast({
-  title: 'Welcome!',
-  description: 'Thanks for playing',
-  duration: 3000,
-  type: 'success' // 'success' | 'failure' | 'info'
-});
-```
-
-**Parameters:**
-- `title` (string, optional): Toast title
-- `description` (string): Toast message
-- `duration` (number): Display duration in milliseconds
-- `type` (string, optional): Toast type
-
----
-
-#### `showAlert(title, message, buttons?)`
-
-Show a native alert dialog.
-
-```typescript
-GamiSDK.showAlert(
-  'Confirm Action',
-  'Are you sure you want to proceed?',
-  ['Cancel', 'Confirm']
-);
-```
-
-**Parameters:**
-- `title` (string): Alert title
-- `message` (string): Alert message
-- `buttons` (string[], optional): Button labels (default: ['OK'])
-
----
-
-#### `openWeb(options)`
-
-Open a URL in an in-app webview.
-
-```typescript
-GamiSDK.openWeb({
-  url: 'https://example.com/rules',
-  title: 'Game Rules'
-});
-
-// Or with custom HTML
-GamiSDK.openWeb({
-  html: '<h1>Custom Content</h1>',
-  title: 'Info'
-});
-```
-
-**Parameters:**
-- `url` (string, optional): URL to open
-- `html` (string, optional): Custom HTML content
-- `title` (string, optional): Webview title
-
-**Returns:** `Promise<boolean>`
-
----
-
-#### `openURL(url)`
-
-Open a URL in the device's external browser.
-
-```typescript
-GamiSDK.openURL('https://momo.vn');
-```
-
-**Parameters:**
-- `url` (string): URL to open
-
-**Returns:** `Promise<boolean>`
-
----
-
-#### `shareExternal(options)`
-
-Share content to external apps.
-
-```typescript
-GamiSDK.shareExternal({
-  title: 'Check out this game!',
-  message: 'I just scored 1000 points!',
-  url: 'https://momo.vn/game',
-  subject: 'Game Score'
-});
-```
-
-**Parameters:**
-- `title` (string, optional): Share title
-- `message` (string, optional): Share message
-- `url` (string, optional): URL to share
-- `subject` (string, optional): Email subject
-
-**Returns:** `Promise<boolean>`
-
----
-
-#### `copyToClipBoard(text, message?)`
-
-Copy text to clipboard.
-
-```typescript
-GamiSDK.copyToClipBoard(
-  'PROMO2025',
-  'Promo code copied!'
-);
-```
-
-**Parameters:**
-- `text` (string): Text to copy
-- `message` (string, optional): Success message to display
-
-**Returns:** `Promise<boolean>`
-
----
-
-#### `shareFacebook(url)` / `shareMessenger(url)`
-
-Share URL to Facebook or Messenger (MoMo app only).
-
-```typescript
-GamiSDK.shareFacebook('https://momo.vn/game');
-GamiSDK.shareMessenger('https://momo.vn/game');
-```
-
-**Parameters:**
-- `url` (string): URL to share
-
-**Returns:** `Promise<boolean>`
-
----
-
-#### `requestPermission(permission)` / `checkPermission(permission)`
-
-Request or check device permissions.
-
-```typescript
-// Request permission
-const status = await GamiSDK.requestPermission('calendars');
-console.log('Permission status:', status); // 'granted' | 'denied'
-
-// Check existing permission
-const hasPermission = await GamiSDK.checkPermission('contacts');
-```
-
-**Parameters:**
-- `permission` (string): Permission type ('calendars', 'contacts', etc.)
-
-**Returns:** `Promise<string>` - Permission status
-
----
-
-#### `getContacts()`
-
-Retrieve device contacts (MoMo app only, requires permission).
-
-```typescript
-const contacts = await GamiSDK.getContacts();
-console.log('Contacts:', contacts);
-```
-
-**Returns:** `Promise<any[] | null>`
-
----
-
-#### `saveCalendarEvent(options)`
-
-Save an event to the device calendar (MoMo app only).
-
-```typescript
-const saved = await GamiSDK.saveCalendarEvent({
-  title: 'Daily Bonus Available',
-  startDate: new Date('2025-12-15T10:00:00'),
-  endDate: new Date('2025-12-15T12:00:00'),
-  notes: 'Come back to claim your daily bonus!',
-  key: 'daily_bonus_reminder',
-  alarm: new Date('2025-12-15T09:45:00'),
-  des: 'Daily bonus notification',
-  toast: 'Please grant calendar permission'
+  description: 'Reward claimed',
+  duration: 2000,
+  type: 'success',
 });
 
-console.log('Event saved:', saved);
-```
-
-**Parameters:**
-- `title` (string): Event title
-- `startDate` (Date | number): Event start time
-- `endDate` (Date | number): Event end time
-- `notes` (string): Event notes
-- `key` (string): Storage key for event ID
-- `alarm` (Date | number): Reminder time
-- `des` (string): Event description
-- `toast` (string, optional): Permission request message
-
-**Returns:** `Promise<boolean>`
-
----
-
-#### `trackingEvent(event, data)`
-
-Track analytics events.
-
-```typescript
-GamiSDK.trackingEvent('level_completed', {
-  level: 5,
-  score: 1200,
-  duration: 45
-});
-```
-
-**Parameters:**
-- `event` (string): Event name
-- `data` (object): Event data
-
----
-
-#### `screenTracking(options)`
-
-Track screen views and user actions.
-
-```typescript
 GamiSDK.screenTracking({
-  game_id: 'vn.momo.web.luckywheel',
   event_name: 'screen_view',
-  action_name: 'view_leaderboard',
-  screen_name: 'leaderboard_screen',
-  extra: { tab: 'weekly' },
-  error_code: 0
+  action_name: 'open_home',
+  screen_name: 'home',
 });
 ```
 
-**Parameters:**
-- `game_id` (string, optional): Game identifier
-- `event_name` (string): Event name
-- `action_name` (string): Action identifier
-- `screen_name` (string): Screen identifier
-- `extra` (object, optional): Additional data
-- `error_code` (number | string, optional): Error code if applicable
+## 6) Shared Utilities
 
----
+Named exports are available for common integration helpers:
 
-#### `startRefId(options)`
+- Storage: `saveItem`, `getItem`, `cacheFile`
+- Calendar wrapper: `addCalendar`
+- Time sync: `setServerTime`, `getServerTime`
+- Event bus: `GameEvent`
+- SSE support: from `features/sse/*`
+- Types: from `features/types/*`
 
-Navigate to another feature/screen by reference ID.
+Example:
 
-```typescript
-// Start feature by code
-GamiSDK.startRefId({
-  refId: 'FEATURE_CODE_123',
-  refExtra: { source: 'game' }
-});
+```ts
+import { saveItem, getItem, GameEvent } from '@momo-cloud/gami-sdk';
 
-// Open URL
-GamiSDK.startRefId({
-  refId: 'https://example.com',
-  useWeb: true // Open in webview instead of external browser
-});
+await saveItem('progress', { level: 3, stars: 15 });
+const progress = await getItem('progress');
 
-// Navigate to internal path
-GamiSDK.startRefId({
-  refId: '/wallet/topup'
+GameEvent.on('GAME_ON_BACK', () => {
+  // route back to your home screen
 });
 ```
 
-**Parameters:**
-- `refId` (string): Feature code, URL, or internal path
-- `refExtra` (object | string, optional): Additional parameters
-- `useWeb` (boolean, optional): Open URLs in webview (default: false)
-
----
-
-#### `listenShaking(options)`
+## 7) Error Handling Pattern
 
-Listen to device shake events (MoMo app only).
+Most game APIs return payloads with `response_info`.
+Treat non-zero error codes as business failures:
 
-```typescript
-GamiSDK.listenShaking({
-  onShake: (data) => {
-    console.log('Device shaken!', data);
-    // Trigger special action
-    showBonusReward();
-  }
-});
+```ts
+const res = await GamiSDK.spin();
+if (res?.response_info?.error_code !== 0) {
+  GamiSDK.showToast({
+    description: res?.response_info?.error_message || 'Spin failed',
+    duration: 2000,
+    type: 'failure',
+  });
+  return;
+}
 ```
 
-**Parameters:**
-- `onShake` (function): Callback when device is shaken
+## 8) Browser vs Host Runtime
 
-**Returns:** Listener object (for cleanup)
+- In MoMo host: full platform bridge behavior is available.
+- In browser/dev mode: host-only behavior may be mocked, no-op, or limited.
 
----
-
-#### `onFocusApp(callback)` / `onBlurApp(callback)`
+Integration recommendation:
 
-Listen to app focus/blur events.
+- Keep game domain flow independent from host-only APIs.
+- Wrap optional host actions with graceful fallback in browser.
 
-```typescript
-GamiSDK.onFocusApp(() => {
-  console.log('App is now active');
-  resumeGame();
-});
-
-GamiSDK.onBlurApp(() => {
-  console.log('App went to background');
-  pauseGame();
-});
-```
-
-**Parameters:**
-- `callback` (function): Function to call on focus/blur
-
----
+## 9) Build and Publish Modes
 
-#### `registerNoti(callback)` / `unregisterNoti()`
+This repository supports two build modes:
 
-Register/unregister notification listeners (MoMo app only).
+- Internal build (`src/index.ts`): full internal integration surface
+- Public build (`src/index.public.ts`): limited/public package output
 
-```typescript
-// Register
-GamiSDK.registerNoti((data) => {
-  console.log('Received notification:', data);
-  handleNotification(data);
-});
+Commands:
 
-// Unregister
-GamiSDK.unregisterNoti();
+```bash
+npm run build:internal
+npm run build:public
 ```
 
-**Parameters:**
-- `callback` (function): Notification handler
-
----
-
-### Utilities
+Publish scripts:
 
-#### `getServerTime()`
-
-Get synchronized server time.
-
-```typescript
-import { getServerTime } from '@momo-cloud/gami-sdk';
-
-const serverTime = getServerTime();
-console.log('Server time:', new Date(serverTime));
+```bash
+npm run publish:nexus
+npm run publish:npm
+npm run publish:all
 ```
 
-**Returns:** `number` - Server timestamp in milliseconds
+## 10) Integration Checklist
 
----
+Before releasing a game integration:
 
-#### `setServerTime(time)`
+- `init()` and `wait()` executed exactly once on app bootstrap
+- `startGame()` called on session start, `endGame()` on session end
+- Critical APIs wrapped with business error handling (`response_info`)
+- Host-only APIs guarded for browser fallback
+- Analytics events wired (`trackingEvent` and `screenTracking`)
+- Local cache keys use SDK helpers to avoid collisions
+- Permissions flow validated for calendar/contacts/image capture
 
-Set server time offset manually (usually handled by init).
+## 11) Minimal End-to-End Example
 
-```typescript
-import { setServerTime } from '@momo-cloud/gami-sdk';
-
-setServerTime(Date.now() + 1000); // 1 second ahead
-```
-
-**Parameters:**
-- `time` (number): Server timestamp in milliseconds
-
----
-
-### Properties
+```ts
+import GamiSDK from '@momo-cloud/gami-sdk';
+import appJson from '../app.json';
 
-Access SDK state and user information:
+export async function run() {
+  await GamiSDK.init({
+    appjson: JSON.stringify(appJson),
+    gameId: import.meta.env.VITE_DEFAULT_GAME_ID,
+    userId: import.meta.env.VITE_USER_ID,
+  });
+  await GamiSDK.wait();
 
-```typescript
-// User information
-console.log(GamiSDK.userId);      // string: User ID
-console.log(GamiSDK.userInfo);    // IUserInfo: Full user profile
-console.log(GamiSDK.token);       // string: Auth token
-console.log(GamiSDK.gameId);      // string: Current game ID
+  await GamiSDK.startGame();
+  const spinResult = await GamiSDK.spin();
 
-// Platform information
-console.log(GamiSDK.isBrowser);   // boolean: Running in browser
-console.log(GamiSDK.isIos);       // boolean: iOS device
-console.log(GamiSDK.feature);     // any: Platform features
-```
+  if (spinResult?.response_info?.error_code === 0) {
+    GamiSDK.showToast({ description: 'Spin success', duration: 1500, type: 'success' });
+  }
 
-**User Info Type:**
-```typescript
-interface IUserInfo {
-  id: string;
-  name: string;
-  phone?: string;
-  avatar?: string;
-  // ... additional fields
+  // Later when leaving the game:
+  await GamiSDK.endGame();
 }
 ```
 
-## 🔐 Authentication Flow
+## 12) Notes for Architects
 
-```
-User Opens Game
-      ↓
-SDK.init() called
-      ↓
-Get user profile and authentication
-      ↓
-Backend: login(appToken) → Exchange for gameToken
-      ↓
-Backend: getProfile(gameToken) → Get game profile
-      ↓
-Backend: getBalance(gameToken) → Get balances
-      ↓
-Backend: getServerTime() → Sync time
-      ↓
-Game Ready ✓
-```
-
-## 🌐 Platform Support
-
-| Feature | Browser | MoMo App | Notes |
-|---------|---------|----------|-------|
-| Authentication | ✅ | ✅ | Mock in browser |
-| Storage | ✅ | ✅ | localStorage / native |
-| Calendar | ❌ | ✅ | Native only |
-| Notifications | ❌ | ✅ | Native only |
-| Game APIs | ✅ | ✅ | Full support |
-
-## ⚙️ Configuration
-
-### TypeScript
-
-The SDK is written in TypeScript and includes type definitions:
-
-```typescript
-import GamiSDK, {
-  TBalance,
-  TGetExchangeResponse,
-  TLeaderboard,
-  TPostExchangeResponse,
-  IUserInfo
-} from '@momo-cloud/gami-sdk';
-
-const balance: TBalance = await GamiSDK.getBalance({
-  balanceIds: ['coin']
-});
+- Keep `GamiSDK` behind your own `sdkService` adapter in app code.
+- Separate domain logic from host bridge calls for easier testability.
+- Use typed DTOs from `features/types` in application boundaries.
+- Favor centralized error normalization to avoid duplicated checks.
 
-const exchangeInfo: TGetExchangeResponse = await GamiSDK.getCoinExchangeInfo();
-const posted: TPostExchangeResponse = await GamiSDK.coinExchange({ amount: 100 });
-```
-
-### Vite Integration
-
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  resolve: {
-    alias: {
-      '@sdk': '@momo-cloud/gami-sdk'
-    }
-  }
-});
-```
-
-## 📄 License
+---
 
-UNLICENSED
+License: `UNLICENSED`