@fragmentpay/react 0.3.4 → 0.4.0

package/dist/index.d.mts

@@ -8,7 +8,7 @@ import * as React from 'react';
 
 interface FragmentPayProviderProps {
     publicKey: string;
-    /** Override the API/host origin. Defaults to https://frag.dev. */
+    /** Override the API/host origin. Defaults to https://frag.cash. */
     baseUrl?: string;
     children: React.ReactNode;
 }
@@ -25,14 +25,43 @@ interface FetchWithRetryOpts extends RequestInit {
  * 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";
+type IntentStatus = "created" | "requires_payment" | "quoted" | "awaiting_signature" | "executing" | "partially_filled" | "settled" | "failed" | "expired" | "cancelled" | "refunded";
 interface PublicIntent {
     id: string;
     amount: string;
     currency: string;
     status: IntentStatus;
+    settlement_chain?: string | null;
+    settlement_token?: string | null;
+    expires_at?: string;
     metadata?: Record<string, unknown>;
 }
+type RefundStatus = "pending" | "processing" | "retry_scheduled" | "succeeded" | "failed";
+type RefundPhase = "queued" | "sent" | "completed" | "failed";
+/**
+ * Bucket a raw refund status into a stable UI phase. Mirrors the identical
+ * helper in `@fragmentpay/server` so front-end and back-end render matching
+ * status pills.
+ */
+declare function refundPhase(status: RefundStatus | string | null | undefined): RefundPhase;
+interface PublicRefundStatus {
+    id: string;
+    payment_intent_id: string;
+    amount_usd: number;
+    chain: string | null;
+    token: string | null;
+    destination_tail: string;
+    reason: string;
+    status: RefundStatus;
+    phase: RefundPhase;
+    tx_hash: string | null;
+    failure_reason: string | null;
+    attempts: number;
+    created_at: string;
+    updated_at: string;
+    paid_at: string | null;
+    terminal: boolean;
+}
 declare function useFragmentIntent(intentId: string | null, opts?: {
     intervalMs?: number;
 }): {
@@ -40,6 +69,21 @@ declare function useFragmentIntent(intentId: string | null, opts?: {
     status: "idle" | "loading" | "ready" | "error";
     error: string | null;
 };
+/**
+ * Poll the payer-facing refund status endpoint at `/api/public/refunds/:id/status`.
+ * UNAUTHENTICATED — safe to use in customer-facing receipt / order-tracking UIs.
+ *
+ * Returns `{ data, status, error }` where `data.phase` buckets the raw refund
+ * state into `queued | sent | completed | failed` for a stable status pill.
+ * Polling stops automatically once `data.terminal === true`.
+ */
+declare function useFragmentRefund(refundId: string | null, opts?: {
+    intervalMs?: number;
+}): {
+    data: PublicRefundStatus | null;
+    status: "idle" | "loading" | "ready" | "error";
+    error: string | null;
+};
 interface FragmentPayCheckoutProps {
     intentId: string;
     /** Called once the intent transitions to `settled`. */
@@ -96,4 +140,4 @@ interface FragmentPayButtonProps extends UseCreateIntentOptions {
 }
 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 };
+export { type FetchWithRetryOpts, type FragToken, FragmentPayButton, type FragmentPayButtonProps, FragmentPayCheckout, type FragmentPayCheckoutProps, FragmentPayProvider, type FragmentPayProviderProps, type IntentStatus, type PublicIntent, type PublicRefundStatus, type RefundPhase, type RefundStatus, type UseCreateIntentOptions, fetchWithRetry, refundPhase, useCreateIntent, useFragmentIntent, useFragmentRefund, useFragmentTokens };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import * as React from 'react';
 
 interface FragmentPayProviderProps {
     publicKey: string;
-    /** Override the API/host origin. Defaults to https://frag.dev. */
+    /** Override the API/host origin. Defaults to https://frag.cash. */
     baseUrl?: string;
     children: React.ReactNode;
 }
@@ -25,14 +25,43 @@ interface FetchWithRetryOpts extends RequestInit {
  * 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";
+type IntentStatus = "created" | "requires_payment" | "quoted" | "awaiting_signature" | "executing" | "partially_filled" | "settled" | "failed" | "expired" | "cancelled" | "refunded";
 interface PublicIntent {
     id: string;
     amount: string;
     currency: string;
     status: IntentStatus;
+    settlement_chain?: string | null;
+    settlement_token?: string | null;
+    expires_at?: string;
     metadata?: Record<string, unknown>;
 }
+type RefundStatus = "pending" | "processing" | "retry_scheduled" | "succeeded" | "failed";
+type RefundPhase = "queued" | "sent" | "completed" | "failed";
+/**
+ * Bucket a raw refund status into a stable UI phase. Mirrors the identical
+ * helper in `@fragmentpay/server` so front-end and back-end render matching
+ * status pills.
+ */
+declare function refundPhase(status: RefundStatus | string | null | undefined): RefundPhase;
+interface PublicRefundStatus {
+    id: string;
+    payment_intent_id: string;
+    amount_usd: number;
+    chain: string | null;
+    token: string | null;
+    destination_tail: string;
+    reason: string;
+    status: RefundStatus;
+    phase: RefundPhase;
+    tx_hash: string | null;
+    failure_reason: string | null;
+    attempts: number;
+    created_at: string;
+    updated_at: string;
+    paid_at: string | null;
+    terminal: boolean;
+}
 declare function useFragmentIntent(intentId: string | null, opts?: {
     intervalMs?: number;
 }): {
@@ -40,6 +69,21 @@ declare function useFragmentIntent(intentId: string | null, opts?: {
     status: "idle" | "loading" | "ready" | "error";
     error: string | null;
 };
+/**
+ * Poll the payer-facing refund status endpoint at `/api/public/refunds/:id/status`.
+ * UNAUTHENTICATED — safe to use in customer-facing receipt / order-tracking UIs.
+ *
+ * Returns `{ data, status, error }` where `data.phase` buckets the raw refund
+ * state into `queued | sent | completed | failed` for a stable status pill.
+ * Polling stops automatically once `data.terminal === true`.
+ */
+declare function useFragmentRefund(refundId: string | null, opts?: {
+    intervalMs?: number;
+}): {
+    data: PublicRefundStatus | null;
+    status: "idle" | "loading" | "ready" | "error";
+    error: string | null;
+};
 interface FragmentPayCheckoutProps {
     intentId: string;
     /** Called once the intent transitions to `settled`. */
@@ -96,4 +140,4 @@ interface FragmentPayButtonProps extends UseCreateIntentOptions {
 }
 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 };
+export { type FetchWithRetryOpts, type FragToken, FragmentPayButton, type FragmentPayButtonProps, FragmentPayCheckout, type FragmentPayCheckoutProps, FragmentPayProvider, type FragmentPayProviderProps, type IntentStatus, type PublicIntent, type PublicRefundStatus, type RefundPhase, type RefundStatus, type UseCreateIntentOptions, fetchWithRetry, refundPhase, useCreateIntent, useFragmentIntent, useFragmentRefund, useFragmentTokens };

package/dist/index.js

@@ -34,8 +34,10 @@ __export(index_exports, {
   FragmentPayCheckout: () => FragmentPayCheckout,
   FragmentPayProvider: () => FragmentPayProvider,
   fetchWithRetry: () => fetchWithRetry,
+  refundPhase: () => refundPhase,
   useCreateIntent: () => useCreateIntent,
   useFragmentIntent: () => useFragmentIntent,
+  useFragmentRefund: () => useFragmentRefund,
   useFragmentTokens: () => useFragmentTokens
 });
 module.exports = __toCommonJS(index_exports);
@@ -56,7 +58,7 @@ function FragmentPayProvider({ publicKey, baseUrl, children }) {
     }
   }
   const value = React.useMemo(
-    () => ({ publicKey, baseUrl: (baseUrl ?? "https://frag.dev").replace(/\/$/, "") }),
+    () => ({ publicKey, baseUrl: (baseUrl ?? "https://frag.cash").replace(/\/$/, "") }),
     [publicKey, baseUrl]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FragContext.Provider, { value, children });
@@ -119,6 +121,18 @@ async function fetchWithRetry(input, init = {}) {
     attempt += 1;
   }
 }
+function refundPhase(status) {
+  switch (status) {
+    case "succeeded":
+      return "completed";
+    case "processing":
+      return "sent";
+    case "failed":
+      return "failed";
+    default:
+      return "queued";
+  }
+}
 function useFragmentIntent(intentId, opts = {}) {
   const { baseUrl } = useFrag();
   if (intentId !== null && (typeof intentId !== "string" || intentId.length < 3)) {
@@ -165,6 +179,51 @@ function useFragmentIntent(intentId, opts = {}) {
   }, [intentId, baseUrl, interval]);
   return state;
 }
+function useFragmentRefund(refundId, opts = {}) {
+  const { baseUrl } = useFrag();
+  if (refundId !== null && (typeof refundId !== "string" || refundId.length < 3)) {
+    throw new Error("[fragmentpay] useFragmentRefund: refundId must be a non-empty string or null");
+  }
+  const interval = opts.intervalMs ?? 3e3;
+  if (typeof interval !== "number" || interval < 500 || interval > 6e4) {
+    throw new Error("[fragmentpay] useFragmentRefund: intervalMs must be between 500 and 60000");
+  }
+  const [state, setState] = React.useState({ data: null, status: "idle", error: null });
+  React.useEffect(() => {
+    if (!refundId) return;
+    let alive = true;
+    let timer;
+    async function tick() {
+      try {
+        const res = await fetchWithRetry(
+          `${baseUrl}/api/public/refunds/${refundId}/status`,
+          { 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 raw = await res.json();
+        const data = { ...raw, phase: refundPhase(raw.status) };
+        if (!alive) return;
+        setState({ data, status: "ready", error: null });
+        if (!data.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);
+    };
+  }, [refundId, baseUrl, interval]);
+  return state;
+}
 function FragmentPayCheckout({
   intentId,
   onSettled,
@@ -299,7 +358,9 @@ function FragmentPayButton({
   FragmentPayCheckout,
   FragmentPayProvider,
   fetchWithRetry,
+  refundPhase,
   useCreateIntent,
   useFragmentIntent,
+  useFragmentRefund,
   useFragmentTokens
 });

package/dist/index.mjs

@@ -16,7 +16,7 @@ function FragmentPayProvider({ publicKey, baseUrl, children }) {
     }
   }
   const value = React.useMemo(
-    () => ({ publicKey, baseUrl: (baseUrl ?? "https://frag.dev").replace(/\/$/, "") }),
+    () => ({ publicKey, baseUrl: (baseUrl ?? "https://frag.cash").replace(/\/$/, "") }),
     [publicKey, baseUrl]
   );
   return /* @__PURE__ */ jsx(FragContext.Provider, { value, children });
@@ -79,6 +79,18 @@ async function fetchWithRetry(input, init = {}) {
     attempt += 1;
   }
 }
+function refundPhase(status) {
+  switch (status) {
+    case "succeeded":
+      return "completed";
+    case "processing":
+      return "sent";
+    case "failed":
+      return "failed";
+    default:
+      return "queued";
+  }
+}
 function useFragmentIntent(intentId, opts = {}) {
   const { baseUrl } = useFrag();
   if (intentId !== null && (typeof intentId !== "string" || intentId.length < 3)) {
@@ -125,6 +137,51 @@ function useFragmentIntent(intentId, opts = {}) {
   }, [intentId, baseUrl, interval]);
   return state;
 }
+function useFragmentRefund(refundId, opts = {}) {
+  const { baseUrl } = useFrag();
+  if (refundId !== null && (typeof refundId !== "string" || refundId.length < 3)) {
+    throw new Error("[fragmentpay] useFragmentRefund: refundId must be a non-empty string or null");
+  }
+  const interval = opts.intervalMs ?? 3e3;
+  if (typeof interval !== "number" || interval < 500 || interval > 6e4) {
+    throw new Error("[fragmentpay] useFragmentRefund: intervalMs must be between 500 and 60000");
+  }
+  const [state, setState] = React.useState({ data: null, status: "idle", error: null });
+  React.useEffect(() => {
+    if (!refundId) return;
+    let alive = true;
+    let timer;
+    async function tick() {
+      try {
+        const res = await fetchWithRetry(
+          `${baseUrl}/api/public/refunds/${refundId}/status`,
+          { 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 raw = await res.json();
+        const data = { ...raw, phase: refundPhase(raw.status) };
+        if (!alive) return;
+        setState({ data, status: "ready", error: null });
+        if (!data.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);
+    };
+  }, [refundId, baseUrl, interval]);
+  return state;
+}
 function FragmentPayCheckout({
   intentId,
   onSettled,
@@ -258,7 +315,9 @@ export {
   FragmentPayCheckout,
   FragmentPayProvider,
   fetchWithRetry,
+  refundPhase,
   useCreateIntent,
   useFragmentIntent,
+  useFragmentRefund,
   useFragmentTokens
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragmentpay/react",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "React components for Frag hosted checkout — accept any token, on any chain.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",