@niama/loops 0.2.0

package/src/client/index.ts

@@ -0,0 +1,618 @@
+import { actionGeneric, mutationGeneric, queryGeneric } from "convex/server";
+import { v } from "convex/values";
+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;
+	lastName?: string;
+	userId?: string;
+	source?: string;
+	subscribed?: boolean;
+	userGroup?: string;
+}
+
+export interface TransactionalEmailOptions {
+	transactionalId: string;
+	email: string;
+	dataVariables?: Record<string, unknown>;
+	idempotencyKey?: string;
+}
+
+export interface EventOptions {
+	email: string;
+	eventName: string;
+	eventProperties?: Record<string, unknown>;
+}
+
+export class Loops {
+	public readonly options?: {
+		apiKey?: string;
+	};
+	private readonly actions: NonNullable<LoopsComponent["actions"]>;
+	private readonly queries: NonNullable<LoopsComponent["queries"]>;
+	private readonly mutations: NonNullable<LoopsComponent["mutations"]>;
+	private _apiKey?: string;
+
+	constructor(
+		component: LoopsComponent,
+		options?: {
+			apiKey?: string;
+		},
+	) {
+		if (!component) {
+			throw new Error(
+				"Loops component reference is required. " +
+					"Make sure the component is mounted in your convex.config.ts and use: " +
+					"new Loops(components.loops)",
+			);
+		}
+
+		if (!component.actions || !component.queries || !component.mutations) {
+			throw new Error(
+				"Invalid component reference. " +
+					"The component may not be properly mounted. " +
+					"Ensure the component is correctly mounted in convex.config.ts: " +
+					"app.use(loops);",
+			);
+		}
+
+		this.actions = component.actions;
+		this.queries = component.queries;
+		this.mutations = component.mutations;
+		this.options = options;
+		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.",
+			);
+		}
+	}
+
+	/**
+	 * 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
+	 */
+	async addContact(ctx: RunActionCtx, contact: ContactData) {
+		return ctx.runAction(this.actions.addContact, {
+			apiKey: this.apiKey,
+			contact,
+		});
+	}
+
+	/**
+	 * Update an existing contact in Loops
+	 */
+	async updateContact(
+		ctx: RunActionCtx,
+		email: string,
+		updates: Partial<ContactData> & {
+			dataVariables?: Record<string, unknown>;
+		},
+	) {
+		return ctx.runAction(this.actions.updateContact, {
+			apiKey: this.apiKey,
+			email,
+			...updates,
+		});
+	}
+
+	/**
+	 * Send a transactional email using a transactional ID
+	 */
+	async sendTransactional(
+		ctx: RunActionCtx,
+		options: TransactionalEmailOptions,
+	) {
+		return ctx.runAction(this.actions.sendTransactional, {
+			apiKey: this.apiKey,
+			...options,
+		});
+	}
+
+	/**
+	 * Send an event to Loops to trigger email workflows
+	 */
+	async sendEvent(ctx: RunActionCtx, options: EventOptions) {
+		return ctx.runAction(this.actions.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.actions.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.actions.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.actions.unsubscribeContact, {
+			apiKey: this.apiKey,
+			email,
+		});
+	}
+
+	/**
+	 * Resubscribe a contact
+	 * Resubscribes a previously unsubscribed contact
+	 */
+	async resubscribeContact(ctx: RunActionCtx, email: string) {
+		return ctx.runAction(this.actions.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.queries.countContacts, options ?? {});
+	}
+
+	/**
+	 * 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,
+		options?: {
+			userGroup?: string;
+			source?: string;
+			subscribed?: boolean;
+			limit?: number;
+			cursor?: string | null;
+		},
+	) {
+		return ctx.runQuery(this.queries.listContacts, {
+			userGroup: options?.userGroup,
+			source: options?.source,
+			subscribed: options?.subscribed,
+			limit: options?.limit ?? 100,
+			cursor: options?.cursor ?? null,
+		});
+	}
+
+	/**
+	 * Detect spam patterns: emails sent to the same recipient too frequently
+	 */
+	async detectRecipientSpam(
+		ctx: RunQueryCtx,
+		options?: {
+			timeWindowMs?: number;
+			maxEmailsPerRecipient?: number;
+		},
+	) {
+		return ctx.runQuery(this.queries.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.queries.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.queries.getEmailStats, {
+			timeWindowMs: options?.timeWindowMs ?? 86400000,
+		});
+	}
+
+	/**
+	 * Detect rapid-fire email sending patterns
+	 */
+	async detectRapidFirePatterns(
+		ctx: RunQueryCtx,
+		options?: {
+			timeWindowMs?: number;
+			minEmailsInWindow?: number;
+		},
+	) {
+		return ctx.runQuery(this.queries.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.queries.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.queries.checkActorRateLimit, options);
+	}
+
+	/**
+	 * Check global email sending rate limit
+	 */
+	async checkGlobalRateLimit(
+		ctx: RunQueryCtx,
+		options: {
+			timeWindowMs: number;
+			maxEmails: number;
+		},
+	) {
+		return ctx.runQuery(this.queries.checkGlobalRateLimit, options);
+	}
+
+	/**
+	 * Delete a contact from Loops
+	 */
+	async deleteContact(ctx: RunActionCtx, email: string) {
+		return ctx.runAction(this.actions.deleteContact, {
+			apiKey: this.apiKey,
+			email,
+		});
+	}
+
+	/**
+	 * Trigger a loop for a contact
+	 * Loops are automated email sequences that can be triggered by events
+	 *
+	 * Note: Loops.so doesn't have a direct loop trigger endpoint.
+	 * Loops are triggered through events. Make sure your loop is configured
+	 * in the Loops dashboard to listen for events.
+	 *
+	 * @param options.eventName - Optional event name. If not provided, uses `loop_{loopId}`
+	 */
+	async triggerLoop(
+		ctx: RunActionCtx,
+		options: {
+			loopId: string;
+			email: string;
+			dataVariables?: Record<string, unknown>;
+			eventName?: string; // Event name that triggers the loop
+		},
+	) {
+		return ctx.runAction(this.actions.triggerLoop, {
+			apiKey: this.apiKey,
+			...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: RunMutationCtx,
+		options?: {
+			cursor?: string | null;
+			batchSize?: number;
+			clear?: boolean;
+		},
+	) {
+		return ctx.runMutation(this.mutations.backfillContactAggregate, {
+			cursor: options?.cursor ?? null,
+			batchSize: options?.batchSize ?? 100,
+			clear: options?.clear,
+		});
+	}
+
+	/**
+	 * For easy re-exporting.
+	 * Apps can do
+	 * ```ts
+	 * export const { addContact, sendTransactional, sendEvent, 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()),
+					idempotencyKey: v.optional(v.string()),
+				},
+				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);
+				},
+			}),
+			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);
+				},
+			}),
+			listContacts: queryGeneric({
+				args: {
+					userGroup: v.optional(v.string()),
+					source: v.optional(v.string()),
+					subscribed: v.optional(v.boolean()),
+					limit: v.optional(v.number()),
+					cursor: v.optional(v.union(v.string(), v.null())),
+				},
+				handler: async (ctx, args) => {
+					return await this.listContacts(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);
+				},
+			}),
+			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);
+				},
+			}),
+		};
+	}
+}