@devwithbobby/loops 0.1.0

package/src/component/schema.ts

@@ -0,0 +1,17 @@
+import { defineSchema } from "convex/server";
+import { Contacts } from "./tables/contacts";
+import { EmailOperations } from "./tables/emailOperations";
+
+export default defineSchema({
+	contacts: Contacts.table
+		.index("email", ["email"])
+		.index("userId", ["userId"])
+		.index("userGroup", ["userGroup"])
+		.index("source", ["source"])
+		.index("subscribed", ["subscribed"]),
+	emailOperations: EmailOperations.table
+		.index("email", ["email", "timestamp"])
+		.index("actorId", ["actorId", "timestamp"])
+		.index("operationType", ["operationType", "timestamp"])
+		.index("timestamp", ["timestamp"]),
+});

package/src/component/tables/contacts.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { zodTable } from "zodvex";
+
+export const Contacts = zodTable("contacts", {
+	email: z.string().email(),
+	firstName: z.string().optional(),
+	lastName: z.string().optional(),
+	userId: z.string().optional(),
+	source: z.string().optional(),
+	subscribed: z.boolean().default(true),
+	userGroup: z.string().optional(),
+	loopsContactId: z.string().optional(),
+	createdAt: z.number(),
+	updatedAt: z.number(),
+});
+

package/src/component/tables/emailOperations.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { zodTable } from "zodvex";
+
+export const EmailOperations = zodTable("emailOperations", {
+	operationType: z.enum([
+		"transactional",
+		"event",
+		"campaign",
+		"loop",
+	]),
+	email: z.string().email(),
+	actorId: z.string().optional(),
+	transactionalId: z.string().optional(),
+	campaignId: z.string().optional(),
+	loopId: z.string().optional(),
+	eventName: z.string().optional(),
+	timestamp: z.number(),
+	success: z.boolean(),
+	messageId: z.string().optional(),
+	metadata: z.optional(z.record(z.string(), z.any())),
+});
+

package/src/component/validators.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+/**
+ * Validators for Loops API requests and component operations
+ */
+
+/**
+ * Validator for contact data
+ * Used for creating and updating contacts
+ */
+export const contactValidator = z.object({
+	email: z.string().email(),
+	firstName: z.string().optional(),
+	lastName: z.string().optional(),
+	userId: z.string().optional(),
+	source: z.string().optional(),
+	subscribed: z.boolean().optional(),
+	userGroup: z.string().optional(),
+});
+
+/**
+ * Validator for transactional email requests
+ */
+export const transactionalEmailValidator = z.object({
+	transactionalId: z.string().optional(),
+	email: z.string().email(),
+	dataVariables: z.record(z.string(), z.any()).optional(),
+});
+
+/**
+ * Validator for event requests
+ * Used for sending events that trigger email workflows
+ */
+export const eventValidator = z.object({
+	email: z.string().email(),
+	eventName: z.string(),
+	eventProperties: z.record(z.string(), z.any()).optional(),
+});
+

package/src/utils.ts

@@ -0,0 +1,6 @@
+import { zActionBuilder, zMutationBuilder, zQueryBuilder } from "zodvex";
+import { action, mutation, query } from "./component/_generated/server";
+
+export const zq = zQueryBuilder(query);
+export const zm = zMutationBuilder(mutation);
+export const za = zActionBuilder(action);

package/test/client/_generated/_ignore.ts

@@ -0,0 +1 @@
+// This is only here so convex-test can detect a _generated folder

package/test/client/index.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import { defineSchema } from "convex/server";
+import { Loops } from "../../src/client";
+import { components, initConvexTest } from "./setup.test.js";
+
+// The schema for the tests
+const schema = defineSchema({});
+
+describe("Loops thick client", () => {
+	test("should create Loops client", () => {
+		const loops = new Loops(components.loops, {
+			apiKey: "test-api-key",
+		});
+		expect(loops).toBeDefined();
+	});
+
+	test("should throw error if no API key provided", () => {
+		const originalEnv = process.env.LOOPS_API_KEY;
+		delete process.env.LOOPS_API_KEY;
+
+		expect(() => {
+			new Loops(components.loops);
+		}).toThrow("Loops API key is required");
+		
+		if (originalEnv) {
+			process.env.LOOPS_API_KEY = originalEnv;
+		}
+	});
+
+	test("should work with api() helper - generates actions", () => {
+		const loops = new Loops(components.loops, {
+			apiKey: "test-api-key",
+		});
+		const api = loops.api();
+
+		expect(api.addContact).toBeDefined();
+		expect(api.updateContact).toBeDefined();
+		expect(api.findContact).toBeDefined();
+		expect(api.batchCreateContacts).toBeDefined();
+		expect(api.unsubscribeContact).toBeDefined();
+		expect(api.resubscribeContact).toBeDefined();
+		expect(api.deleteContact).toBeDefined();
+		expect(api.sendTransactional).toBeDefined();
+		expect(api.sendEvent).toBeDefined();
+		expect(api.sendCampaign).toBeDefined();
+		expect(api.triggerLoop).toBeDefined();
+		expect(api.countContacts).toBeDefined();
+		expect(api.detectRecipientSpam).toBeDefined();
+		expect(api.detectActorSpam).toBeDefined();
+		expect(api.getEmailStats).toBeDefined();
+		expect(api.detectRapidFirePatterns).toBeDefined();
+		expect(api.checkRecipientRateLimit).toBeDefined();
+		expect(api.checkActorRateLimit).toBeDefined();
+		expect(api.checkGlobalRateLimit).toBeDefined();
+		expect(typeof api.addContact).toBe("function");
+		expect(typeof api.sendTransactional).toBe("function");
+		expect(typeof api.countContacts).toBe("function");
+		expect(typeof api.detectRecipientSpam).toBe("function");
+		expect(typeof api.checkRecipientRateLimit).toBe("function");
+	});
+
+	// Note: Integration tests that actually call the Loops API would require
+	// mocking the fetch calls or using a test API key. These tests verify
+	// the structure and basic functionality of the client.
+});

package/test/client/setup.test.ts

@@ -0,0 +1,54 @@
+import { test } from "bun:test";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	componentsGeneric,
+	defineSchema,
+	type GenericSchema,
+	type SchemaDefinition,
+} from "convex/server";
+import { convexTest } from "convex-test";
+import type { LoopsComponentComponent } from "../../src/client/index.js";
+import componentSchema from "../../src/component/schema.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const clientDir = join(__dirname, "../../test/client");
+const componentDir = join(__dirname, "../../src/component");
+
+// Auto-discover client test files
+const clientFiles = await Array.fromAsync(
+	new Bun.Glob("**/*.{ts,js}").scan({ cwd: clientDir }),
+);
+
+export const modules = Object.fromEntries(
+	clientFiles
+		.filter((f) => !f.includes(".test."))
+		.map((f) => [`./${f}`, () => import(join(clientDir, f))]),
+);
+
+// Auto-discover component files for registration
+const componentFiles = await Array.fromAsync(
+	new Bun.Glob("**/*.{ts,js}").scan({ cwd: componentDir }),
+);
+
+export const componentModules = Object.fromEntries(
+	componentFiles
+		.filter((f) => !f.includes(".test."))
+		.map((f) => [`./${f}`, () => import(join(componentDir, f))]),
+);
+
+export { componentSchema };
+
+export function initConvexTest<
+	Schema extends SchemaDefinition<GenericSchema, boolean>,
+>(schema?: Schema) {
+	const t = convexTest(schema ?? defineSchema({}), modules);
+	t.registerComponent("loops", componentSchema, componentModules);
+	return t;
+}
+
+export const components = componentsGeneric() as unknown as {
+	loops: LoopsComponentComponent;
+};
+
+test("setup", () => {});

package/test/component/lib.test.ts

@@ -0,0 +1,225 @@
+import { describe, expect, test } from "bun:test";
+import { api, internal } from "../../src/component/_generated/api";
+import { convexTest } from "./setup.test.ts";
+
+describe("component lib", () => {
+	test("addContact stores contact in database", async () => {
+		const t = convexTest();
+		const result = await t.action(api.lib.addContact, {
+			apiKey: "test-api-key",
+			contact: {
+				email: "test@example.com",
+				firstName: "Test",
+				lastName: "User",
+			},
+		});
+
+		expect(result.success).toBe(true);
+		expect(result.id).toBeDefined();
+		const contacts = await t.db.query("contacts").collect();
+		expect(contacts.length).toBe(1);
+		expect(contacts[0].email).toBe("test@example.com");
+		expect(contacts[0].firstName).toBe("Test");
+		expect(contacts[0].lastName).toBe("User");
+	});
+
+	test("updateContact updates existing contact", async () => {
+		const t = convexTest();
+		await t.action(api.lib.addContact, {
+			apiKey: "test-api-key",
+			contact: {
+				email: "update@example.com",
+				firstName: "Original",
+			},
+		});
+
+		const result = await t.action(api.lib.updateContact, {
+			apiKey: "test-api-key",
+			email: "update@example.com",
+			firstName: "Updated",
+		});
+
+		expect(result.success).toBe(true);
+
+		const contact = await t.db
+			.query("contacts")
+			.withIndex("email", (q: any) => q.eq("email", "update@example.com"))
+			.unique();
+		expect(contact?.firstName).toBe("Updated");
+	});
+
+	test("deleteContact removes contact from database", async () => {
+		const t = convexTest();
+
+		await t.action(api.lib.addContact, {
+			apiKey: "test-api-key",
+			contact: {
+				email: "delete@example.com",
+			},
+		});
+
+		let contacts = await t.db.query("contacts").collect();
+		expect(contacts.length).toBe(1);
+
+		const result = await t.action(api.lib.deleteContact, {
+			apiKey: "test-api-key",
+			email: "delete@example.com",
+		});
+
+		expect(result.success).toBe(true);
+
+		contacts = await t.db.query("contacts").collect();
+		expect(contacts.length).toBe(0);
+	});
+
+	test("countContacts returns correct count", async () => {
+		const t = convexTest();
+		const now = Date.now();
+
+		await t.action(api.lib.addContact, {
+			apiKey: "test-api-key",
+			contact: {
+				email: "count1@example.com",
+			},
+		});
+		await t.action(api.lib.addContact, {
+			apiKey: "test-api-key",
+			contact: {
+				email: "count2@example.com",
+			},
+		});
+		await t.action(api.lib.addContact, {
+			apiKey: "test-api-key",
+			contact: {
+				email: "count3@example.com",
+				userGroup: "premium",
+			},
+		});
+
+		const totalCount = await t.query(api.lib.countContacts, {});
+		expect(totalCount).toBe(3);
+
+		const premiumCount = await t.query(api.lib.countContacts, {
+			userGroup: "premium",
+		});
+		expect(premiumCount).toBe(1);
+
+		const subscribedCount = await t.query(api.lib.countContacts, {
+			subscribed: true,
+		});
+		expect(subscribedCount).toBe(3);
+	});
+
+	test("checkRecipientRateLimit returns correct rate limit status", async () => {
+		const t = convexTest();
+
+		const now = Date.now();
+		
+		await t.mutation(internal.lib.logEmailOperation as any, {
+			operationType: "transactional",
+			email: "ratelimit@example.com",
+			timestamp: now - 1000,
+			success: true,
+		});
+		await t.mutation(internal.lib.logEmailOperation as any, {
+			operationType: "transactional",
+			email: "ratelimit@example.com",
+			timestamp: now - 2000,
+			success: true,
+		});
+
+		const check = await t.query(api.lib.checkRecipientRateLimit, {
+			email: "ratelimit@example.com",
+			timeWindowMs: 3600000,
+			maxEmails: 10,
+		});
+
+		expect(check.allowed).toBe(true);
+		expect(check.count).toBe(2);
+		expect(check.limit).toBe(10);
+	});
+
+	test("checkRecipientRateLimit detects when limit is exceeded", async () => {
+		const t = convexTest();
+		const now = Date.now();
+
+		for (let i = 0; i < 12; i++) {
+			await t.mutation(internal.lib.logEmailOperation as any, {
+				operationType: "transactional",
+				email: "exceeded@example.com",
+				timestamp: now - i * 1000,
+				success: true,
+			});
+		}
+
+		const check = await t.query(api.lib.checkRecipientRateLimit, {
+			email: "exceeded@example.com",
+			timeWindowMs: 3600000,
+			maxEmails: 10,
+		});
+
+		expect(check.allowed).toBe(false);
+		expect(check.count).toBeGreaterThan(10);
+		expect(check.retryAfter).toBeDefined();
+	});
+
+	test("getEmailStats returns correct statistics", async () => {
+		const t = convexTest();
+		const now = Date.now();
+
+		await t.mutation(internal.lib.logEmailOperation as any, {
+			operationType: "transactional",
+			email: "stats1@example.com",
+			timestamp: now - 1000,
+			success: true,
+		});
+		await t.mutation(internal.lib.logEmailOperation as any, {
+			operationType: "event",
+			email: "stats2@example.com",
+			eventName: "test-event",
+			timestamp: now - 2000,
+			success: true,
+		});
+		await t.mutation(internal.lib.logEmailOperation as any, {
+			operationType: "transactional",
+			email: "stats3@example.com",
+			timestamp: now - 3000,
+			success: false,
+		});
+
+		const stats = await t.query(api.lib.getEmailStats, {
+			timeWindowMs: 3600000,
+		});
+
+		expect(stats.totalOperations).toBe(3);
+		expect(stats.successfulOperations).toBe(2);
+		expect(stats.failedOperations).toBe(1);
+		expect((stats.operationsByType as any)["transactional"]).toBe(2);
+		expect((stats.operationsByType as any)["event"]).toBe(1);
+		expect(stats.uniqueRecipients).toBe(3);
+	});
+
+	test("detectRecipientSpam finds suspicious patterns", async () => {
+		const t = convexTest();
+		const now = Date.now();
+
+		for (let i = 0; i < 15; i++) {
+			await t.mutation(internal.lib.logEmailOperation as any, {
+				operationType: "transactional",
+				email: "spam@example.com",
+				timestamp: now - i * 1000,
+				success: true,
+			});
+		}
+
+		const spam = await t.query(api.lib.detectRecipientSpam, {
+			timeWindowMs: 3600000,
+			maxEmailsPerRecipient: 10,
+		});
+
+		expect(spam.length).toBeGreaterThan(0);
+		const spamEntry = spam.find((s) => s.email === "spam@example.com");
+		expect(spamEntry).toBeDefined();
+		expect(spamEntry!.count).toBeGreaterThan(10);
+	});
+});

package/test/component/setup.test.ts

@@ -0,0 +1,21 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { convexTest as convexT } from "convex-test";
+import schema from "../../src/component/schema.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const componentDir = join(__dirname, "../../src/component");
+
+const files = await Array.fromAsync(
+	new Bun.Glob("**/*.{ts,js}").scan({ cwd: componentDir }),
+);
+
+export const modules = Object.fromEntries(
+	files
+		.filter((f) => !f.includes(".test."))
+		.map((f) => [`./${f}`, () => import(join(componentDir, f))]),
+);
+
+export const convexTest = () => {
+	return convexT(schema, modules);
+};

package/tsconfig.build.json

@@ -0,0 +1,20 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noEmit": false,
+		"allowImportingTsExtensions": false,
+		"declaration": true,
+		"declarationMap": true,
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"skipLibCheck": true,
+		"noImplicitAny": false,
+	},
+	"include": ["src/**/*"],
+	"exclude": [
+		"src/**/*.test.*",
+		"src/**/test-setup.ts",
+		"src/**/*.convex.test.*",
+		"src/**/_generated"
+	]
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	}
+}