@niama/loops 0.2.0

package/src/component/aggregates.ts

@@ -0,0 +1,89 @@
+import { TableAggregate } from "@convex-dev/aggregate";
+import type { GenericMutationCtx, GenericQueryCtx } from "convex/server";
+import type { DataModel, Doc } from "./_generated/dataModel";
+import { components } from "./_generated/api";
+
+// Cast components to the expected type for the aggregate library
+// biome-ignore lint/suspicious/noExplicitAny: Component API type mismatch with aggregate library
+const contactAggregateComponent = components.contactAggregate as any;
+
+/**
+ * Aggregate for counting contacts.
+ * Uses userGroup as namespace for efficient filtered counting.
+ * Key is null since we only need counts, not ordering.
+ */
+export const contactAggregate = new TableAggregate<{
+	Namespace: string | undefined;
+	Key: null;
+	DataModel: DataModel;
+	TableName: "contacts";
+}>(contactAggregateComponent, {
+	namespace: (doc) => doc.userGroup,
+	sortKey: () => null,
+});
+
+type MutationCtx = GenericMutationCtx<DataModel>;
+type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * Insert a contact into the aggregate
+ */
+export async function aggregateInsert(
+	ctx: MutationCtx,
+	doc: Doc<"contacts">,
+): Promise<void> {
+	await contactAggregate.insertIfDoesNotExist(ctx, doc);
+}
+
+/**
+ * Delete a contact from the aggregate
+ */
+export async function aggregateDelete(
+	ctx: MutationCtx,
+	doc: Doc<"contacts">,
+): Promise<void> {
+	await contactAggregate.deleteIfExists(ctx, doc);
+}
+
+/**
+ * Replace a contact in the aggregate (when userGroup changes)
+ */
+export async function aggregateReplace(
+	ctx: MutationCtx,
+	oldDoc: Doc<"contacts">,
+	newDoc: Doc<"contacts">,
+): Promise<void> {
+	await contactAggregate.replaceOrInsert(ctx, oldDoc, newDoc);
+}
+
+/**
+ * Count contacts by userGroup namespace
+ */
+export async function aggregateCountByUserGroup(
+	ctx: QueryCtx,
+	userGroup: string | undefined,
+): Promise<number> {
+	return await contactAggregate.count(ctx, { namespace: userGroup });
+}
+
+/**
+ * Count all contacts across all userGroups
+ */
+export async function aggregateCountTotal(ctx: QueryCtx): Promise<number> {
+	let total = 0;
+	for await (const namespace of contactAggregate.iterNamespaces(ctx)) {
+		total += await contactAggregate.count(ctx, { namespace });
+	}
+	return total;
+}
+
+/**
+ * Clear and reinitialize the aggregate (for backfill)
+ */
+export async function aggregateClear(
+	ctx: MutationCtx,
+	namespace?: string,
+): Promise<void> {
+	await contactAggregate.clear(ctx, { namespace });
+}
+

package/src/component/convex.config.ts

@@ -0,0 +1,8 @@
+import aggregate from "@convex-dev/aggregate/convex.config";
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("loops");
+
+component.use(aggregate, { name: "contactAggregate" });
+
+export default component;

package/src/component/helpers.ts

@@ -0,0 +1,130 @@
+import type { HeadersInitParam } from "../types";
+
+const allowedOrigin =
+	process.env.CONVEX_URL ??
+	process.env.NEXT_PUBLIC_CONVEX_URL ??
+	process.env.CONVEX_SITE_URL ??
+	process.env.NEXT_PUBLIC_CONVEX_SITE_URL ??
+	process.env.LOOPS_HTTP_ALLOWED_ORIGIN ??
+	process.env.CLIENT_ORIGIN ??
+	"*";
+
+export const LOOPS_API_BASE_URL = "https://app.loops.so/api/v1";
+
+export const sanitizeLoopsError = (
+	status: number,
+	_errorText: string,
+): Error => {
+	if (status === 401 || status === 403) {
+		return new Error("Authentication failed. Please check your API key.");
+	}
+	if (status === 404) {
+		return new Error("Resource not found.");
+	}
+	if (status === 429) {
+		return new Error("Rate limit exceeded. Please try again later.");
+	}
+	if (status >= 500) {
+		return new Error("Loops service error. Please try again later.");
+	}
+	return new Error(`Loops API error (${status}). Please try again.`);
+};
+
+export type LoopsRequestInit = Omit<RequestInit, "body"> & {
+	json?: unknown;
+};
+
+export const loopsFetch = async (
+	apiKey: string,
+	path: string,
+	init: LoopsRequestInit = {},
+) => {
+	const { json, ...rest } = init;
+	const headers = new Headers(rest.headers ?? {});
+	headers.set("Authorization", `Bearer ${apiKey}`);
+	if (json !== undefined && !headers.has("Content-Type")) {
+		headers.set("Content-Type", "application/json");
+	}
+
+	return fetch(`${LOOPS_API_BASE_URL}${path}`, {
+		...rest,
+		headers,
+		// @ts-expect-error RequestInit in this build doesn't declare body
+		body: json !== undefined ? JSON.stringify(json) : rest.body,
+	});
+};
+
+export const buildCorsHeaders = (extra?: HeadersInitParam) => {
+	const headers = new Headers(extra ?? {});
+	headers.set("Access-Control-Allow-Origin", allowedOrigin);
+	headers.set("Access-Control-Allow-Methods", "GET,POST,PUT,DELETE,OPTIONS");
+	headers.set("Access-Control-Allow-Headers", "Content-Type, Authorization");
+	headers.set("Access-Control-Max-Age", "86400");
+	headers.set("Vary", "Origin");
+	return headers;
+};
+
+export const jsonResponse = (data: unknown, init?: ResponseInit) => {
+	const headers = buildCorsHeaders(
+		(init?.headers as HeadersInitParam | undefined) ?? undefined,
+	);
+	headers.set("Content-Type", "application/json");
+	return new Response(JSON.stringify(data), { ...init, headers });
+};
+
+export const emptyResponse = (init?: ResponseInit) => {
+	const headers = buildCorsHeaders(
+		(init?.headers as HeadersInitParam | undefined) ?? undefined,
+	);
+	return new Response(null, { ...init, headers });
+};
+
+export const readJsonBody = async <T>(request: Request): Promise<T> => {
+	try {
+		return (await request.json()) as T;
+	} catch (_error) {
+		throw new Error("Invalid JSON body");
+	}
+};
+
+export const booleanFromQuery = (value: string | null) => {
+	if (value === null) {
+		return undefined;
+	}
+	if (value === "true") {
+		return true;
+	}
+	if (value === "false") {
+		return false;
+	}
+	return undefined;
+};
+
+export const numberFromQuery = (value: string | null, fallback: number) => {
+	if (!value) {
+		return fallback;
+	}
+	const parsed = Number.parseInt(value, 10);
+	return Number.isNaN(parsed) ? fallback : parsed;
+};
+
+export const requireLoopsApiKey = () => {
+	const apiKey = process.env.LOOPS_API_KEY;
+	if (!apiKey) {
+		throw new Error(
+			"LOOPS_API_KEY environment variable must be set to use the HTTP API.",
+		);
+	}
+	return apiKey;
+};
+
+export const respondError = (error: unknown) => {
+	console.error("[loops:http]", error);
+	const message = error instanceof Error ? error.message : "Unexpected error";
+	const status =
+		error instanceof Error &&
+		error.message.includes("LOOPS_API_KEY environment variable")
+			? 500
+			: 400;
+	return jsonResponse({ error: message }, { status });
+};

package/src/component/http.ts

@@ -0,0 +1,236 @@
+import { httpRouter } from "convex/server";
+import type {
+	ContactPayload,
+	DeleteContactPayload,
+	EventPayload,
+	TransactionalPayload,
+	TriggerPayload,
+	UpdateContactPayload,
+} from "../types";
+import { api } from "./_generated/api";
+import { httpAction } from "./_generated/server";
+import {
+	booleanFromQuery,
+	buildCorsHeaders,
+	emptyResponse,
+	jsonResponse,
+	numberFromQuery,
+	readJsonBody,
+	requireLoopsApiKey,
+	respondError,
+} from "./helpers";
+
+const http = httpRouter();
+
+http.route({
+	pathPrefix: "/loops/",
+	method: "OPTIONS",
+	handler: httpAction(async (_ctx, request) => {
+		const headers = buildCorsHeaders();
+		const requestedHeaders = request.headers.get(
+			"Access-Control-Request-Headers",
+		);
+		if (requestedHeaders) {
+			headers.set("Access-Control-Allow-Headers", requestedHeaders);
+		}
+		const requestedMethod = request.headers.get(
+			"Access-Control-Request-Method",
+		);
+		if (requestedMethod) {
+			headers.set("Access-Control-Allow-Methods", `${requestedMethod},OPTIONS`);
+		}
+		return new Response(null, { status: 204, headers });
+	}),
+});
+
+http.route({
+	path: "/loops/contacts",
+	method: "POST",
+	handler: httpAction(async (ctx, request) => {
+		try {
+			const contact = await readJsonBody<ContactPayload>(request);
+			const data = await ctx.runAction(api.actions.addContact, {
+				apiKey: requireLoopsApiKey(),
+				contact,
+			});
+			return jsonResponse(data, { status: 201 });
+		} catch (error) {
+			return respondError(error);
+		}
+	}),
+});
+
+http.route({
+	path: "/loops/contacts",
+	method: "PUT",
+	handler: httpAction(async (ctx, request) => {
+		try {
+			const payload = await readJsonBody<UpdateContactPayload>(request);
+			if (!payload.email) {
+				throw new Error("email is required");
+			}
+			const data = await ctx.runAction(api.actions.updateContact, {
+				apiKey: requireLoopsApiKey(),
+				email: payload.email,
+				dataVariables: payload.dataVariables,
+				firstName: payload.firstName,
+				lastName: payload.lastName,
+				userId: payload.userId,
+				source: payload.source,
+				subscribed: payload.subscribed,
+				userGroup: payload.userGroup,
+			});
+			return jsonResponse(data);
+		} catch (error) {
+			return respondError(error);
+		}
+	}),
+});
+
+http.route({
+	path: "/loops/contacts",
+	method: "GET",
+	handler: httpAction(async (ctx, request) => {
+		try {
+			const url = new URL(request.url);
+			const email = url.searchParams.get("email");
+			if (email) {
+				const data = await ctx.runAction(api.actions.findContact, {
+					apiKey: requireLoopsApiKey(),
+					email,
+				});
+				return jsonResponse(data);
+			}
+
+			const data = await ctx.runQuery(api.queries.listContacts, {
+				userGroup: url.searchParams.get("userGroup") ?? undefined,
+				source: url.searchParams.get("source") ?? undefined,
+				subscribed: booleanFromQuery(url.searchParams.get("subscribed")),
+				limit: numberFromQuery(url.searchParams.get("limit"), 100),
+				cursor: url.searchParams.get("cursor") ?? null,
+			});
+			return jsonResponse(data);
+		} catch (error) {
+			return respondError(error);
+		}
+	}),
+});
+
+http.route({
+	path: "/loops/contacts",
+	method: "DELETE",
+	handler: httpAction(async (ctx, request) => {
+		try {
+			const payload = await readJsonBody<DeleteContactPayload>(request);
+			if (!payload.email) {
+				throw new Error("email is required");
+			}
+			await ctx.runAction(api.actions.deleteContact, {
+				apiKey: requireLoopsApiKey(),
+				email: payload.email,
+			});
+			return emptyResponse({ status: 204 });
+		} catch (error) {
+			return respondError(error);
+		}
+	}),
+});
+
+http.route({
+	path: "/loops/transactional",
+	method: "POST",
+	handler: httpAction(async (ctx, request) => {
+		try {
+			const payload = await readJsonBody<TransactionalPayload>(request);
+			if (!payload.transactionalId) {
+				throw new Error("transactionalId is required");
+			}
+			if (!payload.email) {
+				throw new Error("email is required");
+			}
+			const data = await ctx.runAction(api.actions.sendTransactional, {
+				apiKey: requireLoopsApiKey(),
+				transactionalId: payload.transactionalId,
+				email: payload.email,
+				dataVariables: payload.dataVariables,
+				idempotencyKey: payload.idempotencyKey,
+			});
+			return jsonResponse(data);
+		} catch (error) {
+			return respondError(error);
+		}
+	}),
+});
+
+http.route({
+	path: "/loops/events",
+	method: "POST",
+	handler: httpAction(async (ctx, request) => {
+		try {
+			const payload = await readJsonBody<EventPayload>(request);
+			if (!payload.email) {
+				throw new Error("email is required");
+			}
+			if (!payload.eventName) {
+				throw new Error("eventName is required");
+			}
+			const data = await ctx.runAction(api.actions.sendEvent, {
+				apiKey: requireLoopsApiKey(),
+				email: payload.email,
+				eventName: payload.eventName,
+				eventProperties: payload.eventProperties,
+			});
+			return jsonResponse(data);
+		} catch (error) {
+			return respondError(error);
+		}
+	}),
+});
+
+http.route({
+	path: "/loops/trigger",
+	method: "POST",
+	handler: httpAction(async (ctx, request) => {
+		try {
+			const payload = await readJsonBody<TriggerPayload>(request);
+			if (!payload.loopId) {
+				throw new Error("loopId is required");
+			}
+			if (!payload.email) {
+				throw new Error("email is required");
+			}
+			const data = await ctx.runAction(api.actions.triggerLoop, {
+				apiKey: requireLoopsApiKey(),
+				loopId: payload.loopId,
+				email: payload.email,
+				dataVariables: payload.dataVariables,
+				eventName: payload.eventName,
+			});
+			return jsonResponse(data);
+		} catch (error) {
+			return respondError(error);
+		}
+	}),
+});
+
+http.route({
+	path: "/loops/stats",
+	method: "GET",
+	handler: httpAction(async (ctx, request) => {
+		try {
+			const url = new URL(request.url);
+			const timeWindowMs = numberFromQuery(
+				url.searchParams.get("timeWindowMs"),
+				86400000,
+			);
+			const data = await ctx.runQuery(api.queries.getEmailStats, {
+				timeWindowMs,
+			});
+			return jsonResponse(data);
+		} catch (error) {
+			return respondError(error);
+		}
+	}),
+});
+
+export default http;

package/src/component/mutations.ts

@@ -0,0 +1,192 @@
+import { v } from "convex/values";
+import { paginator } from "convex-helpers/server/pagination";
+import type { Doc } from "./_generated/dataModel";
+import { internalMutation, mutation } from "./_generated/server";
+import {
+	aggregateClear,
+	aggregateDelete,
+	aggregateInsert,
+	aggregateReplace,
+} from "./aggregates";
+import schema from "./schema";
+import {
+	backfillResponseValidator,
+	operationTypeValidator,
+} from "./validators";
+
+/**
+ * Internal mutation to store/update a contact in the database
+ */
+export const storeContact = internalMutation({
+	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()),
+		loopsContactId: v.optional(v.string()),
+	},
+	returns: v.null(),
+	handler: async (ctx, args) => {
+		const now = Date.now();
+		const existing = await ctx.db
+			.query("contacts")
+			.withIndex("email", (q) => q.eq("email", args.email))
+			.unique();
+
+		if (existing) {
+			// Update the contact
+			await ctx.db.patch(existing._id, {
+				firstName: args.firstName,
+				lastName: args.lastName,
+				userId: args.userId,
+				source: args.source,
+				subscribed: args.subscribed ?? existing.subscribed,
+				userGroup: args.userGroup,
+				loopsContactId: args.loopsContactId,
+				updatedAt: now,
+			});
+
+			// Get the updated document and update aggregate if userGroup changed
+			const updated = await ctx.db.get(existing._id);
+			if (updated && existing.userGroup !== updated.userGroup) {
+				await aggregateReplace(ctx, existing, updated);
+			}
+		} else {
+			// Insert new contact
+			const id = await ctx.db.insert("contacts", {
+				email: args.email,
+				firstName: args.firstName,
+				lastName: args.lastName,
+				userId: args.userId,
+				source: args.source,
+				subscribed: args.subscribed ?? true,
+				userGroup: args.userGroup,
+				loopsContactId: args.loopsContactId,
+				createdAt: now,
+				updatedAt: now,
+			});
+
+			// Add to aggregate for counting
+			const newDoc = await ctx.db.get(id);
+			if (newDoc) {
+				await aggregateInsert(ctx, newDoc);
+			}
+		}
+		return null;
+	},
+});
+
+/**
+ * Internal mutation to delete a contact from the database
+ */
+export const removeContact = internalMutation({
+	args: {
+		email: v.string(),
+	},
+	returns: v.null(),
+	handler: async (ctx, args) => {
+		const existing = await ctx.db
+			.query("contacts")
+			.withIndex("email", (q) => q.eq("email", args.email))
+			.unique();
+
+		if (existing) {
+			// Remove from aggregate first (before deleting the document)
+			await aggregateDelete(ctx, existing);
+			await ctx.db.delete(existing._id);
+		}
+		return null;
+	},
+});
+
+/**
+ * Internal mutation to log an email operation for monitoring
+ */
+export const logEmailOperation = internalMutation({
+	args: {
+		operationType: operationTypeValidator,
+		email: v.string(),
+		actorId: v.optional(v.string()),
+		transactionalId: v.optional(v.string()),
+		campaignId: v.optional(v.string()),
+		loopId: v.optional(v.string()),
+		eventName: v.optional(v.string()),
+		success: v.boolean(),
+		messageId: v.optional(v.string()),
+		metadata: v.optional(v.record(v.string(), v.any())),
+	},
+	returns: v.null(),
+	handler: async (ctx, args) => {
+		const operationData: Omit<
+			Doc<"emailOperations">,
+			"_id" | "_creationTime"
+		> = {
+			operationType: args.operationType,
+			email: args.email,
+			timestamp: Date.now(),
+			success: args.success,
+			actorId: args.actorId,
+			transactionalId: args.transactionalId,
+			campaignId: args.campaignId,
+			loopId: args.loopId,
+			eventName: args.eventName,
+			messageId: args.messageId,
+			metadata: args.metadata,
+		};
+
+		await ctx.db.insert("emailOperations", operationData);
+		return null;
+	},
+});
+
+/**
+ * Backfill the contact aggregate with existing contacts.
+ * Run this mutation 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:
+ * 1. First call with clear: true to reset the aggregate
+ * 2. Subsequent calls with the returned cursor until isDone is true
+ */
+export const backfillContactAggregate = mutation({
+	args: {
+		cursor: v.optional(v.union(v.string(), v.null())),
+		batchSize: v.optional(v.number()),
+		clear: v.optional(v.boolean()),
+	},
+	returns: backfillResponseValidator,
+	handler: async (ctx, args) => {
+		const batchSize = args.batchSize ?? 100;
+
+		// Clear aggregate on first call if requested
+		if (args.clear && !args.cursor) {
+			await aggregateClear(ctx);
+		}
+
+		const paginationOpts = {
+			cursor: args.cursor ?? null,
+			numItems: Math.min(Math.max(1, batchSize), 500),
+		};
+
+		const result = await paginator(ctx.db, schema)
+			.query("contacts")
+			.order("asc")
+			.paginate(paginationOpts);
+
+		// Insert each contact into the aggregate
+		for (const contact of result.page) {
+			await aggregateInsert(ctx, contact);
+		}
+
+		return {
+			processed: result.page.length,
+			cursor: result.continueCursor,
+			isDone: result.isDone,
+		};
+	},
+});