@siyegs/pay-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iyegere Success Karboloo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# pay-kit
+
+> One typed SDK for African payment rails. Unified **Paystack** and **Flutterwave**: initialize a payment, verify it, and handle signature-verified webhooks - with the same API for both.
+
+[![CI](https://github.com/siyegs/pay-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/siyegs/pay-kit/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/badge/npm-%40siyegs%2Fpay--kit-cb3837)](https://www.npmjs.com/package/@siyegs/pay-kit)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![types](https://img.shields.io/badge/types-included-3178c6)](./src/types.ts)
+
+Most serious African products integrate **both** Paystack and Flutterwave - for coverage, redundancy, and better rates. But their APIs, webhook signatures, error shapes, and currency units all differ, so teams re-write the same fragile glue every time. `pay-kit` gives you **one typed interface** over both.
+
+## Why
+
+- **One API, two providers.** Swap `provider: "paystack"` for `"flutterwave"` - your code doesn't change.
+- **Subunits everywhere.** Amounts are always in the smallest unit (kobo/cents), Stripe-style, to kill float-rounding bugs. pay-kit converts per provider.
+- **Signature-verified webhooks.** Paystack HMAC-SHA512 and Flutterwave `verif-hash`, both normalized to the same event shape.
+- **Typed end to end.** Full TypeScript types, one `PayKitError` with a machine-readable `code`.
+- **Tiny + dependency-free.** Uses native `fetch` and `node:crypto`. ESM + CJS.
+
+## Install
+
+```bash
+bun add @siyegs/pay-kit
+# or: npm install @siyegs/pay-kit / pnpm add @siyegs/pay-kit
+```
+
+Runs on **Bun** and **Node >= 18** (both provide global `fetch` and `node:crypto`). Keep your secret key **server-side only**.
+
+## Quick start
+
+```ts
+import { createPayClient } from "@siyegs/pay-kit";
+
+const pay = createPayClient({
+  provider: "paystack", // or "flutterwave"
+  secretKey: process.env.PAYSTACK_SECRET_KEY!,
+});
+
+// 1. Start a payment (amount in subunits: 500000 = NGN 5,000.00)
+const { authorizationUrl, reference } = await pay.initialize({
+  amount: 500000,
+  email: "customer@example.com",
+  currency: "NGN",
+  metadata: { orderId: "order_123" },
+});
+// -> redirect the customer to `authorizationUrl`, persist `reference`
+
+// 2. Verify after the redirect / callback
+const result = await pay.verify(reference);
+if (result.status === "success") {
+  // fulfill the order
+}
+```
+
+## Webhooks
+
+Verify the raw request body against its signature header and get a normalized event. **Always verify before trusting a webhook.**
+
+```ts
+// Express example
+app.post("/webhooks/pay", express.raw({ type: "*/*" }), (req, res) => {
+  const signature =
+    req.header("x-paystack-signature") ?? req.header("verif-hash") ?? "";
+  try {
+    const event = pay.webhooks.construct(req.body.toString("utf8"), signature);
+    if (event.type === "charge.success") {
+      // event.reference, event.amount (subunits), event.currency
+    }
+    res.sendStatus(200);
+  } catch {
+    res.sendStatus(400); // invalid signature -> reject
+  }
+});
+```
+
+- **Paystack**: signature header is `x-paystack-signature`; verification uses your `secretKey`.
+- **Flutterwave**: header is `verif-hash`; pass your "Secret hash" as `webhookSecret` when creating the client.
+
+## Provider fallback
+
+Try one provider, automatically fall through to the next when it is unreachable - so a Paystack outage doesn't stop you taking money.
+
+```ts
+import { createFallbackClient } from "@siyegs/pay-kit";
+
+const pay = createFallbackClient({
+  providers: [
+    { provider: "paystack", secretKey: process.env.PAYSTACK_SECRET_KEY! },
+    { provider: "flutterwave", secretKey: process.env.FLW_SECRET_KEY!, webhookSecret: process.env.FLW_HASH },
+  ],
+});
+
+// initialize tries Paystack, then Flutterwave on an outage
+const { reference, provider } = await pay.initialize({ amount: 500000, email: "a@b.com" });
+
+// persist BOTH reference and provider, then route the rest to that provider
+const result = await pay.verify(provider, reference);
+await pay.refund(provider, reference);
+const event = pay.webhooks.construct(provider, rawBody, signature);
+```
+
+- Only **outage-like** failures trigger fallback: network errors, HTTP 5xx, and 429. A 4xx (bad request, invalid key) fails fast - it would fail the same way on the next provider.
+- A charge started on one provider can only be verified/refunded on that provider, so `initialize` returns which `provider` handled it. **Persist `provider` alongside `reference`.**
+- Fallback is safest for *pre-charge* outages (provider unreachable). If a provider accepts the charge then the connection drops, retrying the other provider could double-charge - use idempotency at your order layer for that edge.
+
+## API
+
+### `createPayClient(config)`
+
+| option             | type                          | notes                                              |
+| ------------------ | ----------------------------- | -------------------------------------------------- |
+| `provider`         | `"paystack" \| "flutterwave"` | required                                           |
+| `secretKey`        | `string`                      | required, server-side only                         |
+| `webhookSecret`    | `string`                      | required for Flutterwave webhooks (Secret hash)    |
+| `baseUrl`          | `string`                      | override API base (tests/proxies)                  |
+| `fetch`            | `typeof fetch`                | inject a fetch impl                                |
+| `generateReference`| `() => string`                | customize reference generation                     |
+
+### Methods
+
+- `initialize(params) -> { reference, authorizationUrl, accessCode?, raw }`
+- `verify(reference) -> { reference, status, amount, currency, paidAt?, channel?, customer?, raw }`
+- `refund(reference, options?) -> { reference, status, amount?, raw }` - full refund, or partial with `options.amount` (subunits)
+- `webhooks.construct(rawBody, signature) -> { type, reference, status?, amount?, currency?, raw }`
+
+`status` is normalized to `"success" | "failed" | "pending" | "abandoned"`. Errors are thrown as `PayKitError` with `code` in `provider_error | network_error | invalid_signature | config_error | verification_failed`.
+
+## Roadmap
+
+- [x] Refunds (full & partial)
+- [x] **Provider fallback** (auto-retry the other provider on outage)
+- [ ] Transfers / payouts
+- [ ] Plans & subscriptions
+- [ ] Framework adapters (NestJS, Hono, Next.js route handlers)
+- [ ] Mock provider for offline development
+
+## Development
+
+Built with the [Bun](https://bun.sh) toolchain.
+
+```bash
+bun install          # install deps
+bun test             # run the test suite (bun:test)
+bun run typecheck    # tsc --noEmit
+bun run build        # tsup -> dist (ESM + CJS + .d.ts)
+```
+
+## License
+
+MIT (c) Iyegere Success Karboloo

package/dist/index.cjs

@@ -0,0 +1,487 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PayKitError: () => PayKitError,
+  createFallbackClient: () => createFallbackClient,
+  createPayClient: () => createPayClient,
+  isRetryableError: () => isRetryableError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_node_crypto3 = require("crypto");
+
+// src/errors.ts
+function isRetryableError(err) {
+  if (!(err instanceof PayKitError)) return false;
+  if (err.code === "network_error") return true;
+  if (typeof err.statusCode === "number") {
+    return err.statusCode >= 500 || err.statusCode === 429;
+  }
+  return false;
+}
+var PayKitError = class extends Error {
+  code;
+  provider;
+  statusCode;
+  raw;
+  constructor(message, options) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = "PayKitError";
+    this.code = options.code;
+    this.provider = options.provider;
+    this.statusCode = options.statusCode;
+    this.raw = options.raw;
+  }
+};
+
+// src/providers/paystack.ts
+var import_node_crypto2 = require("crypto");
+
+// src/internal.ts
+var import_node_crypto = require("crypto");
+async function providerRequest(ctx, provider, url, init) {
+  let res;
+  try {
+    res = await ctx.fetch(url, {
+      ...init,
+      headers: {
+        Authorization: `Bearer ${ctx.secretKey}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...init.headers ?? {}
+      }
+    });
+  } catch (err) {
+    throw new PayKitError(`Network error calling ${provider}`, {
+      code: "network_error",
+      provider,
+      cause: err
+    });
+  }
+  let body = {};
+  try {
+    body = await res.json();
+  } catch {
+    body = {};
+  }
+  if (!res.ok || body.status === false || body.status === "error") {
+    const message = typeof body.message === "string" ? body.message : `${provider} request failed (${res.status})`;
+    throw new PayKitError(message, {
+      code: "provider_error",
+      provider,
+      statusCode: res.status,
+      raw: body
+    });
+  }
+  return body;
+}
+function safeEqual(a, b) {
+  const ba = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ba.length !== bb.length) return false;
+  return (0, import_node_crypto.timingSafeEqual)(ba, bb);
+}
+
+// src/providers/paystack.ts
+var PAYSTACK_BASE = "https://api.paystack.co";
+function mapStatus(raw) {
+  switch (raw) {
+    case "success":
+      return "success";
+    case "failed":
+      return "failed";
+    case "abandoned":
+      return "abandoned";
+    default:
+      return "pending";
+  }
+}
+function mapEventType(event) {
+  return typeof event === "string" && event.length > 0 ? event : "unknown";
+}
+function mapRefundStatus(raw) {
+  switch (raw) {
+    case "processed":
+    case "success":
+      return "processed";
+    case "failed":
+      return "failed";
+    default:
+      return "pending";
+  }
+}
+function createPaystackProvider(ctx) {
+  const base = ctx.baseUrl ?? PAYSTACK_BASE;
+  return {
+    name: "paystack",
+    async initialize(params) {
+      const reference = params.reference ?? ctx.generateReference();
+      const body = await providerRequest(ctx, "paystack", `${base}/transaction/initialize`, {
+        method: "POST",
+        body: JSON.stringify({
+          amount: params.amount,
+          email: params.email,
+          currency: params.currency ?? "NGN",
+          reference,
+          callback_url: params.callbackUrl,
+          metadata: params.metadata
+        })
+      });
+      const data = body.data ?? {};
+      return {
+        reference: String(data.reference ?? reference),
+        authorizationUrl: String(data.authorization_url ?? ""),
+        accessCode: data.access_code ? String(data.access_code) : void 0,
+        raw: body
+      };
+    },
+    async verify(reference) {
+      const body = await providerRequest(
+        ctx,
+        "paystack",
+        `${base}/transaction/verify/${encodeURIComponent(reference)}`,
+        { method: "GET" }
+      );
+      const data = body.data ?? {};
+      const customer = data.customer ?? {};
+      return {
+        reference: String(data.reference ?? reference),
+        status: mapStatus(data.status),
+        amount: Number(data.amount ?? 0),
+        currency: String(data.currency ?? ""),
+        paidAt: data.paid_at ? String(data.paid_at) : void 0,
+        channel: data.channel ? String(data.channel) : void 0,
+        customer: { email: customer.email ? String(customer.email) : void 0 },
+        raw: body
+      };
+    },
+    async refund(reference, options) {
+      const body = await providerRequest(ctx, "paystack", `${base}/refund`, {
+        method: "POST",
+        body: JSON.stringify({
+          transaction: reference,
+          ...options?.amount !== void 0 ? { amount: options.amount } : {}
+        })
+      });
+      const data = body.data ?? {};
+      const transaction = data.transaction ?? {};
+      return {
+        reference: String(transaction.reference ?? reference),
+        status: mapRefundStatus(data.status),
+        amount: data.amount !== void 0 ? Number(data.amount) : void 0,
+        raw: body
+      };
+    },
+    constructWebhookEvent(rawBody, signature) {
+      const expected = (0, import_node_crypto2.createHmac)("sha512", ctx.secretKey).update(rawBody).digest("hex");
+      if (!signature || !safeEqual(expected, signature)) {
+        throw new PayKitError("Invalid Paystack webhook signature", {
+          code: "invalid_signature",
+          provider: "paystack"
+        });
+      }
+      let event;
+      try {
+        event = JSON.parse(rawBody);
+      } catch (err) {
+        throw new PayKitError("Malformed Paystack webhook body", {
+          code: "provider_error",
+          provider: "paystack",
+          cause: err
+        });
+      }
+      const data = event.data ?? {};
+      return {
+        type: mapEventType(event.event),
+        reference: String(data.reference ?? ""),
+        status: data.status ? mapStatus(data.status) : void 0,
+        amount: data.amount !== void 0 ? Number(data.amount) : void 0,
+        currency: data.currency ? String(data.currency) : void 0,
+        raw: event
+      };
+    }
+  };
+}
+
+// src/providers/flutterwave.ts
+var FLUTTERWAVE_BASE = "https://api.flutterwave.com";
+function toMajor(subunits) {
+  return subunits / 100;
+}
+function toSubunits(major) {
+  return Math.round(Number(major ?? 0) * 100);
+}
+function mapStatus2(raw) {
+  switch (raw) {
+    case "successful":
+    case "success":
+      return "success";
+    case "failed":
+      return "failed";
+    default:
+      return "pending";
+  }
+}
+function mapEventType2(status) {
+  if (status === "success") return "charge.success";
+  if (status === "failed") return "charge.failed";
+  return "unknown";
+}
+function mapRefundStatus2(raw) {
+  switch (raw) {
+    case "completed":
+    case "successful":
+    case "success":
+    case "processed":
+      return "processed";
+    case "failed":
+      return "failed";
+    default:
+      return "pending";
+  }
+}
+function createFlutterwaveProvider(ctx) {
+  const base = ctx.baseUrl ?? FLUTTERWAVE_BASE;
+  return {
+    name: "flutterwave",
+    async initialize(params) {
+      const reference = params.reference ?? ctx.generateReference();
+      const body = await providerRequest(ctx, "flutterwave", `${base}/v3/payments`, {
+        method: "POST",
+        body: JSON.stringify({
+          tx_ref: reference,
+          amount: toMajor(params.amount),
+          currency: params.currency ?? "NGN",
+          redirect_url: params.callbackUrl,
+          customer: { email: params.email },
+          meta: params.metadata
+        })
+      });
+      const data = body.data ?? {};
+      return {
+        reference,
+        authorizationUrl: String(data.link ?? ""),
+        raw: body
+      };
+    },
+    async verify(reference) {
+      const body = await providerRequest(
+        ctx,
+        "flutterwave",
+        `${base}/v3/transactions/verify_by_reference?tx_ref=${encodeURIComponent(reference)}`,
+        { method: "GET" }
+      );
+      const data = body.data ?? {};
+      const customer = data.customer ?? {};
+      return {
+        reference: String(data.tx_ref ?? reference),
+        status: mapStatus2(data.status),
+        amount: toSubunits(data.amount),
+        currency: String(data.currency ?? ""),
+        paidAt: data.created_at ? String(data.created_at) : void 0,
+        channel: data.payment_type ? String(data.payment_type) : void 0,
+        customer: { email: customer.email ? String(customer.email) : void 0 },
+        raw: body
+      };
+    },
+    async refund(reference, options) {
+      const verifyBody = await providerRequest(
+        ctx,
+        "flutterwave",
+        `${base}/v3/transactions/verify_by_reference?tx_ref=${encodeURIComponent(reference)}`,
+        { method: "GET" }
+      );
+      const verifyData = verifyBody.data ?? {};
+      const id = verifyData.id;
+      if (id === void 0 || id === null) {
+        throw new PayKitError(
+          `No Flutterwave transaction found for reference "${reference}"`,
+          { code: "provider_error", provider: "flutterwave", raw: verifyBody }
+        );
+      }
+      const body = await providerRequest(
+        ctx,
+        "flutterwave",
+        `${base}/v3/transactions/${encodeURIComponent(String(id))}/refund`,
+        {
+          method: "POST",
+          body: JSON.stringify(
+            options?.amount !== void 0 ? { amount: toMajor(options.amount) } : {}
+          )
+        }
+      );
+      const data = body.data ?? {};
+      const refunded = data.amount_refunded ?? data.amount;
+      return {
+        reference,
+        status: mapRefundStatus2(data.status),
+        amount: refunded !== void 0 ? toSubunits(refunded) : void 0,
+        raw: body
+      };
+    },
+    constructWebhookEvent(rawBody, signature) {
+      if (!ctx.webhookSecret) {
+        throw new PayKitError(
+          "Flutterwave webhook verification requires `webhookSecret` (your Secret hash)",
+          { code: "config_error", provider: "flutterwave" }
+        );
+      }
+      if (!signature || !safeEqual(ctx.webhookSecret, signature)) {
+        throw new PayKitError("Invalid Flutterwave webhook signature", {
+          code: "invalid_signature",
+          provider: "flutterwave"
+        });
+      }
+      let event;
+      try {
+        event = JSON.parse(rawBody);
+      } catch (err) {
+        throw new PayKitError("Malformed Flutterwave webhook body", {
+          code: "provider_error",
+          provider: "flutterwave",
+          cause: err
+        });
+      }
+      const data = event.data ?? {};
+      const status = mapStatus2(data.status);
+      return {
+        type: mapEventType2(status),
+        reference: String(data.tx_ref ?? ""),
+        status,
+        amount: data.amount !== void 0 ? toSubunits(data.amount) : void 0,
+        currency: data.currency ? String(data.currency) : void 0,
+        raw: event
+      };
+    }
+  };
+}
+
+// src/client.ts
+function resolveProvider(config, ctx) {
+  switch (config.provider) {
+    case "paystack":
+      return createPaystackProvider(ctx);
+    case "flutterwave":
+      return createFlutterwaveProvider(ctx);
+    default:
+      throw new PayKitError(`Unknown provider: ${String(config.provider)}`, {
+        code: "config_error"
+      });
+  }
+}
+function createPayClient(config) {
+  if (!config.secretKey) {
+    throw new PayKitError("`secretKey` is required", { code: "config_error" });
+  }
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new PayKitError(
+      "No fetch implementation found. Use Node >= 18 or pass `config.fetch`.",
+      { code: "config_error" }
+    );
+  }
+  const ctx = {
+    secretKey: config.secretKey,
+    webhookSecret: config.webhookSecret,
+    baseUrl: config.baseUrl,
+    fetch: fetchImpl,
+    generateReference: config.generateReference ?? (() => `pk_${(0, import_node_crypto3.randomUUID)().replace(/-/g, "")}`)
+  };
+  const provider = resolveProvider(config, ctx);
+  return {
+    provider: provider.name,
+    initialize: (params) => provider.initialize(params),
+    verify: (reference) => provider.verify(reference),
+    refund: (reference, options) => provider.refund(reference, options),
+    webhooks: {
+      construct: (rawBody, signature) => provider.constructWebhookEvent(rawBody, signature)
+    }
+  };
+}
+
+// src/fallback.ts
+function createFallbackClient(config) {
+  if (!config.providers || config.providers.length === 0) {
+    throw new PayKitError("createFallbackClient requires at least one provider", {
+      code: "config_error"
+    });
+  }
+  const clients = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const entry of config.providers) {
+    if (clients.has(entry.provider)) continue;
+    clients.set(
+      entry.provider,
+      createPayClient({
+        provider: entry.provider,
+        secretKey: entry.secretKey,
+        webhookSecret: entry.webhookSecret,
+        baseUrl: entry.baseUrl,
+        fetch: config.fetch,
+        generateReference: config.generateReference
+      })
+    );
+    order.push(entry.provider);
+  }
+  function getClient(provider) {
+    const client = clients.get(provider);
+    if (!client) {
+      throw new PayKitError(
+        `Provider "${provider}" is not configured on this fallback client`,
+        { code: "config_error" }
+      );
+    }
+    return client;
+  }
+  return {
+    async initialize(params) {
+      let lastError;
+      for (const provider of order) {
+        try {
+          const result = await getClient(provider).initialize(params);
+          return { ...result, provider };
+        } catch (err) {
+          lastError = err;
+          if (!isRetryableError(err)) throw err;
+        }
+      }
+      throw lastError ?? new PayKitError("All providers failed to initialize the payment", {
+        code: "provider_error"
+      });
+    },
+    verify: (provider, reference) => getClient(provider).verify(reference),
+    refund: (provider, reference, options) => getClient(provider).refund(reference, options),
+    webhooks: {
+      construct: (provider, rawBody, signature) => getClient(provider).webhooks.construct(rawBody, signature)
+    },
+    client: getClient
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PayKitError,
+  createFallbackClient,
+  createPayClient,
+  isRetryableError
+});
+//# sourceMappingURL=index.cjs.map