@devwithbobby/loops 0.1.0

package/src/client/index.ts

@@ -0,0 +1,530 @@
+import { actionGeneric, queryGeneric } from "convex/server";
+import { v } from "convex/values";
+import type { Mounts } from "../component/_generated/api.js";
+import type { RunActionCtx, RunQueryCtx, UseApi } from "./types.js";
+
+export type LoopsComponent = UseApi<Mounts>;
+
+export interface ContactData {
+	email: string;
+	firstName?: string;
+	lastName?: string;
+	userId?: string;
+	source?: string;
+	subscribed?: boolean;
+	userGroup?: string;
+}
+
+export interface TransactionalEmailOptions {
+	transactionalId: string;
+	email: string;
+	dataVariables?: Record<string, any>;
+}
+
+export interface EventOptions {
+	email: string;
+	eventName: string;
+	eventProperties?: Record<string, any>;
+}
+
+export class Loops {
+	constructor(
+		public component: LoopsComponent,
+		public options?: {
+			apiKey?: string;
+		},
+	) {
+		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."
+			);
+		}
+
+		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.",
+			);
+		}
+
+		this.apiKey = apiKey;
+	}
+
+	private readonly apiKey: string;
+
+	/**
+	 * Add or update a contact in Loops
+	 */
+	async addContact(ctx: RunActionCtx, contact: ContactData) {
+		return ctx.runAction((this.component.lib as any).addContact, {
+			apiKey: this.apiKey,
+			contact,
+		});
+	}
+
+	/**
+	 * Update an existing contact in Loops
+	 */
+	async updateContact(
+		ctx: RunActionCtx,
+		email: string,
+		updates: Partial<ContactData> & {
+			dataVariables?: Record<string, any>;
+		},
+	) {
+		return ctx.runAction((this.component.lib as any).updateContact, {
+			apiKey: this.apiKey,
+			email,
+			...updates,
+		});
+	}
+
+	/**
+	 * Send a transactional email using a transactional ID
+	 */
+	async sendTransactional(ctx: RunActionCtx, options: TransactionalEmailOptions) {
+		return ctx.runAction((this.component.lib as any).sendTransactional, {
+			apiKey: this.apiKey,
+			...options,
+		});
+	}
+
+	/**
+	 * Send an event to Loops to trigger email workflows
+	 */
+	async sendEvent(ctx: RunActionCtx, options: EventOptions) {
+		return ctx.runAction((this.component.lib as any).sendEvent, {
+			apiKey: this.apiKey,
+			...options,
+		});
+	}
+
+	/**
+	 * Find a contact by email
+	 * Retrieves contact information from Loops
+	 */
+	async findContact(ctx: RunActionCtx, email: string) {
+		return ctx.runAction((this.component.lib as any).findContact, {
+			apiKey: this.apiKey,
+			email,
+		});
+	}
+
+	/**
+	 * Batch create contacts
+	 * Create multiple contacts in a single API call
+	 */
+	async batchCreateContacts(ctx: RunActionCtx, contacts: ContactData[]) {
+		return ctx.runAction((this.component.lib as any).batchCreateContacts, {
+			apiKey: this.apiKey,
+			contacts,
+		});
+	}
+
+	/**
+	 * Unsubscribe a contact
+	 * Unsubscribes a contact from receiving emails (they remain in the system)
+	 */
+	async unsubscribeContact(ctx: RunActionCtx, email: string) {
+		return ctx.runAction((this.component.lib as any).unsubscribeContact, {
+			apiKey: this.apiKey,
+			email,
+		});
+	}
+
+	/**
+	 * Resubscribe a contact
+	 * Resubscribes a previously unsubscribed contact
+	 */
+	async resubscribeContact(ctx: RunActionCtx, email: string) {
+		return ctx.runAction((this.component.lib as any).resubscribeContact, {
+			apiKey: this.apiKey,
+			email,
+		});
+	}
+
+	/**
+	 * Count contacts in the database
+	 * Can filter by audience criteria (userGroup, source, subscribed status)
+	 * This queries the component's local database, not Loops API
+	 */
+	async countContacts(
+		ctx: RunQueryCtx,
+		options?: {
+			userGroup?: string;
+			source?: string;
+			subscribed?: boolean;
+		},
+	) {
+		return ctx.runQuery((this.component.lib as any).countContacts, options ?? {});
+	}
+
+	/**
+	 * Detect spam patterns: emails sent to the same recipient too frequently
+	 */
+	async detectRecipientSpam(
+		ctx: RunQueryCtx,
+		options?: {
+			timeWindowMs?: number;
+			maxEmailsPerRecipient?: number;
+		},
+	) {
+		return ctx.runQuery((this.component.lib as any).detectRecipientSpam, {
+			timeWindowMs: options?.timeWindowMs ?? 3600000,
+			maxEmailsPerRecipient: options?.maxEmailsPerRecipient ?? 10,
+		});
+	}
+
+	/**
+	 * Detect spam patterns: emails sent by the same actor/user too frequently
+	 */
+	async detectActorSpam(
+		ctx: RunQueryCtx,
+		options?: {
+			timeWindowMs?: number;
+			maxEmailsPerActor?: number;
+		},
+	) {
+		return ctx.runQuery((this.component.lib as any).detectActorSpam, {
+			timeWindowMs: options?.timeWindowMs ?? 3600000,
+			maxEmailsPerActor: options?.maxEmailsPerActor ?? 100,
+		});
+	}
+
+	/**
+	 * Get email operation statistics for monitoring
+	 */
+	async getEmailStats(
+		ctx: RunQueryCtx,
+		options?: {
+			timeWindowMs?: number;
+		},
+	) {
+		return ctx.runQuery((this.component.lib as any).getEmailStats, {
+			timeWindowMs: options?.timeWindowMs ?? 86400000,
+		});
+	}
+
+	/**
+	 * Detect rapid-fire email sending patterns
+	 */
+	async detectRapidFirePatterns(
+		ctx: RunQueryCtx,
+		options?: {
+			timeWindowMs?: number;
+			minEmailsInWindow?: number;
+		},
+	) {
+		return ctx.runQuery((this.component.lib as any).detectRapidFirePatterns, {
+			timeWindowMs: options?.timeWindowMs ?? 60000,
+			minEmailsInWindow: options?.minEmailsInWindow ?? 5,
+		});
+	}
+
+	/**
+	 * Check if an email can be sent to a recipient based on rate limits
+	 */
+	async checkRecipientRateLimit(
+		ctx: RunQueryCtx,
+		options: {
+			email: string;
+			timeWindowMs: number;
+			maxEmails: number;
+		},
+	) {
+		return ctx.runQuery((this.component.lib as any).checkRecipientRateLimit, options);
+	}
+
+	/**
+	 * Check if an actor/user can send more emails based on rate limits
+	 */
+	async checkActorRateLimit(
+		ctx: RunQueryCtx,
+		options: {
+			actorId: string;
+			timeWindowMs: number;
+			maxEmails: number;
+		},
+	) {
+		return ctx.runQuery((this.component.lib as any).checkActorRateLimit, options);
+	}
+
+	/**
+	 * Check global email sending rate limit
+	 */
+	async checkGlobalRateLimit(
+		ctx: RunQueryCtx,
+		options: {
+			timeWindowMs: number;
+			maxEmails: number;
+		},
+	) {
+		return ctx.runQuery((this.component.lib as any).checkGlobalRateLimit, options);
+	}
+
+	/**
+	 * Delete a contact from Loops
+	 */
+	async deleteContact(ctx: RunActionCtx, email: string) {
+		return ctx.runAction((this.component.lib as any).deleteContact, {
+			apiKey: this.apiKey,
+			email,
+		});
+	}
+
+	/**
+	 * Send a campaign to contacts
+	 * Campaigns are one-time email sends to a segment or list of contacts
+	 */
+	async sendCampaign(
+		ctx: RunActionCtx,
+		options: {
+			campaignId: string;
+			emails?: string[];
+			transactionalId?: string;
+			dataVariables?: Record<string, any>;
+			audienceFilters?: {
+				userGroup?: string;
+				source?: string;
+			};
+		},
+	) {
+		return ctx.runAction((this.component.lib as any).sendCampaign, {
+			apiKey: this.apiKey,
+			...options,
+		});
+	}
+
+	/**
+	 * Trigger a loop for a contact
+	 * Loops are automated email sequences that can be triggered by events
+	 */
+	async triggerLoop(
+		ctx: RunActionCtx,
+		options: {
+			loopId: string;
+			email: string;
+			dataVariables?: Record<string, any>;
+		},
+	) {
+		return ctx.runAction((this.component.lib as any).triggerLoop, {
+			apiKey: this.apiKey,
+			...options,
+		});
+	}
+
+	/**
+	 * For easy re-exporting.
+	 * Apps can do
+	 * ```ts
+	 * export const { addContact, sendTransactional, sendEvent, sendCampaign, triggerLoop } = loops.api();
+	 * ```
+	 */
+	api() {
+		return {
+			addContact: actionGeneric({
+				args: {
+					email: v.string(),
+					firstName: v.optional(v.string()),
+					lastName: v.optional(v.string()),
+					userId: v.optional(v.string()),
+					source: v.optional(v.string()),
+					subscribed: v.optional(v.boolean()),
+					userGroup: v.optional(v.string()),
+				},
+				handler: async (ctx, args) => {
+					return await this.addContact(ctx, args);
+				},
+			}),
+			updateContact: actionGeneric({
+				args: {
+					email: v.string(),
+					firstName: v.optional(v.string()),
+					lastName: v.optional(v.string()),
+					userId: v.optional(v.string()),
+					source: v.optional(v.string()),
+					subscribed: v.optional(v.boolean()),
+					userGroup: v.optional(v.string()),
+					dataVariables: v.optional(v.any()),
+				},
+				handler: async (ctx, args) => {
+					const { email, ...updates } = args;
+					return await this.updateContact(ctx, email, updates);
+				},
+			}),
+			sendTransactional: actionGeneric({
+				args: {
+					transactionalId: v.string(),
+					email: v.string(),
+					dataVariables: v.optional(v.any()),
+				},
+				handler: async (ctx, args) => {
+					return await this.sendTransactional(ctx, args);
+				},
+			}),
+			sendEvent: actionGeneric({
+				args: {
+					email: v.string(),
+					eventName: v.string(),
+					eventProperties: v.optional(v.any()),
+				},
+				handler: async (ctx, args) => {
+					return await this.sendEvent(ctx, args);
+				},
+			}),
+			deleteContact: actionGeneric({
+				args: {
+					email: v.string(),
+				},
+				handler: async (ctx, args) => {
+					return await this.deleteContact(ctx, args.email);
+				},
+			}),
+			sendCampaign: actionGeneric({
+				args: {
+					campaignId: v.string(),
+					emails: v.optional(v.array(v.string())),
+					transactionalId: v.optional(v.string()),
+					dataVariables: v.optional(v.any()),
+					audienceFilters: v.optional(
+						v.object({
+							userGroup: v.optional(v.string()),
+							source: v.optional(v.string()),
+						}),
+					),
+				},
+				handler: async (ctx, args) => {
+					return await this.sendCampaign(ctx, args);
+				},
+			}),
+			triggerLoop: actionGeneric({
+				args: {
+					loopId: v.string(),
+					email: v.string(),
+					dataVariables: v.optional(v.any()),
+				},
+				handler: async (ctx, args) => {
+					return await this.triggerLoop(ctx, args);
+				},
+			}),
+			findContact: actionGeneric({
+				args: {
+					email: v.string(),
+				},
+				handler: async (ctx, args) => {
+					return await this.findContact(ctx, args.email);
+				},
+			}),
+			batchCreateContacts: actionGeneric({
+				args: {
+					contacts: v.array(
+						v.object({
+							email: v.string(),
+							firstName: v.optional(v.string()),
+							lastName: v.optional(v.string()),
+							userId: v.optional(v.string()),
+							source: v.optional(v.string()),
+							subscribed: v.optional(v.boolean()),
+							userGroup: v.optional(v.string()),
+						}),
+					),
+				},
+				handler: async (ctx, args) => {
+					return await this.batchCreateContacts(ctx, args.contacts);
+				},
+			}),
+			unsubscribeContact: actionGeneric({
+				args: {
+					email: v.string(),
+				},
+				handler: async (ctx, args) => {
+					return await this.unsubscribeContact(ctx, args.email);
+				},
+			}),
+			resubscribeContact: actionGeneric({
+				args: {
+					email: v.string(),
+				},
+				handler: async (ctx, args) => {
+					return await this.resubscribeContact(ctx, args.email);
+				},
+			}),
+			countContacts: queryGeneric({
+				args: {
+					userGroup: v.optional(v.string()),
+					source: v.optional(v.string()),
+					subscribed: v.optional(v.boolean()),
+				},
+				handler: async (ctx, args) => {
+					return await this.countContacts(ctx, args);
+				},
+			}),
+			detectRecipientSpam: queryGeneric({
+				args: {
+					timeWindowMs: v.optional(v.number()),
+					maxEmailsPerRecipient: v.optional(v.number()),
+				},
+				handler: async (ctx, args) => {
+					return await this.detectRecipientSpam(ctx, args);
+				},
+			}),
+			detectActorSpam: queryGeneric({
+				args: {
+					timeWindowMs: v.optional(v.number()),
+					maxEmailsPerActor: v.optional(v.number()),
+				},
+				handler: async (ctx, args) => {
+					return await this.detectActorSpam(ctx, args);
+				},
+			}),
+			getEmailStats: queryGeneric({
+				args: {
+					timeWindowMs: v.optional(v.number()),
+				},
+				handler: async (ctx, args) => {
+					return await this.getEmailStats(ctx, args);
+				},
+			}),
+			detectRapidFirePatterns: queryGeneric({
+				args: {
+					timeWindowMs: v.optional(v.number()),
+					minEmailsInWindow: v.optional(v.number()),
+				},
+				handler: async (ctx, args) => {
+					return await this.detectRapidFirePatterns(ctx, args);
+				},
+			}),
+			checkRecipientRateLimit: queryGeneric({
+				args: {
+					email: v.string(),
+					timeWindowMs: v.number(),
+					maxEmails: v.number(),
+				},
+				handler: async (ctx, args) => {
+					return await this.checkRecipientRateLimit(ctx, args);
+				},
+			}),
+			checkActorRateLimit: queryGeneric({
+				args: {
+					actorId: v.string(),
+					timeWindowMs: v.number(),
+					maxEmails: v.number(),
+				},
+				handler: async (ctx, args) => {
+					return await this.checkActorRateLimit(ctx, args);
+				},
+			}),
+			checkGlobalRateLimit: queryGeneric({
+				args: {
+					timeWindowMs: v.number(),
+					maxEmails: v.number(),
+				},
+				handler: async (ctx, args) => {
+					return await this.checkGlobalRateLimit(ctx, args);
+				},
+			}),
+		};
+	}
+}

package/src/client/types.ts

@@ -0,0 +1,64 @@
+import type {
+	Expand,
+	FunctionArgs,
+	FunctionReference,
+	FunctionReturnType,
+	StorageActionWriter,
+	StorageReader,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+
+export type RunQueryCtx = {
+	runQuery: <Query extends FunctionReference<"query", "internal">>(
+		query: Query,
+		args: FunctionArgs<Query>,
+	) => Promise<FunctionReturnType<Query>>;
+};
+export type RunMutationCtx = RunQueryCtx & {
+	runMutation: <Mutation extends FunctionReference<"mutation", "internal">>(
+		mutation: Mutation,
+		args: FunctionArgs<Mutation>,
+	) => Promise<FunctionReturnType<Mutation>>;
+};
+export type RunActionCtx = RunMutationCtx & {
+	runAction<Action extends FunctionReference<"action", "internal">>(
+		action: Action,
+		args: FunctionArgs<Action>,
+	): Promise<FunctionReturnType<Action>>;
+};
+export type ActionCtx = RunActionCtx & {
+	storage: StorageActionWriter;
+};
+export type QueryCtx = RunQueryCtx & {
+	storage: StorageReader;
+};
+
+export type OpaqueIds<T> = T extends GenericId<infer _T>
+	? string
+	: T extends (infer U)[]
+		? OpaqueIds<U>[]
+		: T extends ArrayBuffer
+			? ArrayBuffer
+			: T extends object
+				? {
+						[K in keyof T]: OpaqueIds<T[K]>;
+					}
+				: T;
+
+export type UseApi<API> = Expand<{
+	[mod in keyof API]: API[mod] extends FunctionReference<
+		infer FType,
+		"public",
+		infer FArgs,
+		infer FReturnType,
+		infer FComponentPath
+	>
+		? FunctionReference<
+				FType,
+				"internal",
+				OpaqueIds<FArgs>,
+				OpaqueIds<FReturnType>,
+				FComponentPath
+			>
+		: UseApi<API[mod]>;
+}>;

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

@@ -0,0 +1,55 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as lib from "../lib.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+declare const fullApi: ApiFromModules<{
+  lib: typeof lib;
+}>;
+export type Mounts = {
+  lib: {
+    add: FunctionReference<
+      "mutation",
+      "public",
+      { count: number; name: string; shards?: number },
+      null
+    >;
+    count: FunctionReference<"query", "public", { name: string }, number>;
+  };
+};
+// For now fullApiWithMounts is only fullApi which provides
+// jump-to-definition in component client code.
+// Use Mounts for the same type without the inference.
+declare const fullApiWithMounts: typeof fullApi;
+
+export declare const api: FilterApi<
+  typeof fullApiWithMounts,
+  FunctionReference<any, "public">
+>;
+export declare const internal: FilterApi<
+  typeof fullApiWithMounts,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {};

package/src/component/_generated/api.js

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();