@momo-cloud/gami-sdk 0.0.93 → 0.0.97

package/README.md

@@ -82,21 +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
 
@@ -134,28 +138,91 @@ GamiSDK.screenTracking({
 });
 ```
 
-## 6) Shared Utilities
+## 6) Shared Utilities (Named Exports)
+
+Alongside the default `GamiSDK`, the package exposes these named exports:
+
+```ts
+import GamiSDK, { Storage, Calendar, AudioPlayer, GameEvent, Utils } from '@momo-cloud/gami-sdk';
+```
 
-Named exports are available for common integration helpers:
+| 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`, …) |
 
-- Storage: `saveItem`, `getItem`, `cacheFile`
-- Calendar wrapper: `addCalendar`
-- Time sync: `setServerTime`, `getServerTime`
-- Event bus: `GameEvent`
-- SSE support: from `features/sse/*`
-- Types: from `features/types/*`
+> `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()
+> ```
 
-Example:
+### 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/' });
+
+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
 
-await saveItem('progress', { level: 3, stars: 15 });
-const progress = await getItem('progress');
+```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
@@ -180,14 +247,11 @@ if (res?.response_info?.error_code !== 0) {
 ### Read leaderboard
 
 ```ts
-const lb = await GamiSDK.getLeaderboard({
-  boardId: 'win',
-  group: 'global', // 'global' | 'friend'
-  limit: 50,
-  page: 0,
-});
+const lb = await GamiSDK.getLeaderboard({ type: 'win' });
 ```
 
+- `type` — the leaderboard identifier (e.g. `'win'`).
+
 ### Submit a score
 
 ```ts

package/dist/index.public.d.ts

@@ -4,6 +4,29 @@ export declare const GameEvent: EventEmitter<string | symbol, any>;
 export declare const GamiSDK: Record<string, any>;
 export default GamiSDK;
 
+export declare const AudioPlayer: {
+    init(options: { baseURL: string }): void;
+    play(name: string, options?: { loop?: boolean; volume?: number }): Promise<any>;
+    playMusic(name: string, options?: { loop?: boolean; volume?: number; onComplete?: () => void }): Promise<any>;
+    stop(name: string): void;
+    pause(name?: string): void;
+    resume(name?: string): void;
+    setVolume(name: string, value: number): void;
+    setMute(name: string, value: boolean): void;
+    musicVolume: number;
+    enableSfx: boolean;
+    enable: boolean;
+};
+
+export declare const Storage: {
+    cacheJson(key: string, value: object): void;
+    cacheValue(key: string, value: string): void;
+    getJson<T = any>(key: string, defaultVal?: T): Promise<T>;
+    getValue(key: string, defaultVal?: string): Promise<string | undefined>;
+    cacheFile(url: string): Promise<string>;
+    getInCache(url: string): string | undefined;
+};
+
 export type IUserInfo = {
     id: string;
     name?: string;