@crediball/react 0.3.2 → 0.3.7

package/dist/CrediballProvider.d.ts

@@ -12,14 +12,12 @@ export interface CrediballProviderProps {
      */
     onTopup?: (amount: number) => void | Promise<void>;
     /**
-     * Auto-detect insufficient-credit responses (HTTP 402 with
-     * `{ code: "insufficient_credits" }`) from any fetch() call and open the paywall
-     * automatically — no per-call wiring. Defaults to true. Set false to only open
-     * the paywall manually via useCrediball().showPaywall().
+     * Auto-detect insufficient-credit responses from any fetch() call and open the
+     * paywall automatically — no per-call wiring. Defaults to true. Set false to only
+     * open the paywall manually via useCrediball().showPaywall().
      *
-     * Note: this only intercepts responses with HTTP 402. Streaming (SSE) routes that
-     * surface credit errors as stream events will not be caught automatically — call
-     * showPaywall() manually from your SSE error handler in those cases.
+     * Handles both HTTP 402 (regular JSON routes) and HTTP 200 text/event-stream /
+     * ndjson (streaming/SSE routes where the error arrives as a stream chunk).
      */
     watchFetch?: boolean;
     /** Allow a free-form amount entry in the paywall. */
@@ -56,8 +54,8 @@ interface CrediballContextValue {
  * Crediball's error), the paywall appears automatically — no extra code per call.
  * You can also open it yourself with useCrediball().showPaywall().
  *
- * For SSE/streaming routes: the 402 is surfaced as a stream event, not an HTTP status,
- * so watchFetch won't catch it. Call showPaywall() manually from your SSE error handler.
+ * SSE/streaming routes (text/event-stream, ndjson) are also handled automatically —
+ * the watcher scans each chunk for credit errors, so no manual wiring is needed.
  */
 export declare function CrediballProvider({ children, amounts, onTopup, watchFetch, allowCustom, customMin, customMax, currencySymbol, title, description, accentColor, }: CrediballProviderProps): import("react").JSX.Element;
 /**

package/dist/CrediballProvider.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { PaywallModal } from "./PaywallModal";
 import { subscribeFetchWatcher } from "./fetchWatcher";
+import { subscribeInsufficientCredits } from "./creditEvent";
 const CrediballContext = createContext(null);
 /**
  * Pattern B, automated. Wrap your app once:
@@ -15,8 +16,8 @@ const CrediballContext = createContext(null);
  * Crediball's error), the paywall appears automatically — no extra code per call.
  * You can also open it yourself with useCrediball().showPaywall().
  *
- * For SSE/streaming routes: the 402 is surfaced as a stream event, not an HTTP status,
- * so watchFetch won't catch it. Call showPaywall() manually from your SSE error handler.
+ * SSE/streaming routes (text/event-stream, ndjson) are also handled automatically —
+ * the watcher scans each chunk for credit errors, so no manual wiring is needed.
  */
 export function CrediballProvider({ children, amounts = [5, 10, 20], onTopup, watchFetch = true, allowCustom = false, customMin, customMax, currencySymbol = "€", title, description, accentColor, }) {
     const [open, setOpen] = useState(false);
@@ -25,6 +26,10 @@ export function CrediballProvider({ children, amounts = [5, 10, 20], onTopup, wa
     // Keep a ref so the fetch-watcher closure always calls the latest version.
     const showPaywallRef = useRef(showPaywall);
     showPaywallRef.current = showPaywall;
+    // Listen for the global credit-error event (fired by notifyInsufficientCredits()
+    // or the fetch watcher). Always active — works regardless of how the request
+    // was made (fetch, XHR, AI SDK internals, etc.).
+    useEffect(() => subscribeInsufficientCredits(() => showPaywallRef.current()), []);
     useEffect(() => {
         if (!watchFetch)
             return;

package/dist/creditEvent.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Global custom-event bus for insufficient-credits signals.
+ *
+ * Any code — a useChat onError, an XHR error handler, a Redux middleware, a
+ * server action catch block — can call notifyInsufficientCredits() and every
+ * mounted CrediballProvider / usePaywall instance will open the paywall.
+ *
+ * This decouples the signal source from the UI, so the paywall works regardless
+ * of how the HTTP request was made (fetch, XHR, EventSource, AI SDK internals…).
+ */
+/**
+ * Fire the global insufficient-credits signal. Safe to call from anywhere in
+ * the app — server components excluded (DOM only). Every mounted paywall
+ * component will react to it automatically.
+ */
+export declare function notifyInsufficientCredits(): void;
+/**
+ * Subscribe to the global insufficient-credits signal.
+ * Returns an unsubscribe function for use in useEffect cleanup.
+ */
+export declare function subscribeInsufficientCredits(listener: () => void): () => void;

package/dist/creditEvent.js

@@ -0,0 +1,31 @@
+/**
+ * Global custom-event bus for insufficient-credits signals.
+ *
+ * Any code — a useChat onError, an XHR error handler, a Redux middleware, a
+ * server action catch block — can call notifyInsufficientCredits() and every
+ * mounted CrediballProvider / usePaywall instance will open the paywall.
+ *
+ * This decouples the signal source from the UI, so the paywall works regardless
+ * of how the HTTP request was made (fetch, XHR, EventSource, AI SDK internals…).
+ */
+const EVENT = "crediball:insufficient-credits";
+/**
+ * Fire the global insufficient-credits signal. Safe to call from anywhere in
+ * the app — server components excluded (DOM only). Every mounted paywall
+ * component will react to it automatically.
+ */
+export function notifyInsufficientCredits() {
+    if (typeof window === "undefined")
+        return;
+    window.dispatchEvent(new CustomEvent(EVENT));
+}
+/**
+ * Subscribe to the global insufficient-credits signal.
+ * Returns an unsubscribe function for use in useEffect cleanup.
+ */
+export function subscribeInsufficientCredits(listener) {
+    if (typeof window === "undefined")
+        return () => { };
+    window.addEventListener(EVENT, listener);
+    return () => window.removeEventListener(EVENT, listener);
+}

package/dist/fetchWatcher.d.ts

@@ -1,13 +1,24 @@
 /**
- * Module-level singleton that patches window.fetch once and fans out to all
- * registered listeners (from CrediballProvider and/or usePaywall). Only one
- * fetch patch exists at a time regardless of how many components subscribe.
- * Reference-counted: the patch is removed when the last listener unsubscribes.
+ * Patches window.fetch at module-import time — before any React component
+ * mounts and before any AI SDK can capture the fetch reference. This is the
+ * key difference from installing the patch in a useEffect: by the time a
+ * useEffect runs, the Vercel AI SDK (and others) may have already resolved
+ * their fetch reference and bypass the patch entirely.
+ *
+ * Handles three credit-error surfaces:
+ *   1. HTTP 402 with { code: "insufficient_credits" } — regular JSON routes.
+ *   2. HTTP 200 streaming body containing "insufficient_credits" — SSE, ndjson,
+ *      or Vercel AI SDK data-stream (text/plain) routes.
+ *   3. Manual call to notifyInsufficientCredits() from any error handler.
  */
 type Listener = () => void;
 /**
- * Subscribe to insufficient-credits 402 events detected in window.fetch.
- * Returns an unsubscribe function — call it in your useEffect cleanup.
+ * Subscribe to insufficient-credits events detected in window.fetch.
+ * Returns an unsubscribe function for use in useEffect cleanup.
+ *
+ * The fetch patch is installed at module load time regardless of whether
+ * anyone calls this function. This exists for components that need a direct
+ * callback rather than the global DOM event.
  */
 export declare function subscribeFetchWatcher(listener: Listener): () => void;
 export {};

package/dist/fetchWatcher.js

@@ -1,15 +1,67 @@
 /**
- * Module-level singleton that patches window.fetch once and fans out to all
- * registered listeners (from CrediballProvider and/or usePaywall). Only one
- * fetch patch exists at a time regardless of how many components subscribe.
- * Reference-counted: the patch is removed when the last listener unsubscribes.
+ * Patches window.fetch at module-import time — before any React component
+ * mounts and before any AI SDK can capture the fetch reference. This is the
+ * key difference from installing the patch in a useEffect: by the time a
+ * useEffect runs, the Vercel AI SDK (and others) may have already resolved
+ * their fetch reference and bypass the patch entirely.
+ *
+ * Handles three credit-error surfaces:
+ *   1. HTTP 402 with { code: "insufficient_credits" } — regular JSON routes.
+ *   2. HTTP 200 streaming body containing "insufficient_credits" — SSE, ndjson,
+ *      or Vercel AI SDK data-stream (text/plain) routes.
+ *   3. Manual call to notifyInsufficientCredits() from any error handler.
  */
-let _original = null;
+import { notifyInsufficientCredits } from "./creditEvent";
 const _listeners = new Set();
-function install() {
-    if (typeof window === "undefined" || _original !== null)
-        return;
-    _original = window.fetch;
+function fire() {
+    notifyInsufficientCredits();
+    _listeners.forEach((fn) => fn());
+}
+function isStreamingContentType(ct) {
+    return (ct.includes("text/event-stream") ||
+        ct.includes("ndjson") ||
+        // Vercel AI SDK uses text/plain for its data-stream protocol
+        ct.includes("text/plain"));
+}
+/**
+ * Tee the streaming response body and scan each chunk for the
+ * `insufficient_credits` signal. Returns a new Response whose body is the
+ * pass-through branch so the calling code receives the full, unmodified stream.
+ */
+function watchStream(res) {
+    if (!res.body)
+        return res;
+    const [scanBranch, passBranch] = res.body.tee();
+    (async () => {
+        const reader = scanBranch.getReader();
+        const decoder = new TextDecoder();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (decoder.decode(value, { stream: true }).includes("insufficient_credits")) {
+                    fire();
+                    reader.cancel().catch(() => { });
+                    return;
+                }
+            }
+        }
+        catch {
+            // stream error — ignore
+        }
+    })();
+    return new Response(passBranch, {
+        status: res.status,
+        statusText: res.statusText,
+        headers: res.headers,
+    });
+}
+// ── Install patch immediately at module load time ─────────────────────────
+// Running here (not in a useEffect) ensures the patch is in place before any
+// SDK or framework code captures the window.fetch reference.
+if (typeof window !== "undefined") {
+    const _original = window.fetch;
     window.fetch = async (...args) => {
         const res = await _original(...args);
         if (res.status === 402) {
@@ -20,38 +72,35 @@ function install() {
                 if (body != null &&
                     typeof body === "object" &&
                     body.code === "insufficient_credits") {
-                    _listeners.forEach((fn) => fn());
+                    fire();
                 }
             })
                 .catch(() => {
-                // Non-JSON 402. Fire listeners anyway — a 402 from the app's own API
-                // route is almost certainly a credit shortage. Set watchFetch=false
-                // and call trigger() manually if your app uses 402 for other purposes.
-                _listeners.forEach((fn) => fn());
+                // Non-JSON 402 — fire anyway.
+                fire();
             });
+            return res;
+        }
+        if (res.body) {
+            const ct = res.headers.get("content-type") ?? "";
+            if (isStreamingContentType(ct)) {
+                return watchStream(res);
+            }
         }
         return res;
     };
 }
-function uninstall() {
-    if (typeof window === "undefined" || _original === null)
-        return;
-    window.fetch = _original;
-    _original = null;
-}
 /**
- * Subscribe to insufficient-credits 402 events detected in window.fetch.
- * Returns an unsubscribe function — call it in your useEffect cleanup.
+ * Subscribe to insufficient-credits events detected in window.fetch.
+ * Returns an unsubscribe function for use in useEffect cleanup.
+ *
+ * The fetch patch is installed at module load time regardless of whether
+ * anyone calls this function. This exists for components that need a direct
+ * callback rather than the global DOM event.
  */
 export function subscribeFetchWatcher(listener) {
     if (typeof window === "undefined")
         return () => { };
-    if (_listeners.size === 0)
-        install();
     _listeners.add(listener);
-    return () => {
-        _listeners.delete(listener);
-        if (_listeners.size === 0)
-            uninstall();
-    };
+    return () => _listeners.delete(listener);
 }

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export { CreditsBadge, type CreditsBadgeProps } from "./CreditsBadge";
 export { PaywallModal, type PaywallModalProps, type PackageOption, type SubscriptionPlanOption, type ActiveSubscriptionInfo, } from "./PaywallModal";
 export { CreditIndicator, type CreditIndicatorProps } from "./CreditIndicator";
 export { CrediballProvider, useCrediball, type CrediballProviderProps, } from "./CrediballProvider";
-export { usePaywall, type UsePaywallProps, type UsePaywallResult, } from "./usePaywall";
+export { usePaywall, isInsufficientCreditsError, type UsePaywallProps, type UsePaywallResult, } from "./usePaywall";
 export { tokens, type CrediballThemeOverrides } from "./theme";
+export { notifyInsufficientCredits } from "./creditEvent";

package/dist/index.js

@@ -4,5 +4,6 @@ export { CreditsBadge } from "./CreditsBadge";
 export { PaywallModal, } from "./PaywallModal";
 export { CreditIndicator } from "./CreditIndicator";
 export { CrediballProvider, useCrediball, } from "./CrediballProvider";
-export { usePaywall, } from "./usePaywall";
+export { usePaywall, isInsufficientCreditsError, } from "./usePaywall";
 export { tokens } from "./theme";
+export { notifyInsufficientCredits } from "./creditEvent";

package/dist/usePaywall.d.ts

@@ -1,21 +1,29 @@
 import { type ReactElement } from "react";
-import { type PaywallModalProps, type PackageOption } from "./PaywallModal";
-export type UsePaywallProps = Pick<PaywallModalProps, "amounts" | "amountPrefix" | "packages" | "allowCustom" | "customMin" | "customMax" | "currencySymbol" | "title" | "description" | "accentColor" | "balance" | "balanceRate" | "currency"> & {
-    /** Called when the user picks a preset or custom top-up amount. */
+import { type PaywallModalProps, type PackageOption, type SubscriptionPlanOption } from "./PaywallModal";
+/**
+ * Props for usePaywall. Accepts everything PaywallModal accepts, except the
+ * three props the hook manages itself (open, onClose, onAdd). Callback props
+ * that the hook wraps (onSelectPackage, onSelectPlan) are overridden to also
+ * accept async handlers. Add watchFetch to auto-open on detected credit errors.
+ */
+export type UsePaywallProps = Omit<PaywallModalProps, "open" | "onClose" | "onAdd" | "style"> & {
+    /** Called when the user picks a legacy preset/custom top-up amount. */
     onTopup?: (amount: number) => void | Promise<void>;
-    /** Called when the user picks a package from `packages`. */
+    /** Called when the user picks a one-time package (async override). */
     onSelectPackage?: (pkg: PackageOption) => void | Promise<void>;
+    /** Called when the user picks a subscription plan (async override). */
+    onSelectPlan?: (plan: SubscriptionPlanOption) => void | Promise<void>;
     /**
-     * Auto-detect HTTP 402 `insufficient_credits` responses from any fetch() call
-     * and open the paywall automatically. Defaults to false.
+     * Auto-detect credit errors from any fetch() call and open the paywall
+     * automatically. Defaults to false.
      *
      * Set to true only if you are NOT using <CrediballProvider> and want automatic
      * interception. If your app already wraps with <CrediballProvider watchFetch>
      * (the recommended pattern), leave this false — double-patching is harmless
      * but unnecessary.
      *
-     * Note: SSE/streaming routes surface credit errors as stream events (HTTP 200),
-     * not HTTP 402 — call trigger() manually from your stream error handler.
+     * Both HTTP 402 (regular routes) and text/event-stream / ndjson streaming
+     * responses are handled automatically.
      */
     watchFetch?: boolean;
 };
@@ -44,6 +52,16 @@ export interface UsePaywallResult {
      *   );
      */
     paywall: ReactElement;
+    /**
+     * Pass directly to useChat / useCompletion as the `onError` prop. Triggers
+     * the paywall automatically when the Vercel AI SDK surfaces a credit error
+     * from a streaming route (the AI SDK captures `fetch` before window.fetch
+     * patching applies, so watchFetch cannot intercept streaming responses).
+     *
+     *   const { paywall, onError } = usePaywall({ ... });
+     *   const { messages } = useChat({ api: '/api/generate', onError });
+     */
+    onError: (error: Error) => void;
 }
 /**
  * Manages a Crediball paywall modal with a simple, misuse-proof API.
@@ -54,20 +72,18 @@ export interface UsePaywallResult {
  * reopening it. This is what makes the paywall reliably reappear on retry.
  *
  *   const { trigger, paywall } = usePaywall({
- *     amounts: [5, 10, 20],
- *     onTopup: async (eur) => checkout(eur),
+ *     packages: pkgs,
+ *     subscriptionPlans: plans,
+ *     activeSubscription: activeSub,
+ *     onSelectPackage: async (pkg) => checkout(pkg),
+ *     onSelectPlan: async (plan) => subscribe(plan),
+ *     onCancelSubscription: async (id) => cancel(id),
  *   });
- *
- *   try {
- *     const page = await meter.wrapMeteredAction(userId, "generate_page", async () => {
- *       const res = await streamAI(prompt);
- *       return { result: res, tokens: res.usage.totalTokens };
- *     });
- *   } catch (e) {
- *     if (e instanceof InsufficientCreditsError) trigger(); // always call — no guard
- *     else throw e;
- *   }
- *
- *   return <div>...<button onClick={generate}>Generate</button>...{paywall}</div>;
  */
-export declare function usePaywall({ amounts, amountPrefix, packages, onTopup, onSelectPackage, allowCustom, customMin, customMax, currencySymbol, title, description, accentColor, balance, balanceRate, currency, watchFetch, }?: UsePaywallProps): UsePaywallResult;
+export declare function usePaywall({ onTopup, onSelectPackage, onSelectPlan, watchFetch, ...rest }?: UsePaywallProps): UsePaywallResult;
+/**
+ * Returns true when an error from the Vercel AI SDK (or any other source)
+ * represents an insufficient-credits rejection from Crediball. Useful when
+ * you need to check the error yourself before calling trigger().
+ */
+export declare function isInsufficientCreditsError(error: unknown): boolean;

package/dist/usePaywall.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { PaywallModal } from "./PaywallModal";
+import { PaywallModal, } from "./PaywallModal";
 import { subscribeFetchWatcher } from "./fetchWatcher";
+import { subscribeInsufficientCredits, notifyInsufficientCredits } from "./creditEvent";
 /**
  * Manages a Crediball paywall modal with a simple, misuse-proof API.
  *
@@ -12,29 +13,24 @@ import { subscribeFetchWatcher } from "./fetchWatcher";
  * reopening it. This is what makes the paywall reliably reappear on retry.
  *
  *   const { trigger, paywall } = usePaywall({
- *     amounts: [5, 10, 20],
- *     onTopup: async (eur) => checkout(eur),
+ *     packages: pkgs,
+ *     subscriptionPlans: plans,
+ *     activeSubscription: activeSub,
+ *     onSelectPackage: async (pkg) => checkout(pkg),
+ *     onSelectPlan: async (plan) => subscribe(plan),
+ *     onCancelSubscription: async (id) => cancel(id),
  *   });
- *
- *   try {
- *     const page = await meter.wrapMeteredAction(userId, "generate_page", async () => {
- *       const res = await streamAI(prompt);
- *       return { result: res, tokens: res.usage.totalTokens };
- *     });
- *   } catch (e) {
- *     if (e instanceof InsufficientCreditsError) trigger(); // always call — no guard
- *     else throw e;
- *   }
- *
- *   return <div>...<button onClick={generate}>Generate</button>...{paywall}</div>;
  */
-export function usePaywall({ amounts, amountPrefix, packages, onTopup, onSelectPackage, allowCustom, customMin, customMax, currencySymbol, title, description, accentColor, balance, balanceRate, currency, watchFetch = false, } = {}) {
+export function usePaywall({ onTopup, onSelectPackage, onSelectPlan, watchFetch = false, ...rest } = {}) {
     const [isOpen, setIsOpen] = useState(false);
     const trigger = useCallback(() => setIsOpen(true), []);
     const dismiss = useCallback(() => setIsOpen(false), []);
-    // Keep a ref so the fetch-watcher closure always calls the latest trigger.
+    // Keep a ref so closures always call the latest trigger.
     const triggerRef = useRef(trigger);
     triggerRef.current = trigger;
+    // Always listen for the global credit-error event — works regardless of how
+    // the request was made (fetch, XHR, AI SDK internals, etc.).
+    useEffect(() => subscribeInsufficientCredits(() => triggerRef.current()), []);
     useEffect(() => {
         if (!watchFetch)
             return;
@@ -48,6 +44,27 @@ export function usePaywall({ amounts, amountPrefix, packages, onTopup, onSelectP
         setIsOpen(false);
         await onSelectPackage?.(pkg);
     }, [onSelectPackage]);
-    const paywall = (_jsx(PaywallModal, { open: isOpen, amounts: amounts, amountPrefix: amountPrefix, packages: packages, onAdd: handleTopup, onSelectPackage: handleSelectPackage, onClose: dismiss, allowCustom: allowCustom, customMin: customMin, customMax: customMax, currencySymbol: currencySymbol, title: title, description: description, accentColor: accentColor, balance: balance, balanceRate: balanceRate, currency: currency }));
-    return { trigger, dismiss, isOpen, paywall };
+    const handleSelectPlan = useCallback(async (plan) => {
+        setIsOpen(false);
+        await onSelectPlan?.(plan);
+    }, [onSelectPlan]);
+    // onError fires the global event so ALL mounted paywall instances react,
+    // not just this hook's local state.
+    const onError = useCallback((error) => {
+        if (isInsufficientCreditsError(error))
+            notifyInsufficientCredits();
+    }, []);
+    const paywall = (_jsx(PaywallModal, { ...rest, open: isOpen, onAdd: handleTopup, onSelectPackage: handleSelectPackage, onSelectPlan: handleSelectPlan, onClose: dismiss }));
+    return { trigger, dismiss, isOpen, paywall, onError };
+}
+/**
+ * Returns true when an error from the Vercel AI SDK (or any other source)
+ * represents an insufficient-credits rejection from Crediball. Useful when
+ * you need to check the error yourself before calling trigger().
+ */
+export function isInsufficientCreditsError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const msg = error.message.toLowerCase();
+    return msg.includes("insufficient_credits") || msg.includes("insufficient credits");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/react",
-  "version": "0.3.2",
+  "version": "0.3.7",
   "description": "Drop-in React components for showing Crediball credits inside your AI app.",
   "license": "MIT",
   "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",