SendFax.sh in a React / Next.js web app

npm install sendfax

                        browser (public code)
                              |
                     your Next.js origin
                              |
     +------------------------+------------------------+
     |  app/api/fax/*  route handlers (server)          |
     |  proxy to https://sendfax.sh -- same-origin for  |
     |  the browser, and the ONLY place a wallet key    |
     |  or a rate limit could live                      |
     +------------------------+------------------------+
                              |
                        sendfax.sh API

FLOW A -- no wallet (Stripe hosted Checkout)
  <input type=file> / drop zone
        +-> POST /api/fax/upload    --proxy--> POST /api/v1/uploads
        |     +-> { id, pageCount, amountCents }
        +-> POST /api/fax/checkout  --proxy--> POST /api/v1/checkout
        |     +-> { url }
        +-> window.location.href = url          [full-page redirect to Stripe]
        +-> user returns to https://sendfax.sh/f/{id}?paid=1  (NOT your site)
        +-> meanwhile/afterwards: poll GET /api/fax/status/{id}

FLOW B -- wallet (pay the 402 in the browser)
  <input type=file>
        +-> POST /api/fax/send      --proxy--> POST /api/v1/faxes
        |     +-> 402 + x-payment-deposit-*  (proxy must FORWARD these headers)
        +-> wagmi writeContract: exact USDC transfer on Base
        +-> POST /api/fax/send      (identical body) ... retry ... -> 202
        +-> poll GET /api/fax/status/{id} with SWR / React Query

// app/api/fax/upload/route.ts -- proxies POST /api/v1/uploads
export const runtime = "edge"          // or "nodejs"; both work

const SENDFAX = "https://sendfax.sh"

export async function POST(request: Request): Promise<Response> {
  // Stream the multipart body straight through. Do not re-parse it: the bytes
  // must reach SendFax unchanged, and re-encoding is a chance to corrupt them.
  const upstream = await fetch(`${SENDFAX}/api/v1/uploads`, {
    method: "POST",
    headers: { "content-type": request.headers.get("content-type") ?? "" },
    body: request.body,
    // @ts-expect-error -- required by undici to stream a request body
    duplex: "half"
  })

  return new Response(upstream.body, {
    status: upstream.status,
    headers: {
      "content-type": upstream.headers.get("content-type") ?? "application/json"
    }
  })
}

// app/api/fax/checkout/route.ts -- proxies POST /api/v1/checkout
export async function POST(request: Request): Promise<Response> {
  const body = await request.text()
  const upstream = await fetch("https://sendfax.sh/api/v1/checkout", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body
  })
  return new Response(await upstream.text(), {
    status: upstream.status,
    headers: { "content-type": upstream.headers.get("content-type") ?? "application/json" }
  })
}

// app/api/fax/status/[id]/route.ts -- proxies GET /api/v1/faxes/{id}
export async function GET(
  _request: Request,
  { params }: { params: Promise<{ id: string }> }
): Promise<Response> {
  const { id } = await params
  const upstream = await fetch(
    `https://sendfax.sh/api/v1/faxes/${encodeURIComponent(id)}`,
    { cache: "no-store" }
  )
  return new Response(await upstream.text(), {
    status: upstream.status,
    headers: {
      "content-type": upstream.headers.get("content-type") ?? "application/json",
      // Status changes every couple of seconds; never let a CDN hold it.
      "cache-control": "no-store"
    }
  })
}

// app/api/fax/send/route.ts -- proxies POST /api/v1/faxes
const FORWARD_HEADERS = [
  "www-authenticate",
  "payment-required",
  "payment-receipt",
  "x-payment-deposit-mode",
  "x-payment-deposit-network",
  "x-payment-deposit-address",
  "x-payment-deposit-token",
  "x-payment-deposit-amount",
  "x-payment-deposit-amount-micros",
  "x-payment-deposit-payment-intent",
  "x-payment-deposit-instructions"
] as const

export async function POST(request: Request): Promise<Response> {
  const upstream = await fetch("https://sendfax.sh/api/v1/faxes", {
    method: "POST",
    headers: { "content-type": request.headers.get("content-type") ?? "" },
    body: request.body,
    // @ts-expect-error -- required by undici to stream a request body
    duplex: "half"
  })

  const headers = new Headers({
    "content-type": upstream.headers.get("content-type") ?? "application/json"
  })
  for (const name of FORWARD_HEADERS) {
    const value = upstream.headers.get(name)
    if (value) headers.set(name, value)
  }

  return new Response(upstream.body, { status: upstream.status, headers })
}

"use client"
import { useCallback, useState } from "react"

const MAX_BYTES = 20 * 1024 * 1024     // lib/domain/pricing.ts:42

export function PdfPicker({ onPick }: { onPick: (file: File) => void }) {
  const [over, setOver] = useState(false)
  const [error, setError] = useState<string | null>(null)

  const accept = useCallback(
    (file: File | undefined) => {
      if (!file) return
      if (file.type !== "application/pdf") return setError("That is not a PDF.")
      if (file.size > MAX_BYTES) return setError("PDFs must be 20 MB or smaller.")
      setError(null)
      onPick(file)
    },
    [onPick]
  )

  return (
    <div
      onDragOver={(e) => { e.preventDefault(); setOver(true) }}
      onDragLeave={() => setOver(false)}
      onDrop={(e) => { e.preventDefault(); setOver(false); accept(e.dataTransfer.files[0]) }}
      data-over={over}
    >
      <label>
        Choose a PDF
        <input
          type="file"
          accept="application/pdf,.pdf"
          onChange={(e) => accept(e.target.files?.[0])}
          hidden
        />
      </label>
      {error && <p role="alert">{error}</p>}
    </div>
  )
}

"use client"
import { useState } from "react"

type Upload = { id: string; pageCount: number; amountCents: number }

export function CardCheckout({ file, to }: { file: File; to: string }) {
  const [busy, setBusy] = useState(false)
  const [quote, setQuote] = useState<Upload | null>(null)
  const [error, setError] = useState<string | null>(null)

  async function priceIt() {
    const form = new FormData()
    form.append("document", file)          // browsers set the filename from the File
    form.append("to", to)

    const res = await fetch("/api/fax/upload", { method: "POST", body: form })
    if (!res.ok) {
      const problem = await res.json().catch(() => null)
      // 422 "Unsupported destination" arrives here, before any payment.
      throw new Error(problem?.detail ?? `Upload failed (${res.status})`)
    }
    return (await res.json()) as Upload
  }

  async function pay() {
    setBusy(true)
    setError(null)
    try {
      const up = quote ?? (await priceIt())
      setQuote(up)

      const res = await fetch("/api/fax/checkout", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ id: up.id })
      })
      if (!res.ok) throw new Error(`Checkout failed (${res.status})`)
      const { url } = (await res.json()) as { url: string }

      // Full-page navigation. NOT router.push -- this is a different origin,
      // and NOT window.open, which popup blockers eat when it is not in the
      // direct call stack of a click.
      window.location.href = url
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err))
      setBusy(false)
    }
  }

  return (
    <div>
      {quote && (
        <p>
          {quote.pageCount} page(s) -- ${(quote.amountCents / 100).toFixed(2)}
        </p>
      )}
      <button onClick={pay} disabled={busy}>
        {busy ? "Redirecting..." : "Pay with card"}
      </button>
      {error && <p role="alert">{error}</p>}
    </div>
  )
}

npm install wagmi viem @tanstack/react-query

// app/providers.tsx
"use client"
import { WagmiProvider, createConfig, http } from "wagmi"
import { base } from "wagmi/chains"
import { injected, walletConnect } from "wagmi/connectors"
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"

const config = createConfig({
  chains: [base],
  connectors: [
    injected(),
    walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID! })
  ],
  transports: { [base.id]: http() },
  ssr: true                 // Next.js App Router: avoids a hydration mismatch
})

const queryClient = new QueryClient()

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    </WagmiProvider>
  )
}

export type DepositQuote = {
  network: string
  address: `0x${string}`
  token: `0x${string}`
  amountDisplay: string      // "0.050000" -- for the UI
  amountBaseUnits: bigint    // 50000n -- for the transfer
  paymentIntent: string      // "pi_..." -- persist this
}

const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as const

/** Deposit headers defined at lib/payments/gate.ts:219-234. */
function readDeposit(res: Response): DepositQuote | null {
  const h = res.headers
  const address = h.get("x-payment-deposit-address")
  const micros = h.get("x-payment-deposit-amount-micros")
  if (!address || !micros) return null
  return {
    network: h.get("x-payment-deposit-network") ?? "base",
    address: address as `0x${string}`,
    token: (h.get("x-payment-deposit-token") ?? USDC_BASE) as `0x${string}`,
    amountDisplay: h.get("x-payment-deposit-amount") ?? "",
    // Integer base units. Deposit mode matches EXACTLY, so never round-trip the
    // decimal display string through a float. lib/payments/deposit.ts:16-18
    amountBaseUnits: BigInt(micros),
    paymentIntent: h.get("x-payment-deposit-payment-intent") ?? ""
  }
}

"use client"
import { useState } from "react"
import { useAccount, useChainId, useSwitchChain, useWriteContract } from "wagmi"
import { base } from "wagmi/chains"
import { erc20Abi } from "viem"

type Receipt = { id: string; pageCount: number; amountUsdMicros: number; statusUrl: string }

export function useWalletFax() {
  const { address, isConnected } = useAccount()
  const chainId = useChainId()
  const { switchChainAsync } = useSwitchChain()
  const { writeContractAsync } = useWriteContract()
  const [phase, setPhase] = useState<string>("idle")

  async function send(file: File, to: string): Promise<Receipt> {
    if (!isConnected || !address) throw new Error("Connect a wallet first.")
    if (chainId !== base.id) await switchChainAsync({ chainId: base.id })

    // Buffer once. Every retry must send byte-identical content, and a File
    // read twice from a picker is not guaranteed to be the same object.
    const bytes = new Uint8Array(await file.arrayBuffer())
    const buildBody = () => {
      const form = new FormData()
      form.append("document", new Blob([bytes], { type: "application/pdf" }), file.name)
      form.append("to", to)
      return form
    }

    // 1. Unpaid submit. A 422 for an unsupported destination lands here,
    //    before any address is minted and before any money moves.
    setPhase("pricing")
    let res = await fetch("/api/fax/send", { method: "POST", body: buildBody() })
    if (res.status === 202) return (await res.json()) as Receipt
    if (res.status !== 402) {
      const problem = await res.json().catch(() => null)
      throw new Error(problem?.detail ?? `Request failed (${res.status})`)
    }

    const quote = readDeposit(res)
    if (!quote) throw new Error("402 carried no deposit headers.")

    // 2. Check the charge against expectations BEFORE asking for a signature.
    if (quote.network !== "base") throw new Error(`unexpected network ${quote.network}`)
    if (quote.token.toLowerCase() !== USDC_BASE.toLowerCase())
      throw new Error("unexpected token")
    if (quote.amountBaseUnits > 5_000_000n) throw new Error("charge over my ceiling")

    setPhase(`confirm ${quote.amountDisplay} USDC`)
    localStorage.setItem("sendfax:pendingPI", quote.paymentIntent)

    await writeContractAsync({
      abi: erc20Abi,
      address: quote.token,                 // the USDC contract
      functionName: "transfer",
      args: [quote.address, quote.amountBaseUnits]   // the deposit address
    })

    // 3. Retry the identical request until 202. Same address for ~15 minutes
    //    (lib/payments/deposit.ts:50), so this is safe to repeat and is not a
    //    second charge.
    setPhase("settling")
    const deadline = Date.now() + 14 * 60_000
    let delay = 3000
    while (Date.now() < deadline) {
      await new Promise((r) => setTimeout(r, delay))
      res = await fetch("/api/fax/send", { method: "POST", body: buildBody() })
      if (res.status === 202) {
        setPhase("accepted")
        return (await res.json()) as Receipt
      }
      delay = Math.min(Math.round(delay * 1.5), 15_000)
    }
    throw new Error("Deposit not detected within the 15-minute window.")
  }

  return { send, phase }
}

"use client"
import useSWR from "swr"

type FaxPublic = {
  id: string
  status: "awaiting_payment" | "paid" | "queued" | "media_processed"
        | "sending" | "delivered" | "failed" | "expired"
  pageCount: number
  toMasked: string
  failureReason: string | null
  createdAt: number
  terminalAt: number | null
}

const TERMINAL = ["delivered", "failed", "expired"]   // sdk/src/types.ts:27

export function useFaxStatus(id: string | null) {
  return useSWR<FaxPublic>(
    id ? `/api/fax/status/${id}` : null,
    (url: string) => fetch(url).then((r) => r.json()),
    {
      // Stop polling once terminal; SWR passes the latest data to the interval fn.
      refreshInterval: (data) => (data && TERMINAL.includes(data.status) ? 0 : 2000),
      revalidateOnFocus: true
    }
  )
}

import { useQuery } from "@tanstack/react-query"

export function useFaxStatus(id: string | null) {
  return useQuery<FaxPublic>({
    queryKey: ["fax", id],
    queryFn: () => fetch(`/api/fax/status/${id}`).then((r) => r.json()),
    enabled: Boolean(id),
    refetchInterval: (query) =>
      query.state.data && TERMINAL.includes(query.state.data.status) ? false : 2000
  })
}

function FaxStatus({ id }: { id: string }) {
  const { data } = useFaxStatus(id)
  if (!data) return <p>Starting...</p>
  return (
    <div>
      <p>{label(data.status)}</p>
      {data.status === "failed" && <p role="alert">{data.failureReason}</p>}
      <a href={`https://sendfax.sh/f/${id}`} target="_blank" rel="noreferrer">
        Open the status page
      </a>
    </div>
  )
}

const label = (s: FaxPublic["status"]) =>
  ({
    awaiting_payment: "Waiting for payment",
    paid: "Paid -- queueing",
    queued: "Queued at the carrier",
    media_processed: "Document processed",
    sending: "Dialing",
    delivered: "Delivered",
    failed: "Failed",
    expired: "Expired"
  })[s]

// app/api/v1/faxes/route.ts, app/api/v1/faxes/[id]/route.ts in YOUR app,
// each proxying the same path upstream. Then:
import { SendFax, PaymentRequiredError } from "sendfax"

const client = new SendFax({ baseUrl: window.location.origin })

const client = new SendFax({
  baseUrl: window.location.origin,
  fetch: (input, init) => {
    const url = new URL(typeof input === "string" ? input : input.toString())
    url.pathname = url.pathname
      .replace(/^\/api\/v1\/faxes\/(.+)$/, "/api/fax/status/$1")
      .replace(/^\/api\/v1\/faxes$/, "/api/fax/send")
    return fetch(url, init)
  }
})

try {
  const receipt = await client.send({ to, document: file })   // a File is a Blob
  return receipt.id
} catch (err) {
  if (!(err instanceof PaymentRequiredError)) throw err
  // No handler configured -> this is the fork, not a failure.
  const up = await fetch("/api/fax/upload", { method: "POST", body: form })
    .then((r) => r.json())
  const { url } = await fetch("/api/fax/checkout", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ id: up.id })
  }).then((r) => r.json())
  window.location.href = url
}