@matchlayerhq/gamekit

TypeScript SDK for Matchlayer lobbies, parties, friends, and matchmaking.

Install

npm install @matchlayerhq/gamekit

Server Usage

Use MatchlayerServer only from trusted backend code. It sends your secret API key.

import { DEFAULT_PLAYER_TOKEN_TTL_SECONDS, MatchlayerServer } from '@matchlayerhq/gamekit'

const matchlayer = new MatchlayerServer({
  secretKey: process.env.MATCHLAYER_SECRET_KEY!,
  baseUrl: process.env.MATCHLAYER_API_URL!
})

await matchlayer.players.create({
  id: 'player_123',
  displayName: 'Ada'
})

await matchlayer.gameModes.create({
  key: 'duo',
  lobbySize: 2
})

const { playerToken } = await matchlayer.playerSessions.create({
  playerId: 'player_123',
  ttlSeconds: DEFAULT_PLAYER_TOKEN_TTL_SECONDS
})

Player sessions default to 900 seconds when ttlSeconds is omitted. Player tokens identify a game and player; they do not carry endpoint scopes.

Client Usage

Use MatchlayerClient from game clients or web clients. It needs a publishable key plus a short-lived player token minted by your server.

import { MatchlayerClient } from '@matchlayerhq/gamekit'

const client = new MatchlayerClient({
  publishableKey: 'ml_pk_test_...',
  playerToken,
  baseUrl: process.env.MATCHLAYER_API_URL!
})

const lobby = await client.lobbies.create({
  name: 'Ranked EU',
  mode: 'duo',
  region: 'eu-west',
  maxPlayers: 2
})

await client.lobbies.ready(lobby.id)

Expired player tokens map to MatchlayerError with code expired_player_token:

import { isExpiredPlayerTokenError } from '@matchlayerhq/gamekit'

try {
  await client.lobbies.list()
} catch (error) {
  if (isExpiredPlayerTokenError(error)) {
    // Mint a fresh player token on your backend, then recreate the client.
  }
}

Matchmaking

const ticket = await client.matchmaking.enqueue({
  mode: 'duo',
  region: 'eu-west',
  skill: 1200
})

const status = await client.matchmaking.get(ticket.id)

Events

const events = new EventSource(await client.eventsUrl())
events.addEventListener('party_invite_received', event => {
  console.log(JSON.parse(event.data))
})

eventsUrl() mints a stream-only credential valid for 60 seconds; it never places the normal player token in the event URL. Treat events as a prompt to refresh durable state after reconnecting:

const [friendRequests, invites] = await Promise.all([
  client.friends.pendingRequests(),
  client.invites.pending()
])

Friend requests remain pending until accepted, rejected, or blocked. Party invites expire after 15 minutes and lobby invites after 5 minutes. Use client.friends.unblock(playerId) to remove one of your blocks, or client.invites.reject(inviteId) to decline an invite.

Public Types

The package exports request option types for app code:

• MatchlayerServerOptions
• MatchlayerClientOptions
• CreatePlayerRequest
• CreateGameModeRequest
• CreatePlayerSessionRequest
• CreateLobbyRequest
• CreateTicketRequest
• DEFAULT_PLAYER_TOKEN_TTL_SECONDS
• isExpiredPlayerTokenError

Versioning

0.x versions may change while the API is still settling. Once the /v1 API and SDK shape are stable, use SemVer: patch for fixes, minor for additive endpoints/options, major for breaking request or response changes.