@devwithbobby/loops 0.1.0 → 0.1.1

package/prds/MONITORING.md

@@ -1,301 +0,0 @@
-# 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.
-

package/prds/RATE_LIMITING.md

@@ -1,412 +0,0 @@
-# Rate Limiting for Email Sending
-
-The Loops component provides built-in rate limiting capabilities to prevent email abuse and ensure compliance with email service provider limits.
-
-## Features
-
-1. **Recipient-based Rate Limiting** - Limit emails per recipient
-2. **Actor-based Rate Limiting** - Limit emails per user/actor
-3. **Global Rate Limiting** - Limit total emails across the system
-4. **Automatic Rate Limit Checks** - Based on logged email operations
-5. **Rate Limit Status Queries** - Check rate limit status before sending
-
-## Rate Limiting Functions
-
-### 1. Check Recipient Rate Limit
-
-Check if an email can be sent to a specific recipient:
-
-```typescript
-const rateLimitCheck = await ctx.runQuery(
-  components.loopsComponent.lib.checkRecipientRateLimit,
-  {
-    email: "user@example.com",
-    timeWindowMs: 3600000, // 1 hour
-    maxEmails: 10, // Max 10 emails per hour to this recipient
-  }
-);
-
-if (!rateLimitCheck.allowed) {
-  throw new Error(
-    `Rate limit exceeded. ${rateLimitCheck.count}/${rateLimitCheck.limit} emails sent in the last hour. Retry after ${Math.ceil(rateLimitCheck.retryAfter! / 1000)} seconds.`
-  );
-}
-```
-
-**Response:**
-```typescript
-{
-  allowed: boolean;        // Whether sending is allowed
-  count: number;           // Current count in time window
-  limit: number;           // Maximum allowed
-  timeWindowMs: number;    // Time window size
-  retryAfter?: number;     // Milliseconds until oldest email expires (if limited)
-}
-```
-
-### 2. Check Actor Rate Limit
-
-Check if a specific user/actor can send more emails:
-
-```typescript
-const rateLimitCheck = await ctx.runQuery(
-  components.loopsComponent.lib.checkActorRateLimit,
-  {
-    actorId: "user-123",   // User ID or actor identifier
-    timeWindowMs: 3600000, // 1 hour
-    maxEmails: 100,        // Max 100 emails per hour from this actor
-  }
-);
-
-if (!rateLimitCheck.allowed) {
-  throw new Error(`Rate limit exceeded for actor.`);
-}
-```
-
-**Note:** Actor ID must be set when logging email operations. The app layer should pass it through (see below).
-
-### 3. Check Global Rate Limit
-
-Check system-wide email sending rate:
-
-```typescript
-const rateLimitCheck = await ctx.runQuery(
-  components.loopsComponent.lib.checkGlobalRateLimit,
-  {
-    timeWindowMs: 3600000, // 1 hour
-    maxEmails: 10000,      // Max 10,000 emails per hour system-wide
-  }
-);
-
-if (!rateLimitCheck.allowed) {
-  throw new Error(`Global rate limit exceeded.`);
-}
-```
-
-## Usage Patterns
-
-### Pattern 1: Rate Limit Check Before Sending
-
-```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 recipient rate limit
-    const recipientCheck = await ctx.runQuery(
-      components.loopsComponent.lib.checkRecipientRateLimit,
-      {
-        email: args.email,
-        timeWindowMs: 3600000, // 1 hour
-        maxEmails: 10,         // 10 emails per hour per recipient
-      }
-    );
-
-    if (!recipientCheck.allowed) {
-      const retrySeconds = Math.ceil((recipientCheck.retryAfter ?? 0) / 1000);
-      throw new Error(
-        `Rate limit exceeded. You can send emails to ${args.email} again in ${retrySeconds} seconds.`
-      );
-    }
-
-    // Check actor rate limit
-    const actorCheck = await ctx.runQuery(
-      components.loopsComponent.lib.checkActorRateLimit,
-      {
-        actorId: identity.subject,
-        timeWindowMs: 3600000, // 1 hour
-        maxEmails: 100,        // 100 emails per hour per user
-      }
-    );
-
-    if (!actorCheck.allowed) {
-      throw new Error(`You've reached your email sending limit. Please try again later.`);
-    }
-
-    // Send email if rate limits pass
-    return await loops.sendTransactional(ctx, {
-      email: args.email,
-      transactionalId: args.transactionalId,
-    });
-  },
-});
-```
-
-### Pattern 2: Helper Function for Rate Limiting
-
-Create a reusable helper function:
-
-```typescript
-// In your app's convex/rateLimits.ts
-import { components } from "./_generated/api";
-
-export async function enforceEmailRateLimits(
-  ctx: ActionCtx,
-  options: {
-    email: string;
-    actorId: string;
-  }
-) {
-  // Check recipient limit (10 per hour)
-  const recipientCheck = await ctx.runQuery(
-    components.loopsComponent.lib.checkRecipientRateLimit,
-    {
-      email: options.email,
-      timeWindowMs: 3600000,
-      maxEmails: 10,
-    }
-  );
-
-  if (!recipientCheck.allowed) {
-    const retrySeconds = Math.ceil((recipientCheck.retryAfter ?? 0) / 1000);
-    throw new Error(
-      `Rate limit exceeded. Retry after ${retrySeconds} seconds.`
-    );
-  }
-
-  // Check actor limit (100 per hour)
-  const actorCheck = await ctx.runQuery(
-    components.loopsComponent.lib.checkActorRateLimit,
-    {
-      actorId: options.actorId,
-      timeWindowMs: 3600000,
-      maxEmails: 100,
-    }
-  );
-
-  if (!actorCheck.allowed) {
-    throw new Error(`Email sending limit reached. Please try again later.`);
-  }
-
-  // Optional: Check global limit
-  const globalCheck = await ctx.runQuery(
-    components.loopsComponent.lib.checkGlobalRateLimit,
-    {
-      timeWindowMs: 3600000,
-      maxEmails: 10000, // 10k per hour system-wide
-    }
-  );
-
-  if (!globalCheck.allowed) {
-    throw new Error(`System email limit reached. Please try again later.`);
-  }
-}
-
-// Then use it:
-export const sendTransactional = action({
-  handler: async (ctx, args) => {
-    const identity = await ctx.auth.getUserIdentity();
-    if (!identity) throw new Error("Unauthorized");
-
-    await enforceEmailRateLimits(ctx, {
-      email: args.email,
-      actorId: identity.subject,
-    });
-
-    return await loops.sendTransactional(ctx, args);
-  },
-});
-```
-
-### Pattern 3: Different Limits for Different Operations
-
-```typescript
-const RATE_LIMITS = {
-  transactional: {
-    recipient: { timeWindowMs: 3600000, maxEmails: 10 }, // 10/hour
-    actor: { timeWindowMs: 3600000, maxEmails: 100 },    // 100/hour
-  },
-  campaign: {
-    actor: { timeWindowMs: 3600000, maxEmails: 5 },      // 5/hour (more restrictive)
-  },
-  event: {
-    recipient: { timeWindowMs: 3600000, maxEmails: 20 }, // 20/hour
-    actor: { timeWindowMs: 3600000, maxEmails: 200 },    // 200/hour
-  },
-};
-
-export const sendTransactional = action({
-  handler: async (ctx, args) => {
-    const identity = await ctx.auth.getUserIdentity();
-    if (!identity) throw new Error("Unauthorized");
-
-    const limits = RATE_LIMITS.transactional;
-
-    // Check limits
-    const recipientCheck = await ctx.runQuery(
-      components.loopsComponent.lib.checkRecipientRateLimit,
-      {
-        email: args.email,
-        ...limits.recipient,
-      }
-    );
-
-    if (!recipientCheck.allowed) {
-      throw new Error("Recipient rate limit exceeded");
-    }
-
-    const actorCheck = await ctx.runQuery(
-      components.loopsComponent.lib.checkActorRateLimit,
-      {
-        actorId: identity.subject,
-        ...limits.actor,
-      }
-    );
-
-    if (!actorCheck.allowed) {
-      throw new Error("Actor rate limit exceeded");
-    }
-
-    return await loops.sendTransactional(ctx, args);
-  },
-});
-```
-
-## Setting Actor IDs
-
-To use actor-based rate limiting, you need to ensure actor IDs are logged with email operations. Currently, the component logs operations automatically, but actor IDs must be passed from the app layer.
-
-**Future Enhancement:** The component could accept an optional `actorId` parameter in email-sending functions. For now, you can track actor IDs by:
-
-1. Using the `userId` field in contacts (which gets logged in some operations)
-2. Extending the component to accept actor IDs
-3. Creating wrapper functions that include actor ID in metadata
-
-## Using the Client Library
-
-```typescript
-import { Loops } from "robertalv/loops-component";
-
-const loops = new Loops(components.loopsComponent);
-
-// In an action
-export const sendTransactional = action({
-  handler: async (ctx, args) => {
-    // Check rate limit
-    const check = await loops.checkRecipientRateLimit(ctx, {
-      email: args.email,
-      timeWindowMs: 3600000,
-      maxEmails: 10,
-    });
-
-    if (!check.allowed) {
-      throw new Error("Rate limit exceeded");
-    }
-
-    // Send email
-    return await loops.sendTransactional(ctx, args);
-  },
-});
-```
-
-Or export rate limit functions:
-
-```typescript
-export const {
-  checkRecipientRateLimit,
-  checkActorRateLimit,
-  checkGlobalRateLimit,
-} = loops.api();
-```
-
-## Recommended Rate Limits
-
-Based on email best practices:
-
-### Per Recipient
-- **Transactional emails**: 10-20 per hour
-- **Event-triggered emails**: 5-10 per hour  
-- **Marketing emails**: 1-3 per day
-
-### Per Actor/User
-- **Regular users**: 50-100 emails per hour
-- **Power users**: 200-500 emails per hour
-- **System/automated**: Higher limits with monitoring
-
-### Global
-- Based on your email service provider limits
-- Typical: 10,000-100,000 emails per hour
-- Monitor and adjust based on your usage
-
-## Rate Limiting with convex-helpers
-
-You can also combine component rate limiting with `convex-helpers` rate limiting:
-
-```typescript
-import { rateLimit } from "convex-helpers/server/rateLimit";
-
-export const sendTransactional = action({
-  handler: async (ctx, args) => {
-    // Generic rate limiting (per user)
-    await rateLimit(ctx, { maxOps: 10, period: 60000 }); // 10 per minute
-
-    // Email-specific rate limiting (per recipient)
-    const emailCheck = await ctx.runQuery(
-      components.loopsComponent.lib.checkRecipientRateLimit,
-      {
-        email: args.email,
-        timeWindowMs: 3600000,
-        maxEmails: 10,
-      }
-    );
-
-    if (!emailCheck.allowed) {
-      throw new Error("Email rate limit exceeded");
-    }
-
-    return await loops.sendTransactional(ctx, args);
-  },
-});
-```
-
-## Best Practices
-
-1. **Always check rate limits before sending** - Prevents unnecessary API calls
-2. **Use multiple layers** - Combine recipient, actor, and global limits
-3. **Provide clear error messages** - Tell users when they can retry
-4. **Monitor rate limit hits** - Log when limits are exceeded for analysis
-5. **Adjust limits based on usage** - Start conservative and increase as needed
-6. **Consider different limits** - Transactional vs marketing emails may have different limits
-7. **Use retryAfter** - Provide users with retry timing information
-
-## Integration with Monitoring
-
-Rate limiting works seamlessly with the monitoring system:
-
-```typescript
-export const sendTransactional = action({
-  handler: async (ctx, args) => {
-    // Check rate limit
-    const check = await ctx.runQuery(
-      components.loopsComponent.lib.checkRecipientRateLimit,
-      { email: args.email, timeWindowMs: 3600000, maxEmails: 10 }
-    );
-
-    if (!check.allowed) {
-      // Log rate limit hit for monitoring
-      console.warn(`Rate limit exceeded for ${args.email}`, check);
-      
-      // Check if it's a spam pattern
-      const spamCheck = await ctx.runQuery(
-        components.loopsComponent.lib.detectRecipientSpam,
-        { maxEmailsPerRecipient: 10 }
-      );
-
-      if (spamCheck.some((s) => s.email === args.email)) {
-        // Alert security team
-        console.error(`Potential spam detected for ${args.email}`);
-      }
-
-      throw new Error("Rate limit exceeded");
-    }
-
-    return await loops.sendTransactional(ctx, args);
-  },
-});
-```
-