# @globalleaderboards/sdk 中文文档

规范地址：https://npmcn.com/package/%40globalleaderboards/sdk/

版本：0\.5\.0
npm 元数据更新时间：2025-08-01T08:53:24.465Z
中文译文更新时间：2026-11-16T16:10:42.084Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40globalleaderboards/sdk
原文对照：https://npmcn.com/package/%40globalleaderboards/sdk/?lang=original
项目主页：https://globalleaderboards.net/
源码仓库：https://github.com/GlobalLeaderboards/sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：430 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.0\.0
- 运行依赖：1 个
- 首次发布：2025-07-26T00:39:51.017Z
- 最新版本发布：2025-08-01T08:53:24.271Z
- 近 30 天下载量：3985（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 0 个）

## 中文简介

GlobalLeaderboards.net的官方SDK - 在任何应用程序中加入竞争性领导牌

## 安装

```sh
npm install @globalleaderboards/sdk
```

也可以使用：`pnpm add @globalleaderboards/sdk`、`yarn add @globalleaderboards/sdk`、`bun add @globalleaderboards/sdk`

## README

# @ globalleaderboards/ sdk 页面存档备份,存于互联网档案馆

GlobalLeaderboards.net的官方SDK - 任意添加竞争性领导板 5分钟后申请.

## 安装

```bash
npm install @globalleaderboards/sdk
# or
yarn add @globalleaderboards/sdk
# or
pnpm add @globalleaderboards/sdk
```

## 认证

SDK采用行业标准 `Authorization: Bearer <api-key>` 标题 认证。 您的 API 密钥可以从 Global Leader boards 获取 仪表板。 每个 API 密钥与一个特定的应用程序相关联,确保适当的数据 隔离.

```javascript
const leaderboard = new GlobalLeaderboards('your-api-key')
```

## 快速启动

```javascript
import {GlobalLeaderboards} from '@globalleaderboards/sdk'

// Initialize the SDK
const leaderboard = new GlobalLeaderboards('your-api-key', {
  defaultLeaderboardId: 'your-default-leaderboard' // Optional
})

// Submit a score - three ways
await leaderboard.submit('player-id', 1250) // Uses default leaderboard
await leaderboard.submit('player-id', 1250, 'specific-leaderboard')
await leaderboard.submit('player-id', 1250, {
  leaderboardId: 'your-leaderboard-id',
  userName: 'PlayerOne',
  metadata: { level: 5 }
})

// Get leaderboard
const scores = await leaderboard.getLeaderboard('your-leaderboard-id', {
  limit: 10
})

// Connect to real-time updates

// Recommended: Server-Sent Events (simpler, auto-reconnect, firewall-friendly)
const sse = leaderboard.connectSSE('your-leaderboard-id', {
  onLeaderboardUpdate: (data) => {
    // Same enhanced format as WebSocket
    console.log('Full leaderboard:', data.leaderboard.entries)
    console.log('What changed:', data.mutations)
    console.log('Triggered by:', data.trigger)
  }
})

// Alternative: WebSocket (only use if you specifically need WebSocket compatibility)
// Note: Currently only receives updates, doesn't send data to server
const ws = leaderboard.connectWebSocket({
  onLeaderboardUpdate: (data) => {
    // New enhanced format with full state and mutations
    console.log('Full leaderboard:', data.leaderboard.entries) // Top 100 entries
    console.log('What changed:', data.mutations) // Array of changes
    console.log('Triggered by:', data.trigger) // What caused the update
  },
  onUserRankUpdate: (data) => {
    console.log('Rank changed:', data)
  }
})
ws.subscribe('your-leaderboard-id')

```

## 特征

-   🚀 **简单 API** - 几分钟后开始
-   🌍 **全球业绩** - 全世界响应次数 < 100ms
-   🔄 **实时更新** - WebSocket和SSE对领导牌直播的支持
-   📱 **离线支持** - 离线时自动排队 存储. sync
-   🛡️ **类型安全** - 全部类型脚本支持
-   🔒 **安全** - API 密钥认证,并限制费率
-   🎮 **游戏准备** - 为游戏和竞争性应用程序所建
-   🏗️ **可靠性** - 自动重试和错误处理

## API 参考

### 构造器

```javascript
const leaderboard = new GlobalLeaderboards(apiKey, options)
```

**参数:**

-   `apiKey` (字符串,需要) - 您的 API 密钥来自 Global Leaderboards.net
-   `options` (对象,可选) - 配置选项

**选项 :**

-   `defaultLeaderboardId` (字符串) - 用于简化提交()调用的默认领导板
-   `baseUrl` (字符串) - API 基础 URL( 默认 : `https://api.globalleaderboards.net`(中文(简体) )
-   `wsUrl` (字符串) - WebSocket URL(默认: `wss://api.globalleaderboards.net`(中文(简体) )
-   `timeout` (数字) - 请求超时 ms( 默认 ): `30000`(中文(简体) )
-   `autoRetry` (boolean) - 启用自动重试( 默认 ): `true`(中文(简体) )
-   `maxRetries` (数字) - 最大重试尝试( 默认 ): `3`(中文(简体) )

### 计分方法

#### 提交( 用户ID、 分数、 选项)

将分数提交有验证的导板 .

```javascript
const result = await leaderboard.submit('user-123', 1500, {
  leaderboardId: 'leaderboard-456',
  userName: 'PlayerOne',
  metadata: {level: 5, character: 'warrior'}
})

// Returns: { operation: 'insert', rank: 42, previous_score?: 1000, improvement?: 500 }
```

**参数:**

-   `userId` (字符串) - 唯一用户标识符
-   `score` (数量) - 分数值(必须是 QQ 0)
-   `options.leaderboardId` (字符串) - 目标头板ID
-   `options.userName` (字符串) - 显示名称(1-50个字符,字母数字+) 发音)
-   `options.metadata` (对象) - 可选元数据

#### 提交分数( playerId, 分数, 领导板Id?, 选项 ?)

简化分数提交 API.

```javascript
// Using default leaderboard from config
await leaderboard.submitScore('player-123', 2500)

// Or specify leaderboard
await leaderboard.submitScore('player-123', 2500, 'leaderboard-456')
```

#### 提交 Bulk( 提交)

以灵活格式提交多个分数。 智能分批按领导板.

```javascript
const results = await leaderboard.submitBulk([
  // Array format with default leaderboard
  ['user-123', 1000],
  
  // Array format with specific leaderboard
  ['user-456', 2000, 'leaderboard-789'],
  
  // Full object format
  {
    userId: 'user-789',
    score: 3000,
    leaderboardId: 'leaderboard-789',
    userName: 'TopPlayer',
    metadata: { level: 10 }
  }
])

// Returns: { results: [...], summary: { total: 3, successful: 3, failed: 0 } }
```

**参数:**

-   `submissions` - 以上述任何一种形式提交材料的组合:
    -   `[userId, score]` - 使用默认标头板
    -   `[userId, score, leaderboardId]`
    -   有完整选项的对象

### 领导板方法

#### 获得领导板( 领导板, 选项 )

获取 Pagation 领导板条目 .

```javascript
const data = await leaderboard.getLeaderboard('leaderboard-456', {
  page: 1,
  limit: 20,
  aroundUser: 'user-123' // Center results around this user
})

// Returns: { data: [...], pagination: {...}, leaderboard: {...} }
```

**选项 :**

-   `page` (数目) - 页号(默认:1)
-   `limit` (数目) - 每页结果(默认:20,最大:100)
-   `aroundUser` (字符串) - 中心结果围绕特定用户

#### 获取用户评分( 用户ID, 选项)

为用户获得所有分数 .

```javascript
const userScores = await leaderboard.getUserScores('user-123', {
  page: 1,
  limit: 50
})

// Returns: { data: [...], pagination: {...}, user: { total_scores: 10, best_rank: 1 } }
```

### 卫生和信息方法

#### 卫生()

基本健康检查(不需要认证).

```javascript
const health = await leaderboard.health()
// Returns: { status: 'healthy', version: '0.1.10', timestamp: '...' }
```

#### 详细健康( )

附有服务状况的详细健康检查(不需要认证).

```javascript
const detailed = await leaderboard.healthDetailed()
// Returns: { 
//   status: 'healthy',
//   services: { database: {...}, cache: {...}, storage: {...} },
//   system: { memoryUsage: 128, uptime: 3600, environment: 'production' }
// }
```

#### 获取 ApiInfo ()

获取API信息和可用的端点(不需要认证).

```javascript
const info = await leaderboard.getApiInfo()
// Returns API version, endpoints, documentation URL, etc.
```

### 服务器事件方法

服务器- Sent Evolution 提供了WebSocket接收的更简单的替代品 实时更新。 SSE是理想的,只要您需要从中获取更新 服务器(单向通信).

#### 连接 SSE( 铅板ID、 处理器、 选项 )

连接到领导板的SSE流进行实时更新.

```javascript
const connection = leaderboard.connectSSE('leaderboard-456', {
  onConnect: () => {
    console.log('SSE connected')
  },
  onLeaderboardUpdate: (data) => {
    // Enhanced format with full state and mutations (same as WebSocket)
    console.log('Full leaderboard:', data.leaderboard.entries) // Top 100 entries
    console.log('What changed:', data.mutations) // Array of changes
    console.log('Triggered by:', data.trigger) // What caused the update
  },
  onError: (error) => {
    console.error('SSE error:', error)
  },
  onDisconnect: () => {
    console.log('SSE disconnected')
  }
}, {
  userId: 'user-123',              // For personalized updates
  includeMetadata: true,           // Include metadata in updates
  topN: 10                         // Number of top scores in refresh events
})

// Later: close the connection
connection.close()
```

**事件处理器 :**

-   `onConnect` - 已建立连接
-   `onDisconnect` - 连接已关闭
-   `onError` - 发生了错误
-   `onLeaderboardUpdate` - 用增强格式更改了领导板数据(见下文增强信件格式)
-   `onHeartbeat` - 服务器发出的动态信号(可选)
-   `onMessage` - 原始信件处理器(可选)

**选项 :**

-   `userId` - 个人化等级更新用户ID
-   `includeMetadata` - 在分数更新中包含元数据( 默认: 真)
-   `topN` - 刷新事件包含的最高分数( 默认: 10)

#### 断开SSE ()

断开所有SSE连接.

```javascript
leaderboard.disconnectSSE()
```

#### 增强 SSE 信件格式

**V.5.27中的新内容**:SSE和WebSocket现在都使用相同的增强消息格式. 这个 `onLeaderboardUpdate` 处理器接收 :

```javascript
{
  leaderboardId: "01K1AKF9NMZFX8FK8XA81QYK2J",
  updateType: "score_update", // or "full_refresh", "bulk_update"
  
  // Complete current state (top 100 entries)
  leaderboard: {
    entries: [
      {
        rank: 1,
        userId: "user123",
        userName: "Alice",
        score: 1000,
        timestamp: "2025-07-29T08:15:37.197Z",
        metadata: { /* custom data */ }
      },
      // ... up to 100 entries
    ],
    totalEntries: 150,
    displayedEntries: 100
  },
  
  // What changed (for animations)
  mutations: [
    {
      type: "new_entry",
      userId: "user456",
      newRank: 3,
      score: 850,
      userName: "Bob"
    },
    {
      type: "rank_change",
      userId: "user789",
      previousRank: 3,
      newRank: 4,
      score: 800
    }
    // ... other mutations
  ],
  
  // What triggered this update
  trigger: {
    type: "score_submission",
    submissions: [
      {
        userId: "user123",
        userName: "Alice",
        score: 1000,
        previousScore: 950,
        timestamp: "2025-07-29T08:15:37.197Z"
      }
    ]
  },
  
  sequence: 42 // For ordering/deduplication
}
```

### 网络安全套方法

**说明:** SSE和WebSocket都收到相同的增强消息格式. SSE被推荐给大多数使用的案例,因为它更简单更方便防火墙.

#### 连接WebSocket( 处理器, 选项 )

通过WebSocket连接到实时更新.

```javascript
const ws = leaderboard.connectWebSocket({
  onConnect: () => console.log('Connected'),
  onDisconnect: (code, reason) => console.log('Disconnected'),
  onError: (error) => console.error('Error:', error),
  onLeaderboardUpdate: (data) => console.log('Leaderboard update:', data),
  onUserRankUpdate: (data) => console.log('Rank changed:', data),
  onMessage: (message) => console.log('Raw message:', message)
}, {
  leaderboardId: 'leaderboard-456',
  userId: 'user-123',
  maxReconnectAttempts: 5,
  reconnectDelay: 1000
})
```

**处理者 :**

-   `onConnect` - 建立联系时呼叫
-   `onDisconnect` - 连接关闭时调用
-   `onError` - 找错人了
-   `onLeaderboardUpdate` - 当领导板数据改变时调用(见下文增强信件格式)
-   `onUserRankUpdate` - 当用户的级别改变时调用
-   `onMessage` - 请求任何 WebSocket 消息
-   `onReconnecting` - 启动重联尝试时调用(包括尝试号、最大尝试和下一次延迟)

**重新连接特征 :**

WebSocket客户端包括智能重联:

-   **网络检测** - 离线时自动暂停,在线时恢复
-   **标志性反转** - 延迟与每次尝试的两倍(1,2,4,8...)
-   **抖动** - ±25%随机化可防止雷击群
-   **永久错误处理** - 在认证失败后不会重试
-   **手动控制** - 使用( I) `ws.reconnect()` 用于自定义重试逻辑

```javascript
// Example: Handling reconnection events
const ws = leaderboard.connectWebSocket({
  onReconnecting: (attempt, maxAttempts, nextDelay) => {
    console.log(`Reconnecting... Attempt ${attempt}/${maxAttempts}`)
    console.log(`Next attempt in ${nextDelay}ms`)
    // Show reconnection UI to user
  },
  onConnect: () => {
    console.log('Connected!')
    // Hide reconnection UI
  }
})
```

#### 增强的 WebSocket 信件格式

**V.5.27中的新内容**编号: `onLeaderboardUpdate` 处理器现在收到一个增强后的信件格式, 并带有完整的领导板状态和详细的突变 :

```javascript
{
  leaderboardId: "01K1AKF9NMZFX8FK8XA81QYK2J",
  updateType: "score_update", // or "full_refresh", "bulk_update"
  
  // Complete current state (top 100 entries)
  leaderboard: {
    entries: [
      {
        rank: 1,
        userId: "user123",
        userName: "Alice",
        score: 1000,
        timestamp: "2025-07-29T08:15:37.197Z",
        metadata: { /* custom data */ }
      },
      // ... up to 100 entries
    ],
    totalEntries: 150,
    displayedEntries: 100
  },
  
  // What changed (for animations)
  mutations: [
    {
      type: "new_entry",
      userId: "user456",
      newRank: 3,
      score: 850,
      userName: "Bob"
    },
    {
      type: "rank_change",
      userId: "user789",
      previousRank: 3,
      newRank: 4,
      score: 800
    },
    {
      type: "score_update",
      userId: "user123",
      previousScore: 950,
      newScore: 1000,
      previousRank: 2,
      newRank: 1
    },
    {
      type: "username_change",
      userId: "user111",
      previousUsername: "Player111",
      newUsername: "ProPlayer",
      rank: 5
    },
    {
      type: "removed",
      userId: "user999",
      previousRank: 100,
      score: 100
    }
  ],
  
  // What triggered this update
  trigger: {
    type: "score_submission", // or "bulk_submission", "admin_action", "leaderboard_reset"
    submissions: [
      {
        userId: "user123",
        userName: "Alice",
        score: 1000,
        previousScore: 950,
        timestamp: "2025-07-29T08:15:37.197Z"
      }
    ]
  },
  
  sequence: 42 // For ordering/deduplication
}
```

**突变类型 :**

-   `new_entry` - 用户之前不在领导板上
-   `rank_change` - 用户的级别改变(但得分没有)
-   `score_update` - 用户的分数改变(也可能改变等级)
-   `username_change` - 用户的显示名已更改
-   `removed` - 用户退出已显示条目

**动画使用突变 :**

```javascript
ws.onLeaderboardUpdate = (data) => {
  // Update display with full state
  updateLeaderboard(data.leaderboard.entries)
  
  // Animate changes
  data.mutations.forEach(mutation => {
    switch(mutation.type) {
      case 'new_entry':
        animateNewEntry(mutation.userId, mutation.newRank)
        break
      case 'rank_change':
        animateRankChange(mutation.userId, mutation.previousRank, mutation.newRank)
        break
      case 'score_update':
        animateScoreUpdate(mutation.userId, mutation.previousScore, mutation.newScore)
        break
    }
  })
}
```

#### 断开WebSocket ()

从 WebSocket 断开连接 .

```javascript
leaderboard.disconnectWebSocket()
```

### 网页实例方法

一旦连接, 在 WebSocket 实例中使用这些方法 :

#### 订阅( 领导板 Id, userId? )

订阅领导板更新 .

```javascript
ws.subscribe('leaderboard-456', 'user-123')
```

#### 未订阅( 领导板) (d) 国家

从头板更新取消订阅 .

```javascript
ws.unsubscribe('leaderboard-456')
```

#### 断开( )

关闭 WebSocket 连接 .

```javascript
ws.disconnect()
```

#### 重新连接( c)

手动触发重接尝试. 用于执行自定义重试逻辑 .

```javascript
try {
  ws.reconnect()
} catch (error) {
  // Will throw if offline or permanent error occurred
  console.error('Cannot reconnect:', error.message)
}
```

### SSE 对 WebSocket

为您的使用选择正确的实时技术 :

| 特性 | 证监会 | 网络安全套 |
| --- | --- | --- |
| 通讯 | 单向(服务器-客户端) | 双向(双向)\* |
| 复杂性 | 简单 | 更为复杂 |
| 浏览器支持 | 不错 | 不错 |
| 自动重接 | 内建 | 手动 |
| 防火墙友好 | 对 | 有时被封锁 |
| 使用大小写 | 显示更新 | 互动特性\* |

\*注:目前的WebSocket执行只接收数据,不向服务器发送命令.

**为什么要推荐SSE:**

由于我们的 WebSocket 执行目前只接收更新(没有发送能力),SSE 提供相同的功能有:

-   更简单的执行
-   自动重接
-   更好的防火墙/代理兼容性
-   资源使用减少
-   容易调试

**当 :**

-   您需要实时领导板更新
-   你想要最简单的融合
-   防火墙/代理兼容性很重要
-   你正在建造一个唯一的显示板

**当 :**

-   您特别需要WebSocket来兼容现有的基础设施
-   您已经在应用程序的其他地方使用 WebSocket
-   计划未来双向功能(目前没有)

### 方法

#### 生成Id ()

生成新的 ULID( 通用唯一可排序的 Lexic 标识符) .

```javascript
const id = leaderboard.generateId()
// Returns: '01ARZ3NDEKTSV4RRFFQ69G5FAV'
```

## 离线支持

SDK提供强力下线支持,自动排队并同步提交分数. 当应用程序下线时,分数会自动排队并持续,然后在恢复连接时同步.

### 如何运作

1.  **自动检测**: SDK 使用浏览器 API 监视网络连接
2.  **智能排队**: 离线时, `submit()` 操作立即返回已排队的响应
3.  **持久性存储**:队列被保存到chrome.storage.sync(带有本地Storage倒置)
4.  **自动同步**: 返回在线时自动排队
5.  **智能击打**: 同一主板的多分分数一起分出

### 基本用途

```javascript
// Score submission works seamlessly online or offline
const result = await leaderboard.submit('user-123', 1000, {
  leaderboardId: 'game-scores',
  userName: 'Player'
})

// When offline, you'll get a queued response
if (result.queued) {
  console.log(`Score queued with ID: ${result.queueId}`)
  console.log(`Queue position: ${result.queuePosition}`)
}
```

### 队列事件监测

```javascript
// Monitor queue events
leaderboard.on('queue:added', (data) => {
  console.log('Score queued:', data)
})

leaderboard.on('queue:processed', (data) => {
  console.log('Queued score submitted:', data)
})

leaderboard.on('queue:failed', (data) => {
  console.log('Queued score failed:', data)
  // data.permanent indicates if the failure is permanent (won't retry)
})

leaderboard.on('queue:progress', (data) => {
  console.log(`Progress: ${data.processed}/${data.total}`)
})
```

### 队列管理

```javascript
// Check queue status
const status = leaderboard.getQueueStatus()
console.log(`Queue size: ${status.size}`)
console.log(`Processing: ${status.processing}`)
console.log('Queued items:', status.items)

// Manually trigger queue processing
await leaderboard.processQueue()

// Clear the queue (use with caution)
// Note: This requires direct access to offlineQueue
// leaderboard.offlineQueue.clear()
```

### 存储细节

下行队列使用混合存储方式:

1.  **Chrome 扩展环境**: 用途 `chrome.storage.sync` 用于交叉设备同步
2.  **普通网络环境**: 倒计时 `localStorage` 持久性
3.  **存储密钥**: 使用散列孤立的每个 API 密钥(`gl_queue_${hash}`(中文(简体) )

### 队列限制和行为

-   **最大队列大小**: 1 000件物品
-   **项目 TTL**: 24小时(过期物品自动清理)
-   **批量大小**: 每批最多100分
-   **重试逻辑**: 以增量重试计数重试提交失败
-   **永久失败**: 401, 403, 404 个错误标记项目为永久失效

### 高级示例

```javascript
// Complete offline-capable game integration
class OfflineCapableGame {
  constructor(apiKey) {
    this.leaderboard = new GlobalLeaderboards(apiKey)
    this.setupQueueMonitoring()
  }

  setupQueueMonitoring() {
    // Show UI indicator when scores are queued
    this.leaderboard.on('queue:added', (data) => {
      this.showNotification('Score saved offline - will sync when online')
    })

    // Update UI when scores are synced
    this.leaderboard.on('queue:processed', (data) => {
      this.showNotification('Offline scores synced!')
    })

    // Handle permanent failures
    this.leaderboard.on('queue:failed', (data) => {
      if (data.permanent) {
        this.showError('Score sync failed permanently')
      }
    })

    // Show sync progress
    this.leaderboard.on('queue:progress', (data) => {
      const percent = (data.processed / data.total) * 100
      this.updateProgressBar(percent)
    })
  }

  async submitScore(score) {
    try {
      const result = await this.leaderboard.submit(
        this.playerId,
        score,
        {
          leaderboardId: this.leaderboardId,
          userName: this.playerName
        }
      )

      if (result.queued) {
        // Score was queued for later
        return { 
          success: true, 
          offline: true, 
          queueId: result.queueId 
        }
      } else {
        // Score was submitted immediately
        return { 
          success: true, 
          offline: false, 
          rank: result.rank 
        }
      }
    } catch (error) {
      return { success: false, error: error.message }
    }
  }
}
```

### 重要说明

-   **散装操作**:目前,提交批量分数`submitBulk()`) 离线时不排队,并将丢出错误
-   **队列处理**:重新连接时自动发生,不需要人工干预
-   **数据完整性**: 分数永远不会丢失 - 要么成功提交,要么保持队列
-   **业绩**: 队列操作是同步操作, 不会屏蔽您的应用程序

## 处理错误

SDK抛出 `GlobalLeaderboardsError` 对所有 API 错误 :

```javascript
try {
  await leaderboard.submit('user-123', -100, {
    leaderboardId: 'leaderboard-456'
  })
} catch (error) {
  if (error instanceof GlobalLeaderboardsError) {
    console.error('Error:', error.message)
    console.error('Code:', error.code)
    console.error('Status:', error.statusCode)
    console.error('Details:', error.details)
  }
}
```

### 常见错误代码

-   `INVALID_SCORE` - 分数验证失败
-   `INVALID_USERNAME` - 用户名验证失败
-   `INVALID_USERNAME_LENGTH` - 用户名长度验证失败
-   `MISSING_LEADERBOARD_ID` - 需要头板身份证明
-   `TIMEOUT` - 请求超时
-   `HEALTH_CHECK_FAILED` - 健康检查失败
-   `WS_NOT_CONNECTED` - WebSocket 没有连接
-   `WS_MAX_RECONNECT` - 实现最大重联尝试

## 类型脚本支持

SDK是用 TypeScript 编写的, 提供了完整的类型定义 :

```typescript
import {
  GlobalLeaderboards,
  SubmitScoreResponse,
  LeaderboardEntriesResponse,
  LeaderboardEntry,
  GlobalLeaderboardsError,
  SSEScoreUpdateEvent,
  SSELeaderboardRefreshEvent,
  SSEEventHandlers,
  // New WebSocket types
  LeaderboardUpdateMessage,
  LeaderboardMutation,
  NewEntryMutation,
  RankChangeMutation,
  ScoreUpdateMutation,
  UsernameChangeMutation,
  RemovedMutation,
  UpdateTrigger
} from '@globalleaderboards/sdk'

// All methods are fully typed
const leaderboard = new GlobalLeaderboards('api-key')

const response: SubmitScoreResponse = await leaderboard.submit(
  'user-123',
  1000,
  {
    leaderboardId: 'leaderboard-456',
    userName: 'Player'
  }
)

// TypeScript will provide full IntelliSense for mutations
ws.onLeaderboardUpdate = (data: LeaderboardUpdateMessage['payload']) => {
  data.mutations.forEach((mutation: LeaderboardMutation) => {
    if (mutation.type === 'new_entry') {
      // TypeScript knows this is NewEntryMutation
      console.log(mutation.newRank)
    }
  })
}
```

## 实例

### 反应钩子示例

```javascript
import {useEffect, useState} from 'react'
import {GlobalLeaderboards} from '@globalleaderboards/sdk'

function useLeaderboard(leaderboardId) {
  const [entries, setEntries] = useState([])
  const [loading, setLoading] = useState(true)

  const leaderboard = new GlobalLeaderboards(process.env.REACT_APP_API_KEY)

  useEffect(() => {
    // Fetch initial data
    leaderboard.getLeaderboard(leaderboardId, {limit: 10})
      .then(data => {
        setEntries(data.data)
        setLoading(false)
      })

    // Connect to real-time updates
    const ws = leaderboard.connectWebSocket({
      onLeaderboardUpdate: (data) => {
        // New format provides full leaderboard state
        setEntries(data.leaderboard.entries)
        
        // Optionally use mutations for animations
        data.mutations.forEach(mutation => {
          if (mutation.type === 'new_entry') {
            // Animate new entry appearing
          } else if (mutation.type === 'rank_change') {
            // Animate rank movement
          }
        })
      }
    })

    ws.subscribe(leaderboardId)

    return () => ws.disconnect()
  }, [leaderboardId])

  return {entries, loading}
}
```

### SSE 实时显示示例

```javascript
import {GlobalLeaderboards} from '@globalleaderboards/sdk'

function LeaderboardDisplay({leaderboardId}) {
  const [scores, setScores] = useState([])
  const [latestScore, setLatestScore] = useState(null)

  useEffect(() => {
    const leaderboard = new GlobalLeaderboards(process.env.REACT_APP_API_KEY)

    // Connect to SSE for real-time updates
    const connection = leaderboard.connectSSE(leaderboardId, {
      onConnect: () => {
        console.log('Connected to real-time updates')
      },
      onLeaderboardUpdate: (data) => {
        // Update the leaderboard display
        setScores(data.topScores)

        // Show the latest score if available
        if (data.topScores.length > 0) {
          const newestScore = data.topScores[0]
          setLatestScore(newestScore)
        }
      },
      onUserRankUpdate: (data) => {
        // Handle user rank changes if needed
        console.log(`User ${data.userName} rank changed to ${data.newRank}`)
      },
      onError: (error) => {
        console.error('Real-time connection error:', error)
      }
    }, {
      topN: 10  // We're displaying top 10
    })

    // Fetch initial leaderboard
    const fetchLeaderboard = async () => {
      const data = await leaderboard.getLeaderboard(leaderboardId, {limit: 10})
      setScores(data.data)
    }

    fetchLeaderboard()

    // Cleanup on unmount
    return () => connection.close()
  }, [leaderboardId])

  return (
    <div>
      {latestScore && (
        <div className="latest-score">
          New Score: {latestScore.userName} - {latestScore.score}
        </div>
      )}
      <div className="leaderboard">
        {scores.map((entry, index) => (
          <div key={entry.userId}>
            #{entry.rank} {entry.userName} - {entry.score}
          </div>
        ))}
      </div>
    </div>
  )
}
```

### 游戏整合示例

```javascript
class GameLeaderboard {
  constructor(apiKey) {
    this.client = new GlobalLeaderboards(apiKey)
    this.leaderboardId = 'game-highscores'
  }

  async submitGameScore(playerId, playerName, score, level) {
    try {
      const result = await this.client.submit(playerId, score, {
        leaderboardId: this.leaderboardId,
        userName: playerName,
        metadata: {
          level,
          timestamp: Date.now(),
          version: '1.0.0'
        }
      })

      if (result.operation === 'update' && result.improvement > 0) {
        console.log(`New personal best! Improved by ${result.improvement} points`)
      }

      return result
    } catch (error) {
      console.error('Failed to submit score:', error.message)
      throw error
    }
  }

  async getTopPlayers(limit = 10) {
    const data = await this.client.getLeaderboard(this.leaderboardId, {limit})
    return data.data
  }
}
```

## API 利率限制

SDK自动处理速率限制并重试. 现行费率 限制为1,000个请求/分钟.

当速率限制时, SDK 将自动重试, 以指数回放 若为 `autoRetry` 已启用.

## 最佳做法

1.  **重用 SDK 实例** - 创建一个实例并重新使用
2.  **处理错误优雅** - 总是把API的电话包起来
3.  **明智地使用元数据** - 存储关卡、字符等特定游戏数据, 包括:.
4.  **验证客户端** - SDK验证分数和用户名 自动
5.  **订阅更新** - 使用WebSocket进行实时领导板
6.  **生成标识** - 使用( I) `generateId()` 用于一致的ID格式

## 文档

完备的 API 文档 时间 [页面存档备份,存于互联网档案馆. docs.globalleaderboards.net](https://docs.globalleaderboards.net/)

## 支助

-   电子邮件: [gl@smokingmedia.com (英语)](mailto:gl@smokingmedia.com)
-   \* 文档: [https://docs.globalleaderboards.net 页面存档备份,存于互联网档案馆](https://docs.globalleaderboards.net/)
-   问题: [https://github.com/globalleaderboards/sdk/ issues (中文(简体) )](https://github.com/globalleaderboards/sdk/issues)

## 许可证

[麻省理工学院](https://npmcn.com/package/%40globalleaderboards/sdk/LICENSE)

## 常见问题

### @globalleaderboards/sdk 是什么？

GlobalLeaderboards\.net的官方SDK - 在任何应用程序中加入竞争性领导牌

### 如何安装 @globalleaderboards/sdk？

在项目目录运行 npm install @globalleaderboards/sdk，或使用 pnpm add / yarn add / bun add。

### @globalleaderboards/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @globalleaderboards/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @globalleaderboards/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @globalleaderboards/sdk 可以商用吗？

@globalleaderboards/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @globalleaderboards/sdk 的下载量有多少？

根据 npm 官方下载统计，@globalleaderboards/sdk 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,985 次，日均约 133 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @globalleaderboards/sdk 还在维护吗？

最新版本 0\.5\.0 发布于 2025/08/01（1\.3 年前）；至今共发布 16 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/07/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

