@afriex/sdk 5.1.0 → 6.0.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `@afriex/sdk`. Versions 5.x and earlier were built in the [afriex-sdk](https://github.com/Afri-exchange/afriex-sdk) repository; see its changelog for them.
+
+<!-- Entries go below this line, newest first. -->
+
+## 6.0.0
+
+The SDK now lives next to the API reference and is generated from its OpenAPI spec, so it changes when the API does.
+
+### New
+
+- A method for every endpoint in the API reference, including `transactions.quote()`.
+- Types for every request, response and webhook event, generated from the spec. Webhook events are a union you can narrow on `event`.
+- `for await` over any list method walks every page. Pages also have `hasNextPage()`, `getNextPage()` and `iterPages()`.
+- `withResponse()` on every call returns the HTTP response and its `requestId`.
+- Per-request options as the last argument: `timeout`, `maxRetries`, `headers` and `signal`.
+- One error class per status, each with `status`, `code`, `details`, `headers` and `requestId`.
+- `afriex.request()` calls an endpoint the SDK doesn't cover yet.
+- `apiKey` defaults to the `AFRIEX_API_KEY` environment variable.
+- ESM and CommonJS builds, no runtime dependencies.
+
+### Breaking changes, and how to migrate from 5.x
+
+- **One package.** Import everything from `@afriex/sdk`. The SDK no longer uses `@afriex/core`, `@afriex/customers`, `@afriex/transactions` or the other per-resource packages, so remove them from your dependencies.
+- **Node 20 or later.**
+- **Retries are on by default** (`maxRetries: 2`), but only where they are safe: any request on `429`, and `GET` requests and `transactions.create` on timeouts and server errors. `retryConfig` is replaced by `maxRetries`, and `retryableMethods` and `retryableStatusCodes` are gone. See "Retries" in the README.
+- **Configuration.** `customConfig.baseUrl` is now `baseURL`, and `customConfig.timeout` is now `timeout`. `userAgent`, `logLevel` and `enableLogging` are removed. `environment` takes `'sandbox'`; `'staging'` still works.
+- **Errors.** `ApiError` is now `APIError`, with a subclass per status (`NotFoundError`, `ConflictError` and so on). `RateLimitError` extends it. `NetworkError` is now `APIConnectionError`. `ValidationError` is removed: the SDK no longer validates requests itself, and the API's `400` or `422` arrives as `BadRequestError` or `UnprocessableEntityError`.
+- **Return values.** Every method resolves to the response's `data`, except:
+  - list methods, which resolve to a page, `{data, total, page}`, as before;
+  - `paymentMethods.getInstitutions()` and `paymentMethods.listVirtualAccounts()`, which resolve to the whole response, as before;
+  - `paymentMethods.delete()`, which resolves to the whole response.
+
+  `paymentMethods.resolveAccount()`, `paymentMethods.resolveInstitutionCode()`, `paymentMethods.getCryptoWallet()` and `webhooks.triggerTestWebhook()` used to resolve to the whole response and now resolve to its `data`. `customers.delete()`, `paymentBatches.delete()` and `paymentBatches.removeRecipient()` used to resolve to nothing and now resolve to the response's `data`. `paymentMethods.createVirtualAccount()` resolves to the response's `data` rather than `null` when the account opens later.
+- **Type names** follow the spec and the `<Resource><Action>Params` pattern: `CreateCustomerRequest` is now `CustomerCreateParams`, `ListTransactionsParams` is now `TransactionListParams`, `WebhookPayload` is now `WebhookEvent`, and so on. Field types are exactly what the spec says. Where the spec does not mark a response field as required, its type is optional.
+- **Removed helpers:** `balance.getBalanceForCurrency()`, `rates.getRate()` and `rates.convert()`. Use `balance.getBalance()` and `rates.getRates()`.
+- **Webhooks.** The `WebhookVerifier` class and the `webhookVerifier` property are removed: create the client with `webhookPublicKey` and call `afriex.webhooks.verify()` or `verifyAndParse()`. Both now accept the header value as Node gives it (`string | string[] | undefined`). `verifyAndParse()` throws `WebhookVerificationError`. `triggerTestWebhook()` no longer accepts the deprecated `resourceId`: use `entityId`.
+- `paymentMethods.listPoolAccounts()` is deprecated: use `paymentMethods.getPoolAccount()`.

package/README.md

@@ -1,199 +1,206 @@
-# @afriex/sdk
+# Afriex TypeScript SDK
 
-Official TypeScript SDK for the Afriex Business API. A unified interface for all Afriex services.
+The official TypeScript and JavaScript client for the [Afriex Business API](https://docs.afriex.com). It is generated from the same OpenAPI spec as the API reference, so its types always match the documented API.
 
-## Installation
+- One package, no runtime dependencies, built on the platform's `fetch`
+- Full types for every request, response and webhook event
+- Retries with backoff where they are safe, timeouts, and typed errors
+- Pagination you can `for await` over
+- ESM and CommonJS, Node 20 or later
+
+## Install
 
 ```bash
 npm install @afriex/sdk
-# or
-pnpm add @afriex/sdk
 ```
 
-## Quick Start
+## Usage
 
-```typescript
-import { AfriexSDK } from "@afriex/sdk";
-// or use the alias
-import { Afriex } from "@afriex/sdk";
+```ts
+import {Afriex} from '@afriex/sdk';
 
-const afriex = new AfriexSDK({
-  apiKey: "your-api-key",
-  environment: "production", // or 'staging' (default: 'production')
-  webhookPublicKey: "-----BEGIN PUBLIC KEY-----...", // optional
+const afriex = new Afriex({
+  apiKey: process.env.AFRIEX_API_KEY, // the default, so you can leave it out
+  environment: 'sandbox', // or 'production', the default
 });
 
-// Customers
 const customer = await afriex.customers.create({
-  fullName: "John Doe",
-  email: "john@example.com",
-  phone: "+1234567890",
-  countryCode: "US",
-});
-
-// Payment Methods
-const paymentMethod = await afriex.paymentMethods.create({
-  customerId: customer.customerId,
-  channel: "BANK_ACCOUNT",
-  accountName: "John Doe",
-  accountNumber: "1234567890",
-  countryCode: "NG",
-  institution: {
-    institutionCode: "058",
-    institutionName: "GTBank",
-  },
+  fullName: 'Ada Obi',
+  email: 'ada@example.com',
+  phone: '+2348012345678',
+  countryCode: 'NG',
 });
 
-// Transactions
 const transaction = await afriex.transactions.create({
-  customerId: customer.customerId,
-  sourceAmount: "100",
-  destinationAmount: "50000",
-  sourceCurrency: "USD",
-  destinationCurrency: "NGN",
-  destinationId: paymentMethod.paymentMethodId,
-  meta: {
-    idempotencyKey: "quick-start-transaction-1",
-    reference: "order-123",
-  },
+  customerId: customer.customerId!,
+  destinationId: 'payment-method-id',
+  sourceAmount: '10',
+  sourceCurrency: 'USD',
+  destinationCurrency: 'NGN',
+  meta: {idempotencyKey: crypto.randomUUID(), reference: 'order-456'},
 });
+```
 
-// Rates
-const rate = await afriex.rates.getRate("USD", "NGN");
+Every endpoint in the [API reference](https://docs.afriex.com/api-reference/introduction) has a method, grouped by resource: `customers`, `transactions`, `paymentMethods`, `paymentBatches`, `balance`, `rates`, `checkout`, `media`, `smeRegistration` and `webhooks`. Each endpoint page shows its SDK call.
 
-// Balance
-const balances = await afriex.balance.getBalance({
-  currencies: ["USD", "NGN"],
-});
+Keep your API key on your server. The SDK refuses to run in a browser.
 
-// 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",
-  channels: ["VIRTUAL_BANK_ACCOUNT", "MOBILE_MONEY", "CARD"],
-  customer: {
-    name: "John Doe",
-    email: "john@example.com",
-    phone: "+1234567890",
-    countryCode: "US",
-  },
+## Configuration
+
+| Option | Default | Description |
+| :-- | :-- | :-- |
+| `apiKey` | `AFRIEX_API_KEY` | Your API key, from **Developer → API keys** in the dashboard |
+| `environment` | `'production'` | `'sandbox'` or `'production'`. `'staging'` also means the sandbox |
+| `baseURL` | from `environment` | Overrides the base URL |
+| `timeout` | `30000` | Milliseconds to wait for each attempt |
+| `maxRetries` | `2` | Retries for a failed request. See [Retries](#retries) |
+| `apiVersion` | `'2026-05-18'` | Sent as `x-api-version`. Each SDK release targets one API version |
+| `webhookPublicKey` | none | Verifies webhook signatures. See [Webhooks](#webhooks) |
+| `signRequest` | none | Returns the `x-api-signature` for a request, if your business has [request signing](https://docs.afriex.com/api-reference/authentication#request-signing) enabled |
+| `defaultHeaders` | none | Headers sent with every request |
+| `fetch` | global `fetch` | A `fetch` implementation to use instead |
+
+`environment` defaults to production, so set it while you integrate.
+
+## Per-request options
+
+Every method takes an options object last:
+
+```ts
+const customer = await afriex.customers.get('customer-id', {
+  timeout: 5_000,
+  maxRetries: 0,
+  signal: AbortSignal.timeout(10_000),
+  headers: {'x-correlation-id': 'abc'},
 });
-// session.checkoutUrl, session.channels
+```
+
+## Errors
 
-// Webhook verification (requires webhookPublicKey)
-const isValid = afriex.webhooks.verify(payload, signature);
+A failed request throws. A response outside 2xx throws an `APIError` subclass that carries the status, the API's error `code` and `details`, the response headers, and the `requestId` to quote to support:
+
+| Status | Error |
+| :-- | :-- |
+| 400 | `BadRequestError` |
+| 401 | `AuthenticationError` (wrong key, or a key without this endpoint's permission) |
+| 403 | `PermissionDeniedError` |
+| 404 | `NotFoundError` |
+| 409 | `ConflictError` |
+| 422 | `UnprocessableEntityError` |
+| 429 | `RateLimitError`, with `retryAfter` in seconds |
+| 500 and above | `InternalServerError` |
+| no response | `APIConnectionError`, or `APIConnectionTimeoutError` after the timeout |
+| you aborted | `APIUserAbortError` |
+
+```ts
+import {APIError, ConflictError} from '@afriex/sdk';
+
+try {
+  await afriex.transactions.create(params);
+} catch (error) {
+  if (error instanceof ConflictError && error.code === 'DUPLICATE_REQUEST') {
+    // The idempotency key or reference is taken: look the transaction up.
+    const page = await afriex.transactions.list({reference: params.meta?.reference});
+  } else if (error instanceof APIError) {
+    console.error(error.status, error.code, error.requestId);
+  }
+  throw error;
+}
 ```
 
-## Available Services
+Every error extends `AfriexError`.
 
-| 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.paymentBatches` | Pay many recipients in one call                             |
-| `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.media`          | Upload invoices, payment proofs and documents               |
-| `afriex.smeRegistration` | Register the business for dedicated KES virtual accounts   |
-| `afriex.webhooks`       | Webhook signature verification and sandbox test triggers    |
+## Retries
 
-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.
+The SDK retries a request only when sending it again can't repeat its effect:
 
-## Configuration
+- **Every request on `429`.** The API rejects it before doing anything. The SDK waits for `Retry-After`.
+- **`GET` requests,** and **`transactions.create`,** on a timeout, a dropped connection, `408` or a `5xx`. A transaction create is safe to send again because the API refuses a second request with the same `meta.idempotencyKey`. If the first attempt went through, the retry gets `409 DUPLICATE_REQUEST`: look the transaction up by its reference. See [Idempotency](https://docs.afriex.com/api-reference/idempotency).
 
-```typescript
-interface AfriexSDKConfig {
-  apiKey: string; // Required - Your Afriex API key
-  environment?: "staging" | "production"; // Default: 'production'
-  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]
-    retryableMethods?: HttpMethod[]; // Default: every method except POST and PATCH
-  };
-  apiVersion?: string; // Default: '2026-05-18', sent as x-api-version
-  signRequest?: RequestSigner; // Optional - returns the x-api-signature value
-  userAgent?: string; // Default: 'Afriex-TypeScript-SDK/<version of @afriex/sdk>'
+Other `POST`, `PATCH` and `DELETE` requests are not retried on errors. The API has no idempotency key for them, so a retry could create a second customer or payment method.
+
+Retries wait 0.5 seconds, doubling each time up to 8 seconds, with jitter. Set `maxRetries: 0` to turn them off.
+
+## Pagination
+
+List methods return the first page as the API sends it, `{data, total, page}`:
+
+```ts
+const page = await afriex.transactions.list({limit: 100, status: ['SUCCESS']});
+console.log(page.data, page.total);
+```
+
+Iterate the call with `for await` to walk every item across every page:
+
+```ts
+for await (const transaction of afriex.transactions.list({limit: 100})) {
+  console.log(transaction.transactionId);
 }
 ```
 
-`SDK_VERSION` holds the version of `@afriex/sdk` that is installed.
+A page also has `hasNextPage()`, `getNextPage()` and `iterPages()`.
 
-Retries are off by default. When they are on, `POST` and `PATCH` requests are
-still sent once unless `retryableMethods` lists them. See
-[`@afriex/core`](https://www.npmjs.com/package/@afriex/core) for retries and
-request signing.
+## Webhooks
 
-`staging` points at `https://sandbox.api.afriex.com/api/v1`, `production` at
-`https://api.afriex.com/api/v1`.
+Verify a webhook before you act on it. The signature covers the exact bytes Afriex sent, so pass the raw body, not parsed JSON:
 
-## Error Handling
+```ts
+import express from 'express';
+import {Afriex, WEBHOOK_SIGNATURE_HEADER, WebhookVerificationError} from '@afriex/sdk';
 
-All errors extend `AfriexError` and are re-exported from this package:
+const afriex = new Afriex({webhookPublicKey: process.env.AFRIEX_WEBHOOK_PUBLIC_KEY});
+const app = express();
 
-```typescript
-import { AfriexError, ApiError, ValidationError, RateLimitError, NetworkError } from "@afriex/sdk";
+app.post('/webhooks/afriex', express.raw({type: 'application/json'}), (req, res) => {
+  let event;
+  try {
+    event = afriex.webhooks.verifyAndParse(req.body, req.headers[WEBHOOK_SIGNATURE_HEADER]);
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) return res.status(400).send('Invalid signature');
+    throw error;
+  }
 
-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
+  switch (event.event) {
+    case 'TRANSACTION.UPDATED':
+      console.log(event.data.transactionId, event.data.status);
+      break;
+    case 'CUSTOMER.CREATED':
+      console.log(event.data.customerId);
+      break;
   }
-}
+  res.sendStatus(200);
+});
 ```
 
-## Individual Packages
+`event` is typed by its `event` name. `afriex.webhooks.verify()` returns a boolean instead of throwing. Store each event before you acknowledge it, keyed on `event.id`: see [Duplicates, ordering, and replays](https://docs.afriex.com/api-reference/endpoint/webhooks/introduction#duplicates-ordering-and-replays).
 
-For smaller bundle sizes, install packages individually:
+## The raw response
 
-| 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/payment-batches` | Bulk payouts to a saved list of recipients             |
-| `@afriex/balance`         | Balance queries and sandbox top-ups                    |
-| `@afriex/rates`           | Exchange rates and conversions                         |
-| `@afriex/checkout`        | Hosted checkout sessions                               |
-| `@afriex/media`           | File uploads                                           |
-| `@afriex/sme-registration` | SME registration for KES virtual accounts             |
-| `@afriex/webhooks`        | Webhook verification and test triggers                 |
+Every method returns an `APIPromise`. Call `withResponse()` for the HTTP response and its request id:
 
-Each service package depends only on `@afriex/core`, so you can mix and match.
+```ts
+const {data: customer, response, requestId} = await afriex.customers.get('customer-id').withResponse();
+```
 
-## AI agents
+## Types
 
-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:
+Request and response types are exported by name, such as `Customer`, `Transaction`, `TransactionCreateParams` and `WebhookEvent`. Every type in the spec is also available under the `OpenAPI` namespace:
 
-```bash
-npx @tanstack/intent@latest install
+```ts
+import type {OpenAPI} from '@afriex/sdk';
+type Status = OpenAPI.components['schemas']['TransactionStatus'];
 ```
 
-List what is available with `npx @tanstack/intent@latest list`.
+An endpoint the SDK doesn't cover yet can be called with `afriex.request('get', '/api/v1/...', {query})`.
+
+## Requirements
+
+Node 20 or later. The SDK uses `fetch` and `node:crypto` (for webhooks), so it also runs on Bun, Deno, and edge runtimes with Node compatibility.
 
-## Documentation
+## Versioning
 
-Full documentation available at [docs.afriex.com](https://docs.afriex.com/sdk/introduction)
+The SDK follows [semantic versioning](https://semver.org). Each release targets the API version in `API_VERSION`. A change to the API that adds to it ships as a minor release; one that would break existing code ships as a major release. Releases are listed in the [changelog](https://docs.afriex.com/changelog), and [Upgrading from version 5](https://docs.afriex.com/sdk/introduction#upgrading-from-version-5) covers the move to 6.0.
 
-## License
+## Support
 
-MIT
+Full documentation is at [docs.afriex.com/sdk](https://docs.afriex.com/sdk/introduction). If something doesn't work as documented, email [support@afriex.com](mailto:support@afriex.com) with the `requestId` from the error.

package/dist/cjs/client.d.ts

@@ -0,0 +1,110 @@
+import { APIPromise } from './core/api-promise.js';
+import { PagePromise } from './core/pagination.js';
+import type { RequestOptions } from './core/types.js';
+import { Balance } from './resources/balance.js';
+import { Checkout } from './resources/checkout.js';
+import { Customers } from './resources/customers.js';
+import { Media } from './resources/media.js';
+import { PaymentBatches } from './resources/payment-batches.js';
+import { PaymentMethods } from './resources/payment-methods.js';
+import { Rates } from './resources/rates.js';
+import { SmeRegistration } from './resources/sme-registration.js';
+import { Transactions } from './resources/transactions.js';
+import { Webhooks } from './resources/webhooks.js';
+/** The base URL of each environment. `staging` is the sandbox's older name. */
+export declare const ENVIRONMENTS: {
+    readonly sandbox: "https://sandbox.api.afriex.com";
+    readonly staging: "https://sandbox.api.afriex.com";
+    readonly production: "https://api.afriex.com";
+};
+export type Environment = keyof typeof ENVIRONMENTS;
+/**
+ * The API version this release of the SDK was built against, sent as
+ * `x-api-version`. Each SDK release targets one API version.
+ */
+export declare const API_VERSION = "2026-05-18";
+/** What `signRequest` receives: the request exactly as it will be sent. */
+export interface SignableRequest {
+    method: string;
+    url: string;
+    body: string;
+}
+export interface ClientOptions {
+    /** Your Afriex API key. Defaults to the `AFRIEX_API_KEY` environment variable. */
+    apiKey?: string;
+    /**
+     * `'sandbox'` or `'production'`. Defaults to `'production'`, so set it
+     * explicitly while you integrate. `'staging'` is accepted as the sandbox.
+     */
+    environment?: Environment;
+    /** Overrides the base URL that `environment` selects. */
+    baseURL?: string;
+    /** Sent as `x-api-version`. Defaults to `API_VERSION`. */
+    apiVersion?: string;
+    /** Milliseconds to wait for each attempt. Defaults to 30 seconds. */
+    timeout?: number;
+    /**
+     * How many times to retry a failed request. Defaults to 2. See the README
+     * for which requests are retried.
+     */
+    maxRetries?: number;
+    /**
+     * Returns the `x-api-signature` for a request, if your business has request
+     * signing enabled.
+     */
+    signRequest?: (request: SignableRequest) => string | undefined | Promise<string | undefined>;
+    /** Afriex's public key for webhook signatures, from **Developer → Webhook** in the dashboard. */
+    webhookPublicKey?: string;
+    /** Headers sent with every request. */
+    defaultHeaders?: Record<string, string>;
+    /** A `fetch` implementation to use instead of the global one. */
+    fetch?: typeof fetch;
+    /**
+     * The SDK refuses to run in a browser, where your API key would be visible
+     * to anyone. Set this only if you understand that.
+     */
+    dangerouslyAllowBrowser?: boolean;
+}
+type Method = 'get' | 'post' | 'patch' | 'delete';
+export interface APIRequestInit {
+    query?: object;
+    body?: unknown;
+    /**
+     * Safe to send twice: retried on timeouts and server errors as well as on
+     * 429. True for every GET; set it for a POST whose body carries an
+     * idempotency key.
+     */
+    idempotent?: boolean;
+    options?: RequestOptions;
+}
+export declare class Afriex {
+    #private;
+    readonly customers: Customers;
+    readonly transactions: Transactions;
+    readonly paymentMethods: PaymentMethods;
+    readonly paymentBatches: PaymentBatches;
+    readonly balance: Balance;
+    readonly rates: Rates;
+    readonly checkout: Checkout;
+    readonly media: Media;
+    readonly smeRegistration: SmeRegistration;
+    readonly webhooks: Webhooks;
+    readonly baseURL: string;
+    readonly apiVersion: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    constructor(options?: ClientOptions);
+    /**
+     * Sends a request and returns the parsed JSON body. The resource methods
+     * call this; use it yourself only for an endpoint they don't cover yet.
+     */
+    request<T>(method: Method, path: string, init?: APIRequestInit): APIPromise<T>;
+    /** @internal Fetches one page of a list endpoint. */
+    getPage<Item>(path: string, query?: {
+        page?: number;
+        limit?: number;
+    } & object, options?: RequestOptions): PagePromise<Item>;
+    /** @internal Sends a request with the configured `fetch`, without the API key. For presigned upload URLs. */
+    fetchUnauthenticated(url: string, init: RequestInit): Promise<Response>;
+}
+export {};