Kuber SDK

Official TypeScript SDK for the Kuber Payment Ledger API.

Installation

npm install kuber-sdk

Quick Start

import { Kuber } from 'kuber-sdk';

// Initialize the SDK
const kuber = new Kuber({
  baseUrl: 'http://localhost:3000', // Your Kuber API URL
  apiKey: 'your-api-key', // Optional API key for authentication
});

// Create a transfer with automatic idempotency
const transfer = await kuber.transfers.create({
  from: 'acc-alice-001',
  to: 'acc-bob-002',
  amount: 500,
  description: 'Payment for services',
});

console.log(transfer);
// {
//   success: true,
//   transactionId: 'uuid...',
//   message: 'Transfer completed successfully',
//   fromBalance: 9500,
//   toBalance: 5500,
// }

Features

Automatic Idempotency

The SDK automatically generates idempotency keys for each request, preventing duplicate transfers:

// These will only execute once even if called multiple times
const transfer = await kuber.transfers.create({
  from: 'acc-alice-001',
  to: 'acc-bob-002',
  amount: 500,
  idempotencyKey: 'my-unique-order-id-123', // Optional: provide your own key
});

Account Management

// List all accounts
const accounts = await kuber.accounts.list();

// Get account details with transaction history
const account = await kuber.accounts.get('acc-alice-001');

// Create a new account
const newAccount = await kuber.accounts.create({
  userId: 'user_123',
  name: "John's Wallet",
  initialBalance: 1000,
});

Webhook Management

// Register a webhook
const webhook = await kuber.webhooks.create({
  userId: 'user_123',
  url: 'https://your-server.com/webhook',
  events: ['transfer.completed', 'transfer.failed'],
});

// Save the secret for signature verification!
console.log('Webhook secret:', webhook.secret);

// List webhooks
const webhooks = await kuber.webhooks.list('user_123');

// Delete a webhook
await kuber.webhooks.delete(webhook.id);

Verifying Webhook Signatures

import { verifyWebhookSignature } from 'kuber-sdk';

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-kuber-signature'];
  const payload = JSON.stringify(req.body);
  
  if (verifyWebhookSignature(payload, signature, 'your-webhook-secret')) {
    // Signature valid, process the event
    console.log('Received event:', req.body);
    res.status(200).send('OK');
  } else {
    res.status(401).send('Invalid signature');
  }
});

Error Handling

try {
  const transfer = await kuber.transfers.create({
    from: 'acc-alice-001',
    to: 'acc-bob-002',
    amount: 1000000, // More than available balance
  });
} catch (error) {
  if (error instanceof KuberError) {
    console.log('Status:', error.status); // 400
    console.log('Message:', error.message); // "Insufficient balance..."
  }
}

License

MIT