@nozle-js/react 0.10.0 → 0.10.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nozle
+
+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

@@ -13,7 +13,7 @@ React components for Nozle's public catalog, checkout, and customer billing port
 ## Install
 
 ```bash
-npm install @nozle-js/react@0.10.0 react react-dom @stripe/stripe-js @stripe/react-stripe-js
+npm install @nozle-js/react@0.10.2 react react-dom @stripe/stripe-js @stripe/react-stripe-js
 ```
 
 ## Merchant-backed checkout
@@ -50,6 +50,79 @@ The merchant endpoint authenticates the user, derives the Nozle customer from th
 
 `createCheckout` returns a `stripe`, `razorpay`, `hosted`, `processing`, `completed`, or `scheduled` result. Nozle payment fulfillment determines activation; Razorpay requires capture. A browser redirect or callback alone does not prove activation.
 
+## Payment providers: Stripe and Razorpay
+
+Your merchant backend returns whatever result Nozle gives for the customer's connected provider, and `CheckoutButton` handles each `type`:
+
+| Result `type` | Provider | What `CheckoutButton` does |
+| --- | --- | --- |
+| `stripe` | Stripe | Calls `onStripeClientSecret` with the `cs_` Embedded Checkout secret. Render `Checkout` with it |
+| `razorpay` | Razorpay | Loads Razorpay's `checkout.js`, opens the modal, then calls your `verifyCheckout` and polls your `getCheckoutStatus` (30 attempts, one second apart) |
+| `hosted` | Razorpay | Declared in the result types; `POST /checkout` does not return it for Razorpay. Invoice payment URLs and credit top-ups return a `payment_url` (an rzp.io payment link) with no checkout id to poll; the React component navigates to `payment_url` (HTTPS only) if one is returned |
+| `processing` | Razorpay or Stripe | Polls `getCheckoutStatus`. For Razorpay it opens the order once ready; Stripe returns `processing` when a quoted upgrade is replayed while its webhook is pending |
+| `completed`, `scheduled` | Either | Calls `onComplete` or `onScheduled`. No payment is collected |
+
+Plan and invoice checkout return the Stripe secret but never a Stripe-hosted URL or your Stripe publishable key (credit top-up purchases do return a Stripe-hosted `payment_url`, valid for 24 hours), so pass your own `pk_` key for the connected Stripe account to `Checkout`. For Razorpay, the server supplies `key_id`, `order_id`, amount and currency; `razorpayKeyId` is deprecated. Razorpay supports only INR.
+
+```tsx
+import { useState } from "react";
+import { BillingProvider, Checkout, CheckoutButton } from "@nozle-js/react";
+
+export function Upgrade({ csrfToken }: { csrfToken: string }) {
+  const [clientSecret, setClientSecret] = useState<string>();
+  const post = (path: string, body: object) =>
+    fetch(path, {
+      method: "POST",
+      credentials: "include",
+      headers: { "Content-Type": "application/json", "X-CSRF-Token": csrfToken },
+      body: JSON.stringify(body),
+    }).then((response) => {
+      if (!response.ok) throw new Error("Request failed");
+      return response.json();
+    });
+
+  return (
+    <BillingProvider
+      publishableKey="pk_your_catalog_key"
+      createCheckout={({ planCode, returnUrl, idempotencyKey }) =>
+        post("/api/billing/checkout", { planCode, returnUrl, idempotencyKey })
+      }
+      // Razorpay only. Your backend calls nozle.verifyCheckout / nozle.checkoutStatus
+      // with an sk_ key and the customer and subscription scope it derived.
+      verifyCheckout={(checkoutId, verification) =>
+        post(`/api/billing/checkout/${checkoutId}/verify`, verification)
+      }
+      getCheckoutStatus={(checkoutId) =>
+        fetch(`/api/billing/checkout/${checkoutId}`, { credentials: "include" }).then(
+          (response) => {
+            if (!response.ok) throw new Error("Status failed");
+            return response.json();
+          },
+        )
+      }
+    >
+      <CheckoutButton
+        planCode="pro_monthly"
+        onStripeClientSecret={setClientSecret}
+        onSuccess={() => window.location.reload()}
+        onComplete={() => window.location.reload()}
+      />
+      {clientSecret && (
+        <Checkout
+          clientSecret={clientSecret}
+          publishableKey="pk_live_your_stripe_key"
+          onComplete={() => window.location.reload()}
+        />
+      )}
+    </BillingProvider>
+  );
+}
+```
+
+The Stripe `Checkout` component's `onComplete` does not fire when the session redirects to the `return_url`. Show success from the return page, or reload billing status there, rather than relying on `onComplete` alone. A new-subscription checkout retried while the subscription is still incomplete fails with HTTP 422 `subscription_incomplete`, even with the same idempotency key; your backend can recover with an invoice checkout for the `invoice_id` from the first response. An invoice checkout retried with the same key and a different body currently returns HTTP 500, not 409.
+
+`CheckoutButton` rejects a Razorpay result without `checkout_id`, `key_id` and `order_id`, and fails when `BillingProvider` has no `verifyCheckout`. A modal `payment.failed` event shows "Payment failed. You can retry checkout." For a UPI AutoPay mandate, pass `registerMandate` to `CheckoutButton`; the modal then receives `customer_id` and `recurring: "1"` from the result. Show success only after both `status` and `fulfillment_status` are `succeeded`. See the [Stripe](https://docs.nozle.dev/integrations/stripe) and [Razorpay](https://docs.nozle.dev/integrations/razorpay) integration guides.
+
 ## Components
 
 - `PricingTable` and `usePlans` read the public catalog with the publishable key.
@@ -147,7 +220,7 @@ formats amounts/dates. Errors use `code: "session" | "unauthorized" | "request"
 Pass `planChangeActions` to `BillingPortal`, or use the standalone `PlanChangeControl`.
 Its adapter provides `load`, `status`, `preview`, `apply`, and `withdraw`; use
 `verifyCheckout` and `getCheckoutStatus` for scoped payment verification/recovery.
-The Node.js `0.9.0` and Python `0.9.0` SDKs provide the matching backend methods.
+The Node.js `0.9.0` and Python `0.9.0` SDKs introduced the matching backend methods. Use `0.9.1` of either backend SDK for the Feature Event timestamp fix used by provider capture.
 
 Load eligible plans for the selected external subscription, confirm the signed quote,
 and retain the same quote and idempotency key for uncertain retries. Upgrades activate
@@ -159,3 +232,7 @@ See the [billing portal guide](https://docs.nozle.dev/sdks/react/billing-portal)
 complete typed adapters, standalone controls, and the runnable Node/Python integrations.
 The hosted Nozle backend supports these flows; self-hosted deployments need the matching
 subscription-management endpoints and cancellation-date guard.
+
+## License
+
+Proprietary. Contact Nozle about licensing.

package/dist/index.cjs

@@ -2872,8 +2872,12 @@ function usePlans() {
   const { client } = useBillingContext();
   const [plans, setPlans] = React.useState([]);
   const [isLoading, setIsLoading] = React.useState(true);
+  const [error, setError] = React.useState(null);
   React.useEffect(() => {
     let cancelled = false;
+    setIsLoading(true);
+    setError(null);
+    setPlans([]);
     if (!client) {
       setIsLoading(false);
       return;
@@ -2882,6 +2886,12 @@ function usePlans() {
       if (!response.ok) throw new Error(`HTTP ${response.status}`);
       const data = await response.json();
       if (!cancelled) setPlans(data.plans ?? []);
+    }).catch((cause) => {
+      if (!cancelled) {
+        setError(
+          cause instanceof Error ? cause : new Error("Failed to load plans")
+        );
+      }
     }).finally(() => {
       if (!cancelled) setIsLoading(false);
     });
@@ -2889,7 +2899,7 @@ function usePlans() {
       cancelled = true;
     };
   }, [client]);
-  return { plans, isLoading };
+  return { plans, isLoading, error };
 }
 function useCheckout2() {
   const { createCheckout } = useBillingContext();
@@ -3220,10 +3230,11 @@ function PricingTable({
     }
     let cancelled = false;
     client.catalogFetch("/api/v1/plans").then(async (res) => {
-      if (!cancelled && res.ok) {
-        const data = await res.json();
-        setPlans(data.plans || []);
-      }
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      if (!cancelled) setPlans(data.plans || []);
+    }).catch((cause) => {
+      if (!cancelled) setCheckoutError(`Plans could not be loaded: ${cause instanceof Error ? cause.message : "unknown error"}`);
     }).finally(() => {
       if (!cancelled) setLoading(false);
     });