@solvapay/react 1.0.0-preview.2 → 1.0.0-preview.20

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SolvaPay Inc.
+
+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

@@ -1,34 +1,324 @@
 # @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, usePurchase } from '@solvapay/react'
+
+export default function App() {
+  return (
+    <SolvaPayProvider>
+      <CheckoutPage />
+    </SolvaPayProvider>
+  )
+}
+```
+
+By default, `SolvaPayProvider` uses:
+
+- `/api/check-purchase` for purchase 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 App() {
+  return (
+    <SolvaPayProvider
+      config={{
+        api: {
+          checkPurchase: '/api/custom/purchase',
+          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, PaymentForm } from '@solvapay/react';
+import { SolvaPayProvider } from '@solvapay/react'
 
-export default function CheckoutPage() {
+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()
+      }}
+      checkPurchase={async customerRef => {
+        const res = await fetch(`/api/custom/purchase?customerRef=${customerRef}`)
+        if (!res.ok) throw new Error('Failed to check purchase')
+        return res.json()
+      }}
     >
-      <PaymentForm
-        returnUrl="/checkout/success"
-        onSuccess={(paymentIntent) => {
-          console.log('Payment successful!', paymentIntent);
-        }}
-      />
+      <CheckoutPage />
     </SolvaPayProvider>
-  );
+  )
+}
+```
+
+## Components
+
+### SolvaPayProvider
+
+Headless context provider that manages purchase state, payment methods, and customer references.
+
+**Features:**
+
+- Zero-config with sensible defaults
+- Auto-fetches purchases 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)
+- `checkPurchase?: (customerRef: string) => Promise<CustomerPurchaseData>` - Custom purchase 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?: {
+    checkPurchase?: string // Default: '/api/check-purchase'
+    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>
+  )
 }
 ```
 
-Peer deps: react, react-dom
+### 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 purchase 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" />
+```
+
+### PurchaseGate
+
+Controls access to content based on purchase status.
+
+**Props:**
+
+- `requirePlan?: string` - Optional plan name to require
+- `children: (props) => React.ReactNode` - Render prop function
+
+**Example:**
+
+```tsx
+<PurchaseGate requirePlan="Pro Plan">
+  {({ hasAccess, loading, purchases }) => {
+    if (loading) return <Loading />
+    if (!hasAccess) return <Paywall />
+    return <PremiumContent />
+  }}
+</PurchaseGate>
+```
+
+## Hooks
+
+### usePurchase
+
+Access purchase status, active purchases, and helper functions.
+
+```tsx
+const {
+  purchases, // Array of all purchases
+  loading, // Loading state
+  hasPaidPurchase, // Boolean: has any paid purchase
+  activePurchase, // Most recent active purchase
+  refetch, // Function to refetch purchases
+} = usePurchase()
+```
+
+### 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
+})
+```
+
+### usePurchaseStatus
+
+Advanced purchase status helpers.
+
+```tsx
+const {
+  cancelledPurchase, // Most recent cancelled purchase
+  shouldShowCancelledNotice, // Boolean: should show cancellation notice
+  formatDate, // Helper to format dates
+  getDaysUntilExpiration, // Helper to get days until expiration
+} = usePurchaseStatus()
+```
+
+### useCheckout
+
+Manage checkout flow for a specific plan.
+
+```tsx
+const { loading, error, startCheckout, reset } = useCheckout('plan_ref')
+```
+
+### useSolvaPay
+
+Access SolvaPay context directly.
+
+```tsx
+const {
+  purchaseData, // Full purchase 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, PurchaseStatus, PaymentIntentResult } from '@solvapay/react'
+```
+
+## More Information
 
-More: docs/architecture.md
+See [`docs/guides/architecture.md`](../../docs/guides/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
+};