@zhimakechuang/game-sdk 1.0.0

package/README.md

@@ -0,0 +1,179 @@
+# @zhimakechuang/game-sdk
+
+通用游戏 SDK — 封装 [`apps/game-server-shared`](https://github.com/Chuang0516/game-factory/tree/main/apps/game-server-shared) 的 HTTP 接口，一套代码支持**微信小游戏 / 抖音小游戏 / H5** 三端。
+
+## 特性
+
+- **一套代码三端运行**：自动检测运行环境（wx / tt / H5），底层切换 `wx.request` / `tt.request` / `fetch`
+- **Token 自动持久化**：登录后自动存到 `localStorage`（H5）或本地存储（小游戏），下次进入免登录
+- **多租户隔离**：通过 `gameId` 隔离不同游戏的数据，一套服务端承载所有游戏
+- **模拟模式**：`mock: true` 时不连服务端，返回假数据，方便模板开发与调试
+- **全类型定义**：TypeScript 编写，自带 `.d.ts`，IDE 智能提示完备
+- **零依赖**：打包后仅 8KB（gzip 后更小），不引入任何运行时依赖
+
+## 安装
+
+```bash
+npm install @zhimakechuang/game-sdk
+# 或
+pnpm add @zhimakechuang/game-sdk
+# 或
+yarn add @zhimakechuang/game-sdk
+```
+
+## 快速开始
+
+### 工程化项目（npm 安装）
+
+```ts
+import { createGameSdk } from '@zhimakechuang/game-sdk';
+
+const sdk = createGameSdk({
+  gameId: 'merge-game',           // 在平台后台登记的游戏 ID
+  baseUrl: 'https://api.example.com', // api-server 根地址
+});
+
+// 登录（微信小游戏）
+const { wx } = miniProgram; // 假设已拿到微信环境
+const { code } = await wx.login();
+await sdk.auth.login({ code, platform: 'wx' });
+
+// 提交分数
+const result = await sdk.score.submit({ score: 1000 });
+console.log(result.rank, result.isHighScore);
+
+// 拉排行榜
+const top = await sdk.leaderboard.top(100);
+const me = await sdk.leaderboard.myRank();
+```
+
+### CDN 引入（轻量模板 / H5）
+
+```html
+<script src="https://unpkg.com/@zhimakechuang/game-sdk"></script>
+<script>
+  const sdk = GameSDK.createGameSdk({
+    gameId: 'merge-game',
+    baseUrl: 'https://api.example.com',
+  });
+
+  // 访客登录（H5 无需微信/抖音凭据）
+  await sdk.auth.login({ code: 'device-id', platform: 'guest' });
+  await sdk.score.submit({ score: 1000 });
+</script>
+```
+
+### 模拟模式（不连服务端）
+
+```ts
+const sdk = createGameSdk({
+  gameId: 'demo',
+  baseUrl: '',     // 不需要
+  mock: true,      // 关键：走 mock
+});
+
+await sdk.auth.login({ code: 'x', platform: 'guest' });
+const r = await sdk.score.submit({ score: 100 });
+// r.isHighScore === true, r.rank === 1
+```
+
+## API 参考
+
+### `createGameSdk(config)` → `GameSdk`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `config.gameId` | `string` | 游戏 ID（必填） |
+| `config.baseUrl` | `string` | api-server 根地址（必填，mock 模式可空） |
+| `config.mock` | `boolean` | 模拟模式，默认 `false` |
+
+### `sdk.auth` — 身份与登录
+
+| 方法 | 说明 |
+|---|---|
+| `login(opts)` | 登录（wx/tt/guest），成功后自动持久化 token |
+| `me()` | 获取当前登录玩家信息 |
+| `logout()` | 登出，清除本地 token |
+| `getToken()` | 获取当前 token（调试用） |
+
+```ts
+await sdk.auth.login({
+  code: 'wx-code',         // wx/tt 的 login code，或 guest 的设备标识
+  platform: 'wx',          // 'wx' | 'tt' | 'guest'，默认 guest
+  deviceId?: 'xxx',        // platform=guest 时必传
+  nickname?: '玩家名',      // 首次登录设置
+});
+```
+
+### `sdk.score` — 分数
+
+| 方法 | 说明 |
+|---|---|
+| `submit(opts)` | 提交分数，返回 `{ isHighScore, previousBest, bestScore, rank }` |
+
+```ts
+const r = await sdk.score.submit({
+  score: 1000,
+  extra?: { maxLevel: 5 },     // 游戏自定义数据
+  metadata?: { seed: 'xxx' },  // 反作弊元数据
+});
+// r.submitted / r.isHighScore / r.previousBest / r.bestScore / r.rank
+```
+
+### `sdk.leaderboard` — 排行榜
+
+| 方法 | 说明 |
+|---|---|
+| `top(limit?)` | 获取 Top N（匿名可访问，默认 100） |
+| `myRank()` | 获取当前玩家排名（需登录） |
+| `nearby(range?)` | 获取附近排名（需登录，默认 ±5） |
+
+### `sdk.player` — 玩家档案
+
+| 方法 | 说明 |
+|---|---|
+| `getProfile()` | 获取当前玩家档案 |
+| `updateProfile(patch)` | 更新昵称/头像/扩展字段 |
+
+### `sdk.save` — 云存档（KV）
+
+| 方法 | 说明 |
+|---|---|
+| `set(key, value)` | 保存数据到指定 key |
+| `get(key)` | 读取指定 key |
+| `getAll()` | 读取所有存档 |
+| `remove(key)` | 删除指定 key |
+| `clear()` | 清空所有存档 |
+
+```ts
+// 存进度
+await sdk.save.set('progress', { level: 5, coins: 100 });
+const progress = await sdk.save.get('progress');
+```
+
+## 运行环境检测
+
+SDK 会自动检测当前环境：
+
+| 环境 | 检测条件 | HTTP 实现 | 存储实现 |
+|---|---|---|---|
+| 微信小游戏 | `typeof wx !== 'undefined'` | `wx.request` | `wx.setStorageSync` |
+| 抖音小游戏 | `typeof tt !== 'undefined'` | `tt.request` | `tt.setStorageSync` |
+| H5 浏览器 | 其他 | `fetch` | `localStorage` |
+
+无需手动指定，SDK 自动适配。
+
+## 服务端
+
+本 SDK 配套的通用游戏服务端在 [`apps/game-server-shared`](https://github.com/Chuang0516/game-factory/tree/main/apps/game-server-shared)（NestJS + MongoDB），提供：
+
+- 多租户数据隔离（按 `gameId`）
+- 身份（微信/抖音 code2session + JWT）/ 访客模式
+- 分数 + 排行榜（Top / 我的排名 / 附近玩家）
+- 云存档（KV）
+- 玩家档案 + 封禁管理
+- Admin 运营接口
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,161 @@
+/**
+ * Game SDK 类型定义
+ * 与 game-server-shared 接口契约一一对应
+ */
+type Platform = 'wx' | 'tt' | 'guest';
+/** SDK 配置 */
+interface GameSdkConfig {
+    /** 游戏 ID（在平台后台登记） */
+    gameId: string;
+    /** api-server 根地址（如 https://api.example.com） */
+    baseUrl: string;
+    /** 模拟模式（不连服务端，返回假数据，用于模板开发） */
+    mock?: boolean;
+}
+interface LoginOptions {
+    /** 登录凭据：wx/tt 的 code，或 guest 的设备标识 */
+    code: string;
+    platform?: Platform;
+    /** 访客设备 ID（platform=guest 时必传） */
+    deviceId?: string;
+    nickname?: string;
+    avatarUrl?: string;
+}
+interface LoginResult {
+    token: string;
+    openId: string;
+    isNew: boolean;
+    profile: PlayerProfile;
+}
+interface PlayerProfile {
+    openId: string;
+    platform: Platform;
+    nickname: string;
+    avatarUrl?: string;
+    bestScore: number;
+    playCount: number;
+    createdAt: string;
+    lastSeenAt: string;
+}
+interface SubmitScoreOptions {
+    score: number;
+    /** 游戏自定义扩展数据（如 maxLevel、通关时间） */
+    extra?: Record<string, any>;
+    /** 反作弊元数据 */
+    metadata?: Record<string, any>;
+}
+interface SubmitScoreResult {
+    submitted: number;
+    isHighScore: boolean;
+    previousBest: number;
+    bestScore: number;
+    rank: number;
+}
+interface LeaderboardEntry {
+    rank: number;
+    openId: string;
+    nickname: string;
+    avatarUrl?: string;
+    score: number;
+    isSelf?: boolean;
+}
+interface MyRank {
+    rank: number;
+    score: number;
+    totalPlayers: number;
+    playCount?: number;
+}
+interface SaveEntry {
+    key: string;
+    value: Record<string, any>;
+    updatedAt: string;
+}
+
+/**
+ * @game-factory/game-sdk
+ *
+ * 通用游戏 SDK，封装 game-server-shared 所有 HTTP 接口。
+ *
+ * 用法（工程化）：
+ *   import { createGameSdk } from '@game-factory/game-sdk';
+ *   const sdk = createGameSdk({ gameId: 'merge-game', baseUrl: 'https://api.example.com' });
+ *   await sdk.auth.login({ code: 'xxx', platform: 'wx' });
+ *   await sdk.score.submit({ score: 1000 });
+ *
+ * 用法（CDN）：
+ *   <script src="https://cdn.example.com/game-sdk/index.umd.js"></script>
+ *   const sdk = GameSDK.createGameSdk({ gameId: 'merge-game', baseUrl: '...' });
+ *
+ * 用法（模拟模式，不连服务端）：
+ *   const sdk = createGameSdk({ gameId: 'demo', baseUrl: '', mock: true });
+ */
+
+declare class GameSdkError extends Error {
+    status: number;
+    data?: any | undefined;
+    constructor(message: string, status: number, data?: any | undefined);
+}
+interface GameSdk {
+    /** 身份与登录 */
+    auth: {
+        /** 登录（微信/抖音/访客），成功后自动持久化 token */
+        login(opts: LoginOptions): Promise<LoginResult>;
+        /** 获取当前登录玩家信息（需先 login） */
+        me(): Promise<PlayerProfile>;
+        /** 登出，清除本地 token */
+        logout(): void;
+        /** 获取当前 token（用于调试） */
+        getToken(): string | null;
+    };
+    /** 分数 */
+    score: {
+        /** 提交分数（需登录） */
+        submit(opts: SubmitScoreOptions): Promise<SubmitScoreResult>;
+    };
+    /** 排行榜 */
+    leaderboard: {
+        /** 获取 Top N（匿名可访问，limit 默认 100） */
+        top(limit?: number): Promise<LeaderboardEntry[]>;
+        /** 获取当前玩家排名（需登录） */
+        myRank(): Promise<MyRank>;
+        /** 获取附近排名（需登录，range 默认 ±5） */
+        nearby(range?: number): Promise<LeaderboardEntry[]>;
+    };
+    /** 玩家档案 */
+    player: {
+        /** 获取当前玩家档案（需登录） */
+        getProfile(): Promise<PlayerProfile>;
+        /** 更新档案（昵称/头像/扩展字段） */
+        updateProfile(patch: {
+            nickname?: string;
+            avatarUrl?: string;
+            extra?: Record<string, any>;
+        }): Promise<PlayerProfile>;
+    };
+    /** 云存档（KV） */
+    save: {
+        /** 保存数据到指定 key */
+        set(key: string, value: Record<string, any>): Promise<{
+            success: boolean;
+            key: string;
+            value: Record<string, any>;
+        }>;
+        /** 读取指定 key 的数据 */
+        get(key: string): Promise<Record<string, any> | null>;
+        /** 读取所有存档 */
+        getAll(): Promise<Record<string, any>>;
+        /** 删除指定 key */
+        remove(key: string): Promise<{
+            success: boolean;
+            key: string;
+        }>;
+        /** 清空所有存档 */
+        clear(): Promise<{
+            success: boolean;
+            deleted: number;
+        }>;
+    };
+}
+declare function createGameSdk(config: GameSdkConfig): GameSdk;
+
+export { type GameSdk, type GameSdkConfig, GameSdkError, type LeaderboardEntry, type LoginOptions, type LoginResult, type MyRank, type Platform, type PlayerProfile, type SaveEntry, type SubmitScoreOptions, type SubmitScoreResult, createGameSdk };

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Game SDK 类型定义
+ * 与 game-server-shared 接口契约一一对应
+ */
+type Platform = 'wx' | 'tt' | 'guest';
+/** SDK 配置 */
+interface GameSdkConfig {
+    /** 游戏 ID（在平台后台登记） */
+    gameId: string;
+    /** api-server 根地址（如 https://api.example.com） */
+    baseUrl: string;
+    /** 模拟模式（不连服务端，返回假数据，用于模板开发） */
+    mock?: boolean;
+}
+interface LoginOptions {
+    /** 登录凭据：wx/tt 的 code，或 guest 的设备标识 */
+    code: string;
+    platform?: Platform;
+    /** 访客设备 ID（platform=guest 时必传） */
+    deviceId?: string;
+    nickname?: string;
+    avatarUrl?: string;
+}
+interface LoginResult {
+    token: string;
+    openId: string;
+    isNew: boolean;
+    profile: PlayerProfile;
+}
+interface PlayerProfile {
+    openId: string;
+    platform: Platform;
+    nickname: string;
+    avatarUrl?: string;
+    bestScore: number;
+    playCount: number;
+    createdAt: string;
+    lastSeenAt: string;
+}
+interface SubmitScoreOptions {
+    score: number;
+    /** 游戏自定义扩展数据（如 maxLevel、通关时间） */
+    extra?: Record<string, any>;
+    /** 反作弊元数据 */
+    metadata?: Record<string, any>;
+}
+interface SubmitScoreResult {
+    submitted: number;
+    isHighScore: boolean;
+    previousBest: number;
+    bestScore: number;
+    rank: number;
+}
+interface LeaderboardEntry {
+    rank: number;
+    openId: string;
+    nickname: string;
+    avatarUrl?: string;
+    score: number;
+    isSelf?: boolean;
+}
+interface MyRank {
+    rank: number;
+    score: number;
+    totalPlayers: number;
+    playCount?: number;
+}
+interface SaveEntry {
+    key: string;
+    value: Record<string, any>;
+    updatedAt: string;
+}
+
+/**
+ * @game-factory/game-sdk
+ *
+ * 通用游戏 SDK，封装 game-server-shared 所有 HTTP 接口。
+ *
+ * 用法（工程化）：
+ *   import { createGameSdk } from '@game-factory/game-sdk';
+ *   const sdk = createGameSdk({ gameId: 'merge-game', baseUrl: 'https://api.example.com' });
+ *   await sdk.auth.login({ code: 'xxx', platform: 'wx' });
+ *   await sdk.score.submit({ score: 1000 });
+ *
+ * 用法（CDN）：
+ *   <script src="https://cdn.example.com/game-sdk/index.umd.js"></script>
+ *   const sdk = GameSDK.createGameSdk({ gameId: 'merge-game', baseUrl: '...' });
+ *
+ * 用法（模拟模式，不连服务端）：
+ *   const sdk = createGameSdk({ gameId: 'demo', baseUrl: '', mock: true });
+ */
+
+declare class GameSdkError extends Error {
+    status: number;
+    data?: any | undefined;
+    constructor(message: string, status: number, data?: any | undefined);
+}
+interface GameSdk {
+    /** 身份与登录 */
+    auth: {
+        /** 登录（微信/抖音/访客），成功后自动持久化 token */
+        login(opts: LoginOptions): Promise<LoginResult>;
+        /** 获取当前登录玩家信息（需先 login） */
+        me(): Promise<PlayerProfile>;
+        /** 登出，清除本地 token */
+        logout(): void;
+        /** 获取当前 token（用于调试） */
+        getToken(): string | null;
+    };
+    /** 分数 */
+    score: {
+        /** 提交分数（需登录） */
+        submit(opts: SubmitScoreOptions): Promise<SubmitScoreResult>;
+    };
+    /** 排行榜 */
+    leaderboard: {
+        /** 获取 Top N（匿名可访问，limit 默认 100） */
+        top(limit?: number): Promise<LeaderboardEntry[]>;
+        /** 获取当前玩家排名（需登录） */
+        myRank(): Promise<MyRank>;
+        /** 获取附近排名（需登录，range 默认 ±5） */
+        nearby(range?: number): Promise<LeaderboardEntry[]>;
+    };
+    /** 玩家档案 */
+    player: {
+        /** 获取当前玩家档案（需登录） */
+        getProfile(): Promise<PlayerProfile>;
+        /** 更新档案（昵称/头像/扩展字段） */
+        updateProfile(patch: {
+            nickname?: string;
+            avatarUrl?: string;
+            extra?: Record<string, any>;
+        }): Promise<PlayerProfile>;
+    };
+    /** 云存档（KV） */
+    save: {
+        /** 保存数据到指定 key */
+        set(key: string, value: Record<string, any>): Promise<{
+            success: boolean;
+            key: string;
+            value: Record<string, any>;
+        }>;
+        /** 读取指定 key 的数据 */
+        get(key: string): Promise<Record<string, any> | null>;
+        /** 读取所有存档 */
+        getAll(): Promise<Record<string, any>>;
+        /** 删除指定 key */
+        remove(key: string): Promise<{
+            success: boolean;
+            key: string;
+        }>;
+        /** 清空所有存档 */
+        clear(): Promise<{
+            success: boolean;
+            deleted: number;
+        }>;
+    };
+}
+declare function createGameSdk(config: GameSdkConfig): GameSdk;
+
+export { type GameSdk, type GameSdkConfig, GameSdkError, type LeaderboardEntry, type LoginOptions, type LoginResult, type MyRank, type Platform, type PlayerProfile, type SaveEntry, type SubmitScoreOptions, type SubmitScoreResult, createGameSdk };