paybox-emulator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ds asante
+
+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,47 @@
+# paybox-emulator
+
+A local payment infrastructure emulator. Point an existing Paystack, Stripe,
+Flutterwave, Kora, WeWire or Wise integration at `localhost` and test the parts
+of payments that are hard to test: pending transactions, asynchronous
+mobile-money authorization, duplicate webhooks, retries, timeouts, refunds,
+idempotency and flaky networks — deterministically, with no provider sandbox.
+
+```bash
+npx paybox-emulator start
+```
+
+```
+  paybox — local payment emulator
+  ───────────────────────────────────────────────
+  API         http://127.0.0.1:8080
+  Dashboard   http://127.0.0.1:8080/dashboard
+  API docs    http://127.0.0.1:8080/docs
+```
+
+Point your app at it and use it exactly as you would the real API:
+
+```env
+PAYSTACK_BASE_URL=http://127.0.0.1:8080/paystack
+PAYSTACK_SECRET_KEY=sk_test_local_...        # printed by the banner
+```
+
+Then drive the things a sandbox cannot:
+
+```bash
+paybox webhook add http://localhost:3000/webhooks/paystack
+paybox payment success order_1               # signed charge.success arrives
+paybox time advance 2h                       # every retry due in that window fires now
+paybox webhook chaos --duplicate true        # does your handler double-credit?
+```
+
+**No real money can move through this process.** It has no code path that
+reaches a payment network and it refuses live API keys.
+
+Every adapter is **partially** implemented and each one's coverage is a
+documented contract, not marketing. Requires Node 22.5 or newer; nothing else.
+
+Full documentation, the coverage tables, the Docker image and the source:
+<https://github.com/dsasante1/paybox>.
+
+MIT. Not affiliated with, endorsed by, or connected to any payment provider
+named above; the names describe API compatibility only.

package/bin/paybox.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// The `paybox` command installed by `npm install -g paybox-emulator` (and what
+// `npx paybox-emulator` runs). It does two things before loading the bundle,
+// and both have to happen before anything imports `node:sqlite`, which is why
+// the bundle is loaded with a dynamic import at the very end rather than a
+// static one at the top (static imports are hoisted above this code).
+//
+// 1. Refuse old Node with a message that names the fix. The storage layer uses
+//    the built-in `node:sqlite`, which arrived in 22.5; on anything older the
+//    first sign of trouble would otherwise be ERR_UNKNOWN_BUILTIN_MODULE from
+//    deep inside the bundle, and `npx` does not enforce `engines` by itself.
+//
+// 2. Silence `node:sqlite`'s ExperimentalWarning on Node 22, where it prints on
+//    every start and buries the banner. Only that one warning: deprecations and
+//    everything else still reach Node's own printer, so nothing is hidden that
+//    a developer would want to see. `node --disable-warning=ExperimentalWarning`
+//    would be broader and cannot be set from a shebang portably anyway.
+
+const [major = 0, minor = 0] = process.versions.node.split('.').map(Number);
+if (major < 22 || (major === 22 && minor < 5)) {
+  process.stderr.write(
+    `paybox needs Node 22.5 or newer; this is Node ${process.versions.node}.\n` +
+      'It uses the built-in node:sqlite module, so there is nothing to compile — ' +
+      'upgrading Node is the whole fix.\n',
+  );
+  process.exit(1);
+}
+
+const printers = process.listeners('warning');
+process.removeAllListeners('warning');
+process.on('warning', (warning) => {
+  if (warning.name === 'ExperimentalWarning' && /sqlite/i.test(warning.message)) return;
+  for (const print of printers) print.call(process, warning);
+});
+
+await import('../dist/paybox.js');