@moneybar.online/moneybar 9.1.0 → 9.1.2

package/README.md

@@ -144,17 +144,49 @@ window.moneyBar.attachToButton('#my-btn', (userContext) => {
   // User info
   userContext.email              // String - User's email (if signed in)
   userContext.name               // String - User's name (if available)
-
-  // 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.user               // Object - Full Supabase user object
+
+  // Subscription details (only for subscription users)
+  userContext.subscriptionType          // 'monthly', 'quarterly', 'yearly'
+  userContext.subscriptionId            // String - Subscription ID
+  userContext.subscriptionExpiresAt     // ISO date string - When subscription expires
+  userContext.subscriptionDaysRemaining // Number - Days until expiry
+  userContext.isSubscriptionActive      // true/false - Active or cancelled
+  userContext.nextBillingDate           // ISO date string - Next billing date
+  userContext.billingFrequency          // String - 'monthly', 'quarterly', etc.
   userContext.customerId                // String - Customer ID for portal access
 
 });
 ```
 
+### UserContext for Different Payment Types
+
+**One-Time Payment:**
+```javascript
+{
+  isPremium: true,
+  subscriptionType: 'one-time',  // Indicates one-time payment
+  // No subscription fields (expiresAt, nextBillingDate, etc.)
+}
+```
+
+**Subscription Payment:**
+```javascript
+{
+  isPremium: true,
+  subscriptionType: 'monthly',            // or 'quarterly', 'yearly'
+  subscriptionId: 'sub_xxx',
+  subscriptionExpiresAt: '2026-02-06',
+  subscriptionDaysRemaining: 31,
+  isSubscriptionActive: true,             // false if cancelled
+  nextBillingDate: '2026-02-06',
+  billingFrequency: 'monthly',
+  customerId: 'cus_xxx'                   // For customer portal
+}
+```
+
+**Note:** Payment amounts, transaction IDs, and billing details are available in your Dodo Payments dashboard.
+
 ---
 
 ## Common Patterns
@@ -219,6 +251,141 @@ window.moneyBar.attachToButton('#convert-btn', (ctx) => {
 
 ---
 
+## Integrating Your Existing Functions
+
+MoneyBar works with your existing functions. Here's how to integrate them properly:
+
+### Basic Integration
+
+```javascript
+// Your existing function
+async function generatePDF(userId, template) {
+  const response = await fetch('/api/generate-pdf', {
+    method: 'POST',
+    body: JSON.stringify({ userId, template })
+  });
+
+  if (!response.ok) {
+    throw new Error('PDF generation failed');
+  }
+
+  return await response.json();
+}
+
+// Integrate with MoneyBar
+window.moneyBar.attachToButton('#generate-pdf-btn', async (userContext) => {
+
+  if (userContext.isPremium) {
+    // Premium: Unlimited access
+    try {
+      const result = await generatePDF(userContext.email, 'premium-template');
+      alert('✅ PDF generated successfully!');
+    } catch (error) {
+      alert('❌ Error: ' + error.message);
+      throw error; // Re-throw to prevent count increment
+    }
+
+  } else {
+    // Free: Limited attempts
+    try {
+      const result = await generatePDF(userContext.email, 'basic-template');
+      const remaining = userContext.remaining - 1;
+      alert(`✅ PDF generated! ${remaining} attempts remaining.`);
+    } catch (error) {
+      alert(`❌ Error: ${error.message}\n\nYou still have ${userContext.remaining} attempts.`);
+      throw error; // Re-throw to prevent count increment
+    }
+  }
+});
+```
+
+### How Success/Error Handling Works
+
+**Critical: Count increments ONLY if your function succeeds**
+
+```javascript
+window.moneyBar.attachToButton('#my-btn', async (userContext) => {
+
+  try {
+    // Your async function runs FIRST
+    await yourCustomFunction();
+
+    // ✅ SUCCESS PATH:
+    // - Function completed without error
+    // - MoneyBar increments count AFTER this
+    // - User consumed 1 attempt
+
+  } catch (error) {
+    // ❌ ERROR PATH:
+    // - Function threw an error
+    // - Re-throw the error to prevent count increment
+    // - User does NOT consume an attempt
+
+    console.error('Function failed:', error);
+    throw error; // IMPORTANT: Re-throw to prevent count increment
+  }
+});
+```
+
+### Real-World Example: API Call with Error Handling
+
+```javascript
+// Your existing API function
+async function processImage(imageUrl, format) {
+  const response = await fetch('https://api.yourapp.com/process', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ imageUrl, format })
+  });
+
+  if (!response.ok) {
+    const error = await response.json();
+    throw new Error(error.message || 'Processing failed');
+  }
+
+  return await response.json();
+}
+
+// Integrate with MoneyBar
+window.moneyBar.attachToButton('#process-image-btn', async (userContext) => {
+
+  const imageUrl = document.getElementById('image-url').value;
+  const format = userContext.isPremium ? 'high-quality' : 'standard';
+
+  try {
+    const result = await processImage(imageUrl, format);
+
+    // Success
+    if (userContext.isPremium) {
+      alert('✅ Image processed in high quality!');
+    } else {
+      const remaining = userContext.remaining - 1;
+      alert(`✅ Image processed! ${remaining} attempts remaining.`);
+    }
+
+  } catch (error) {
+    // Error - API failed, network issue, etc.
+    if (userContext.isPremium) {
+      alert('❌ Processing failed: ' + error.message);
+    } else {
+      alert(`❌ Processing failed: ${error.message}\n\nNo attempt used. You still have ${userContext.remaining} attempts.`);
+    }
+
+    throw error; // Re-throw to prevent count increment
+  }
+});
+```
+
+### Key Points
+
+1. **Async Functions**: MoneyBar automatically waits for async functions to complete
+2. **Error Handling**: If your function throws an error, count does NOT increment
+3. **Re-throw Errors**: Always `throw error;` in catch blocks to prevent count increment
+4. **Success/Error Feedback**: Show different messages based on outcome and user type
+5. **userContext.isPremium**: Use this to provide different features/quality for premium users
+
+---
+
 ## What MoneyBar Handles Automatically
 
 ✅ **Authentication** - Google sign-in (more providers coming)