@moneybar.online/moneybar 9.0.1 → 9.0.2

package/README.md

@@ -1,424 +1,275 @@
-# MoneyBar - Complete Integration Guide
-## The NavBar of Monetization
+# MoneyBar
 
-> **Every product has a navbar for navigation. Every product needs a moneybar for monetization.**
+**The navbar that gets you money faster.** Complete backend infrastructure included. Setup in 1 minute.
 
-MoneyBar fixes the 3 critical money-blocking stages that prevent revenue from reaching your bank account, even when your product is good enough. Add usage limiting and premium upgrades to any web app in **3 simple steps**.
-
-[![npm version](https://badge.fury.io/js/%40moneybar.online%2Fmoneybar.svg)](https://www.npmjs.com/package/@moneybar.online/moneybar)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+MoneyBar handles authentication, payment processing, usage limits, and subscription management - all in one navbar component. No backend coding required.
 
 ---
 
-## 🏗️ Architecture Guidelines
+## Quick Start (2 Steps)
 
-**Keep your code clean with proper separation:**
+### Step 1: Copy & Customize Config
 
-### ✅ Recommended File Structure
-```
-index.html          // Only your custom business functions
-moneybar-config.js   // All MoneyBar configuration and setup
-```
+Copy `moneybar-config-template.js` to your project and customize these settings:
 
-### 🚫 Avoid This
-- Don't mix MoneyBar configuration directly in HTML files
-- Don't put business logic in config files
-- Keep concerns separated for maintainability
+```javascript
+const CONFIG = {
+  // ========================================
+  // CUSTOMIZABLE SETTINGS
+  // ========================================
 
-### 📋 Template Prompt
-When creating MoneyBar projects, follow this structure:
-> "HTML should contain only custom business functions. All MoneyBar configuration, initialization, and attachToButton calls should be in a separate config file."
+  // Security key - Get yours from Supabase
+  // Run: SELECT generate_security_key('my-app', 'yourdomain.com', 'your@email.com', 3)
+  security_key: 'sk_...',
 
----
+  // What are users doing? (shown in UI: "PDF Generations: 2/3")
+  actionLabel: 'PDF Generations', // Examples: 'Image Exports', 'Downloads', 'AI Requests'
 
-## 🚀 Installation & Usage
+  // How many free attempts before paywall?
+  freeAttemptLimit: 3,
 
-### Option 1: NPM Install (For projects with bundlers)
-```bash
-npm install @moneybar.online/moneybar
-```
+  // Payment setup (optional - add later if needed)
+  payment: [{
+    provider: 'dodo',
+    productId: 'pdt_xxx', // Get from Dodo Payments dashboard
+    mode: 'test' // 'test' or 'live'
+  }],
 
-```javascript
-import { MoneyBar } from '@moneybar.online/moneybar';
+  // Feedback form (optional)
+  feedback: {
+    form: {
+      title: 'Quick Feedback',
+      description: 'What stopped you from upgrading?',
+      option1: 'Too expensive',
+      option2: 'Not enough features',
+      option3: 'Need more time to evaluate'
+    },
+    email: [{
+      provider: 'resend',
+      apiKey: 'your-resend-api-key',
+      fromEmail: 'feedback@yourapp.com'
+    }]
+  },
 
-const moneyBar = new MoneyBar({
-  actionFunction: 'generatePDF',
-  appId: 'my-pdf-app',
-  freeAttemptLimit: 3,
-  supabase: {
-    url: 'your-supabase-url',
-    anonKey: 'your-anon-key'
+  // UI Theme (optional)
+  theme: {
+    name: 'emerald', // DaisyUI theme name
+    primaryColor: '#059669'
   },
-  payment: [{
-    provider: 'dodo',
-    productId: 'your-product-id',
-    mode: 'test'
-  }]
-});
 
-moneyBar.attachToButton('#action-btn', generatePDF);
+  // Title bar (optional)
+  titleBar: {
+    title: '🚀 My App',
+    links: [
+      { text: 'Features', url: '#features', target: '_self' },
+      { text: 'Pricing', url: '#pricing', target: '_self' }
+    ]
+  },
 
-function generatePDF(userContext) {
-  if (userContext.isPremium) {
-    alert('Premium PDF generated with all features!');
-  } else {
-    alert(`Basic PDF generated! ${userContext.remaining} downloads remaining`);
+  // ⚠️ DO NOT MODIFY - Required for MoneyBar to work
+  supabase: {
+    url: 'https://qhlzdkwcrrjjcqvupyaa.supabase.co',
+    anonKey: 'eyJ...'
   }
-}
+};
 ```
 
-### Option 2: CDN (Recommended for HTML projects)
+---
+
+### Step 2: Add to HTML & Attach to Buttons
+
+Add these scripts to your HTML:
 
-**index.html** (Business logic only):
 ```html
 <!DOCTYPE html>
 <html>
+<head>
+  <title>My App</title>
+</head>
 <body>
-  <button id="action-btn">Try Action</button>
+  <!-- Your app content -->
+  <button id="my-custom-btn">Generate PDF</button>
 
-  <!-- Include MoneyBar configuration -->
-  <script type="module" src="moneybar-config.js"></script>
+  <!-- Step 2a: Load MoneyBar config -->
+  <script type="module" src="moneybar-config-template.js"></script>
 
-  <!-- Your business logic only -->
-  <script>
-    function myAction(userContext) {
+  <!-- Step 2b: Attach to your buttons -->
+  <script type="module">
+    // Access the MoneyBar instance
+    window.moneyBar.attachToButton('#my-custom-btn', (userContext) => {
+
+      // Check if user is premium
       if (userContext.isPremium) {
-        alert('Premium features unlocked!');
+        // ✅ Premium user - no limits!
+        generatePDF(); // Your custom function
+
       } else {
-        alert(`Free trial: ${userContext.remaining} uses left`);
+        // Free user - show remaining attempts
+        alert(`Free user. ${userContext.remaining} attempts remaining`);
+
+        if (userContext.remaining > 0) {
+          generatePDF(); // Your custom function
+        }
       }
+    });
+
+    // Your custom function
+    function generatePDF() {
+      console.log('Generating PDF...');
+      // Your PDF generation logic here
     }
   </script>
 </body>
 </html>
 ```
 
-**moneybar-config.js** (MoneyBar configuration):
-```javascript
-import { MoneyBar } from 'https://cdn.jsdelivr.net/npm/@moneybar.online/moneybar@latest/dist/index.bundle.js';
-
-const moneyBar = new MoneyBar({
-  actionFunction: 'myAction',
-  appId: 'my-app',
-  freeAttemptLimit: 3,
-  supabase: {
-    url: 'your-supabase-url',
-    anonKey: 'your-anon-key'
-  },
-  payment: [{
-    provider: 'dodo',
-    productId: 'your-product-id',
-    mode: 'test'
-  }]
-});
-
-moneyBar.attachToButton('#action-btn', myAction);
-```
+---
 
-### Quick Start Template
-Copy `moneybar-config-template.js` and `example-template.html` from this package for a ready-to-use template.
+## Understanding UserContext
 
-## 🚀 Quick Start (2 minutes)
+When you attach to a button, you get a `userContext` object with all user info:
 
-### Files You Need:
-1. **`example-template.html`** - Working demo with all 3 use cases
-2. **`moneybar-config-template.js`** - Comprehensive configuration with 3 problem-focused examples
+```javascript
+window.moneyBar.attachToButton('#my-btn', (userContext) => {
 
-### Try It Now:
-```bash
-# After npm install
-open example-template.html
-```
+  // Premium status
+  userContext.isPremium          // true/false - Does user have premium access?
+  userContext.isAuthenticated    // true/false - Is user signed in?
 
-Then edit line 157 in `moneybar-config-template.js` to switch between use cases!
+  // Usage limits
+  userContext.currentCount       // Number - How many times user has used the feature
+  userContext.remaining          // Number - Remaining free attempts
+  userContext.limit              // Number - Total free attempt limit
 
----
+  // User info
+  userContext.email              // String - User's email (if signed in)
+  userContext.name               // String - User's name (if available)
 
-## 📱 The 3 Money-Blocking Problems MoneyBar Solves
-
-### Problem #1: "Forced Sign-In Before Value"
-**Revenue Impact: 40-60% boost**
-- ❌ **What Kills Revenue:** Users bounce before seeing your product works
-- ✅ **MoneyBar Solution:** Value-first trials with 3 free attempts
-- 🎯 **Perfect for:** PDF generators, image tools, converters
-- 🎨 **Theme:** Emerald (trustworthy, fresh)
-- **Config:** `VALUE_FIRST_CONFIG` in template
-
-### Problem #2: "Silent Drop-Off"
-**Revenue Impact: 20-30% boost**
-- ❌ **What Kills Revenue:** Users try but don't buy - you don't know why
-- ✅ **MoneyBar Solution:** Exit feedback capture at cancel moment
-- 🎯 **Perfect for:** SaaS trials, B2B tools, complex products
-- 🎨 **Theme:** Corporate (professional B2B)
-- **Config:** `FEEDBACK_INTELLIGENCE_CONFIG` in template
-
-### Problem #3: "Broken Money Flow"
-**Revenue Impact: 25-40% boost**
-- ❌ **What Kills Revenue:** Complex payments and broken sessions
-- ✅ **MoneyBar Solution:** Seamless Google Auth + instant payments
-- 🎯 **Perfect for:** Templates, premium features, instant upgrades
-- 🎨 **Theme:** Dark (modern, premium)
-- **Config:** `INSTANT_PAYMENT_CONFIG` in template
-
-## 🔧 How to Use
-
-### Step 1: Choose Your Use Case
-Edit line 157 in `moneybar-config-template.js`:
+  // Subscription details (for premium users)
+  userContext.subscriptionType          // 'one-time', 'monthly', 'quarterly', 'yearly'
+  userContext.subscriptionExpiresAt     // ISO date string
+  userContext.subscriptionDaysRemaining // Number - Days until subscription expires
+  userContext.isSubscriptionActive      // true/false - Is subscription active?
+  userContext.customerId                // String - Customer ID for portal access
 
-```javascript
-// Pick one:
-window.APP_CONFIG = VALUE_FIRST_CONFIG;           // PDF/Image/Converter tools
-window.APP_CONFIG = FEEDBACK_INTELLIGENCE_CONFIG; // SaaS/B2B products
-window.APP_CONFIG = INSTANT_PAYMENT_CONFIG;       // Templates/Premium features
-```
-
-### Step 2: Update Credentials (REQUIRED!)
-⚠️ **Before testing, you MUST replace these placeholder values or you'll get errors:**
-
-```javascript
-supabase: {
-  url: 'https://your-project.supabase.co',     // ✅ Replace with your Supabase project URL
-  anonKey: 'your-anon-key'                     // ✅ Replace with your Supabase anon key
-},
-payment: [{
-  provider: 'dodo',                            // ✅ Payment provider
-  productId: 'your-product-id',                // ✅ Replace with your DodoPayments product ID
-  mode: 'test'                                 // ✅ Set to 'test' or 'live'
-}]
+});
 ```
 
-**🚨 Common Error:** If you get "Cannot read properties of null (reading 'AuthClient')" error:
-- ❌ You haven't updated the Supabase credentials above
-- ✅ Replace ALL placeholder values with your actual credentials
-
-### Step 3: Test the Demo
-Open `example-template.html` in your browser and try the button!
-
 ---
 
-## 🎯 Advanced Features
+## Common Patterns
 
-### User Context for Personalization
-Access complete user information in your functions:
+### Pattern 1: Premium vs Free
 
 ```javascript
-function myAction(userContext) {
-  console.log({
-    isPremium: userContext.isPremium,      // Boolean
-    email: userContext.email,              // String
-    name: userContext.name,                // String
-    currentCount: userContext.currentCount, // Number
-    remaining: userContext.remaining,       // Number
-    isAuthenticated: userContext.isAuthenticated
-  });
-
-  // Dynamic features based on user status
+window.moneyBar.attachToButton('#export-btn', (userContext) => {
   if (userContext.isPremium) {
-    removeWatermark();
+    // Full access
+    exportHighQuality();
   } else {
-    addWatermark();
+    // Limited access
+    exportLowQuality();
   }
-}
+});
 ```
 
+### Pattern 2: Check Remaining Attempts
 
-### Feedback Collection Configuration
 ```javascript
-const moneyBar = new MoneyBar({
-  // ... other config
-  feedback: {
-    form: {
-      title: 'Quick Feedback',
-      description: 'What stopped you from upgrading?',
-      option1: 'Too expensive',
-      option2: 'Need more features',
-      option3: 'Just testing'
-    },
-    email: [
-      {
-        provider: 'resend',
-        apiKey: 'your-resend-api-key',
-        fromEmail: 'feedback@yourapp.com'
-      }
-      // Future providers can be added here:
-      // {
-      //   provider: 'sendgrid',
-      //   apiKey: 'your-sendgrid-api-key',
-      //   fromEmail: 'feedback@yourapp.com'
-      // }
-    ]
+window.moneyBar.attachToButton('#convert-btn', (userContext) => {
+  if (userContext.isPremium) {
+    convert();
+  } else if (userContext.remaining > 0) {
+    convert();
+    console.log(`${userContext.remaining} attempts left`);
+  } else {
+    console.log('No attempts remaining - upgrade required');
   }
 });
 ```
 
----
-
-## 🎨 UI Themes & Customization
-
-MoneyBar includes 29 beautiful DaisyUI themes:
+### Pattern 3: Multiple Buttons
 
 ```javascript
-const moneyBar = new MoneyBar({
-  // ... other config
-  theme: {
-    name: 'dark', // or 'cupcake', 'emerald', 'corporate', etc.
-    primaryColor: '#059669'
-  },
-  titleBar: {
-    title: 'My App',
-    links: [
-      { text: 'Home', url: '/', target: '_self' },
-      { text: 'About', url: '/about', target: '_self' }
-    ]
+// Attach to multiple buttons with the same logic
+window.moneyBar.attachToButton('#btn1', handleAction);
+window.moneyBar.attachToButton('#btn2', handleAction);
+window.moneyBar.attachToButton('#btn3', handleAction);
+
+function handleAction(userContext) {
+  if (userContext.isPremium) {
+    performAction();
   }
-});
+}
 ```
 
----
-
-## 📊 Complete Configuration Reference
+### Pattern 4: Different Actions per Button
 
-### Core Configuration (Required)
 ```javascript
-const moneyBar = new MoneyBar({
-  // Core required config
-  appId: 'my-app',                    // Unique identifier for your app
-  freeAttemptLimit: 3,               // Free attempts before paywall
-
-  // Supabase configuration (required)
-  supabase: {
-    url: 'https://xyz.supabase.co',   // Your Supabase project URL
-    anonKey: 'your-anon-key'          // Public anon key from Supabase
-  },
-
-  // Payment configuration (required)
-  payment: [{
-    provider: 'dodo',                 // Payment provider
-    productId: 'prod_xyz',            // DodoPayments product ID
-    mode: 'test'                      // 'test' or 'live'
-  }]
+// Button 1: Export
+window.moneyBar.attachToButton('#export-btn', (ctx) => {
+  if (ctx.isPremium) exportPDF();
 });
-```
-
-### 🎨 Available Themes (29 Options)
-
-**Light Themes:**
-- `light` - Clean white theme
-- `cupcake` - Soft pink theme
-- `bumblebee` - Warm yellow theme
-- `emerald` - Fresh green theme
-- `corporate` - Professional blue
-- `garden` - Nature green
-- `lofi` - Minimalist gray
-- `pastel` - Soft purple theme
-- `fantasy` - Magical pink theme
-- `wireframe` - Minimal outline style
-- `cmyk` - Print-inspired colors
-- `autumn` - Warm orange theme
-- `business` - Clean corporate
-- `acid` - Bright lime theme
-- `lemonade` - Citrus yellow
-- `winter` - Cool blue theme
-
-**Dark Themes:**
-- `dark` - Classic dark mode
-- `synthwave` - Retro 80s neon
-- `retro` - Vintage brown theme
-- `cyberpunk` - Futuristic neon
-- `valentine` - Deep pink theme
-- `halloween` - Orange & purple
-- `forest` - Deep forest green
-- `aqua` - Ocean blue theme
-- `luxury` - Gold & purple
-- `dracula` - Purple vampire theme
-- `night` - Deep blue dark
-- `coffee` - Rich brown theme
-- `black` - Pure dark theme
-
-### 👤 User Context Properties
-
-All user information available in your functions:
 
-```javascript
-function myAction(userContext) {
-  // Available properties:
-  userContext.isPremium        // Boolean: Premium vs Free user
-  userContext.isAuthenticated  // Boolean: Signed in status
-  userContext.email           // String: User's email (if signed in)
-  userContext.name            // String: User's display name (if available)
-  userContext.currentCount    // Number: Actions taken so far
-  userContext.remaining       // Number: Free actions remaining
-  userContext.limit           // Number: Maximum free actions allowed
-  userContext.user            // Object: Full Supabase user object
-}
+// Button 2: Convert
+window.moneyBar.attachToButton('#convert-btn', (ctx) => {
+  if (ctx.isPremium) convertImage();
+});
 ```
 
 ---
 
-## 🔧 Backend Setup
+## What MoneyBar Handles Automatically
 
-### Supabase Setup
-1. Create a Supabase project
-2. Enable Google OAuth
-3. Set up edge functions for payment verification
-
-### Payment Integration
-MoneyBar supports DodoPayments for seamless checkout:
-
-```javascript
-payment: [{
-  provider: 'dodo',
-  productId: 'your-dodo-product-id',
-  mode: 'test' // or 'live'
-}]
-```
+✅ **Authentication** - Google sign-in (more providers coming)
+✅ **Usage Tracking** - Counts attempts per user per app
+✅ **Payment Flow** - Checkout, webhooks, confirmation
+✅ **Subscription Management** - Auto-renewal, expiry, cancellation
+✅ **Customer Portal** - Self-service subscription management
+✅ **Caching** - 24h cache for premium status, 60s for usage counts
+✅ **Multi-app Support** - Same user, different apps, separate limits
 
 ---
 
-## 🚀 Why MoneyBar?
-
-**For Indie Hackers:**
-- ✅ Turn trial users into paying customers
-- ✅ Understand why users don't convert
-- ✅ Remove friction from payment flow
-- ✅ Focus on product, not payment infrastructure
+## Configuration Reference
 
-**Technical Benefits:**
-- ✅ Zero-config auto-initialization
-- ✅ TypeScript support with full type safety
-- ✅ User context for personalized experiences
-- ✅ Built-in UI themes and components
-- ✅ Server-side tracking (incognito-proof)
-
-**Revenue Benefits:**
-- ✅ 40-60% more trial conversions (value-first)
-- ✅ 20-30% better conversion through feedback insights
-- ✅ 25-40% higher payment completion rates
+| Setting | Required | Purpose | Example |
+|---------|----------|---------|---------|
+| `security_key` | ✅ Yes | App identifier + auth | `'sk_...'` |
+| `actionLabel` | ✅ Yes | What users are doing | `'PDF Generations'` |
+| `freeAttemptLimit` | ✅ Yes | Free attempts before paywall | `3` |
+| `payment` | ⬜ Optional | Payment provider config | Dodo Payments |
+| `feedback` | ⬜ Optional | Collect user feedback | Email to you |
+| `theme` | ⬜ Optional | Customize colors | DaisyUI themes |
+| `titleBar` | ⬜ Optional | Navbar title & links | Your branding |
+| `supabase` | ✅ Yes | Backend (DO NOT CHANGE) | Pre-configured |
 
 ---
 
-## 📞 Support & Community
-
-- **GitHub:** [ravi-cloudworks/moneybar](https://github.com/ravi-cloudworks/moneybar)
-- **Website:** [moneybar.online](https://moneybar.online)
-- **Issues:** [GitHub Issues](https://github.com/ravi-cloudworks/moneybar/issues)
+## Getting Your Security Key
 
----
+Run this SQL in Supabase SQL Editor:
 
-## 🎯 Next Steps
+```sql
+SELECT generate_security_key(
+  'my-app-name',           -- Your app identifier
+  'yourdomain.com',        -- Your domain
+  'your@email.com',        -- Your email
+  3                        -- Free attempt limit
+);
+```
 
-1. **Try the examples:** Start with [`value-first-demo.html`](examples/value-first-demo.html)
-2. **Copy the config:** Use [`minimum-config.js`](examples/minimum-config.js) as template
-3. **Add your business logic:** Replace the demo function with your code
-4. **Configure feedback:** Set up exit feedback to understand user behavior
-5. **Launch and iterate:** Use feedback data to improve conversion
+Copy the returned `sk_...` key into your config.
 
-**MoneyBar: Because every product needs a navbar for navigation and a moneybar for monetization.** 💰
+---
 
-## 📄 License
+## Support
 
-MIT - Use in any project, commercial or personal.
+- **Issues**: [GitHub Issues](https://github.com/ravi-cloudworks/moneybar/issues)
+- **Docs**: [moneybar.online](https://moneybar.online)
 
 ---
 
-**⭐ Star on GitHub if this helped you build better freemium apps!**
+## License
+
+MIT