@momo-cloud/gami-sdk 0.0.84 → 0.0.93

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)
 
@@ -94,6 +94,7 @@ Typical game loop calls:
 - `coinExchange({ amount })`
 - `getMission({ viewId? })`
 - `getLeaderboard({ boardId, group?, limit?, page? })`
+- `submitLeaderboard({ boardName, score, periodType?, delta? })`
 - `getHistory({ page, limit })`
 - `getEvent({ eventId })`
 
@@ -174,7 +175,38 @@ if (res?.response_info?.error_code !== 0) {
 }
 ```
 
-## 8) Browser vs Host Runtime
+## 8) Leaderboard APIs
+
+### Read leaderboard
+
+```ts
+const lb = await GamiSDK.getLeaderboard({
+  boardId: 'win',
+  group: 'global', // 'global' | 'friend'
+  limit: 50,
+  page: 0,
+});
+```
+
+### 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 +216,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 +238,7 @@ npm run publish:npm
 npm run publish:all
 ```
 
-## 10) Integration Checklist
+## 11) Integration Checklist
 
 Before releasing a game integration:
 
@@ -218,7 +250,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 +276,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.