@opaqueprivacy/merchant-sdk 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,140 @@
+# @opaqueprivacy/merchant-sdk
+
+Drop-in SDK for accepting **private** crypto payments on your site. The amount and sender are hidden on-chain; you still get a signed receipt and a webhook when payment lands.
+
+> **v1 alpha.** APIs may change. Don't rely on this for production revenue yet — treat early integrations as demos. File issues at the [main repo](https://github.com/sorrowzzz/OpaquePrivacy).
+
+---
+
+## Install
+
+```bash
+npm install @opaqueprivacy/merchant-sdk
+```
+
+## Get an API key
+
+1. Go to the Opaque dashboard → **Merchant SDK** tab.
+2. Click **Generate key** and copy the `op_live_...` value. It's shown exactly once.
+3. Paste it into your server's env as `OPAQUE_API_KEY`.
+
+You also need to have made at least one deposit on Opaque from the wallet you generated the key under — that provisions the intermediate wallet that receives payments.
+
+## Server: create a checkout
+
+```ts
+import { OpaquePay } from "@opaqueprivacy/merchant-sdk";
+
+const opaque = new OpaquePay({ apiKey: process.env.OPAQUE_API_KEY! });
+
+const checkout = await opaque.createCheckout({
+  amount: 9.99,
+  serviceId: "order_1234",          // your own order ID
+  expirationHours: 1,
+  callbackUrl: "https://shop.com/webhooks/opaque",
+});
+
+// Send the customer to checkout.url, or hand the URL to the browser widget.
+```
+
+## Browser: drop-in widget
+
+```html
+<button id="pay">Pay with Opaque</button>
+<script type="module">
+  import { openCheckout } from "@opaqueprivacy/merchant-sdk/browser";
+
+  document.getElementById("pay").onclick = async () => {
+    // Ask your server to create a checkout, then open the URL.
+    const { url } = await fetch("/api/create-checkout", { method: "POST" })
+      .then((r) => r.json());
+
+    try {
+      const result = await openCheckout({ url });
+      console.log("paid", result.transactionSignature);
+    } catch (err) {
+      // CheckoutCancelledError if the user closed the popup
+    }
+  };
+</script>
+```
+
+The widget opens `/pay/<id>` in a popup, listens for a `postMessage` from the Opaque gateway, and resolves with `{ requestId, transactionSignature, amount, token }` when the on-chain settle lands.
+
+## Server: verify the webhook
+
+When the payment lands, Opaque POSTs a JSON event to your `callbackUrl` and signs it with an ed25519 key. **Always verify** — anyone could POST anything to your endpoint, but only Opaque can sign with the gateway key.
+
+```ts
+import express from "express";
+import { OpaquePay } from "@opaqueprivacy/merchant-sdk";
+
+const opaque = new OpaquePay({ apiKey: process.env.OPAQUE_API_KEY! });
+const app = express();
+
+// Capture the raw body — needed for signature verification.
+app.post(
+  "/webhooks/opaque",
+  express.raw({ type: "*/*" }),
+  (req, res) => {
+    const sig = req.headers["x-opaque-receipt-signature"] as string;
+    try {
+      const event = opaque.verifyWebhook(req.body.toString("utf8"), sig);
+      // event.requestId, event.amount, event.transactionSignature, …
+      // Mark order paid in your DB here.
+      res.json({ ok: true });
+    } catch (err) {
+      res.status(400).json({ error: (err as Error).message });
+    }
+  },
+);
+```
+
+The webhook is **best-effort, single attempt** in v1 alpha. If your server is down when the gateway tries, the payment still settles on-chain — you can pull the latest state with `opaque.retrieveCheckout(id)` and reconcile.
+
+## Reference
+
+### `new OpaquePay({ apiKey, baseUrl?, fetch? })`
+
+- `apiKey` — required. `op_live_...` from the dashboard.
+- `baseUrl` — defaults to `https://opaque.privacy`.
+- `fetch` — optional custom fetch (defaults to global).
+
+### `opaque.createCheckout(input)`
+
+| Field             | Type     | Notes                                              |
+| ----------------- | -------- | -------------------------------------------------- |
+| `amount`          | `number` | Human units (`9.99` = 9.99 USDC). Required.        |
+| `serviceId`       | `string` | Your own order/cart ID. Max 200 chars. Required.   |
+| `expirationHours` | `number` | Default 24, max 720.                               |
+| `callbackUrl`     | `string` | https:// only. Required if you want a webhook.     |
+
+Returns a `Checkout` with `id`, `url`, `status`, `expiresAt`, etc.
+
+### `opaque.retrieveCheckout(id)`
+
+Returns the latest state of a checkout. Use this to reconcile if a webhook is missed.
+
+### `opaque.verifyWebhook(rawBody, signatureHeader)`
+
+Verifies the ed25519 receipt signature against the gateway's public key. Returns the parsed `WebhookEvent` if valid, throws otherwise.
+
+### `openCheckout({ url, width?, height?, timeoutMs? })` (browser)
+
+Opens the checkout URL in a popup, resolves when the customer pays. Rejects with `CheckoutCancelledError` if they close the window.
+
+## Example
+
+A full Express app is in [`examples/express/`](./examples/express). Run it with:
+
+```bash
+OPAQUE_API_KEY=op_live_xxx node examples/express/index.js
+```
+
+Then visit `http://localhost:3000/pay.html`.
+
+## Security notes
+
+- **Never embed your API key in client-side code.** Always create checkouts from your server.
+- **Always verify webhook signatures.** Webhooks come from the public internet — only the signature proves they came from Opaque.
+- The plaintext API key is shown once at creation. Revoke and rotate from the dashboard.

package/dist/browser.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Browser-side helper for opening an Opaque Pay checkout as a popup and
+ * resolving when the payment lands. The popup posts a message back via
+ * window.opener.postMessage — see src/pages/Pay.tsx on the gateway.
+ *
+ * Usage:
+ *   import { openCheckout } from "@opaqueprivacy/merchant-sdk/browser";
+ *   const result = await openCheckout({ url: checkout.url });
+ *   // result.transactionSignature is the on-chain proof of payment.
+ */
+export interface OpenCheckoutOptions {
+    /** Checkout URL returned by OpaquePay.createCheckout(). */
+    url: string;
+    /** Popup width, default 480. */
+    width?: number;
+    /** Popup height, default 720. */
+    height?: number;
+    /** Abort if no payment within N ms. Default: no timeout. */
+    timeoutMs?: number;
+}
+export interface CheckoutResult {
+    requestId: string;
+    transactionSignature: string | null;
+    amount: number;
+    token: "USDC";
+}
+export declare class CheckoutCancelledError extends Error {
+    constructor();
+}
+export declare class CheckoutTimeoutError extends Error {
+    constructor();
+}
+export declare function openCheckout(opts: OpenCheckoutOptions): Promise<CheckoutResult>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,sBAAuB,SAAQ,KAAK;;CAKhD;AAED,qBAAa,oBAAqB,SAAQ,KAAK;;CAK9C;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,cAAc,CAAC,CAyEzB"}

package/dist/browser.js

@@ -0,0 +1,87 @@
+/**
+ * Browser-side helper for opening an Opaque Pay checkout as a popup and
+ * resolving when the payment lands. The popup posts a message back via
+ * window.opener.postMessage — see src/pages/Pay.tsx on the gateway.
+ *
+ * Usage:
+ *   import { openCheckout } from "@opaqueprivacy/merchant-sdk/browser";
+ *   const result = await openCheckout({ url: checkout.url });
+ *   // result.transactionSignature is the on-chain proof of payment.
+ */
+export class CheckoutCancelledError extends Error {
+    constructor() {
+        super("Checkout window was closed before payment completed");
+        this.name = "CheckoutCancelledError";
+    }
+}
+export class CheckoutTimeoutError extends Error {
+    constructor() {
+        super("Checkout timed out");
+        this.name = "CheckoutTimeoutError";
+    }
+}
+export function openCheckout(opts) {
+    const width = opts.width ?? 480;
+    const height = opts.height ?? 720;
+    const left = Math.max(0, Math.floor((window.screen.width - width) / 2));
+    const top = Math.max(0, Math.floor((window.screen.height - height) / 2));
+    const features = `width=${width},height=${height},left=${left},top=${top},menubar=no,toolbar=no,location=no,status=no`;
+    const popup = window.open(opts.url, "opaque-pay-checkout", features);
+    if (!popup) {
+        return Promise.reject(new Error("Popup blocked. Open the URL in a new tab or whitelist the domain."));
+    }
+    return new Promise((resolve, reject) => {
+        let done = false;
+        const cleanup = () => {
+            done = true;
+            window.removeEventListener("message", onMessage);
+            window.clearInterval(pollClosed);
+            if (timeoutHandle)
+                window.clearTimeout(timeoutHandle);
+        };
+        const onMessage = (ev) => {
+            const data = ev.data;
+            if (!data || data.type !== "opaque-pay-success")
+                return;
+            if (!data.requestId)
+                return;
+            cleanup();
+            try {
+                popup.close();
+            }
+            catch {
+                // popup may already be closed cross-origin; ignore.
+            }
+            resolve({
+                requestId: data.requestId,
+                transactionSignature: data.transactionSignature ?? null,
+                amount: data.amount ?? 0,
+                token: data.token ?? "USDC",
+            });
+        };
+        window.addEventListener("message", onMessage);
+        const pollClosed = window.setInterval(() => {
+            if (done)
+                return;
+            if (popup.closed) {
+                cleanup();
+                reject(new CheckoutCancelledError());
+            }
+        }, 500);
+        const timeoutHandle = opts.timeoutMs
+            ? window.setTimeout(() => {
+                if (done)
+                    return;
+                cleanup();
+                try {
+                    popup.close();
+                }
+                catch {
+                    // ignore
+                }
+                reject(new CheckoutTimeoutError());
+            }, opts.timeoutMs)
+            : null;
+    });
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import type { Checkout, CreateCheckoutInput, WebhookEvent } from "./types.js";
+export interface OpaquePayOptions {
+    /** API key generated in the Opaque dashboard (op_live_...). */
+    apiKey: string;
+    /** Base URL of the Opaque gateway. Defaults to production. */
+    baseUrl?: string;
+    /** Optional fetch implementation (e.g. for testing or non-global fetch). */
+    fetch?: typeof fetch;
+}
+export declare class OpaquePayError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+export declare class OpaquePay {
+    private apiKey;
+    private baseUrl;
+    private fetchImpl;
+    constructor(opts: OpaquePayOptions);
+    /**
+     * Create a private checkout. Send the customer to `checkout.url` —
+     * either by redirecting, or by passing the URL to the browser widget.
+     */
+    createCheckout(input: CreateCheckoutInput): Promise<Checkout>;
+    /** Fetch the latest state of a checkout (status, payer, tx sig). */
+    retrieveCheckout(id: string): Promise<Checkout & {
+        payerWallet?: string;
+        transactionSignature?: string;
+        paidAt?: string;
+    }>;
+    /**
+     * Verify a webhook payload using the receipt signature the gateway
+     * sends alongside it. Returns the parsed event if valid, throws if
+     * the signature doesn't verify.
+     *
+     * Pass the raw request body (string) and the signature from the
+     * X-Opaque-Receipt-Signature header.
+     */
+    verifyWebhook(rawBody: string, signatureHexHeader: string | undefined): WebhookEvent;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,mBAAmB,EACnB,YAAY,EACb,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;gBACF,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM3D;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAe;gBAEpB,IAAI,EAAE,gBAAgB;IAmBlC;;;OAGG;IACG,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IA4CnE,oEAAoE;IAC9D,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG;QACrD,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IAeF;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY;CAkBrF"}

package/dist/client.js

@@ -0,0 +1,117 @@
+import { verifyReceipt } from "./receipt.js";
+export class OpaquePayError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.name = "OpaquePayError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export class OpaquePay {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    constructor(opts) {
+        if (!opts.apiKey) {
+            throw new Error("OpaquePay: apiKey is required");
+        }
+        if (!opts.apiKey.startsWith("op_live_")) {
+            throw new Error("OpaquePay: apiKey must start with op_live_ (generate one in your dashboard)");
+        }
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? "https://opaque.privacy").replace(/\/$/, "");
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error("OpaquePay: no fetch implementation found. Pass one via options.fetch.");
+        }
+    }
+    /**
+     * Create a private checkout. Send the customer to `checkout.url` —
+     * either by redirecting, or by passing the URL to the browser widget.
+     */
+    async createCheckout(input) {
+        if (!(input.amount > 0)) {
+            throw new Error("createCheckout: amount must be > 0");
+        }
+        if (!input.serviceId?.trim()) {
+            throw new Error("createCheckout: serviceId is required");
+        }
+        const res = await this.fetchImpl(`${this.baseUrl}/api/x402/create`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                amount: input.amount,
+                serviceId: input.serviceId,
+                expirationHours: input.expirationHours,
+                callbackUrl: input.callbackUrl,
+            }),
+        });
+        const json = await safeJson(res);
+        if (!res.ok) {
+            throw new OpaquePayError(res.status, json?.error ?? `Failed to create checkout (${res.status})`, json);
+        }
+        return {
+            id: json.id,
+            url: json.url,
+            amount: json.amount,
+            token: json.token,
+            serviceId: json.serviceId,
+            status: json.status,
+            expiresAt: json.expiresAt,
+            createdAt: json.createdAt,
+            callbackUrl: json.callbackUrl ?? null,
+        };
+    }
+    /** Fetch the latest state of a checkout (status, payer, tx sig). */
+    async retrieveCheckout(id) {
+        const res = await this.fetchImpl(`${this.baseUrl}/api/x402/${id}`, {
+            method: "GET",
+        });
+        const json = await safeJson(res);
+        if (!res.ok) {
+            throw new OpaquePayError(res.status, json?.error ?? `Failed to retrieve checkout (${res.status})`, json);
+        }
+        return json;
+    }
+    /**
+     * Verify a webhook payload using the receipt signature the gateway
+     * sends alongside it. Returns the parsed event if valid, throws if
+     * the signature doesn't verify.
+     *
+     * Pass the raw request body (string) and the signature from the
+     * X-Opaque-Receipt-Signature header.
+     */
+    verifyWebhook(rawBody, signatureHexHeader) {
+        if (!signatureHexHeader) {
+            throw new Error("verifyWebhook: missing X-Opaque-Receipt-Signature header");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(rawBody);
+        }
+        catch {
+            throw new Error("verifyWebhook: body is not valid JSON");
+        }
+        if (parsed.receiptSignatureHex !== signatureHexHeader) {
+            throw new Error("verifyWebhook: header signature does not match body");
+        }
+        if (!verifyReceipt(parsed)) {
+            throw new Error("verifyWebhook: signature is invalid");
+        }
+        return parsed;
+    }
+}
+async function safeJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { OpaquePay, OpaquePayError } from "./client.js";
+export type { OpaquePayOptions } from "./client.js";
+export { buildCanonicalReceipt, verifyReceipt, } from "./receipt.js";
+export type { Checkout, CheckoutStatus, CreateCheckoutInput, Token, WebhookEvent, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,KAAK,EACL,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { OpaquePay, OpaquePayError } from "./client.js";
+export { buildCanonicalReceipt, verifyReceipt, } from "./receipt.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EACL,qBAAqB,EACrB,aAAa,GACd,MAAM,cAAc,CAAC"}

package/dist/receipt.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Verify the ed25519 receipt the Opaque gateway signs for every paid
+ * checkout. The canonical message must match lib/x402-receipt.ts on the
+ * gateway side — if you change one, change both.
+ */
+import type { WebhookEvent } from "./types.js";
+export declare function buildCanonicalReceipt(e: {
+    requestId: string;
+    merchantWallet: string;
+    payerWallet: string;
+    amount: number;
+    token: "USDC";
+    paidAt: Date;
+    transactionSignature: string;
+}): string;
+export declare function verifyReceipt(event: WebhookEvent): boolean;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C,wBAAgB,qBAAqB,CAAC,CAAC,EAAE;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,IAAI,CAAC;IACb,oBAAoB,EAAE,MAAM,CAAC;CAC9B,GAAG,MAAM,CAWT;AAWD,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAe1D"}

package/dist/receipt.js

@@ -0,0 +1,47 @@
+/**
+ * Verify the ed25519 receipt the Opaque gateway signs for every paid
+ * checkout. The canonical message must match lib/x402-receipt.ts on the
+ * gateway side — if you change one, change both.
+ */
+import nacl from "tweetnacl";
+import bs58 from "bs58";
+const RECEIPT_VERSION = "opaque.x402.receipt.v1";
+function formatAmount(n) {
+    return Number(n.toFixed(6)).toString();
+}
+export function buildCanonicalReceipt(e) {
+    return [
+        RECEIPT_VERSION,
+        e.requestId,
+        e.merchantWallet,
+        e.payerWallet,
+        formatAmount(e.amount),
+        e.token,
+        Math.floor(e.paidAt.getTime() / 1000).toString(),
+        e.transactionSignature,
+    ].join("\n");
+}
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0)
+        throw new Error("invalid hex");
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+export function verifyReceipt(event) {
+    const message = new TextEncoder().encode(buildCanonicalReceipt({
+        requestId: event.requestId,
+        merchantWallet: event.merchantWallet,
+        payerWallet: event.payerWallet,
+        amount: event.amount,
+        token: event.token,
+        paidAt: new Date(event.paidAt),
+        transactionSignature: event.transactionSignature,
+    }));
+    const sig = hexToBytes(event.receiptSignatureHex);
+    const pubkey = bs58.decode(event.gatewayPublicKey);
+    return nacl.sign.detached.verify(message, sig, pubkey);
+}
+//# sourceMappingURL=receipt.js.map

package/dist/receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,IAAI,MAAM,MAAM,CAAC;AAGxB,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEjD,SAAS,YAAY,CAAC,CAAS;IAC7B,OAAO,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,CAQrC;IACC,OAAO;QACL,eAAe;QACf,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,WAAW;QACb,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC;QACtB,CAAC,CAAC,KAAK;QACP,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,EAAE;QAChD,CAAC,CAAC,oBAAoB;KACvB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;IACzD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAmB;IAC/C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CACtC,qBAAqB,CAAC;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QAC9B,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;KACjD,CAAC,CACH,CAAC;IACF,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+export type Token = "USDC";
+export type CheckoutStatus = "pending" | "settling" | "paid" | "expired" | "failed";
+export interface CreateCheckoutInput {
+    /** Amount in human units (e.g. 9.99 USDC). */
+    amount: number;
+    /** Opaque identifier the merchant uses to correlate the checkout
+     *  back to their own order/cart. Max 200 chars. */
+    serviceId: string;
+    /** How long the checkout link stays valid. Default 24h, max 720h. */
+    expirationHours?: number;
+    /** HTTPS URL the gateway POSTs to when the payment lands. */
+    callbackUrl?: string;
+}
+export interface Checkout {
+    id: string;
+    /** URL the customer is sent to. Hosts the private-pay flow. */
+    url: string;
+    amount: number;
+    token: Token;
+    serviceId: string;
+    status: CheckoutStatus;
+    expiresAt: string;
+    createdAt: string;
+    callbackUrl: string | null;
+}
+export interface WebhookEvent {
+    requestId: string;
+    status: "paid";
+    merchantWallet: string;
+    payerWallet: string;
+    amount: number;
+    token: Token;
+    paidAt: string;
+    transactionSignature: string;
+    receiptSignatureHex: string;
+    gatewayPublicKey: string;
+    receiptVersion: "opaque.x402.receipt.v1";
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC;AAE3B,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,UAAU,GACV,MAAM,GACN,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf;uDACmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,wBAAwB,CAAC;CAC1C"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@opaqueprivacy/merchant-sdk",
+  "version": "0.1.0-alpha.0",
+  "description": "Opaque Pay Merchant SDK — accept private crypto payments on your site.",
+  "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",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "bs58": "^5.0.0",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sorrowzzz/OpaquePrivacy.git",
+    "directory": "sdk"
+  },
+  "keywords": [
+    "opaque",
+    "privacy",
+    "payments",
+    "solana",
+    "x402",
+    "zk"
+  ]
+}

package/src/browser.ts

@@ -0,0 +1,119 @@
+/**
+ * Browser-side helper for opening an Opaque Pay checkout as a popup and
+ * resolving when the payment lands. The popup posts a message back via
+ * window.opener.postMessage — see src/pages/Pay.tsx on the gateway.
+ *
+ * Usage:
+ *   import { openCheckout } from "@opaqueprivacy/merchant-sdk/browser";
+ *   const result = await openCheckout({ url: checkout.url });
+ *   // result.transactionSignature is the on-chain proof of payment.
+ */
+
+export interface OpenCheckoutOptions {
+  /** Checkout URL returned by OpaquePay.createCheckout(). */
+  url: string;
+  /** Popup width, default 480. */
+  width?: number;
+  /** Popup height, default 720. */
+  height?: number;
+  /** Abort if no payment within N ms. Default: no timeout. */
+  timeoutMs?: number;
+}
+
+export interface CheckoutResult {
+  requestId: string;
+  transactionSignature: string | null;
+  amount: number;
+  token: "USDC";
+}
+
+export class CheckoutCancelledError extends Error {
+  constructor() {
+    super("Checkout window was closed before payment completed");
+    this.name = "CheckoutCancelledError";
+  }
+}
+
+export class CheckoutTimeoutError extends Error {
+  constructor() {
+    super("Checkout timed out");
+    this.name = "CheckoutTimeoutError";
+  }
+}
+
+export function openCheckout(
+  opts: OpenCheckoutOptions,
+): Promise<CheckoutResult> {
+  const width = opts.width ?? 480;
+  const height = opts.height ?? 720;
+  const left = Math.max(0, Math.floor((window.screen.width - width) / 2));
+  const top = Math.max(0, Math.floor((window.screen.height - height) / 2));
+  const features = `width=${width},height=${height},left=${left},top=${top},menubar=no,toolbar=no,location=no,status=no`;
+
+  const popup = window.open(opts.url, "opaque-pay-checkout", features);
+  if (!popup) {
+    return Promise.reject(
+      new Error(
+        "Popup blocked. Open the URL in a new tab or whitelist the domain.",
+      ),
+    );
+  }
+
+  return new Promise<CheckoutResult>((resolve, reject) => {
+    let done = false;
+    const cleanup = () => {
+      done = true;
+      window.removeEventListener("message", onMessage);
+      window.clearInterval(pollClosed);
+      if (timeoutHandle) window.clearTimeout(timeoutHandle);
+    };
+
+    const onMessage = (ev: MessageEvent) => {
+      const data = ev.data as
+        | {
+            type?: string;
+            requestId?: string;
+            transactionSignature?: string | null;
+            amount?: number;
+            token?: "USDC";
+          }
+        | null;
+      if (!data || data.type !== "opaque-pay-success") return;
+      if (!data.requestId) return;
+      cleanup();
+      try {
+        popup.close();
+      } catch {
+        // popup may already be closed cross-origin; ignore.
+      }
+      resolve({
+        requestId: data.requestId,
+        transactionSignature: data.transactionSignature ?? null,
+        amount: data.amount ?? 0,
+        token: data.token ?? "USDC",
+      });
+    };
+    window.addEventListener("message", onMessage);
+
+    const pollClosed = window.setInterval(() => {
+      if (done) return;
+      if (popup.closed) {
+        cleanup();
+        reject(new CheckoutCancelledError());
+      }
+    }, 500);
+
+    const timeoutHandle = opts.timeoutMs
+      ? window.setTimeout(() => {
+          if (done) return;
+          cleanup();
+          try {
+            popup.close();
+          } catch {
+            // ignore
+          }
+          reject(new CheckoutTimeoutError());
+        }, opts.timeoutMs)
+      : null;
+  });
+}

package/src/client.ts

@@ -0,0 +1,154 @@
+import type {
+  Checkout,
+  CreateCheckoutInput,
+  WebhookEvent,
+} from "./types.js";
+import { verifyReceipt } from "./receipt.js";
+
+export interface OpaquePayOptions {
+  /** API key generated in the Opaque dashboard (op_live_...). */
+  apiKey: string;
+  /** Base URL of the Opaque gateway. Defaults to production. */
+  baseUrl?: string;
+  /** Optional fetch implementation (e.g. for testing or non-global fetch). */
+  fetch?: typeof fetch;
+}
+
+export class OpaquePayError extends Error {
+  status: number;
+  body: unknown;
+  constructor(status: number, message: string, body: unknown) {
+    super(message);
+    this.name = "OpaquePayError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class OpaquePay {
+  private apiKey: string;
+  private baseUrl: string;
+  private fetchImpl: typeof fetch;
+
+  constructor(opts: OpaquePayOptions) {
+    if (!opts.apiKey) {
+      throw new Error("OpaquePay: apiKey is required");
+    }
+    if (!opts.apiKey.startsWith("op_live_")) {
+      throw new Error(
+        "OpaquePay: apiKey must start with op_live_ (generate one in your dashboard)",
+      );
+    }
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://opaque.privacy").replace(/\/$/, "");
+    this.fetchImpl = opts.fetch ?? (globalThis.fetch as typeof fetch);
+    if (!this.fetchImpl) {
+      throw new Error(
+        "OpaquePay: no fetch implementation found. Pass one via options.fetch.",
+      );
+    }
+  }
+
+  /**
+   * Create a private checkout. Send the customer to `checkout.url` —
+   * either by redirecting, or by passing the URL to the browser widget.
+   */
+  async createCheckout(input: CreateCheckoutInput): Promise<Checkout> {
+    if (!(input.amount > 0)) {
+      throw new Error("createCheckout: amount must be > 0");
+    }
+    if (!input.serviceId?.trim()) {
+      throw new Error("createCheckout: serviceId is required");
+    }
+
+    const res = await this.fetchImpl(`${this.baseUrl}/api/x402/create`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        amount: input.amount,
+        serviceId: input.serviceId,
+        expirationHours: input.expirationHours,
+        callbackUrl: input.callbackUrl,
+      }),
+    });
+
+    const json = await safeJson(res);
+    if (!res.ok) {
+      throw new OpaquePayError(
+        res.status,
+        (json as any)?.error ?? `Failed to create checkout (${res.status})`,
+        json,
+      );
+    }
+
+    return {
+      id: (json as any).id,
+      url: (json as any).url,
+      amount: (json as any).amount,
+      token: (json as any).token,
+      serviceId: (json as any).serviceId,
+      status: (json as any).status,
+      expiresAt: (json as any).expiresAt,
+      createdAt: (json as any).createdAt,
+      callbackUrl: (json as any).callbackUrl ?? null,
+    };
+  }
+
+  /** Fetch the latest state of a checkout (status, payer, tx sig). */
+  async retrieveCheckout(id: string): Promise<Checkout & {
+    payerWallet?: string;
+    transactionSignature?: string;
+    paidAt?: string;
+  }> {
+    const res = await this.fetchImpl(`${this.baseUrl}/api/x402/${id}`, {
+      method: "GET",
+    });
+    const json = await safeJson(res);
+    if (!res.ok) {
+      throw new OpaquePayError(
+        res.status,
+        (json as any)?.error ?? `Failed to retrieve checkout (${res.status})`,
+        json,
+      );
+    }
+    return json as any;
+  }
+
+  /**
+   * Verify a webhook payload using the receipt signature the gateway
+   * sends alongside it. Returns the parsed event if valid, throws if
+   * the signature doesn't verify.
+   *
+   * Pass the raw request body (string) and the signature from the
+   * X-Opaque-Receipt-Signature header.
+   */
+  verifyWebhook(rawBody: string, signatureHexHeader: string | undefined): WebhookEvent {
+    if (!signatureHexHeader) {
+      throw new Error("verifyWebhook: missing X-Opaque-Receipt-Signature header");
+    }
+    let parsed: WebhookEvent;
+    try {
+      parsed = JSON.parse(rawBody) as WebhookEvent;
+    } catch {
+      throw new Error("verifyWebhook: body is not valid JSON");
+    }
+    if (parsed.receiptSignatureHex !== signatureHexHeader) {
+      throw new Error("verifyWebhook: header signature does not match body");
+    }
+    if (!verifyReceipt(parsed)) {
+      throw new Error("verifyWebhook: signature is invalid");
+    }
+    return parsed;
+  }
+}
+
+async function safeJson(res: Response): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { OpaquePay, OpaquePayError } from "./client.js";
+export type { OpaquePayOptions } from "./client.js";
+export {
+  buildCanonicalReceipt,
+  verifyReceipt,
+} from "./receipt.js";
+export type {
+  Checkout,
+  CheckoutStatus,
+  CreateCheckoutInput,
+  Token,
+  WebhookEvent,
+} from "./types.js";

package/src/receipt.ts

@@ -0,0 +1,62 @@
+/**
+ * Verify the ed25519 receipt the Opaque gateway signs for every paid
+ * checkout. The canonical message must match lib/x402-receipt.ts on the
+ * gateway side — if you change one, change both.
+ */
+
+import nacl from "tweetnacl";
+import bs58 from "bs58";
+import type { WebhookEvent } from "./types.js";
+
+const RECEIPT_VERSION = "opaque.x402.receipt.v1";
+
+function formatAmount(n: number): string {
+  return Number(n.toFixed(6)).toString();
+}
+
+export function buildCanonicalReceipt(e: {
+  requestId: string;
+  merchantWallet: string;
+  payerWallet: string;
+  amount: number;
+  token: "USDC";
+  paidAt: Date;
+  transactionSignature: string;
+}): string {
+  return [
+    RECEIPT_VERSION,
+    e.requestId,
+    e.merchantWallet,
+    e.payerWallet,
+    formatAmount(e.amount),
+    e.token,
+    Math.floor(e.paidAt.getTime() / 1000).toString(),
+    e.transactionSignature,
+  ].join("\n");
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0) throw new Error("invalid hex");
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+export function verifyReceipt(event: WebhookEvent): boolean {
+  const message = new TextEncoder().encode(
+    buildCanonicalReceipt({
+      requestId: event.requestId,
+      merchantWallet: event.merchantWallet,
+      payerWallet: event.payerWallet,
+      amount: event.amount,
+      token: event.token,
+      paidAt: new Date(event.paidAt),
+      transactionSignature: event.transactionSignature,
+    }),
+  );
+  const sig = hexToBytes(event.receiptSignatureHex);
+  const pubkey = bs58.decode(event.gatewayPublicKey);
+  return nacl.sign.detached.verify(message, sig, pubkey);
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+export type Token = "USDC";
+
+export type CheckoutStatus =
+  | "pending"
+  | "settling"
+  | "paid"
+  | "expired"
+  | "failed";
+
+export interface CreateCheckoutInput {
+  /** Amount in human units (e.g. 9.99 USDC). */
+  amount: number;
+  /** Opaque identifier the merchant uses to correlate the checkout
+   *  back to their own order/cart. Max 200 chars. */
+  serviceId: string;
+  /** How long the checkout link stays valid. Default 24h, max 720h. */
+  expirationHours?: number;
+  /** HTTPS URL the gateway POSTs to when the payment lands. */
+  callbackUrl?: string;
+}
+
+export interface Checkout {
+  id: string;
+  /** URL the customer is sent to. Hosts the private-pay flow. */
+  url: string;
+  amount: number;
+  token: Token;
+  serviceId: string;
+  status: CheckoutStatus;
+  expiresAt: string;
+  createdAt: string;
+  callbackUrl: string | null;
+}
+
+export interface WebhookEvent {
+  requestId: string;
+  status: "paid";
+  merchantWallet: string;
+  payerWallet: string;
+  amount: number;
+  token: Token;
+  paidAt: string;
+  transactionSignature: string;
+  receiptSignatureHex: string;
+  gatewayPublicKey: string;
+  receiptVersion: "opaque.x402.receipt.v1";
+}