# SendFax.sh in React Native React Native is the one platform in this set where the official SDK runs, so this guide uses it. `sendfax` is dependency-free and built on web-standard `fetch`, `FormData` and `Blob` -- which mostly works on Hermes, with three real gaps this guide names and fixes rather than papering over. ```sh npm install sendfax ``` - SDK source: [`sdk/src/`](https://github.com/DanielSinclair/sendfax) | reference: [`sdk/README.md`](https://github.com/DanielSinclair/sendfax) - Contract: | docs: - Shared payment framework: [README.md](/guides/index.md) --- ## The two flows ``` FLOW A -- no wallet DocumentPicker --> blob | +-> client.send({ to, document }) [no PaymentHandler] | +-> throws PaymentRequiredError <-- this is the fork | +-> POST /api/v1/uploads (plain fetch; the SDK has no upload method) | +-> { id, pageCount, amountCents } +-> POST /api/v1/checkout { id } --> { url } +-> WebBrowser.openBrowserAsync(url) [user pays] +-> client.waitForDelivery(id) --> delivered FLOW B -- wallet DocumentPicker --> blob | +-> client.send({ to, document }) [with a PaymentHandler] +- 402 --> handler: | (i) MPP wallet signs challenge -> PAYMENT header | (ii) WalletConnect sends USDC -> no credential needed +- retry --> 202 { id, pageCount, amountUsdMicros, statusUrl } (Flow B(ii) usually needs an OUTER retry -- see below) +-> client.waitForDelivery(id) --> delivered ``` ## Which payment path am I in? **Can this app move USDC on Base right now?** A live WalletConnect session, an embedded signer, an in-app wallet -- Flow B. Nothing connected -- Flow A. In SDK terms the choice is exactly one constructor option: pass `payment` and `send()` pays inline; omit it and `send()` throws `PaymentRequiredError`, which is your signal to run the Stripe fallback (`sdk/src/client.ts:113-128`). --- ## Runtime support: what RN gives you, and what it doesn't Everything the SDK touches, checked against `sdk/src`: | API | Used at | Hermes / RN | |---|---|---| | `fetch` | `sdk/src/client.ts:111` | provided | | `FormData` | `sdk/src/client.ts:104-108` | provided, **with a filename caveat** | | `Blob` | `sdk/src/client.ts:189-192` | provided, **cannot be built from bytes** | | `AbortSignal` / `setTimeout` | `sdk/src/client.ts:218-242` | provided | | `atob` | `sdk/src/challenge.ts:216` | global since RN 0.74; polyfill below that | | `TextDecoder` | `sdk/src/challenge.ts:218` | **not provided -- polyfill required** | | `crypto` | -- | not used by the SDK at all | The SDK needs no crypto polyfill. Wallet libraries do (see Flow B). ### Gap 1 -- `TextDecoder` is missing `parseChallenge` decodes the base64url `request` parameter of the MPP challenge through `atob` then `new TextDecoder().decode(...)` (`sdk/src/challenge.ts:211-224`). Hermes ships no `TextDecoder`. Without it, `decodeJson` catches the `ReferenceError` and returns `null`, so you silently get a challenge with `amountBaseUnits: "0"` and every field `null` (`sdk/src/challenge.ts:108-124`) -- a failure that looks like a server bug and is not one. ```sh npx expo install @bacons/text-decoder # or: npm install fast-text-encoding ``` ```ts // index.js / App entry -- BEFORE any sendfax import. import "@bacons/text-decoder/install" ``` Verify it once at startup rather than discovering it in a payment path: ```ts if (typeof TextDecoder === "undefined") { throw new Error("TextDecoder polyfill missing: sendfax cannot parse the 402 challenge") } ``` ### Gap 2 -- `atob` below RN 0.74 `atob`/`btoa` became Hermes globals in React Native 0.74. On older versions: ```sh npm install base-64 ``` ```ts import { decode as atob, encode as btoa } from "base-64" if (typeof global.atob === "undefined") { global.atob = atob; global.btoa = btoa } ``` ### Gap 3 -- `Blob` cannot be constructed from bytes The SDK converts your `document` to a Blob with `new Blob([bytes], { type: "application/pdf" })` when you hand it a `Uint8Array` or `ArrayBuffer` (`sdk/src/client.ts:189-192`). React Native's `Blob` polyfill rejects that: it throws *"Creating blobs from 'ArrayBuffer' and 'ArrayBufferView' is not supported"*. An existing `Blob` passes through untouched (same lines), so the fix is to hand the SDK a Blob you obtained natively -- RN gives you one from a file URI: ```ts import * as DocumentPicker from "expo-document-picker" async function pickPdf(): Promise { const result = await DocumentPicker.getDocumentAsync({ type: "application/pdf", copyToCacheDirectory: true }) if (result.canceled) throw new Error("cancelled") const asset = result.assets[0] // RN can turn a file:// URI into a real Blob. Do NOT read it to a Uint8Array // and let the SDK wrap it -- that path throws on Hermes. const blob = await (await fetch(asset.uri)).blob() // See Gap 4: RN's FormData reads the filename off the value, not from the // SDK's `filename` argument. ;(blob as any).name = asset.name ?? "document.pdf" return blob } ``` Check the size here too -- over 20 MB the API answers `413` (`lib/domain/pricing.ts:42`). ### Gap 4 -- `FormData` filename The SDK appends the document as `form.append("document", blob, filename)` (`sdk/src/client.ts:106`). React Native's `FormData` implementation ignores the third argument and instead reads `.name` and `.type` off the appended value (`react-native/Libraries/Network/FormData.js`). The API requires the `document` part to arrive as a *file* part -- it checks `document instanceof File` and answers `400 "Missing document"` otherwise (`web/app/api/v1/faxes/route.ts:56-58`), and a multipart part with no `filename` parameter parses as a plain string field. Setting `blob.name` before you pass it (as in `pickPdf` above) is the one-line fix. Verify it against the RN version you ship: `console.log` the response of a real `send()` against `FAX_MODE=mock` and confirm you get 402 (the gate) rather than 400 (the parser). If you would rather not depend on that detail, skip `client.send()` and do the multipart yourself with RN's native part shape, keeping the SDK for everything else -- that path is spelled out in [Flow A](#flow-a) and works identically for Flow B: ```ts const form = new FormData() form.append("document", { uri, name: "document.pdf", type: "application/pdf" } as any) form.append("to", to) ``` --- ## Flow A -- no wallet: SDK send, catch, fall back to Stripe `send()` without a `PaymentHandler` throws `PaymentRequiredError` on the 402 (`sdk/src/client.ts:115`). That is not an error condition -- it is the branch. The SDK has no `upload()` or `checkout()`: it covers the agent rail only (`sdk/src/index.ts`). The human rail is two plain `fetch` calls. ```ts import { SendFax, PaymentRequiredError, InvalidDestinationError, InvalidDocumentError, FaxFailedError, type FaxPublic } from "sendfax" import * as WebBrowser from "expo-web-browser" import { Linking } from "react-native" const BASE_URL = "https://sendfax.sh" const client = new SendFax() // no payment handler -> Flow A /** POST /api/v1/uploads -- validates, page-counts, prices. Charges nothing. */ async function upload(uri: string, to: string) { const form = new FormData() form.append("document", { uri, name: "document.pdf", type: "application/pdf" } as any) form.append("to", to) const res = await fetch(`${BASE_URL}/api/v1/uploads`, { method: "POST", body: form }) if (!res.ok) throw await problemError(res) // { id, pageCount, amountCents } -- amountCents is max(50, ceil(pages * 5)). // lib/domain/pricing.ts:23 return (await res.json()) as { id: string; pageCount: number; amountCents: number } } /** POST /api/v1/checkout -- hosted Stripe Checkout URL for a prior upload. */ async function checkoutUrl(id: string) { const res = await fetch(`${BASE_URL}/api/v1/checkout`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ id }) }) if (!res.ok) throw await problemError(res) return ((await res.json()) as { url: string }).url } async function problemError(res: Response) { const problem = await res.json().catch(() => null) return new Error(problem?.detail ?? problem?.title ?? `HTTP ${res.status}`) } ``` The whole flow, with the fork made explicit: ```ts export async function sendFax( uri: string, to: string, onStatus: (fax: FaxPublic) => void ): Promise { const document = await blobFromUri(uri) // see Gap 3 let id: string try { // Optimistic: if a handler is ever configured, this settles inline. const receipt = await client.send({ to, document }) id = receipt.id } catch (err) { if (!(err instanceof PaymentRequiredError)) throw err // --- the fork: no wallet, so pay with Stripe -------------------------- const up = await upload(uri, to) const url = await checkoutUrl(up.id) // In-app browser keeps the user in your app; Linking hands off to Safari/ // Chrome. Either is fine -- neither tells you when payment lands, because // Checkout's success_url is https://sendfax.sh/f/{id}?paid=1 // (lib/payments/stripe.ts:139), not a scheme of yours. You poll. await WebBrowser.openBrowserAsync(url) // or Linking.openURL(url) id = up.id } // Both branches converge here. GET /api/v1/faxes/{id} is free and unauthed. return client.waitForDelivery(id, { intervalMs: 2000, timeoutMs: 300_000, onStatus }) } ``` `waitForDelivery` resolves on `delivered` and rejects with `FaxFailedError` on `failed`/`expired`, carrying `failureReason` (`sdk/src/client.ts:161-185`). > **Note on the optimistic `send()` first.** It costs one round trip and gives > you the server's validation for free -- an unsupported destination throws > `InvalidDestinationError` before you ever build a Checkout session. If you > would rather skip it, call `upload()` directly; it runs the same validation > (`web/app/api/v1/uploads/route.ts:49-57`). ### Errors worth handling by name ```ts try { await sendFax(uri, to, setStatus) } catch (err) { if (err instanceof InvalidDestinationError) { // 422. Either not E.164, or outside US/CA/MX/PM. err.problem.detail is the // exact sentence to show. lib/domain/fax.ts:84-85 setError(err.problem?.detail ?? err.message) } else if (err instanceof InvalidDocumentError) { // 400 / 413 / 422: not a PDF, encrypted, zero pages, or over 20 MB. setError(err.message) } else if (err instanceof FaxFailedError) { setError(`Delivery failed: ${err.failureReason ?? "unknown"}`) } else { setError(String(err)) } } ``` ### Foreground-only polling `waitForDelivery` is a plain interval loop; iOS suspends it when your app backgrounds and Android may too under Doze. Cancel on background, restart on foreground, and offer the status page as the escape hatch: ```ts import { AppState } from "react-native" const controller = new AbortController() const sub = AppState.addEventListener("change", (s) => { if (s !== "active") controller.abort() }) try { await client.waitForDelivery(id, { signal: controller.signal, onStatus }) } finally { sub.remove() } // Anywhere in the UI: