@solvapay/react 1.0.0-preview.4 → 1.0.0-preview.5

package/dist/index.d.cts

@@ -1,84 +1,240 @@
-import React from 'react';
-import { Stripe } from '@stripe/stripe-js';
+import React$1 from 'react';
+import { PaymentIntent, Stripe } from '@stripe/stripe-js';
 
+/**
+ * TypeScript type definitions for @solvapay/react
+ */
+
+interface SubscriptionInfo {
+    reference: string;
+    planName: string;
+    agentName: string;
+    status: string;
+    startDate: string;
+}
+interface CustomerSubscriptionData {
+    customerRef?: string;
+    email?: string;
+    name?: string;
+    subscriptions: SubscriptionInfo[];
+}
+interface PaymentIntentResult {
+    clientSecret: string;
+    publishableKey: string;
+    accountId?: string;
+    customerRef?: string;
+}
+interface SubscriptionStatus {
+    loading: boolean;
+    customerRef?: string;
+    email?: string;
+    name?: string;
+    subscriptions: SubscriptionInfo[];
+    hasActiveSubscription: boolean;
+    hasPlan: (planName: string) => boolean;
+}
+interface SolvaPayContextValue {
+    subscription: SubscriptionStatus;
+    refetchSubscription: () => Promise<void>;
+    createPayment: (params: {
+        planRef: string;
+        customerRef: string;
+    }) => Promise<PaymentIntentResult>;
+    customerRef?: string;
+    updateCustomerRef?: (newCustomerRef: string) => void;
+}
 interface SolvaPayProviderProps {
+    createPayment: (params: {
+        planRef: string;
+        customerRef: string;
+    }) => Promise<PaymentIntentResult>;
+    checkSubscription: (customerRef: string) => Promise<CustomerSubscriptionData>;
+    customerRef?: string;
+    onCustomerRefUpdate?: (newCustomerRef: string) => void;
     children: React.ReactNode;
-    amount?: number;
-    currency?: string;
+}
+interface PlanBadgeProps {
+    children?: (props: {
+        subscriptions: SubscriptionInfo[];
+        loading: boolean;
+    }) => React.ReactNode;
+    as?: React.ElementType;
+    className?: string | ((props: {
+        subscriptions: SubscriptionInfo[];
+    }) => string);
+}
+interface SubscriptionGateProps {
+    requirePlan?: string;
+    children: (props: {
+        hasAccess: boolean;
+        subscriptions: SubscriptionInfo[];
+        loading: boolean;
+    }) => React.ReactNode;
+}
+/**
+ * Error type for payment operations
+ */
+interface PaymentError extends Error {
+    code?: string;
+    type?: string;
+}
+/**
+ * Payment form props with proper Stripe types
+ */
+interface PaymentFormProps {
+    /**
+     * Plan reference to checkout. PaymentForm handles the entire checkout flow internally
+     * including Stripe initialization and payment intent creation.
+     */
     planRef: string;
-    agentRef: string;
-    apiBaseUrl?: string;
-    onPaymentReady?: (stripe: Stripe | null, clientSecret: string) => void;
+    onSuccess?: (paymentIntent: PaymentIntent) => void;
+    onError?: (error: Error) => void;
+    /**
+     * Return URL after payment completion. Defaults to current page URL if not provided.
+     */
+    returnUrl?: string;
+    submitButtonText?: string;
+    /**
+     * Optional className for the form container (wraps form, messages, and cancel button)
+     */
+    className?: string;
+    /**
+     * Optional className for the submit button
+     */
+    buttonClassName?: string;
+    /**
+     * Text for the initial checkout button. If provided, shows a button first instead of
+     * auto-starting checkout.
+     */
+    initialButtonText?: string;
+    /**
+     * Text for the cancel button. Set to empty string to hide cancel button.
+     */
+    cancelButtonText?: string;
 }
+
 /**
- * SolvaPay Payment Provider Component
+ * SolvaPay Provider - Headless Context Provider
+ *
+ * Provides subscription state and payment methods to child components.
+ * This is a headless provider that manages state without rendering UI.
  *
- * Wraps children with Stripe Elements context after initializing a payment intent
- * via the backend API. This component handles the secure payment flow:
+ * @example
+ * ```tsx
+ * <SolvaPayProvider
+ *   customerRef={user?.id}
+ *   createPayment={async ({ planRef, customerRef }) => {
+ *     const res = await fetch('/api/payments/create', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ planRef, customerRef })
+ *     });
+ *     return res.json();
+ *   }}
+ *   checkSubscription={async (customerRef) => {
+ *     const res = await fetch(`/api/subscriptions/${customerRef}`);
+ *     return res.json();
+ *   }}
+ * >
+ *   <App />
+ * </SolvaPayProvider>
+ * ```
+ */
+declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
+
+/**
+ * SolvaPay Payment Form Component
  *
- * 1. Calls backend API route to create payment intent (backend uses secret key)
- * 2. Backend returns clientSecret and publishableKey from Stripe
- * 3. Initializes Stripe.js with publishableKey
- * 4. Wraps children in Stripe Elements provider
+ * Handles the entire checkout flow internally including Stripe initialization,
+ * payment intent creation, and form rendering. Simply provide a planRef and
+ * handle success/error callbacks.
  *
  * @example
  * ```tsx
- * // In your Next.js page
- * import { SolvaPayProvider, PaymentForm } from '@solvapay/react';
+ * import { PaymentForm } from '@solvapay/react';
  *
- * export default function CheckoutPage() {
- *   return (
- *     <SolvaPayProvider
- *       amount={999}
- *       currency="USD"
- *       planRef="pln_abc123"
- *       agentRef="agt_xyz789"
- *       onPaymentReady={(stripe, clientSecret) => {
- *         console.log('Payment ready!');
- *       }}
- *     >
- *       <PaymentForm />
- *     </SolvaPayProvider>
- *   );
- * }
+ * <PaymentForm
+ *   planRef="pro_plan"
+ *   onSuccess={(paymentIntent) => {
+ *     console.log('Payment successful!');
+ *   }}
+ *   onError={(error) => {
+ *     console.error('Payment failed:', error);
+ *   }}
+ * />
  * ```
  */
-declare const SolvaPayProvider: React.FC<SolvaPayProviderProps>;
+declare const PaymentForm: React$1.FC<PaymentFormProps>;
 
-interface PaymentFormProps {
-    onSuccess?: (paymentIntent: any) => void;
-    onError?: (error: Error) => void;
-    returnUrl?: string;
-    submitButtonText?: string;
-    className?: string;
-}
 /**
- * SolvaPay Payment Form Component
+ * Headless Plan Badge Component
  *
- * Renders a payment form using Stripe's PaymentElement for secure card input.
- * This component must be wrapped in a SolvaPayProvider to work properly.
+ * Displays subscription status with complete styling control.
+ * Supports render props, custom components, or className patterns.
  *
  * @example
  * ```tsx
- * import { SolvaPayProvider, PaymentForm } from '@solvapay/react';
+ * // Render prop pattern
+ * <PlanBadge>
+ *   {({ subscriptions, loading }) => (
+ *     <div>
+ *       {subscriptions.map(sub => <span key={sub.reference}>{sub.planName}</span>)}
+ *     </div>
+ *   )}
+ * </PlanBadge>
+ *
+ * //ClassName pattern
+ * <PlanBadge className="badge badge-primary" />
+ * ```
+ */
+declare const PlanBadge: React$1.FC<PlanBadgeProps>;
+
+/**
+ * Headless Subscription Gate Component
  *
- * export default function CheckoutPage() {
- *   return (
- *     <SolvaPayProvider amount={999} planRef="pln_abc123">
- *       <PaymentForm
- *         returnUrl={`${window.location.origin}/checkout/success`}
- *         onSuccess={(paymentIntent) => {
- *           console.log('Payment successful!', paymentIntent);
- *         }}
- *         onError={(error) => {
- *           console.error('Payment failed:', error);
- *         }}
- *       />
- *     </SolvaPayProvider>
- *   );
- * }
+ * Controls access to content based on subscription status.
+ * Uses render props to give developers full control over locked/unlocked states.
+ *
+ * @example
+ * ```tsx
+ * <SubscriptionGate requirePlan="Pro Plan">
+ *   {({ hasAccess, loading }) => {
+ *     if (loading) return <Skeleton />;
+ *     if (!hasAccess) return <Paywall />;
+ *     return <PremiumContent />;
+ *   }}
+ * </SubscriptionGate>
  * ```
  */
-declare const PaymentForm: React.FC<PaymentFormProps>;
+declare const SubscriptionGate: React$1.FC<SubscriptionGateProps>;
+
+/**
+ * Hook to access subscription status
+ * Returns the current subscription state and a refetch function
+ */
+declare function useSubscription(): SubscriptionStatus & {
+    refetch: () => Promise<void>;
+};
+
+interface UseCheckoutReturn {
+    loading: boolean;
+    error: Error | null;
+    stripePromise: Promise<Stripe | null> | null;
+    clientSecret: string | null;
+    startCheckout: () => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Hook to manage checkout flow
+ * Handles payment intent creation and Stripe initialization
+ *
+ * @param planRef - The plan reference to checkout
+ */
+declare function useCheckout(planRef: string): UseCheckoutReturn;
+
+/**
+ * Hook to access SolvaPay context
+ * Must be used within a SolvaPayProvider
+ */
+declare function useSolvaPay(): SolvaPayContextValue;
 
-export { PaymentForm, type PaymentFormProps, SolvaPayProvider, type SolvaPayProviderProps };
+export { type CustomerSubscriptionData, type PaymentError, PaymentForm, type PaymentFormProps, type PaymentIntentResult, PlanBadge, type PlanBadgeProps, type SolvaPayContextValue, SolvaPayProvider, type SolvaPayProviderProps, SubscriptionGate, type SubscriptionGateProps, type SubscriptionInfo, type SubscriptionStatus, useCheckout, useSolvaPay, useSubscription };

package/dist/index.d.ts

@@ -1,84 +1,240 @@
-import React from 'react';
-import { Stripe } from '@stripe/stripe-js';
+import React$1 from 'react';
+import { PaymentIntent, Stripe } from '@stripe/stripe-js';
 
+/**
+ * TypeScript type definitions for @solvapay/react
+ */
+
+interface SubscriptionInfo {
+    reference: string;
+    planName: string;
+    agentName: string;
+    status: string;
+    startDate: string;
+}
+interface CustomerSubscriptionData {
+    customerRef?: string;
+    email?: string;
+    name?: string;
+    subscriptions: SubscriptionInfo[];
+}
+interface PaymentIntentResult {
+    clientSecret: string;
+    publishableKey: string;
+    accountId?: string;
+    customerRef?: string;
+}
+interface SubscriptionStatus {
+    loading: boolean;
+    customerRef?: string;
+    email?: string;
+    name?: string;
+    subscriptions: SubscriptionInfo[];
+    hasActiveSubscription: boolean;
+    hasPlan: (planName: string) => boolean;
+}
+interface SolvaPayContextValue {
+    subscription: SubscriptionStatus;
+    refetchSubscription: () => Promise<void>;
+    createPayment: (params: {
+        planRef: string;
+        customerRef: string;
+    }) => Promise<PaymentIntentResult>;
+    customerRef?: string;
+    updateCustomerRef?: (newCustomerRef: string) => void;
+}
 interface SolvaPayProviderProps {
+    createPayment: (params: {
+        planRef: string;
+        customerRef: string;
+    }) => Promise<PaymentIntentResult>;
+    checkSubscription: (customerRef: string) => Promise<CustomerSubscriptionData>;
+    customerRef?: string;
+    onCustomerRefUpdate?: (newCustomerRef: string) => void;
     children: React.ReactNode;
-    amount?: number;
-    currency?: string;
+}
+interface PlanBadgeProps {
+    children?: (props: {
+        subscriptions: SubscriptionInfo[];
+        loading: boolean;
+    }) => React.ReactNode;
+    as?: React.ElementType;
+    className?: string | ((props: {
+        subscriptions: SubscriptionInfo[];
+    }) => string);
+}
+interface SubscriptionGateProps {
+    requirePlan?: string;
+    children: (props: {
+        hasAccess: boolean;
+        subscriptions: SubscriptionInfo[];
+        loading: boolean;
+    }) => React.ReactNode;
+}
+/**
+ * Error type for payment operations
+ */
+interface PaymentError extends Error {
+    code?: string;
+    type?: string;
+}
+/**
+ * Payment form props with proper Stripe types
+ */
+interface PaymentFormProps {
+    /**
+     * Plan reference to checkout. PaymentForm handles the entire checkout flow internally
+     * including Stripe initialization and payment intent creation.
+     */
     planRef: string;
-    agentRef: string;
-    apiBaseUrl?: string;
-    onPaymentReady?: (stripe: Stripe | null, clientSecret: string) => void;
+    onSuccess?: (paymentIntent: PaymentIntent) => void;
+    onError?: (error: Error) => void;
+    /**
+     * Return URL after payment completion. Defaults to current page URL if not provided.
+     */
+    returnUrl?: string;
+    submitButtonText?: string;
+    /**
+     * Optional className for the form container (wraps form, messages, and cancel button)
+     */
+    className?: string;
+    /**
+     * Optional className for the submit button
+     */
+    buttonClassName?: string;
+    /**
+     * Text for the initial checkout button. If provided, shows a button first instead of
+     * auto-starting checkout.
+     */
+    initialButtonText?: string;
+    /**
+     * Text for the cancel button. Set to empty string to hide cancel button.
+     */
+    cancelButtonText?: string;
 }
+
 /**
- * SolvaPay Payment Provider Component
+ * SolvaPay Provider - Headless Context Provider
+ *
+ * Provides subscription state and payment methods to child components.
+ * This is a headless provider that manages state without rendering UI.
  *
- * Wraps children with Stripe Elements context after initializing a payment intent
- * via the backend API. This component handles the secure payment flow:
+ * @example
+ * ```tsx
+ * <SolvaPayProvider
+ *   customerRef={user?.id}
+ *   createPayment={async ({ planRef, customerRef }) => {
+ *     const res = await fetch('/api/payments/create', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ planRef, customerRef })
+ *     });
+ *     return res.json();
+ *   }}
+ *   checkSubscription={async (customerRef) => {
+ *     const res = await fetch(`/api/subscriptions/${customerRef}`);
+ *     return res.json();
+ *   }}
+ * >
+ *   <App />
+ * </SolvaPayProvider>
+ * ```
+ */
+declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
+
+/**
+ * SolvaPay Payment Form Component
  *
- * 1. Calls backend API route to create payment intent (backend uses secret key)
- * 2. Backend returns clientSecret and publishableKey from Stripe
- * 3. Initializes Stripe.js with publishableKey
- * 4. Wraps children in Stripe Elements provider
+ * Handles the entire checkout flow internally including Stripe initialization,
+ * payment intent creation, and form rendering. Simply provide a planRef and
+ * handle success/error callbacks.
  *
  * @example
  * ```tsx
- * // In your Next.js page
- * import { SolvaPayProvider, PaymentForm } from '@solvapay/react';
+ * import { PaymentForm } from '@solvapay/react';
  *
- * export default function CheckoutPage() {
- *   return (
- *     <SolvaPayProvider
- *       amount={999}
- *       currency="USD"
- *       planRef="pln_abc123"
- *       agentRef="agt_xyz789"
- *       onPaymentReady={(stripe, clientSecret) => {
- *         console.log('Payment ready!');
- *       }}
- *     >
- *       <PaymentForm />
- *     </SolvaPayProvider>
- *   );
- * }
+ * <PaymentForm
+ *   planRef="pro_plan"
+ *   onSuccess={(paymentIntent) => {
+ *     console.log('Payment successful!');
+ *   }}
+ *   onError={(error) => {
+ *     console.error('Payment failed:', error);
+ *   }}
+ * />
  * ```
  */
-declare const SolvaPayProvider: React.FC<SolvaPayProviderProps>;
+declare const PaymentForm: React$1.FC<PaymentFormProps>;
 
-interface PaymentFormProps {
-    onSuccess?: (paymentIntent: any) => void;
-    onError?: (error: Error) => void;
-    returnUrl?: string;
-    submitButtonText?: string;
-    className?: string;
-}
 /**
- * SolvaPay Payment Form Component
+ * Headless Plan Badge Component
  *
- * Renders a payment form using Stripe's PaymentElement for secure card input.
- * This component must be wrapped in a SolvaPayProvider to work properly.
+ * Displays subscription status with complete styling control.
+ * Supports render props, custom components, or className patterns.
  *
  * @example
  * ```tsx
- * import { SolvaPayProvider, PaymentForm } from '@solvapay/react';
+ * // Render prop pattern
+ * <PlanBadge>
+ *   {({ subscriptions, loading }) => (
+ *     <div>
+ *       {subscriptions.map(sub => <span key={sub.reference}>{sub.planName}</span>)}
+ *     </div>
+ *   )}
+ * </PlanBadge>
+ *
+ * //ClassName pattern
+ * <PlanBadge className="badge badge-primary" />
+ * ```
+ */
+declare const PlanBadge: React$1.FC<PlanBadgeProps>;
+
+/**
+ * Headless Subscription Gate Component
  *
- * export default function CheckoutPage() {
- *   return (
- *     <SolvaPayProvider amount={999} planRef="pln_abc123">
- *       <PaymentForm
- *         returnUrl={`${window.location.origin}/checkout/success`}
- *         onSuccess={(paymentIntent) => {
- *           console.log('Payment successful!', paymentIntent);
- *         }}
- *         onError={(error) => {
- *           console.error('Payment failed:', error);
- *         }}
- *       />
- *     </SolvaPayProvider>
- *   );
- * }
+ * Controls access to content based on subscription status.
+ * Uses render props to give developers full control over locked/unlocked states.
+ *
+ * @example
+ * ```tsx
+ * <SubscriptionGate requirePlan="Pro Plan">
+ *   {({ hasAccess, loading }) => {
+ *     if (loading) return <Skeleton />;
+ *     if (!hasAccess) return <Paywall />;
+ *     return <PremiumContent />;
+ *   }}
+ * </SubscriptionGate>
  * ```
  */
-declare const PaymentForm: React.FC<PaymentFormProps>;
+declare const SubscriptionGate: React$1.FC<SubscriptionGateProps>;
+
+/**
+ * Hook to access subscription status
+ * Returns the current subscription state and a refetch function
+ */
+declare function useSubscription(): SubscriptionStatus & {
+    refetch: () => Promise<void>;
+};
+
+interface UseCheckoutReturn {
+    loading: boolean;
+    error: Error | null;
+    stripePromise: Promise<Stripe | null> | null;
+    clientSecret: string | null;
+    startCheckout: () => Promise<void>;
+    reset: () => void;
+}
+/**
+ * Hook to manage checkout flow
+ * Handles payment intent creation and Stripe initialization
+ *
+ * @param planRef - The plan reference to checkout
+ */
+declare function useCheckout(planRef: string): UseCheckoutReturn;
+
+/**
+ * Hook to access SolvaPay context
+ * Must be used within a SolvaPayProvider
+ */
+declare function useSolvaPay(): SolvaPayContextValue;
 
-export { PaymentForm, type PaymentFormProps, SolvaPayProvider, type SolvaPayProviderProps };
+export { type CustomerSubscriptionData, type PaymentError, PaymentForm, type PaymentFormProps, type PaymentIntentResult, PlanBadge, type PlanBadgeProps, type SolvaPayContextValue, SolvaPayProvider, type SolvaPayProviderProps, SubscriptionGate, type SubscriptionGateProps, type SubscriptionInfo, type SubscriptionStatus, useCheckout, useSolvaPay, useSubscription };