@devwithbobby/loops 0.1.18 → 0.2.0

package/src/client/index.ts

@@ -1,9 +1,9 @@
-import { actionGeneric, queryGeneric } from "convex/server";
+import { actionGeneric, mutationGeneric, queryGeneric } from "convex/server";
 import { v } from "convex/values";
-import type { Mounts } from "../component/_generated/api";
-import type { RunActionCtx, RunQueryCtx, UseApi } from "../types";
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { RunActionCtx, RunMutationCtx, RunQueryCtx } from "../types";
 
-export type LoopsComponent = UseApi<Mounts>;
+export type LoopsComponent = ComponentApi;
 
 export interface ContactData {
 	email: string;
@@ -32,6 +32,7 @@ export class Loops {
 		apiKey?: string;
 	};
 	private readonly lib: NonNullable<LoopsComponent["lib"]>;
+	private _apiKey?: string;
 
 	constructor(
 		component: LoopsComponent,
@@ -58,13 +59,7 @@ 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(
@@ -73,11 +68,21 @@ export class Loops {
 					"See README.md for details.",
 			);
 		}
-
-		this.apiKey = apiKey;
 	}
 
-	private readonly apiKey: string;
+	/**
+	 * 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(): string {
+		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
@@ -190,9 +195,12 @@ export class Loops {
 	}
 
 	/**
-	 * 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: RunQueryCtx,
@@ -201,7 +209,7 @@ export class Loops {
 			source?: string;
 			subscribed?: boolean;
 			limit?: number;
-			offset?: number;
+			cursor?: string | null;
 		},
 	) {
 		return ctx.runQuery(this.lib.listContacts, {
@@ -209,7 +217,7 @@ export class Loops {
 			source: options?.source,
 			subscribed: options?.subscribed,
 			limit: options?.limit ?? 100,
-			offset: options?.offset ?? 0,
+			cursor: options?.cursor ?? null,
 		});
 	}
 
@@ -351,6 +359,39 @@ export class Loops {
 		});
 	}
 
+	/**
+	 * 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: RunMutationCtx,
+		options?: {
+			cursor?: string | null;
+			batchSize?: number;
+			clear?: boolean;
+		},
+	) {
+		return ctx.runMutation(this.lib.backfillContactAggregate, {
+			cursor: options?.cursor ?? null,
+			batchSize: options?.batchSize ?? 100,
+			clear: options?.clear,
+		});
+	}
+
 	/**
 	 * For easy re-exporting.
 	 * Apps can do
@@ -486,7 +527,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);
@@ -556,6 +597,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);
+				},
+			}),
 		};
 	}
 }

package/src/component/_generated/api.ts

@@ -0,0 +1,249 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as aggregates from "../aggregates.js";
+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";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  aggregates: typeof aggregates;
+  helpers: typeof helpers;
+  http: typeof http;
+  lib: typeof lib;
+  "tables/contacts": typeof tables_contacts;
+  "tables/emailOperations": typeof tables_emailOperations;
+  validators: typeof validators;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {
+  contactAggregate: {
+    btree: {
+      aggregateBetween: FunctionReference<
+        "query",
+        "internal",
+        { k1?: any; k2?: any; namespace?: any },
+        { count: number; sum: number }
+      >;
+      aggregateBetweenBatch: FunctionReference<
+        "query",
+        "internal",
+        { queries: Array<{ k1?: any; k2?: any; namespace?: any }> },
+        Array<{ count: number; sum: number }>
+      >;
+      atNegativeOffset: FunctionReference<
+        "query",
+        "internal",
+        { k1?: any; k2?: any; namespace?: any; offset: number },
+        { k: any; s: number; v: any }
+      >;
+      atOffset: FunctionReference<
+        "query",
+        "internal",
+        { k1?: any; k2?: any; namespace?: any; offset: number },
+        { k: any; s: number; v: any }
+      >;
+      atOffsetBatch: FunctionReference<
+        "query",
+        "internal",
+        {
+          queries: Array<{
+            k1?: any;
+            k2?: any;
+            namespace?: any;
+            offset: number;
+          }>;
+        },
+        Array<{ k: any; s: number; v: any }>
+      >;
+      get: FunctionReference<
+        "query",
+        "internal",
+        { key: any; namespace?: any },
+        null | { k: any; s: number; v: any }
+      >;
+      offset: FunctionReference<
+        "query",
+        "internal",
+        { k1?: any; key: any; namespace?: any },
+        number
+      >;
+      offsetUntil: FunctionReference<
+        "query",
+        "internal",
+        { k2?: any; key: any; namespace?: any },
+        number
+      >;
+      paginate: FunctionReference<
+        "query",
+        "internal",
+        {
+          cursor?: string;
+          k1?: any;
+          k2?: any;
+          limit: number;
+          namespace?: any;
+          order: "asc" | "desc";
+        },
+        {
+          cursor: string;
+          isDone: boolean;
+          page: Array<{ k: any; s: number; v: any }>;
+        }
+      >;
+      paginateNamespaces: FunctionReference<
+        "query",
+        "internal",
+        { cursor?: string; limit: number },
+        { cursor: string; isDone: boolean; page: Array<any> }
+      >;
+      validate: FunctionReference<
+        "query",
+        "internal",
+        { namespace?: any },
+        any
+      >;
+    };
+    inspect: {
+      display: FunctionReference<"query", "internal", { namespace?: any }, any>;
+      dump: FunctionReference<"query", "internal", { namespace?: any }, string>;
+      inspectNode: FunctionReference<
+        "query",
+        "internal",
+        { namespace?: any; node?: string },
+        null
+      >;
+      listTreeNodes: FunctionReference<
+        "query",
+        "internal",
+        { take?: number },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          aggregate?: { count: number; sum: number };
+          items: Array<{ k: any; s: number; v: any }>;
+          subtrees: Array<string>;
+        }>
+      >;
+      listTrees: FunctionReference<
+        "query",
+        "internal",
+        { take?: number },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          maxNodeSize: number;
+          namespace?: any;
+          root: string;
+        }>
+      >;
+    };
+    public: {
+      clear: FunctionReference<
+        "mutation",
+        "internal",
+        { maxNodeSize?: number; namespace?: any; rootLazy?: boolean },
+        null
+      >;
+      delete_: FunctionReference<
+        "mutation",
+        "internal",
+        { key: any; namespace?: any },
+        null
+      >;
+      deleteIfExists: FunctionReference<
+        "mutation",
+        "internal",
+        { key: any; namespace?: any },
+        any
+      >;
+      init: FunctionReference<
+        "mutation",
+        "internal",
+        { maxNodeSize?: number; namespace?: any; rootLazy?: boolean },
+        null
+      >;
+      insert: FunctionReference<
+        "mutation",
+        "internal",
+        { key: any; namespace?: any; summand?: number; value: any },
+        null
+      >;
+      makeRootLazy: FunctionReference<
+        "mutation",
+        "internal",
+        { namespace?: any },
+        null
+      >;
+      replace: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          currentKey: any;
+          namespace?: any;
+          newKey: any;
+          newNamespace?: any;
+          summand?: number;
+          value: any;
+        },
+        null
+      >;
+      replaceOrInsert: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          currentKey: any;
+          namespace?: any;
+          newKey: any;
+          newNamespace?: any;
+          summand?: number;
+          value: any;
+        },
+        any
+      >;
+    };
+  };
+};