@blockmoblabs/cryptopay 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @blockmoblabs/cryptopay
+
+Take crypto payments in your product. Create a payment against your own customer, order or
+subscription reference; CryptoPay handles the address, the chain and the confirmations, and posts you
+a signed webhook carrying that reference back.
+
+Zero dependencies. Node 18+ for the server entry; any modern browser for `@blockmoblabs/cryptopay/browser`.
+
+```bash
+npm install @blockmoblabs/cryptopay
+```
+
+## Server
+
+```ts
+import { CryptoPay } from '@blockmoblabs/cryptopay';
+
+const cryptopay = new CryptoPay({
+  apiKey: process.env.CRYPTOPAY_API_KEY!,   // cp_test_… or cp_live_…
+  baseUrl: process.env.CRYPTOPAY_API_URL,   // only when self-hosting
+});
+
+const intent = await cryptopay.createIntent({
+  amountUsd: 40,
+  customerEmail: 'user@example.com',
+  customerRef: 'user_8812',
+  orderRef: 'ord_5571',
+  subscriptionRef: 'sub_221',
+  successUrl: 'https://yourapp.com/billing/done',
+  metadata: { plan: 'pro' },
+  idempotencyKey: 'ord_5571',               // replaying returns the same intent
+});
+```
+
+The key decides the merchant **and** the mode — there is no mode flag to get wrong. `cryptopay.mode`
+reports which one you are on.
+
+| Method | What |
+| --- | --- |
+| `createIntent(input)` | Create a payment. Returns `checkoutUrl` and `clientSecret`. |
+| `getIntent(id)` | Read one payment, including its deposit sessions. |
+| `listIntents(query)` | Page through payments; `search` matches any of your references. |
+| `cancelIntent(id)` | Cancel an unpaid payment. Refused once completed. |
+| `verifyWebhook(opts)` | Verify and parse a webhook. Throws on anything suspect. |
+
+Non-2xx responses throw `CryptoPayError` with `status` and `body`.
+
+## Browser
+
+```ts
+import { openCheckout, embedCheckout } from '@blockmoblabs/cryptopay/browser';
+
+openCheckout({
+  checkoutUrl,                               // from the intent your server created
+  onStatus: (status) => console.log(status),
+  onSuccess: () => location.assign('/billing/done'),
+  onCancel: () => console.log('payer closed the modal'),
+});
+
+// or inline, into an element you already have
+embedCheckout(document.getElementById('pay')!, { checkoutUrl, onSuccess: () => location.reload() });
+```
+
+Nothing secret lives here: the checkout URL carries the payer's own credential, and the page it opens
+is served by CryptoPay, so your page never handles an address or an amount. Only messages from the
+checkout's origin can drive the modal.
+
+## Webhooks
+
+Pass the **raw** body — a re-serialized object will not match the signature.
+
+```ts
+app.post('/webhooks/cryptopay', express.raw({ type: 'application/json' }), async (req, res) => {
+  let event;
+  try {
+    event = cryptopay.verifyWebhook({
+      body: req.body,                         // Buffer, not parsed JSON
+      headers: req.headers,
+      secret: process.env.CRYPTOPAY_WEBHOOK_SECRET!,
+    });
+  } catch {
+    return res.sendStatus(400);               // never act on an unverified body
+  }
+
+  if (await alreadyHandled(event.id)) return res.sendStatus(200);
+
+  if (event.type === 'payment.completed') {
+    await credit(event.customer.customerRef!, event.fee!.netUsd, event.customer.orderRef);
+  }
+
+  await markHandled(event.id);
+  res.sendStatus(200);                        // 2xx stops the retries
+});
+```
+
+`verifyWebhook` checks the HMAC-SHA256 signature over `timestamp.eventId.rawBody` in constant time
+and rejects a timestamp outside `toleranceMs` (default 5 minutes), so a validly signed replay of an
+old event does not get through. Delivery is at-least-once: dedupe on `event.id`.
+
+Events: `payment.created`, `payment.detected`, `payment.confirming`, `payment.underpaid`,
+`payment.completed`, `payment.expired`, `payment.failed`.
+
+## Test mode
+
+A test key runs the whole lifecycle against a simulator — real intents, statuses and webhooks, no
+chain and no money. The deposit address is `cptest_…`, deliberately invalid on every network, and the
+payment confirms on a timer: detected within ~15s and confirmed within ~30s, since the watcher that
+advances it ticks every 15 seconds. In an automated test, call `POST /sessions/:id/recheck` (what *I
+have paid* does in the checkout) to confirm immediately instead of sleeping.
+
+Going live is one environment variable: the key changes, the code does not.
+
+## Fees
+
+$2 flat per successful payment, charged once on completion. It comes off your side — the payer is
+asked for exactly the invoice amount. On a $40 payment, `fee` is
+`{ grossUsd: 40, feeUsd: 2, netUsd: 38 }`.

package/dist/browser.d.ts

@@ -0,0 +1,31 @@
+import type { PaymentStatus } from './types.js';
+export type { PaymentStatus } from './types.js';
+/** What the checkout page posts to its opener as the payment progresses. */
+export type CheckoutMessage = {
+    source: 'cryptopay';
+    status: PaymentStatus | 'closed';
+};
+export type OpenCheckoutOptions = {
+    /** `checkoutUrl` from the intent your server created. */
+    checkoutUrl: string;
+    /** 'modal' overlays an iframe; 'redirect' navigates the whole page. Default 'modal'. */
+    mode?: 'modal' | 'redirect';
+    onStatus?: (status: PaymentStatus) => void;
+    onSuccess?: () => void;
+    /** Called when the payer closes the modal without completing. */
+    onCancel?: () => void;
+};
+export type CheckoutHandle = {
+    close: () => void;
+};
+/**
+ * Browser helper. Nothing secret lives here — the checkout URL already carries the payer's
+ * credential, and the page it opens is served by CryptoPay, so the merchant's own page never
+ * handles an address or an amount.
+ *
+ *   import { openCheckout } from '@blockmoblabs/cryptopay/browser';
+ *   openCheckout({ checkoutUrl, onSuccess: () => location.reload() });
+ */
+export declare function openCheckout(options: OpenCheckoutOptions): CheckoutHandle;
+/** Inline variant: renders the checkout into an element you already have on the page. */
+export declare function embedCheckout(target: HTMLElement, options: Omit<OpenCheckoutOptions, 'mode'>): CheckoutHandle;

package/dist/browser.js

@@ -0,0 +1,104 @@
+/**
+ * Browser helper. Nothing secret lives here — the checkout URL already carries the payer's
+ * credential, and the page it opens is served by CryptoPay, so the merchant's own page never
+ * handles an address or an amount.
+ *
+ *   import { openCheckout } from '@blockmoblabs/cryptopay/browser';
+ *   openCheckout({ checkoutUrl, onSuccess: () => location.reload() });
+ */
+export function openCheckout(options) {
+    if (options.mode === 'redirect') {
+        window.location.href = options.checkoutUrl;
+        return { close: () => undefined };
+    }
+    const origin = new URL(options.checkoutUrl, window.location.href).origin;
+    const overlay = document.createElement('div');
+    overlay.setAttribute('data-cryptopay', 'overlay');
+    overlay.setAttribute('role', 'dialog');
+    overlay.setAttribute('aria-modal', 'true');
+    overlay.setAttribute('aria-label', 'Pay with crypto');
+    overlay.style.cssText =
+        'position:fixed;inset:0;z-index:2147483000;display:flex;align-items:center;' +
+            'justify-content:center;background:rgba(8,10,16,.72);backdrop-filter:blur(4px);padding:16px';
+    const frame = document.createElement('iframe');
+    frame.src = options.checkoutUrl;
+    frame.title = 'CryptoPay checkout';
+    frame.allow = 'clipboard-write';
+    frame.style.cssText =
+        'width:100%;max-width:460px;height:min(760px,calc(100vh - 32px));border:0;' +
+            'border-radius:16px;background:#fff;box-shadow:0 24px 70px rgba(0,0,0,.45)';
+    const close = document.createElement('button');
+    close.type = 'button';
+    close.setAttribute('aria-label', 'Close checkout');
+    close.textContent = '×';
+    close.style.cssText =
+        'position:absolute;top:14px;right:16px;width:36px;height:36px;border:0;border-radius:50%;' +
+            'background:rgba(255,255,255,.14);color:#fff;font:22px/1 system-ui;cursor:pointer';
+    let done = false;
+    const teardown = (cancelled) => {
+        if (done)
+            return;
+        done = true;
+        window.removeEventListener('message', onMessage);
+        document.removeEventListener('keydown', onKey);
+        overlay.remove();
+        if (cancelled)
+            options.onCancel?.();
+    };
+    function onMessage(event) {
+        // Only the checkout origin may drive this modal.
+        if (event.origin !== origin)
+            return;
+        const data = event.data;
+        if (data?.source !== 'cryptopay')
+            return;
+        if (data.status === 'closed')
+            return teardown(true);
+        options.onStatus?.(data.status);
+        if (data.status === 'completed') {
+            teardown(false);
+            options.onSuccess?.();
+        }
+    }
+    function onKey(event) {
+        if (event.key === 'Escape')
+            teardown(true);
+    }
+    close.addEventListener('click', () => teardown(true));
+    overlay.addEventListener('click', (event) => {
+        if (event.target === overlay)
+            teardown(true);
+    });
+    window.addEventListener('message', onMessage);
+    document.addEventListener('keydown', onKey);
+    overlay.append(frame, close);
+    document.body.appendChild(overlay);
+    return { close: () => teardown(true) };
+}
+/** Inline variant: renders the checkout into an element you already have on the page. */
+export function embedCheckout(target, options) {
+    const origin = new URL(options.checkoutUrl, window.location.href).origin;
+    const frame = document.createElement('iframe');
+    frame.src = options.checkoutUrl;
+    frame.title = 'CryptoPay checkout';
+    frame.allow = 'clipboard-write';
+    frame.style.cssText = 'width:100%;height:100%;min-height:620px;border:0;border-radius:12px';
+    const onMessage = (event) => {
+        if (event.origin !== origin)
+            return;
+        const data = event.data;
+        if (data?.source !== 'cryptopay' || data.status === 'closed')
+            return;
+        options.onStatus?.(data.status);
+        if (data.status === 'completed')
+            options.onSuccess?.();
+    };
+    window.addEventListener('message', onMessage);
+    target.appendChild(frame);
+    return {
+        close: () => {
+            window.removeEventListener('message', onMessage);
+            frame.remove();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { type CreateIntentInput, type PaymentIntent, type WebhookEvent } from './types.js';
+export * from './types.js';
+export type CryptoPayOptions = {
+    /** `cp_test_…` or `cp_live_…`. The key decides the mode; there is no mode flag to get wrong. */
+    apiKey: string;
+    /** Defaults to the hosted API. Point this at your own deployment if you self-host. */
+    baseUrl?: string;
+    /** Per-request timeout, ms. Default 20s. */
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+};
+/**
+ * Server-side CryptoPay client. Keep the API key on your server: it can create charges.
+ *
+ *   const cryptopay = new CryptoPay({ apiKey: process.env.CRYPTOPAY_API_KEY! });
+ *   const intent = await cryptopay.createIntent({ amountUsd: 40, customerEmail: 'user@example.com' });
+ *   // → hand intent.checkoutUrl to the browser
+ */
+export declare class CryptoPay {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: CryptoPayOptions);
+    /** `test` or `live`, read off the key. */
+    get mode(): 'test' | 'live';
+    /**
+     * Create a payment to collect. Pass whichever of your own identifiers you will want back:
+     * they are stored with the payment and echoed in every webhook.
+     */
+    createIntent(input: CreateIntentInput): Promise<PaymentIntent>;
+    getIntent(intentId: string): Promise<PaymentIntent>;
+    cancelIntent(intentId: string): Promise<PaymentIntent>;
+    /** Page through your payments. Filter by any of your own references with `search`. */
+    listIntents(query?: {
+        status?: 'open' | 'completed';
+        search?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        intents: PaymentIntent[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * Verify a webhook and return its parsed body. Pass the RAW request body — a re-serialized object
+     * will not match the signature. Throws if the signature, the headers, or the timestamp is wrong,
+     * so a handler that calls this can trust whatever it returns.
+     */
+    verifyWebhook(opts: {
+        body: string | Buffer;
+        /** The request headers. Case-insensitive lookup; a Node `IncomingHttpHeaders` works directly. */
+        headers: Record<string, string | string[] | undefined> | Headers;
+        secret: string;
+        /** How far out of date a signed request may be. Default 5 minutes. */
+        toleranceMs?: number;
+    }): WebhookEvent;
+    private request;
+}

package/dist/index.js

@@ -0,0 +1,123 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { CryptoPayError, } from './types.js';
+export * from './types.js';
+/**
+ * Server-side CryptoPay client. Keep the API key on your server: it can create charges.
+ *
+ *   const cryptopay = new CryptoPay({ apiKey: process.env.CRYPTOPAY_API_KEY! });
+ *   const intent = await cryptopay.createIntent({ amountUsd: 40, customerEmail: 'user@example.com' });
+ *   // → hand intent.checkoutUrl to the browser
+ */
+export class CryptoPay {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error('CryptoPay: apiKey is required');
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? 'https://api.cryptopay.blockmob.io').replace(/\/+$/, '');
+        this.timeoutMs = options.timeoutMs ?? 20_000;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl)
+            throw new Error('CryptoPay: no fetch available — pass options.fetch');
+    }
+    /** `test` or `live`, read off the key. */
+    get mode() {
+        return this.apiKey.startsWith('cp_live_') ? 'live' : 'test';
+    }
+    /**
+     * Create a payment to collect. Pass whichever of your own identifiers you will want back:
+     * they are stored with the payment and echoed in every webhook.
+     */
+    createIntent(input) {
+        const { idempotencyKey, ...body } = input;
+        return this.request('POST', '/payment-intents', {
+            body,
+            headers: idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {},
+        });
+    }
+    getIntent(intentId) {
+        return this.request('GET', `/payment-intents/${encodeURIComponent(intentId)}`);
+    }
+    cancelIntent(intentId) {
+        return this.request('POST', `/payment-intents/${encodeURIComponent(intentId)}/cancel`);
+    }
+    /** Page through your payments. Filter by any of your own references with `search`. */
+    listIntents(query = {}) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query))
+            if (value !== undefined)
+                params.set(key, String(value));
+        const suffix = params.toString();
+        return this.request('GET', `/payment-intents${suffix ? `?${suffix}` : ''}`);
+    }
+    /**
+     * Verify a webhook and return its parsed body. Pass the RAW request body — a re-serialized object
+     * will not match the signature. Throws if the signature, the headers, or the timestamp is wrong,
+     * so a handler that calls this can trust whatever it returns.
+     */
+    verifyWebhook(opts) {
+        const header = (name) => {
+            const raw = opts.headers instanceof Headers
+                ? opts.headers.get(name)
+                : (opts.headers[name] ?? opts.headers[name.toLowerCase()]);
+            return Array.isArray(raw) ? (raw[0] ?? '') : (raw ?? '');
+        };
+        const signature = header('x-cryptopay-signature');
+        const timestamp = header('x-cryptopay-timestamp');
+        const eventId = header('x-cryptopay-event-id');
+        if (!signature || !timestamp || !eventId)
+            throw new Error('CryptoPay webhook: missing signature headers');
+        const age = Date.now() - Number(timestamp);
+        if (!Number.isFinite(age) || Math.abs(age) > (opts.toleranceMs ?? 5 * 60_000))
+            throw new Error('CryptoPay webhook: timestamp outside tolerance (possible replay)');
+        const body = typeof opts.body === 'string' ? opts.body : opts.body.toString('utf8');
+        const expected = Buffer.from(createHmac('sha256', opts.secret).update(`${timestamp}.${eventId}.${body}`).digest('hex'));
+        const given = Buffer.from(signature.replace(/^sha256=/, ''));
+        if (expected.length !== given.length || !timingSafeEqual(expected, given))
+            throw new Error('CryptoPay webhook: signature mismatch');
+        return JSON.parse(body);
+    }
+    async request(method, path, opts = {}) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                signal: controller.signal,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    ...(opts.body ? { 'Content-Type': 'application/json' } : {}),
+                    ...opts.headers,
+                },
+                ...(opts.body ? { body: JSON.stringify(opts.body) } : {}),
+            });
+            const text = await res.text();
+            const parsed = text ? safeJson(text) : null;
+            if (!res.ok)
+                throw new CryptoPayError(messageOf(parsed) ?? `HTTP ${res.status}`, res.status, parsed);
+            return parsed;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function messageOf(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const message = body.message;
+    if (Array.isArray(message))
+        return message.join('; ');
+    return typeof message === 'string' ? message : null;
+}

package/dist/types.d.ts

@@ -0,0 +1,123 @@
+/** Shared shapes. Mirrors the API's own types; no runtime dependency on the server package. */
+export type ApiMode = 'test' | 'live';
+export type Chain = 'ethereum' | 'bsc' | 'polygon' | 'arbitrum' | 'base' | 'tron' | 'solana' | 'bitcoin';
+export type Asset = 'USDT' | 'USDC' | 'BTC';
+/** The lifecycle of a payment intent. */
+export type PaymentStatus = 'created' | 'awaiting_payment' | 'payment_detected' | 'confirming' | 'completed' | 'expired' | 'failed';
+export type PaymentIntent = {
+    intentId: string;
+    mode: ApiMode;
+    amountUsd: number;
+    status: PaymentStatus;
+    /** Your own identifiers, returned exactly as you sent them. */
+    reference: string | null;
+    customerEmail: string | null;
+    customerRef: string | null;
+    orderRef: string | null;
+    subscriptionRef: string | null;
+    metadata: unknown;
+    /** Present on a server-to-server response. Hand it to the browser; it is the payer's credential. */
+    clientSecret: string | null;
+    /** Redirect or iframe the payer here. Already carries the client secret. */
+    checkoutUrl: string | null;
+    successUrl: string | null;
+    cancelUrl: string | null;
+    /** Null until the payment completes. `netUsd` is what you are credited. */
+    fee: {
+        grossUsd: number;
+        feeUsd: number;
+        netUsd: number;
+    } | null;
+    settledAt: string | null;
+    completedAt: string | null;
+    expiresAt: string | null;
+    createdAt: string;
+};
+export type PaymentSession = {
+    sessionId: string;
+    intentId: string;
+    mode: ApiMode;
+    chain: Chain;
+    chainLabel: string;
+    standard: string;
+    asset: Asset;
+    address: string;
+    amountUsd: number;
+    amount: string;
+    received: string;
+    remaining: string;
+    status: 'awaiting' | 'underpaid' | 'detected' | 'confirmed' | 'expired';
+    confirmations: {
+        required: number;
+        current: number;
+    } | null;
+    finalitySeconds: number;
+    txHashes: string[];
+    explorerTx: string;
+    explorerAddress: string;
+    uri: string;
+    feeHint: string;
+    refundAddress: string | null;
+    expiresAt: string;
+    createdAt: string;
+};
+export type CreateIntentInput = {
+    amountUsd: number;
+    /** At least one of these is strongly recommended: it is how you recognise the payment later. */
+    customerEmail?: string;
+    customerRef?: string;
+    orderRef?: string;
+    subscriptionRef?: string;
+    reference?: string;
+    successUrl?: string;
+    cancelUrl?: string;
+    metadata?: Record<string, unknown>;
+    expiresInHours?: number;
+    /** Repeating a request with the same key returns the original intent instead of charging twice. */
+    idempotencyKey?: string;
+};
+export type WebhookEventType = 'payment.created' | 'payment.detected' | 'payment.confirming' | 'payment.underpaid' | 'payment.completed' | 'payment.expired' | 'payment.failed' | 'sweep.failed';
+export type WebhookEvent = {
+    id: string;
+    type: WebhookEventType;
+    mode: ApiMode;
+    createdAt: string;
+    intentId: string;
+    status: PaymentStatus;
+    amountUsd: number;
+    reference: string | null;
+    /** Your identifiers, so you can map the payment to a user without another API call. */
+    customer: {
+        email: string | null;
+        customerRef: string | null;
+        orderRef: string | null;
+        subscriptionRef: string | null;
+    };
+    metadata: unknown;
+    fee: {
+        grossUsd: number;
+        feeUsd: number;
+        netUsd: number;
+    } | null;
+    payment: {
+        sessionId: string;
+        chain: Chain;
+        asset: Asset;
+        address: string;
+        status: string;
+        amount: string;
+        received: string;
+        /** What actually arrived, in dollars. This is the credited figure, not `amountUsd`. */
+        creditedUsd: number | null;
+        txHashes: string[];
+        confirmations: number | null;
+        refundAddress: string | null;
+        confirmedAt: string | null;
+    } | null;
+};
+/** Thrown for any non-2xx API response. */
+export declare class CryptoPayError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+/** Shared shapes. Mirrors the API's own types; no runtime dependency on the server package. */
+/** Thrown for any non-2xx API response. */
+export class CryptoPayError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'CryptoPayError';
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@blockmoblabs/cryptopay",
+  "version": "0.1.0",
+  "description": "CryptoPay crypto payment infrastructure: create payment intents, open the checkout, verify webhooks.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  }
+}