@devwithbobby/loops 0.1.0

package/prds/ENV_SETUP.md

@@ -0,0 +1,222 @@
+# Environment Variable Setup
+
+The Loops component requires a Loops.so API key to be configured. **For security, the API key should ONLY be stored in Convex environment variables.**
+
+## Setting Up the API Key
+
+### 1. Get Your Loops API Key
+
+1. Log in to your [Loops.so dashboard](https://app.loops.so)
+2. Navigate to Settings → API Keys
+3. Copy your API key
+
+### 2. Set Environment Variable in Convex
+
+**Via Convex Dashboard:**
+
+1. Go to your Convex project dashboard
+2. Navigate to **Settings** → **Environment Variables**
+3. Click **Add Variable**
+4. Set:
+   - **Name:** `LOOPS_API_KEY`
+   - **Value:** Your Loops API key
+5. Click **Save**
+
+**Via Convex CLI:**
+
+```bash
+npx convex env set LOOPS_API_KEY "your-api-key-here"
+```
+
+**Important:** The API key will be automatically available as `process.env.LOOPS_API_KEY` in your Convex functions.
+
+### 3. Initialize the Component
+
+Once the environment variable is set, initialize the component in your app:
+
+```typescript
+// In your app's convex/loops.ts (or similar)
+import { Loops } from "robertalv/loops-component";
+import { components } from "./_generated/api";
+
+/**
+ * Initialize Loops client.
+ * The API key is automatically loaded from process.env.LOOPS_API_KEY
+ */
+const loops = new Loops(components.loopsComponent);
+
+export const {
+  addContact,
+  sendTransactional,
+  // ... other functions
+} = loops.api();
+```
+
+## Security Best Practices
+
+### ✅ DO:
+
+1. **Store API key in Convex environment variables only**
+   ```typescript
+   // ✅ GOOD - Uses environment variable automatically
+   const loops = new Loops(components.loopsComponent);
+   ```
+
+2. **Use different keys for different environments**
+   - Development: Set `LOOPS_API_KEY` in your dev deployment
+   - Production: Set `LOOPS_API_KEY` in your prod deployment
+   - Each deployment has its own environment variables
+
+3. **Rotate API keys regularly**
+   - Generate new keys in Loops dashboard
+   - Update environment variable
+   - Remove old keys
+
+4. **Restrict API key access**
+   - Only give access to necessary team members
+   - Use Convex's role-based access control for dashboard access
+
+### ❌ DON'T:
+
+1. **Don't hardcode API keys in code**
+   ```typescript
+   // ❌ BAD - Never do this!
+   const loops = new Loops(components.loopsComponent, {
+     apiKey: "sk-abc123..." // NEVER hardcode!
+   });
+   ```
+
+2. **Don't commit API keys to git**
+   ```typescript
+   // ❌ BAD - API key in code = exposed in git history
+   const API_KEY = "sk-abc123...";
+   ```
+
+3. **Don't pass API keys from client-side code**
+   ```typescript
+   // ❌ BAD - Never accept API keys from clients
+   export const sendEmail = action({
+     args: {
+       apiKey: v.string(), // NEVER accept API key as argument!
+       email: v.string(),
+     },
+     // ...
+   });
+   ```
+
+4. **Don't log API keys**
+   ```typescript
+   // ❌ BAD - Never log API keys
+   console.log("API Key:", process.env.LOOPS_API_KEY);
+   ```
+
+5. **Don't store in client-side code or config files**
+   - Not in `.env.local` (if exposed to client)
+   - Not in React components
+   - Not in browser storage
+
+## Environment Variable Management
+
+### Viewing Environment Variables
+
+```bash
+# List all environment variables
+npx convex env list
+
+# View a specific variable (value is masked for security)
+npx convex env get LOOPS_API_KEY
+```
+
+### Updating Environment Variables
+
+```bash
+# Update existing variable
+npx convex env set LOOPS_API_KEY "new-api-key-here"
+```
+
+### Removing Environment Variables
+
+```bash
+# Remove a variable
+npx convex env remove LOOPS_API_KEY
+```
+
+## Multiple Environments
+
+If you have multiple Convex deployments (dev, staging, prod), set the environment variable in each:
+
+```bash
+# Development deployment
+npx convex env set LOOPS_API_KEY "dev-key-here" --prod=false
+
+# Production deployment
+npx convex env set LOOPS_API_KEY "prod-key-here" --prod=true
+```
+
+## Verification
+
+To verify your API key is set correctly:
+
+```typescript
+// In a test query or action
+export const testLoopsConnection = query({
+  handler: async (ctx) => {
+    const apiKey = process.env.LOOPS_API_KEY;
+    if (!apiKey) {
+      return { error: "LOOPS_API_KEY not set in environment variables" };
+    }
+    
+    // Try a simple operation
+    const loops = new Loops(components.loopsComponent);
+    // If initialization succeeds, API key is valid
+    return { success: true, message: "Loops client initialized successfully" };
+  },
+});
+```
+
+## Troubleshooting
+
+### "Loops API key is required" Error
+
+This means `LOOPS_API_KEY` is not set in your Convex environment variables:
+
+1. Check if variable exists: `npx convex env list`
+2. Set the variable: `npx convex env set LOOPS_API_KEY "your-key"`
+3. Restart your Convex dev server if running locally
+
+### API Key Not Working
+
+1. Verify the key is correct in Loops dashboard
+2. Check if the key has expired or been rotated
+3. Ensure you're using the correct deployment's environment variables
+4. Check Convex dashboard for any environment variable errors
+
+### Testing Without Environment Variable
+
+For testing purposes only, you can pass the API key directly (but never commit this):
+
+```typescript
+// ⚠️ TESTING ONLY - Remove before production
+const loops = new Loops(components.loopsComponent, {
+  apiKey: process.env.TEST_LOOPS_API_KEY || "test-key",
+});
+```
+
+**Important:** This should only be used for local testing. In production, always use environment variables.
+
+## Security Checklist
+
+- [ ] API key stored only in Convex environment variables
+- [ ] API key NOT in source code
+- [ ] API key NOT in git repository
+- [ ] API key NOT in client-side code
+- [ ] Different keys for dev/staging/prod environments
+- [ ] API key access restricted to necessary team members
+- [ ] Regular key rotation schedule in place
+
+## Additional Resources
+
+- [Convex Environment Variables Documentation](https://docs.convex.dev/production/environment-variables)
+- [Loops.so API Documentation](https://loops.so/docs)
+- [Component Security Guide](./SECURITY.md)
+

package/prds/MONITORING.md

@@ -0,0 +1,301 @@
+# Email Monitoring & Spam Detection
+
+The Loops component includes built-in monitoring and spam detection capabilities to help you track email operations and identify unusual activity patterns.
+
+## Features
+
+1. **Automatic Operation Logging** - All email operations are automatically logged
+2. **Spam Pattern Detection** - Queries to detect suspicious sending patterns
+3. **Email Statistics** - Get comprehensive stats about email operations
+4. **Rapid-Fire Detection** - Identify burst email sending patterns
+
+## Automatic Logging
+
+All email-sending operations are automatically logged to the `emailOperations` table:
+
+- `sendTransactional` - Transactional emails
+- `sendEvent` - Event-triggered emails
+- `sendCampaign` - Campaign emails
+- `triggerLoop` - Loop-triggered emails
+
+Each operation records:
+- Operation type
+- Recipient email
+- Actor ID (optional - set by app layer)
+- Timestamp
+- Success/failure status
+- Related IDs (transactionalId, campaignId, loopId, eventName)
+- Message ID (if available)
+
+## Spam Detection Queries
+
+### 1. Detect Recipient Spam
+
+Detect emails sent to the same recipient too frequently:
+
+```typescript
+const suspicious = await ctx.runQuery(
+  components.loopsComponent.lib.detectRecipientSpam,
+  {
+    timeWindowMs: 3600000, // 1 hour (default)
+    maxEmailsPerRecipient: 10, // Default: 10 emails per hour
+  }
+);
+
+// Returns: [{ email: "user@example.com", count: 15, timeWindowMs: 3600000 }]
+```
+
+### 2. Detect Actor Spam
+
+Detect emails sent by the same actor/user too frequently:
+
+```typescript
+const suspicious = await ctx.runQuery(
+  components.loopsComponent.lib.detectActorSpam,
+  {
+    timeWindowMs: 3600000, // 1 hour (default)
+    maxEmailsPerActor: 100, // Default: 100 emails per hour
+  }
+);
+
+// Returns: [{ actorId: "user-123", count: 150, timeWindowMs: 3600000 }]
+```
+
+**Note:** Actor ID must be set when sending emails. The app layer should pass it:
+
+```typescript
+// In your app's wrapper function
+export const sendTransactional = action({
+  handler: async (ctx, args) => {
+    const identity = await ctx.auth.getUserIdentity();
+    // Pass actorId through metadata or extend the component
+    return await loops.sendTransactional(ctx, args);
+  },
+});
+```
+
+### 3. Get Email Statistics
+
+Get comprehensive statistics about email operations:
+
+```typescript
+const stats = await ctx.runQuery(
+  components.loopsComponent.lib.getEmailStats,
+  {
+    timeWindowMs: 86400000, // 24 hours (default)
+  }
+);
+
+// Returns:
+// {
+//   totalOperations: 1250,
+//   successfulOperations: 1200,
+//   failedOperations: 50,
+//   operationsByType: {
+//     transactional: 800,
+//     event: 300,
+//     campaign: 100,
+//     loop: 50,
+//   },
+//   uniqueRecipients: 450,
+//   uniqueActors: 12,
+// }
+```
+
+### 4. Detect Rapid-Fire Patterns
+
+Detect burst email sending (multiple emails sent in quick succession):
+
+```typescript
+const patterns = await ctx.runQuery(
+  components.loopsComponent.lib.detectRapidFirePatterns,
+  {
+    timeWindowMs: 60000, // 1 minute (default)
+    minEmailsInWindow: 5, // Default: 5 emails in 1 minute
+  }
+);
+
+// Returns: [
+//   {
+//     email: "user@example.com",
+//     count: 8,
+//     timeWindowMs: 60000,
+//     firstTimestamp: 1234567890,
+//     lastTimestamp: 1234567950,
+//   },
+//   ...
+// ]
+```
+
+## Usage Examples
+
+### Monitor Email Operations in Real-Time
+
+```typescript
+// In your app
+export const checkEmailHealth = query({
+  handler: async (ctx) => {
+    // Get stats for last hour
+    const stats = await ctx.runQuery(
+      components.loopsComponent.lib.getEmailStats,
+      { timeWindowMs: 3600000 }
+    );
+
+    // Check for spam patterns
+    const recipientSpam = await ctx.runQuery(
+      components.loopsComponent.lib.detectRecipientSpam,
+      { maxEmailsPerRecipient: 10 }
+    );
+
+    const actorSpam = await ctx.runQuery(
+      components.loopsComponent.lib.detectActorSpam,
+      { maxEmailsPerActor: 100 }
+    );
+
+    return {
+      stats,
+      warnings: {
+        recipientSpam: recipientSpam.length > 0,
+        actorSpam: actorSpam.length > 0,
+        failureRate: stats.failedOperations / stats.totalOperations,
+      },
+      suspiciousRecipients: recipientSpam,
+      suspiciousActors: actorSpam,
+    };
+  },
+});
+```
+
+### Automatic Rate Limiting Based on Monitoring
+
+```typescript
+export const sendTransactional = action({
+  args: { email: v.string(), transactionalId: v.string() },
+  handler: async (ctx, args) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new Error("Unauthorized");
+
+    // Check for spam patterns before sending
+    const recentRecipientEmails = await ctx.runQuery(
+      components.loopsComponent.lib.detectRecipientSpam,
+      {
+        timeWindowMs: 3600000, // 1 hour
+        maxEmailsPerRecipient: 10,
+      }
+    );
+
+    const isSuspicious = recentRecipientEmails.some(
+      (r) => r.email === args.email && r.count >= 10
+    );
+
+    if (isSuspicious) {
+      console.warn(`Suspicious activity detected for ${args.email}`);
+      // Log for review, but still allow (or block if needed)
+      // throw new Error("Rate limit exceeded");
+    }
+
+    return await loops.sendTransactional(ctx, args);
+  },
+});
+```
+
+### Scheduled Spam Monitoring
+
+Use Convex scheduled functions to periodically check for spam:
+
+```typescript
+// In your app's convex/scheduled.ts
+import { cronJobs } from "convex/server";
+import { internal } from "./_generated/api";
+
+const crons = cronJobs();
+
+// Check for spam every hour
+crons.hourly(
+  "checkSpam",
+  {
+    hourUTC: 0, // Run at start of each hour
+  },
+  internal.monitoring.checkForSpam,
+);
+
+// In convex/monitoring.ts
+export const checkForSpam = internalAction({
+  handler: async (ctx) => {
+    const recipientSpam = await ctx.runQuery(
+      components.loopsComponent.lib.detectRecipientSpam,
+      { maxEmailsPerRecipient: 10 }
+    );
+
+    const actorSpam = await ctx.runQuery(
+      components.loopsComponent.lib.detectActorSpam,
+      { maxEmailsPerActor: 100 }
+    );
+
+    if (recipientSpam.length > 0 || actorSpam.length > 0) {
+      // Send alert (email, Slack, etc.)
+      console.error("Spam patterns detected:", {
+        recipientSpam,
+        actorSpam,
+      });
+      
+      // Could send alert email via Loops itself!
+      await ctx.runAction(components.loopsComponent.lib.sendTransactional, {
+        apiKey: process.env.LOOPS_API_KEY!,
+        transactionalId: "alert-id",
+        email: "admin@example.com",
+        dataVariables: {
+          recipientSpamCount: recipientSpam.length,
+          actorSpamCount: actorSpam.length,
+        },
+      });
+    }
+  },
+});
+```
+
+## Using the Client Library
+
+If you're using the `Loops` client class:
+
+```typescript
+import { Loops } from "robertalv/loops-component";
+
+const loops = new Loops(components.loopsComponent);
+
+// In a query
+const stats = await loops.getEmailStats(ctx, { timeWindowMs: 3600000 });
+const spam = await loops.detectRecipientSpam(ctx, { maxEmailsPerRecipient: 10 });
+```
+
+Or export from `loops.api()`:
+
+```typescript
+export const {
+  detectRecipientSpam,
+  detectActorSpam,
+  getEmailStats,
+  detectRapidFirePatterns,
+} = loops.api();
+```
+
+## Best Practices
+
+1. **Set Actor IDs** - Pass actor IDs from your auth system to track who's sending emails
+2. **Regular Monitoring** - Set up scheduled checks to monitor for spam patterns
+3. **Customize Thresholds** - Adjust thresholds based on your email volume and use case
+4. **Log Actions** - When spam is detected, log it for audit purposes
+5. **Rate Limiting** - Use monitoring results to implement dynamic rate limiting
+6. **Alerting** - Set up alerts when spam patterns are detected
+
+## Configuration Recommendations
+
+Based on typical email sending patterns:
+
+- **Transactional Emails**: 10-20 per recipient per hour is reasonable
+- **Event-Triggered**: 5-10 per recipient per hour
+- **Campaigns**: Usually sent in bulk, less frequent
+- **Rapid-Fire Detection**: 5+ emails in 1 minute is suspicious
+
+Adjust these based on your specific use case and email volume.
+