Overview
Overview
nimiq-pay-utils is a pnpm monorepo for the Nimiq Pay Better Auth flows, runtime adapters, and local test harness packages.
- The direct flow runs entirely inside a Nimiq Pay mini-app and signs in immediately.
- The QR flow starts on desktop, moves the approval step to the phone, and creates the Better Auth session on the desktop side.
Packages
| Package | Purpose |
|---|---|
@onmax/better-auth-nimiq-pay | Direct Nimiq Pay sign-in for Better Auth |
@onmax/better-auth-mobile-qr | Same-origin QR challenge, approval, and desktop session claim |
@onmax/mobile-signer-bridge | Generic phone-side bridge contract |
@onmax/mobile-signer-nimiq-pay | Nimiq Pay adapter for the bridge and QR provider |
@onmax/nimiq-mini-app-runtime | Runtime-safe access to the published mini-app provider |
@onmax/nimiq-mini-app-simulator | Local host shell, injected provider, and Nuxt devtools integration |
@onmax/better-auth-nimiq-pay-e2e | Shared local fetchers, stub providers, and Vitest-first scenarios |
How the flows differ
Direct flow
The direct plugin issues a nonce, asks the mini-app to sign a message, verifies the signature, and returns a Better Auth bearer token or session. Use this when the current browser already has access to window.nimiq.
QR flow
The QR plugin creates a pending desktop challenge, stores a poll cookie, exposes the challenge to the phone page, accepts the signed phone assertion, and creates the Better Auth session only when the desktop polls the status endpoint again.
Runtime and simulator support
Use @onmax/nimiq-mini-app-runtime when your app code needs one stable way to wait for and read the Nimiq mini-app provider.
Use @onmax/nimiq-mini-app-simulator when you want deterministic local development without the real host app. The simulator can inject a fake provider, expose host state, and start a separate Nuxt sidecar during development.