@scalemule/money

Official ScaleMule SDK for pricing, wallets, exchange, billing, and subscriptions.

Works in browsers, Node.js 18+, and edge runtimes with standard fetch.

Install

npm install @scalemule/money

Quick Start

import { createMoneyClient } from '@scalemule/money'

const money = createMoneyClient({
  apiKey: process.env.NEXT_PUBLIC_SCALEMULE_API_KEY!,
  environment: 'prod',
})

const rates = await money.pricing.rates()
const plans = await money.subscriptions.listPlans()

Session-Scoped Usage

Money APIs use your application API key plus a member or end-user bearer token.

const money = createMoneyClient({
  apiKey: process.env.NEXT_PUBLIC_SCALEMULE_API_KEY!,
  environment: 'prod',
})

const authedMoney = money.withAccessToken(memberAccessToken)

const accounts = await authedMoney.accounts.list()
const deposits = await authedMoney.billing.listDeposits()
const subscriptions = await authedMoney.subscriptions.list()

Configuration

const money = createMoneyClient({
  apiKey: 'sm_pb_xxx',
  environment: 'dev',                 // 'dev' | 'prod'
  gatewayUrl: 'https://api-dev.scalemule.com',
  accessToken: 'member_access_token', // optional
  defaultHeaders: {
    'x-request-id': crypto.randomUUID(),
  },
})

Surface Area

Pricing

await money.pricing.rates()
await money.pricing.price({ item_id: 'sku_pro', asset_code: 'USD' })
await money.pricing.priceBulk({ item_ids: ['sku_pro', 'sku_team'], asset_code: 'USD' })
await money.pricing.createQuote({
  from_asset_code: 'USD',
  to_asset_code: 'EUR',
  amount_minor: 5000,
})

Wallets and Ledger

await money.accounts.list({ currency_code: 'USD' })
await money.accounts.get(accountId)
await money.accounts.getLedger(accountId, { source_type: 'deposit' })

Exchange

await money.transfers.send({
  receiver_user_id: '0195...',
  amount_minor: 500,
  currency_code: 'USD',
  idempotency_key: 'tip_123',
})

await money.conversions.convert({
  source_currency: 'USD',
  target_currency: 'EUR',
  source_amount_minor: 1000,
  idempotency_key: 'fx_123',
})

Billing

await money.billing.listPaymentMethods()

await money.billing.deposit({
  amount_minor: 2500,
  currency: 'USD',
  payment_method_id: 'pm_123',
  idempotency_key: 'deposit_123',
})

await money.billing.getDeposit(depositId)

Subscriptions

const plans = await money.subscriptions.listPlans()

await money.subscriptions.subscribe({
  plan_id: plans[0].id,
  funding_source: 'wallet',
  preferred_currency: 'USD',
})

await money.subscriptions.get(subscriptionId)
await money.subscriptions.getCycles(subscriptionId, { status: 'paid', limit: 12 })
await money.subscriptions.getDunning(subscriptionId)
await money.subscriptions.cancel(subscriptionId)

Error Handling

Requests throw MoneyHttpError on HTTP failures or success: false envelopes.

import { MoneyHttpError } from '@scalemule/money'

try {
  await money.billing.deposit({
    amount_minor: 5000,
    currency: 'USD',
    payment_method_id: 'pm_missing',
  })
} catch (error) {
  if (error instanceof MoneyHttpError) {
    console.error(error.status, error.detail?.code, error.detail?.message)
  }
}

React

The package also ships a small React entrypoint:

import { MoneyProvider, useMoneyClient } from '@scalemule/money/react'

Use @scalemule/nextjs if you want the higher-level ScaleMule server/client integration for session handling.