sebpay-node 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# sebpay-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official Node.js SDK for [Sebpay](https://sebpay.africa) **hosted checkout**. It does four things:
+- create a checkout session;
+- redirect your customer to the Sebpay payment page;
+- confirm the payment when they come back;
+- verify Sebpay's webhooks.
+
+**Server-side only.** This SDK runs in Node.js (≥ 18). Never bundle it into a browser build: your secret key must never reach the client.
+
+It uses Node's native `fetch` and has no runtime dependency. Direct collections, payouts and reference data are not part of the SDK. They remain available over plain HTTP: see [`docs/SEBPAY_PUBLIC_API.md`](../../docs/SEBPAY_PUBLIC_API.md).
+
+## Install
+
+```bash
+npm install sebpay-node
+```
+
+Requires Node.js 18 or later. The package ships its TypeScript types.
+
+## Usage
+
+### 1. Create a session and redirect your customer
+
+```ts
+import { SebpayClient } from "sebpay-node";
+
+// Keys from your dashboard (API développeur): pk_test_ keys go to the sandbox server, pk_live_ keys to live.
+const sebpay = new SebpayClient(process.env.SEBPAY_PUBLIC_KEY!, process.env.SEBPAY_SECRET_KEY!);
+
+const session = await sebpay.checkoutSessions.create({
+  amount: 5000,
+  currency: "XOF",
+  redirect_url: "https://yoursite.com/orders/return",
+  external_reference: order.id, // your order id: sending it again returns the same session
+  callback_url: "https://yoursite.com/webhook/sebpay",
+  metadata: { order_id: order.id },
+});
+
+res.redirect(session.checkout_url);
+```
+
+### 2. Confirm the payment when your customer comes back
+
+Your `redirect_url` receives `?checkout_session_id=<id>`. Coming back proves nothing, so ask Sebpay before you deliver:
+
+```ts
+const session = await sebpay.checkoutSessions.retrieve(req.query.checkout_session_id);
+
+if (session.transaction_status === "approved") {
+  // Paid: deliver the order (session.external_reference, session.metadata).
+}
+```
+
+`retrieve()` also accepts your `external_reference`.
+
+### 3. Verify the webhook
+
+Sebpay POSTs the final status (`approved` or `rejected`) to your `callback_url`. For a checkout, the request also carries `checkout_session_id` and your `metadata`.
+
+```ts
+import express from "express";
+import { SIGNATURE_HEADER, verifySignature, type WebhookPayload } from "sebpay-node";
+
+app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));
+
+app.post("/webhook/sebpay", (req, res) => {
+  if (!verifySignature(req.rawBody, req.get(SIGNATURE_HEADER), process.env.SEBPAY_SECRET_KEY!)) {
+    return res.status(401).json({ error: "Invalid signature" });
+  }
+
+  const payload = req.body as WebhookPayload;
+  // payload.status: "approved" | "rejected"
+  res.status(200).json({ received: true });
+});
+```
+
+- Always pass the **raw** request body. Re-serializing a parsed payload can reorder keys and break the signature.
+- A missing header returns `false`; it never throws.
+
+## Options
+
+```ts
+new SebpayClient(publicKey, secretKey, {
+  baseUrl: "http://localhost:8000/api/v1", // only to test against a local API; otherwise chosen from the keys
+  timeout: 10_000,                         // ms, default 30 000
+});
+```
+
+`sebpay.baseUrl` tells which server the client talks to.
+
+## Errors
+
+Every failed call throws a `SebpayApiError`, with three fields:
+- `status`: the HTTP status, or 0 when no response came back;
+- `code`: the API's `errors.code`, or one of the SDK's own codes. Examples: `EXTERNAL_REFERENCE_CONFLICT`, `RATE_LIMITED`, `WRONG_ENVIRONMENT`, `NETWORK_ERROR`, `TIMEOUT`, `INVALID_RESPONSE`. It is `null` otherwise;
+- `body`: the decoded response.
+
+```ts
+import { SebpayApiError } from "sebpay-node";
+
+try {
+  await sebpay.checkoutSessions.create({ ... });
+} catch (err) {
+  if (err instanceof SebpayApiError && err.code === "EXTERNAL_REFERENCE_CONFLICT") {
+    // This order id was already used with other parameters.
+  }
+}
+```
+
+## Examples
+
+See [`examples/`](examples/). Build first (`npm run build`), set `SEBPAY_PUBLIC_KEY` and `SEBPAY_SECRET_KEY`, then:
+- `node examples/create-checkout.mjs` creates a session and prints its `checkout_url`;
+- `node examples/webhook-server.mjs` starts an Express server (`npm install express`) that handles the webhook and the return page, on `PORT` (default 3001).
+
+For local testing, also set `SEBPAY_BASE_URL`.
+
+## Tests
+
+`npm test` builds the SDK and runs its offline tests with `node --test`. They cover the transport, against a local HTTP server, and the shared signature vectors.
+
+## Requirements
+
+Node.js 18+ (for native `fetch` and `node:crypto`).

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import { CheckoutSessions } from "./resources/checkoutSessions";
+export interface SebpayClientOptions {
+    /** API URL. By default it follows the keys: pk_test_ → sandbox server, otherwise live. */
+    baseUrl?: string;
+    /** Request timeout, in milliseconds (default 30 000). */
+    timeout?: number;
+}
+/** How a resource reaches the API — kept internal, so the SDK only calls the endpoints it wraps. */
+export type Requester = <T>(method: "GET" | "POST", path: string, body?: Record<string, unknown>) => Promise<T>;
+/**
+ * Entry point for Sebpay hosted checkout. Server-side only — the secret key must never reach a
+ * browser bundle. Pass the key pair from your dashboard (API développeur): the sandbox and live
+ * are separate servers, and pk_test_ keys are sent to the sandbox, pk_live_ keys to live.
+ */
+export declare class SebpayClient {
+    #private;
+    readonly baseUrl: string;
+    readonly checkoutSessions: CheckoutSessions;
+    constructor(publicKey: string, secretKey: string, options?: SebpayClientOptions);
+}

package/dist/client.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SebpayClient = void 0;
+const errors_1 = require("./errors");
+const checkoutSessions_1 = require("./resources/checkoutSessions");
+const version_1 = require("./version");
+const LIVE_BASE_URL = "https://newapi.sebpay.africa/api/v1";
+const SANDBOX_BASE_URL = "https://api.sandbox.sebpay.bj/api/v1";
+// Same 30 s default as the PHP and Python SDKs — fetch has no timeout of its own.
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Entry point for Sebpay hosted checkout. Server-side only — the secret key must never reach a
+ * browser bundle. Pass the key pair from your dashboard (API développeur): the sandbox and live
+ * are separate servers, and pk_test_ keys are sent to the sandbox, pk_live_ keys to live.
+ */
+class SebpayClient {
+    baseUrl;
+    checkoutSessions;
+    #publicKey;
+    #secretKey;
+    #timeout;
+    constructor(publicKey, secretKey, options = {}) {
+        this.#publicKey = publicKey;
+        this.#secretKey = secretKey;
+        this.#timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.baseUrl = (options.baseUrl ?? (publicKey.startsWith("pk_test_") ? SANDBOX_BASE_URL : LIVE_BASE_URL)).replace(/\/+$/, "");
+        this.checkoutSessions = new checkoutSessions_1.CheckoutSessions((method, path, body) => this.#request(method, path, body));
+    }
+    /** Returns the `data` field of a successful response; throws SebpayApiError otherwise. */
+    async #request(method, path, body) {
+        const headers = {
+            "X-Public-Key": this.#publicKey,
+            "X-Secret-Key": this.#secretKey,
+            Accept: "application/json",
+            "User-Agent": `sebpay-node/${version_1.VERSION}`,
+        };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let res;
+        let text;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(this.#timeout),
+            });
+            text = await res.text();
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "TimeoutError") {
+                throw new errors_1.SebpayApiError(`Sebpay request timed out after ${this.#timeout} ms`, 0, "TIMEOUT", null);
+            }
+            const cause = err instanceof Error ? (err.cause?.message ?? err.message) : String(err);
+            throw new errors_1.SebpayApiError(`Sebpay request failed: ${cause}`, 0, "NETWORK_ERROR", null);
+        }
+        let decoded = null;
+        try {
+            decoded = JSON.parse(text);
+        }
+        catch {
+            // not JSON: handled below
+        }
+        if (!res.ok || decoded?.success === false) {
+            const code = typeof decoded?.errors?.code === "string" ? decoded.errors.code : null;
+            throw new errors_1.SebpayApiError(decoded?.message ?? `Sebpay API error (HTTP ${res.status})`, res.status, code, decoded ?? text);
+        }
+        if (decoded === null || typeof decoded !== "object" || !("data" in decoded)) {
+            throw new errors_1.SebpayApiError("Sebpay API returned an unexpected response", res.status, "INVALID_RESPONSE", decoded ?? text);
+        }
+        return decoded.data;
+    }
+}
+exports.SebpayClient = SebpayClient;

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Thrown for every failed call. `status` is the HTTP status, or 0 when no response came back
+ * (`code` "NETWORK_ERROR" or "TIMEOUT"). `code` is the API's `errors.code` when it sends one
+ * (e.g. "EXTERNAL_REFERENCE_CONFLICT", "RATE_LIMITED", "WRONG_ENVIRONMENT"), else null.
+ * `body` is the decoded response.
+ */
+export declare class SebpayApiError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly body: unknown;
+    constructor(message: string, status: number, code: string | null, body: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SebpayApiError = void 0;
+/**
+ * Thrown for every failed call. `status` is the HTTP status, or 0 when no response came back
+ * (`code` "NETWORK_ERROR" or "TIMEOUT"). `code` is the API's `errors.code` when it sends one
+ * (e.g. "EXTERNAL_REFERENCE_CONFLICT", "RATE_LIMITED", "WRONG_ENVIRONMENT"), else null.
+ * `body` is the decoded response.
+ */
+class SebpayApiError extends Error {
+    status;
+    code;
+    body;
+    constructor(message, status, code, body) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.body = body;
+        this.name = "SebpayApiError";
+    }
+}
+exports.SebpayApiError = SebpayApiError;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { SebpayClient } from "./client";
+export type { SebpayClientOptions } from "./client";
+export { SebpayApiError } from "./errors";
+export { SIGNATURE_HEADER, verifySignature } from "./webhooks";
+export type { WebhookPayload } from "./webhooks";
+export { VERSION } from "./version";
+export type { CreateCheckoutSessionParams, CheckoutSession, CheckoutSessionDetails, CheckoutSessionStatus, } from "./resources/checkoutSessions";

package/dist/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.verifySignature = exports.SIGNATURE_HEADER = exports.SebpayApiError = exports.SebpayClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "SebpayClient", { enumerable: true, get: function () { return client_1.SebpayClient; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "SebpayApiError", { enumerable: true, get: function () { return errors_1.SebpayApiError; } });
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "SIGNATURE_HEADER", { enumerable: true, get: function () { return webhooks_1.SIGNATURE_HEADER; } });
+Object.defineProperty(exports, "verifySignature", { enumerable: true, get: function () { return webhooks_1.verifySignature; } });
+var version_1 = require("./version");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_1.VERSION; } });

package/dist/resources/checkoutSessions.d.ts

@@ -0,0 +1,50 @@
+import type { Requester } from "../client";
+export interface CreateCheckoutSessionParams {
+    amount: number;
+    /** ISO code, e.g. "XOF". */
+    currency: string;
+    /** Where your customer lands after paying, with `?checkout_session_id=<id>` appended. */
+    redirect_url: string;
+    /** Your order id. Sending it again with the same parameters returns the same session (`idempotent_replay`). */
+    external_reference?: string;
+    /** Receives the signed webhook when the payment is approved or rejected (https). */
+    callback_url?: string;
+    customer_name?: string;
+    customer_email?: string;
+    customer_phone?: string;
+    /** Echoed back on the session and in its webhook. */
+    metadata?: Record<string, unknown>;
+}
+export type CheckoutSessionStatus = "open" | "completed" | "expired" | "canceled";
+export interface CheckoutSession {
+    id: string;
+    status: CheckoutSessionStatus;
+    /** The Sebpay-hosted page to redirect your customer to. */
+    checkout_url: string;
+    amount: number;
+    currency: string;
+    external_reference: string | null;
+    metadata: Record<string, unknown> | null;
+    expires_at: string;
+    /** Present (true) when this external_reference had already created the session: it is returned as is. */
+    idempotent_replay?: true;
+}
+export interface CheckoutSessionDetails extends Omit<CheckoutSession, "idempotent_replay"> {
+    /** The latest payment attempt, if any. */
+    transaction_id: string | null;
+    /** "approved" is the only status that means paid. */
+    transaction_status: "pending" | "approved" | "rejected" | null;
+    created_at: string;
+}
+export declare class CheckoutSessions {
+    private readonly request;
+    constructor(request: Requester);
+    /** Create a hosted checkout session and get back a `checkout_url` to redirect your customer to. */
+    create(params: CreateCheckoutSessionParams): Promise<CheckoutSession>;
+    /**
+     * Retrieve a session by its id (the `checkout_session_id` of your redirect_url), its token or your
+     * external_reference. This is the server-to-server confirmation: when your customer comes back,
+     * deliver only if `transaction_status` is "approved" — the redirect alone proves nothing.
+     */
+    retrieve(idOrReference: string): Promise<CheckoutSessionDetails>;
+}

package/dist/resources/checkoutSessions.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckoutSessions = void 0;
+class CheckoutSessions {
+    request;
+    constructor(request) {
+        this.request = request;
+    }
+    /** Create a hosted checkout session and get back a `checkout_url` to redirect your customer to. */
+    create(params) {
+        return this.request("POST", "/checkout/sessions", { ...params });
+    }
+    /**
+     * Retrieve a session by its id (the `checkout_session_id` of your redirect_url), its token or your
+     * external_reference. This is the server-to-server confirmation: when your customer comes back,
+     * deliver only if `transaction_status` is "approved" — the redirect alone proves nothing.
+     */
+    retrieve(idOrReference) {
+        return this.request("GET", `/checkout/sessions/${encodeURIComponent(idOrReference)}`);
+    }
+}
+exports.CheckoutSessions = CheckoutSessions;

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** SDK version, sent in the User-Agent header. Keep in sync with package.json (checked by the tests). */
+export declare const VERSION = "0.2.0";

package/dist/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/** SDK version, sent in the User-Agent header. Keep in sync with package.json (checked by the tests). */
+exports.VERSION = "0.2.0";

package/dist/webhooks.d.ts

@@ -0,0 +1,24 @@
+/** The header carrying the signature of every Sebpay webhook. */
+export declare const SIGNATURE_HEADER = "X-SebPay-Signature";
+/** The body Sebpay POSTs to your callback_url once a payment is final. */
+export interface WebhookPayload {
+    transaction_id: string;
+    external_reference: string | null;
+    /** Only final statuses are sent. */
+    status: "approved" | "rejected";
+    amount: number;
+    currency: string;
+    customer_phone: string | null;
+    created_at: string;
+    updated_at: string;
+    /** The checkout session this payment belongs to. */
+    checkout_session_id?: string;
+    /** The metadata you attached to that session. */
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * Verifies the `X-SebPay-Signature` header Sebpay sends with every webhook callback. Always pass
+ * the raw request body — re-serializing a parsed payload (e.g. via JSON.stringify after parsing)
+ * can reorder keys and break the signature. A missing signature or body returns false.
+ */
+export declare function verifySignature(rawBody: string | Uint8Array | null | undefined, signature: string | string[] | null | undefined, secretKey: string): boolean;

package/dist/webhooks.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGNATURE_HEADER = void 0;
+exports.verifySignature = verifySignature;
+const node_crypto_1 = require("node:crypto");
+/** The header carrying the signature of every Sebpay webhook. */
+exports.SIGNATURE_HEADER = "X-SebPay-Signature";
+/**
+ * Verifies the `X-SebPay-Signature` header Sebpay sends with every webhook callback. Always pass
+ * the raw request body — re-serializing a parsed payload (e.g. via JSON.stringify after parsing)
+ * can reorder keys and break the signature. A missing signature or body returns false.
+ */
+function verifySignature(rawBody, signature, secretKey) {
+    if (typeof signature !== "string" || signature === "")
+        return false;
+    if (typeof rawBody !== "string" && !(rawBody instanceof Uint8Array))
+        return false;
+    const expected = (0, node_crypto_1.createHmac)("sha256", secretKey).update(rawBody).digest("hex");
+    const expectedBuf = Buffer.from(expected, "utf8");
+    const signatureBuf = Buffer.from(signature, "utf8");
+    if (expectedBuf.length !== signatureBuf.length) {
+        return false;
+    }
+    return (0, node_crypto_1.timingSafeEqual)(expectedBuf, signatureBuf);
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "sebpay-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Official Node.js SDK for Sebpay hosted checkout — create a checkout session, redirect your customer, confirm the payment and verify webhooks. Server-side only.",
+  "license": "MIT",
+  "author": "Sebpay",
+  "homepage": "https://sebpay.africa",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mjims/sebpay-sdk-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mjims/sebpay-sdk-js/issues"
+  },
+  "keywords": [
+    "sebpay",
+    "payment",
+    "payments",
+    "checkout",
+    "mobile-money",
+    "africa",
+    "webhook",
+    "sdk"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  }
+}