SettleSettle SDK

The official SDK for SettleSettle — the Revenue Operating System for African developers.

Installation

npm install settlesettle
# or
pnpm add settlesettle
# or
yarn add settlesettle

Quick Start

import { SettleSettle } from 'settlesettle'

const settle = new SettleSettle({ apiKey: 'ss_live_your_key' })
// Start using the modules!
const balance = await settle.wallet.getBalance('user_123')

Modules

Payments

Easily initialize and verify Paystack checkout sessions.

// Initialize a checkout session
const { checkoutUrl, reference } = await settle.payments.initialize({
  endUserId: 'user_123',
  amountKobo: 500000,   // ₦5,000 in kobo
  email: 'user@example.com',
})
// Redirect your user to checkoutUrl

// Verify payment status later
const result = await settle.payments.verify(reference)
if (result.status === 'success') {
  console.log('Payment successful!')
}

Wallet

Manage user credit balances directly from the SDK.

// Credit a user's wallet
await settle.wallet.credit('user_123', {
  amount: 100,
  description: 'Welcome bonus',
})

// Deduct credits for usage
await settle.wallet.debit('user_123', {
  amount: 10,
  description: 'AI Query',
})

// View transaction history
const history = await settle.wallet.getHistory('user_123', { page: 1, limit: 10 })

Events (Usage Metering)

Track user activities with built-in, non-blocking background buffering.

// Synchronous and non-blocking — buffers automatically!
settle.events.track({
  userId: 'user_123',
  eventType: 'AI_QUERY',
  metadata: { model: 'gpt-4' }
})

// Get a usage summary for a user
const summary = await settle.events.getSummary('user_123')

Authentication

Authenticate developers to retrieve and refresh access tokens programmatically.

const auth = await settle.auth.login({
  email: 'dev@example.com',
  password: 'securepassword',
})

console.log('Access token:', auth.accessToken)

Error Handling

Every error thrown by the SDK is a strictly typed class. Always catch by type to handle specific scenarios properly.

import {
  SettleSettleError,
  InsufficientCreditsError,
  AuthenticationError,
} from 'settlesettle'

try {
  await settle.wallet.debit('user_123', { amount: 10 })
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.log(`Balance: ${err.currentBalance}. Need: ${err.requestedAmount}.`)
    // e.g. Trigger a paywall or ad fallback here
  } else if (err instanceof AuthenticationError) {
    console.error('Invalid API Key')
  } else if (err instanceof SettleSettleError) {
    console.error('General SDK Error:', err.message)
  }
}

Graceful Shutdown

To ensure any buffered events are sent to the SettleSettle API before your Node.js process exits, call destroy().

// On server shutdown or process exit
await settle.destroy()

Documentation

For full documentation and API reference, please visit docs.settlesettle.com.