@solvapay/react 1.0.0-preview.9 → 1.0.1-preview.1

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

@@ -15,31 +15,93 @@ pnpm add @solvapay/react
 
 ## 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, UpgradeButton, useSubscription } from '@solvapay/react';
+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
-      customerRef={user?.id}
-      createPayment={async ({ planRef, customerRef }) => {
-        const res = await fetch('/api/payments/create', {
+      createPayment={async ({ planRef, productRef }) => {
+        const res = await fetch('/api/custom/payment', {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ planRef, customerRef }),
-        });
-        if (!res.ok) throw new Error('Failed to create payment');
-        return res.json();
+          body: JSON.stringify({ planRef, productRef }),
+        })
+        if (!res.ok) throw new Error('Failed to create payment')
+        return res.json()
       }}
-      checkSubscription={async (customerRef) => {
-        const res = await fetch(`/api/subscriptions/${customerRef}`);
-        if (!res.ok) throw new Error('Failed to check subscription');
-        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()
       }}
     >
       <CheckoutPage />
     </SolvaPayProvider>
-  );
+  )
 }
 ```
 
@@ -47,95 +109,183 @@ export default function App() {
 
 ### SolvaPayProvider
 
-Headless context provider that manages subscription state and payment methods.
+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:**
-- `createPayment: (params: { planRef: string; customerRef: string }) => Promise<PaymentIntentResult>` - Function to create payment intent
-- `checkSubscription: (customerRef: string) => Promise<CustomerSubscriptionData>` - Function to check subscription status
-- `customerRef?: string` - Optional customer reference
-- `onCustomerRefUpdate?: (newCustomerRef: string) => void` - Callback when customer ref updates
+
+- `config?: SolvaPayConfig` - Configuration object (optional)
+  - `config.api?` - Custom API route paths
+  - `config.auth?` - Auth adapter configuration
+- `createPayment?: (params: { planRef: string; productRef?: 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; productRef: string; planRef?: string }) => Promise<ProcessPaymentResult>` - Custom payment processing function (optional)
 - `children: React.ReactNode` - Child components
 
-### UpgradeButton
+**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
+  }
+}
+```
+
+### PricingSelector
 
-Headless component for handling upgrade flows with render props pattern.
+Component for selecting and displaying available pricing options.
 
 **Props:**
-- `planRef: string` - Plan reference to upgrade to
-- `onSuccess?: () => void` - Callback on successful payment
-- `onError?: (error: Error) => void` - Callback on payment error
-- `children: (props) => React.ReactNode` - Render prop function
-- `renderPaymentForm?: (props) => React.ReactNode` - Custom payment form renderer
-- `paymentFormContainerClassName?: string` - Optional className for container
-- `cancelButtonClassName?: string` - Optional className for cancel button
+
+- `productRef?: string` - Product reference to filter pricing options
+- `fetcher?: (productRef: string) => Promise<Plan[]>` - Custom fetcher function
+- `onPlanSelect?: (plan: Plan) => void` - Callback when option is selected
+- `renderPlan?: (plan: Plan) => React.ReactNode` - Custom option renderer
+- `className?: string` - Container className
 
 **Example:**
+
 ```tsx
-<UpgradeButton planRef="pro_plan">
-  {({ onClick, loading, disabled, error }) => (
-    <button onClick={onClick} disabled={disabled}>
-      {loading ? 'Processing...' : 'Upgrade to Pro'}
-      {error && <span>Error: {error.message}</span>}
-    </button>
-  )}
-</UpgradeButton>
+import { PricingSelector, usePlans } from '@solvapay/react'
+
+function PricingPage() {
+  const { plans, loading } = usePlans({ productRef: 'my-product' })
+
+  return (
+    <div>
+      {loading ? 'Loading...' : plans.map(plan => <div key={plan.reference}>{plan.price}/{plan.interval}</div>)}
+    </div>
+  )
+}
 ```
 
 ### PaymentForm
 
-Payment form component using Stripe PaymentElement. Must be wrapped in Stripe Elements provider (provided by UpgradeButton or manually).
+Payment form component using Stripe PaymentElement. Automatically handles Stripe Elements provider setup.
 
 **Props:**
+
+- `planRef: string` - Plan reference for the payment
+- `productRef?: string` - Optional product 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")
-- `className?: string` - Form className (legacy, use formClassName)
 - `formClassName?: string` - Form element className
 - `messageClassName?: string` - Message container className
 - `buttonClassName?: string` - Submit button className
 
-### PlanBadge
+**Example:**
+
+```tsx
+import { PaymentForm } from '@solvapay/react'
+
+function CheckoutPage() {
+  return (
+    <PaymentForm
+      planRef="pln_YOUR_PLAN"
+      productRef="prd_YOUR_PRODUCT"
+      onSuccess={() => console.log('Payment successful!')}
+    />
+  )
+}
+```
+
+### ProductBadge
 
-Displays current subscription plan with render props or className pattern.
+Displays current product subscription 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" />
+<ProductBadge className="badge badge-primary" />
 ```
 
-### SubscriptionGate
+### PurchaseGate
 
-Controls access to content based on subscription status.
+Controls access to content based on purchase status.
 
 **Props:**
-- `requirePlan?: string` - Optional plan name to require
+
+- `requireProduct?: string` - Optional product name to check for an active purchase
 - `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 />;
+<PurchaseGate requireProduct="Pro Plan">
+  {({ hasAccess, loading, purchases }) => {
+    if (loading) return <Loading />
+    if (!hasAccess) return <Paywall />
+    return <PremiumContent />
   }}
-</SubscriptionGate>
+</PurchaseGate>
 ```
 
 ## Hooks
 
-### useSubscription
+### 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({
+  productRef: 'my-product', // Optional product reference
+  fetcher: customFetcher, // Optional custom fetcher function
+})
+```
+
+### usePurchaseStatus
 
-Access subscription status and refetch function.
+Advanced purchase status helpers.
 
 ```tsx
-const { subscriptions, loading, hasActiveSubscription, hasPlan, refetch } = useSubscription();
+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
@@ -143,7 +293,7 @@ const { subscriptions, loading, hasActiveSubscription, hasPlan, refetch } = useS
 Manage checkout flow for a specific plan.
 
 ```tsx
-const { loading, error, startCheckout, reset } = useCheckout('plan_ref');
+const { loading, error, startCheckout, reset } = useCheckout('plan_ref')
 ```
 
 ### useSolvaPay
@@ -151,7 +301,14 @@ const { loading, error, startCheckout, reset } = useCheckout('plan_ref');
 Access SolvaPay context directly.
 
 ```tsx
-const { subscription, createPayment, customerRef } = useSolvaPay();
+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
@@ -159,9 +316,9 @@ const { subscription, createPayment, customerRef } = useSolvaPay();
 All components and hooks are fully typed. Import types as needed:
 
 ```tsx
-import type { PaymentFormProps, SubscriptionStatus, PaymentIntentResult } from '@solvapay/react';
+import type { PaymentFormProps, PurchaseStatus, PaymentIntentResult } from '@solvapay/react'
 ```
 
 ## More Information
 
-See `docs/architecture.md` for detailed architecture documentation.
+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
+};