@phala/pay 0.1.0

package/src/react/Checkout.tsx

@@ -0,0 +1,409 @@
+"use client";
+
+import { useEffect, useId, useRef, useState, type KeyboardEvent } from "react";
+import type { Hash } from "viem";
+import type { CheckoutStatus } from "../checkout.js";
+import { networkName, transactionUrl } from "../chains.js";
+import { formatAmount, formatCountdown, formatTokenAmount, tokenAmount } from "../format.js";
+import { quoteTransfer } from "../payment.js";
+import type { ClientQuote } from "../quote.js";
+import { WalletError, payWithWallet, watchWallets, type Wallet } from "../wallet.js";
+import { STYLES, appearanceStyle, type Appearance } from "./appearance.js";
+import { QrCode } from "./QrCode.js";
+import { useCheckout } from "./useCheckout.js";
+
+export interface CheckoutProps {
+  /** The quote's `client_secret`, from your backend's `POST /v1/quotes`. */
+  clientSecret: string;
+  /** The service origin, for example `https://topup.example.com`. */
+  apiBase: string;
+  /** Called once when the payment is credited. Fulfil from the `deposit.credited` webhook, not here. */
+  onSuccess?: (quote: ClientQuote) => void;
+  /** Called once when the quote expires or is canceled without a payment. */
+  onExpire?: (quote: ClientQuote) => void;
+  appearance?: Appearance;
+  /** Milliseconds between status reads; default 3000. */
+  pollInterval?: number;
+  className?: string;
+  /** The wallet button's label; default "Pay with crypto". */
+  buttonText?: string;
+}
+
+type Method = "wallet" | "qr" | "manual";
+
+const METHODS: { id: Method; label: string }[] = [
+  { id: "wallet", label: "Browser wallet" },
+  { id: "qr", label: "QR code" },
+  { id: "manual", label: "Send manually" },
+];
+
+/** A checkout for one quote: pay from a browser wallet, by QR code, or manually, with live status. */
+export function Checkout({
+  clientSecret,
+  apiBase,
+  onSuccess,
+  onExpire,
+  appearance,
+  pollInterval,
+  className,
+  buttonText = "Pay with crypto",
+}: CheckoutProps) {
+  const { status, quote, error, refresh } = useCheckout({
+    clientSecret,
+    apiBase,
+    ...(pollInterval === undefined ? {} : { pollInterval }),
+  });
+  const [txHash, setTxHash] = useState<Hash | null>(null);
+  const now = useNow(status === "waiting");
+
+  const callbacks = useRef({ onSuccess, onExpire });
+  useEffect(() => {
+    callbacks.current = { onSuccess, onExpire };
+  });
+  const notified = useRef<string | null>(null);
+  useEffect(() => {
+    if (quote === null || notified.current === quote.id) {
+      return;
+    }
+    if (status === "credited") {
+      notified.current = quote.id;
+      callbacks.current.onSuccess?.(quote);
+    } else if (status === "expired" || status === "canceled") {
+      notified.current = quote.id;
+      callbacks.current.onExpire?.(quote);
+    }
+  }, [status, quote]);
+
+  return (
+    <div
+      className={className === undefined ? "pp-root" : `pp-root ${className}`}
+      data-theme={appearance?.theme ?? "light"}
+      style={appearanceStyle(appearance)}
+    >
+      <style>{STYLES}</style>
+      {quote !== null && (
+        <>
+          <p className="pp-amount">
+            {formatTokenAmount(quote)} {quote.asset.toUpperCase()}
+          </p>
+          <p className="pp-subtitle">
+            {formatAmount(quote)} top-up · {networkName(quote.chain_id)}
+          </p>
+        </>
+      )}
+      <StatusLine status={status} quote={quote} now={now} reconnecting={error !== null} />
+      {txHash !== null && quote !== null && <Transaction hash={txHash} chainId={quote.chain_id} />}
+      {status === "waiting" && quote !== null && (
+        <PaymentOptions
+          quote={quote}
+          buttonText={buttonText}
+          now={now}
+          onSent={(hash) => {
+            setTxHash(hash);
+            refresh();
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+function StatusLine({
+  status,
+  quote,
+  now,
+  reconnecting,
+}: {
+  status: CheckoutStatus;
+  quote: ClientQuote | null;
+  now: number;
+  reconnecting: boolean;
+}) {
+  const tone =
+    status === "credited"
+      ? "success"
+      : ["rejected", "expired", "canceled", "error"].includes(status)
+        ? "danger"
+        : "neutral";
+  return (
+    <div className="pp-status" data-tone={tone}>
+      <span role="status" aria-live="polite">
+        {statusMessage(status, quote)}
+        {reconnecting && status !== "error" ? " (reconnecting…)" : ""}
+      </span>
+      {status === "waiting" && quote !== null && (
+        <span className="pp-countdown" aria-label="Time left to pay">
+          {formatCountdown(quote.expires_at, now)}
+        </span>
+      )}
+    </div>
+  );
+}
+
+function statusMessage(status: CheckoutStatus, quote: ClientQuote | null): string {
+  switch (status) {
+    case "loading":
+      return "Loading payment details…";
+    case "waiting":
+      return "Waiting for your payment";
+    case "seen":
+      return quote?.confirmations == null
+        ? "Payment received, waiting for confirmations"
+        : `Payment received, ${quote.confirmations} confirmation${quote.confirmations === 1 ? "" : "s"}`;
+    case "confirming":
+      return "Payment confirmed on chain, crediting…";
+    case "credited":
+      return quote === null ? "Payment credited" : `Payment credited: ${formatAmount(quote)}`;
+    case "rejected":
+      return "This payment cannot be credited. Contact support with your transaction.";
+    case "expired":
+      return "This quote has expired. Do not send funds to this address; start a new top-up.";
+    case "canceled":
+      return "This quote was canceled. Do not send funds to this address.";
+    case "error":
+      return "This payment link is not valid. Start a new top-up.";
+  }
+}
+
+function Transaction({ hash, chainId }: { hash: Hash; chainId: number }) {
+  const url = transactionUrl(chainId, hash);
+  const short = `${hash.slice(0, 10)}…${hash.slice(-8)}`;
+  return (
+    <p className="pp-tx">
+      Transaction sent:{" "}
+      {url === undefined ? (
+        <span className="pp-value" title={hash}>
+          {short}
+        </span>
+      ) : (
+        <a href={url} target="_blank" rel="noreferrer" title={hash}>
+          {short}
+        </a>
+      )}
+    </p>
+  );
+}
+
+function PaymentOptions({
+  quote,
+  now,
+  buttonText,
+  onSent,
+}: {
+  quote: ClientQuote;
+  now: number;
+  buttonText: string;
+  onSent: (hash: Hash) => void;
+}) {
+  const [method, setMethod] = useState<Method>("wallet");
+  const id = useId();
+  const tabs = useRef<(HTMLButtonElement | null)[]>([]);
+  const amount = `${formatTokenAmount(quote)} ${quote.asset.toUpperCase()}`;
+
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const index = METHODS.findIndex((m) => m.id === method);
+    const next =
+      event.key === "ArrowRight"
+        ? (index + 1) % METHODS.length
+        : event.key === "ArrowLeft"
+          ? (index - 1 + METHODS.length) % METHODS.length
+          : event.key === "Home"
+            ? 0
+            : event.key === "End"
+              ? METHODS.length - 1
+              : null;
+    const target = next === null ? undefined : METHODS[next];
+    if (next !== null && target !== undefined) {
+      event.preventDefault();
+      setMethod(target.id);
+      tabs.current[next]?.focus();
+    }
+  };
+
+  return (
+    <>
+      <p className="pp-notice">
+        Send <strong>exactly {amount}</strong> on {networkName(quote.chain_id)} in one transfer
+        before the timer ends. A different amount, or a payment after expiry, is credited at the
+        market price instead of this quote. Exchanges may deduct a withdrawal fee, so the amount
+        that arrives must be exact.
+      </p>
+      <div className="pp-tabs" role="tablist" aria-label="Payment method" onKeyDown={onKeyDown}>
+        {METHODS.map((m, index) => (
+          <button
+            key={m.id}
+            ref={(element) => {
+              tabs.current[index] = element;
+            }}
+            type="button"
+            role="tab"
+            className="pp-tab"
+            id={`${id}-tab-${m.id}`}
+            aria-selected={method === m.id}
+            aria-controls={`${id}-panel-${m.id}`}
+            tabIndex={method === m.id ? 0 : -1}
+            onClick={() => setMethod(m.id)}
+          >
+            {m.label}
+          </button>
+        ))}
+      </div>
+      <div
+        role="tabpanel"
+        id={`${id}-panel-${method}`}
+        aria-labelledby={`${id}-tab-${method}`}
+        tabIndex={0}
+      >
+        {method === "wallet" && <WalletPanel quote={quote} buttonText={buttonText} onSent={onSent} />}
+        {method === "qr" && (
+          <div className="pp-qr-panel">
+            <QrCode value={quote.payment_uri} label={`Payment request for ${amount}`} />
+            <p className="pp-message">
+              Scan with a wallet app that reads payment links, and check that it shows {amount} on{" "}
+              {networkName(quote.chain_id)} before you confirm.
+            </p>
+          </div>
+        )}
+        {method === "manual" && <ManualPanel quote={quote} now={now} />}
+      </div>
+    </>
+  );
+}
+
+type WalletStep =
+  | { kind: "idle" }
+  | { kind: "pending"; wallet: string }
+  | { kind: "failed"; message: string };
+
+function WalletPanel({
+  quote,
+  buttonText,
+  onSent,
+}: {
+  quote: ClientQuote;
+  buttonText: string;
+  onSent: (hash: Hash) => void;
+}) {
+  const [wallets, setWallets] = useState<Wallet[]>([]);
+  const [step, setStep] = useState<WalletStep>({ kind: "idle" });
+  useEffect(() => watchWallets(setWallets), []);
+
+  const pay = async (wallet: Wallet) => {
+    setStep({ kind: "pending", wallet: wallet.info.name });
+    try {
+      onSent(await payWithWallet(wallet.provider, quote));
+      setStep({ kind: "idle" });
+    } catch (error) {
+      setStep({
+        kind: "failed",
+        message: error instanceof WalletError ? error.message : "The payment could not be sent",
+      });
+    }
+  };
+
+  if (wallets.length === 0) {
+    return (
+      <p className="pp-message">
+        No browser wallet found. Scan the QR code with a mobile wallet, or send the payment
+        manually.
+      </p>
+    );
+  }
+  return (
+    <div className="pp-wallets">
+      {wallets.map((wallet) => (
+        <button
+          key={wallet.info.uuid}
+          type="button"
+          className="pp-button"
+          disabled={step.kind === "pending"}
+          onClick={() => void pay(wallet)}
+          aria-label={`${buttonText} (${wallet.info.name})`}
+        >
+          {wallet.info.icon !== "" && <img src={wallet.info.icon} alt="" />}
+          <span>{buttonText}</span>
+          <span className="pp-wallet-name">{wallet.info.name}</span>
+        </button>
+      ))}
+      <p
+        className="pp-message"
+        data-tone={step.kind === "failed" ? "danger" : undefined}
+        aria-live="polite"
+      >
+        {step.kind === "pending" && `Confirm the payment in ${step.wallet}…`}
+        {step.kind === "failed" && step.message}
+      </p>
+    </div>
+  );
+}
+
+function ManualPanel({ quote, now }: { quote: ClientQuote; now: number }) {
+  const token = quoteTransfer(quote).token;
+  return (
+    <dl className="pp-fields">
+      <Field label="Network" value={`${networkName(quote.chain_id)} (chain ID ${quote.chain_id})`} />
+      <Field label={`Token (${quote.asset.toUpperCase()}) contract`} value={token} copy />
+      <Field label="Send to address" value={quote.address} copy />
+      <Field label="Exact amount" value={formatTokenAmount(quote)} copy={tokenAmount(quote)} />
+      <Field label="Time left" value={formatCountdown(quote.expires_at, now)} />
+    </dl>
+  );
+}
+
+/** `copy` adds a copy button, copying `value`, or the given string when it differs from it. */
+function Field({
+  label,
+  value,
+  copy = false,
+}: {
+  label: string;
+  value: string;
+  copy?: boolean | string;
+}) {
+  return (
+    <div className="pp-field">
+      <dt>{label}</dt>
+      <dd>
+        <span className={copy === false ? undefined : "pp-value"}>{value}</span>
+        {copy !== false && (
+          <CopyButton value={typeof copy === "string" ? copy : value} label={label} />
+        )}
+      </dd>
+    </div>
+  );
+}
+
+function CopyButton({ value, label }: { value: string; label: string }) {
+  const [copied, setCopied] = useState<boolean | null>(null);
+  useEffect(() => {
+    if (copied === null) {
+      return;
+    }
+    const timer = setTimeout(() => setCopied(null), 2000);
+    return () => clearTimeout(timer);
+  }, [copied]);
+  const onClick = () => {
+    navigator.clipboard.writeText(value).then(
+      () => setCopied(true),
+      () => setCopied(false),
+    );
+  };
+  return (
+    <button type="button" className="pp-copy" onClick={onClick} aria-label={`Copy ${label}`}>
+      <span aria-live="polite">{copied === null ? "Copy" : copied ? "Copied" : "Copy failed"}</span>
+    </button>
+  );
+}
+
+/** The current time in milliseconds, updated every second while `active`. */
+function useNow(active: boolean): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!active) {
+      return;
+    }
+    const timer = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(timer);
+  }, [active]);
+  return now;
+}

package/src/react/QrCode.tsx

@@ -0,0 +1,39 @@
+import { useMemo } from "react";
+import { encode } from "uqr";
+
+export interface QrCodeProps {
+  value: string;
+  label: string;
+  size?: number;
+}
+
+/** A QR code as an SVG path, one unit per module. */
+export function QrCode({ value, label, size = 208 }: QrCodeProps) {
+  const { path, width } = useMemo(() => {
+    const { data, size: modules } = encode(value, { ecc: "M", border: 2 });
+    let d = "";
+    data.forEach((row, y) => {
+      row.forEach((dark, x) => {
+        if (dark) {
+          d += `M${x} ${y}h1v1h-1z`;
+        }
+      });
+    });
+    return { path: d, width: modules };
+  }, [value]);
+
+  return (
+    <svg
+      className="pp-qr"
+      role="img"
+      aria-label={label}
+      width={size}
+      height={size}
+      viewBox={`0 0 ${width} ${width}`}
+      shapeRendering="crispEdges"
+    >
+      <rect width={width} height={width} fill="#fff" />
+      <path d={path} fill="#000" />
+    </svg>
+  );
+}

package/src/react/appearance.ts

@@ -0,0 +1,114 @@
+import type { CSSProperties } from "react";
+
+/** Theming in the spirit of Stripe's Appearance API: a base theme plus a few variables. */
+export interface Appearance {
+  theme?: "light" | "dark";
+  variables?: {
+    colorPrimary?: string;
+    colorBackground?: string;
+    colorText?: string;
+    colorTextSecondary?: string;
+    colorBorder?: string;
+    colorDanger?: string;
+    colorSuccess?: string;
+    fontFamily?: string;
+    borderRadius?: string;
+  };
+}
+
+const VARIABLES: Record<keyof NonNullable<Appearance["variables"]>, string> = {
+  colorPrimary: "--pp-color-primary",
+  colorBackground: "--pp-color-background",
+  colorText: "--pp-color-text",
+  colorTextSecondary: "--pp-color-text-secondary",
+  colorBorder: "--pp-color-border",
+  colorDanger: "--pp-color-danger",
+  colorSuccess: "--pp-color-success",
+  fontFamily: "--pp-font-family",
+  borderRadius: "--pp-border-radius",
+};
+
+/** The root element's custom properties for `appearance.variables`. */
+export function appearanceStyle(appearance: Appearance | undefined): CSSProperties {
+  const variables = appearance?.variables ?? {};
+  const style: Record<string, string> = {};
+  for (const [name, property] of Object.entries(VARIABLES)) {
+    const value = variables[name as keyof typeof VARIABLES];
+    if (value !== undefined) {
+      style[property] = value;
+    }
+  }
+  return style;
+}
+
+/**
+ * Every rule is scoped under `.pp-root`; the variables can also be set from the page's own CSS on
+ * `.pp-root`.
+ */
+export const STYLES = `
+.pp-root {
+  --pp-color-primary: #0f62fe;
+  --pp-color-background: #ffffff;
+  --pp-color-text: #1a1a1a;
+  --pp-color-text-secondary: #5c5f66;
+  --pp-color-border: #d9dce1;
+  --pp-color-danger: #c62828;
+  --pp-color-success: #1b7f3b;
+  --pp-font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --pp-border-radius: 8px;
+  box-sizing: border-box;
+  max-width: 440px;
+  padding: 20px;
+  border: 1px solid var(--pp-color-border);
+  border-radius: var(--pp-border-radius);
+  background: var(--pp-color-background);
+  color: var(--pp-color-text);
+  font-family: var(--pp-font-family);
+  font-size: 14px;
+  line-height: 1.45;
+}
+.pp-root[data-theme="dark"] {
+  --pp-color-primary: #78a9ff;
+  --pp-color-background: #161616;
+  --pp-color-text: #f4f4f4;
+  --pp-color-text-secondary: #a8a8a8;
+  --pp-color-border: #393939;
+  --pp-color-danger: #ff8389;
+  --pp-color-success: #42be65;
+}
+.pp-root *, .pp-root *::before, .pp-root *::after { box-sizing: inherit; }
+.pp-amount { margin: 0; font-size: 22px; font-weight: 600; }
+.pp-subtitle { margin: 2px 0 16px; color: var(--pp-color-text-secondary); }
+.pp-status { display: flex; gap: 8px; align-items: baseline; justify-content: space-between;
+  margin-bottom: 12px; padding: 10px 12px; border-radius: var(--pp-border-radius);
+  border: 1px solid var(--pp-color-border); }
+.pp-status[data-tone="success"] { border-color: var(--pp-color-success); color: var(--pp-color-success); }
+.pp-status[data-tone="danger"] { border-color: var(--pp-color-danger); color: var(--pp-color-danger); }
+.pp-countdown { font-variant-numeric: tabular-nums; white-space: nowrap; }
+.pp-notice { margin: 0 0 16px; color: var(--pp-color-text-secondary); font-size: 13px; }
+.pp-notice strong { color: var(--pp-color-text); }
+.pp-tabs { display: flex; gap: 4px; border-bottom: 1px solid var(--pp-color-border); margin-bottom: 16px; }
+.pp-tab { appearance: none; border: 0; border-bottom: 2px solid transparent; background: none;
+  color: var(--pp-color-text-secondary); font: inherit; padding: 8px 10px; cursor: pointer; }
+.pp-tab[aria-selected="true"] { color: var(--pp-color-text); border-bottom-color: var(--pp-color-primary); font-weight: 600; }
+.pp-root button:focus-visible, .pp-root a:focus-visible { outline: 2px solid var(--pp-color-primary); outline-offset: 2px; }
+.pp-wallets { display: grid; gap: 8px; }
+.pp-button { display: flex; gap: 10px; align-items: center; justify-content: center; width: 100%;
+  appearance: none; border: 1px solid var(--pp-color-primary); border-radius: var(--pp-border-radius);
+  background: var(--pp-color-primary); color: #fff; font: inherit; font-weight: 600; padding: 10px 14px; cursor: pointer; }
+.pp-button:disabled { opacity: 0.6; cursor: progress; }
+.pp-button img { width: 20px; height: 20px; }
+.pp-wallet-name { font-weight: 400; opacity: 0.85; }
+.pp-message { margin: 10px 0 0; color: var(--pp-color-text-secondary); }
+.pp-message[data-tone="danger"] { color: var(--pp-color-danger); }
+.pp-qr-panel { display: grid; justify-items: center; gap: 10px; text-align: center; }
+.pp-qr { border-radius: 4px; }
+.pp-fields { display: grid; gap: 10px; margin: 0; }
+.pp-field dt { color: var(--pp-color-text-secondary); font-size: 12px; }
+.pp-field dd { display: flex; gap: 8px; align-items: center; margin: 2px 0 0; }
+.pp-value { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; word-break: break-all; }
+.pp-copy { flex: none; appearance: none; border: 1px solid var(--pp-color-border); border-radius: 6px;
+  background: none; color: var(--pp-color-text); font: inherit; font-size: 12px; padding: 3px 8px; cursor: pointer; }
+.pp-tx { margin: 0 0 12px; font-size: 13px; }
+.pp-tx a { color: var(--pp-color-primary); }
+`;

package/src/react/index.ts

@@ -0,0 +1,5 @@
+"use client";
+
+export { Checkout, type CheckoutProps } from "./Checkout.js";
+export { useCheckout, type UseCheckoutOptions, type UseCheckoutResult } from "./useCheckout.js";
+export type { Appearance } from "./appearance.js";

package/src/react/useCheckout.ts

@@ -0,0 +1,48 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { createCheckout, type CheckoutSession, type CheckoutState } from "../checkout.js";
+
+export interface UseCheckoutOptions {
+  clientSecret: string;
+  apiBase: string;
+  pollInterval?: number;
+}
+
+export interface UseCheckoutResult extends CheckoutState {
+  /** Reads the quote now, for example right after the wallet broadcast the payment. */
+  refresh: () => void;
+}
+
+const LOADING: CheckoutState = { status: "loading", quote: null, error: null };
+
+/** Follows a quote's public view for as long as the component is mounted. */
+export function useCheckout({
+  clientSecret,
+  apiBase,
+  pollInterval,
+}: UseCheckoutOptions): UseCheckoutResult {
+  const [current, setCurrent] = useState({ key: "", state: LOADING });
+  const checkout = useRef<CheckoutSession | null>(null);
+  const key = `${apiBase} ${clientSecret}`;
+
+  useEffect(() => {
+    const instance = createCheckout({
+      clientSecret,
+      apiBase,
+      ...(pollInterval === undefined ? {} : { pollInterval }),
+    });
+    checkout.current = instance;
+    const unsubscribe = instance.subscribe((state) => setCurrent({ key, state }));
+    return () => {
+      unsubscribe();
+      instance.destroy();
+      checkout.current = null;
+    };
+  }, [key, clientSecret, apiBase, pollInterval]);
+
+  const refresh = useCallback(() => {
+    void checkout.current?.refresh();
+  }, []);
+
+  // A new client secret starts from `loading`, not from the previous quote's state.
+  return { ...(current.key === key ? current.state : LOADING), refresh };
+}