@afriex/sdk 2.0.0 → 3.0.1

package/README.md

@@ -66,22 +66,39 @@ const balances = await afriex.balance.getBalance({
   currencies: ["USD", "NGN"],
 });
 
-// Webhook Verification (only if webhookPublicKey provided)
-if (afriex.webhooks) {
-  const isValid = afriex.webhooks.verify(payload, signature);
-}
+// Checkout - hosted payment page
+const session = await afriex.checkout.createSession({
+  amount: 10000, // minor units, minimum 100
+  currency: "USD",
+  merchantReference: "order-123",
+  redirectUrl: "https://example.com/checkout/complete",
+  customer: {
+    name: "John Doe",
+    email: "john@example.com",
+    phone: "+1234567890",
+    countryCode: "US",
+  },
+});
+// session.checkoutUrl
+
+// Webhook verification (requires webhookPublicKey)
+const isValid = afriex.webhooks.verify(payload, signature);
 ```
 
 ## Available Services
 
-| Service                 | Description                                  |
-| ----------------------- | -------------------------------------------- |
-| `afriex.customers`      | Customer CRUD and KYC management             |
-| `afriex.transactions`   | Create and track transactions                |
-| `afriex.paymentMethods` | Bank, mobile money, crypto, virtual accounts |
-| `afriex.balance`        | Organization wallet balances                 |
-| `afriex.rates`          | Exchange rates and conversions               |
-| `afriex.webhooks`       | Webhook signature verification (optional)    |
+| Service                 | Description                                                |
+| ----------------------- | ---------------------------------------------------------- |
+| `afriex.customers`      | Customer CRUD, KYC updates, and document verification       |
+| `afriex.transactions`   | Create, authorize, list, and track transactions             |
+| `afriex.paymentMethods` | Bank, mobile money, crypto wallets, virtual & pool accounts |
+| `afriex.balance`        | Organization wallet balances and sandbox top-ups            |
+| `afriex.rates`          | Exchange rates and conversions                              |
+| `afriex.checkout`       | Hosted checkout sessions (card, virtual account, momo)      |
+| `afriex.webhooks`       | Webhook signature verification and sandbox test triggers    |
+
+Every service is always available on the client. `afriex.webhooks.verify()` returns `false`
+unless a `webhookPublicKey` was provided; `afriex.webhookVerifier` is set only when one was.
 
 ## Configuration
 
@@ -89,7 +106,40 @@ if (afriex.webhooks) {
 interface AfriexSDKConfig {
   apiKey: string; // Required - Your Afriex API key
   environment?: "staging" | "production"; // Default: 'production'
-  webhookPublicKey?: string; // Optional - Afriex's public key for webhooks
+  webhookPublicKey?: string; // Optional - Afriex's PEM public key for webhook verification
+  customConfig?: { timeout?: number }; // Optional - override timeout
+  logLevel?: LogLevel; // Default: LogLevel.ERROR
+  enableLogging?: boolean; // Default: true
+  retryConfig?: {
+    maxRetries: number;
+    retryDelay: number;
+    retryableStatusCodes: number[]; // Default: [408, 429, 500, 502, 503, 504]
+  };
+}
+```
+
+`staging` points at `https://sandbox.api.afriex.com/api/v1`, `production` at
+`https://api.afriex.com/api/v1`.
+
+## Error Handling
+
+All errors extend `AfriexError` and are re-exported from this package:
+
+```typescript
+import { AfriexError, ApiError, ValidationError, RateLimitError, NetworkError } from "@afriex/sdk";
+
+try {
+  await afriex.transactions.create(request);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // Request failed local validation before being sent
+  } else if (error instanceof RateLimitError) {
+    // 429 - back off and retry
+  } else if (error instanceof ApiError) {
+    // Non-2xx response from the API
+  } else if (error instanceof NetworkError) {
+    // Connection/timeout failure
+  }
 }
 ```
 
@@ -97,19 +147,34 @@ interface AfriexSDKConfig {
 
 For smaller bundle sizes, install packages individually:
 
-| Package                   | Description                   |
-| ------------------------- | ----------------------------- |
-| `@afriex/core`            | Base client and configuration |
-| `@afriex/customers`       | Customer management           |
-| `@afriex/transactions`    | Transaction handling          |
-| `@afriex/payment-methods` | Payment methods               |
-| `@afriex/balance`         | Balance queries               |
-| `@afriex/rates`           | Exchange rates                |
-| `@afriex/webhooks`        | Webhook verification          |
+| Package                   | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `@afriex/core`            | Base client, config, HTTP layer, errors, shared types  |
+| `@afriex/customers`       | Customer management and KYC                            |
+| `@afriex/transactions`    | Transaction handling                                   |
+| `@afriex/payment-methods` | Payment methods, institutions, virtual & pool accounts |
+| `@afriex/balance`         | Balance queries and sandbox top-ups                    |
+| `@afriex/rates`           | Exchange rates and conversions                         |
+| `@afriex/checkout`        | Hosted checkout sessions                               |
+| `@afriex/webhooks`        | Webhook verification and test triggers                 |
+
+Each service package depends only on `@afriex/core`, so you can mix and match.
+
+## AI agents
+
+Every `@afriex/*` package ships [TanStack Intent](https://tanstack.com/intent) skills under
+`skills/`, so coding agents get grounded guidance on this SDK instead of guessing at the API.
+If you use an AI agent, run:
+
+```bash
+npx @tanstack/intent@latest install
+```
+
+List what is available with `npx @tanstack/intent@latest list`.
 
 ## Documentation
 
-Full documentation available at [afriex-sdk-docs.vercel.app](https://afriex-sdk-docs.vercel.app)
+Full documentation available at [docs.afriex.com](https://docs.afriex.com/sdk/introduction)
 
 ## License
 

package/dist/index.d.ts

@@ -29,9 +29,9 @@ export { BalanceService } from "@afriex/balance";
 export { RateService } from "@afriex/rates";
 export { CheckoutService } from "@afriex/checkout";
 export { WebhookVerifier, WebhookService } from "@afriex/webhooks";
-export type { Customer, CreateCustomerRequest, UpdateCustomerKycRequest, ListCustomersParams, CustomerListResponse, } from "@afriex/customers";
-export type { Transaction, CreateTransactionRequest, ListTransactionsParams, TransactionListResponse, TransactionListType, TransactionChannel, TransactionType, TransactionStatus, TransactionMeta, } from "@afriex/transactions";
-export type { PaymentMethod, CreatePaymentMethodRequest, ListPaymentMethodsParams, PaymentMethodListResponse, PaymentChannel, Institution, ResolveAccountParams, ResolveAccountResponse, GetInstitutionsParams, CryptoWalletResponse, GetCryptoWalletParams, ListVirtualAccountsParams, CreateVirtualAccountParams, ListPoolAccountsParams, VirtualAccountListResponse, PoolAccountResponse, } from "@afriex/payment-methods";
+export type { Customer, CreateCustomerRequest, UpdateCustomerRequest, UpdateCustomerKycRequest, VerifyCustomerRequest, ListCustomersParams, CustomerListResponse, } from "@afriex/customers";
+export type { Transaction, CreateTransactionRequest, AuthorizeTransactionRequest, ListTransactionsParams, TransactionListResponse, TransactionListType, TransactionChannel, TransactionType, TransactionStatus, TransactionMeta, TransactionMetaResponse, TransactionFailureCode, TransactionFailureReason, } from "@afriex/transactions";
+export type { PaymentMethod, CreatePaymentMethodRequest, ListPaymentMethodsParams, PaymentMethodListResponse, PaymentChannel, CreatablePaymentChannel, PaymentMethodStatus, CardBrand, CardExpiration, Institution, InstitutionListChannel, ResolveAccountParams, ResolveAccountResponse, GetInstitutionsParams, CryptoWalletResponse, GetCryptoWalletParams, ListVirtualAccountsParams, CreateVirtualAccountParams, ListPoolAccountsParams, VirtualAccountListResponse, PoolAccountResponse, } from "@afriex/payment-methods";
 export type { BalanceResponse, GetBalanceParams } from "@afriex/balance";
 export type { RatesResponse, GetRatesParams } from "@afriex/rates";
 export type { CheckoutSession, CreateCheckoutSessionRequest, CheckoutCustomer, CheckoutChannel, } from "@afriex/checkout";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afriex/sdk",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "Official TypeScript SDK for the Afriex Business API",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,18 +20,19 @@
     }
   },
   "dependencies": {
-    "@afriex/core": "1.3.0",
-    "@afriex/customers": "1.4.0",
-    "@afriex/transactions": "1.4.0",
-    "@afriex/payment-methods": "2.0.0",
-    "@afriex/balance": "1.3.0",
-    "@afriex/rates": "1.4.0",
-    "@afriex/checkout": "2.0.0",
-    "@afriex/webhooks": "1.4.0"
+    "@afriex/core": "2.0.1",
+    "@afriex/customers": "2.0.1",
+    "@afriex/transactions": "2.0.1",
+    "@afriex/payment-methods": "3.0.1",
+    "@afriex/balance": "1.4.1",
+    "@afriex/rates": "1.4.2",
+    "@afriex/checkout": "2.0.2",
+    "@afriex/webhooks": "1.5.1"
   },
   "devDependencies": {
-    "rimraf": "^5.0.5",
-    "typescript": "^5.3.3"
+    "@tanstack/intent": "^0.3.6",
+    "rimraf": "^6.1.3",
+    "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"
@@ -39,7 +40,8 @@
   "files": [
     "dist",
     "README.md",
-    "!dist/**/*.map"
+    "!dist/**/*.map",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"
@@ -51,7 +53,8 @@
     "money-transfer",
     "payments",
     "fintech",
-    "typescript"
+    "typescript",
+    "tanstack-intent"
   ],
   "license": "MIT",
   "scripts": {

package/skills/afriex-go-live/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: afriex-go-live
+description: >
+  Pre-deploy security and correctness checklist for an Afriex Business API
+  integration built on @afriex/afriex. Verifies API key handling, Environment
+  selection, retry and timeout policy, transaction idempotency keys, webhook
+  signature verification against webhookPublicKey with raw bodies, at-least-once
+  delivery handling, sandbox-only endpoints, and error-code handling. Load
+  before shipping an Afriex integration to production, during a payments
+  security review, or when auditing an existing Afriex integration.
+metadata:
+  type: security
+  library: '@afriex/sdk'
+  library_version: '3.0.1'
+requires:
+  - 'afriex-sdk'
+sources:
+  - 'Afri-exchange/afriex-sdk:packages/sdk/src/index.ts'
+  - 'Afri-exchange/afriex-sdk:packages/core/src/config/Config.ts'
+  - 'Afri-exchange/afriex-sdk:packages/webhooks/src/WebhookService.ts'
+  - 'Afri-exchange/afriex-sdk:packages/transactions/src/TransactionService.ts'
+---
+
+# Afriex SDK — Go-Live Checklist
+
+Run through each section before pointing an integration at
+`Environment.PRODUCTION`. This skill builds on `afriex-sdk`; read it first for
+the configuration surface these checks refer to.
+
+## Credential Checks
+
+### Check: the API key comes from the environment, never source
+
+Expected:
+
+```ts
+import { AfriexSDK, Environment } from "@afriex/sdk";
+
+const apiKey = process.env.AFRIEX_API_KEY;
+if (!apiKey) {
+  throw new Error("AFRIEX_API_KEY is not set");
+}
+
+export const afriex = new AfriexSDK({ apiKey, environment: Environment.PRODUCTION });
+```
+
+Fail condition: an `apiKey` string literal, a key in a committed `.env`, or a
+key reaching client-side bundles.
+Fix: move the key to a server-side secret store and rotate the exposed one.
+
+### Check: production and sandbox keys are distinct variables
+
+Expected:
+
+```ts
+import { AfriexSDK, Environment } from "@afriex/sdk";
+
+const isProduction = process.env.NODE_ENV === "production";
+
+export const afriex = new AfriexSDK({
+  apiKey: (isProduction ? process.env.AFRIEX_API_KEY : process.env.AFRIEX_SANDBOX_API_KEY)!,
+  environment: isProduction ? Environment.PRODUCTION : Environment.STAGING,
+});
+```
+
+Fail condition: one `AFRIEX_API_KEY` variable reused across environments, or
+`environment` omitted entirely.
+Fix: separate the variables — `Config` defaults `environment` to
+`Environment.PRODUCTION`, so an omitted field silently targets live money.
+
+## Transport Checks
+
+### Check: retries are explicitly configured
+
+Expected:
+
+```ts
+import { AfriexSDK, Environment } from "@afriex/sdk";
+
+export const afriex = new AfriexSDK({
+  apiKey: process.env.AFRIEX_API_KEY!,
+  environment: Environment.PRODUCTION,
+  retryConfig: {
+    maxRetries: 3,
+    retryDelay: 1000,
+    retryableStatusCodes: [408, 429, 500, 502, 503, 504],
+  },
+});
+```
+
+Fail condition: no `retryConfig` — `DEFAULT_CONFIG` sets `maxRetries: 0`, so a
+single 503 fails the request outright.
+Fix: supply `retryConfig`, and make sure every retried write carries a stable
+`meta.idempotencyKey`.
+
+### Check: request logging does not leak request bodies
+
+Expected:
+
+```ts
+import { AfriexSDK, Environment, LogLevel } from "@afriex/sdk";
+
+export const afriex = new AfriexSDK({
+  apiKey: process.env.AFRIEX_API_KEY!,
+  environment: Environment.PRODUCTION,
+  enableLogging: true,
+  logLevel: LogLevel.ERROR,
+});
+```
+
+Fail condition: `logLevel: LogLevel.DEBUG` in production, which logs request
+and response metadata for every call.
+Fix: keep production at `LogLevel.ERROR` and scrub customer data from any
+handler that serializes `ApiError.details`.
+
+## Money-Movement Checks
+
+### Check: every transaction carries a stable idempotency key
+
+Expected:
+
+```ts
+import { AfriexSDK } from "@afriex/sdk";
+import { randomUUID } from "node:crypto";
+
+const afriex = new AfriexSDK({ apiKey: process.env.AFRIEX_API_KEY! });
+
+export async function payout(orderId: string, idempotencyKey: string) {
+  return afriex.transactions.create({
+    customerId: "cus_123",
+    destinationId: "pm_456",
+    sourceAmount: "100.00",
+    sourceCurrency: "USD",
+    destinationAmount: "150000.00",
+    destinationCurrency: "NGN",
+    meta: { idempotencyKey, reference: orderId },
+  });
+}
+
+export const keyForOrder = (orderId: string) => `${orderId}:${randomUUID()}`;
+```
+
+Fail condition: `idempotencyKey: randomUUID()` generated inside a retry loop or
+inside the request handler, so each attempt is a new key.
+Fix: persist the key with the order before the first attempt and reuse it for
+every retry.
+
+### Check: settlement is driven by webhooks, not by create() resolving
+
+Expected:
+
+```ts
+import type { TransactionWebhookPayload } from "@afriex/sdk";
+
+const TERMINAL = new Set(["SUCCESS", "FAILED", "CANCELLED", "REJECTED", "REFUNDED"]);
+
+export function isSettled(event: TransactionWebhookPayload): boolean {
+  return TERMINAL.has(event.data.status);
+}
+```
+
+Fail condition: order state marked paid immediately after
+`transactions.create()` resolves.
+Fix: treat `PENDING` and `PROCESSING` as in-flight and settle on
+`TRANSACTION.UPDATED`.
+
+### Check: no sandbox-only calls run in production
+
+Expected:
+
+```ts
+import { AfriexSDK, Environment } from "@afriex/sdk";
+
+const afriex = new AfriexSDK({
+  apiKey: process.env.AFRIEX_SANDBOX_API_KEY!,
+  environment: Environment.STAGING,
+});
+
+export async function seedTestWallet(): Promise<void> {
+  if (process.env.NODE_ENV === "production") {
+    return;
+  }
+  await afriex.balance.topUpSandbox({ amount: 10000, currency: "USD" });
+  await afriex.webhooks.triggerTestWebhook({
+    event: "TRANSACTION.UPDATED",
+    entityId: "507f1f77bcf86cd799439011",
+  });
+}
+```
+
+Fail condition: `topUpSandbox` or `triggerTestWebhook` reachable on a
+production code path — both answer `403 FORBIDDEN` there.
+Fix: guard them behind an environment check or keep them in test-only modules.
+
+## Webhook Checks
+
+### Check: the endpoint verifies signatures against the raw body
+
+Expected:
+
+```ts
+import express from "express";
+import { AfriexSDK, WEBHOOK_SIGNATURE_HEADER } from "@afriex/sdk";
+
+const webhookPublicKey = process.env.AFRIEX_WEBHOOK_PUBLIC_KEY;
+if (!webhookPublicKey) {
+  throw new Error("AFRIEX_WEBHOOK_PUBLIC_KEY is not set");
+}
+
+const afriex = new AfriexSDK({ apiKey: process.env.AFRIEX_API_KEY!, webhookPublicKey });
+const app = express();
+
+app.post(
+  "/webhooks/afriex",
+  express.raw({ type: "application/json" }),
+  (req, res) => {
+    try {
+      const event = afriex.webhooks.verifyAndParse(
+        req.body.toString("utf8"),
+        req.header(WEBHOOK_SIGNATURE_HEADER) ?? ""
+      );
+      console.log(event.event);
+      res.sendStatus(200);
+    } catch {
+      res.sendStatus(400);
+    }
+  }
+);
+```
+
+Fail condition: `express.json()` applied to the webhook route, or
+`JSON.stringify(req.body)` passed to `verify`.
+Fix: mount `express.raw` on the webhook path and verify the exact bytes.
+
+### Check: a missing public key fails closed
+
+Expected:
+
+```ts
+import { AfriexSDK } from "@afriex/sdk";
+
+const webhookPublicKey = process.env.AFRIEX_WEBHOOK_PUBLIC_KEY;
+if (!webhookPublicKey) {
+  throw new Error("AFRIEX_WEBHOOK_PUBLIC_KEY is not set");
+}
+
+export const afriex = new AfriexSDK({
+  apiKey: process.env.AFRIEX_API_KEY!,
+  webhookPublicKey,
+});
+```
+
+Fail condition: the handler logs a warning and processes the payload when
+`verify` returns `false`.
+Fix: assert the key at boot and use `verifyAndParse`, which throws on a missing
+key instead of returning `false`.
+
+### Check: handlers are idempotent across redeliveries
+
+Expected:
+
+```ts
+import type { TransactionWebhookPayload } from "@afriex/sdk";
+
+export async function onTransaction(
+  event: TransactionWebhookPayload,
+  seen: { has(key: string): Promise<boolean>; add(key: string): Promise<void> }
+): Promise<void> {
+  const key = `${event.data.transactionId}:${event.data.status}`;
+  if (await seen.has(key)) {
+    return;
+  }
+  await seen.add(key);
+  console.log("processing", key);
+}
+```
+
+Fail condition: side effects run on every delivery with no deduplication key.
+Fix: deduplicate on `transactionId` plus `status` in durable storage.
+
+## Common Security Mistakes
+
+### HIGH Returning ApiError.message to end users as an error code
+
+Wrong:
+
+```ts
+import { ApiError } from "@afriex/sdk";
+
+export function toClientError(error: unknown): { code: string } {
+  return { code: error instanceof ApiError ? error.message : "UNKNOWN" };
+}
+```
+
+Correct:
+
+```ts
+import { ApiError, AfriexErrorCode } from "@afriex/sdk";
+
+export function toClientError(error: unknown): { code: string; message: string } {
+  if (error instanceof ApiError) {
+    return {
+      code: error.errorCode ?? AfriexErrorCode.UNKNOWN_ERROR,
+      message: error.details?.friendlyMessage ?? "Payment could not be completed",
+    };
+  }
+  return { code: AfriexErrorCode.UNKNOWN_ERROR, message: "Payment could not be completed" };
+}
+```
+
+`ApiError.message` falls back through `friendlyMessage`, `errorMessage`, and
+`error`, so it can surface internal technical detail as a client-facing code
+and it changes without a version bump.
+
+Source: packages/core/src/errors/ApiError.ts
+
+## Pre-Deploy Summary
+
+- [ ] API key read from a secret store; no key in source or client bundles
+- [ ] Separate sandbox and production keys; `environment` set explicitly
+- [ ] `retryConfig` configured — retries are off by default
+- [ ] `logLevel` is `LogLevel.ERROR` in production
+- [ ] Every `transactions.create` carries a persisted, reused `meta.idempotencyKey`
+- [ ] Order state settles on `TRANSACTION.UPDATED`, not on `create()` resolving
+- [ ] `topUpSandbox` and `triggerTestWebhook` are unreachable in production
+- [ ] Webhook route uses a raw body parser and `verifyAndParse`
+- [ ] `AFRIEX_WEBHOOK_PUBLIC_KEY` asserted at boot
+- [ ] Webhook handlers deduplicate on `transactionId` plus `status`
+- [ ] Client-facing errors use `errorCode`, not `ApiError.message`

package/skills/afriex-sdk/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: afriex-sdk
+description: >
+  Entry point for the Afriex Business API TypeScript SDK (@afriex/sdk) — the
+  AfriexSDK / Afriex facade and its customers, transactions, paymentMethods,
+  balance, rates, checkout, and webhooks services. Covers installation,
+  AfriexSDKConfig including webhookPublicKey, choosing sandbox vs production,
+  the end-to-end customer → payment method → transaction → webhook payout flow,
+  and which sub-skill covers each service. Load when starting an Afriex
+  integration, sending or collecting cross-border payments in TypeScript, or
+  deciding which Afriex service to call.
+metadata:
+  type: core
+  library: '@afriex/sdk'
+  library_version: '3.0.1'
+sources:
+  - 'Afri-exchange/afriex-sdk:packages/sdk/src/index.ts'
+  - 'Afri-exchange/afriex-sdk:packages/core/src/config/Config.ts'
+  - 'Afri-exchange/afriex-sdk:README.md'
+---
+
+# Afriex SDK
+
+`@afriex/sdk` is the umbrella package for the Afriex Business API. `AfriexSDK`
+extends `AfriexClient` from `@afriex/core` and constructs every service against
+one shared `HttpClient`, so a single instance carries the API key, environment,
+retry policy, and logging for the whole integration. Individual services also
+ship as standalone `@afriex/*` packages when only part of the surface is
+needed.
+
+## Setup
+
+```ts
+import { AfriexSDK, Environment } from "@afriex/sdk";
+
+export const afriex = new AfriexSDK({
+  apiKey: process.env.AFRIEX_API_KEY!,
+  environment:
+    process.env.NODE_ENV === "production"
+      ? Environment.PRODUCTION
+      : Environment.STAGING,
+  webhookPublicKey: process.env.AFRIEX_WEBHOOK_PUBLIC_KEY,
+  retryConfig: {
+    maxRetries: 3,
+    retryDelay: 1000,
+    retryableStatusCodes: [408, 429, 500, 502, 503, 504],
+  },
+});
+```
+
+Install with `npm install @afriex/sdk`. Create one instance at module scope and
+import it where needed — each construction builds a fresh HTTP client.
+
+## Services
+
+| Need to...                                        | Use                     | Skill                             |
+| ------------------------------------------------- | ----------------------- | --------------------------------- |
+| Register senders and recipients, submit KYC       | `afriex.customers`         | `afriex-customers`                |
+| Add bank, mobile money, or virtual account rails  | `afriex.paymentMethods`    | `afriex-payment-methods`          |
+| Send payouts, collect deposits, swap currencies   | `afriex.transactions`      | `afriex-transactions`             |
+| Read wallet balances, fund a sandbox wallet       | `afriex.balance`           | `afriex-balance`                  |
+| Quote exchange rates                              | `afriex.rates`             | `afriex-rates`                    |
+| Host a payment page                               | `afriex.checkout`          | `afriex-checkout`                 |
+| Verify inbound events, replay test events         | `afriex.webhooks`          | `afriex-webhooks`                 |
+| Configure transport, errors, retries              | `AfriexClient`, errors  | `afriex-core`                     |
+| Ship to production safely                         | —                       | `afriex-go-live`                  |
+
+## Core Patterns
+
+### End-to-end payout
+
+```ts
+import { AfriexSDK, Environment } from "@afriex/sdk";
+import { randomUUID } from "node:crypto";
+
+const afriex = new AfriexSDK({
+  apiKey: process.env.AFRIEX_API_KEY!,
+  environment: Environment.STAGING,
+});
+
+const customer = await afriex.customers.create({
+  fullName: "Ada Lovelace",
+  email: "ada@example.com",
+  phone: "+2348012345678",
+  countryCode: "NG",
+});
+
+const institutions = await afriex.paymentMethods.getInstitutions({
+  channel: "BANK_ACCOUNT",
+  countryCode: "NG",
+});
+
+const destination = await afriex.paymentMethods.create({
+  channel: "BANK_ACCOUNT",
+  customerId: customer.customerId,
+  accountName: customer.name,
+  accountNumber: "0123456789",
+  countryCode: "NG",
+  institution: {
+    institutionId: institutions[0].institutionId,
+    institutionCode: institutions[0].institutionCode,
+    institutionName: institutions[0].institutionName,
+  },
+});
+
+const transaction = await afriex.transactions.create({
+  customerId: customer.customerId,
+  destinationId: destination.paymentMethodId,
+  sourceAmount: "100.00",
+  sourceCurrency: "USD",
+  destinationAmount: "150000.00",
+  destinationCurrency: "NGN",
+  meta: { idempotencyKey: randomUUID(), reference: "order_9981" },
+});
+
+console.log(transaction.transactionId, transaction.status);
+```
+
+The transaction resolves as `PENDING` or `PROCESSING`; settlement arrives as a
+`TRANSACTION.UPDATED` webhook.
+
+### Import only the services you use
+
+```ts
+import { AfriexClient, Environment } from "@afriex/core";
+import { RateService } from "@afriex/rates";
+
+const client = new AfriexClient({
+  apiKey: process.env.AFRIEX_API_KEY!,
+  environment: Environment.STAGING,
+});
+
+const rates = new RateService(client.getHttpClient());
+console.log(await rates.getRate("USD", "NGN"));
+```
+
+Every service takes the `HttpClient` returned by `client.getHttpClient()`.
+
+### Handle errors once, at the edge
+
+```ts
+import { AfriexSDK, ApiError, RateLimitError, ValidationError } from "@afriex/sdk";
+
+const afriex = new AfriexSDK({ apiKey: process.env.AFRIEX_API_KEY! });
+
+export async function safeGetTransaction(id: string) {
+  try {
+    return await afriex.transactions.get(id);
+  } catch (error) {
+    if (error instanceof RateLimitError) {
+      throw new Error(`rate limited, retry after ${error.retryAfter ?? 1}s`);
+    }
+    if (error instanceof ValidationError) {
+      throw new Error(`bad request: ${JSON.stringify(error.fields)}`);
+    }
+    if (error instanceof ApiError) {
+      throw new Error(`afriex ${error.statusCode} ${error.errorCode}`);
+    }
+    throw error;
+  }
+}
+```
+
+`@afriex/sdk` re-exports everything from `@afriex/core`, so error classes and
+`Environment` come from the same import.
+
+## Common Mistakes
+
+### HIGH Calling afriex.webhookVerifier without configuring a public key
+
+Wrong:
+
+```ts
+import { AfriexSDK } from "@afriex/sdk";
+
+const afriex = new AfriexSDK({ apiKey: process.env.AFRIEX_API_KEY! });
+
+export function handle(rawBody: string, signature: string) {
+  return afriex.webhookVerifier!.verifyAndParse(rawBody, signature);
+}
+```
+
+Correct:
+
+```ts
+import { AfriexSDK } from "@afriex/sdk";
+
+const afriex = new AfriexSDK({
+  apiKey: process.env.AFRIEX_API_KEY!,
+  webhookPublicKey: process.env.AFRIEX_WEBHOOK_PUBLIC_KEY!,
+});
+
+export function handle(rawBody: string, signature: string) {
+  return afriex.webhooks.verifyAndParse(rawBody, signature);
+}
+```
+
+`webhookVerifier` is assigned only when `webhookPublicKey` is present, so the
+non-null assertion throws `Cannot read properties of undefined` at the first
+delivery; `afriex.webhooks` always exists and is the same object when the key is
+configured.
+
+Source: packages/sdk/src/index.ts (`if (config.webhookPublicKey) this.webhookVerifier = this.webhooks`)
+
+### HIGH Constructing a new AfriexSDK per request
+
+Wrong:
+
+```ts
+import { AfriexSDK, Environment } from "@afriex/sdk";
+
+export async function getBalances() {
+  const afriex = new AfriexSDK({
+    apiKey: process.env.AFRIEX_API_KEY!,
+    environment: Environment.PRODUCTION,
+  });
+  return afriex.balance.getBalance();
+}
+```
+
+Correct:
+
+```ts
+import { AfriexSDK, Environment } from "@afriex/sdk";
+
+const afriex = new AfriexSDK({
+  apiKey: process.env.AFRIEX_API_KEY!,
+  environment: Environment.PRODUCTION,
+});
+
+export async function getBalances() {
+  return afriex.balance.getBalance();
+}
+```
+
+Each `AfriexSDK` builds a fresh `ky` instance and seven service objects, so
+per-request construction discards connection reuse and multiplies allocation
+under load.
+
+Source: packages/sdk/src/index.ts (constructor)
+
+### MEDIUM Omitting environment and defaulting to production
+
+Wrong:
+
+```ts
+import { AfriexSDK } from "@afriex/sdk";
+
+const afriex = new AfriexSDK({ apiKey: process.env.AFRIEX_API_KEY! });
+```
+
+Correct:
+
+```ts
+import { AfriexSDK, Environment } from "@afriex/sdk";
+
+const afriex = new AfriexSDK({
+  apiKey: process.env.AFRIEX_API_KEY!,
+  environment:
+    process.env.NODE_ENV === "production"
+      ? Environment.PRODUCTION
+      : Environment.STAGING,
+});
+```
+
+`Config` defaults `environment` to `Environment.PRODUCTION`, so an integration
+test written without the field points at the live API and moves real money.
+
+Source: packages/core/src/config/Config.ts (environment default)
+
+See also: afriex-go-live/SKILL.md — the pre-deploy checklist for this
+configuration.