@fragmentpay/react 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frag / FragmentPay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @fragmentpay/react
+
+React components for the Frag hosted checkout. Zero runtime deps.
+
+## Install
+
+```bash
+npm install @fragmentpay/react
+# or: bun add @fragmentpay/react
+```
+
+## Required environment variables
+
+| Name                          | Where             | Example                                  |
+| ----------------------------- | ----------------- | ---------------------------------------- |
+| `NEXT_PUBLIC_FRAG_PUBLIC_KEY` | browser (public)  | `pk_live_…` or `pk_test_…`               |
+| `FRAG_SECRET_KEY`             | your backend only | `sk_live_…` (used by `@fragmentpay/server`) |
+
+The React SDK never touches `sk_…`. Intent creation happens on your server
+and the client uses the returned `intent.id`.
+
+## End-to-end example (copy-paste)
+
+**1. Wrap your app once**
+
+```tsx
+// app/providers.tsx
+"use client";
+import { FragmentPayProvider } from "@fragmentpay/react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <FragmentPayProvider publicKey={process.env.NEXT_PUBLIC_FRAG_PUBLIC_KEY!}>
+      {children}
+    </FragmentPayProvider>
+  );
+}
+```
+
+**2. Create a server endpoint that starts the intent**
+
+```ts
+// app/api/frag/route.ts
+import { Frag } from "@fragmentpay/server";
+
+const frag = new Frag({ secretKey: process.env.FRAG_SECRET_KEY! });
+
+export async function POST(req: Request) {
+  const { amount, email } = await req.json();
+  const intent = await frag.paymentIntents.create({
+    amount,
+    currency: "USD",
+    customerEmail: email,
+    settlement: { chain: "base", token: "USDC", address: process.env.MERCHANT_USDC_ADDRESS! },
+  });
+  return Response.json(intent);
+}
+```
+
+**3. Drop the button in any page — that's it**
+
+```tsx
+// app/checkout/page.tsx
+"use client";
+import { FragmentPayButton } from "@fragmentpay/react";
+
+export default function Checkout() {
+  return (
+    <FragmentPayButton
+      endpoint="/api/frag"
+      input={{ amount: 25, email: "buyer@example.com" }}
+      label="Pay $25 with Frag"
+      onSettled={(intent) => console.log("paid!", intent.id)}
+      onError={(intent) => console.error("payment failed", intent.status)}
+    />
+  );
+}
+```
+
+Behind the scenes: click → POST to your `/api/frag` → returns intent →
+embed Frag checkout iframe → live-poll status → invoke `onSettled` when
+`status === "settled"`.
+
+## Validation
+
+Wrong props fail immediately with a clear message:
+
+```tsx
+<FragmentPayProvider publicKey="oops">…
+// Error: [fragmentpay] publicKey must match pk_test_… or pk_live_…
+```
+
+## API
+
+- `<FragmentPayProvider publicKey baseUrl?>`
+- `<FragmentPayButton endpoint input label onSettled onError>`
+- `<FragmentPayCheckout intentId onSettled onError mode="iframe" | "redirect">`
+- `useFragmentIntent(intentId, { intervalMs })`
+- `useFragmentTokens({ chain })`
+- `useCreateIntent({ endpoint, transform, headers })`
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,99 @@
+import * as React from 'react';
+
+/**
+ * @fragmentpay/react
+ *
+ * Drop-in React components for Frag hosted checkout. Zero runtime deps.
+ */
+
+interface FragmentPayProviderProps {
+    publicKey: string;
+    /** Override the API/host origin. Defaults to https://frag.dev. */
+    baseUrl?: string;
+    children: React.ReactNode;
+}
+declare function FragmentPayProvider({ publicKey, baseUrl, children }: FragmentPayProviderProps): React.JSX.Element;
+interface FetchWithRetryOpts extends RequestInit {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    /** Retry POSTs on 429/503; other 5xx are only retried for idempotent methods. */
+    retryOnMethods?: string[];
+}
+/**
+ * Fetch wrapper that honors Retry-After on 429/503 and does exponential backoff
+ * with jitter for retryable failures. Exposed for advanced integrators.
+ */
+declare function fetchWithRetry(input: string, init?: FetchWithRetryOpts): Promise<Response>;
+type IntentStatus = "created" | "requires_payment" | "quoted" | "executing" | "settled" | "failed" | "expired" | "cancelled" | "refunded";
+interface PublicIntent {
+    id: string;
+    amount: string;
+    currency: string;
+    status: IntentStatus;
+    metadata?: Record<string, unknown>;
+}
+declare function useFragmentIntent(intentId: string | null, opts?: {
+    intervalMs?: number;
+}): {
+    data: PublicIntent | null;
+    status: "idle" | "loading" | "ready" | "error";
+    error: string | null;
+};
+interface FragmentPayCheckoutProps {
+    intentId: string;
+    /** Called once the intent transitions to `settled`. */
+    onSettled?: (intent: PublicIntent) => void;
+    /** Called on `failed` | `expired` | `cancelled`. */
+    onError?: (intent: PublicIntent) => void;
+    /** Iframe height in px. Defaults to 640. */
+    height?: number;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Render inline iframe (default) or open Frag checkout in a popup. */
+    mode?: "iframe" | "redirect";
+}
+declare function FragmentPayCheckout({ intentId, onSettled, onError, height, className, style, mode, }: FragmentPayCheckoutProps): React.JSX.Element;
+interface FragToken {
+    chain: string;
+    address: string;
+    symbol: string;
+    decimals: number;
+    verified: boolean;
+    name?: string;
+}
+declare function useFragmentTokens(params?: {
+    chain?: string;
+}): {
+    data: FragToken[];
+    loading: boolean;
+    error: string | null;
+};
+interface UseCreateIntentOptions<TInput = unknown> {
+    /** Absolute or relative URL on YOUR backend that creates an intent. */
+    endpoint: string;
+    /** Custom transformer if you want to shape the request body. */
+    transform?: (input: TInput) => unknown;
+    headers?: Record<string, string>;
+}
+declare function useCreateIntent<TInput = Record<string, unknown>>(opts: UseCreateIntentOptions<TInput>): {
+    mutate: (input: TInput) => Promise<PublicIntent & {
+        checkout_url?: string;
+    }>;
+    intent: (PublicIntent & {
+        checkout_url?: string;
+    }) | null;
+    loading: boolean;
+    error: string | null;
+};
+interface FragmentPayButtonProps extends UseCreateIntentOptions {
+    input?: Record<string, unknown>;
+    label?: string;
+    onSettled?: (intent: PublicIntent) => void;
+    onError?: (intent: PublicIntent) => void;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function FragmentPayButton({ input, label, onSettled, onError, className, style, ...opts }: FragmentPayButtonProps): React.JSX.Element;
+
+export { type FetchWithRetryOpts, type FragToken, FragmentPayButton, type FragmentPayButtonProps, FragmentPayCheckout, type FragmentPayCheckoutProps, FragmentPayProvider, type FragmentPayProviderProps, type IntentStatus, type PublicIntent, type UseCreateIntentOptions, fetchWithRetry, useCreateIntent, useFragmentIntent, useFragmentTokens };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import * as React from 'react';
+
+/**
+ * @fragmentpay/react
+ *
+ * Drop-in React components for Frag hosted checkout. Zero runtime deps.
+ */
+
+interface FragmentPayProviderProps {
+    publicKey: string;
+    /** Override the API/host origin. Defaults to https://frag.dev. */
+    baseUrl?: string;
+    children: React.ReactNode;
+}
+declare function FragmentPayProvider({ publicKey, baseUrl, children }: FragmentPayProviderProps): React.JSX.Element;
+interface FetchWithRetryOpts extends RequestInit {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    /** Retry POSTs on 429/503; other 5xx are only retried for idempotent methods. */
+    retryOnMethods?: string[];
+}
+/**
+ * Fetch wrapper that honors Retry-After on 429/503 and does exponential backoff
+ * with jitter for retryable failures. Exposed for advanced integrators.
+ */
+declare function fetchWithRetry(input: string, init?: FetchWithRetryOpts): Promise<Response>;
+type IntentStatus = "created" | "requires_payment" | "quoted" | "executing" | "settled" | "failed" | "expired" | "cancelled" | "refunded";
+interface PublicIntent {
+    id: string;
+    amount: string;
+    currency: string;
+    status: IntentStatus;
+    metadata?: Record<string, unknown>;
+}
+declare function useFragmentIntent(intentId: string | null, opts?: {
+    intervalMs?: number;
+}): {
+    data: PublicIntent | null;
+    status: "idle" | "loading" | "ready" | "error";
+    error: string | null;
+};
+interface FragmentPayCheckoutProps {
+    intentId: string;
+    /** Called once the intent transitions to `settled`. */
+    onSettled?: (intent: PublicIntent) => void;
+    /** Called on `failed` | `expired` | `cancelled`. */
+    onError?: (intent: PublicIntent) => void;
+    /** Iframe height in px. Defaults to 640. */
+    height?: number;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Render inline iframe (default) or open Frag checkout in a popup. */
+    mode?: "iframe" | "redirect";
+}
+declare function FragmentPayCheckout({ intentId, onSettled, onError, height, className, style, mode, }: FragmentPayCheckoutProps): React.JSX.Element;
+interface FragToken {
+    chain: string;
+    address: string;
+    symbol: string;
+    decimals: number;
+    verified: boolean;
+    name?: string;
+}
+declare function useFragmentTokens(params?: {
+    chain?: string;
+}): {
+    data: FragToken[];
+    loading: boolean;
+    error: string | null;
+};
+interface UseCreateIntentOptions<TInput = unknown> {
+    /** Absolute or relative URL on YOUR backend that creates an intent. */
+    endpoint: string;
+    /** Custom transformer if you want to shape the request body. */
+    transform?: (input: TInput) => unknown;
+    headers?: Record<string, string>;
+}
+declare function useCreateIntent<TInput = Record<string, unknown>>(opts: UseCreateIntentOptions<TInput>): {
+    mutate: (input: TInput) => Promise<PublicIntent & {
+        checkout_url?: string;
+    }>;
+    intent: (PublicIntent & {
+        checkout_url?: string;
+    }) | null;
+    loading: boolean;
+    error: string | null;
+};
+interface FragmentPayButtonProps extends UseCreateIntentOptions {
+    input?: Record<string, unknown>;
+    label?: string;
+    onSettled?: (intent: PublicIntent) => void;
+    onError?: (intent: PublicIntent) => void;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function FragmentPayButton({ input, label, onSettled, onError, className, style, ...opts }: FragmentPayButtonProps): React.JSX.Element;
+
+export { type FetchWithRetryOpts, type FragToken, FragmentPayButton, type FragmentPayButtonProps, FragmentPayCheckout, type FragmentPayCheckoutProps, FragmentPayProvider, type FragmentPayProviderProps, type IntentStatus, type PublicIntent, type UseCreateIntentOptions, fetchWithRetry, useCreateIntent, useFragmentIntent, useFragmentTokens };

package/dist/index.js

@@ -0,0 +1,305 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  FragmentPayButton: () => FragmentPayButton,
+  FragmentPayCheckout: () => FragmentPayCheckout,
+  FragmentPayProvider: () => FragmentPayProvider,
+  fetchWithRetry: () => fetchWithRetry,
+  useCreateIntent: () => useCreateIntent,
+  useFragmentIntent: () => useFragmentIntent,
+  useFragmentTokens: () => useFragmentTokens
+});
+module.exports = __toCommonJS(index_exports);
+var React = __toESM(require("react"));
+var import_jsx_runtime = require("react/jsx-runtime");
+var FragContext = React.createContext(null);
+function FragmentPayProvider({ publicKey, baseUrl, children }) {
+  if (typeof publicKey !== "string" || !/^pk_(test|live)_[A-Za-z0-9_-]{8,}$/.test(publicKey)) {
+    throw new Error("[fragmentpay] publicKey must match pk_test_\u2026 or pk_live_\u2026 (min 8 chars after prefix)");
+  }
+  if (baseUrl !== void 0) {
+    try {
+      new URL(baseUrl);
+    } catch {
+      throw new Error("[fragmentpay] baseUrl must be an absolute URL");
+    }
+  }
+  const value = React.useMemo(
+    () => ({ publicKey, baseUrl: (baseUrl ?? "https://frag.dev").replace(/\/$/, "") }),
+    [publicKey, baseUrl]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FragContext.Provider, { value, children });
+}
+function useFrag() {
+  const ctx = React.useContext(FragContext);
+  if (!ctx) throw new Error("Wrap your tree with <FragmentPayProvider>");
+  return ctx;
+}
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) return reject(new DOMException("Aborted", "AbortError"));
+  const id = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+  const onAbort = () => {
+    clearTimeout(id);
+    reject(new DOMException("Aborted", "AbortError"));
+  };
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+function parseRetryAfter(h) {
+  if (!h) return null;
+  const secs = Number(h);
+  if (Number.isFinite(secs) && secs >= 0) return Math.min(secs, 60) * 1e3;
+  const when = Date.parse(h);
+  if (!Number.isNaN(when)) return Math.max(0, Math.min(6e4, when - Date.now()));
+  return null;
+}
+async function fetchWithRetry(input, init = {}) {
+  const {
+    maxRetries = 4,
+    baseDelayMs = 500,
+    maxDelayMs = 8e3,
+    retryOnMethods = ["GET", "HEAD", "POST"],
+    ...rest
+  } = init;
+  const method = (rest.method ?? "GET").toUpperCase();
+  const canRetry = retryOnMethods.map((m) => m.toUpperCase()).includes(method);
+  let attempt = 0;
+  while (true) {
+    let res = null;
+    let netErr = null;
+    try {
+      res = await fetch(input, rest);
+    } catch (e) {
+      netErr = e;
+    }
+    const status = res?.status ?? 0;
+    const retriable = !!netErr || status === 429 || status === 503 || status >= 500 && status < 600;
+    if (!retriable || !canRetry || attempt >= maxRetries) {
+      if (res) return res;
+      throw netErr ?? new Error("network error");
+    }
+    const hinted = res ? parseRetryAfter(res.headers.get("retry-after")) : null;
+    const backoff = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+    const jitter = Math.random() * (backoff * 0.25);
+    const delay = hinted ?? backoff + jitter;
+    await sleep(delay, rest.signal ?? void 0);
+    attempt += 1;
+  }
+}
+function useFragmentIntent(intentId, opts = {}) {
+  const { baseUrl } = useFrag();
+  if (intentId !== null && (typeof intentId !== "string" || intentId.length < 3)) {
+    throw new Error("[fragmentpay] useFragmentIntent: intentId must be a non-empty string or null");
+  }
+  const interval = opts.intervalMs ?? 2e3;
+  if (typeof interval !== "number" || interval < 250 || interval > 6e4) {
+    throw new Error("[fragmentpay] useFragmentIntent: intervalMs must be between 250 and 60000");
+  }
+  const [state, setState] = React.useState({ data: null, status: "idle", error: null });
+  React.useEffect(() => {
+    if (!intentId) return;
+    let alive = true;
+    let timer;
+    async function tick() {
+      try {
+        const res = await fetchWithRetry(`${baseUrl}/api/public/v1/checkout/${intentId}`, {
+          maxRetries: 4
+        });
+        if (!res.ok) {
+          const retryAfter = parseRetryAfter(res.headers.get("retry-after")) ?? interval * 2;
+          throw Object.assign(new Error(`HTTP ${res.status}`), { retryAfter });
+        }
+        const data = await res.json();
+        if (!alive) return;
+        setState({ data, status: "ready", error: null });
+        const terminal = ["settled", "failed", "expired", "cancelled", "refunded"].includes(data.status);
+        if (!terminal) timer = setTimeout(tick, interval);
+      } catch (e) {
+        if (!alive) return;
+        const wait = e.retryAfter ?? interval * 2;
+        setState((s) => ({ ...s, status: "error", error: e.message }));
+        timer = setTimeout(tick, wait);
+      }
+    }
+    setState({ data: null, status: "loading", error: null });
+    tick();
+    return () => {
+      alive = false;
+      clearTimeout(timer);
+    };
+  }, [intentId, baseUrl, interval]);
+  return state;
+}
+function FragmentPayCheckout({
+  intentId,
+  onSettled,
+  onError,
+  height = 640,
+  className,
+  style,
+  mode = "iframe"
+}) {
+  const { baseUrl } = useFrag();
+  const url = `${baseUrl}/checkout/${intentId}?embed=1`;
+  const intent = useFragmentIntent(intentId);
+  const fired = React.useRef(false);
+  React.useEffect(() => {
+    if (fired.current || !intent.data) return;
+    const s = intent.data.status;
+    if (s === "settled") {
+      fired.current = true;
+      onSettled?.(intent.data);
+    } else if (s === "failed" || s === "expired" || s === "cancelled") {
+      fired.current = true;
+      onError?.(intent.data);
+    }
+  }, [intent.data, onSettled, onError]);
+  if (mode === "redirect") {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "a",
+      {
+        href: `${baseUrl}/checkout/${intentId}`,
+        className,
+        style,
+        target: "_blank",
+        rel: "noreferrer",
+        children: "Pay with Frag"
+      }
+    );
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "iframe",
+    {
+      title: "Frag checkout",
+      src: url,
+      className,
+      style: { width: "100%", height, border: 0, borderRadius: 8, ...style },
+      allow: "clipboard-write; payment"
+    }
+  );
+}
+function useFragmentTokens(params = {}) {
+  const { baseUrl } = useFrag();
+  const [state, setState] = React.useState({
+    data: [],
+    loading: true,
+    error: null
+  });
+  React.useEffect(() => {
+    let alive = true;
+    const url = params.chain ? `${baseUrl}/api/public/v1/tokens?chain=${encodeURIComponent(params.chain)}` : `${baseUrl}/api/public/v1/tokens`;
+    fetchWithRetry(url, { maxRetries: 3 }).then((r) => r.json()).then((j) => {
+      if (alive) setState({ data: j.data ?? [], loading: false, error: null });
+    }).catch((e) => {
+      if (alive) setState({ data: [], loading: false, error: e.message });
+    });
+    return () => {
+      alive = false;
+    };
+  }, [baseUrl, params.chain]);
+  return state;
+}
+function useCreateIntent(opts) {
+  if (!opts || typeof opts.endpoint !== "string" || opts.endpoint.length === 0) {
+    throw new Error("[fragmentpay] useCreateIntent: `endpoint` is required");
+  }
+  const [state, setState] = React.useState({ intent: null, loading: false, error: null });
+  const mutate = React.useCallback(async (input) => {
+    setState({ intent: null, loading: true, error: null });
+    try {
+      const body = opts.transform ? opts.transform(input) : input;
+      const res = await fetchWithRetry(opts.endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...opts.headers ?? {} },
+        body: JSON.stringify(body),
+        maxRetries: 3
+      });
+      if (!res.ok) {
+        const retryAfter = res.headers.get("retry-after");
+        const suffix = res.status === 429 && retryAfter ? ` (retry after ${retryAfter}s)` : "";
+        throw new Error(`HTTP ${res.status}${suffix}: ${await res.text()}`);
+      }
+      const intent = await res.json();
+      setState({ intent, loading: false, error: null });
+      return intent;
+    } catch (e) {
+      setState({ intent: null, loading: false, error: e.message });
+      throw e;
+    }
+  }, [opts.endpoint, opts.transform, opts.headers]);
+  return { ...state, mutate };
+}
+function FragmentPayButton({
+  input,
+  label = "Pay with Frag",
+  onSettled,
+  onError,
+  className,
+  style,
+  ...opts
+}) {
+  const { intent, loading, error, mutate } = useCreateIntent(opts);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "button",
+      {
+        type: "button",
+        className,
+        style,
+        disabled: loading,
+        onClick: () => mutate(input ?? {}),
+        children: loading ? "Loading\u2026" : label
+      }
+    ),
+    error && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { role: "alert", style: { color: "crimson", fontSize: 12 }, children: error }),
+    intent?.id && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      FragmentPayCheckout,
+      {
+        intentId: intent.id,
+        onSettled,
+        onError
+      }
+    )
+  ] });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FragmentPayButton,
+  FragmentPayCheckout,
+  FragmentPayProvider,
+  fetchWithRetry,
+  useCreateIntent,
+  useFragmentIntent,
+  useFragmentTokens
+});

package/dist/index.mjs

@@ -0,0 +1,264 @@
+// src/index.tsx
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var FragContext = React.createContext(null);
+function FragmentPayProvider({ publicKey, baseUrl, children }) {
+  if (typeof publicKey !== "string" || !/^pk_(test|live)_[A-Za-z0-9_-]{8,}$/.test(publicKey)) {
+    throw new Error("[fragmentpay] publicKey must match pk_test_\u2026 or pk_live_\u2026 (min 8 chars after prefix)");
+  }
+  if (baseUrl !== void 0) {
+    try {
+      new URL(baseUrl);
+    } catch {
+      throw new Error("[fragmentpay] baseUrl must be an absolute URL");
+    }
+  }
+  const value = React.useMemo(
+    () => ({ publicKey, baseUrl: (baseUrl ?? "https://frag.dev").replace(/\/$/, "") }),
+    [publicKey, baseUrl]
+  );
+  return /* @__PURE__ */ jsx(FragContext.Provider, { value, children });
+}
+function useFrag() {
+  const ctx = React.useContext(FragContext);
+  if (!ctx) throw new Error("Wrap your tree with <FragmentPayProvider>");
+  return ctx;
+}
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) return reject(new DOMException("Aborted", "AbortError"));
+  const id = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+  const onAbort = () => {
+    clearTimeout(id);
+    reject(new DOMException("Aborted", "AbortError"));
+  };
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+function parseRetryAfter(h) {
+  if (!h) return null;
+  const secs = Number(h);
+  if (Number.isFinite(secs) && secs >= 0) return Math.min(secs, 60) * 1e3;
+  const when = Date.parse(h);
+  if (!Number.isNaN(when)) return Math.max(0, Math.min(6e4, when - Date.now()));
+  return null;
+}
+async function fetchWithRetry(input, init = {}) {
+  const {
+    maxRetries = 4,
+    baseDelayMs = 500,
+    maxDelayMs = 8e3,
+    retryOnMethods = ["GET", "HEAD", "POST"],
+    ...rest
+  } = init;
+  const method = (rest.method ?? "GET").toUpperCase();
+  const canRetry = retryOnMethods.map((m) => m.toUpperCase()).includes(method);
+  let attempt = 0;
+  while (true) {
+    let res = null;
+    let netErr = null;
+    try {
+      res = await fetch(input, rest);
+    } catch (e) {
+      netErr = e;
+    }
+    const status = res?.status ?? 0;
+    const retriable = !!netErr || status === 429 || status === 503 || status >= 500 && status < 600;
+    if (!retriable || !canRetry || attempt >= maxRetries) {
+      if (res) return res;
+      throw netErr ?? new Error("network error");
+    }
+    const hinted = res ? parseRetryAfter(res.headers.get("retry-after")) : null;
+    const backoff = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+    const jitter = Math.random() * (backoff * 0.25);
+    const delay = hinted ?? backoff + jitter;
+    await sleep(delay, rest.signal ?? void 0);
+    attempt += 1;
+  }
+}
+function useFragmentIntent(intentId, opts = {}) {
+  const { baseUrl } = useFrag();
+  if (intentId !== null && (typeof intentId !== "string" || intentId.length < 3)) {
+    throw new Error("[fragmentpay] useFragmentIntent: intentId must be a non-empty string or null");
+  }
+  const interval = opts.intervalMs ?? 2e3;
+  if (typeof interval !== "number" || interval < 250 || interval > 6e4) {
+    throw new Error("[fragmentpay] useFragmentIntent: intervalMs must be between 250 and 60000");
+  }
+  const [state, setState] = React.useState({ data: null, status: "idle", error: null });
+  React.useEffect(() => {
+    if (!intentId) return;
+    let alive = true;
+    let timer;
+    async function tick() {
+      try {
+        const res = await fetchWithRetry(`${baseUrl}/api/public/v1/checkout/${intentId}`, {
+          maxRetries: 4
+        });
+        if (!res.ok) {
+          const retryAfter = parseRetryAfter(res.headers.get("retry-after")) ?? interval * 2;
+          throw Object.assign(new Error(`HTTP ${res.status}`), { retryAfter });
+        }
+        const data = await res.json();
+        if (!alive) return;
+        setState({ data, status: "ready", error: null });
+        const terminal = ["settled", "failed", "expired", "cancelled", "refunded"].includes(data.status);
+        if (!terminal) timer = setTimeout(tick, interval);
+      } catch (e) {
+        if (!alive) return;
+        const wait = e.retryAfter ?? interval * 2;
+        setState((s) => ({ ...s, status: "error", error: e.message }));
+        timer = setTimeout(tick, wait);
+      }
+    }
+    setState({ data: null, status: "loading", error: null });
+    tick();
+    return () => {
+      alive = false;
+      clearTimeout(timer);
+    };
+  }, [intentId, baseUrl, interval]);
+  return state;
+}
+function FragmentPayCheckout({
+  intentId,
+  onSettled,
+  onError,
+  height = 640,
+  className,
+  style,
+  mode = "iframe"
+}) {
+  const { baseUrl } = useFrag();
+  const url = `${baseUrl}/checkout/${intentId}?embed=1`;
+  const intent = useFragmentIntent(intentId);
+  const fired = React.useRef(false);
+  React.useEffect(() => {
+    if (fired.current || !intent.data) return;
+    const s = intent.data.status;
+    if (s === "settled") {
+      fired.current = true;
+      onSettled?.(intent.data);
+    } else if (s === "failed" || s === "expired" || s === "cancelled") {
+      fired.current = true;
+      onError?.(intent.data);
+    }
+  }, [intent.data, onSettled, onError]);
+  if (mode === "redirect") {
+    return /* @__PURE__ */ jsx(
+      "a",
+      {
+        href: `${baseUrl}/checkout/${intentId}`,
+        className,
+        style,
+        target: "_blank",
+        rel: "noreferrer",
+        children: "Pay with Frag"
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "iframe",
+    {
+      title: "Frag checkout",
+      src: url,
+      className,
+      style: { width: "100%", height, border: 0, borderRadius: 8, ...style },
+      allow: "clipboard-write; payment"
+    }
+  );
+}
+function useFragmentTokens(params = {}) {
+  const { baseUrl } = useFrag();
+  const [state, setState] = React.useState({
+    data: [],
+    loading: true,
+    error: null
+  });
+  React.useEffect(() => {
+    let alive = true;
+    const url = params.chain ? `${baseUrl}/api/public/v1/tokens?chain=${encodeURIComponent(params.chain)}` : `${baseUrl}/api/public/v1/tokens`;
+    fetchWithRetry(url, { maxRetries: 3 }).then((r) => r.json()).then((j) => {
+      if (alive) setState({ data: j.data ?? [], loading: false, error: null });
+    }).catch((e) => {
+      if (alive) setState({ data: [], loading: false, error: e.message });
+    });
+    return () => {
+      alive = false;
+    };
+  }, [baseUrl, params.chain]);
+  return state;
+}
+function useCreateIntent(opts) {
+  if (!opts || typeof opts.endpoint !== "string" || opts.endpoint.length === 0) {
+    throw new Error("[fragmentpay] useCreateIntent: `endpoint` is required");
+  }
+  const [state, setState] = React.useState({ intent: null, loading: false, error: null });
+  const mutate = React.useCallback(async (input) => {
+    setState({ intent: null, loading: true, error: null });
+    try {
+      const body = opts.transform ? opts.transform(input) : input;
+      const res = await fetchWithRetry(opts.endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...opts.headers ?? {} },
+        body: JSON.stringify(body),
+        maxRetries: 3
+      });
+      if (!res.ok) {
+        const retryAfter = res.headers.get("retry-after");
+        const suffix = res.status === 429 && retryAfter ? ` (retry after ${retryAfter}s)` : "";
+        throw new Error(`HTTP ${res.status}${suffix}: ${await res.text()}`);
+      }
+      const intent = await res.json();
+      setState({ intent, loading: false, error: null });
+      return intent;
+    } catch (e) {
+      setState({ intent: null, loading: false, error: e.message });
+      throw e;
+    }
+  }, [opts.endpoint, opts.transform, opts.headers]);
+  return { ...state, mutate };
+}
+function FragmentPayButton({
+  input,
+  label = "Pay with Frag",
+  onSettled,
+  onError,
+  className,
+  style,
+  ...opts
+}) {
+  const { intent, loading, error, mutate } = useCreateIntent(opts);
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        className,
+        style,
+        disabled: loading,
+        onClick: () => mutate(input ?? {}),
+        children: loading ? "Loading\u2026" : label
+      }
+    ),
+    error && /* @__PURE__ */ jsx("div", { role: "alert", style: { color: "crimson", fontSize: 12 }, children: error }),
+    intent?.id && /* @__PURE__ */ jsx(
+      FragmentPayCheckout,
+      {
+        intentId: intent.id,
+        onSettled,
+        onError
+      }
+    )
+  ] });
+}
+export {
+  FragmentPayButton,
+  FragmentPayCheckout,
+  FragmentPayProvider,
+  fetchWithRetry,
+  useCreateIntent,
+  useFragmentIntent,
+  useFragmentTokens
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@fragmentpay/react",
+  "version": "0.3.1",
+  "description": "React components for Frag hosted checkout — accept any token, on any chain.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "keywords": ["crypto", "payments", "react", "checkout", "fragmentpay", "frag"],
+  "peerDependencies": { "react": ">=18", "react-dom": ">=18" },
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fragmentpay/fragpay.git",
+    "directory": "sdk/frag-react"
+  },
+  "homepage": "https://github.com/fragmentpay/fragpay#readme",
+  "bugs": { "url": "https://github.com/fragmentpay/fragpay/issues" },
+  "publishConfig": { "access": "public", "provenance": true },
+  "scripts": {
+    "build": "tsup src/index.tsx --format esm,cjs --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "@types/react": "^18.2.0"
+  }
+}