@devwithbobby/loops 0.1.17 → 0.1.19

package/README.md

@@ -6,13 +6,13 @@ A Convex component for integrating with [Loops.so](https://loops.so) email marke
 
 ## Features
 
-- ✅ **Contact Management** - Create, update, find, and delete contacts
-- ✅ **Transactional Emails** - Send one-off emails with templates
-- ✅ **Events** - Trigger email workflows based on events
-- ✅ **Loops** - Trigger automated email sequences
-- ✅ **Monitoring** - Track all email operations with spam detection
-- ✅ **Rate Limiting** - Built-in rate limiting queries for abuse prevention
-- ✅ **Type-Safe** - Full TypeScript support with Zod validation
+- **Contact Management** - Create, update, find, list, and delete contacts
+- **Transactional Emails** - Send one-off emails with templates
+- **Events** - Trigger email workflows based on events
+- **Loops** - Trigger automated email sequences
+- **Monitoring** - Track all email operations with spam detection
+- **Rate Limiting** - Built-in rate limiting queries for abuse prevention
+- **Type-Safe** - Full TypeScript support with Zod validation
 
 ## Installation
 
@@ -40,17 +40,17 @@ export default app;
 
 ### 2. Set Up Environment Variables
 
-**⚠️ IMPORTANT: Set your Loops API key before using the component.**
+**IMPORTANT: Set your Loops API key before using the component.**
 
 ```bash
 npx convex env set LOOPS_API_KEY "your-loops-api-key-here"
 ```
 
 **Or via Convex Dashboard:**
-1. Go to Settings → Environment Variables
+1. Go to Settings -> Environment Variables
 2. Add `LOOPS_API_KEY` with your Loops.so API key
 
-Get your API key from [Loops.so Dashboard](https://app.loops.so/settings/api).
+Get your API key from [Loops.so Dashboard](https://app.loops.so/settings?page=api).
 
 ### 3. Use the Component
 
@@ -135,6 +135,27 @@ await loops.updateContact(ctx, "user@example.com", {
 const contact = await loops.findContact(ctx, "user@example.com");
 ```
 
+#### List Contacts
+
+List contacts with pagination and optional filtering.
+
+```typescript
+// Simple list with default limit (100)
+const result = await loops.listContacts(ctx);
+
+// List with filters and pagination
+const result = await loops.listContacts(ctx, {
+  userGroup: "premium",
+  subscribed: true,
+  limit: 20,
+  offset: 0
+});
+
+console.log(result.contacts); // Array of contacts
+console.log(result.total);    // Total count matching filters
+console.log(result.hasMore);  // Boolean indicating if more pages exist
+```
+
 #### Delete Contact
 
 ```typescript
@@ -335,11 +356,12 @@ export const {
   sendEvent,
   triggerLoop,
   countContacts,
+  listContacts,
   // ... all other functions
 } = loops.api();
 ```
 
-**⚠️ Security Warning:** The `api()` helper exports functions without authentication. Always wrap these functions with auth checks in production:
+**Security Warning:** The `api()` helper exports functions without authentication. Always wrap these functions with auth checks in production:
 
 ```typescript
 export const addContact = action({
@@ -392,12 +414,12 @@ npx convex env set LOOPS_API_KEY "your-api-key"
 
 **Via Dashboard:**
 1. Go to your Convex Dashboard
-2. Navigate to Settings → Environment Variables
+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).
+Get your API key from [Loops.so Dashboard](https://app.loops.so/settings?page=api).
 
-⚠️ **Never** pass the API key directly in code or via function options in production. Always use environment variables.
+**Never** pass the API key directly in code or via function options in production. Always use environment variables.
 
 ## Monitoring & Rate Limiting
 
@@ -458,15 +480,16 @@ example/                   # Example app
 
 This component implements the following Loops.so API endpoints:
 
-- ✅ Create/Update Contact
-- ✅ Delete Contact
-- ✅ Find Contact
-- ✅ Batch Create Contacts
-- ✅ Unsubscribe/Resubscribe Contact
-- ✅ Count Contacts (custom implementation)
-- ✅ Send Transactional Email
-- ✅ Send Event
-- ✅ Trigger Loop
+- Create/Update Contact
+- Delete Contact
+- Find Contact
+- Batch Create Contacts
+- Unsubscribe/Resubscribe Contact
+- Count Contacts (custom implementation)
+- List Contacts (custom implementation)
+- Send Transactional Email
+- Send Event
+- Trigger Loop
 
 ## Contributing
 

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
-import type { Mounts } from "../component/_generated/api";
-import type { RunActionCtx, RunQueryCtx, UseApi } from "../types";
-export type LoopsComponent = UseApi<Mounts>;
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { RunActionCtx, RunQueryCtx } from "../types";
+export type LoopsComponent = ComponentApi;
 export interface ContactData {
     email: string;
     firstName?: string;
@@ -25,16 +25,21 @@ export declare class Loops {
         apiKey?: string;
     };
     private readonly lib;
+    private _apiKey?;
     constructor(component: LoopsComponent, options?: {
         apiKey?: string;
     });
-    private readonly apiKey;
+    /**
+     * Get the API key, checking environment at call time (not constructor time).
+     * This allows the Loops client to be instantiated at module load time.
+     */
+    private get apiKey();
     /**
      * Add or update a contact in Loops
      */
     addContact(ctx: RunActionCtx, contact: ContactData): Promise<{
+        id?: string;
         success: boolean;
-        id?: string | undefined;
     }>;
     /**
      * Update an existing contact in Loops
@@ -48,8 +53,8 @@ export declare class Loops {
      * Send a transactional email using a transactional ID
      */
     sendTransactional(ctx: RunActionCtx, options: TransactionalEmailOptions): Promise<{
+        messageId?: string;
         success: boolean;
-        messageId?: string | undefined;
     }>;
     /**
      * Send an event to Loops to trigger email workflows
@@ -62,32 +67,32 @@ export declare class Loops {
      * Retrieves contact information from Loops
      */
     findContact(ctx: RunActionCtx, email: string): Promise<{
-        success: boolean;
         contact?: {
-            id?: string | null | undefined;
-            email?: string | null | undefined;
-            firstName?: string | null | undefined;
-            lastName?: string | null | undefined;
-            source?: string | null | undefined;
-            subscribed?: boolean | null | undefined;
-            userGroup?: string | null | undefined;
-            userId?: string | null | undefined;
-            createdAt?: string | null | undefined;
-        } | undefined;
+            createdAt?: string | null;
+            email?: string | null;
+            firstName?: string | null;
+            id?: string | null;
+            lastName?: string | null;
+            source?: string | null;
+            subscribed?: boolean | null;
+            userGroup?: string | null;
+            userId?: string | null;
+        };
+        success: boolean;
     }>;
     /**
      * Batch create contacts
      * Create multiple contacts in a single API call
      */
     batchCreateContacts(ctx: RunActionCtx, contacts: ContactData[]): Promise<{
-        success: boolean;
-        created?: number | undefined;
-        failed?: number | undefined;
-        results?: {
+        created?: number;
+        failed?: number;
+        results?: Array<{
             email: string;
+            error?: string;
             success: boolean;
-            error?: string | undefined;
-        }[] | undefined;
+        }>;
+        success: boolean;
     }>;
     /**
      * Unsubscribe a contact
@@ -125,23 +130,23 @@ export declare class Loops {
         limit?: number;
         offset?: number;
     }): Promise<{
-        contacts: {
+        contacts: Array<{
             _id: string;
+            createdAt: number;
             email: string;
+            firstName?: string;
+            lastName?: string;
+            loopsContactId?: string;
+            source?: string;
             subscribed: boolean;
-            createdAt: number;
             updatedAt: number;
-            firstName?: string | undefined;
-            lastName?: string | undefined;
-            userId?: string | undefined;
-            source?: string | undefined;
-            userGroup?: string | undefined;
-            loopsContactId?: string | undefined;
-        }[];
-        total: number;
+            userGroup?: string;
+            userId?: string;
+        }>;
+        hasMore: boolean;
         limit: number;
         offset: number;
-        hasMore: boolean;
+        total: number;
     }>;
     /**
      * Detect spam patterns: emails sent to the same recipient too frequently
@@ -150,9 +155,8 @@ export declare class Loops {
         timeWindowMs?: number;
         maxEmailsPerRecipient?: number;
     }): Promise<{
-        [x: string]: any;
-        email: string;
         count: number;
+        email: string;
         timeWindowMs: number;
     }[]>;
     /**
@@ -172,15 +176,12 @@ export declare class Loops {
     getEmailStats(ctx: RunQueryCtx, options?: {
         timeWindowMs?: number;
     }): Promise<{
-        [x: string]: any;
-        totalOperations: number;
-        successfulOperations: number;
         failedOperations: number;
-        operationsByType: {
-            [x: string]: number;
-        };
-        uniqueRecipients: number;
+        operationsByType: Record<string, number>;
+        successfulOperations: number;
+        totalOperations: number;
         uniqueActors: number;
+        uniqueRecipients: number;
     }>;
     /**
      * Detect rapid-fire email sending patterns
@@ -189,12 +190,12 @@ export declare class Loops {
         timeWindowMs?: number;
         minEmailsInWindow?: number;
     }): Promise<{
+        actorId?: string;
         count: number;
-        timeWindowMs: number;
+        email?: string;
         firstTimestamp: number;
         lastTimestamp: number;
-        email?: string | undefined;
-        actorId?: string | undefined;
+        timeWindowMs: number;
     }[]>;
     /**
      * Check if an email can be sent to a recipient based on rate limits
@@ -204,12 +205,11 @@ export declare class Loops {
         timeWindowMs: number;
         maxEmails: number;
     }): Promise<{
-        [x: string]: any;
         allowed: boolean;
         count: number;
         limit: number;
+        retryAfter?: number;
         timeWindowMs: number;
-        retryAfter?: number | undefined;
     }>;
     /**
      * Check if an actor/user can send more emails based on rate limits
@@ -222,8 +222,8 @@ export declare class Loops {
         allowed: boolean;
         count: number;
         limit: number;
+        retryAfter?: number;
         timeWindowMs: number;
-        retryAfter?: number | undefined;
     }>;
     /**
      * Check global email sending rate limit
@@ -260,7 +260,7 @@ export declare class Loops {
         eventName?: string;
     }): Promise<{
         success: boolean;
-        warning?: string | undefined;
+        warning?: string;
     }>;
     /**
      * For easy re-exporting.
@@ -279,8 +279,8 @@ export declare class Loops {
             userGroup?: string | undefined;
             email: string;
         }, Promise<{
+            id?: string;
             success: boolean;
-            id?: string | undefined;
         }>>;
         updateContact: import("convex/server").RegisteredAction<"public", {
             firstName?: string | undefined;
@@ -299,8 +299,8 @@ export declare class Loops {
             email: string;
             transactionalId: string;
         }, Promise<{
+            messageId?: string;
             success: boolean;
-            messageId?: string | undefined;
         }>>;
         sendEvent: import("convex/server").RegisteredAction<"public", {
             eventProperties?: any;
@@ -320,23 +320,23 @@ export declare class Loops {
             loopId: string;
         }, Promise<{
             success: boolean;
-            warning?: string | undefined;
+            warning?: string;
         }>>;
         findContact: import("convex/server").RegisteredAction<"public", {
             email: string;
         }, Promise<{
-            success: boolean;
             contact?: {
-                id?: string | null | undefined;
-                email?: string | null | undefined;
-                firstName?: string | null | undefined;
-                lastName?: string | null | undefined;
-                source?: string | null | undefined;
-                subscribed?: boolean | null | undefined;
-                userGroup?: string | null | undefined;
-                userId?: string | null | undefined;
-                createdAt?: string | null | undefined;
-            } | undefined;
+                createdAt?: string | null;
+                email?: string | null;
+                firstName?: string | null;
+                id?: string | null;
+                lastName?: string | null;
+                source?: string | null;
+                subscribed?: boolean | null;
+                userGroup?: string | null;
+                userId?: string | null;
+            };
+            success: boolean;
         }>>;
         batchCreateContacts: import("convex/server").RegisteredAction<"public", {
             contacts: {
@@ -349,14 +349,14 @@ export declare class Loops {
                 email: string;
             }[];
         }, Promise<{
-            success: boolean;
-            created?: number | undefined;
-            failed?: number | undefined;
-            results?: {
+            created?: number;
+            failed?: number;
+            results?: Array<{
                 email: string;
+                error?: string;
                 success: boolean;
-                error?: string | undefined;
-            }[] | undefined;
+            }>;
+            success: boolean;
         }>>;
         unsubscribeContact: import("convex/server").RegisteredAction<"public", {
             email: string;
@@ -373,13 +373,37 @@ export declare class Loops {
             subscribed?: boolean | undefined;
             userGroup?: string | undefined;
         }, Promise<number>>;
+        listContacts: import("convex/server").RegisteredQuery<"public", {
+            source?: string | undefined;
+            subscribed?: boolean | undefined;
+            userGroup?: string | undefined;
+            limit?: number | undefined;
+            offset?: number | undefined;
+        }, Promise<{
+            contacts: Array<{
+                _id: string;
+                createdAt: number;
+                email: string;
+                firstName?: string;
+                lastName?: string;
+                loopsContactId?: string;
+                source?: string;
+                subscribed: boolean;
+                updatedAt: number;
+                userGroup?: string;
+                userId?: string;
+            }>;
+            hasMore: boolean;
+            limit: number;
+            offset: number;
+            total: number;
+        }>>;
         detectRecipientSpam: import("convex/server").RegisteredQuery<"public", {
             timeWindowMs?: number | undefined;
             maxEmailsPerRecipient?: number | undefined;
         }, Promise<{
-            [x: string]: any;
-            email: string;
             count: number;
+            email: string;
             timeWindowMs: number;
         }[]>>;
         detectActorSpam: import("convex/server").RegisteredQuery<"public", {
@@ -393,38 +417,34 @@ export declare class Loops {
         getEmailStats: import("convex/server").RegisteredQuery<"public", {
             timeWindowMs?: number | undefined;
         }, Promise<{
-            [x: string]: any;
-            totalOperations: number;
-            successfulOperations: number;
             failedOperations: number;
-            operationsByType: {
-                [x: string]: number;
-            };
-            uniqueRecipients: number;
+            operationsByType: Record<string, number>;
+            successfulOperations: number;
+            totalOperations: number;
             uniqueActors: number;
+            uniqueRecipients: number;
         }>>;
         detectRapidFirePatterns: import("convex/server").RegisteredQuery<"public", {
             timeWindowMs?: number | undefined;
             minEmailsInWindow?: number | undefined;
         }, Promise<{
+            actorId?: string;
             count: number;
-            timeWindowMs: number;
+            email?: string;
             firstTimestamp: number;
             lastTimestamp: number;
-            email?: string | undefined;
-            actorId?: string | undefined;
+            timeWindowMs: number;
         }[]>>;
         checkRecipientRateLimit: import("convex/server").RegisteredQuery<"public", {
             email: string;
             timeWindowMs: number;
             maxEmails: number;
         }, Promise<{
-            [x: string]: any;
             allowed: boolean;
             count: number;
             limit: number;
+            retryAfter?: number;
             timeWindowMs: number;
-            retryAfter?: number | undefined;
         }>>;
         checkActorRateLimit: import("convex/server").RegisteredQuery<"public", {
             actorId: string;
@@ -434,8 +454,8 @@ export declare class Loops {
             allowed: boolean;
             count: number;
             limit: number;
+            retryAfter?: number;
             timeWindowMs: number;
-            retryAfter?: number | undefined;
         }>>;
         checkGlobalRateLimit: import("convex/server").RegisteredQuery<"public", {
             timeWindowMs: number;

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/index.js

@@ -3,6 +3,7 @@ import { v } from "convex/values";
 export class Loops {
     options;
     lib;
+    _apiKey;
     constructor(component, options) {
         if (!component) {
             throw new Error("Loops component reference is required. " +
@@ -17,18 +18,24 @@ export class Loops {
         }
         this.lib = component.lib;
         this.options = options;
-        const apiKey = options?.apiKey ?? process.env.LOOPS_API_KEY;
-        if (!apiKey) {
-            throw new Error("Loops API key is required. Set LOOPS_API_KEY in your Convex environment variables.");
-        }
+        this._apiKey = options?.apiKey;
         if (options?.apiKey) {
             console.warn("API key passed directly via options. " +
                 "For security, use LOOPS_API_KEY environment variable instead. " +
-                "See ENV_SETUP.md for details.");
+                "See README.md for details.");
+        }
+    }
+    /**
+     * Get the API key, checking environment at call time (not constructor time).
+     * This allows the Loops client to be instantiated at module load time.
+     */
+    get apiKey() {
+        const key = this._apiKey ?? process.env.LOOPS_API_KEY;
+        if (!key) {
+            throw new Error("Loops API key is required. Set LOOPS_API_KEY in your Convex environment variables.");
         }
-        this.apiKey = apiKey;
+        return key;
     }
-    apiKey;
     /**
      * Add or update a contact in Loops
      */
@@ -333,6 +340,18 @@ export class Loops {
                     return await this.countContacts(ctx, args);
                 },
             }),
+            listContacts: queryGeneric({
+                args: {
+                    userGroup: v.optional(v.string()),
+                    source: v.optional(v.string()),
+                    subscribed: v.optional(v.boolean()),
+                    limit: v.optional(v.number()),
+                    offset: v.optional(v.number()),
+                },
+                handler: async (ctx, args) => {
+                    return await this.listContacts(ctx, args);
+                },
+            }),
             detectRecipientSpam: queryGeneric({
                 args: {
                     timeWindowMs: v.optional(v.number()),

package/dist/component/_generated/api.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import type * as helpers from "../helpers.js";
+import type * as http from "../http.js";
+import type * as lib from "../lib.js";
+import type * as tables_contacts from "../tables/contacts.js";
+import type * as tables_emailOperations from "../tables/emailOperations.js";
+import type * as validators from "../validators.js";
+import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
+declare const fullApi: ApiFromModules<{
+    helpers: typeof helpers;
+    http: typeof http;
+    lib: typeof lib;
+    "tables/contacts": typeof tables_contacts;
+    "tables/emailOperations": typeof tables_emailOperations;
+    validators: typeof validators;
+}>;
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<typeof fullApi, FunctionReference<any, "public">>;
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<typeof fullApi, FunctionReference<any, "internal">>;
+export declare const components: {};
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/component/_generated/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,KAAK,OAAO,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,KAAK,IAAI,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,KAAK,GAAG,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,KAAK,eAAe,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,KAAK,sBAAsB,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAEpD,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,QAAA,MAAM,OAAO,EAAE,cAAc,CAAC;IAC5B,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,GAAG,EAAE,OAAO,GAAG,CAAC;IAChB,iBAAiB,EAAE,OAAO,eAAe,CAAC;IAC1C,wBAAwB,EAAE,OAAO,sBAAsB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;CAC/B,CAAiB,CAAC;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,EAAE,SAAS,CACzB,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,QAAQ,CAAC,CACjB,CAAC;AAElB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,CAC9B,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,UAAU,CAAC,CACnB,CAAC;AAElB,eAAO,MAAM,UAAU,EAAqC,EAAE,CAAC"}

package/{src → dist}/component/_generated/api.js

@@ -7,11 +7,10 @@
  * To regenerate, run `npx convex dev`.
  * @module
  */
-
 import { anyApi, componentsGeneric } from "convex/server";
-
+const fullApi = anyApi;
 /**
- * A utility for referencing Convex functions in your app's API.
+ * A utility for referencing Convex functions in your app's public API.
  *
  * Usage:
  * ```js
@@ -19,5 +18,13 @@ import { anyApi, componentsGeneric } from "convex/server";
  * ```
  */
 export const api = anyApi;
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
 export const internal = anyApi;
 export const components = componentsGeneric();