Optum Subs - Subscription Management Package

A powerful, customizable subscription and checkout system for React applications. Built with TypeScript, Tailwind CSS, and Lucide icons for a modern, professional experience.

✨ Features

• 🛒 Smart Cart Management: Add, remove, and manage subscription plans with real-time updates
• 💳 Flexible Checkout: Generate checkout URLs with cart data or direct plan purchase
• 📊 Advanced Pricing: Handle multiple billing cycles (weekly, monthly, quarterly, half-yearly, yearly) with discounts
• 🎨 Color Scheme Customization: Complete control over colors, gradients, and theming
• 🔄 State Management: Built-in React state management with hooks
• 🎯 Beautiful Default UI: Professional design with hover effects and animations
• 🎨 Customizable UI: Replace any component with render props
• 📱 Responsive Design: Perfect on all device sizes
• ⚡ TypeScript: Full type safety and IntelliSense support
• 🎨 Lucide Icons: Modern, consistent iconography

📦 Installation

npm install optum-subs
# or
yarn add optum-subs
# or
pnpm add optum-subs

🚀 Quick Start

Basic Usage

import { Subscription } from 'optum-subs';

function App() {
  const [apiData, setApiData] = useState(null);

  useEffect(() => {
    // Fetch your subscription data
    const fetchData = async () => {
      const response = await fetch('/api/subscriptions');
      const data = await response.json();
      setApiData(data);
    };
    fetchData();
  }, []);

  return (
      <Subscription 
        apiData={apiData}
        config={{
        showCart: true,
        currencySymbol: '₹'
        }}
      />
  );
}

With Color Scheme Customization

import { Subscription } from 'optum-subs';

function App() {
  const [apiData, setApiData] = useState(null);

  const colorScheme = {
    primary: '#3B82F6',      // Blue
    secondary: '#64748B',    // Slate
    accent: '#F59E0B',       // Amber
    background: '#FFFFFF',   // White
    text: '#1F2937',         // Gray-800
    border: '#E5E7EB',       // Gray-200
    gradient: {
      from: '#3B82F6',       // Blue
      to: '#1D4ED8'          // Blue-700
    }
  };

  return (
      <Subscription 
        apiData={apiData}
      colorScheme={colorScheme}
      config={{
        showCart: true,
        currencySymbol: '₹'
      }}
    />
  );
}

⚙️ Configuration

SubscriptionConfig

The main configuration object for the Subscription component:

interface SubscriptionConfig {
  initialPlanType?: 'subscriptionPlans' | 'modelPortfolios';
  initialSortBy?: string;
  currencySymbol?: string;
  showCart?: boolean;
  enableSorting?: boolean;
  enableFiltering?: boolean;
  showSavingsAsPercentage?: boolean;
}

Configuration Options

Example Configuration

const config = {
  initialPlanType: 'subscriptionPlans',
  initialSortBy: 'price-asc',
  currencySymbol: '$',
  showCart: true,
  enableSorting: true,
  enableFiltering: true,
  showSavingsAsPercentage: true
};

<Subscription apiData={apiData} config={config} />

🎨 Color Scheme Customization

The package supports comprehensive color scheme customization through the colorScheme prop:

Color Scheme Interface

interface ColorScheme {
  primary?: string;        // Primary brand color
  secondary?: string;      // Secondary color
  accent?: string;         // Accent color
  background?: string;     // Background color
  text?: string;          // Text color
  border?: string;        // Border color
  gradient?: {
    from?: string;        // Gradient start color
    to?: string;          // Gradient end color
  };
}

Color Scheme Examples

Blue Theme (Default)

const blueTheme = {
  primary: '#3B82F6',
  secondary: '#64748B',
  accent: '#F59E0B',
  background: '#FFFFFF',
  text: '#1F2937',
  border: '#E5E7EB',
  gradient: {
    from: '#3B82F6',
    to: '#1D4ED8'
  }
};

Purple Theme

const purpleTheme = {
  primary: '#8B5CF6',
  secondary: '#64748B',
  accent: '#F59E0B',
  background: '#FFFFFF',
  text: '#1F2937',
  border: '#E5E7EB',
  gradient: {
    from: '#8B5CF6',
    to: '#7C3AED'
  }
};

Green Theme

const greenTheme = {
  primary: '#10B981',
  secondary: '#64748B',
  accent: '#F59E0B',
  background: '#FFFFFF',
  text: '#1F2937',
  border: '#E5E7EB',
  gradient: {
    from: '#10B981',
    to: '#059669'
  }
};

Dark Theme

const darkTheme = {
  primary: '#3B82F6',
  secondary: '#94A3B8',
  accent: '#F59E0B',
  background: '#1F2937',
  text: '#F9FAFB',
  border: '#374151',
  gradient: {
    from: '#3B82F6',
    to: '#1D4ED8'
  }
};

How Color Scheme Works

The color scheme is applied using CSS custom properties and inline styles:

1. CSS Custom Properties: Colors are set as CSS variables for consistent theming
2. Inline Styles: Specific elements use inline styles for precise control
3. Opacity Variants: Primary color automatically generates opacity variants (10%, 5%, 90%)
4. Gradient Support: Linear gradients for buttons and highlights

Elements That Use Color Scheme

Visual Color Reference

Here's a visual breakdown of how colors are applied:

┌─────────────────────────────────────────────────────────────┐
│                    SUBSCRIPTION COMPONENT                   │
├─────────────────────────────────────────────────────────────┤
│  [Tab Navigation] ── primary (10% bg) + primary (text)      │
│  [Selected Tab] ──── white (bg) + primary (text)           │
│  [Sort Dropdown] ─── primary (border) + primary (text)     │
│  [Cart Icon] ─────── gradient (bg) + white (text)          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   PLAN CARD 1   │  │   PLAN CARD 2   │  │   PLAN CARD 3   │ │
│  │                 │  │                 │  │                 │ │
│  │ Title: primary  │  │ Title: primary  │  │ Title: primary  │ │
│  │ Price: primary  │  │ Price: primary  │  │ Price: primary  │ │
│  │                 │  │                 │  │                 │ │
│  │ [Cycle Options] │  │ [Cycle Options] │  │ [Cycle Options] │ │
│  │ Selected:       │  │ Selected:       │  │ Selected:       │ │
│  │ primary (bg)    │  │ primary (bg)    │  │ primary (bg)    │ │
│  │ + primary (border)│ │ + primary (border)│ │ + primary (border)│ │
│  │                 │  │                 │  │                 │ │
│  │ ✓ Feature 1     │  │ ✓ Feature 1     │  │ ✓ Feature 1     │ │
│  │ ✓ Feature 2     │  │ ✓ Feature 2     │  │ ✓ Feature 2     │ │
│  │ (checkmark: primary)│ (checkmark: primary)│ (checkmark: primary)│ │
│  │                 │  │                 │  │                 │ │
│  │ [Add to Cart]   │  │ [Add to Cart]   │  │ [Add to Cart]   │ │
│  │ gradient (bg)   │  │ gradient (bg)   │  │ gradient (bg)   │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                    CART COMPONENT                           │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ Cart Header: primary (text)                             │ │
│  │ ┌─────────────────────────────────────────────────────┐ │ │
│  │ │ Item 1: primary (border) + primary (text)          │ │ │
│  │ │ Item 2: primary (border) + primary (text)          │ │ │
│  │ └─────────────────────────────────────────────────────┘ │ │
│  │ Cart Footer: primary (text)                             │ │
│  │ [Checkout]: gradient (bg)                               │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Color Scheme Property Mapping Summary

Note: The primary color is the most important property as it controls the majority of the UI elements. The gradient properties are used for buttons and interactive elements to create visual hierarchy.

📊 API Data Structure

The package expects data in this format:

interface ApiData {
  subscriptionPlans: PricingPackage[];
  modelPortfolios: PricingPackage[];
}

interface PricingPackage {
  id: string;
  title: string;
  package_name?: string;  // Alternative to title
  description: string;
  prices: {
    weekly: number;
    monthly: number;
    quarterly: number;
    halfyearly: number;
    yearly: number;
  };
  discounted: {
    weekly: number;
    monthly: number;
    quarterly: number;
    halfyearly: number;
    yearly: number;
  };
  features: Array<{
    [key: string]: string;  // e.g., { "features1": "Feature description" }
  }>;
  popular?: boolean;
}

Example API Response

{
  "subscriptionPlans": [
    {
      "package_code_str": "20258156285092043",
      "package_name": "Stock & Index Options",
      "description": "This Package includes Stock Options and Index Options both",
      "prices": {
        "weekly": 6000.0,
        "monthly": 17000.0,
        "quarterly": 40000.0,
        "halfyearly": 80000.0,
        "yearly": 160000.0
      },
      "discounted": {
        "weekly": 4000.0,
        "monthly": 15000.0,
        "quarterly": 36000.0,
        "halfyearly": 70000.0,
        "yearly": 120000.0
      },
      "features": [
        { "features1": "Swing Positions and volume" },
        { "features2": "Average of 30% Return history of Recommendations" },
        { "features3": "Call & Put combinations to keep the balance" },
        { "features4": "Premium calls" }
      ]
    }
  ],
  "modelPortfolios": []
}

🎨 Custom UI Components

Render Props

You can replace any component using render props:

<Subscription
  apiData={apiData}
  renderPlanCard={({ plan, onAddToCart, isInCart }) => (
    <div className="my-custom-card">
      <h3>{plan.package_name}</h3>
      <button onClick={onAddToCart}>
        {isInCart ? 'In Cart' : 'Add to Cart'}
      </button>
    </div>
  )}
  renderHeader={({ planType, setPlanType }) => (
    <div className="my-custom-header">
      <button onClick={() => setPlanType('subscriptionPlans')}>
        Plans
      </button>
    </div>
  )}
  renderCart={({ cart, isCartOpen, closeCart }) => (
    <div className="my-custom-cart">
      {/* Your custom cart UI */}
    </div>
  )}
/>

Available Render Props

🛒 Cart Functionality

Cart Features

• Add to Cart: Add plans with selected billing cycles
• Remove from Cart: Remove plans from cart
• Update Cycles: Change billing cycles for cart items
• Cart Count: Real-time cart item count
• Checkout: Generate checkout URLs with cart data

Cart Configuration

// Enable cart (default)
config={{ showCart: true }}

// Disable cart
config={{ showCart: false }}

Cart Data Structure

interface CartItem {
  plan: PricingPackage;
  cycle: BillingCycle;
}

🔧 Advanced Usage

Custom Hooks

import { useSubscription } from 'optum-subs';

function CustomComponent() {
  const {
    subscriptionPlans,
    modelPortfolios,
    loading,
    error,
    selectedCycles,
    setSelectedCycle,
    getDiscountInfo,
    getAvailableCycles
  } = useSubscription({
    initialData: apiData,
    config: { showCart: true }
  });

  // Use the data and functions
}

Utility Functions

import { 
  calculateDiscountInfo, 
  formatPrice, 
  generateCheckoutUrl 
} from 'optum-subs';

// Calculate discount for a plan
const discountInfo = calculateDiscountInfo(plan, 'monthly');

// Format price with currency
const formattedPrice = formatPrice(1000, '₹');

// Generate checkout URL
const checkoutUrl = generateCheckoutUrl(cartItems, 'https://checkout.com');

📱 Responsive Design

The package is fully responsive with these breakpoints:

• Mobile: Single column layout
• Tablet: Two column layout
• Desktop: Three column layout

🎯 Features

Smart Default Selection

• Automatically selects the minimum price cycle for each plan
• Preserves user selections when switching between plans
• Handles missing pricing cycles gracefully

Sorting Options

• Default: Original order
• Price: Low to High: Sort by minimum price
• Price: High to Low: Sort by maximum price
• Name: Alphabetical by plan name

Conditional Rendering

• Model Portfolios Tab: Only shows if modelPortfolios array has items
• Cart Icon: Only shows when cart has items
• Savings Display: Only shows when discounts are available

🔍 TypeScript Support

Full TypeScript support with exported types:

import { 
  PricingPackage, 
  BillingCycle, 
  CartItem, 
  SubscriptionConfig,
  ColorScheme,
  DiscountInfo
} from 'optum-subs';

🚀 Performance

• Optimized Rendering: Uses React.memo and useMemo for performance
• Lazy Loading: Components load only when needed
• Minimal Re-renders: Efficient state management
• Bundle Size: Tree-shakeable and optimized

🛠️ Development

Local Development

For local development without publishing to npm, see LOCAL_DEVELOPMENT.md.

Building

# Install dependencies
npm install

# Build the package
npm run build

# Development mode with watch
npm run dev

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📞 Support

For issues, questions, or contributions, please open an issue on GitHub.