@usions/sdk

Client SDK for building mini-apps and games on the Usion platform.

Provides access to user info, storage, wallet, chat, sessions, and real-time multiplayer game features.

Install

npm install @usions/sdk

Or load via script tag:

<script src="https://usions.com/usion-sdk.js"></script>

Quick Start

import Usion from '@usions/sdk';

Usion.init((config) => {
  console.log('User:', Usion.user.getName());
  console.log('Room:', config.roomId);
});

Modules

User

Usion.user.getId()       // User ID
Usion.user.getName()     // Display name
Usion.user.getAvatar()   // Avatar URL
Usion.user.getToken()    // Auth JWT
Usion.user.getProfile()  // Promise<{ id, name, avatar }>

Storage (persistent, per-user, per-service)

await Usion.storage.set('highscore', 1500)
await Usion.storage.get('highscore')     // 1500
await Usion.storage.remove('highscore')
await Usion.storage.keys()               // ['key1', 'key2']
await Usion.storage.clear()

Wallet

await Usion.wallet.getBalance()            // 500
await Usion.wallet.hasCredits(100)         // true
await Usion.wallet.requestPayment(50, 'Power-up')
Usion.wallet.onBalanceChange((balance) => { ... })

Session (ephemeral)

Usion.session.getId()
Usion.session.getData('key')
Usion.session.setData('key', 'value')
Usion.session.clear()

Chat

await Usion.chat.sendMessage(recipientId, 'Hello!')
await Usion.chat.createPersonalChat(peerUserId)

Game (Multiplayer)

Platform Mode (relay through Usion backend)

await Usion.game.connect()
await Usion.game.join(roomId)

// Send actions (validated, sequenced)
await Usion.game.action('move', { cell: 4 })

// Send real-time updates (fire-and-forget)
Usion.game.realtime('position', { x: 100, y: 200 })

Direct Mode (connect to game creator's server)

await Usion.game.connectDirect()
await Usion.game.join(roomId)

Event Handlers

Usion.game.onPlayerJoined((data) => { ... })
Usion.game.onPlayerLeft((data) => { ... })
Usion.game.onStateUpdate((data) => { ... })
Usion.game.onAction((data) => { ... })
Usion.game.onRealtime((data) => { ... })
Usion.game.onGameFinished((data) => { ... })
Usion.game.onGameRestarted((data) => { ... })
Usion.game.onError((data) => { ... })
Usion.game.onDisconnect((reason) => { ... })
Usion.game.onReconnect((attempt) => { ... })

Other

Usion.game.requestSync(lastSequence)  // Recover missed actions
Usion.game.requestRematch()
Usion.game.forfeit()
Usion.game.disconnect()
Usion.game.isConnected()              // boolean

Utility

Usion.requestPayment(amount, reason)
Usion.share('image', { imageUrl, text })
Usion.exit()                         // Close the mini-app
Usion.log(message)                   // Debug log

TypeScript

Full type declarations included:

import Usion from '@usions/sdk';
import type { UsionConfig, GameModule, PlayerJoinedData } from '@usions/sdk';

License

MIT