@devwithbobby/loops 0.1.17 → 0.1.19

package/src/component/_generated/component.ts

@@ -0,0 +1,323 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    lib: {
+      addContact: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          contact: {
+            email: string;
+            firstName?: string;
+            lastName?: string;
+            source?: string;
+            subscribed?: boolean;
+            userGroup?: string;
+            userId?: string;
+          };
+        },
+        { id?: string; success: boolean },
+        Name
+      >;
+      batchCreateContacts: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          contacts: Array<{
+            email: string;
+            firstName?: string;
+            lastName?: string;
+            source?: string;
+            subscribed?: boolean;
+            userGroup?: string;
+            userId?: string;
+          }>;
+        },
+        {
+          created?: number;
+          failed?: number;
+          results?: Array<{ email: string; error?: string; success: boolean }>;
+          success: boolean;
+        },
+        Name
+      >;
+      checkActorRateLimit: FunctionReference<
+        "query",
+        "internal",
+        { actorId: string; maxEmails: number; timeWindowMs: number },
+        {
+          allowed: boolean;
+          count: number;
+          limit: number;
+          retryAfter?: number;
+          timeWindowMs: number;
+        },
+        Name
+      >;
+      checkGlobalRateLimit: FunctionReference<
+        "query",
+        "internal",
+        { maxEmails: number; timeWindowMs: number },
+        {
+          allowed: boolean;
+          count: number;
+          limit: number;
+          timeWindowMs: number;
+        },
+        Name
+      >;
+      checkRecipientRateLimit: FunctionReference<
+        "query",
+        "internal",
+        { email: string; maxEmails: number; timeWindowMs: number },
+        {
+          allowed: boolean;
+          count: number;
+          limit: number;
+          retryAfter?: number;
+          timeWindowMs: number;
+        },
+        Name
+      >;
+      countContacts: FunctionReference<
+        "query",
+        "internal",
+        { source?: string; subscribed?: boolean; userGroup?: string },
+        number,
+        Name
+      >;
+      deleteContact: FunctionReference<
+        "action",
+        "internal",
+        { apiKey: string; email: string },
+        { success: boolean },
+        Name
+      >;
+      detectActorSpam: FunctionReference<
+        "query",
+        "internal",
+        { maxEmailsPerActor?: number; timeWindowMs?: number },
+        Array<{ actorId: string; count: number; timeWindowMs: number }>,
+        Name
+      >;
+      detectRapidFirePatterns: FunctionReference<
+        "query",
+        "internal",
+        { minEmailsInWindow?: number; timeWindowMs?: number },
+        Array<{
+          actorId?: string;
+          count: number;
+          email?: string;
+          firstTimestamp: number;
+          lastTimestamp: number;
+          timeWindowMs: number;
+        }>,
+        Name
+      >;
+      detectRecipientSpam: FunctionReference<
+        "query",
+        "internal",
+        { maxEmailsPerRecipient?: number; timeWindowMs?: number },
+        Array<{ count: number; email: string; timeWindowMs: number }>,
+        Name
+      >;
+      findContact: FunctionReference<
+        "action",
+        "internal",
+        { apiKey: string; email: string },
+        {
+          contact?: {
+            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;
+        },
+        Name
+      >;
+      getEmailStats: FunctionReference<
+        "query",
+        "internal",
+        { timeWindowMs?: number },
+        {
+          failedOperations: number;
+          operationsByType: Record<string, number>;
+          successfulOperations: number;
+          totalOperations: number;
+          uniqueActors: number;
+          uniqueRecipients: number;
+        },
+        Name
+      >;
+      listContacts: FunctionReference<
+        "query",
+        "internal",
+        {
+          limit?: number;
+          offset?: number;
+          source?: string;
+          subscribed?: boolean;
+          userGroup?: string;
+        },
+        {
+          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;
+        },
+        Name
+      >;
+      logEmailOperation: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          actorId?: string;
+          campaignId?: string;
+          email: string;
+          eventName?: string;
+          loopId?: string;
+          messageId?: string;
+          metadata?: Record<string, any>;
+          operationType: "transactional" | "event" | "campaign" | "loop";
+          success: boolean;
+          transactionalId?: string;
+        },
+        any,
+        Name
+      >;
+      removeContact: FunctionReference<
+        "mutation",
+        "internal",
+        { email: string },
+        any,
+        Name
+      >;
+      resubscribeContact: FunctionReference<
+        "action",
+        "internal",
+        { apiKey: string; email: string },
+        { success: boolean },
+        Name
+      >;
+      sendEvent: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          email: string;
+          eventName: string;
+          eventProperties?: Record<string, any>;
+        },
+        { success: boolean },
+        Name
+      >;
+      sendTransactional: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          dataVariables?: Record<string, any>;
+          email: string;
+          transactionalId: string;
+        },
+        { messageId?: string; success: boolean },
+        Name
+      >;
+      storeContact: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          email: string;
+          firstName?: string;
+          lastName?: string;
+          loopsContactId?: string;
+          source?: string;
+          subscribed?: boolean;
+          userGroup?: string;
+          userId?: string;
+        },
+        any,
+        Name
+      >;
+      triggerLoop: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          dataVariables?: Record<string, any>;
+          email: string;
+          eventName?: string;
+          loopId: string;
+        },
+        { success: boolean; warning?: string },
+        Name
+      >;
+      unsubscribeContact: FunctionReference<
+        "action",
+        "internal",
+        { apiKey: string; email: string },
+        { success: boolean },
+        Name
+      >;
+      updateContact: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          dataVariables?: Record<string, any>;
+          email: string;
+          firstName?: string;
+          lastName?: string;
+          source?: string;
+          subscribed?: boolean;
+          userGroup?: string;
+          userId?: string;
+        },
+        { success: boolean },
+        Name
+      >;
+    };
+  };

package/src/component/_generated/{dataModel.d.ts → dataModel.ts}

@@ -38,7 +38,7 @@ export type Doc<TableName extends TableNames> = DocumentByName<
  * Convex documents are uniquely identified by their `Id`, which is accessible
  * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
  *
- * Documents can be loaded using `db.get(id)` in query and mutation functions.
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
  *
  * IDs are just strings at runtime, but this type can be used to distinguish them from other
  * strings when type checking.

package/src/component/_generated/server.ts

@@ -0,0 +1,161 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+type GenericCtx =
+  | GenericActionCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -1,32 +1,5 @@
 import { defineComponent } from "convex/server";
-import { api } from "./_generated/api";
 
 const component = defineComponent("loops");
 
-type ExportableComponent = typeof component & {
-	export: (apiRef: typeof api, functions: Record<string, unknown>) => void;
-};
-
-(component as ExportableComponent).export(api, {
-	addContact: api.lib.addContact,
-	updateContact: api.lib.updateContact,
-	findContact: api.lib.findContact,
-	batchCreateContacts: api.lib.batchCreateContacts,
-	unsubscribeContact: api.lib.unsubscribeContact,
-	resubscribeContact: api.lib.resubscribeContact,
-	countContacts: api.lib.countContacts,
-	listContacts: api.lib.listContacts,
-	sendTransactional: api.lib.sendTransactional,
-	sendEvent: api.lib.sendEvent,
-	triggerLoop: api.lib.triggerLoop,
-	deleteContact: api.lib.deleteContact,
-	detectRecipientSpam: api.lib.detectRecipientSpam,
-	detectActorSpam: api.lib.detectActorSpam,
-	getEmailStats: api.lib.getEmailStats,
-	detectRapidFirePatterns: api.lib.detectRapidFirePatterns,
-	checkRecipientRateLimit: api.lib.checkRecipientRateLimit,
-	checkActorRateLimit: api.lib.checkActorRateLimit,
-	checkGlobalRateLimit: api.lib.checkGlobalRateLimit,
-});
-
 export default component;

package/src/component/helpers.ts

@@ -1,4 +1,4 @@
-import { type HeadersInitParam } from "../types";
+import type { HeadersInitParam } from "../types";
 
 const allowedOrigin =
 	process.env.CONVEX_URL ??
@@ -82,7 +82,7 @@ export const emptyResponse = (init?: ResponseInit) => {
 export const readJsonBody = async <T>(request: Request): Promise<T> => {
 	try {
 		return (await request.json()) as T;
-	} catch (error) {
+	} catch (_error) {
 		throw new Error("Invalid JSON body");
 	}
 };

package/src/component/http.ts

@@ -22,10 +22,6 @@ import { httpAction } from "./_generated/server";
 
 const http = httpRouter();
 
-const allowedOrigin =
-	process.env.LOOPS_HTTP_ALLOWED_ORIGIN ?? process.env.CLIENT_ORIGIN ?? "*";
-
-
 http.route({
 	pathPrefix: "/loops/",
 	method: "OPTIONS",

package/src/component/lib.ts

@@ -117,6 +117,10 @@ export const logEmailOperation = zm({
 /**
  * Count contacts in the database
  * Can filter by audience criteria (userGroup, source, subscribed status)
+ *
+ * Note: When multiple filters are provided, only one index can be used.
+ * Additional filters are applied in-memory, which is efficient for small result sets.
+ * For large contact lists with multiple filters, consider using a composite index.
  */
 export const countContacts = zq({
 	args: z.object({
@@ -126,7 +130,10 @@ export const countContacts = zq({
 	}),
 	returns: z.number(),
 	handler: async (ctx, args) => {
+		// Build query using the most selective index available
+		// Priority: userGroup > source > subscribed
 		let contacts: Doc<"contacts">[];
+
 		if (args.userGroup !== undefined) {
 			contacts = await ctx.db
 				.query("contacts")
@@ -146,17 +153,32 @@ export const countContacts = zq({
 			contacts = await ctx.db.query("contacts").collect();
 		}
 
-		if (args.userGroup !== undefined && contacts) {
-			contacts = contacts.filter((c) => c.userGroup === args.userGroup);
-		}
-		if (args.source !== undefined && contacts) {
-			contacts = contacts.filter((c) => c.source === args.source);
-		}
-		if (args.subscribed !== undefined && contacts) {
-			contacts = contacts.filter((c) => c.subscribed === args.subscribed);
+		// Apply additional filters if multiple criteria were provided
+		// This avoids redundant filtering when only one filter was used
+		const needsFiltering =
+			(args.userGroup !== undefined ? 1 : 0) +
+				(args.source !== undefined ? 1 : 0) +
+				(args.subscribed !== undefined ? 1 : 0) >
+			1;
+
+		if (!needsFiltering) {
+			return contacts.length;
 		}
 
-		return contacts.length;
+		const filtered = contacts.filter((c) => {
+			if (args.userGroup !== undefined && c.userGroup !== args.userGroup) {
+				return false;
+			}
+			if (args.source !== undefined && c.source !== args.source) {
+				return false;
+			}
+			if (args.subscribed !== undefined && c.subscribed !== args.subscribed) {
+				return false;
+			}
+			return true;
+		});
+
+		return filtered.length;
 	},
 });
 
@@ -164,6 +186,9 @@ export const countContacts = zq({
  * List contacts from the database with pagination
  * Can filter by audience criteria (userGroup, source, subscribed status)
  * Returns actual contact data, not just a count
+ *
+ * Note: When multiple filters are provided, only one index can be used.
+ * Additional filters are applied in-memory before pagination.
  */
 export const listContacts = zq({
 	args: z.object({
@@ -195,9 +220,9 @@ export const listContacts = zq({
 		hasMore: z.boolean(),
 	}),
 	handler: async (ctx, args) => {
+		// Build query using the most selective index available
 		let allContacts: Doc<"contacts">[];
 
-		// Get all contacts matching the filters
 		if (args.userGroup !== undefined) {
 			allContacts = await ctx.db
 				.query("contacts")
@@ -217,15 +242,26 @@ export const listContacts = zq({
 			allContacts = await ctx.db.query("contacts").collect();
 		}
 
-		// Apply additional filters (for cases where we need to filter by multiple criteria)
-		if (args.userGroup !== undefined && allContacts) {
-			allContacts = allContacts.filter((c) => c.userGroup === args.userGroup);
-		}
-		if (args.source !== undefined && allContacts) {
-			allContacts = allContacts.filter((c) => c.source === args.source);
-		}
-		if (args.subscribed !== undefined && allContacts) {
-			allContacts = allContacts.filter((c) => c.subscribed === args.subscribed);
+		// Apply additional filters if multiple criteria were provided
+		const needsFiltering =
+			(args.userGroup !== undefined ? 1 : 0) +
+				(args.source !== undefined ? 1 : 0) +
+				(args.subscribed !== undefined ? 1 : 0) >
+			1;
+
+		if (needsFiltering) {
+			allContacts = allContacts.filter((c) => {
+				if (args.userGroup !== undefined && c.userGroup !== args.userGroup) {
+					return false;
+				}
+				if (args.source !== undefined && c.source !== args.source) {
+					return false;
+				}
+				if (args.subscribed !== undefined && c.subscribed !== args.subscribed) {
+					return false;
+				}
+				return true;
+			});
 		}
 
 		// Sort by createdAt (newest first)
@@ -488,7 +524,7 @@ export const sendEvent = za({
 	returns: z.object({
 		success: z.boolean(),
 	}),
-	handler: async (_ctx, args) => {
+	handler: async (ctx, args) => {
 		const response = await loopsFetch(args.apiKey, "/events/send", {
 			method: "POST",
 			json: {
@@ -501,9 +537,22 @@ export const sendEvent = za({
 		if (!response.ok) {
 			const errorText = await response.text();
 			console.error(`Loops API error [${response.status}]:`, errorText);
+			await ctx.runMutation(internalLib.logEmailOperation, {
+				operationType: "event",
+				email: args.email,
+				success: false,
+				eventName: args.eventName,
+			});
 			throw sanitizeLoopsError(response.status, errorText);
 		}
 
+		await ctx.runMutation(internalLib.logEmailOperation, {
+			operationType: "event",
+			email: args.email,
+			success: true,
+			eventName: args.eventName,
+		});
+
 		return { success: true };
 	},
 });