@nozle-js/react 0.5.2 → 0.7.0

package/README.md

@@ -1,241 +1,59 @@
 # @nozle-js/react
 
-React SDK for usage-based billing. Hooks and components for entitlements, real-time usage tracking, plan management, and Stripe checkout.
+Browser-safe React components for Nozle's public plan catalog and merchant-controlled checkout.
 
-## Install
+## Credential boundary
 
-```bash
-npm install @nozle-js/react
-```
+- `pk_` is used only for `GET /api/v1/plans`.
+- Secret keys stay on the merchant backend.
+- The React package does not fetch customer billing, invoice, subscription, entitlement, or credit data.
+- The React package never sends a customer ID.
 
-Peer dependencies:
+## Install
 
 ```bash
-npm install react react-dom @stripe/stripe-js @stripe/react-stripe-js
+npm install @nozle-js/react react react-dom @stripe/stripe-js @stripe/react-stripe-js
 ```
 
-## Quick Start
-
-Wrap your app with `BillingProvider`:
+## Merchant-backed checkout
 
 ```tsx
-import { BillingProvider } from "@nozle-js/react";
+import { BillingProvider, PricingTable } from "@nozle-js/react";
 
-function App() {
+export function BillingPage({ csrfToken }: { csrfToken: string }) {
   return (
     <BillingProvider
-      apiKey="pk_live_..."
-      baseUrl="https://api.nozle.app"       // Default: https://api.nozle.app
-      workspaceId="ws_123"                   // Optional: workspace scoping
-      centrifugoUrl="wss://ws.nozle.app/connection/websocket"  // Optional: real-time updates
+      publishableKey={import.meta.env.VITE_NOZLE_PUBLISHABLE_KEY}
+      createCheckout={async ({ planCode, returnUrl }) => {
+        const response = await fetch("/api/billing/checkout", {
+          method: "POST",
+          credentials: "include",
+          headers: {
+            "Content-Type": "application/json",
+            "X-CSRF-Token": csrfToken,
+          },
+          body: JSON.stringify({ planCode, returnUrl }),
+        });
+
+        if (!response.ok) throw new Error("Checkout failed");
+        return response.json();
+      }}
     >
-      <YourApp />
+      <PricingTable returnUrl={window.location.href} highlightPlan="pro" />
     </BillingProvider>
   );
 }
 ```
 
-> **Note:** LLM wrappers (`wrapOpenAI`, `wrapAnthropic`) and server-side methods (`checkAndDeduct`, `customers.upsert`) are only available in `@nozle-js/node`. The React SDK is for client-side billing UI only.
-
-## Hooks
-
-### `useCan(feature)`
-
-Check if a customer has access to a feature.
-
-```tsx
-import { useCan } from "@nozle-js/react";
-
-function MyFeature() {
-  const { allowed, isLoading, error } = useCan("advanced_analytics");
-
-  if (isLoading) return <p>Loading...</p>;
-  if (!allowed) return <p>Upgrade to access this feature.</p>;
-
-  return <div>Feature content here</div>;
-}
-```
-
-### `useUsage(metric)`
-
-Get real-time usage data for a metric. Updates automatically via WebSocket.
-
-```tsx
-import { useUsage } from "@nozle-js/react";
-
-function TokenCounter() {
-  const { data, isLoading } = useUsage("tokens_used");
-
-  if (isLoading || !data) return null;
-
-  return (
-    <p>
-      {data.used.toLocaleString()} / {data.limit.toLocaleString()} tokens used
-    </p>
-  );
-}
-```
-
-### `usePlan()`
-
-Get the customer's current plan and subscription status.
-
-```tsx
-import { usePlan } from "@nozle-js/react";
-
-function CurrentPlan() {
-  const { data } = usePlan();
-
-  if (!data) return null;
-
-  return (
-    <p>
-      Plan: {data.plan_slug} ({data.subscription_status})
-    </p>
-  );
-}
-```
-
-### `usePlans()`
-
-Fetch all available plans.
-
-```tsx
-import { usePlans } from "@nozle-js/react";
-
-function PlanList() {
-  const { plans, isLoading } = usePlans();
-
-  if (isLoading) return <p>Loading plans...</p>;
-
-  return (
-    <ul>
-      {plans.map((plan) => (
-        <li key={plan.code}>
-          {plan.name} — ${(plan.amount_cents / 100).toFixed(2)}/{plan.interval}
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
-### `useCheckout()`
+The merchant endpoint authenticates the user, derives the Nozle customer from the authenticated user or team, validates the plan and HTTPS return URL, and calls Nozle with a restricted server-side `sk_`. Any browser-supplied customer identifier must be ignored or rejected.
 
-Create a Stripe checkout session and render embedded checkout.
-
-```tsx
-import { useCheckout } from "@nozle-js/react";
-
-function UpgradeButton({ planCode }: { planCode: string }) {
-  const { fetchClientSecret, isLoading } = useCheckout();
-
-  const handleUpgrade = async () => {
-    const clientSecret = await fetchClientSecret(planCode);
-    // Use clientSecret with Stripe EmbeddedCheckout
-  };
-
-  return (
-    <button onClick={handleUpgrade} disabled={isLoading}>
-      Upgrade
-    </button>
-  );
-}
-```
-
-### `useSubscribe()`
-
-Create a subscription after successful payment.
-
-```tsx
-import { useSubscribe } from "@nozle-js/react";
-
-function AfterPayment({ planCode }: { planCode: string }) {
-  const { subscribe, isLoading } = useSubscribe();
-
-  const handleComplete = async () => {
-    await subscribe(planCode);
-  };
-
-  return (
-    <button onClick={handleComplete} disabled={isLoading}>
-      Activate Subscription
-    </button>
-  );
-}
-```
+`createCheckout` may return a hosted URL, an embedded Stripe client secret, `type: "completed"`, or `type: "scheduled"`. Paid plans activate only after Nozle processes verified Stripe success; a browser redirect is not proof of payment.
 
 ## Components
 
-Pre-built UI components with built-in styling. No CSS imports needed.
-
-### `UsageMeter`
-
-Displays usage with bar, ring, or minimal variants.
-
-```tsx
-import { UsageMeter } from "@nozle-js/react";
-
-<UsageMeter metric="tokens_used" variant="bar" />
-<UsageMeter metric="tokens_used" variant="ring" />
-<UsageMeter metric="tokens_used" variant="minimal" />
-```
-
-### `PlanBadge`
-
-Shows the current plan with status indicator.
-
-```tsx
-import { PlanBadge } from "@nozle-js/react";
-
-<PlanBadge variant="pill" />
-<PlanBadge variant="text" />
-<PlanBadge variant="icon" />
-```
-
-### `UpgradePrompt`
-
-Conditionally renders an upgrade prompt when a feature is gated.
-
-```tsx
-import { UpgradePrompt } from "@nozle-js/react";
-
-<UpgradePrompt feature="advanced_analytics" variant="card" upgradeUrl="/upgrade" />
-<UpgradePrompt feature="advanced_analytics" variant="banner" />
-<UpgradePrompt feature="advanced_analytics" variant="inline" />
-```
-
-## Tailwind CSS Preset
-
-Optional Tailwind preset for styling the `data-nozle` attributes on components.
-
-```ts
-// tailwind.config.ts
-import { nozlePreset } from "@nozle-js/react/styles/preset";
-
-export default {
-  presets: [nozlePreset],
-};
-```
-
-## TypeScript
-
-All hooks and components are fully typed. Exported types:
-
-```ts
-import type {
-  BillingState,
-  UseCanResult,
-  UseUsageResult,
-  UsePlanResult,
-  UseCheckoutResult,
-  Plan,
-  UsageMeterProps,
-  PlanBadgeProps,
-  UpgradePromptProps,
-} from "@nozle-js/react";
-```
-
-## License
+- `PricingTable` and `usePlans` read the public catalog with the publishable key.
+- `CheckoutButton`, `UpgradeButton`, `UpgradeModal`, and the default `PricingTable` CTA call the merchant's `createCheckout` callback.
+- `Checkout` renders Stripe hosted/embedded checkout results supplied by the merchant.
+- Gates, usage displays, `PlanBadge`, and `PaymentMethodDisplay` are presentational and consume caller-supplied data.
 
-Proprietary
+Customer billing, invoices, cancellation, top-ups, subscriptions, entitlements, and credits belong behind authenticated merchant endpoints. Never put an `sk_`, master key, or internal credential in browser code.