@devwithbobby/loops 0.1.12 → 0.1.14

package/src/client/index.ts

@@ -1,7 +1,7 @@
 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";
+import type { Mounts } from "../component/_generated/api";
+import type { RunActionCtx, RunQueryCtx, UseApi } from "../types";
 
 export type LoopsComponent = UseApi<Mounts>;
 
@@ -18,21 +18,21 @@ export interface ContactData {
 export interface TransactionalEmailOptions {
 	transactionalId: string;
 	email: string;
-	dataVariables?: Record<string, any>;
+	dataVariables?: Record<string, unknown>;
 }
 
 export interface EventOptions {
 	email: string;
 	eventName: string;
-	eventProperties?: Record<string, any>;
+	eventProperties?: Record<string, unknown>;
 }
 
 export class Loops {
-	private readonly component: LoopsComponent;
 	public readonly options?: {
 		apiKey?: string;
 	};
-	
+	private readonly lib: NonNullable<LoopsComponent["lib"]>;
+
 	constructor(
 		component: LoopsComponent,
 		options?: {
@@ -43,26 +43,26 @@ export class Loops {
 			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)"
+					"new Loops(components.loops)",
 			);
 		}
-		
+
 		if (!component.lib) {
 			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);"
+					"app.use(loops);",
 			);
 		}
-		
-		this.component = component;
+
+		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."
+				"Loops API key is required. Set LOOPS_API_KEY in your Convex environment variables.",
 			);
 		}
 
@@ -83,22 +83,7 @@ export class Loops {
 	 * Add or update a contact in Loops
 	 */
 	async addContact(ctx: RunActionCtx, contact: ContactData) {
-		if (!this.component) {
-			throw new Error(
-				"Loops component is not initialized. " +
-					"Make sure to pass components.loops to the Loops constructor: " +
-					"new Loops(components.loops)"
-			);
-		}
-		if (!this.component.lib) {
-			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);"
-			);
-		}
-		return ctx.runAction((this.component.lib as any).addContact, {
+		return ctx.runAction(this.lib.addContact, {
 			apiKey: this.apiKey,
 			contact,
 		});
@@ -111,10 +96,10 @@ export class Loops {
 		ctx: RunActionCtx,
 		email: string,
 		updates: Partial<ContactData> & {
-			dataVariables?: Record<string, any>;
+			dataVariables?: Record<string, unknown>;
 		},
 	) {
-		return ctx.runAction((this.component.lib as any).updateContact, {
+		return ctx.runAction(this.lib.updateContact, {
 			apiKey: this.apiKey,
 			email,
 			...updates,
@@ -124,8 +109,11 @@ export class Loops {
 	/**
 	 * Send a transactional email using a transactional ID
 	 */
-	async sendTransactional(ctx: RunActionCtx, options: TransactionalEmailOptions) {
-		return ctx.runAction((this.component.lib as any).sendTransactional, {
+	async sendTransactional(
+		ctx: RunActionCtx,
+		options: TransactionalEmailOptions,
+	) {
+		return ctx.runAction(this.lib.sendTransactional, {
 			apiKey: this.apiKey,
 			...options,
 		});
@@ -135,7 +123,7 @@ export class Loops {
 	 * Send an event to Loops to trigger email workflows
 	 */
 	async sendEvent(ctx: RunActionCtx, options: EventOptions) {
-		return ctx.runAction((this.component.lib as any).sendEvent, {
+		return ctx.runAction(this.lib.sendEvent, {
 			apiKey: this.apiKey,
 			...options,
 		});
@@ -146,7 +134,7 @@ export class Loops {
 	 * Retrieves contact information from Loops
 	 */
 	async findContact(ctx: RunActionCtx, email: string) {
-		return ctx.runAction((this.component.lib as any).findContact, {
+		return ctx.runAction(this.lib.findContact, {
 			apiKey: this.apiKey,
 			email,
 		});
@@ -157,7 +145,7 @@ export class Loops {
 	 * Create multiple contacts in a single API call
 	 */
 	async batchCreateContacts(ctx: RunActionCtx, contacts: ContactData[]) {
-		return ctx.runAction((this.component.lib as any).batchCreateContacts, {
+		return ctx.runAction(this.lib.batchCreateContacts, {
 			apiKey: this.apiKey,
 			contacts,
 		});
@@ -168,7 +156,7 @@ export class Loops {
 	 * 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, {
+		return ctx.runAction(this.lib.unsubscribeContact, {
 			apiKey: this.apiKey,
 			email,
 		});
@@ -179,7 +167,7 @@ export class Loops {
 	 * Resubscribes a previously unsubscribed contact
 	 */
 	async resubscribeContact(ctx: RunActionCtx, email: string) {
-		return ctx.runAction((this.component.lib as any).resubscribeContact, {
+		return ctx.runAction(this.lib.resubscribeContact, {
 			apiKey: this.apiKey,
 			email,
 		});
@@ -198,7 +186,7 @@ export class Loops {
 			subscribed?: boolean;
 		},
 	) {
-		return ctx.runQuery((this.component.lib as any).countContacts, options ?? {});
+		return ctx.runQuery(this.lib.countContacts, options ?? {});
 	}
 
 	/**
@@ -216,7 +204,7 @@ export class Loops {
 			offset?: number;
 		},
 	) {
-		return ctx.runQuery((this.component.lib as any).listContacts, {
+		return ctx.runQuery(this.lib.listContacts, {
 			userGroup: options?.userGroup,
 			source: options?.source,
 			subscribed: options?.subscribed,
@@ -235,7 +223,7 @@ export class Loops {
 			maxEmailsPerRecipient?: number;
 		},
 	) {
-		return ctx.runQuery((this.component.lib as any).detectRecipientSpam, {
+		return ctx.runQuery(this.lib.detectRecipientSpam, {
 			timeWindowMs: options?.timeWindowMs ?? 3600000,
 			maxEmailsPerRecipient: options?.maxEmailsPerRecipient ?? 10,
 		});
@@ -251,7 +239,7 @@ export class Loops {
 			maxEmailsPerActor?: number;
 		},
 	) {
-		return ctx.runQuery((this.component.lib as any).detectActorSpam, {
+		return ctx.runQuery(this.lib.detectActorSpam, {
 			timeWindowMs: options?.timeWindowMs ?? 3600000,
 			maxEmailsPerActor: options?.maxEmailsPerActor ?? 100,
 		});
@@ -266,7 +254,7 @@ export class Loops {
 			timeWindowMs?: number;
 		},
 	) {
-		return ctx.runQuery((this.component.lib as any).getEmailStats, {
+		return ctx.runQuery(this.lib.getEmailStats, {
 			timeWindowMs: options?.timeWindowMs ?? 86400000,
 		});
 	}
@@ -281,7 +269,7 @@ export class Loops {
 			minEmailsInWindow?: number;
 		},
 	) {
-		return ctx.runQuery((this.component.lib as any).detectRapidFirePatterns, {
+		return ctx.runQuery(this.lib.detectRapidFirePatterns, {
 			timeWindowMs: options?.timeWindowMs ?? 60000,
 			minEmailsInWindow: options?.minEmailsInWindow ?? 5,
 		});
@@ -298,7 +286,7 @@ export class Loops {
 			maxEmails: number;
 		},
 	) {
-		return ctx.runQuery((this.component.lib as any).checkRecipientRateLimit, options);
+		return ctx.runQuery(this.lib.checkRecipientRateLimit, options);
 	}
 
 	/**
@@ -312,7 +300,7 @@ export class Loops {
 			maxEmails: number;
 		},
 	) {
-		return ctx.runQuery((this.component.lib as any).checkActorRateLimit, options);
+		return ctx.runQuery(this.lib.checkActorRateLimit, options);
 	}
 
 	/**
@@ -325,14 +313,14 @@ export class Loops {
 			maxEmails: number;
 		},
 	) {
-		return ctx.runQuery((this.component.lib as any).checkGlobalRateLimit, options);
+		return ctx.runQuery(this.lib.checkGlobalRateLimit, options);
 	}
 
 	/**
 	 * Delete a contact from Loops
 	 */
 	async deleteContact(ctx: RunActionCtx, email: string) {
-		return ctx.runAction((this.component.lib as any).deleteContact, {
+		return ctx.runAction(this.lib.deleteContact, {
 			apiKey: this.apiKey,
 			email,
 		});
@@ -341,11 +329,11 @@ export class Loops {
 	/**
 	 * 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(
@@ -353,11 +341,11 @@ export class Loops {
 		options: {
 			loopId: string;
 			email: string;
-			dataVariables?: Record<string, any>;
+			dataVariables?: Record<string, unknown>;
 			eventName?: string; // Event name that triggers the loop
 		},
 	) {
-		return ctx.runAction((this.component.lib as any).triggerLoop, {
+		return ctx.runAction(this.lib.triggerLoop, {
 			apiKey: this.apiKey,
 			...options,
 		});

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

@@ -27,17 +27,9 @@ import type {
 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>;
-  };
-};
+export type Mounts = ApiFromModules<{
+  lib: typeof lib;
+}>;
 // For now fullApiWithMounts is only fullApi which provides
 // jump-to-definition in component client code.
 // Use Mounts for the same type without the inference.

package/src/component/convex.config.ts

@@ -1,8 +1,13 @@
 import { defineComponent } from "convex/server";
-import { api } from "./_generated/api.js";
+import { api } from "./_generated/api";
 
 const component = defineComponent("loops");
-(component as any).export(api, {
+
+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,

package/src/component/helpers.ts

@@ -0,0 +1,44 @@
+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,
+	});
+};

package/src/component/http.ts

@@ -0,0 +1,304 @@
+import { httpRouter } from "convex/server";
+import {
+	type ContactPayload,
+	type DeleteContactPayload,
+	type EventPayload,
+	type HeadersInitParam,
+	internalLib,
+	type TransactionalPayload,
+	type TriggerPayload,
+	type UpdateContactPayload,
+} from "../types";
+import { httpAction } from "./_generated/server";
+
+const http = httpRouter();
+
+const allowedOrigin =
+	process.env.LOOPS_HTTP_ALLOWED_ORIGIN ?? process.env.CLIENT_ORIGIN ?? "*";
+
+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;
+};
+
+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 });
+};
+
+const emptyResponse = (init?: ResponseInit) => {
+	const headers = buildCorsHeaders(
+		(init?.headers as HeadersInitParam | undefined) ?? undefined,
+	);
+	return new Response(null, { ...init, headers });
+};
+
+const readJsonBody = async <T>(request: Request): Promise<T> => {
+	try {
+		return (await request.json()) as T;
+	} catch (_error) {
+		throw new Error("Invalid JSON body");
+	}
+};
+
+const booleanFromQuery = (value: string | null) => {
+	if (value === null) {
+		return undefined;
+	}
+	if (value === "true") {
+		return true;
+	}
+	if (value === "false") {
+		return false;
+	}
+	return undefined;
+};
+
+const numberFromQuery = (value: string | null, fallback: number) => {
+	if (!value) {
+		return fallback;
+	}
+	const parsed = Number.parseInt(value, 10);
+	return Number.isNaN(parsed) ? fallback : parsed;
+};
+
+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;
+};
+
+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 });
+};
+
+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(internalLib.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(internalLib.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(internalLib.findContact, {
+					apiKey: requireLoopsApiKey(),
+					email,
+				});
+				return jsonResponse(data);
+			}
+
+			const data = await ctx.runQuery(internalLib.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),
+				offset: numberFromQuery(url.searchParams.get("offset"), 0),
+			});
+			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(internalLib.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(internalLib.sendTransactional, {
+				apiKey: requireLoopsApiKey(),
+				transactionalId: payload.transactionalId,
+				email: payload.email,
+				dataVariables: payload.dataVariables,
+			});
+			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(internalLib.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(internalLib.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(internalLib.getEmailStats, {
+				timeWindowMs,
+			});
+			return jsonResponse(data);
+		} catch (error) {
+			return respondError(error);
+		}
+	}),
+});
+
+export default http;