Package Exports

settlesettle

Readme

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!')
}

// Support for Solana (Devnet)
const solanaResult = await settle.payments.verifySolana('ref_123', 'signature_abc...')

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',
})

// Set the access token to access management APIs
settle.setAccessToken(auth.accessToken)
console.log('Access token:', auth.accessToken)

Users (Directory Sync)

Idempotently sync user profiles from your application database into SettleSettle's unified user directory.

// Sync on login or profile updates
await settle.users.sync({
  externalUserId: 'user_abc123',
  email: 'user@example.com',
  name: 'Tunde Adeyemi',
})

Hydrate billing UI modals and reward credits to users for watched ads with dedicated APIs.

// 1. Bootstrap all UI config, balances, and active rules in a single call
const config = await settle.billing.bootstrap('user_123')
console.log('Current Balance:', config.walletState.currentBalance)
console.log('Theme Color:', config.uiConfig.themeColor)

// 2. Reward ad credits (calculated server-side) upon completed watch
const result = await settle.billing.rewardAd('user_123')
console.log(`Awarded ${result.creditsAwarded} credits. New balance: ${result.newBalance}`)

// 3. Report custom ad network impressions
await settle.billing.reportAdImpression('imp_abc123', 45000) // 45 seconds

// 4. Developer Management (Requires JWT Auth)
const packages = await settle.billing.listPackages('app_123')
const newAction = await settle.billing.createAction('app_123', {
  eventType: 'PREMIUM_FEATURE',
  creditCost: 50
})

Ads (Developer Earnings)

Track and withdraw your application's ad revenue.

// Get earnings summary and transaction ledger
const earnings = await settle.ads.getEarningsSummary()
console.log('Available for withdrawal:', earnings.balance.availableKobo)

// Withdraw revenue to your developer wallet
await settle.ads.withdrawEarnings(500000) // ₦5,000

Advertiser (Campaign Management)

Manage ad campaigns, creative assets, and budgets programmatically.

// Login as an advertiser
await settle.advertiser.login({ email: 'ads@brand.com', password: '...' })

// Create a new campaign
const campaign = await settle.advertiser.createCampaign({
  name: 'Summer Sale 2024',
  budgetKobo: 1000000, // ₦10,000
  rewardCredits: 10
})

// Add a creative asset
await settle.advertiser.addCreative(campaign.id, {
  headline: 'Huge Discounts!',
  body: 'Get 50% off all items.',
  ctaLabel: 'Shop Now',
  ctaUrl: 'https://brand.com/sale',
  brandName: 'BrandX'
})

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.

JSPM

settlesettle