@momo-cloud/gami-sdk 0.0.86 → 0.0.95

package/README.md

@@ -3,7 +3,7 @@
 `@momo-cloud/gami-sdk` is the integration layer between your web game and MoMo host capabilities.
 It provides:
 
-- Game backend APIs (spin, shake, mission, leaderboard, balance, exchange)
+- Game backend APIs (spin, shake, mission, leaderboard, submit leaderboard score, 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)
 
@@ -82,20 +82,25 @@ Then rely on runtime properties:
 await GamiSDK.startGame();
 ```
 
-Typical game loop calls:
+> `startGame()` / `endGame()` bracket a **gameplay session**, not a single spin. Call `startGame()` once when entering the game and `endGame()` once when leaving — many `spin()` calls happen in between.
 
-- `getConfig()`
-- `getBalance({ balanceId })`
+Typical game loop calls (signatures match `IGameApi`):
+
+- `getConfig({ ext? })`
+- `getBalance({ balanceId? })`
 - `getBalanceConfig()`
-- `spin()`
+- `spin({ checkCounter?, giftCate?, isBonus? })`
 - `shake()`
 - `getCoinBalance()`
-- `getCoinExchangeInfo()`
-- `coinExchange({ amount })`
+- `getCoinExchangeInfo({ actionId? })`
+- `coinExchange({ amount, actionId? })`
 - `getMission({ viewId? })`
-- `getLeaderboard({ boardId, group?, limit?, page? })`
+- `postSuccessMission({ eventName, serviceId? })`
+- `getLeaderboard({ type })`
+- `submitLeaderboard({ boardName, score, periodType?, delta? })`
 - `getHistory({ page, limit })`
 - `getEvent({ eventId })`
+- `customGameRequest({ path, method, subDomain?, body?, extraHeader?, mockData? })`
 
 ### Phase C - Close or Navigate
 
@@ -133,28 +138,91 @@ GamiSDK.screenTracking({
 });
 ```
 
-## 6) Shared Utilities
+## 6) Shared Utilities (Named Exports)
 
-Named exports are available for common integration helpers:
+Alongside the default `GamiSDK`, the package exposes these named exports:
 
-- Storage: `saveItem`, `getItem`, `cacheFile`
-- Calendar wrapper: `addCalendar`
-- Time sync: `setServerTime`, `getServerTime`
-- Event bus: `GameEvent`
-- SSE support: from `features/sse/*`
-- Types: from `features/types/*`
+```ts
+import GamiSDK, { Storage, Calendar, AudioPlayer, GameEvent, Utils } from '@momo-cloud/gami-sdk';
+```
 
-Example:
+| Export | What it is |
+| --- | --- |
+| `GamiSDK` (default) | Composed game + platform API object |
+| `Storage` | Persistent key/value + file cache (see §6.1) |
+| `Calendar` | Device calendar helper |
+| `AudioPlayer` | Music / SFX playback (see §6.2) |
+| `GameEvent` | In-app event bus (`eventemitter3`) |
+| `Utils` | Misc helpers (name/phone formatting, etc.) |
+| Types | Domain DTOs (`TSpin`, `TLeaderboard`, `THistory`, …) |
+
+> `getServerTime()` / `setServerTime()` live on the `GamiSDK` object, not as standalone named exports — call `GamiSDK.getServerTime()`. It is **synchronous** (returns `number`, ms epoch) — do **not** `await` it. Use it for any countdown, expiry, or campaign window instead of `Date.now()` to avoid client-clock skew.
+>
+> ```ts
+> const now = GamiSDK.getServerTime();   // ✅ synchronous
+> const remaining = campaignEndAt - now; // ❌ never Date.now()
+> ```
+
+### 6.1) Storage
+
+**Use `Storage` for all persistence — not `localStorage` / `sessionStorage`.** Browser storage is unreliable inside the MoMo WebView. All keys are automatically namespaced with the current `gameId` (e.g. `wheel_fpt_progress`).
+
+```ts
+import { Storage } from '@momo-cloud/gami-sdk';
+
+// Writes are fire-and-forget (synchronous, return void)
+Storage.cacheJson('progress', { level: 3, stars: 15 });
+Storage.cacheValue('lastSeen', Date.now());
+
+// Reads are async
+const progress = await Storage.getJson('progress', /* default */ {});
+const lastSeen = await Storage.getValue('lastSeen');
+
+// CDN file caching → returns a usable (possibly object) URL
+const localUrl = await Storage.cacheFile('https://cdn.example.com/img/wheel.png');
+```
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `cacheJson(key, obj)` | `void` | Persist an object (fire-and-forget) |
+| `cacheValue(key, val)` | `void` | Persist a primitive |
+| `getJson(key, default?)` | `Promise<any>` | Read object; falls back to `default` |
+| `getValue(key, default?)` | `Promise<any>` | Read primitive |
+| `cacheFile(url)` | `Promise<string>` | Cache a remote file, returns local URL |
+| `getInCache(url)` | `string \| undefined` | Synchronous lookup of an already-cached file |
+
+### 6.2) AudioPlayer
 
 ```ts
-import { saveItem, getItem, GameEvent } from '@momo-cloud/gami-sdk';
+import { AudioPlayer } from '@momo-cloud/gami-sdk';
+
+// If sound names are short keys (e.g. 'bg', 'btn-click'), set a base URL first.
+// Skip this if every name you pass is already a full https URL.
+AudioPlayer.init({ baseURL: 'https://cdn.example.com/sounds/' });
 
-await saveItem('progress', { level: 3, stars: 15 });
-const progress = await getItem('progress');
+AudioPlayer.play('btn-click');                       // one-shot SFX
+AudioPlayer.play('btn-click', { volume: 0.5 });      // with options
+AudioPlayer.playMusic('bg', { loop: true, volume: 1 }); // looping background music
+
+AudioPlayer.pause();          // pause all (no arg) — call synchronously on app blur
+AudioPlayer.resume();         // resume all — on app focus, wrap in setTimeout(…, 1000) on iOS WebView
+AudioPlayer.stop('bg');
+AudioPlayer.enable = false;    // mute everything (respect user setting)
+AudioPlayer.musicVolume = 0.3; // 0..1
+```
+
+> `playMusic`'s second argument is an **options object** (`{ loop, volume, onComplete }`) — not a boolean. `init` takes `{ baseURL }` (capital `URL`).
+
+### 6.3) Event bus
+
+```ts
+import { GameEvent } from '@momo-cloud/gami-sdk';
 
 GameEvent.on('GAME_ON_BACK', () => {
   // route back to your home screen
 });
+GameEvent.emit('GAME_ON_BACK');
+GameEvent.off('GAME_ON_BACK', handler);
 ```
 
 ## 7) Error Handling Pattern
@@ -174,7 +242,35 @@ if (res?.response_info?.error_code !== 0) {
 }
 ```
 
-## 8) Browser vs Host Runtime
+## 8) Leaderboard APIs
+
+### Read leaderboard
+
+```ts
+const lb = await GamiSDK.getLeaderboard({ type: 'win' });
+```
+
+- `type` — the leaderboard identifier (e.g. `'win'`).
+
+### Submit a score
+
+```ts
+await GamiSDK.submitLeaderboard({
+  boardName: 'win',
+  score: 1,
+  periodType: 'WEEKLY', // default – omit if weekly
+  delta: 1,             // optional; defaults to score value
+});
+```
+
+- `boardName` — leaderboard identifier (e.g. `'win'`).
+- `score` — the score value to record.
+- `periodType` — leaderboard period bucket; defaults to `'WEEKLY'`.
+- `delta` — incremental change amount; omit to use the same value as `score`.
+
+`gameId` and `userId` are injected automatically from the SDK session — do not pass them manually.
+
+## 9) Browser vs Host Runtime
 
 - In MoMo host: full platform bridge behavior is available.
 - In browser/dev mode: host-only behavior may be mocked, no-op, or limited.
@@ -184,7 +280,7 @@ Integration recommendation:
 - Keep game domain flow independent from host-only APIs.
 - Wrap optional host actions with graceful fallback in browser.
 
-## 9) Build and Publish Modes
+## 10) Build and Publish Modes
 
 This repository supports two build modes:
 
@@ -206,7 +302,7 @@ npm run publish:npm
 npm run publish:all
 ```
 
-## 10) Integration Checklist
+## 11) Integration Checklist
 
 Before releasing a game integration:
 
@@ -218,7 +314,7 @@ Before releasing a game integration:
 - Local cache keys use SDK helpers to avoid collisions
 - Permissions flow validated for calendar/contacts/image capture
 
-## 11) Minimal End-to-End Example
+## 12) Minimal End-to-End Example
 
 ```ts
 import GamiSDK from '@momo-cloud/gami-sdk';
@@ -244,7 +340,7 @@ export async function run() {
 }
 ```
 
-## 12) Notes for Architects
+## 13) Notes for Architects
 
 - Keep `GamiSDK` behind your own `sdkService` adapter in app code.
 - Separate domain logic from host bridge calls for easier testability.