Beamable JavaScript SDK

A modern, type-safe JavaScript/TypeScript SDK for Beamable, featuring modular architecture, comprehensive authentication, content management, and developer-friendly tooling. Supports both client and server (admin) use cases from a single SDK.

🚀 Features

• 🔐 Complete Authentication - Guest, user, third-party, and device ID login
• 📦 Type-Safe Content API - Generic content fetching with auto-generated types
• 🎯 Modular Architecture - Clean separation of concerns with context pattern
• 🛠️ Developer Tools - CLI for type generation and content management
• ✅ Comprehensive Testing - Full test coverage with real API integration
• 📱 Modern JavaScript - ESM/CJS compatible with TypeScript support
• 🛡️ Server/Admin Mode - Signed requests, player impersonation, and admin APIs

📚 Documentation

Getting Started

• Installation & Setup - Get up and running quickly
• Quick Start Guide - Your first Beamable integration
• Configuration - Environment setup and options

Core Concepts

• Architecture Overview - Understanding the SDK structure
• BeamContext Pattern - The unified context approach
• Authentication Flow - Complete auth system guide

API Reference

• Auth Module - User authentication and management
• Content Module - Type-safe content fetching
• Inventory Module - Player inventory management
• Stats Module - Player statistics and data

Developer Tools

• Type Generation CLI - Auto-generate content types
• Testing Guide - Running and writing tests
• CLI Reference - Command-line tool documentation

Advanced Topics

• Content Type System - Understanding generated types
• Error Handling - Best practices for errors
• Performance Optimization - Tips for production use

Examples & Tutorials

• Basic Integration - Simple game integration
• Content Management - Working with content
• User Management - User registration and login

🛠️ Quick Installation

npm install @omen.foundation/beamable-sdk

🔧 Type Generation

The SDK includes a CLI tool to automatically generate TypeScript types from your Beamable realm content:

# Generate types in your project's src/types/content/ directory
npx beamable generateTypes

# Or if you have the SDK installed locally
npm run generateTypes

Setup:

1. Create a .env file in your project root:

   VITE_CID=your-customer-id
   VITE_PID=your-project-id
   VITE_API_URL=https://api.beamable.com
   # For server mode:
   VITE_SECRET=your-server-secret

2. Run the type generation tool:

   npx beamable generateTypes

3. Types will be generated in src/types/content/ and can be imported in your code:

   import type { AbilityMaps, Minions, Items } from './types/content';

What it does:

• Fetches your realm's content manifest from Beamable
• Downloads all content objects and groups them by type
• Generates TypeScript declaration files (.d.ts) for each content type
• Places them in your project's src/types/content/ directory
• Cleans up obsolete type files automatically

🎯 Quick Example (Client & Server)

Client Mode (Browser, Desktop, Mobile)

import { BeamContext, configureBeamable } from '@omen.foundation/beamable-sdk';

// Configure the SDK (client mode)
configureBeamable({
  cid: 'your-customer-id',
  pid: 'your-project-id',
  apiUrl: 'https://api.beamable.com'
});

const context = await BeamContext.Default;
await context.onReady;

// Fetch type-safe content
const abilityMap = await context.Content.getContent<AbilityMaps>('AbilityMaps.VitalityAura');
const allMinions = await context.Content.getContentByType<Minions>('Minions');

console.log(`Ability: ${abilityMap.properties.actions.data[0].abilityName}`);

🛡️ Server Mode (Admin/Backend)

import { BeamContext, configureBeamable } from '@omen.foundation/beamable-sdk';

configureBeamable({
  cid: process.env.VITE_CID!,
  pid: process.env.VITE_PID!,
  apiUrl: process.env.VITE_API_URL || 'https://api.beamable.com',
  secret: process.env.VITE_SECRET!,
  mode: 'server'
});
const context = await BeamContext.Default;

// Impersonate any player using gamertag
const playerId = '1234567890';
const inventory = await context.Inventory.getInventory(playerId, playerId); // gamertag = playerId
const stats = await context.Stats.getStats(`client.public.player.${playerId}`, playerId);

// Call server-only/admin APIs
const params = new URLSearchParams({ query: '[email protected]', page: '0', pagesize: '10' }).toString();
const accounts = await context.core.request('GET', `/basic/accounts/search?${params}`);
console.log('Accounts:', accounts);

Security Note:

• Never expose your server secret in client-side code.
• Use server mode only in trusted backend environments.

📦 Package Structure

src/
├── core/           # Core SDK functionality
│   ├── BeamableCore.ts
│   └── BeamContext.ts
├── modules/        # Feature modules
│   ├── Auth.ts
│   ├── Content.ts
│   ├── Inventory.ts
│   └── Stats.ts
├── types/          # Generated content types
│   └── content/
├── cli/            # Developer tools
│   ├── beamable.ts
│   └── generateTypes.ts
└── index.ts        # Main entry point

🧪 Testing

# Run all tests
npm test

# Run specific test suites
npm test auth
npm test content
npm test inventory
npm test stats

# Generate content types
npm run generateTypes

🤝 Contributing

See Contributing Guide for development setup and guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Beamable Documentation
• API Reference
• Community Discord

Need help? Check out our Troubleshooting Guide or open an issue.

Advanced Usage: Manual Login Before Context

If you want to log in an existing user (and avoid creating a new guest user), you can use the AuthModule directly:

import { configureBeamable, BeamableCore, AuthModule, BeamContext } from '@omen.foundation/beamable-sdk';

configureBeamable({ cid, pid, apiUrl });
const core = new BeamableCore();
const auth = new AuthModule(core);
await auth.loginUser('[email protected]', 'password');
const context = await BeamContext.Default;
await context.onReady;

This pattern works for all login methods (username/password, third-party, etc.).