@digilogiclabs/saas-factory-payments 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 DigiLogicLabs
+
+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

@@ -0,0 +1,679 @@
+# @digilogiclabs/saas-factory-payments
+
+A comprehensive payments package for SaaS Factory that works seamlessly in both Next.js and React Native environments. Built with TypeScript and designed to be provider-agnostic (currently supporting Stripe with plans for Paddle, LemonSqueezy, and more).
+
+## Features
+
+- 🌐 **Hybrid Support**: Works in both Next.js web applications and React Native mobile apps
+- 🔒 **Type-Safe**: Built with TypeScript for better developer experience
+- 🎨 **UI Components**: Pre-built components for checkout, pricing tables, and billing management
+- 🪝 **React Hooks**: Powerful hooks for subscription and customer management
+- 🔧 **Server Utilities**: Complete server-side API and webhook handling
+- 📱 **Mobile-First**: Native mobile payment flows with Stripe React Native
+- 🎯 **Provider-Agnostic**: Extensible architecture for multiple payment providers
+- 🚀 **CLI Integration**: Works seamlessly with create-saas-app
+
+## Installation
+
+```bash
+npm install @digilogiclabs/saas-factory-payments
+# or
+yarn add @digilogiclabs/saas-factory-payments
+# or
+pnpm add @digilogiclabs/saas-factory-payments
+```
+
+### Peer Dependencies
+
+The package requires different peer dependencies based on your platform:
+
+**For Web (Next.js):**
+```bash
+npm install @stripe/stripe-js @stripe/react-stripe-js stripe
+```
+
+**For React Native:**
+```bash
+npm install @stripe/stripe-react-native stripe
+```
+
+**For Server-side:**
+```bash
+npm install stripe
+```
+
+
+
+
+## Quick Start
+
+### 1. Setup Providers
+
+First, wrap your app with the PaymentsProvider and platform-specific StripeProvider:
+
+**Web (Next.js) - `pages/_app.tsx`:**
+```tsx
+import { PaymentsProvider } from '@digilogiclabs/saas-factory-payments';
+import { StripeProvider } from '@digilogiclabs/saas-factory-payments/web';
+
+export default function App({ Component, pageProps }) {
+  return (
+    <PaymentsProvider
+      config={{
+        provider: 'stripe',
+        publishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!,
+        environment: process.env.NODE_ENV as 'development' | 'production',
+      }}
+    >
+      <StripeProvider>
+        <Component {...pageProps} />
+      </StripeProvider>
+    </PaymentsProvider>
+  );
+}
+```
+
+**React Native - `App.tsx`:**
+```tsx
+import { PaymentsProvider } from '@digilogiclabs/saas-factory-payments';
+import { StripeProvider } from '@digilogiclabs/saas-factory-payments/native';
+
+export default function App() {
+  return (
+    <PaymentsProvider
+      config={{
+        provider: 'stripe',
+        publishableKey: process.env.EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY!,
+        environment: __DEV__ ? 'development' : 'production',
+      }}
+    >
+      <StripeProvider>
+        <MainApp />
+      </StripeProvider>
+    </PaymentsProvider>
+  );
+}
+```
+
+### 2. Use Components
+
+**Checkout Button (Web):**
+```tsx
+import { CheckoutButton } from '@digilogiclabs/saas-factory-payments/web';
+
+export default function PricingPage() {
+  return (
+    <CheckoutButton 
+      priceId="price_basic_monthly"
+      onSuccess={() => console.log('Payment successful!')}
+      onError={(error) => console.error('Payment failed:', error)}
+    >
+      Subscribe to Basic Plan
+    </CheckoutButton>
+  );
+}
+```
+
+**Checkout Button (React Native):**
+```tsx
+import { CheckoutButton } from '@digilogiclabs/saas-factory-payments/native';
+
+export default function PricingScreen() {
+  return (
+    <CheckoutButton 
+      priceId="price_basic_monthly"
+      onSuccess={() => navigation.navigate('Success')}
+      onError={(error) => Alert.alert('Error', error)}
+    >
+      Subscribe to Basic Plan
+    </CheckoutButton>
+  );
+}
+```
+
+### 3. Manage Subscriptions
+
+```tsx
+import { useSubscription } from '@digilogiclabs/saas-factory-payments/web'; // or /native
+
+function SubscriptionManager({ customerId }) {
+  const { subscription, loading, cancel, reactivate } = useSubscription({
+    customerId,
+  });
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h3>Current Subscription</h3>
+      <p>Status: {subscription?.status}</p>
+      <p>Plan: {subscription?.priceId}</p>
+      
+      {subscription?.status === 'active' && (
+        <button onClick={() => cancel()}>
+          Cancel Subscription
+        </button>
+      )}
+      
+      {subscription?.cancelAtPeriodEnd && (
+        <button onClick={() => reactivate()}>
+          Reactivate Subscription
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+
+## API Reference
+
+### Components
+
+#### CheckoutButton
+
+A button component that handles subscription or one-time payment checkout.
+
+**Props:**
+- `priceId` (string): Stripe price ID
+- `customerId?` (string): Existing customer ID
+- `customerEmail?` (string): Customer email for new customers
+- `successUrl?` (string): Redirect URL after successful payment
+- `cancelUrl?` (string): Redirect URL after cancelled payment
+- `onSuccess?` (function): Callback for successful payment
+- `onError?` (function): Callback for payment errors
+- `children` (ReactNode): Button content
+
+#### PricingTable
+
+A responsive pricing table component with multiple plans.
+
+**Props:**
+- `plans` (PricingPlan[]): Array of pricing plans
+- `customerId?` (string): Customer ID for checkout
+- `showFeatures?` (boolean): Whether to show plan features
+- `layout?` ('grid' | 'list' | 'carousel'): Layout style
+- `onPlanSelect?` (function): Callback when plan is selected
+
+#### PaymentForm
+
+An inline payment form for direct payment processing.
+
+**Props:**
+- `clientSecret?` (string): Payment intent client secret
+- `amount?` (number): Payment amount in cents
+- `currency?` (string): Payment currency
+- `onSuccess?` (function): Success callback
+- `onError?` (function): Error callback
+
+#### BillingPortal (Web only)
+
+A button that opens the Stripe Customer Portal for subscription management.
+
+**Props:**
+- `customerId` (string): Customer ID
+- `returnUrl?` (string): Return URL after portal session
+- `onSuccess?` (function): Success callback
+- `onError?` (function): Error callback
+
+### Hooks
+
+#### useSubscription
+
+Hook for managing customer subscriptions.
+
+```tsx
+const {
+  subscription,
+  subscriptions,
+  loading,
+  error,
+  refetch,
+  cancel,
+  reactivate,
+  updatePaymentMethod,
+} = useSubscription({ customerId });
+```
+
+#### useCheckout
+
+Hook for handling checkout processes.
+
+```tsx
+const {
+  loading,
+  error,
+  createCheckoutSession,
+  redirectToCheckout,
+  createPaymentIntent,
+} = useCheckout({
+  onSuccess: (sessionId) => console.log('Success:', sessionId),
+  onError: (error) => console.error('Error:', error),
+});
+```
+
+#### useCustomer
+
+Hook for customer management.
+
+```tsx
+const {
+  customer,
+  paymentMethods,
+  loading,
+  error,
+  createCustomer,
+  updateCustomer,
+  fetchPaymentMethods,
+} = useCustomer({ customerId });
+```
+
+#### usePayments
+
+High-level hook that combines customer and subscription management.
+
+```tsx
+const {
+  customer,
+  subscriptions,
+  activeSubscription,
+  loading,
+  createCustomer,
+  subscribe,
+  cancelSubscription,
+  hasActiveSubscription,
+  isSubscribedToPlan,
+} = usePayments({ customerId });
+```
+
+
+### Server-Side Utilities
+
+#### StripeServerAPI
+
+Complete server-side Stripe API wrapper.
+
+```tsx
+import { StripeServerAPI } from '@digilogiclabs/saas-factory-payments/server';
+
+const stripeAPI = new StripeServerAPI(process.env.STRIPE_SECRET_KEY!);
+
+// Create customer
+const customer = await stripeAPI.createCustomer({
+  email: 'user@example.com',
+  name: 'John Doe',
+});
+
+// Create subscription
+const subscription = await stripeAPI.createSubscription({
+  customerId: customer.id,
+  priceId: 'price_basic_monthly',
+});
+
+// Create checkout session
+const session = await stripeAPI.createCheckoutSession({
+  priceId: 'price_basic_monthly',
+  successUrl: 'https://yourapp.com/success',
+  cancelUrl: 'https://yourapp.com/cancel',
+});
+```
+
+#### Webhook Handling
+
+Handle Stripe webhooks with built-in event processing.
+
+**Next.js API Route (`pages/api/webhooks/stripe.ts`):**
+```tsx
+import { createNextJSWebhookHandler } from '@digilogiclabs/saas-factory-payments/server';
+
+export default createNextJSWebhookHandler(
+  process.env.STRIPE_SECRET_KEY!,
+  process.env.STRIPE_WEBHOOK_SECRET!,
+  {
+    onCustomerSubscriptionCreated: async (subscription) => {
+      // Handle new subscription
+      console.log('New subscription:', subscription.id);
+    },
+    onInvoicePaymentSucceeded: async (invoice) => {
+      // Handle successful payment
+      console.log('Payment succeeded:', invoice.id);
+    },
+    onInvoicePaymentFailed: async (invoice) => {
+      // Handle failed payment
+      console.log('Payment failed:', invoice.id);
+    },
+  }
+);
+
+export const config = {
+  api: {
+    bodyParser: {
+      sizeLimit: '1mb',
+    },
+  },
+};
+```
+
+**Express.js:**
+```tsx
+import express from 'express';
+import { createStripeWebhookMiddleware } from '@digilogiclabs/saas-factory-payments/server';
+
+const app = express();
+
+app.use('/webhooks/stripe', express.raw({ type: 'application/json' }));
+app.use('/webhooks/stripe', createStripeWebhookMiddleware(
+  process.env.STRIPE_SECRET_KEY!,
+  process.env.STRIPE_WEBHOOK_SECRET!,
+  {
+    onCustomerSubscriptionCreated: async (subscription) => {
+      // Handle subscription creation
+    },
+  }
+));
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env.local` file (Next.js) or configure your environment:
+
+```bash
+# Stripe Configuration
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# For React Native (Expo)
+EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+```
+
+### PaymentsProvider Configuration
+
+```tsx
+interface PaymentsConfig {
+  provider: 'stripe'; // More providers coming soon
+  publishableKey: string;
+  secretKey?: string; // Server-side only
+  webhookSecret?: string; // Server-side only
+  environment: 'development' | 'production';
+}
+```
+
+### Pricing Plans Configuration
+
+```tsx
+interface PricingPlan {
+  id: string;
+  name: string;
+  description?: string;
+  price: number; // In cents
+  currency: string;
+  interval: 'day' | 'week' | 'month' | 'year';
+  stripePriceId: string;
+  features: string[];
+  popular?: boolean;
+  trialPeriodDays?: number;
+}
+
+const plans: PricingPlan[] = [
+  {
+    id: 'basic',
+    name: 'Basic Plan',
+    description: 'Perfect for getting started',
+    price: 999, // $9.99
+    currency: 'USD',
+    interval: 'month',
+    stripePriceId: 'price_basic_monthly',
+    features: [
+      'Up to 10 projects',
+      'Basic support',
+      '1GB storage',
+    ],
+  },
+  {
+    id: 'pro',
+    name: 'Pro Plan',
+    description: 'For growing businesses',
+    price: 1999, // $19.99
+    currency: 'USD',
+    interval: 'month',
+    stripePriceId: 'price_pro_monthly',
+    features: [
+      'Unlimited projects',
+      'Priority support',
+      '10GB storage',
+      'Advanced analytics',
+    ],
+    popular: true,
+  },
+];
+```
+
+
+## Examples
+
+### Complete Pricing Page (Web)
+
+```tsx
+import { useState } from 'react';
+import { PricingTable, BillingPortal } from '@digilogiclabs/saas-factory-payments/web';
+import { usePayments } from '@digilogiclabs/saas-factory-payments';
+
+const plans = [
+  {
+    id: 'basic',
+    name: 'Basic',
+    price: 999,
+    currency: 'USD',
+    interval: 'month',
+    stripePriceId: 'price_basic_monthly',
+    features: ['Feature 1', 'Feature 2'],
+  },
+  {
+    id: 'pro',
+    name: 'Pro',
+    price: 1999,
+    currency: 'USD',
+    interval: 'month',
+    stripePriceId: 'price_pro_monthly',
+    features: ['All Basic features', 'Feature 3', 'Feature 4'],
+    popular: true,
+  },
+];
+
+export default function PricingPage() {
+  const [customerId] = useState('cus_example123');
+  const { hasActiveSubscription } = usePayments({ customerId });
+
+  if (hasActiveSubscription()) {
+    return (
+      <div className="text-center py-8">
+        <h2>Manage Your Subscription</h2>
+        <BillingPortal customerId={customerId}>
+          Manage Billing
+        </BillingPortal>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-6xl mx-auto px-4 py-8">
+      <h1 className="text-3xl font-bold text-center mb-8">Choose Your Plan</h1>
+      <PricingTable
+        plans={plans}
+        customerId={customerId}
+        onCheckoutSuccess={(plan) => {
+          console.log(`Successfully subscribed to ${plan.name}`);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Mobile Subscription Flow (React Native)
+
+```tsx
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { PricingTable } from '@digilogiclabs/saas-factory-payments/native';
+import { usePayments } from '@digilogiclabs/saas-factory-payments';
+
+const plans = [
+  // Same plans as above
+];
+
+export default function PricingScreen({ navigation, customerId }) {
+  const { hasActiveSubscription } = usePayments({ customerId });
+
+  if (hasActiveSubscription()) {
+    return (
+      <View style={styles.container}>
+        <Text style={styles.title}>You're all set!</Text>
+        <Text style={styles.subtitle}>
+          Manage your subscription in the account settings.
+        </Text>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Choose Your Plan</Text>
+      <PricingTable
+        plans={plans}
+        customerId={customerId}
+        layout="carousel"
+        onCheckoutSuccess={(plan) => {
+          navigation.navigate('Success', { plan: plan.name });
+        }}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    padding: 20,
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    textAlign: 'center',
+    marginBottom: 20,
+  },
+  subtitle: {
+    fontSize: 16,
+    textAlign: 'center',
+    color: '#666',
+  },
+});
+```
+
+### Server API Routes (Next.js)
+
+```tsx
+// pages/api/payments/create-checkout-session.ts
+import { NextApiRequest, NextApiResponse } from 'next';
+import { StripeServerAPI } from '@digilogiclabs/saas-factory-payments/server';
+
+const stripeAPI = new StripeServerAPI(process.env.STRIPE_SECRET_KEY!);
+
+export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  try {
+    const { priceId, customerId, successUrl, cancelUrl } = req.body;
+
+    const session = await stripeAPI.createCheckoutSession({
+      priceId,
+      customerId,
+      successUrl,
+      cancelUrl,
+      allowPromotionCodes: true,
+    });
+
+    res.status(200).json({ sessionId: session.id });
+  } catch (error) {
+    console.error('Checkout session error:', error);
+    res.status(500).json({ error: 'Failed to create checkout session' });
+  }
+}
+```
+
+## CLI Integration
+
+This package is designed to work seamlessly with `create-saas-app`:
+
+```bash
+npx create-saas-app my-saas-app --payments=stripe
+```
+
+When using the `--payments=stripe` flag, the CLI will:
+
+1. **Install Dependencies**: Automatically install the payments package and required peer dependencies
+2. **Setup Environment**: Create `.env.example` with Stripe configuration variables
+3. **Generate API Routes**: Create Next.js API routes for checkout, webhooks, and subscription management
+4. **Configure Providers**: Set up PaymentsProvider and StripeProvider in your app
+5. **Add Database Schema**: Include subscription and customer tables for your database
+6. **Create Example Components**: Generate a basic pricing page with working checkout
+
+### Manual Integration
+
+If you're adding payments to an existing project:
+
+1. **Install the package and dependencies**
+2. **Set up environment variables**
+3. **Configure providers in your app**
+4. **Create API routes** (see examples above)
+5. **Set up webhook endpoints**
+6. **Add database tables for subscriptions and customers**
+
+## TypeScript Support
+
+This package is built with TypeScript and provides full type safety:
+
+```tsx
+import type { 
+  PricingPlan, 
+  Subscription, 
+  Customer,
+  PaymentsConfig 
+} from '@digilogiclabs/saas-factory-payments';
+
+// All components and hooks are fully typed
+const subscription: Subscription = {
+  id: 'sub_123',
+  customerId: 'cus_123',
+  priceId: 'price_123',
+  status: 'active',
+  currentPeriodStart: new Date(),
+  currentPeriodEnd: new Date(),
+  cancelAtPeriodEnd: false,
+};
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 📧 Email: support@digilogiclabs.com
+- 💬 Discord: [Join our community](https://discord.gg/digilogiclabs)
+- 📖 Documentation: [docs.digilogiclabs.com](https://docs.digilogiclabs.com)
+- 🐛 Issues: [GitHub Issues](https://github.com/DigiLogicLabs/saas-factory-payments/issues)
+
+---
+
+Built with ❤️ by [DigiLogicLabs](https://digilogiclabs.com)
+