@devwithbobby/loops 0.1.5 → 0.1.7

package/README.md

@@ -124,8 +124,7 @@ await loops.addContact(ctx, {
 #### Update Contact
 
 ```typescript
-await loops.updateContact(ctx, {
-  email: "user@example.com",
+await loops.updateContact(ctx, "user@example.com", {
   firstName: "Jane",
   userGroup: "vip",
 });
@@ -134,17 +133,13 @@ await loops.updateContact(ctx, {
 #### Find Contact
 
 ```typescript
-const contact = await loops.findContact(ctx, {
-  email: "user@example.com",
-});
+const contact = await loops.findContact(ctx, "user@example.com");
 ```
 
 #### Delete Contact
 
 ```typescript
-await loops.deleteContact(ctx, {
-  email: "user@example.com",
-});
+await loops.deleteContact(ctx, "user@example.com");
 ```
 
 #### Batch Create Contacts
@@ -161,8 +156,8 @@ await loops.batchCreateContacts(ctx, {
 #### Unsubscribe/Resubscribe
 
 ```typescript
-await loops.unsubscribeContact(ctx, { email: "user@example.com" });
-await loops.resubscribeContact(ctx, { email: "user@example.com" });
+await loops.unsubscribeContact(ctx, "user@example.com");
+await loops.resubscribeContact(ctx, "user@example.com");
 ```
 
 #### Count Contacts
@@ -383,33 +378,59 @@ export const addContact = action({
 ## Security Best Practices
 
 1. **Always add authentication** - Wrap all functions with auth checks
-2. **Use environment variables** - Store API key in Convex environment variables
-3. **Implement rate limiting** - Use the built-in rate limiting queries
+2. **Use environment variables** - Store API key in Convex environment variables (never hardcode)
+3. **Implement rate limiting** - Use the built-in rate limiting queries to prevent abuse
 4. **Monitor for abuse** - Use spam detection queries to identify suspicious patterns
 5. **Sanitize errors** - Don't expose sensitive error details to clients
 
-See [SECURITY.md](./prds/SECURITY.md) for detailed security guidelines.
-
-## Monitoring & Rate Limiting
-
-The component automatically logs all email operations for monitoring. Use the built-in queries to:
+### Authentication Example
 
-- Track email statistics
-- Detect spam patterns
-- Enforce rate limits
-- Monitor for abuse
+All functions should be wrapped with authentication:
 
-See [MONITORING.md](./prds/MONITORING.md) and [RATE_LIMITING.md](./prds/RATE_LIMITING.md) for detailed guides.
+```typescript
+export const addContact = action({
+  args: { email: v.string(), ... },
+  handler: async (ctx, args) => {
+    // Add authentication check
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new Error("Unauthorized");
+    
+    // Add authorization checks if needed
+    // if (!isAdmin(identity)) throw new Error("Forbidden");
+    
+    return await loops.addContact(ctx, args);
+  },
+});
+```
 
-## Environment Variables
+### Environment Variables
 
 Set `LOOPS_API_KEY` in your Convex environment:
 
+**Via CLI:**
 ```bash
 npx convex env set LOOPS_API_KEY "your-api-key"
 ```
 
-See [ENV_SETUP.md](./prds/ENV_SETUP.md) for detailed setup instructions.
+**Via Dashboard:**
+1. Go to your Convex Dashboard
+2. Navigate to Settings → Environment Variables
+3. Add `LOOPS_API_KEY` with your Loops.so API key value
+
+Get your API key from [Loops.so Dashboard](https://app.loops.so/settings/api).
+
+⚠️ **Never** pass the API key directly in code or via function options in production. Always use environment variables.
+
+## Monitoring & Rate Limiting
+
+The component automatically logs all email operations to the `emailOperations` table for monitoring. Use the built-in queries to:
+
+- **Track email statistics** - See total sends, success/failure rates, breakdowns by type
+- **Detect spam patterns** - Identify suspicious activity by recipient or actor
+- **Enforce rate limits** - Prevent abuse with recipient, actor, or global rate limits
+- **Monitor for abuse** - Detect rapid-fire patterns and unusual sending behavior
+
+All monitoring queries are available through the `Loops` client - see the [Monitoring & Analytics](#monitoring--analytics) section above for usage examples.
 
 ## Development
 

package/dist/component/lib.d.ts

@@ -17,6 +17,8 @@ export declare const logEmailOperation: any;
 export declare const countContacts: any;
 /**
  * Add or update a contact in Loops
+ * This function tries to create a contact, and if the email already exists (409),
+ * it falls back to updating the contact instead.
  */
 export declare const addContact: any;
 /**
@@ -49,6 +51,7 @@ export declare const triggerLoop: any;
 /**
  * Find a contact by email
  * Retrieves contact information from Loops
+ * Note: Loops API may return either an object or an array
  */
 export declare const findContact: any;
 /**

package/dist/component/lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/component/lib.ts"],"names":[],"mappings":"AA0BA;;GAEG;AACH,eAAO,MAAM,YAAY,KA6CvB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,KAexB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,KAgC5B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa,KAwCxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU,KA2CrB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,KAoDxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,KAqD5B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS,KAgCpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,KA8BxB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY,KAkFvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,KA+CtB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,WAAW,KAiDtB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KA4C9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KA+B7B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KA+B7B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KAwC9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,KAwC1B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,KAgDxB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,uBAAuB,KAsGlC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,uBAAuB,KA6ClC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KA6C9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,KA8B/B,CAAC"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/component/lib.ts"],"names":[],"mappings":"AA0BA;;GAEG;AACH,eAAO,MAAM,YAAY,KA6CvB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,KAexB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,KAgC5B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa,KAwCxB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU,KAiHrB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,KAoDxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,KAqD5B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS,KAgCpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,KA8BxB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,YAAY,KAkFvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,KA+CtB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,KAoDtB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KA4C9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KA+B7B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KA+B7B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KAwC9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe,KAwC1B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,KAgDxB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,uBAAuB,KAsGlC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,uBAAuB,KA6ClC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KA6C9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,KA8B/B,CAAC"}

package/dist/component/lib.js

@@ -177,6 +177,8 @@ export const countContacts = zq({
 });
 /**
  * Add or update a contact in Loops
+ * This function tries to create a contact, and if the email already exists (409),
+ * it falls back to updating the contact instead.
  */
 export const addContact = za({
     args: z.object({
@@ -198,9 +200,67 @@ export const addContact = za({
         });
         if (!response.ok) {
             const errorText = await response.text();
+            if (response.status === 409) {
+                console.log(`Contact ${args.contact.email} already exists, updating instead`);
+                const findResponse = await fetch(`${LOOPS_API_BASE_URL}/contacts/find?email=${encodeURIComponent(args.contact.email)}`, {
+                    method: "GET",
+                    headers: {
+                        Authorization: `Bearer ${args.apiKey}`,
+                        "Content-Type": "application/json",
+                    },
+                });
+                if (!findResponse.ok) {
+                    const findErrorText = await findResponse.text();
+                    console.error(`Failed to find existing contact [${findResponse.status}]:`, findErrorText);
+                }
+                const updateResponse = await fetch(`${LOOPS_API_BASE_URL}/contacts/update`, {
+                    method: "PUT",
+                    headers: {
+                        Authorization: `Bearer ${args.apiKey}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        email: args.contact.email,
+                        firstName: args.contact.firstName,
+                        lastName: args.contact.lastName,
+                        userId: args.contact.userId,
+                        source: args.contact.source,
+                        subscribed: args.contact.subscribed,
+                        userGroup: args.contact.userGroup,
+                    }),
+                });
+                if (!updateResponse.ok) {
+                    const updateErrorText = await updateResponse.text();
+                    console.error(`Loops API error [${updateResponse.status}]:`, updateErrorText);
+                    throw sanitizeError(updateResponse.status, updateErrorText);
+                }
+                // Get contact ID if available
+                let contactId;
+                if (findResponse.ok) {
+                    const findData = (await findResponse.json());
+                    contactId = findData.id;
+                }
+                // Store/update in our database
+                await ctx.runMutation((internal.lib).storeContact, {
+                    email: args.contact.email,
+                    firstName: args.contact.firstName,
+                    lastName: args.contact.lastName,
+                    userId: args.contact.userId,
+                    source: args.contact.source,
+                    subscribed: args.contact.subscribed,
+                    userGroup: args.contact.userGroup,
+                    loopsContactId: contactId,
+                });
+                return {
+                    success: true,
+                    id: contactId,
+                };
+            }
+            // For other errors, throw as normal
             console.error(`Loops API error [${response.status}]:`, errorText);
             throw sanitizeError(response.status, errorText);
         }
+        // Contact was created successfully
         const data = (await response.json());
         await ctx.runMutation((internal.lib).storeContact, {
             email: args.contact.email,
@@ -518,6 +578,7 @@ export const triggerLoop = za({
 /**
  * Find a contact by email
  * Retrieves contact information from Loops
+ * Note: Loops API may return either an object or an array
  */
 export const findContact = za({
     args: z.object({
@@ -557,9 +618,11 @@ export const findContact = za({
             throw sanitizeError(response.status, errorText);
         }
         const data = (await response.json());
+        // Handle case where Loops returns an array instead of a single object
+        const contact = Array.isArray(data) ? data[0] : data;
         return {
             success: true,
-            contact: data,
+            contact: contact,
         };
     },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devwithbobby/loops",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Convex component for integrating with Loops.so email marketing platform",
   "license": "Apache-2.0",
   "type": "module",

package/src/component/lib.ts

@@ -179,6 +179,8 @@ export const countContacts = zq({
 
 /**
  * Add or update a contact in Loops
+ * This function tries to create a contact, and if the email already exists (409),
+ * it falls back to updating the contact instead.
  */
 export const addContact = za({
 	args: z.object({
@@ -201,10 +203,80 @@ export const addContact = za({
 
 		if (!response.ok) {
 			const errorText = await response.text();
+			
+			if (response.status === 409) {
+				console.log(`Contact ${args.contact.email} already exists, updating instead`);
+				
+				const findResponse = await fetch(
+					`${LOOPS_API_BASE_URL}/contacts/find?email=${encodeURIComponent(args.contact.email)}`,
+					{
+						method: "GET",
+						headers: {
+							Authorization: `Bearer ${args.apiKey}`,
+							"Content-Type": "application/json",
+						},
+					}
+				);
+
+				if (!findResponse.ok) {
+					const findErrorText = await findResponse.text();
+					console.error(`Failed to find existing contact [${findResponse.status}]:`, findErrorText);
+				}
+
+				const updateResponse = await fetch(`${LOOPS_API_BASE_URL}/contacts/update`, {
+					method: "PUT",
+					headers: {
+						Authorization: `Bearer ${args.apiKey}`,
+						"Content-Type": "application/json",
+					},
+					body: JSON.stringify({
+						email: args.contact.email,
+						firstName: args.contact.firstName,
+						lastName: args.contact.lastName,
+						userId: args.contact.userId,
+						source: args.contact.source,
+						subscribed: args.contact.subscribed,
+						userGroup: args.contact.userGroup,
+					}),
+				});
+
+				if (!updateResponse.ok) {
+					const updateErrorText = await updateResponse.text();
+					console.error(`Loops API error [${updateResponse.status}]:`, updateErrorText);
+					throw sanitizeError(updateResponse.status, updateErrorText);
+				}
+
+				// Get contact ID if available
+				let contactId: string | undefined;
+				if (findResponse.ok) {
+					const findData = (await findResponse.json()) as { id?: string };
+					contactId = findData.id;
+				}
+
+				// Store/update in our database
+				await ctx.runMutation(((internal as any).lib).storeContact as any, {
+					email: args.contact.email,
+					firstName: args.contact.firstName,
+					lastName: args.contact.lastName,
+					userId: args.contact.userId,
+					source: args.contact.source,
+					subscribed: args.contact.subscribed,
+					userGroup: args.contact.userGroup,
+					loopsContactId: contactId,
+				});
+
+				return {
+					success: true,
+					id: contactId,
+				};
+			}
+
+			// For other errors, throw as normal
 			console.error(`Loops API error [${response.status}]:`, errorText);
 			throw sanitizeError(response.status, errorText);
 		}
 
+		// Contact was created successfully
 		const data = (await response.json()) as { id?: string };
 
 		await ctx.runMutation(((internal as any).lib).storeContact as any, {
@@ -557,6 +629,7 @@ export const triggerLoop = za({
 /**
  * Find a contact by email
  * Retrieves contact information from Loops
+ * Note: Loops API may return either an object or an array
  */
 export const findContact = za({
 	args: z.object({
@@ -600,11 +673,14 @@ export const findContact = za({
 			throw sanitizeError(response.status, errorText);
 		}
 
-		const data = (await response.json()) as Record<string, any>;
+		const data = (await response.json()) as Record<string, any> | Array<Record<string, any>>;
+
+		// Handle case where Loops returns an array instead of a single object
+		const contact = Array.isArray(data) ? data[0] : data;
 
 		return {
 			success: true,
-			contact: data,
+			contact: contact as Record<string, any> | undefined,
 		};
 	},
 });