SDK
TypeScript SDK for platform features and integrations
Overview
The Playcademy SDK provides a TypeScript interface for interacting with the Playcademy platform API from your projects.
Installation
Add the Playcademy SDK to your project:
bun add @playcademy/sdknpm install @playcademy/sdkpnpm add @playcademy/sdkyarn add @playcademy/sdkInitialization
Automatic (Recommended)
For most use cases, especially when using our Vite plugin (@playcademy/vite-plugin), use automatic initialization:
import { PlaycademyClient } from '@playcademy/sdk'
const client = await PlaycademyClient.init()
const user = await client.users.me()
console.log('Current user:', user)How it works:
| Environment | Behavior |
|---|---|
| Development | Connects to local sandbox (via @playcademy/vite-plugin or @playcademy/sandbox) |
| Production | Receives configuration from Playcademy platform loader |
| Standalone | Falls back to mock configuration for testing |
Manual
For server-side applications, standalone scripts, or custom environments:
Authenticate
import { PlaycademyClient } from '@playcademy/sdk'
const baseUrl = 'https://api.playcademy.com'
const email = 'your-email@example.com'
const password = process.env.PLAYCADEMY_PASSWORD
const loginData = await PlaycademyClient.login(baseUrl, email, password)Create Client Instance
const client = new PlaycademyClient({
baseUrl: baseUrl,
token: loginData.token,
gameId: 'your-game-id', // Optional: for automatic session management
})Quick Start
A simple example demonstrating common SDK operations:
import { PlaycademyClient } from '@playcademy/sdk'
async function runProject() {
const client = await PlaycademyClient.init()
try {
// Get current user
const user = await client.users.me()
console.log('Current user:', user.name)
// Get player's inventory
const inventory = await client.users.inventory.get()
console.log('Player inventory:', inventory)
// Check balance
const credits = await client.credits.balance()
console.log('Player balance:', credits)
// Submit a score
await client.scores.submit(gameId, 1500, {
level: 5,
difficulty: 'hard',
})
console.log('Score submitted')
// Exit
client.runtime.exit()
} catch (error) {
console.error('Error:', error)
}
}
runProject()Event System
The SDK includes an event system for responding to platform events:
import { PlaycademyClient } from '@playcademy/sdk'
const client = await PlaycademyClient.init()
// Listen for pause events
client.on('pause', () => {
console.log('Paused by platform')
pauseGame()
})
// Listen for resume events
client.on('resume', () => {
console.log('Resumed')
resumeGame()
})
// Listen for connection changes
client.on('connectionChange', ({ state, reason }) => {
console.log(`Connection: ${state} - ${reason}`)
updateConnectionIndicator(state)
})
// Listen for credit changes
client.on('creditsChanged', (newBalance: number) => {
console.log('New balance:', newBalance)
updateUI(newBalance)
})Available Events:
| Event | Payload | Description |
|---|---|---|
pause | void | Should pause |
resume | void | Should resume |
connectionChange | { state: ConnectionState, reason: string } | Connection state changed |
creditsChanged | number | Player's credit balance update |
exit | void | Should clean up and exit |
itemPurchased | ItemWithId | Item added to player inventory |
levelUp | LevelStatus | Player leveled up |
Connection Monitoring
For handling connection issues specifically, use client.onDisconnect() which only fires for
offline/degraded states.
Learn more about Connection Monitoring.
Error Handling
The SDK uses a custom error type for consistent error handling:
import { PlaycademyClient, PlaycademyError } from '@playcademy/sdk'
try {
const client = await PlaycademyClient.init()
await client.credits.spend(100)
} catch (error) {
if (error instanceof PlaycademyError) {
console.error('API Error:', error.message)
console.error('Status:', error.status)
console.error('Code:', error.code)
} else {
console.error('Unexpected error:', error)
}
}