@phala/pay 0.1.0

package/src/checkout.ts

@@ -0,0 +1,225 @@
+import { parseClientQuote, quoteIdFromClientSecret, type ClientQuote } from "./quote.js";
+
+/**
+ * What the payer sees:
+ * - `loading` until the quote is first read;
+ * - `waiting` for a payment, until `expires_at`;
+ * - `seen` once a transfer is in a block, `confirming` once it is final and being valued;
+ * - `credited`, or `rejected` for a final payment that will not be credited;
+ * - `expired` or `canceled` without a payment;
+ * - `error` when the client secret is not valid.
+ */
+export type CheckoutStatus =
+  | "loading"
+  | "waiting"
+  | "seen"
+  | "confirming"
+  | "credited"
+  | "rejected"
+  | "expired"
+  | "canceled"
+  | "error";
+
+export type CheckoutErrorCode =
+  | "invalid_client_secret"
+  | "rate_limited"
+  | "network_error"
+  | "invalid_response"
+  | "api_error";
+
+export class CheckoutError extends Error {
+  override readonly name = "CheckoutError";
+
+  constructor(
+    readonly code: CheckoutErrorCode,
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+  }
+}
+
+export interface CheckoutState {
+  status: CheckoutStatus;
+  quote: ClientQuote | null;
+  /** The last failed refresh; polling continues after every error but `invalid_client_secret`. */
+  error: CheckoutError | null;
+}
+
+export interface CheckoutOptions {
+  /** 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;
+  /** Milliseconds between status reads; default 3000. */
+  pollInterval?: number;
+  fetch?: typeof globalThis.fetch;
+  /** Current time in milliseconds; for tests. */
+  now?: () => number;
+}
+
+export interface CheckoutSession {
+  getState(): CheckoutState;
+  /** Calls `listener` on every state change; returns the unsubscribe function. */
+  subscribe(listener: (state: CheckoutState) => void): () => void;
+  /** Reads the quote now instead of at the next poll. */
+  refresh(): Promise<void>;
+  /** Stops polling. */
+  destroy(): void;
+}
+
+const DEFAULT_POLL_INTERVAL = 3000;
+const MAX_BACKOFF = 30_000;
+
+export interface RetrieveQuoteOptions {
+  clientSecret: string;
+  apiBase: string;
+  fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * Reads a quote's public view once, as Stripe.js's `retrievePaymentIntent(clientSecret)` does.
+ * Rejects with a `CheckoutError`: `invalid_client_secret` for an unknown quote or secret.
+ */
+export async function retrieveQuote(options: RetrieveQuoteOptions): Promise<ClientQuote> {
+  const quoteId = quoteIdFromClientSecret(options.clientSecret);
+  const base = options.apiBase.replace(/\/+$/, "");
+  const url = `${base}/v1/quotes/${quoteId}?client_secret=${encodeURIComponent(options.clientSecret)}`;
+  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+  // A simple GET with no custom headers, so the browser sends no CORS preflight.
+  const response = await fetchImpl(url, { cache: "no-store", credentials: "omit" });
+  if (response.status === 404) {
+    throw new CheckoutError("invalid_client_secret", "the quote or its client secret is unknown");
+  }
+  if (response.status === 429) {
+    throw new CheckoutError("rate_limited", "too many status requests");
+  }
+  if (!response.ok) {
+    throw new CheckoutError("api_error", `the payment service answered ${response.status}`);
+  }
+  try {
+    return parseClientQuote(await response.json());
+  } catch (cause) {
+    throw new CheckoutError("invalid_response", "unexpected response from the payment service", {
+      cause,
+    });
+  }
+}
+
+/** The payer-facing status of a quote at `nowSeconds`. */
+export function checkoutStatus(quote: ClientQuote, nowSeconds: number): CheckoutStatus {
+  if (quote.payment_status !== "none") {
+    return quote.payment_status;
+  }
+  if (quote.status === "canceled") {
+    return "canceled";
+  }
+  if (quote.status === "expired" || nowSeconds >= quote.expires_at) {
+    return "expired";
+  }
+  return quote.status === "open" ? "waiting" : "confirming";
+}
+
+/**
+ * Follows a quote from the browser by polling its public view until it is credited, rejected,
+ * canceled, or expired by the service. The status turns `expired` at `expires_at` even while the
+ * service, which expires quotes by chain time, still reports the quote open; polling continues
+ * until then, so a payment sent just before expiry still shows.
+ */
+export function createCheckout(options: CheckoutOptions): CheckoutSession {
+  quoteIdFromClientSecret(options.clientSecret);
+  const now = options.now ?? Date.now;
+  const interval = options.pollInterval ?? DEFAULT_POLL_INTERVAL;
+  const listeners = new Set<(state: CheckoutState) => void>();
+
+  let state: CheckoutState = { status: "loading", quote: null, error: null };
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let failures = 0;
+  let destroyed = false;
+  let inFlight: Promise<void> | undefined;
+
+  function setState(next: CheckoutState): void {
+    if (
+      next.status === state.status &&
+      next.error === state.error &&
+      JSON.stringify(next.quote) === JSON.stringify(state.quote)
+    ) {
+      return;
+    }
+    state = next;
+    for (const listener of listeners) {
+      listener(state);
+    }
+  }
+
+  function finished(): boolean {
+    const { status, quote } = state;
+    return (
+      destroyed ||
+      status === "error" ||
+      status === "credited" ||
+      status === "rejected" ||
+      status === "canceled" ||
+      (status === "expired" && quote?.status === "expired")
+    );
+  }
+
+  async function load(): Promise<void> {
+    try {
+      const quote = await retrieveQuote(options);
+      failures = 0;
+      setState({ status: checkoutStatus(quote, now() / 1000), quote, error: null });
+    } catch (cause) {
+      const error =
+        cause instanceof CheckoutError
+          ? cause
+          : new CheckoutError("network_error", "could not reach the payment service", { cause });
+      failures += 1;
+      const quote = state.quote;
+      if (error.code === "invalid_client_secret") {
+        setState({ status: "error", quote, error });
+      } else {
+        setState({
+          status: quote === null ? state.status : checkoutStatus(quote, now() / 1000),
+          quote,
+          error,
+        });
+      }
+    }
+  }
+
+  function refresh(): Promise<void> {
+    inFlight ??= load().finally(() => {
+      inFlight = undefined;
+    });
+    return inFlight;
+  }
+
+  function schedule(): void {
+    if (finished()) {
+      return;
+    }
+    const delay = failures === 0 ? interval : Math.min(interval * 2 ** failures, MAX_BACKOFF);
+    timer = setTimeout(() => {
+      void refresh().then(schedule);
+    }, delay);
+  }
+
+  void refresh().then(schedule);
+
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    refresh,
+    destroy() {
+      destroyed = true;
+      clearTimeout(timer);
+      listeners.clear();
+    },
+  };
+}

package/src/client.ts

@@ -0,0 +1,54 @@
+import {
+  createCheckout,
+  retrieveQuote,
+  type CheckoutOptions,
+  type CheckoutSession,
+} from "./checkout.js";
+import type { ClientQuote } from "./quote.js";
+
+export interface PhalaPayOptions {
+  /** The service origin, for example `https://pay.example.com`. */
+  apiBase: string;
+  fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * The browser client, in the shape of Stripe.js: it holds no key, only the service origin, and
+ * works with the `client_secret` your backend got from `POST /v1/quotes`.
+ *
+ *     const pay = new PhalaPay({ apiBase: "https://pay.example.com" });
+ *     const quote = await pay.retrieveQuote(clientSecret);
+ *     const session = pay.checkout(clientSecret);
+ *     session.subscribe(({ status }) => render(status));
+ */
+export class PhalaPay {
+  readonly apiBase: string;
+  readonly #fetch: typeof globalThis.fetch | undefined;
+
+  constructor(options: PhalaPayOptions) {
+    this.apiBase = options.apiBase;
+    this.#fetch = options.fetch;
+  }
+
+  /** Reads the quote's public view once. */
+  retrieveQuote(clientSecret: string): Promise<ClientQuote> {
+    return retrieveQuote({ clientSecret, apiBase: this.apiBase, ...this.#fetchOption() });
+  }
+
+  /** Follows the quote until it is credited, rejected, canceled, or expired. */
+  checkout(
+    clientSecret: string,
+    options: Pick<CheckoutOptions, "pollInterval"> = {},
+  ): CheckoutSession {
+    return createCheckout({
+      clientSecret,
+      apiBase: this.apiBase,
+      ...options,
+      ...this.#fetchOption(),
+    });
+  }
+
+  #fetchOption(): { fetch?: typeof globalThis.fetch } {
+    return this.#fetch === undefined ? {} : { fetch: this.#fetch };
+  }
+}

package/src/format.ts

@@ -0,0 +1,41 @@
+import { formatUnits } from "viem";
+import type { ClientQuote } from "./quote.js";
+
+/**
+ * The exact token amount to show, grouped for `locale` and without trailing zeros, for example
+ * `1,273.9185`. Every digit is kept: the service rounds a quote to a few decimals.
+ */
+export function formatTokenAmount(quote: ClientQuote, locale?: string): string {
+  const [whole = "0", fraction] = tokenAmount(quote).split(".");
+  const format = new Intl.NumberFormat(locale);
+  const grouped = format.format(BigInt(whole));
+  if (fraction === undefined) {
+    return grouped;
+  }
+  const separator = format.formatToParts(0.5).find((part) => part.type === "decimal")?.value ?? ".";
+  return `${grouped}${separator}${fraction}`;
+}
+
+/** The exact token amount as a plain decimal, for copying into a wallet, for example `1273.9185`. */
+export function tokenAmount(quote: ClientQuote): string {
+  return formatUnits(BigInt(quote.amount_atomic), quote.decimals);
+}
+
+/** The credit in the quote's currency, for example `$25.00`. */
+export function formatAmount(quote: ClientQuote, locale?: string): string {
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: quote.currency.toUpperCase(),
+  }).format(quote.amount / 100);
+}
+
+/** `mm:ss` (or `h:mm:ss`) until `expiresAt` Unix seconds, never negative. */
+export function formatCountdown(expiresAt: number, nowMs: number): string {
+  const total = Math.max(0, Math.ceil(expiresAt - nowMs / 1000));
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const seconds = String(total % 60).padStart(2, "0");
+  return hours > 0
+    ? `${hours}:${String(minutes).padStart(2, "0")}:${seconds}`
+    : `${minutes}:${seconds}`;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export {
+  CheckoutError,
+  checkoutStatus,
+  createCheckout,
+  retrieveQuote,
+  type CheckoutErrorCode,
+  type CheckoutOptions,
+  type CheckoutSession,
+  type CheckoutState,
+  type CheckoutStatus,
+  type RetrieveQuoteOptions,
+} from "./checkout.js";
+export { PhalaPay, type PhalaPayOptions } from "./client.js";
+export { knownChain, networkName, transactionUrl } from "./chains.js";
+export { formatAmount, formatCountdown, formatTokenAmount, tokenAmount } from "./format.js";
+export { quoteTransfer, type TokenTransfer } from "./payment.js";
+export { parseClientQuote, quoteIdFromClientSecret, type ClientQuote } from "./quote.js";
+export {
+  INJECTED_WALLET_UUID,
+  WalletError,
+  payWithWallet,
+  watchWallets,
+  type EthereumProvider,
+  type Wallet,
+  type WalletErrorCode,
+  type WalletInfo,
+} from "./wallet.js";

package/src/payment.ts

@@ -0,0 +1,52 @@
+import { getAddress, isAddressEqual, type Address } from "viem";
+import type { ClientQuote } from "./quote.js";
+
+/** An ERC-20 transfer request, as EIP-681 encodes it and a wallet sends it. */
+export interface TokenTransfer {
+  chainId: number;
+  /** The token contract. */
+  token: Address;
+  /** The recipient: the quote's deposit address. */
+  to: Address;
+  /** Token amount in the smallest unit. */
+  amount: bigint;
+}
+
+const EIP681_TRANSFER =
+  /^ethereum:(?:pay-)?(0x[0-9a-fA-F]{40})@([1-9][0-9]*)\/transfer\?([^#]*)$/;
+
+/**
+ * Reads the token transfer from a quote's EIP-681 `payment_uri`, and checks that it pays exactly
+ * the quote's `amount_atomic` to the quote's `address` on the quote's chain, so the wallet, the QR
+ * code, and the manual instructions all state the same payment.
+ */
+export function quoteTransfer(quote: ClientQuote): TokenTransfer {
+  const match = EIP681_TRANSFER.exec(quote.payment_uri);
+  const params = new URLSearchParams(match?.[3] ?? "");
+  const to = params.get("address");
+  const amount = params.get("uint256");
+  if (
+    match?.[1] === undefined ||
+    match[2] === undefined ||
+    to === null ||
+    !/^0x[0-9a-fA-F]{40}$/.test(to) ||
+    amount === null ||
+    !/^\d+$/.test(amount)
+  ) {
+    throw new TypeError("payment_uri is not an EIP-681 ERC-20 transfer");
+  }
+  const transfer: TokenTransfer = {
+    chainId: Number(match[2]),
+    token: getAddress(match[1]),
+    to: getAddress(to),
+    amount: BigInt(amount),
+  };
+  if (
+    transfer.chainId !== quote.chain_id ||
+    !isAddressEqual(transfer.to, getAddress(quote.address)) ||
+    transfer.amount !== BigInt(quote.amount_atomic)
+  ) {
+    throw new TypeError("payment_uri does not match the quote");
+  }
+  return transfer;
+}

package/src/quote.ts

@@ -0,0 +1,96 @@
+/**
+ * The public view of a quote, as `GET /v1/quotes/{id}?client_secret=…` returns it to a browser.
+ */
+export interface ClientQuote {
+  id: string;
+  object: "quote";
+  /** `open` until a matching payment completes it, it expires by chain time, or it is canceled. */
+  status: "open" | "complete" | "expired" | "canceled";
+  /** Credit in the currency's minor unit (US cents). */
+  amount: number;
+  currency: string;
+  /** The token's code, for example `pha`. */
+  asset: string;
+  decimals: number;
+  chain_id: number;
+  /** The exact token amount to send, in the token's smallest unit, as a decimal string. */
+  amount_atomic: string;
+  /** The quote's single-use deposit address. */
+  address: string;
+  /** The EIP-681 payment request: token transfer of `amount_atomic` to `address`. */
+  payment_uri: string;
+  /** Unix seconds; after this the address must no longer be shown. */
+  expires_at: number;
+  /**
+   * `seen` before finality (a reorg can remove it), `confirming` while a final payment is valued
+   * and screened, `credited` once it is credited, `rejected` when it is final but will not be.
+   */
+  payment_status: "none" | "seen" | "confirming" | "credited" | "rejected";
+  /** Block confirmations while `payment_status` is `seen`, otherwise `null`. */
+  confirmations: number | null;
+}
+
+const QUOTE_STATUSES = ["open", "complete", "expired", "canceled"] as const;
+const PAYMENT_STATUSES = ["none", "seen", "confirming", "credited", "rejected"] as const;
+
+/** Returns the quote id a client secret belongs to (`qt_…_secret_…`), or throws. */
+export function quoteIdFromClientSecret(clientSecret: string): string {
+  const match = /^(qt_[0-9a-f]+)_secret_[0-9a-f]+$/.exec(clientSecret);
+  if (match?.[1] === undefined) {
+    throw new TypeError("clientSecret is not a quote client secret");
+  }
+  return match[1];
+}
+
+/** Validates a response body against the public quote view; throws on anything else. */
+export function parseClientQuote(value: unknown): ClientQuote {
+  if (typeof value !== "object" || value === null) {
+    throw new TypeError("quote response is not an object");
+  }
+  const v = value as Record<string, unknown>;
+  const confirmations = v["confirmations"];
+  if (
+    typeof v["id"] !== "string" ||
+    v["object"] !== "quote" ||
+    !oneOf(v["status"], QUOTE_STATUSES) ||
+    !isSafeInteger(v["amount"]) ||
+    typeof v["currency"] !== "string" ||
+    typeof v["asset"] !== "string" ||
+    !isSafeInteger(v["decimals"]) ||
+    !isSafeInteger(v["chain_id"]) ||
+    typeof v["amount_atomic"] !== "string" ||
+    !/^\d+$/.test(v["amount_atomic"]) ||
+    typeof v["address"] !== "string" ||
+    !/^0x[0-9a-fA-F]{40}$/.test(v["address"]) ||
+    typeof v["payment_uri"] !== "string" ||
+    !isSafeInteger(v["expires_at"]) ||
+    !oneOf(v["payment_status"], PAYMENT_STATUSES) ||
+    !(confirmations === null || confirmations === undefined || isSafeInteger(confirmations))
+  ) {
+    throw new TypeError("quote response does not match the public quote view");
+  }
+  return {
+    id: v["id"],
+    object: "quote",
+    status: v["status"],
+    amount: v["amount"],
+    currency: v["currency"],
+    asset: v["asset"],
+    decimals: v["decimals"],
+    chain_id: v["chain_id"],
+    amount_atomic: v["amount_atomic"],
+    address: v["address"],
+    payment_uri: v["payment_uri"],
+    expires_at: v["expires_at"],
+    payment_status: v["payment_status"],
+    confirmations: confirmations ?? null,
+  };
+}
+
+function oneOf<T extends string>(value: unknown, allowed: readonly T[]): value is T {
+  return typeof value === "string" && (allowed as readonly string[]).includes(value);
+}
+
+function isSafeInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value);
+}