@solvapay/react 1.0.0-preview.1 → 1.0.0-preview.11

package/README.md

@@ -1,34 +1,314 @@
 # @solvapay/react
 
-Payment components for SolvaPay with Stripe integration.
+Headless React components and hooks for SolvaPay payment integration with Stripe.
 
 ## Install
+
 ```bash
 pnpm add @solvapay/react
 ```
 
-## Usage
+## Peer Dependencies
+
+- `react` ^18.2.0 || ^19.0.0
+- `react-dom` ^18.2.0 || ^19.0.0
+
+## Quick Start
+
+### Zero-Config Usage (Recommended)
+
+```tsx
+import { SolvaPayProvider, PaymentForm, useSubscription } from '@solvapay/react';
+
+export default function App() {
+  return (
+    <SolvaPayProvider>
+      <CheckoutPage />
+    </SolvaPayProvider>
+  );
+}
+```
+
+By default, `SolvaPayProvider` uses:
+- `/api/check-subscription` for subscription checks
+- `/api/create-payment-intent` for payment creation
+- `/api/process-payment` for payment processing
+
+### Custom API Routes
+
 ```tsx
 import { SolvaPayProvider, PaymentForm } from '@solvapay/react';
 
-export default function CheckoutPage() {
+export default function App() {
+  return (
+    <SolvaPayProvider
+      config={{
+        api: {
+          checkSubscription: '/api/custom/subscription',
+          createPayment: '/api/custom/payment',
+          processPayment: '/api/custom/process',
+        },
+      }}
+    >
+      <CheckoutPage />
+    </SolvaPayProvider>
+  );
+}
+```
+
+### With Supabase Authentication
+
+```tsx
+import { SolvaPayProvider } from '@solvapay/react';
+import { createSupabaseAuthAdapter } from '@solvapay/react-supabase';
+
+export default function App() {
+  const adapter = createSupabaseAuthAdapter({
+    supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    supabaseAnonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+  });
+
+  return (
+    <SolvaPayProvider config={{ auth: { adapter } }}>
+      <CheckoutPage />
+    </SolvaPayProvider>
+  );
+}
+```
+
+### Fully Custom Implementation
+
+```tsx
+import { SolvaPayProvider } from '@solvapay/react';
+
+export default function App() {
   return (
     <SolvaPayProvider
-      amount={999}
-      currency="USD"
-      planRef="pln_abc123"
+      createPayment={async ({ planRef, agentRef }) => {
+        const res = await fetch('/api/custom/payment', {
+          method: 'POST',
+          body: JSON.stringify({ planRef, agentRef }),
+        });
+        if (!res.ok) throw new Error('Failed to create payment');
+        return res.json();
+      }}
+      checkSubscription={async (customerRef) => {
+        const res = await fetch(`/api/custom/subscription?customerRef=${customerRef}`);
+        if (!res.ok) throw new Error('Failed to check subscription');
+        return res.json();
+      }}
     >
-      <PaymentForm
-        returnUrl="/checkout/success"
-        onSuccess={(paymentIntent) => {
-          console.log('Payment successful!', paymentIntent);
-        }}
-      />
+      <CheckoutPage />
     </SolvaPayProvider>
   );
 }
 ```
 
-Peer deps: react, react-dom
+## Components
+
+### SolvaPayProvider
+
+Headless context provider that manages subscription state, payment methods, and customer references.
+
+**Features:**
+- Zero-config with sensible defaults
+- Auto-fetches subscriptions on mount
+- Built-in localStorage caching with user validation
+- Supports auth adapters for extracting user IDs and tokens
+- Customizable API routes via config
+
+**Props:**
+- `config?: SolvaPayConfig` - Configuration object (optional)
+  - `config.api?` - Custom API route paths
+  - `config.auth?` - Auth adapter configuration
+- `createPayment?: (params: { planRef: string; agentRef?: string }) => Promise<PaymentIntentResult>` - Custom payment creation function (optional, overrides config)
+- `checkSubscription?: (customerRef: string) => Promise<CustomerSubscriptionData>` - Custom subscription check function (optional, overrides config)
+- `processPayment?: (params: { paymentIntentId: string; agentRef: string; planRef?: string }) => Promise<ProcessPaymentResult>` - Custom payment processing function (optional)
+- `children: React.ReactNode` - Child components
+
+**Config Options:**
+```tsx
+interface SolvaPayConfig {
+  api?: {
+    checkSubscription?: string;      // Default: '/api/check-subscription'
+    createPayment?: string;           // Default: '/api/create-payment-intent'
+    processPayment?: string;          // Default: '/api/process-payment'
+  };
+  auth?: {
+    adapter?: AuthAdapter;           // Auth adapter for extracting user ID/token
+    getToken?: () => Promise<string | null>;  // Deprecated: use adapter
+    getUserId?: () => Promise<string | null>; // Deprecated: use adapter
+  };
+}
+```
+
+### PlanSelector
+
+Component for selecting and displaying available plans.
+
+**Props:**
+- `agentRef?: string` - Agent reference to filter plans
+- `fetcher?: (agentRef: string) => Promise<Plan[]>` - Custom plan fetcher function
+- `onPlanSelect?: (plan: Plan) => void` - Callback when plan is selected
+- `renderPlan?: (plan: Plan) => React.ReactNode` - Custom plan renderer
+- `className?: string` - Container className
+
+**Example:**
+```tsx
+import { PlanSelector, usePlans } from '@solvapay/react';
+
+function PlansPage() {
+  const { plans, loading } = usePlans({ agentRef: 'my-agent' });
+  
+  return (
+    <div>
+      {loading ? 'Loading...' : plans.map(plan => (
+        <div key={plan.reference}>{plan.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### PaymentForm
+
+Payment form component using Stripe PaymentElement. Automatically handles Stripe Elements provider setup.
+
+**Props:**
+- `planRef: string` - Plan reference for the payment
+- `agentRef?: string` - Optional agent reference
+- `onSuccess?: (paymentIntent: PaymentIntent) => void` - Callback on successful payment
+- `onError?: (error: Error) => void` - Callback on payment error
+- `returnUrl?: string` - Return URL after payment
+- `submitButtonText?: string` - Submit button text (default: "Pay Now")
+- `formClassName?: string` - Form element className
+- `messageClassName?: string` - Message container className
+- `buttonClassName?: string` - Submit button className
+
+**Example:**
+```tsx
+import { PaymentForm } from '@solvapay/react';
+
+function CheckoutPage() {
+  return (
+    <PaymentForm
+      planRef="pln_YOUR_PLAN"
+      agentRef="agt_YOUR_AGENT"
+      onSuccess={() => console.log('Payment successful!')}
+    />
+  );
+}
+```
+
+### PlanBadge
+
+Displays current subscription plan with render props or className pattern.
+
+**Props:**
+- `children?: (props) => React.ReactNode` - Render prop function
+- `as?: React.ElementType` - Component to render (default: "div")
+- `className?: string | ((props) => string)` - ClassName or function
+
+**Example:**
+```tsx
+<PlanBadge className="badge badge-primary" />
+```
+
+### SubscriptionGate
+
+Controls access to content based on subscription status.
+
+**Props:**
+- `requirePlan?: string` - Optional plan name to require
+- `children: (props) => React.ReactNode` - Render prop function
+
+**Example:**
+```tsx
+<SubscriptionGate requirePlan="Pro Plan">
+  {({ hasAccess, loading, subscriptions }) => {
+    if (loading) return <Loading />;
+    if (!hasAccess) return <Paywall />;
+    return <PremiumContent />;
+  }}
+</SubscriptionGate>
+```
+
+## Hooks
+
+### useSubscription
+
+Access subscription status, active subscriptions, and helper functions.
+
+```tsx
+const { 
+  subscriptions,           // Array of all subscriptions
+  loading,                 // Loading state
+  hasPaidSubscription,    // Boolean: has any paid subscription
+  activeSubscription,      // Most recent active subscription
+  refetch                  // Function to refetch subscriptions
+} = useSubscription();
+```
+
+### usePlans
+
+Fetch and manage available plans.
+
+```tsx
+const { 
+  plans,                   // Array of available plans
+  loading,                 // Loading state
+  error,                   // Error object if fetch failed
+  refetch                  // Function to refetch plans
+} = usePlans({ 
+  agentRef: 'my-agent',   // Optional agent reference
+  fetcher: customFetcher  // Optional custom fetcher function
+});
+```
+
+### useSubscriptionStatus
+
+Advanced subscription status helpers.
+
+```tsx
+const {
+  cancelledSubscription,      // Most recent cancelled subscription
+  shouldShowCancelledNotice,   // Boolean: should show cancellation notice
+  formatDate,                  // Helper to format dates
+  getDaysUntilExpiration       // Helper to get days until expiration
+} = useSubscriptionStatus();
+```
+
+### useCheckout
+
+Manage checkout flow for a specific plan.
+
+```tsx
+const { loading, error, startCheckout, reset } = useCheckout('plan_ref');
+```
+
+### useSolvaPay
+
+Access SolvaPay context directly.
+
+```tsx
+const { 
+  subscriptionData,      // Full subscription data
+  loading,                // Loading state
+  createPayment,         // Payment creation function
+  processPayment,        // Payment processing function
+  customerRef,           // Current customer reference
+  updateCustomerRef      // Function to update customer reference
+} = useSolvaPay();
+```
+
+## TypeScript
+
+All components and hooks are fully typed. Import types as needed:
+
+```tsx
+import type { PaymentFormProps, SubscriptionStatus, PaymentIntentResult } from '@solvapay/react';
+```
+
+## More Information
 
-More: docs/architecture.md
+See `docs/architecture.md` for detailed architecture documentation.

package/dist/adapters/auth.cjs

@@ -0,0 +1,49 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/auth.ts
+var auth_exports = {};
+__export(auth_exports, {
+  defaultAuthAdapter: () => defaultAuthAdapter
+});
+module.exports = __toCommonJS(auth_exports);
+var defaultAuthAdapter = {
+  async getToken() {
+    if (typeof window === "undefined") return null;
+    const token = localStorage.getItem("auth_token");
+    return token || null;
+  },
+  async getUserId() {
+    const token = await this.getToken();
+    if (!token) return null;
+    try {
+      const parts = token.split(".");
+      if (parts.length === 3) {
+        const payload = JSON.parse(atob(parts[1]));
+        return payload.sub || payload.user_id || null;
+      }
+    } catch {
+    }
+    return null;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defaultAuthAdapter
+});

package/dist/adapters/auth.d.cts

@@ -0,0 +1,44 @@
+/**
+ * Auth Adapter Interface for Client-Side Authentication
+ *
+ * Defines the contract for authentication adapters used by SolvaPayProvider.
+ * Adapters handle token retrieval and user ID extraction in the browser.
+ */
+/**
+ * Auth adapter interface for client-side authentication
+ *
+ * Used by SolvaPayProvider to get auth tokens and user IDs.
+ * Adapters should handle their own error cases and return null when
+ * authentication is not available or fails.
+ */
+interface AuthAdapter {
+    /**
+     * Get the authentication token
+     *
+     * @returns The auth token string if available, null otherwise
+     *
+     * @remarks
+     * This method should never throw. If authentication fails or is missing,
+     * return null and let the caller decide how to handle unauthenticated requests.
+     */
+    getToken: () => Promise<string | null>;
+    /**
+     * Get the authenticated user ID
+     *
+     * @returns The user ID string if authenticated, null otherwise
+     *
+     * @remarks
+     * This method should never throw. If authentication fails or is missing,
+     * return null and let the caller decide how to handle unauthenticated requests.
+     */
+    getUserId: () => Promise<string | null>;
+}
+/**
+ * Default auth adapter that only checks localStorage
+ *
+ * This is a fallback adapter that doesn't depend on any specific auth provider.
+ * It checks for a token in localStorage under the 'auth_token' key.
+ */
+declare const defaultAuthAdapter: AuthAdapter;
+
+export { type AuthAdapter, defaultAuthAdapter };

package/dist/adapters/auth.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Auth Adapter Interface for Client-Side Authentication
+ *
+ * Defines the contract for authentication adapters used by SolvaPayProvider.
+ * Adapters handle token retrieval and user ID extraction in the browser.
+ */
+/**
+ * Auth adapter interface for client-side authentication
+ *
+ * Used by SolvaPayProvider to get auth tokens and user IDs.
+ * Adapters should handle their own error cases and return null when
+ * authentication is not available or fails.
+ */
+interface AuthAdapter {
+    /**
+     * Get the authentication token
+     *
+     * @returns The auth token string if available, null otherwise
+     *
+     * @remarks
+     * This method should never throw. If authentication fails or is missing,
+     * return null and let the caller decide how to handle unauthenticated requests.
+     */
+    getToken: () => Promise<string | null>;
+    /**
+     * Get the authenticated user ID
+     *
+     * @returns The user ID string if authenticated, null otherwise
+     *
+     * @remarks
+     * This method should never throw. If authentication fails or is missing,
+     * return null and let the caller decide how to handle unauthenticated requests.
+     */
+    getUserId: () => Promise<string | null>;
+}
+/**
+ * Default auth adapter that only checks localStorage
+ *
+ * This is a fallback adapter that doesn't depend on any specific auth provider.
+ * It checks for a token in localStorage under the 'auth_token' key.
+ */
+declare const defaultAuthAdapter: AuthAdapter;
+
+export { type AuthAdapter, defaultAuthAdapter };

package/dist/adapters/auth.js

@@ -0,0 +1,6 @@
+import {
+  defaultAuthAdapter
+} from "../chunk-OUSEQRCT.js";
+export {
+  defaultAuthAdapter
+};

package/dist/chunk-OUSEQRCT.js

@@ -0,0 +1,25 @@
+// src/adapters/auth.ts
+var defaultAuthAdapter = {
+  async getToken() {
+    if (typeof window === "undefined") return null;
+    const token = localStorage.getItem("auth_token");
+    return token || null;
+  },
+  async getUserId() {
+    const token = await this.getToken();
+    if (!token) return null;
+    try {
+      const parts = token.split(".");
+      if (parts.length === 3) {
+        const payload = JSON.parse(atob(parts[1]));
+        return payload.sub || payload.user_id || null;
+      }
+    } catch {
+    }
+    return null;
+  }
+};
+
+export {
+  defaultAuthAdapter
+};