@omen.foundation/game-sdk

OmenX Game SDK for web applications - OAuth authentication and API integration.

The SDK supports two modes:

• Client Mode: OAuth authentication for frontend applications (browser/React)
• Server Mode: API key authentication for Node.js backends

Installation

npm install @omen.foundation/game-sdk

Quick Start

Client Mode (OAuth Authentication)

For frontend applications that need user authentication:

import { OmenXGameSDK } from '@omen.foundation/game-sdk';

const sdk = new OmenXGameSDK({
  gameId: 'your-game-id',
  onAuth: (authData) => {
    console.log('Authenticated!', authData);
    // User is now authenticated
  },
  onAuthError: (error) => {
    console.error('Auth error:', error);
  },
});

// Initialize SDK
await sdk.init();

Server Mode (API Key Authentication)

For Node.js backends using developer API keys:

import { OmenXServerSDK } from '@omen.foundation/game-sdk';

const sdk = new OmenXServerSDK({
  apiKey: 'your-developer-api-key',
  apiBaseUrl: 'https://api.omen.foundation', // Optional
});

// Make API calls directly
const templates = await sdk.getNftTemplates('your-game-id');
const contract = await sdk.getNftContract('your-game-id');

OAuth Authentication

For standalone games (not embedded in iframes):

// Authenticate user via OAuth popup
await sdk.authenticate({
  redirectUri: 'https://yourgame.com/auth/callback',
  enablePKCE: true, // Recommended for security
});

Iframe Authentication

For games embedded in the OmenX frontend, authentication is automatic:

const sdk = new OmenXGameSDK({
  gameId: 'your-game-id',
  enableIframeAuth: true, // Default: true
  parentOrigin: 'https://omen.foundation', // Optional: for security
  onAuth: (authData) => {
    // Auth data received automatically from parent window
  },
});

await sdk.init();

Making API Calls (Client Mode)

// Make authenticated API calls using user's access token
const response = await sdk.apiCall('/v1/nfts/templates?gameId=your-game-id');
const data = await response.json();

Server Mode API Methods

The server SDK provides convenient methods for all API operations:

Health & Auth

// Health check
const health = await sdk.healthCheck();

// Get API key information
const info = await sdk.getApiKeyInfo();

Players

// Get wallet balances
const balances = await sdk.getPlayerBalances('0x...', '8453');

// Get wallet NFTs
const nfts = await sdk.getPlayerNfts('0x...', '8453', {
  contract: '0x...', // Optional
  cursor: '...',      // Optional
  limit: 20,          // Optional
});

Purchases

// Create a purchase
const purchase = await sdk.createPurchase({
  playerWallet: '0x...',
  skuId: 'sku-id',
  quantity: 1,
  idempotencyKey: 'unique-key', // Optional
});

NFTs

// Get NFT templates
const templates = await sdk.getNftTemplates('your-game-id');

// Get contract address
const contract = await sdk.getNftContract('your-game-id');

// Mint NFTs
const result = await sdk.mintNfts({
  templateId: 'template-id',
  recipientAddress: '0x...',
  quantity: 1,
});

// Batch mint
const batchResult = await sdk.batchMintNfts([
  { templateId: 'template-1', recipientAddress: '0x...', quantity: 1 },
  { templateId: 'template-2', recipientAddress: '0x...', quantity: 2 },
]);

// Update NFT metadata
await sdk.updateNftMetadata('token-id', {
  rarity: 'legendary',
  level: 10,
});

// Burn NFT
await sdk.burnNft('token-id');

// Batch burn
await sdk.batchBurnNfts(['token-1', 'token-2']);

// Pack opener
const packResult = await sdk.packOpener({
  dropTableId: 'drop-table-id',
  recipientAddress: '0x...',
});

// Generic API call
const response = await sdk.apiCall('/v1/custom-endpoint', {
  method: 'POST',
  body: { custom: 'data' },
});

Check Authentication Status

if (sdk.isAuthenticated()) {
  const authData = sdk.getAuthData();
  console.log('User:', authData.walletAddress);
}

Logout

await sdk.logout();

API Reference

See the full documentation for detailed API reference.

License

MIT