subos-frontend 1.0.0 → 1.0.2

package/PACKAGE_REFERENCE.md

@@ -0,0 +1,822 @@
+# SubOS Frontend Package Reference
+
+## Overview
+
+SubOS Frontend is a comprehensive React component library for managing subscriptions, pricing, billing, and account logic in SaaS applications. This package provides ready-to-use components, hooks, and API integrations for building subscription management interfaces.
+
+**Built with:** React 19, TypeScript, Material-UI, Emotion, React Router DOM, Stripe
+
+---
+
+## 📦 Installation & Setup
+
+```bash
+npm install subos-frontend
+# or
+yarn add subos-frontend
+```
+
+### Required Peer Dependencies
+```bash
+npm install react react-dom react-router-dom @stripe/react-stripe-js @stripe/stripe-js
+```
+
+### Configuration (REQUIRED)
+```javascript
+import { configureSubOS } from 'subos-frontend';
+import 'subos-frontend/style.css';
+
+// Configure at app startup
+configureSubOS({
+  apiEndpoint: 'https://your-api.com/api/v1',
+  projectId: 'your-project-id',
+  stripePublishableKey: 'pk_test_your_stripe_key',
+  appName: 'Your App Name',
+  appEnvironment: 'production' // or 'development'
+});
+```
+
+---
+
+## 🎯 Components
+
+### Plan Components
+
+#### `PlanCard`
+Displays individual subscription plan details with selection functionality.
+
+**Props:**
+```typescript
+interface PlanCardProps {
+  plan: Plan;                    // Plan object with pricing and features
+  isSelected: boolean;           // Whether this plan is currently selected
+  billingCycle: 'monthly' | 'yearly'; // Current billing cycle filter
+  onSelect: (plan: Plan) => void; // Callback when plan is selected
+  isActive?: boolean;            // Whether this is user's current plan
+}
+```
+
+**Usage:**
+```jsx
+<PlanCard 
+  plan={planData}
+  isSelected={selectedPlan?.id === planData.id}
+  billingCycle="monthly"
+  onSelect={handlePlanSelect}
+  isActive={false}
+/>
+```
+
+#### `PlansGrid`
+Grid layout container for displaying multiple plan cards.
+
+**Props:**
+```typescript
+interface PlansGridProps {
+  plans: Plan[];                 // Array of plans to display
+  selectedPlan: Plan | null;     // Currently selected plan
+  billingCycle: 'monthly' | 'yearly'; // Billing cycle filter
+  onPlanSelect: (plan: Plan) => void; // Plan selection handler
+  activeSubscription?: Subscription; // User's current subscription
+}
+```
+
+#### `PlanSelector`
+Complete plan selection interface with filtering and selection.
+
+**Props:**
+```typescript
+interface PlanSelectorProps {
+  onPlanSelect: (plan: Plan) => void; // Plan selection callback
+  initialBillingCycle?: 'monthly' | 'yearly'; // Default billing cycle
+  showBillingToggle?: boolean;    // Show billing cycle toggle
+  showTierFilter?: boolean;       // Show tier filtering dropdown
+}
+```
+
+#### `BillingCycleToggle`
+Toggle component for switching between monthly and yearly billing.
+
+**Props:**
+```typescript
+interface BillingCycleToggleProps {
+  value: 'monthly' | 'yearly';   // Current billing cycle
+  onChange: (cycle: 'monthly' | 'yearly') => void; // Change handler
+  disabled?: boolean;            // Disable the toggle
+}
+```
+
+#### `TierFilterDropdown`
+Dropdown for filtering plans by tier/category.
+
+**Props:**
+```typescript
+interface TierFilterDropdownProps {
+  value: string;                 // Current filter value
+  onChange: (value: string) => void; // Filter change handler
+  options: DropdownOption[];     // Available filter options
+  disabled?: boolean;            // Disable the dropdown
+}
+```
+
+### Payment Components
+
+#### `ChangeCardButton`
+Button component for updating payment methods.
+
+**Props:**
+```typescript
+interface ChangeCardButtonProps {
+  onSuccess?: () => void;        // Success callback
+  onError?: (error: string) => void; // Error callback
+  customerId: string;            // Customer ID for payment method update
+}
+```
+
+#### `PaymentSuccessView`
+Success page component after successful payment.
+
+**Usage:**
+```jsx
+<PaymentSuccessView />
+```
+
+#### `PaymentCancelView`
+Cancellation page component when payment is cancelled.
+
+**Usage:**
+```jsx
+<PaymentCancelView />
+```
+
+### Subscription Components
+
+#### `SubscriptionDetails`
+Displays detailed information about user's subscription.
+
+**Props:**
+```typescript
+interface SubscriptionDetailsProps {
+  subscription: Subscription;    // Subscription data
+  onCancel?: () => void;        // Cancel subscription callback
+  onUpgrade?: () => void;       // Upgrade subscription callback
+  showActions?: boolean;        // Show action buttons
+}
+```
+
+### Transaction Components
+
+#### `TransactionList`
+List component for displaying transaction history.
+
+**Props:**
+```typescript
+interface TransactionListProps {
+  externalId: string;           // Customer external ID
+  filters?: TransactionFilters; // Optional transaction filters
+  onTransactionClick?: (transaction: Transaction) => void; // Transaction click handler
+}
+```
+
+#### `TransactionModal`
+Modal component for displaying transaction details.
+
+**Props:**
+```typescript
+interface TransactionModalProps {
+  transaction: Transaction | null; // Transaction to display
+  isOpen: boolean;              // Modal open state
+  onClose: () => void;          // Close modal callback
+}
+```
+
+### Email Components
+
+#### `EmailEntry`
+Component for email input and management.
+
+**Props:**
+```typescript
+interface EmailEntryProps {
+  value: string;                // Current email value
+  onChange: (email: string) => void; // Email change handler
+  onSubmit?: (email: string) => void; // Email submit handler
+  placeholder?: string;         // Input placeholder
+  disabled?: boolean;           // Disable input
+}
+```
+
+### Upgrade Components
+
+#### `UpgradeSummary`
+Summary component showing upgrade details and pricing.
+
+**Props:**
+```typescript
+interface UpgradeSummaryProps {
+  currentPlan: Plan;            // User's current plan
+  newPlan: Plan;               // Plan to upgrade to
+  onConfirm: () => void;       // Upgrade confirmation callback
+  onCancel: () => void;        // Cancel upgrade callback
+}
+```
+
+### Common Components
+
+#### `Layout`
+Main layout wrapper component.
+
+**Usage:**
+```jsx
+<Layout>
+  <YourContent />
+</Layout>
+```
+
+#### `LogoInline`
+Inline logo component.
+
+**Usage:**
+```jsx
+<LogoInline />
+```
+
+#### `Pagination`
+Pagination component for paginated data.
+
+**Props:**
+```typescript
+interface PaginationProps {
+  currentPage: number;          // Current page number
+  totalPages: number;           // Total number of pages
+  onPageChange: (page: number) => void; // Page change handler
+  disabled?: boolean;           // Disable pagination
+}
+```
+
+### Icon Components
+
+#### `CheckIcon`
+Check mark icon component.
+
+**Props:**
+```typescript
+interface CheckIconProps {
+  className?: string;           // CSS classes
+  size?: number;               // Icon size
+}
+```
+
+---
+
+## 🪝 Hooks
+
+### `usePlans()`
+Hook for managing plan data and filtering.
+
+**Returns:**
+```typescript
+interface UsePlansReturn {
+  // Data
+  plans: Plan[];                // All available plans
+  filteredPlans: Plan[];        // Filtered plans based on current filters
+  selectedPlan: Plan | null;    // Currently selected plan
+  
+  // Filters
+  tierFilter: string;           // Current tier filter
+  billingCycle: 'monthly' | 'yearly'; // Current billing cycle
+  
+  // Loading states
+  loading: boolean;             // Loading state
+  error: string | null;         // Error message
+  
+  // Actions
+  fetchPlans: () => Promise<void>; // Fetch plans from API
+  setSelectedPlan: (plan: Plan | null) => void; // Set selected plan
+  setTierFilter: (filter: string) => void; // Set tier filter
+  setBillingCycle: (cycle: 'monthly' | 'yearly') => void; // Set billing cycle
+  clearPlans: () => void;       // Clear all plans
+  
+  // Computed values
+  dropdownOptions: DropdownOption[]; // Options for tier dropdown
+  currentSelectionText: string; // Current filter description
+  
+  // Plan operations
+  handlePlanSelect: (plan: Plan) => void; // Handle plan selection
+  handleUpgrade: (email: string) => Promise<void>; // Handle plan upgrade
+}
+```
+
+**Usage:**
+```jsx
+const {
+  plans,
+  filteredPlans,
+  selectedPlan,
+  loading,
+  error,
+  fetchPlans,
+  setSelectedPlan,
+  setBillingCycle
+} = usePlans();
+```
+
+### `useSubscription()`
+Hook for managing subscription data.
+
+**Returns:**
+```typescript
+interface UseSubscriptionReturn {
+  subscription: Subscription | null; // Current subscription
+  loading: boolean;             // Loading state
+  error: string | null;         // Error message
+  fetchSubscription: (externalId: string) => Promise<void>; // Fetch subscription
+  cancelSubscription: (externalId: string, options?: CancelOptions) => Promise<void>; // Cancel subscription
+}
+```
+
+### `useTransactions()`
+Hook for managing transaction history.
+
+**Props:**
+```typescript
+interface UseTransactionsProps {
+  externalId: string;           // Customer external ID
+  filters?: TransactionFilters; // Transaction filters
+}
+```
+
+**Returns:**
+```typescript
+interface UseTransactionsReturn {
+  transactions: Transaction[];  // Transaction list
+  loading: boolean;             // Loading state
+  error: string | null;         // Error message
+  pagination: PaginationMeta;   // Pagination information
+  fetchTransactions: () => Promise<void>; // Fetch transactions
+  downloadInvoice: (transactionId: string) => Promise<void>; // Download invoice
+}
+```
+
+### `usePagination()`
+Hook for managing pagination state.
+
+**Props:**
+```typescript
+interface UsePaginationProps {
+  totalItems: number;           // Total number of items
+  itemsPerPage: number;         // Items per page
+  initialPage?: number;         // Initial page number
+}
+```
+
+**Returns:**
+```typescript
+interface UsePaginationReturn {
+  currentPage: number;          // Current page
+  totalPages: number;           // Total pages
+  hasNextPage: boolean;         // Has next page
+  hasPreviousPage: boolean;     // Has previous page
+  goToPage: (page: number) => void; // Go to specific page
+  nextPage: () => void;         // Go to next page
+  previousPage: () => void;     // Go to previous page
+}
+```
+
+### `useCancelSubscription()`
+Hook for cancelling subscriptions.
+
+**Props:**
+```typescript
+interface UseCancelSubscriptionProps {
+  externalId: string;           // Customer external ID
+  onSuccess?: () => void;       // Success callback
+  onError?: (error: string) => void; // Error callback
+}
+```
+
+**Returns:**
+```typescript
+interface UseCancelSubscriptionReturn {
+  cancelSubscription: (options?: CancelOptions) => Promise<void>; // Cancel function
+  loading: boolean;             // Loading state
+  error: string | null;         // Error message
+}
+```
+
+### `useCustomerPortal()`
+Hook for customer portal functionality.
+
+**Props:**
+```typescript
+interface UseCustomerPortalProps {
+  externalId: string;           // Customer external ID
+}
+```
+
+**Returns:**
+```typescript
+interface UseCustomerPortalReturn {
+  redirectToPortal: () => Promise<void>; // Redirect to customer portal
+  loading: boolean;             // Loading state
+  error: string | null;         // Error message
+}
+```
+
+### `useEmailManagement()`
+Hook for email management functionality.
+
+**Returns:**
+```typescript
+interface UseEmailManagementReturn {
+  email: string;                // Current email
+  setEmail: (email: string) => void; // Set email
+  validateEmail: (email: string) => boolean; // Validate email
+  saveEmail: () => Promise<void>; // Save email
+  loading: boolean;             // Loading state
+  error: string | null;         // Error message
+}
+```
+
+---
+
+## 🌐 API Functions
+
+### Plans API
+
+#### `plansApi.getPlans()`
+Fetch all available plans.
+
+**Request:** No payload required
+
+**Response:**
+```typescript
+ApiResponse<Plan[]>
+```
+
+**Usage:**
+```javascript
+const response = await plansApi.getPlans();
+if (response.success) {
+  console.log(response.data); // Plan[]
+}
+```
+
+#### `plansApi.getPlanByCode(code, externalId, queryParams?)`
+Fetch specific plan by code.
+
+**Parameters:**
+- `code: string` - Plan code
+- `externalId: string` - Customer external ID
+- `queryParams?: { paymentMethodId?: string; couponCode?: string }` - Optional query parameters
+
+**Response:**
+```typescript
+ApiResponse<Plan>
+```
+
+#### `plansApi.createPaymentSession(planCode, options?)`
+Create payment session for checkout.
+
+**Parameters:**
+- `planCode: string` - Plan code to purchase
+- `options?: { amount?: number; currency?: string; customerEmail?: string; couponCode?: string }` - Optional parameters
+
+**Payload:**
+```typescript
+{
+  planCode: string;
+  currency?: string;           // Default: 'USD'
+  returnUrl: string;           // Auto-generated: ${origin}/payment-success
+  cancelUrl: string;           // Auto-generated: ${origin}/payment-cancel
+  customerEmail?: string;      // Optional customer email
+  couponCode?: string;         // Optional coupon code
+  amount?: number;             // Optional custom amount
+}
+```
+
+**Response:**
+```typescript
+ApiResponse<{
+  checkoutUrl: string;         // Hosted checkout URL
+  gateway: string;             // Payment gateway used
+  sessionId?: string;          // Session ID
+  paymentId?: string;          // Payment ID
+}>
+```
+
+### Checkout API
+
+#### `checkoutApi.getCheckoutDetails(planCode, queryParams?)`
+Get checkout details including pricing and taxes.
+
+**Parameters:**
+- `planCode: string` - Plan code
+- `queryParams?: { externalId?: string; paymentMethodId?: string; couponCode?: string }` - Optional parameters
+
+**Response:**
+```typescript
+ApiResponse<CheckoutDetails>
+```
+
+### Subscription API
+
+#### `subscriptionApi.getActiveSubscription(externalId)`
+Get user's active subscription.
+
+**Parameters:**
+- `externalId: string` - Customer external ID
+
+**Response:**
+```typescript
+ApiResponse<Subscription>
+```
+
+#### `subscriptionApi.cancelSubscription(externalId, options?)`
+Cancel user's subscription.
+
+**Parameters:**
+- `externalId: string` - Customer external ID
+- `options?: { cancellationMode?: string; cancellationReason?: string }` - Cancellation options
+
+**Response:**
+```typescript
+ApiResponse<any>
+```
+
+### Customer API
+
+#### `customerApi.getCustomer(externalId)`
+Get customer information.
+
+**Parameters:**
+- `externalId: string` - Customer external ID
+
+**Response:**
+```typescript
+ApiResponse<Customer>
+```
+
+### Transaction API
+
+#### `transactionApi.getTransactions(externalId, filters?)`
+Get customer's transaction history.
+
+**Parameters:**
+- `externalId: string` - Customer external ID
+- `filters?: TransactionFilters` - Optional filters
+
+**Filters:**
+```typescript
+interface TransactionFilters {
+  startDate?: string;          // ISO date string
+  endDate?: string;            // ISO date string
+  status?: string;             // Transaction status
+  page?: number;               // Page number (1-based)
+  limit?: number;              // Items per page
+}
+```
+
+**Response:**
+```typescript
+ApiResponse<PaginatedResponse<Transaction>>
+```
+
+#### `transactionApi.getInvoice(transactionId)`
+Get invoice URL for a transaction.
+
+**Parameters:**
+- `transactionId: string` - Transaction ID
+
+**Response:**
+```typescript
+ApiResponse<{ invoiceUrl: string }>
+```
+
+---
+
+## 🛠 Utility Functions
+
+### Plan Utilities
+
+- `getPlanFeatures(plan: Plan): string[]` - Extract features from plan
+- `getCandidateUnits(plans: Plan[]): string[]` - Get unique plan units
+- `getUniqueCandidateUnits(plans: Plan[]): string[]` - Get unique candidate units
+- `getDropdownOptions(plans: Plan[]): DropdownOption[]` - Generate dropdown options
+- `getCurrentSelectionText(filter: string, options: DropdownOption[]): string` - Get current filter text
+- `filterPlansByBillingCycle(plans: Plan[], cycle: 'monthly' | 'yearly'): Plan[]` - Filter by billing cycle
+- `filterPlansByTier(plans: Plan[], tier: string): Plan[]` - Filter by tier
+- `isPlanPopular(plan: Plan): boolean` - Check if plan is marked as popular
+- `getPlanDescription(plan: Plan): string` - Get plan description
+- `formatDate(date: string): string` - Format date string
+
+---
+
+## 📝 TypeScript Types
+
+### Core Types
+
+```typescript
+interface Plan {
+  id: string;
+  name: string;
+  code: string;
+  fixedCost: number;
+  paymentMode: string;
+  interval: string;
+  successRedirectUrl: string;
+  order: number;
+  isDefault: boolean;
+  intervalCount: number;
+  projectId: string;
+  charges: any[];
+  description?: string;
+  price?: number;
+  billingFrequency?: 'monthly' | 'yearly' | 'one-time';
+  features?: string[];
+  isPopular?: boolean;
+}
+
+interface Subscription {
+  id: string;
+  isActive: boolean;
+  membershipDate: string;
+  expiryDate: string;
+  meta: Record<string, any>;
+  isPaymentFailed?: boolean;
+  transactionCode?: string;
+  usage: Record<string, any>;
+  plan: {
+    name: string;
+    code: string;
+    fixedCost: number;
+    paymentMode: string;
+    interval: string;
+    trialDays?: number;
+    charges: Array<{
+      billableMetric: {
+        code: string;
+        name: string;
+      };
+      chargeModel: string;
+      properties: Record<string, any>;
+    }>;
+    charge: number;
+    canceledOn: string | null;
+    features?: string[];
+  };
+  tax?: number;
+  amount?: number;
+  customer?: {
+    paymentMethodCurrency: string;
+    paymentMethodId?: string;
+  };
+  gracePeriodEndDate?: string;
+  remainingGracePeriodDays?: number;
+}
+
+interface Transaction {
+  id: string;
+  transactionCode?: string;
+  customerId?: string;
+  membershipId?: string;
+  purchaseId?: string;
+  amount: string | number;
+  tax?: number;
+  charge?: string | number;
+  membershipDate: string;
+  expiryDate: string;
+  transactionDate?: string;
+  transactionStatus: string;
+  paymentGateway?: string;
+  planName?: string;
+  planInterval?: string;
+  currency?: string;
+  coupon?: string | null;
+  discountAmt?: string | number;
+  isPlanActive?: boolean;
+  order?: number;
+  meta?: Record<string, any>;
+  invoiceUrl?: string;
+}
+
+interface ApiResponse<T> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+```
+
+---
+
+## 🚀 Complete Usage Example
+
+```jsx
+import React from 'react';
+import {
+  configureSubOS,
+  PlanSelector,
+  SubscriptionDetails,
+  TransactionList,
+  usePlans,
+  useSubscription,
+  useTransactions
+} from 'subos-frontend';
+import 'subos-frontend/style.css';
+
+// Configure SubOS
+configureSubOS({
+  apiEndpoint: 'https://api.example.com/v1',
+  projectId: 'your-project-id',
+  stripePublishableKey: 'pk_test_...',
+  appName: 'My SaaS App'
+});
+
+function SubscriptionApp() {
+  const { selectedPlan, handlePlanSelect } = usePlans();
+  const { subscription } = useSubscription();
+  const { transactions } = useTransactions({ 
+    externalId: 'customer-123' 
+  });
+
+  return (
+    <div className="app">
+      <h1>Subscription Management</h1>
+      
+      {/* Plan Selection */}
+      <section>
+        <h2>Choose Your Plan</h2>
+        <PlanSelector onPlanSelect={handlePlanSelect} />
+      </section>
+
+      {/* Current Subscription */}
+      {subscription && (
+        <section>
+          <h2>Current Subscription</h2>
+          <SubscriptionDetails 
+            subscription={subscription}
+            showActions={true}
+          />
+        </section>
+      )}
+
+      {/* Transaction History */}
+      <section>
+        <h2>Transaction History</h2>
+        <TransactionList externalId="customer-123" />
+      </section>
+    </div>
+  );
+}
+
+export default SubscriptionApp;
+```
+
+---
+
+## 🔧 Configuration Options
+
+### Environment Variables
+```bash
+VITE_API_ENDPOINT=https://your-api.com/api/v1
+VITE_PROJECT_ID=your-project-id
+VITE_STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_key
+VITE_APP_NAME=Your App Name
+VITE_APP_ENVIRONMENT=production
+```
+
+### Runtime Configuration
+```javascript
+configureSubOS({
+  apiEndpoint: string;          // Required: API base URL
+  projectId: string;            // Required: Project identifier
+  stripePublishableKey: string; // Required: Stripe publishable key
+  appName?: string;             // Optional: Application name
+  appEnvironment?: string;      // Optional: Environment (development/production)
+});
+```
+
+---
+
+## 📋 Requirements
+
+- **React**: >=18
+- **React DOM**: >=18  
+- **React Router DOM**: >=6
+- **Stripe**: @stripe/react-stripe-js, @stripe/stripe-js
+
+---
+
+## 🎨 Styling
+
+The package includes pre-built CSS that should be imported:
+
+```javascript
+import 'subos-frontend/style.css';
+```
+
+Components use Tailwind CSS classes and can be customized by overriding the CSS variables or classes.
+
+---
+
+This documentation provides a complete reference for integrating and using the SubOS Frontend package in your React applications. Each component and hook is designed to work independently or together to create a complete subscription management experience.