🚀 Subscription Status Plugin

A lightweight, beautiful plugin to check subscription status via API and display elegant renewal prompts. Works with any website - React, Vue, Angular, or vanilla JavaScript.

✨ Features

• 🎨 Beautiful UI - Modern modal design with smooth animations
• 🔧 Universal Compatibility - Works with any framework or vanilla JS
• ⚡ Lightweight - Minimal bundle size with excellent performance
• 🎯 Customizable - Easy theming and configuration options
• 📱 Responsive - Mobile-friendly design
• 🌙 Dark Mode - Automatic theme detection
• 🔒 Type Safe - Full TypeScript support

📦 Installation

npm install smess-plugin-subscription

🚀 Quick Start

React Usage

import { SubscriptionPlugin } from 'smess-plugin-subscription';
import 'smess-plugin-subscription/dist/styles.css';

function App() {
  return (
    <SubscriptionPlugin 
      apiEndpoint="/api/subscription/status"
      userId="user-123"
      onReactivate={() => window.open('/billing', '_blank')}
    />
  );
}

Vanilla JavaScript Usage

<!-- Include CSS -->
<link rel="stylesheet" href="node_modules/smess-plugin-subscription/dist/styles.css">

<!-- Include JS -->
<script src="node_modules/smess-plugin-subscription/dist/vanilla/subscription-plugin.js"></script>

<script>
const plugin = new SubscriptionStatusPlugin({
  apiEndpoint: '/api/subscription/status',
  userId: 'user-123',
  onReactivate: () => window.open('/billing', '_blank'),
  checkInterval: 300000 // Check every 5 minutes
});

plugin.init();
</script>

CDN Usage

<!-- CSS -->
<link rel="stylesheet" href="https://unpkg.com/smess-plugin-subscription/dist/styles.css">

<!-- JavaScript -->
<script src="https://unpkg.com/smess-plugin-subscription/dist/vanilla/subscription-plugin.js"></script>

⚙️ Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiEndpoint | string | Required | API endpoint to check subscription status | | userId | string | undefined | User ID to check (sent as X-User-ID header) | | onReactivate | function | undefined | Callback when user clicks reactivate button | | onClose | function | undefined | Callback when modal is closed | | checkInterval | number | 300000 | How often to check status (milliseconds) | | theme | string | 'auto' | Theme: 'light', 'dark', or 'auto' | | position | string | 'center' | Modal position: 'center', 'top', or 'bottom' |

📡 API Response Format

Your API endpoint should return JSON in this format:

{
  "isExpired": true,
  "planName": "Pro Plan",
  "expiryDate": "2024-01-15",
  "userId": "user-123"
}

🎨 Customizing Colors

Method 1: CSS Variables (Recommended)

:root {
  /* Primary colors */
  --primary: 142 76% 36%;        /* Green theme */
  --primary-glow: 142 76% 60%;
  
  /* Warning colors */
  --warning: 45 93% 58%;         /* Yellow warning */  
  --warning-glow: 45 93% 75%;
}

Method 2: Pre-built Themes

Choose from 5 beautiful themes:

• Ocean Blue (default) - Professional blue with orange accents
• Forest Green - Nature-inspired green with yellow warnings
• Royal Purple - Elegant purple with red warnings
• Sunset Orange - Warm orange theme with red alerts
• Tech Dark - High-tech cyan with bright warnings

Method 3: JavaScript Configuration

const plugin = new SubscriptionStatusPlugin({
  apiEndpoint: '/api/subscription/status',
  customStyles: {
    primaryColor: 'hsl(142, 76%, 36%)',
    warningColor: 'hsl(45, 93%, 58%)',
    primaryGlow: 'hsl(142, 76%, 60%)',
    warningGlow: 'hsl(45, 93%, 75%)'
  }
});

🛠️ Development

Prerequisites

• Node.js 16+
• npm or yarn

Setup

# Clone the repository
git clone <repository-url>
cd smess-plugin-subscription

# Install dependencies
make install

# Start development server
make dev

Build Commands

# Show all available commands
make help

# Development
make dev          # Start dev server
make install      # Install dependencies

# Building
make build        # Build demo site
make build-lib    # Build library for npm
make package      # Create npm package

# Quality
make lint         # Run linting
make test         # Run tests
make clean        # Clean build files

# Publishing
make version      # Show current version
make release      # Prepare new release
make publish      # Publish to npm

Project Structure

smess-plugin-subscription/
├── src/
│   ├── components/           # React components
│   │   ├── SubscriptionPlugin.tsx
│   │   ├── PluginDemo.tsx
│   │   └── ColorCustomizer.tsx
│   ├── lib/                 # Vanilla JS library
│   │   └── subscription-plugin.ts
│   ├── pages/               # Demo pages
│   └── index.css            # Styles and design tokens
├── dist/                    # Built library files
├── Makefile                 # Build automation
└── package.json

🚀 Publishing to NPM

1. Prepare Release

# Update version and build
make release

2. Login to NPM

npm login

3. Publish

make publish

4. Verify Publication

npm view smess-plugin-subscription

📝 API Integration Examples

Express.js Backend

app.get('/api/subscription/status', async (req, res) => {
  const userId = req.headers['x-user-id'];
  
  // Check subscription in your database
  const subscription = await getSubscription(userId);
  
  res.json({
    isExpired: subscription.expiryDate < new Date(),
    planName: subscription.planName,
    expiryDate: subscription.expiryDate.toISOString(),
    userId: userId
  });
});

Next.js API Route

// pages/api/subscription/status.js
export default async function handler(req, res) {
  const userId = req.headers['x-user-id'];
  
  const subscription = await checkUserSubscription(userId);
  
  res.status(200).json({
    isExpired: subscription.expired,
    planName: subscription.plan,
    expiryDate: subscription.expiryDate,
    userId: userId
  });
}

🎯 Usage Examples

E-commerce Site

const plugin = new SubscriptionStatusPlugin({
  apiEndpoint: '/api/subscription/check',
  userId: getCurrentUserId(),
  onReactivate: () => {
    // Redirect to checkout
    window.location.href = '/checkout?plan=premium';
  },
  checkInterval: 600000 // Check every 10 minutes
});

SaaS Dashboard

<SubscriptionPlugin 
  apiEndpoint="/api/user/subscription"
  userId={user.id}
  onReactivate={() => {
    analytics.track('subscription_reactivate_clicked');
    router.push('/billing');
  }}
  onClose={() => {
    analytics.track('subscription_modal_dismissed');
  }}
/>

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📚 Documentation
• 💬 Discord Community
• 🐛 Issue Tracker

Made with ❤️ using Lovable