@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/integrations/SOCKET_IO_BROADCAST_ALL_VS_ROOM.md

@@ -0,0 +1,141 @@
+---
+name: socket-io-broadcast-all-vs-room
+category: integrations
+version: 1.0.0
+contributed: 2026-02-21
+contributor: my-other-project
+last_updated: 2026-02-21
+tags: [socket.io, websocket, real-time, broadcast, emit, rooms]
+difficulty: easy
+usage_count: 1
+success_rate: 100
+---
+
+# Socket.IO: Broadcast to All Users vs. Room/Namespace
+
+## Problem
+
+In Socket.IO, there are several different `emit()` patterns that look similar but have very different scopes. Choosing the wrong one results in messages going to only admins, only one user, only users in a specific room, or being silently dropped.
+
+Common confusion: a codebase already has `io.to('admins').emit()` and you need to send to **all** connected users.
+
+## Solution Pattern
+
+Use `io.emit()` (global emit on the io instance) to broadcast to every connected socket. This is different from `socket.emit()` (one socket) or `io.to('room').emit()` (room members only).
+
+## Code Example
+
+```js
+// ❌ Wrong: emits to only one specific client
+socket.emit('broadcast_announcement', data);
+
+// ❌ Wrong: emits only to users in the 'admins' room
+this.io.to('admins').emit('broadcast_announcement', data);
+
+// ❌ Wrong: emits to everyone EXCEPT the sender socket
+socket.broadcast.emit('broadcast_announcement', data);
+
+// ✅ Correct: emits to ALL connected sockets (true broadcast)
+this.io.emit('broadcast_announcement', data);
+```
+
+### Extending a SocketService class:
+
+```js
+class SocketService {
+  // Existing method — only reaches admin room
+  broadcastToAdmins(event, data) {
+    if (!this.io) return;
+    this.io.to('admins').emit(event, data);
+  }
+
+  // New method — reaches ALL connected users
+  broadcastAnnouncement(announcement) {
+    if (!this.io) return;
+    this.io.emit('broadcast_announcement', {
+      id: announcement.id,
+      title: announcement.title,
+      message: announcement.message,
+      image_url: announcement.image_url,
+      cta_label: announcement.cta_label,
+      cta_url: announcement.cta_url,
+      created_at: announcement.created_at
+    });
+  }
+}
+```
+
+### Client listener (React):
+
+```js
+// In a top-level layout component that stays mounted when user is logged in
+useEffect(() => {
+  if (!socket) return;
+
+  const handleAnnouncement = (announcement) => {
+    toast.custom((t) => (
+      <div
+        className={`${t.visible ? 'opacity-100' : 'opacity-0'} bg-white shadow-lg rounded-lg p-4 border-l-4 border-blue-500 cursor-pointer`}
+        onClick={() => {
+          toast.dismiss(t.id);
+          if (announcement.cta_url) window.open(announcement.cta_url, '_blank');
+          else window.location.href = '/dashboard/announcements';
+        }}
+      >
+        <p className="font-semibold text-sm">📢 {announcement.title}</p>
+        <p className="text-xs text-gray-500 line-clamp-2">{announcement.message}</p>
+      </div>
+    ), { duration: 8000 });
+  };
+
+  socket.on('broadcast_announcement', handleAnnouncement);
+  return () => socket.off('broadcast_announcement', handleAnnouncement);
+}, [socket]);
+```
+
+## Socket.IO Emit Reference
+
+| Pattern | Reaches |
+|---------|---------|
+| `socket.emit(event, data)` | Only the one connected socket |
+| `socket.broadcast.emit(event, data)` | All sockets EXCEPT the sender |
+| `io.emit(event, data)` | ALL connected sockets (true broadcast) |
+| `io.to('room').emit(event, data)` | All sockets in a specific room |
+| `io.to('room1').to('room2').emit()` | All sockets in either room |
+| `io.except('room').emit()` | All sockets NOT in the room |
+
+## Implementation Steps
+
+1. Add the broadcast method to your SocketService class using `this.io.emit()` (not `this.io.to('room').emit()`)
+2. Guard against `!this.io` (io may not be initialized when called at startup)
+3. Only emit safe/public fields — don't emit internal DB fields like `created_by` or `updated_at`
+4. On the client, listen for the event in the highest always-mounted component (e.g., App.jsx or a layout wrapper) so it fires regardless of which page the user is on
+5. Always clean up with `socket.off()` in the useEffect cleanup to prevent listener accumulation
+
+## When to Use
+
+- Admin-to-all-users announcement/notification systems
+- Platform-wide alerts (maintenance windows, new feature announcements)
+- Live events (countdown endings, contest results)
+- Any case where ALL currently-online users should receive a message simultaneously
+
+## When NOT to Use
+
+- User-to-user direct messages (use rooms/namespaces)
+- Notifications for specific users only (use `io.to(userSocketId).emit()` or a user-specific room)
+- Admin-only updates (use `io.to('admins').emit()`)
+
+## Common Mistakes
+
+- **Using `socket.emit()` from the server** — this only goes to the socket that sent the triggering request, not all users
+- **Listening in a component that unmounts** — if the listener is in a page component, navigating away stops receiving toasts. Always put broadcast listeners in the top-level layout.
+- **Accumulating listeners** — always return a cleanup function: `return () => socket.off('event', handler)`
+
+## Related Skills
+
+- [BROADCAST_SCHEDULER_SHARED_EXECUTE_FUNCTION.md](../api-patterns/BROADCAST_SCHEDULER_SHARED_EXECUTE_FUNCTION.md)
+
+## References
+
+- Socket.IO docs: https://socket.io/docs/v4/broadcasting-events/
+- Contributed from: my-other-project, Phase 15 Broadcast Announcements (2026-02-21)

package/skills-library/integrations/VIRTUAL_MEETINGS_IMPLEMENTATION.md

@@ -0,0 +1,374 @@
+# Virtual Meeting Integration Implementation
+
+**Date:** October 27, 2025
+**Status:** ✅ Complete and Ready for Testing
+
+---
+
+## Overview
+
+Implemented comprehensive virtual meeting integration for online events and sales. Admins and shop managers can now:
+
+1. **Create Virtual Products** with Zoom, Google Meet, Microsoft Teams, or other platform links
+2. **Manage Meeting URLs** directly in the product creation form
+3. **Display Meeting Links** on product detail pages with "Join Meeting" button
+4. **Support Multiple Platforms** (Zoom, Google Meet, Microsoft Teams, Other)
+
+---
+
+## Features Implemented
+
+### 1. **Admin Product Form Enhancement**
+
+**Location:** `client/src/pages/admin/Products.jsx`
+
+Added conditional fields for virtual meeting products:
+
+```javascript
+// Form state updated to include:
+{
+  meeting_url: '',           // URL for the meeting link
+  meeting_platform: 'zoom'   // Platform type (zoom, google_meet, microsoft_teams, other)
+}
+```
+
+**Features:**
+- ✅ Meeting URL field (required for virtual_meeting products)
+- ✅ Platform selector dropdown
+- ✅ Only displays when `product_type === 'virtual_meeting'`
+- ✅ URL validation (requires valid URL format)
+- ✅ Helper text explaining accepted platforms
+- ✅ Persists data when editing existing products
+
+**UI:** Styled section with border separator, appears only for virtual meeting products
+
+---
+
+### 2. **Database Schema Update**
+
+**Migration File:** `server/migrations/038_add_virtual_meeting_fields.sql`
+
+Added columns to the `products` table:
+
+```sql
+-- Meeting URL column
+ALTER TABLE products ADD COLUMN IF NOT EXISTS meeting_url VARCHAR(500);
+
+-- Meeting platform enum type
+CREATE TYPE meeting_platform_enum AS ENUM (
+  'zoom',
+  'google_meet',
+  'microsoft_teams',
+  'other'
+);
+
+ALTER TABLE products ADD COLUMN IF NOT EXISTS meeting_platform meeting_platform_enum DEFAULT 'zoom';
+```
+
+**Indexes Added:**
+- `idx_products_meeting_url` - Find virtual meeting products with URLs
+- `idx_products_meeting_platform` - Query by platform type
+
+**Database Structure:**
+```sql
+products table:
+├── meeting_url VARCHAR(500) - NULL if no URL provided
+└── meeting_platform meeting_platform_enum - Defaults to 'zoom'
+```
+
+---
+
+### 3. **Backend API Updates**
+
+#### A. **Create Product Controller**
+**File:** `server/controllers/productsController.js` (lines 199-268)
+
+**Changes:**
+- ✅ Added `meeting_url` and `meeting_platform` to request destructuring
+- ✅ Included both fields in INSERT statement
+- ✅ Validated meeting_url is provided for virtual products (if needed)
+- ✅ Returns complete product data including meeting details
+
+**Example Request:**
+```json
+{
+  "name": "Daily Prayer Session",
+  "description": "Join us for a live prayer meeting",
+  "product_type": "virtual_meeting",
+  "price": 0,
+  "meeting_url": "https://zoom.us/j/123456789",
+  "meeting_platform": "zoom"
+}
+```
+
+#### B. **Update Product Controller**
+**File:** `server/controllers/productsController.js` (lines 310-396)
+
+**Changes:**
+- ✅ Added `meeting_url` and `meeting_platform` to request destructuring
+- ✅ Added update conditions for both fields
+- ✅ Allows partial updates (only update meeting fields if provided)
+- ✅ Handles null values (clearing meeting URL)
+
+**Example Request:**
+```json
+{
+  "meeting_url": "https://meet.google.com/abc-defg-hij",
+  "meeting_platform": "google_meet"
+}
+```
+
+**API Endpoints:**
+- `POST /api/products` - Create virtual product with meeting URL
+- `PUT /api/products/:id` - Update product's meeting details
+
+---
+
+### 4. **Frontend Product Detail Display**
+
+**File:** `client/src/pages/ProductDetail.jsx` (lines 255-301)
+
+**Features:**
+- ✅ Conditional rendering for virtual_meeting products
+- ✅ Displays meeting platform (formatted from database enum)
+- ✅ Shows "Join Meeting" button linking to the URL
+- ✅ Opens meeting link in new tab/window
+- ✅ Integrated with existing meeting details (date, duration, participants)
+- ✅ Styled with blue theme matching product detail page
+
+**Display Structure:**
+```
+Meeting/Event Details Box (blue background)
+├── Calendar: [Meeting Date]
+├── Duration: [Minutes]
+├── Max Participants: [Number]
+└── Platform & Join Button:
+    └── Platform: [ZOOM / GOOGLE MEET / MICROSOFT TEAMS / OTHER]
+    └── [Join Meeting Button]
+```
+
+**Example UI:**
+```
+┌─────────────────────────────────────┐
+│ Meeting/Event Details              │
+│                                     │
+│ 📅 10/27/2025                      │
+│ 🕐 60 minutes                      │
+│ 👥 Max 100 participants            │
+│                                     │
+│ Platform: ZOOM                     │
+│ [Join Meeting Button] →            │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Form Fields Reference
+
+### Products Admin Form - Virtual Meeting Section
+
+When `product_type === "virtual_meeting"`:
+
+| Field | Type | Required | Placeholder | Validation |
+|-------|------|----------|-------------|-----------|
+| Meeting Platform | Select Dropdown | No | - | zoom, google_meet, microsoft_teams, other |
+| Meeting Link/URL | Text (URL) | **Yes** | https://zoom.us/j/... | Valid URL format |
+
+---
+
+## API Response Examples
+
+### Create Virtual Product Response
+
+```json
+{
+  "success": true,
+  "message": "Product created successfully",
+  "data": {
+    "id": "uuid-1234",
+    "name": "Daily Prayer Session",
+    "product_type": "virtual_meeting",
+    "price": 0,
+    "meeting_url": "https://zoom.us/j/123456789",
+    "meeting_platform": "zoom",
+    "status": "active",
+    "created_at": "2025-10-27T19:30:00Z"
+  }
+}
+```
+
+### Get Product Details Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "uuid-1234",
+    "name": "Daily Prayer Session",
+    "product_type": "virtual_meeting",
+    "meeting_url": "https://zoom.us/j/123456789",
+    "meeting_platform": "zoom",
+    "meeting_datetime": "2025-10-28T10:00:00Z",
+    "details": {
+      "duration": 60,
+      "max_participants": 100
+    }
+  }
+}
+```
+
+---
+
+## Admin Workflow
+
+### Step 1: Create Virtual Product
+1. Go to Admin → Products
+2. Click "Add Product"
+3. Fill in basic details (name, description, price)
+4. Select "Virtual Meeting" from Product Type dropdown
+5. **New:** Meeting Settings section appears
+6. Select Platform (Zoom, Google Meet, etc.)
+7. Paste meeting URL
+8. Click "Create Product"
+
+### Step 2: Edit Meeting Link
+1. Go to Admin → Products
+2. Click "Edit" on virtual meeting product
+3. Modify meeting URL or platform
+4. Click "Update Product"
+
+### Step 3: Customer Sees Meeting Link
+1. Customer browses to product detail page
+2. For virtual_meeting products, they see the "Join Meeting" button
+3. Click button to open meeting in new window
+
+---
+
+## Supported Platforms
+
+```
+Platform           Format Example                              Enum Value
+────────────────────────────────────────────────────────────────────
+Zoom               https://zoom.us/j/123456789                zoom
+Google Meet        https://meet.google.com/abc-defg-hij        google_meet
+Microsoft Teams    https://teams.microsoft.com/l/meetup-join/... microsoft_teams
+Other              Any custom URL                             other
+```
+
+---
+
+## Database Migration Steps
+
+**To apply the migration:**
+
+```bash
+# If using runMigration.js:
+node runMigration.js 038_add_virtual_meeting_fields
+
+# Or manually in Supabase:
+# 1. Go to Supabase Dashboard
+# 2. SQL Editor
+# 3. Copy contents of 038_add_virtual_meeting_fields.sql
+# 4. Execute query
+```
+
+**Verify migration:**
+```sql
+-- Check columns added:
+SELECT column_name, data_type
+FROM information_schema.columns
+WHERE table_name = 'products'
+AND column_name IN ('meeting_url', 'meeting_platform');
+```
+
+---
+
+## Testing Checklist
+
+### Backend Tests
+- [ ] Create virtual_meeting product with meeting_url
+- [ ] Update product to change meeting_url
+- [ ] Update product to change meeting_platform
+- [ ] Get product details includes meeting fields
+- [ ] Non-virtual products don't show meeting fields
+- [ ] Meeting URL can be NULL/empty
+
+### Frontend Tests
+- [ ] Admin form shows meeting fields for virtual_meeting type only
+- [ ] Admin form hides meeting fields for other product types
+- [ ] Can save virtual product with meeting URL
+- [ ] Can edit meeting URL on existing product
+- [ ] Product detail page shows "Join Meeting" button for virtual products
+- [ ] Join button links to correct URL
+- [ ] Join button opens in new tab
+
+### Integration Tests
+- [ ] Create product → See meeting link on detail page
+- [ ] Edit product meeting URL → Detail page updates
+- [ ] Delete product → Meeting reference removed
+
+---
+
+## Future Enhancements
+
+### Phase 2: Zoom API Integration
+- [ ] Auto-create Zoom meetings when product created
+- [ ] Auto-update meeting links if duration changes
+- [ ] Fetch real Zoom meeting details for display
+- [ ] Attendance tracking integration
+
+### Phase 3: Advanced Features
+- [ ] Google Calendar integration for meeting dates
+- [ ] Automatic email reminders before meetings
+- [ ] Meeting recording storage and access
+- [ ] Attendee list management
+- [ ] Q&A and chat feature integration
+
+### Phase 4: Performance
+- [ ] Cache meeting URLs in Redis
+- [ ] Queue async Zoom API calls
+- [ ] Add pagination for large meeting lists
+
+---
+
+## File Changes Summary
+
+### Modified Files
+1. **`client/src/pages/admin/Products.jsx`** - Added meeting URL form fields
+2. **`client/src/pages/ProductDetail.jsx`** - Added meeting link display
+3. **`server/controllers/productsController.js`** - Added meeting field handling
+
+### New Files
+1. **`server/migrations/038_add_virtual_meeting_fields.sql`** - Database schema update
+
+---
+
+## Related Documentation
+
+- **Image Upload Features:** See [IMAGE_UPLOAD_FIX.md](./IMAGE_UPLOAD_FIX.md)
+- **E-Commerce Complete:** See [ECOMMERCE_COMPLETE_HANDOFF.md](./ECOMMERCE_COMPLETE_HANDOFF.md)
+- **Product Analytics:** See [Product Analytics in productsController.js](./server/controllers/productsController.js)
+
+---
+
+## Support & Questions
+
+For issues or questions:
+1. Check the test checklist above
+2. Verify database migration was applied
+3. Check browser console for form validation errors
+4. Verify API responses in Network tab
+
+---
+
+## Deployment Notes
+
+1. **Apply migration before deploying backend changes**
+2. Frontend changes are backward compatible
+3. Existing products without meeting_url will work fine
+4. No data migration needed (new columns default to NULL)
+5. No breaking API changes - all additions are optional
+
+---
+
+**Status:** Ready for production deployment ✅

package/skills-library/integrations/WORDPRESS_LEARNDASH_DATA_RECOVERY.md

@@ -0,0 +1,53 @@
+# WordPress LMS Course Data Recovery - Extraction & Migration
+
+## The Problem
+
+You have WordPress LMS course data exported as JSON files, and need to extract course structure, find embedded media URLs, and recreate the course in a new LMS system.
+
+### Why It Was Hard
+
+- LMS exports are spread across multiple JSON files (courses, lessons, topics)
+- Media URLs are embedded in HTML content fields
+- Course iterations create duplicate entries with slug suffixes like `-2-2-2-3`
+
+---
+
+## The Solution
+
+### LMS Export Structure
+
+| File | Post Type | Contains |
+|------|-----------|----------|
+| `wordpress-courses.json` | `sfwd-courses` | Course metadata |
+| `wordpress-lessons.json` | `sfwd-lessons` | Lesson titles, ordering |
+| `wordpress-topics.json` | `sfwd-topic` | Sub-lessons with actual content/media |
+
+### Extract Media URLs
+
+```bash
+# Find all Castos audio URLs
+grep -oE "https://[^\"']*castos[^\"']*\.mp3" wordpress-topics.json | sort -u
+```
+
+### Generate Embed HTML
+
+```html
+<audio controls style="width:100%">
+  <source src="https://episodes.castos.com/.../file.mp3" type="audio/mpeg">
+</audio>
+```
+
+---
+
+## Key Insight
+
+LMS spreads content across three post types. Lessons often just have titles - the actual content with media is in **Topics**. Always search all three JSON files.
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5)
+
+---
+
+**Author Notes:**
+"Activation completed during a live session" means no audio exists - it was conducted live.

package/skills-library/integrations/YOUTUBE_API_SETUP.md

@@ -0,0 +1,141 @@
+# YouTube API Setup Guide
+
+This guide will help you set up the YouTube Data API v3 for importing YouTube playlists into your LMS.
+
+## Prerequisites
+
+- Google Account
+- Google Cloud Platform (GCP) access
+
+## Step-by-Step Setup
+
+### 1. Create a Google Cloud Project
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Click on the project dropdown at the top
+3. Click "New Project"
+4. Enter project name (e.g., "MERN-LMS")
+5. Click "Create"
+
+### 2. Enable YouTube Data API v3
+
+1. In the Google Cloud Console, make sure your project is selected
+2. Go to **APIs & Services** > **Library**
+3. Search for "YouTube Data API v3"
+4. Click on it
+5. Click **Enable**
+
+### 3. Create API Credentials
+
+1. Go to **APIs & Services** > **Credentials**
+2. Click **Create Credentials** > **API Key**
+3. Your API key will be created and displayed
+4. **Important**: Click **Restrict Key** to secure it
+
+### 4. Restrict the API Key (Recommended)
+
+#### Application Restrictions:
+- **None** (or HTTP referrers if you want to restrict to your domain)
+
+#### API Restrictions:
+- Select "Restrict key"
+- Check only "YouTube Data API v3"
+- Click "Save"
+
+### 5. Add API Key to Your Environment
+
+1. Copy the API key
+2. Open `server/.env` file
+3. Add or update the following line:
+   ```
+   YOUTUBE_API_KEY=YOUR_API_KEY_HERE
+   ```
+
+### 6. Test the API
+
+Run the test script to verify everything works:
+
+```bash
+cd server
+node test-youtube-api.js
+```
+
+You should see:
+```
+✅ All tests passed!
+```
+
+## Usage Limits
+
+### Free Tier Quota:
+- **10,000 units per day** (quota resets at midnight Pacific Time)
+
+### Cost Per Operation:
+- List playlist items: **1 unit per request** (50 videos)
+- Get playlist metadata: **1 unit per request**
+
+### Example:
+- Importing a 50-video playlist = **2 units**
+- Importing a 200-video playlist = **6 units** (4 paginated requests + 1 metadata)
+
+**You can import approximately 2,500 playlists per day within the free tier.**
+
+## Troubleshooting
+
+### Error: "API key not valid"
+**Solution:**
+1. Make sure YouTube Data API v3 is enabled
+2. Check that the API key is copied correctly
+3. Wait a few minutes after creating the key (can take time to activate)
+4. Verify API restrictions don't block your requests
+
+### Error: "The request cannot be completed because you have exceeded your quota"
+**Solution:**
+1. Wait 24 hours for quota reset
+2. Request a quota increase in Google Cloud Console:
+   - Go to **APIs & Services** > **Quotas**
+   - Find "YouTube Data API v3"
+   - Click "Edit Quotas"
+   - Submit quota increase request
+
+### Error: "Playlist not found or is private"
+**Solution:**
+- Make sure the playlist is public or unlisted
+- Private playlists cannot be imported
+
+### Error: "Access Not Configured"
+**Solution:**
+- Ensure YouTube Data API v3 is enabled in your project
+- Try disabling and re-enabling the API
+
+## Security Best Practices
+
+1. **Never commit API keys to version control**
+   - Add `.env` to `.gitignore`
+   - Use environment variables in production
+
+2. **Restrict API key usage**
+   - Set application restrictions (HTTP referrers, IP addresses)
+   - Limit to YouTube Data API v3 only
+   - Rotate keys periodically
+
+3. **Monitor usage**
+   - Check quota usage in Google Cloud Console
+   - Set up billing alerts if using paid quota
+
+## Alternative: Vimeo Showcase Import
+
+If you prefer not to use YouTube or need an alternative, the LMS also supports Vimeo showcases:
+
+1. Get a Vimeo access token from [Vimeo Developer](https://developer.vimeo.com/apps)
+2. Add to `.env`:
+   ```
+   VIMEO_ACCESS_TOKEN=YOUR_TOKEN_HERE
+   ```
+
+## Support
+
+For more help:
+- [YouTube Data API Documentation](https://developers.google.com/youtube/v3)
+- [Google Cloud Console](https://console.cloud.google.com/)
+- [API Key Best Practices](https://cloud.google.com/docs/authentication/api-keys)