@devwithbobby/loops 0.1.0

package/prds/RATE_LIMITING.md

@@ -0,0 +1,412 @@
+# 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);
+  },
+});
+```
+

package/prds/SECURITY.md

@@ -0,0 +1,246 @@
+# Security Considerations for Loops Component
+
+## Current Security Risks
+
+### 1. ⚠️ **No Authentication/Authorization in Example**
+**Risk Level: HIGH**
+
+The example (`example/convex/example.ts`) exports all functions directly without authentication checks. This means:
+- Any authenticated user (or anyone with access) can send emails
+- Anyone can delete contacts
+- Anyone can unsubscribe users
+- No permission checks
+
+**Mitigation Required:**
+- Apps MUST wrap component functions with authentication
+- Add authorization checks before exposing functions to clients
+- Consider role-based access control
+
+### 2. ⚠️ **API Key Exposure Risk**
+**Risk Level: MEDIUM**
+
+The API key is passed through function arguments to component actions:
+- API keys appear in function arguments (could be logged)
+- Error messages might leak API key information
+- API key stored in memory in multiple places
+
+**Current Protection:**
+- API key is `private readonly` in client class
+- Stored in environment variables (not in code)
+- Only accessible from server-side code
+
+**Recommendations:**
+- Avoid logging function arguments
+- Sanitize error messages
+- Consider using Convex secrets management
+
+### 3. ⚠️ **Error Message Information Leakage**
+**Risk Level: MEDIUM**
+
+Error messages could expose sensitive information:
+```typescript
+throw new Error(`Loops API error: ${response.status} ${error}`);
+```
+- Could leak API details
+- Could expose internal structure
+
+**Recommendation:**
+- Sanitize error messages in production
+- Log detailed errors server-side only
+- Return generic error messages to clients
+
+### 4. ⚠️ **No Rate Limiting**
+**Risk Level: MEDIUM**
+
+Functions can be called unlimited times:
+- Could be abused to send spam
+- Could exhaust API quotas
+- Could cause DoS
+
+**Recommendation:**
+- Implement rate limiting in app wrapper functions
+- Use Convex rate limiting features
+- Consider per-user/per-IP limits
+
+### 5. ⚠️ **countContacts Query Exposed**
+**Risk Level: LOW-MEDIUM**
+
+The `countContacts` query can reveal user counts without authentication:
+- Anyone with app access can see audience sizes
+- Could be used for reconnaissance
+
+**Recommendation:**
+- Wrap in app function with auth
+- Consider if counts should be public information
+
+### 6. ✅ **Input Validation**
+**Status: GOOD**
+
+- Zod validation on all inputs
+- Email validation using `.email()` validator
+- Type safety enforced
+
+**Remaining Concerns:**
+- Ensure no email injection attacks
+- Validate event names and properties
+
+### 7. ✅ **Component Isolation**
+**Status: GOOD**
+
+- Component functions are internal (not directly callable from clients)
+- Apps must explicitly wrap functions
+- Follows Convex security model
+
+## Security Best Practices
+
+### ✅ What to Do:
+
+1. **Always Add Authentication in App Wrapper:**
+```typescript
+// ✅ GOOD - Add auth check
+export const addContact = action({
+  args: { email: v.string(), ... },
+  handler: async (ctx, args) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new Error("Unauthorized");
+    
+    // Check permissions
+    if (!hasPermission(identity, "manageContacts")) {
+      throw new Error("Forbidden");
+    }
+    
+    return await loops.addContact(ctx, { email: args.email, ... });
+  },
+});
+```
+
+2. **Use Environment Variables for API Key:**
+```typescript
+// ✅ GOOD - API key from environment
+// Set LOOPS_API_KEY in Convex environment variables first:
+// npx convex env set LOOPS_API_KEY "your-api-key"
+const loops = new Loops(components.loopsComponent);
+// Uses process.env.LOOPS_API_KEY automatically
+
+// ❌ BAD - Never pass API key directly in production
+// const loops = new Loops(components.loopsComponent, { apiKey: "..." });
+```
+**📖 See [ENV_SETUP.md](./ENV_SETUP.md) for detailed setup instructions and security best practices.**
+
+3. **Sanitize Error Messages:**
+```typescript
+// ✅ GOOD - Generic error to client
+try {
+  await loops.addContact(ctx, contact);
+} catch (error) {
+  // Log detailed error server-side
+  console.error("Failed to add contact:", error);
+  // Return generic error to client
+  throw new Error("Failed to add contact. Please try again.");
+}
+```
+
+4. **Implement Rate Limiting:**
+```typescript
+import { rateLimit } from "convex-helpers/server/rateLimit";
+
+export const sendTransactional = action({
+  args: { ... },
+  handler: async (ctx, args) => {
+    await rateLimit(ctx, { maxOps: 10, period: 60000 }); // 10 per minute
+    return await loops.sendTransactional(ctx, args);
+  },
+});
+```
+
+5. **Validate User Permissions:**
+```typescript
+export const deleteContact = action({
+  args: { email: v.string() },
+  handler: async (ctx, args) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new Error("Unauthorized");
+    
+    // Only admins can delete contacts
+    if (!isAdmin(identity)) {
+      throw new Error("Only admins can delete contacts");
+    }
+    
+    return await loops.deleteContact(ctx, args.email);
+  },
+});
+```
+
+### ❌ What NOT to Do:
+
+1. **Don't Export Functions Directly Without Auth:**
+```typescript
+// ❌ BAD - No authentication
+export const { addContact, deleteContact } = loops.api();
+```
+
+2. **Don't Pass API Key from Client:**
+```typescript
+// ❌ BAD - Never do this
+export const addContact = action({
+  args: { apiKey: v.string(), ... }, // Never accept API key from client
+  handler: async (ctx, args) => { ... }
+});
+```
+
+3. **Don't Expose Internal Errors:**
+```typescript
+// ❌ BAD - Exposes internal details
+catch (error) {
+  throw new Error(`API call failed: ${error.message} with key ${apiKey}`);
+}
+```
+
+4. **Don't Skip Rate Limiting for Email Sending:**
+```typescript
+// ❌ BAD - No rate limiting
+export const sendCampaign = action({
+  handler: async (ctx, args) => {
+    // Anyone could spam unlimited emails!
+    return await loops.sendCampaign(ctx, args);
+  },
+});
+```
+
+## Recommended Security Architecture
+
+```
+Client (React)
+    ↓
+App Function (with auth, rate limiting, validation)
+    ↓
+Loops Client (with API key from env)
+    ↓
+Component Function (validates input)
+    ↓
+Loops.so API
+```
+
+## Security Checklist for Apps Using This Component
+
+- [ ] Wrap all functions with authentication checks
+- [ ] Add authorization checks (role-based if needed)
+- [x] Implement rate limiting for email-sending functions - ✅ **IMPLEMENTED** See RATE_LIMITING.md
+- [ ] Sanitize error messages before returning to clients
+- [x] Store API key in Convex environment variables only - ✅ **IMPLEMENTED** See ENV_SETUP.md
+- [ ] Audit who can access contact management functions
+- [ ] Consider logging all email operations for audit trail
+- [ ] Validate user permissions for sensitive operations (delete, unsubscribe)
+- [x] Monitor for unusual activity (spam patterns) - ✅ **IMPLEMENTED** See MONITORING.md
+
+## Component-Level Security
+
+The component itself is secure because:
+- ✅ Functions are internal (not directly callable from clients)
+- ✅ Input validation with Zod
+- ✅ Type safety enforced
+- ✅ Component isolation prevents unauthorized access
+- ✅ API key never exposed to client code
+
+However, **apps using this component MUST implement their own security layer** when exposing functions to clients.
+

package/renovate.json

@@ -0,0 +1,32 @@
+{
+	"$schema": "https://docs.renovatebot.com/renovate-schema.json",
+	"extends": ["config:best-practices"],
+	"schedule": ["* 0-4 * * 1"],
+	"timezone": "America/Los_Angeles",
+	"prConcurrentLimit": 1,
+	"packageRules": [
+		{
+			"groupName": "Convex packages",
+			"matchPackagePatterns": ["^convex"],
+			"automerge": false,
+			"description": "Keep Convex packages together but require manual review"
+		},
+		{
+			"groupName": "Routine updates",
+			"matchUpdateTypes": ["minor", "patch", "pin", "digest"],
+			"excludePackagePatterns": ["^convex"],
+			"automerge": true
+		},
+		{
+			"groupName": "Major updates",
+			"matchUpdateTypes": ["major"],
+			"excludePackagePatterns": ["^convex"],
+			"automerge": false
+		},
+		{
+			"matchDepTypes": ["devDependencies"],
+			"excludePackagePatterns": ["^convex"],
+			"automerge": true
+		}
+	]
+}