@afriex/sdk 5.0.0 → 6.0.0

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

@@ -1,386 +0,0 @@
----
-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: '4.1.0'
-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`.
-
-### Check: writes are not retried blindly
-
-Expected: `retryConfig.retryableMethods` is absent, or lists neither `POST`
-nor `PATCH`.
-
-With the default methods, the SDK retries reads and sends every `POST` and
-`PATCH` once. A write that fails with a 5xx or a timeout may still have been
-applied, so the application reads the state back (for a transaction,
-`transactions.list({ reference })`) before it sends the write again, and
-reuses the same `meta.idempotencyKey` when it does.
-
-Fail condition: `retryableMethods` includes `POST` on a client that calls
-`paymentBatches.withdraw` — a repeat starts a second run and pays every
-recipient again.
-Fix: remove `POST` from `retryableMethods` and retry writes in application
-code, where the state can be checked first.
-
-### 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: `balance.topUpSandbox`, `webhooks.triggerTestWebhook`,
-`transactions.simulate` or `paymentMethods.simulateTransfer` reachable on a
-production code path — all four answer `403 FORBIDDEN` there.
-Fix: guard them behind an environment check or keep them in test-only modules.
-
-### Check: no sandbox test value reaches production
-
-Expected:
-
-```ts
-const SANDBOX_OUTCOME_SUFFIXES = ["0001", "0002", "0003", "0004", "0005"];
-
-export function assertRealAccount(accountNumber: string): void {
-  if (process.env.NODE_ENV !== "production") {
-    return;
-  }
-  if (SANDBOX_OUTCOME_SUFFIXES.some((suffix) => accountNumber.endsWith(suffix))) {
-    console.warn("account number matches a sandbox test value", accountNumber);
-  }
-}
-```
-
-In the sandbox, an account number, phone number or card number ending in
-`0001` to `0005` chooses the outcome of a transaction, the OTP is always
-`123456`, and `SIMULATE_INSTANT` in `meta.reference` completes a transaction
-early. None of this applies in production, where those are ordinary values.
-
-Fail condition: a fixture account, the OTP `123456` or a `SIMULATE_INSTANT`
-reference hard-coded on a path that runs in production.
-Fix: keep test values in fixtures that only the test environment loads.
-
-## Webhook Checks
-
-### Check: the firewall admits Afriex's webhook addresses
-
-Expected: inbound traffic to the webhook endpoint is allowed from
-`34.197.33.100` in production and `34.234.189.210` in the sandbox.
-
-Fail condition: a firewall or allowlist in front of the endpoint that does not
-include the address for the environment — deliveries are dropped before they
-reach the handler, and nothing is logged on the application side.
-Fix: add the address to the allowlist. The address is not a substitute for
-verifying the signature.
-
-### 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
-- [ ] `retryableMethods` does not include `POST` or `PATCH`
-- [ ] Afriex's webhook IP address is allowed through the firewall
-- [ ] `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`, `triggerTestWebhook`, `simulate` and `simulateTransfer` are unreachable in production
-- [ ] No sandbox test account, OTP or `SIMULATE_INSTANT` reference on a production path
-- [ ] 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

@@ -1,275 +0,0 @@
----
-name: afriex-sdk
-description: >
-  Entry point for the Afriex Business API TypeScript SDK (@afriex/sdk) — the
-  AfriexSDK / Afriex facade and its customers, transactions, paymentMethods,
-  paymentBatches, balance, rates, checkout, media, smeRegistration, 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: '4.1.0'
-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`             |
-| Pay many recipients in one call                   | `afriex.paymentBatches`    | `afriex-payment-batches`          |
-| 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`                 |
-| Upload an invoice, a proof or a document          | `afriex.media`             | `afriex-media`                    |
-| Register for dedicated KES virtual accounts       | `afriex.smeRegistration`   | `afriex-sme-registration`         |
-| 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 { data: 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: {
-    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.