@kingstoneapp/sdk

TypeScript SDK for the KINGSTONE B2B Partner API.

Zero runtime dependencies. Uses native fetch only. Supports ESM and CJS.

Installation

npm install @kingstoneapp/sdk

Quick Start

import { KingstoneClient, KingstoneApiError } from '@kingstoneapp/sdk';

const client = new KingstoneClient({
  apiKey: 'ks_sandbox_abc123',
  sandbox: true,
});

// Execute a spin
const result = await client.spin({
  gameId: 1,
  playerId: 'player-abc',
  wagerUsd: 0.25,
});

console.log(result.outcome.payoutUsd);
console.log(result.presentation.comboString); // e.g., '7|7|7'
console.log(result.balance.balanceUsd);

Error Handling

try {
  await client.spin({ gameId: 1, playerId: 'p1', wagerUsd: 0.25 });
} catch (err) {
  if (err instanceof KingstoneApiError) {
    console.error(`[${err.errorCode}] ${err.message}`);
    console.error(`Status: ${err.statusCode}`);
    console.error(`Retryable: ${err.retryable}`);
  }
}

API Methods

Core

• spin(request) - Execute a spin

PAR Sheets

• uploadParSheet(request) - Upload a licensed PAR sheet
• listParSheets() - List available PAR sheets

Games

• registerGame(request) - Register a game configuration
• listGames() - List partner's games

Players

• getPlayer(externalId) - Look up a player

Settlements

• listSettlements(options?) - List settlement reports
• getSettlement(date) - Get a report by date
• acknowledgeSettlement(date) - Acknowledge a report
• disputeSettlement(date, reason) - Dispute a report

Audit

• getAuditLog(options?) - Paginated audit log
• verifyAuditChain(gameConfigId, options?) - Verify SHA-256 hash chain

Compliance

• getRtpCompliance(gameId) - Game RTP detail
• getComplianceSummary() - All-games overview
• getComplianceCertificate(gameId) - JSON compliance certificate

Webhooks

• registerWebhook(request) - Register a webhook
• listWebhooks() - List webhooks
• deleteWebhook(webhookId) - Delete a webhook
• getWebhookDeliveries(webhookId, options?) - List deliveries

Configuration

const client = new KingstoneClient({
  apiKey: 'kp_production_key',           // Required
  baseUrl: 'https://api.kingstone.dev/api', // Optional (default)
  sandbox: false,                           // Optional (default)
});

| Option | Description | Default | |-----------|--------------------------------------------------|--------------------------------------| | apiKey | Partner API key (ks_ = sandbox, kp_ = prod) | Required | | baseUrl | Override the API base URL | https://api.kingstone.dev/api | | sandbox | Use sandbox URL if baseUrl not set | false |

Requirements

• Node.js >= 18.0.0 (native fetch support)
• TypeScript >= 5.0 (optional, for type safety)