Class GlobalLeaderboards

GlobalLeaderboards SDK client for interacting with the GlobalLeaderboards.net API

Example

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

Index

Constructors

constructor

new GlobalLeaderboards(
apiKey: string,
config?: Partial<GlobalLeaderboardsConfig>,
): GlobalLeaderboards
Create a new GlobalLeaderboards SDK instance
Parameters
- apiKey: string
  Your API key from GlobalLeaderboards.net
- Optionalconfig: Partial<GlobalLeaderboardsConfig>
  Optional configuration options
  - defaultLeaderboardId
    Default leaderboard ID for simplified submit() calls
  - baseUrl
    API base URL (default: https://api.globalleaderboards.net)
  - wsUrl
    WebSocket URL (default: wss://api.globalleaderboards.net)
  - timeout
    Request timeout in ms (default: 30000)
  - autoRetry
    Enable automatic retry (default: true)
  - maxRetries
    Maximum retry attempts (default: 3)
Returns GlobalLeaderboards
Example
```
const leaderboard = new GlobalLeaderboards('your-api-key', {
  timeout: 60000
})
```
- Defined in src/index.ts:66

Properties

`Readonly`version

version: string = SDK_VERSION

Methods

submit

submit(
    userId: string,
    score: number,
    leaderboardIdOrOptions?:
        | string
        | {
            leaderboardId?: string;
            userName?: string;
            metadata?: Record<string, unknown>;
        },
): Promise<SubmitScoreResponse | QueuedSubmitResponse>
Submit a score to a leaderboard with validation

Supports three signature variations:
- submit(userId, score) - Uses default leaderboard ID
- submit(userId, score, leaderboardId) - Specify leaderboard
- submit(userId, score, options) - Full options object
When offline or queue not empty, submissions are queued and processed when online.
Parameters
- userId: string
  Unique user identifier
- score: number
  Score value (must be >= 0)
- OptionalleaderboardIdOrOptions:
      | string
      | {
          leaderboardId?: string;
          userName?: string;
          metadata?: Record<string, unknown>;
      }
  Leaderboard ID string or options object
Returns Promise<SubmitScoreResponse | QueuedSubmitResponse>
Score submission response or queued response
Throws
If validation fails
Example
```
// Using default leaderboard
await leaderboard.submit('user-123', 1500)

// Specify leaderboard
await leaderboard.submit('user-123', 1500, 'leaderboard-456')

// Full options
await leaderboard.submit('user-123', 1500, {
  leaderboardId: 'leaderboard-456',
  userName: 'PlayerOne',
  metadata: { level: 5 }
})
```
- Defined in src/index.ts:119

getLeaderboard

getLeaderboard(
leaderboardId: string,
options?: { page?: number; limit?: number; aroundUser?: string },
): Promise<LeaderboardEntriesResponse>
Get paginated leaderboard entries
Parameters
- leaderboardId: string
  Leaderboard ID to retrieve
- Optionaloptions: { page?: number; limit?: number; aroundUser?: string }
  Query options
  - Optionalpage?: number
    Page number (default: 1)
  - Optionallimit?: number
    Results per page (default: 20, max: 100)
  - OptionalaroundUser?: string
    Center results around specific user ID
Returns Promise<LeaderboardEntriesResponse>
Leaderboard entries with pagination info
Throws
If API returns an error
Example
```
const data = await leaderboard.getLeaderboard('leaderboard-456', {
  page: 1,
  limit: 10,
  aroundUser: 'user-123'
})
```
- Defined in src/index.ts:230

submitBulk

submitBulk(
submissions: FlexibleScoreSubmission[],
): Promise<BulkSubmitScoreResponse>
Submit multiple scores in bulk for better performance

Accepts mixed formats for flexibility:
- [userId, score] - Uses default leaderboard
- [userId, score, leaderboardId] - Specify leaderboard
- Full object with all options
Parameters
- submissions: FlexibleScoreSubmission[]
  Array of score submissions in various formats (max 100)
Returns Promise<BulkSubmitScoreResponse>
Bulk submission response with individual results and summary
Throws
If validation fails or API returns an error
Example
```
const results = await leaderboard.submitBulk([
  ['user-123', 1000],                    // Uses default leaderboard
  ['user-456', 2000, 'leaderboard-789'], // Specific leaderboard
  {                                      // Full options
    userId: 'user-789',
    score: 3000,
    leaderboardId: 'leaderboard-789',
    userName: 'TopPlayer',
    metadata: { level: 10 }
  }
])
```
- Defined in src/index.ts:277

getUserScores

getUserScores(
userId: string,
options?: { page?: number; limit?: number },
): Promise<UserScoresResponse>
Get all scores for a user across leaderboards
Parameters
- userId: string
  User ID to get scores for
- Optionaloptions: { page?: number; limit?: number }
  Query options
  - Optionalpage?: number
    Page number (default: 1)
  - Optionallimit?: number
    Results per page (default: 20)
Returns Promise<UserScoresResponse>
User scores with pagination and summary stats
Throws
If API returns an error
Example
```
const userScores = await leaderboard.getUserScores('user-123', {
  page: 1,
  limit: 50
})
```
- Defined in src/index.ts:352

connectWebSocket

connectWebSocket(
    handlers: WebSocketHandlers,
    options?: {
        leaderboardId?: string;
        userId?: string;
        maxReconnectAttempts?: number;
        reconnectDelay?: number;
    },
): LeaderboardWebSocket
Connect to WebSocket for real-time leaderboard updates

WebSocket connections now work through the main API domain with full Cloudflare proxy protection. Both WebSocket and SSE are supported options for real-time updates. Choose based on your specific needs:
- WebSocket: Lower latency, binary support, bidirectional potential
- SSE: Simpler implementation, automatic reconnection, better firewall compatibility
Parameters
- handlers: WebSocketHandlers
  Event handlers for WebSocket events
  
  WebSocket event handlers
  - OptionalonConnect?: () => void
    Called when connection is established
  - OptionalonDisconnect?: (code: number, reason: string) => void
    Called when connection is closed
  - OptionalonError?: (error: Error) => void
    Called when an error occurs
  - OptionalonLeaderboardUpdate?: (
        data: {
            leaderboardId: string;
            updateType: "score_update" | "full_refresh" | "bulk_update";
            leaderboard: {
                entries: LeaderboardEntry[];
                totalEntries: number;
                displayedEntries: number;
            };
            mutations: LeaderboardMutation[];
            trigger: UpdateTrigger;
            sequence: number;
        },
    ) => void
    Called when leaderboard is updated
  - OptionalonUserRankUpdate?: (
        data: {
            leaderboard_id: string;
            user_id: string;
            old_rank: number;
            new_rank: number;
            score: number;
        },
    ) => void
    Called when user rank changes
  - OptionalonMessage?: (message: WebSocketMessage) => void
    Called for any message
  - OptionalonReconnecting?: (attempt: number, maxAttempts: number, nextDelay: number) => void
    Called when starting a reconnection attempt
- Optionaloptions: {
      leaderboardId?: string;
      userId?: string;
      maxReconnectAttempts?: number;
      reconnectDelay?: number;
  }
  Connection options
  - OptionalleaderboardId?: string
    Initial leaderboard to subscribe to
  - OptionaluserId?: string
    User ID for personalized updates
  - OptionalmaxReconnectAttempts?: number
    Max reconnection attempts
  - OptionalreconnectDelay?: number
    Delay between reconnection attempts in ms
Returns LeaderboardWebSocket
WebSocket client instance
Example
```
const ws = leaderboard.connectWebSocket({
  onConnect: () => console.log('Connected'),
  onLeaderboardUpdate: (data) => console.log('Update:', data)
}, {
  leaderboardId: 'leaderboard-456'
})
```
See
connectSSE - Recommended alternative for real-time updates
- Defined in src/index.ts:405

disconnectWebSocket

disconnectWebSocket(): void
Disconnect from WebSocket

Returns void
Example
```
leaderboard.disconnectWebSocket()
```
- Defined in src/index.ts:441

connectSSE

connectSSE(
    leaderboardId: string,
    handlers: SSEEventHandlers,
    options?: SSEConnectionOptions,
): { close: () => void }
Connect to Server-Sent Events (SSE) for real-time leaderboard updates

This is the recommended method for real-time updates. SSE provides:
- Simpler implementation compared to WebSocket
- Automatic reconnection with exponential backoff
- Better firewall and proxy compatibility
- Lower resource usage
- Built-in heartbeat for connection health
Parameters
- leaderboardId: string
  Leaderboard to connect to
- handlers: SSEEventHandlers
  Event handlers for SSE events
  
  Event handlers for SSE
  - OptionalonConnect?: () => void
  - OptionalonDisconnect?: () => void
  - OptionalonError?: (error: GlobalLeaderboardsError) => void
  - OptionalonLeaderboardUpdate?: (data: SSELeaderboardUpdateEvent) => void
  - OptionalonHeartbeat?: (data: { connectionId: string; serverTime: string }) => void
  - OptionalonMessage?: (message: any) => void
- Optionaloptions: SSEConnectionOptions
  Connection options
  
  SSE connection options
  - OptionaluserId?: string
  - OptionalincludeMetadata?: boolean
  - OptionaltopN?: number
Returns { close: () => void }
SSE connection object with close method
Example
```
const connection = leaderboard.connectSSE('leaderboard-123', {
  onLeaderboardUpdate: (data) => {
    console.log('Top scores:', data.topScores)
  },
  onUserRankUpdate: (data) => {
    console.log('Rank changed:', data)
  }
})

// Later...
connection.close()
```
- Defined in src/index.ts:488

disconnectSSE

disconnectSSE(): void
Disconnect from all SSE connections

Returns void
Example
```
leaderboard.disconnectSSE()
```
- Defined in src/index.ts:507

generateId

generateId(): string
Generate a new ULID (Universally Unique Lexicographically Sortable Identifier)

Returns string
A new ULID string
Example
```
const id = leaderboard.generateId()
// Returns: '01ARZ3NDEKTSV4RRFFQ69G5FAV'
```
- Defined in src/index.ts:525

getApiInfo

getApiInfo(): Promise<ApiInfoResponse>
Get API information and available endpoints

Returns Promise<ApiInfoResponse>
API info including version, endpoints, and documentation URL
Throws
If API returns an error

Remarks
No authentication required for this endpoint
Example
```
const info = await leaderboard.getApiInfo()
console.log('API Version:', info.version)
```
- Defined in src/index.ts:543

health

health(): Promise<HealthResponse>
Perform a basic health check on the API

Returns Promise<HealthResponse>
Health status with version and timestamp
Throws
If health check fails

Remarks
No authentication required for this endpoint
Example
```
const health = await leaderboard.health()
if (health.status === 'healthy') {
  console.log('API is healthy')
}
```
- Defined in src/index.ts:609

healthDetailed

healthDetailed(): Promise<DetailedHealthResponse>
Perform a detailed health check with individual service statuses

Returns Promise<DetailedHealthResponse>
Detailed health info including database, cache, and storage status
Throws
If health check fails

Remarks
No authentication required for this endpoint
Example
```
const health = await leaderboard.healthDetailed()
console.log('Database:', health.services.database.status)
console.log('Cache:', health.services.cache.status)
```
- Defined in src/index.ts:674

on

on(event: QueueEventType, handler: QueueEventHandler): void
Register event handler for queue events
Parameters
- event: QueueEventType
  Event type to listen for
- handler: QueueEventHandler
  Handler function
Returns void
Example
```
leaderboard.on('queue:processed', (data) => {
  console.log('Queue item processed:', data)
})
```
- Defined in src/index.ts:947

off

off(event: QueueEventType, handler: QueueEventHandler): void
Unregister event handler
Parameters
- event: QueueEventType
  Event type
- handler: QueueEventHandler
  Handler function to remove
Returns void
- Defined in src/index.ts:957

getQueueStatus

getQueueStatus(): {
    size: number;
    processing: boolean;
    items: { queueId: string; method: string; timestamp: number }[];
}
Get current offline queue status

Returns {
    size: number;
    processing: boolean;
    items: { queueId: string; method: string; timestamp: number }[];
}
Queue information including size and processing state
- Defined in src/index.ts:966

processQueue

processQueue(): Promise<void>
Manually trigger offline queue processing

Returns Promise<void>
Promise that resolves when processing is complete
- Defined in src/index.ts:992

Class GlobalLeaderboards

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

defaultLeaderboardId

baseUrl

wsUrl

timeout

autoRetry

maxRetries

Returns GlobalLeaderboards

Example

Properties

Readonlyversion

Methods

submit

Parameters

Returns Promise<SubmitScoreResponse | QueuedSubmitResponse>

Throws

Example

getLeaderboard

Parameters

Optionalpage?: number

Optionallimit?: number

OptionalaroundUser?: string

Returns Promise<LeaderboardEntriesResponse>

Throws

Example

submitBulk

Parameters

Returns Promise<BulkSubmitScoreResponse>

Throws

Example

getUserScores

Parameters

Optionalpage?: number

Optionallimit?: number

Returns Promise<UserScoresResponse>

Throws

Example

connectWebSocket

Parameters

OptionalonConnect?: () => void

OptionalonDisconnect?: (code: number, reason: string) => void

OptionalonError?: (error: Error) => void

OptionalonUserRankUpdate?: ( data: { leaderboard_id: string; user_id: string; old_rank: number; new_rank: number; score: number; },) => void

OptionalonMessage?: (message: WebSocketMessage) => void

OptionalonReconnecting?: (attempt: number, maxAttempts: number, nextDelay: number) => void

OptionalleaderboardId?: string

OptionaluserId?: string

OptionalmaxReconnectAttempts?: number

OptionalreconnectDelay?: number

Returns LeaderboardWebSocket

Example

See

disconnectWebSocket

Returns void

Example

connectSSE

Parameters

OptionalonConnect?: () => void

OptionalonDisconnect?: () => void

OptionalonError?: (error: GlobalLeaderboardsError) => void

OptionalonLeaderboardUpdate?: (data: SSELeaderboardUpdateEvent) => void

OptionalonHeartbeat?: (data: { connectionId: string; serverTime: string }) => void

OptionalonMessage?: (message: any) => void

OptionaluserId?: string

OptionalincludeMetadata?: boolean

OptionaltopN?: number

Returns { close: () => void }

Example

disconnectSSE

Returns void

Example

generateId

`Readonly`version

`Optional`page?: number

`Optional`limit?: number

`Optional`aroundUser?: string

`Optional`page?: number

`Optional`limit?: number

`Optional`onConnect?: () => void

`Optional`onDisconnect?: (code: number, reason: string) => void

`Optional`onError?: (error: Error) => void

`Optional`onUserRankUpdate?: (
data: {
leaderboard_id: string;
user_id: string;
old_rank: number;
new_rank: number;
score: number;
},
) => void

`Optional`onMessage?: (message: WebSocketMessage) => void

`Optional`onReconnecting?: (attempt: number, maxAttempts: number, nextDelay: number) => void

`Optional`leaderboardId?: string

`Optional`userId?: string

`Optional`maxReconnectAttempts?: number

`Optional`reconnectDelay?: number

`Optional`onConnect?: () => void

`Optional`onDisconnect?: () => void

`Optional`onError?: (error: GlobalLeaderboardsError) => void

`Optional`onLeaderboardUpdate?: (data: SSELeaderboardUpdateEvent) => void

`Optional`onHeartbeat?: (data: { connectionId: string; serverTime: string }) => void

`Optional`onMessage?: (message: any) => void

`Optional`userId?: string

`Optional`includeMetadata?: boolean

`Optional`topN?: number

Returns {
size: number;
processing: boolean;
items: { queueId: string; method: string; timestamp: number }[];
}