Sending a fax with TypeScript

npm install sendfax        # or: bun add sendfax / deno add npm:sendfax

FLOW A -- no wallet
  new SendFax()                       [no PaymentHandler]
    +-> send() throws PaymentRequiredError   <-- the fork, not a failure
    +-> POST /api/v1/uploads   (plain fetch; the SDK has no upload method)
    +-> POST /api/v1/checkout  -> { url }
    +-> open the URL in a browser
    +-> client.waitForDelivery(id)  ->  delivered

FLOW B -- wallet
  new SendFax({ fetch: capturing, payment: handler })
    +-> send() -> 402 -> handler pays -> retry
    |     handler: viem sends exact USDC on Base to the deposit address
    +-> outer loop re-calls send() until 202   (see "One retry is not enough")
    +-> client.waitForDelivery(id)  ->  delivered

import { SendFax } from "sendfax"
import { readFile } from "node:fs/promises"

const client = new SendFax({ payment: myHandler })   // see below

const receipt = await client.send({
  to: "+14155550123",
  document: await readFile("invoice.pdf")            // Uint8Array | ArrayBuffer | Blob
})
// { id, pageCount, amountUsdMicros, statusUrl }

const fax = await client.waitForDelivery(receipt.id, {
  onStatus: (f) => console.log(f.status)             // queued -> sending -> delivered
})
console.log(fax.status)                              // "delivered"

import { SendFax, PaymentRequiredError } from "sendfax"
import { readFile } from "node:fs/promises"

const BASE = "https://sendfax.sh"
const client = new SendFax()                 // no handler -> Flow A

async function sendWithCard(path: string, to: string) {
  const bytes = await readFile(path)

  try {
    const receipt = await client.send({ to, document: bytes })
    return receipt.id                        // a handler was configured after all
  } catch (err) {
    if (!(err instanceof PaymentRequiredError)) throw err

    // --- the fork ---------------------------------------------------------
    const form = new FormData()
    form.append("document", new Blob([bytes], { type: "application/pdf" }), "document.pdf")
    form.append("to", to)

    const up = await fetch(`${BASE}/api/v1/uploads`, { method: "POST", body: form })
    if (!up.ok) throw await problem(up)
    // amountCents is max(50, ceil(pages * 5)). lib/domain/pricing.ts:23
    const { id, pageCount, amountCents } =
      (await up.json()) as { id: string; pageCount: number; amountCents: number }

    const co = await fetch(`${BASE}/api/v1/checkout`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ id })
    })
    if (!co.ok) throw await problem(co)
    const { url } = (await co.json()) as { url: string }

    console.log(`${pageCount} page(s), $${(amountCents / 100).toFixed(2)}`)
    console.log(`Pay here: ${url}`)
    return id
  }
}

async function problem(res: Response) {
  const body = (await res.json().catch(() => null)) as { detail?: string; title?: string } | null
  return new Error(body?.detail ?? body?.title ?? `HTTP ${res.status}`)
}

const id = await sendWithCard("invoice.pdf", "+14155550123")
const fax = await client.waitForDelivery(id, { timeoutMs: 600_000 })

npm install viem

const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as const

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

/** Captures what the SDK's challenge parser drops. gate.ts:219-234 */
export function depositCapture() {
  let latest: DepositQuote | null = null

  const capturingFetch: typeof fetch = async (input, init) => {
    const res = await fetch(input, init)
    if (res.status === 402) {
      const h = res.headers
      const address = h.get("x-payment-deposit-address")
      const micros = h.get("x-payment-deposit-amount-micros")
      if (address && micros) {
        latest = {
          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. deposit.ts:16-18
          amountBaseUnits: BigInt(micros),
          paymentIntent: h.get("x-payment-deposit-payment-intent") ?? ""
        }
      }
    }
    return res
  }

  return { capturingFetch, quote: () => latest }
}

import { createWalletClient, http, encodeFunctionData, erc20Abi } from "viem"
import { privateKeyToAccount } from "viem/accounts"
import { base } from "viem/chains"
import type { PaymentHandler } from "sendfax"

export function depositHandler(
  quoteOf: () => DepositQuote | null,
  opts: { privateKey: `0x${string}`; maxMicros: bigint; rpcUrl?: string }
): PaymentHandler {
  const account = privateKeyToAccount(opts.privateKey)
  const wallet = createWalletClient({ account, chain: base, transport: http(opts.rpcUrl) })

  let fundedIntent: string | null = null
  let txHash = "pending"

  return async () => {
    const quote = quoteOf()
    if (!quote) throw new Error("402 carried no x-payment-deposit-* headers")

    // The outer loop calls send() repeatedly, so the handler runs more than
    // once. Pay per PaymentIntent, not per attempt.
    if (fundedIntent !== quote.paymentIntent) {
      // Enforce limits in code. The amount arrived over the wire from a remote
      // party -- which is still true when the remote party is us.
      if (quote.network !== "base") throw new Error(`unexpected network ${quote.network}`)
      if (quote.token.toLowerCase() !== USDC_BASE.toLowerCase())
        throw new Error(`unexpected token ${quote.token}`)
      if (quote.amountBaseUnits > opts.maxMicros)
        throw new Error(`charge ${quote.amountDisplay} exceeds the configured ceiling`)

      txHash = await wallet.sendTransaction({
        to: quote.token,                                 // the USDC contract
        data: encodeFunctionData({
          abi: erc20Abi,
          functionName: "transfer",
          args: [quote.address, quote.amountBaseUnits]   // the deposit address
        })
      })
      fundedIntent = quote.paymentIntent
    }

    // Deposit mode has no credential: the retry itself settles, and the gate
    // never reads request headers on this path. Informational only.
    return { headerName: "x-sendfax-deposit-tx", headerValue: txHash }
  }
}

import { SendFax, PaymentRequiredError, type SendFaxResult } from "sendfax"

export async function sendWithWallet(
  document: Uint8Array,
  to: string,
  opts: { privateKey: `0x${string}`; maxMicros?: bigint }
): Promise<SendFaxResult> {
  const { capturingFetch, quote } = depositCapture()
  const client = new SendFax({
    fetch: capturingFetch,
    payment: depositHandler(quote, {
      privateKey: opts.privateKey,
      maxMicros: opts.maxMicros ?? 1_000_000n         // $1.00
    })
  })

  // Stay inside the 15-minute deposit reuse window.
  const deadline = Date.now() + 14 * 60_000
  let delay = 3000

  while (Date.now() < deadline) {
    try {
      return await client.send({ to, document })       // 202
    } catch (err) {
      if (!(err instanceof PaymentRequiredError)) throw err   // 422 etc: give up
      await new Promise((r) => setTimeout(r, delay))
      delay = Math.min(Math.round(delay * 1.5), 15_000)
    }
  }
  throw new Error("deposit not detected within the 15-minute window")
}

const receipt = await sendWithWallet(await readFile("invoice.pdf"), "+14155550123", {
  privateKey: process.env.SENDFAX_PRIVATE_KEY as `0x${string}`
})
const fax = await new SendFax().waitForDelivery(receipt.id, {
  onStatus: (f) => console.error(f.status)
})

import { SendFax, mockPaymentHandler } from "sendfax"

const dev = process.env.NODE_ENV !== "production"
const client = new SendFax({
  baseUrl: dev ? "http://localhost:3001" : "https://sendfax.sh",
  payment: dev ? mockPaymentHandler() : realHandler
})

import {
  PaymentRequiredError,
  InvalidDestinationError,
  InvalidDocumentError,
  NotFoundError,
  FaxFailedError,
  ApiError
} from "sendfax"

try {
  await client.send({ to, document })
} catch (err) {
  if (err instanceof InvalidDestinationError) {
    // 422. Not E.164, or outside US/CA/MX/PM. `err.problem.detail` is the
    // exact sentence to show. lib/domain/fax.ts:84-85
    console.error(err.problem?.detail ?? err.message)
  } else if (err instanceof InvalidDocumentError) {
    // 400 / 413 / 422: not a PDF, encrypted, zero pages, or over 20 MB.
  } else if (err instanceof PaymentRequiredError) {
    // No handler, or the handler could not satisfy the challenge.
    console.error(err.challenge.amountBaseUnits, err.challenge.tokenAddress)
  } else if (err instanceof ApiError) {
    // Any other non-2xx: inspect err.status / err.problem.
  }
}

import { readFile } from "node:fs/promises"

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

type Receipt = { id: string; pageCount: number; amountUsdMicros: number; statusUrl: string }
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"]

async function sendFax(path: string, to: string, pay: (q: Quote) => Promise<void>) {
  const bytes = await readFile(path)

  // Build fresh each attempt; the BYTES must be identical, the envelope need not be.
  const body = () => {
    const form = new FormData()
    form.append("document", new Blob([bytes], { type: "application/pdf" }), "document.pdf")
    form.append("to", to)
    return form
  }

  let res = await fetch(`${BASE}/api/v1/faxes`, { method: "POST", body: body() })
  if (res.status === 202) return (await res.json()) as Receipt
  if (res.status !== 402) throw await problem(res)

  const quote = readQuote(res)
  if (!quote) throw new Error("402 carried no deposit headers")
  await pay(quote)

  const deadline = Date.now() + 14 * 60_000
  let delay = 3000
  while (Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, delay))
    res = await fetch(`${BASE}/api/v1/faxes`, { method: "POST", body: body() })
    if (res.status === 202) return (await res.json()) as Receipt
    if (res.status !== 402) throw await problem(res)
    delay = Math.min(Math.round(delay * 1.5), 15_000)
  }
  throw new Error("deposit not detected within the 15-minute window")
}

type Quote = { address: string; token: string; network: string; amountBaseUnits: bigint }

function readQuote(res: Response): Quote | 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 {
    address,
    token: h.get("x-payment-deposit-token") ?? "",
    network: h.get("x-payment-deposit-network") ?? "base",
    amountBaseUnits: BigInt(micros)
  }
}

async function waitForDelivery(id: string, timeoutMs = 300_000): Promise<FaxPublic> {
  const deadline = Date.now() + timeoutMs
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/v1/faxes/${encodeURIComponent(id)}`)
    if (!res.ok) throw await problem(res)
    const fax = (await res.json()) as FaxPublic
    if (TERMINAL.includes(fax.status)) return fax
    await new Promise((r) => setTimeout(r, 2000))
  }
  throw new Error(`timed out waiting for ${id}`)
}

async function problem(res: Response) {
  const b = (await res.json().catch(() => null)) as { detail?: string; title?: string } | null
  return new Error(b?.detail ?? b?.title ?? `HTTP ${res.status}`)
}

#!/usr/bin/env bun
/**
 * sendfax <file.pdf> <+E164>
 * Exit: 0 delivered - 2 usage - 3 bad destination - 4 bad document
 *       5 payment not settled - 6 delivery failed - 1 other
 */
import { readFile } from "node:fs/promises"
import {
  SendFax,
  PaymentRequiredError,
  InvalidDestinationError,
  InvalidDocumentError,
  FaxFailedError,
  mockPaymentHandler
} from "sendfax"

const API = process.env.SENDFAX_API ?? "https://sendfax.sh"
const MAX = BigInt(Math.round(Number(process.env.SENDFAX_MAX_USD ?? "1.00") * 1_000_000))

const [file, to] = process.argv.slice(2)
if (!file || !to) {
  console.error("usage: sendfax <file.pdf> <+E164>")
  process.exit(2)
}

const bytes = await readFile(file)
const { capturingFetch, quote } = depositCapture()

const payment =
  process.env.SENDFAX_MOCK === "1"
    ? mockPaymentHandler()
    : process.env.SENDFAX_PRIVATE_KEY
      ? depositHandler(quote, {
          privateKey: process.env.SENDFAX_PRIVATE_KEY as `0x${string}`,
          maxMicros: MAX,
          rpcUrl: process.env.SENDFAX_RPC_URL
        })
      : undefined

const client = new SendFax({ baseUrl: API, fetch: capturingFetch, payment })

const deadline = Date.now() + 14 * 60_000
let delay = 3000
let receipt

while (!receipt) {
  try {
    receipt = await client.send({ to, document: bytes })
  } catch (err) {
    if (err instanceof InvalidDestinationError) {
      console.error(err.problem?.detail ?? err.message)
      process.exit(3)
    }
    if (err instanceof InvalidDocumentError) {
      console.error(err.problem?.detail ?? err.message)
      process.exit(4)
    }
    if (!(err instanceof PaymentRequiredError)) throw err
    if (!payment) {
      const q = quote()
      console.error(
        q
          ? `payment required: send exactly ${q.amountDisplay} USDC on ${q.network} to ${q.address}`
          : `payment required: ${err.challenge.amountBaseUnits} base units`
      )
      process.exit(5)
    }
    if (Date.now() > deadline) {
      console.error("deposit not detected within the 15-minute window")
      process.exit(5)
    }
    await new Promise((r) => setTimeout(r, delay))
    delay = Math.min(Math.round(delay * 1.5), 15_000)
  }
}

console.error(
  `accepted ${receipt.id} (${receipt.pageCount} page(s), ` +
    `$${(receipt.amountUsdMicros / 1_000_000).toFixed(2)})`
)
console.error(receipt.statusUrl)

try {
  const fax = await client.waitForDelivery(receipt.id, {
    intervalMs: 2000,
    timeoutMs: 600_000,
    onStatus: (f) => console.error(f.status)
  })
  console.log(JSON.stringify(fax))       // stdout: the machine-readable result
  process.exit(0)
} catch (err) {
  if (err instanceof FaxFailedError) {
    console.error(`failed: ${err.failureReason ?? "unknown"}`)
    console.log(JSON.stringify(err.fax))
    process.exit(6)
  }
  throw err
}

export SENDFAX_PRIVATE_KEY=0x...        # from a secret manager, not your shell history
export SENDFAX_MAX_USD=0.50
bun sendfax.ts invoice.pdf +14155550123
# accepted 133718a5-... (1 page(s), $0.05)
# https://sendfax.sh/f/133718a5-...
# queued
# sending
# delivered
# {"id":"133718a5-...","status":"delivered",...}