@koda-rising/sdk

Typed TypeScript client for the Koda Rising API — an affordable AI coding-assistant platform built for African developers. One thin, dependency-free client used by the Koda CLI and VS Code extension, and yours to build on.

• Zero runtime dependencies — uses the global fetch (Node ≥ 18, Deno, Bun, browsers).
• Fully typed — request/response shapes, streaming agent events, currency helpers.
• ESM.

Install

npm install @koda-rising/sdk

Quick start

import { KodaClient, formatMinor } from '@koda-rising/sdk';

const koda = new KodaClient('https://your-gateway.example.com', process.env.KODA_API_KEY!);

// Who am I? (org, role, currency, wallet balance)
const me = await koda.me();
console.log(`Balance: ${formatMinor(me.balanceMinor, me.currency?.code)}`);

// Run the agent as a single turn
for await (const ev of koda.agentRun('add a null check to parseConfig')) {
  if (ev.plan) console.log('plan:', ev.plan);
  if (ev.edits) console.log('edits:', ev.edits);
  if (ev.costMinor != null) console.log('cost:', formatMinor(ev.costMinor, me.currency?.code));
}

Streaming run-loop (plan → edit → verify → retry)

agentRunLoop yields Server-Sent events as they arrive: {start}, token {delta} frames, a {step} per iteration, {turn} billing, and a final result with verified/iterations/totalCostMinor.

for await (const ev of koda.agentRunLoop('fix the failing test', undefined, { sandbox: 'docker', testCmd: 'npm test' })) {
  if (typeof ev.chunk === 'string') process.stdout.write(ev.chunk);   // token deltas
  if (ev.step) console.log(`\niteration ${ev.step.iteration}: ${ev.step.ok ? 'passed' : 'retry'}`);
  if (ev.verified != null) console.log(`done — verified=${ev.verified} in ${ev.iterations} iterations`);
}

Wallet & billing

const intent = await koda.topup(5000);          // ₦5,000 → returns a hosted URL / USSD code per rail
await koda.verifyTopup(intent.reference);        // server-side settle (webhook fallback)
const wallet = await koda.getWallet();

Currency helpers

Re-exported so amounts format per market without a second dependency:

import { formatMinor, toMinor, fromMinor, currencyOf, railsFor, CURRENCIES } from '@koda-rising/sdk';

formatMinor(1250, 'NGN', { decimals: true }); // "₦12.50"
toMinor(12.5, 'NGN');                          // 1250
railsFor('KES');                               // ["card", "mpesa"]

Six currencies ship in CURRENCIES, and railsFor returns the payment methods available in each — cards everywhere, plus the local rail people actually use. Amounts are always integer minor units, never floats.

| Currency | | Minor unit | railsFor() | |---|---|---|---| | NGN | Nigerian Naira ₦ | kobo | card, bank, ussd, opay, palmpay | | KES | Kenyan Shilling KSh | cent | card, mpesa | | GHS | Ghanaian Cedi GH₵ | pesewa | card, mtn_momo, telecel_cash, airteltigo | | ZAR | South African Rand R | cent | card, payshap, instant_eft, ozow | | EGP | Egyptian Pound E£ | piastre | card, fawry, instapay, vodafone_cash | | USD | US Dollar $ | cent | card |

API surface

KodaClient: me, getWallet, topup, verifyTopup, createKey, listKeys, revokeKey, repoIndex, repoStatus, repoClear, createTeam, listMembers, addMember, agentRun (stream), agentRunLoop (stream). Plus parseSSE() for manual stream handling and the currency helpers above.

Auth

Pass an API key (koda_sk_…, created via POST /auth/keys) as the second constructor argument; keys carry scopes (agent:run, wallet:read, keys:manage, metrics:read). Money is always integer minor units (*Minor fields).

License

MIT