@fragmentpay/react 0.3.1 → 0.3.4

package/README.md

@@ -11,9 +11,9 @@ npm install @fragmentpay/react
 
 ## Required environment variables
 
-| Name                          | Where             | Example                                  |
-| ----------------------------- | ----------------- | ---------------------------------------- |
-| `NEXT_PUBLIC_FRAG_PUBLIC_KEY` | browser (public)  | `pk_live_…` or `pk_test_…`               |
+| 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
@@ -81,6 +81,30 @@ Behind the scenes: click → POST to your `/api/frag` → returns intent →
 embed Frag checkout iframe → live-poll status → invoke `onSettled` when
 `status === "settled"`.
 
+## Embed vs redirect
+
+```tsx
+// Embed (default) — hosted checkout iframe with post-message events
+<FragmentPayCheckout intentId={id} onSettled={onDone} onError={onErr} />
+
+// Redirect — full-page navigation to hosted checkout
+<FragmentPayCheckout intentId={id} mode="redirect" />
+
+// Or just point the user at the hosted URL manually:
+window.location.href = intent.checkout_url;
+```
+
+## Polling with `useFragmentIntent`
+
+```tsx
+const { data, status } = useFragmentIntent(intentId, { intervalMs: 3000 });
+// data.status: created → quoted → executing → settled | failed | expired
+```
+
+Polling uses exponential backoff on 5xx / network errors and honors any
+`Retry-After` header the API returns; on the terminal states (`settled`,
+`failed`, `expired`, `cancelled`, `refunded`) polling stops automatically.
+
 ## Validation
 
 Wrong props fail immediately with a clear message:
@@ -98,6 +122,7 @@ Wrong props fail immediately with a clear message:
 - `useFragmentIntent(intentId, { intervalMs })`
 - `useFragmentTokens({ chain })`
 - `useCreateIntent({ endpoint, transform, headers })`
+- `fetchWithRetry(url, init)` — exported for advanced integrators
 
 ## License
 

package/dist/index.js

@@ -44,7 +44,9 @@ 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)");
+    throw new Error(
+      "[fragmentpay] publicKey must match pk_test_\u2026 or pk_live_\u2026 (min 8 chars after prefix)"
+    );
   }
   if (baseUrl !== void 0) {
     try {
@@ -143,7 +145,9 @@ function useFragmentIntent(intentId, opts = {}) {
         const data = await res.json();
         if (!alive) return;
         setState({ data, status: "ready", error: null });
-        const terminal = ["settled", "failed", "expired", "cancelled", "refunded"].includes(data.status);
+        const terminal = ["settled", "failed", "expired", "cancelled", "refunded"].includes(
+          data.status
+        );
         if (!terminal) timer = setTimeout(tick, interval);
       } catch (e) {
         if (!alive) return;
@@ -235,29 +239,32 @@ function useCreateIntent(opts) {
     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 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;
       }
-      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]);
+    },
+    [opts.endpoint, opts.transform, opts.headers]
+  );
   return { ...state, mutate };
 }
 function FragmentPayButton({
@@ -283,14 +290,7 @@ function FragmentPayButton({
       }
     ),
     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
-      }
-    )
+    intent?.id && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FragmentPayCheckout, { intentId: intent.id, onSettled, onError })
   ] });
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -4,7 +4,9 @@ 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)");
+    throw new Error(
+      "[fragmentpay] publicKey must match pk_test_\u2026 or pk_live_\u2026 (min 8 chars after prefix)"
+    );
   }
   if (baseUrl !== void 0) {
     try {
@@ -103,7 +105,9 @@ function useFragmentIntent(intentId, opts = {}) {
         const data = await res.json();
         if (!alive) return;
         setState({ data, status: "ready", error: null });
-        const terminal = ["settled", "failed", "expired", "cancelled", "refunded"].includes(data.status);
+        const terminal = ["settled", "failed", "expired", "cancelled", "refunded"].includes(
+          data.status
+        );
         if (!terminal) timer = setTimeout(tick, interval);
       } catch (e) {
         if (!alive) return;
@@ -195,29 +199,32 @@ function useCreateIntent(opts) {
     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 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;
       }
-      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]);
+    },
+    [opts.endpoint, opts.transform, opts.headers]
+  );
   return { ...state, mutate };
 }
 function FragmentPayButton({
@@ -243,14 +250,7 @@ function FragmentPayButton({
       }
     ),
     error && /* @__PURE__ */ jsx("div", { role: "alert", style: { color: "crimson", fontSize: 12 }, children: error }),
-    intent?.id && /* @__PURE__ */ jsx(
-      FragmentPayCheckout,
-      {
-        intentId: intent.id,
-        onSettled,
-        onError
-      }
-    )
+    intent?.id && /* @__PURE__ */ jsx(FragmentPayCheckout, { intentId: intent.id, onSettled, onError })
   ] });
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragmentpay/react",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "React components for Frag hosted checkout — accept any token, on any chain.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -12,9 +12,23 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
-  "keywords": ["crypto", "payments", "react", "checkout", "fragmentpay", "frag"],
-  "peerDependencies": { "react": ">=18", "react-dom": ">=18" },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "crypto",
+    "payments",
+    "react",
+    "checkout",
+    "fragmentpay",
+    "frag"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
   "license": "MIT",
   "sideEffects": false,
   "repository": {
@@ -23,8 +37,13 @@
     "directory": "sdk/frag-react"
   },
   "homepage": "https://github.com/fragmentpay/fragpay#readme",
-  "bugs": { "url": "https://github.com/fragmentpay/fragpay/issues" },
-  "publishConfig": { "access": "public", "provenance": true },
+  "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"