@devwithbobby/loops 0.1.18 → 0.2.0

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, RunMutationCtx, 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
@@ -114,34 +119,35 @@ export declare class Loops {
         subscribed?: boolean;
     }): Promise<number>;
     /**
-     * List contacts with pagination and optional filters
+     * List contacts with cursor-based pagination and optional filters
      * Returns actual contact data, not just a count
      * This queries the component's local database, not Loops API
+     *
+     * Uses cursor-based pagination for efficiency. Pass the `continueCursor`
+     * from the previous response as `cursor` to get the next page.
      */
     listContacts(ctx: RunQueryCtx, options?: {
         userGroup?: string;
         source?: string;
         subscribed?: boolean;
         limit?: number;
-        offset?: number;
+        cursor?: string | null;
     }): 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;
-        limit: number;
-        offset: number;
-        hasMore: boolean;
+            userGroup?: string;
+            userId?: string;
+        }>;
+        continueCursor: string | null;
+        isDone: boolean;
     }>;
     /**
      * Detect spam patterns: emails sent to the same recipient too frequently
@@ -150,9 +156,8 @@ export declare class Loops {
         timeWindowMs?: number;
         maxEmailsPerRecipient?: number;
     }): Promise<{
-        [x: string]: any;
-        email: string;
         count: number;
+        email: string;
         timeWindowMs: number;
     }[]>;
     /**
@@ -172,15 +177,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 +191,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 +206,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 +223,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 +261,34 @@ export declare class Loops {
         eventName?: string;
     }): Promise<{
         success: boolean;
-        warning?: string | undefined;
+        warning?: string;
+    }>;
+    /**
+     * Backfill the contact aggregate with existing contacts.
+     * Run this after upgrading to a version with aggregate support.
+     *
+     * This processes contacts in batches to avoid timeout issues with large datasets.
+     * Call repeatedly with the returned cursor until isDone is true.
+     *
+     * Usage:
+     * ```ts
+     * // First call - clear existing aggregate and start backfill
+     * let result = await loops.backfillContactAggregate(ctx, { clear: true });
+     *
+     * // Continue until done
+     * while (!result.isDone) {
+     *   result = await loops.backfillContactAggregate(ctx, { cursor: result.cursor });
+     * }
+     * ```
+     */
+    backfillContactAggregate(ctx: RunMutationCtx, options?: {
+        cursor?: string | null;
+        batchSize?: number;
+        clear?: boolean;
+    }): Promise<{
+        cursor: string | null;
+        isDone: boolean;
+        processed: number;
     }>;
     /**
      * For easy re-exporting.
@@ -279,8 +307,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 +327,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 +348,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 +377,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;
@@ -378,33 +406,30 @@ export declare class Loops {
             subscribed?: boolean | undefined;
             userGroup?: string | undefined;
             limit?: number | undefined;
-            offset?: number | undefined;
+            cursor?: string | null | undefined;
         }, 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;
-            limit: number;
-            offset: number;
-            hasMore: boolean;
+                userGroup?: string;
+                userId?: string;
+            }>;
+            continueCursor: string | null;
+            isDone: boolean;
         }>>;
         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", {
@@ -418,38 +443,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;
@@ -459,8 +480,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;
@@ -471,6 +492,15 @@ export declare class Loops {
             limit: number;
             timeWindowMs: number;
         }>>;
+        backfillContactAggregate: import("convex/server").RegisteredMutation<"public", {
+            cursor?: string | null | undefined;
+            batchSize?: number | undefined;
+            clear?: boolean | undefined;
+        }, Promise<{
+            cursor: string | null;
+            isDone: boolean;
+            processed: number;
+        }>>;
     };
 }
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,8 +1,9 @@
-import { actionGeneric, queryGeneric } from "convex/server";
+import { actionGeneric, mutationGeneric, queryGeneric } from "convex/server";
 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 README.md for details.");
         }
-        this.apiKey = apiKey;
     }
-    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.
+     */
+    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.");
+        }
+        return key;
+    }
     /**
      * Add or update a contact in Loops
      */
@@ -115,9 +122,12 @@ export class Loops {
         return ctx.runQuery(this.lib.countContacts, options ?? {});
     }
     /**
-     * List contacts with pagination and optional filters
+     * List contacts with cursor-based pagination and optional filters
      * Returns actual contact data, not just a count
      * This queries the component's local database, not Loops API
+     *
+     * Uses cursor-based pagination for efficiency. Pass the `continueCursor`
+     * from the previous response as `cursor` to get the next page.
      */
     async listContacts(ctx, options) {
         return ctx.runQuery(this.lib.listContacts, {
@@ -125,7 +135,7 @@ export class Loops {
             source: options?.source,
             subscribed: options?.subscribed,
             limit: options?.limit ?? 100,
-            offset: options?.offset ?? 0,
+            cursor: options?.cursor ?? null,
         });
     }
     /**
@@ -206,6 +216,31 @@ export class Loops {
             ...options,
         });
     }
+    /**
+     * Backfill the contact aggregate with existing contacts.
+     * Run this after upgrading to a version with aggregate support.
+     *
+     * This processes contacts in batches to avoid timeout issues with large datasets.
+     * Call repeatedly with the returned cursor until isDone is true.
+     *
+     * Usage:
+     * ```ts
+     * // First call - clear existing aggregate and start backfill
+     * let result = await loops.backfillContactAggregate(ctx, { clear: true });
+     *
+     * // Continue until done
+     * while (!result.isDone) {
+     *   result = await loops.backfillContactAggregate(ctx, { cursor: result.cursor });
+     * }
+     * ```
+     */
+    async backfillContactAggregate(ctx, options) {
+        return ctx.runMutation(this.lib.backfillContactAggregate, {
+            cursor: options?.cursor ?? null,
+            batchSize: options?.batchSize ?? 100,
+            clear: options?.clear,
+        });
+    }
     /**
      * For easy re-exporting.
      * Apps can do
@@ -339,7 +374,7 @@ export class Loops {
                     source: v.optional(v.string()),
                     subscribed: v.optional(v.boolean()),
                     limit: v.optional(v.number()),
-                    offset: v.optional(v.number()),
+                    cursor: v.optional(v.union(v.string(), v.null())),
                 },
                 handler: async (ctx, args) => {
                     return await this.listContacts(ctx, args);
@@ -409,6 +444,16 @@ export class Loops {
                     return await this.checkGlobalRateLimit(ctx, args);
                 },
             }),
+            backfillContactAggregate: mutationGeneric({
+                args: {
+                    cursor: v.optional(v.union(v.string(), v.null())),
+                    batchSize: v.optional(v.number()),
+                    clear: v.optional(v.boolean()),
+                },
+                handler: async (ctx, args) => {
+                    return await this.backfillContactAggregate(ctx, args);
+                },
+            }),
         };
     }
 }