@niama/loops 0.2.0

package/dist/component/aggregates.js

@@ -0,0 +1,54 @@
+import { TableAggregate } from "@convex-dev/aggregate";
+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;
+/**
+ * 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(contactAggregateComponent, {
+    namespace: (doc) => doc.userGroup,
+    sortKey: () => null,
+});
+/**
+ * Insert a contact into the aggregate
+ */
+export async function aggregateInsert(ctx, doc) {
+    await contactAggregate.insertIfDoesNotExist(ctx, doc);
+}
+/**
+ * Delete a contact from the aggregate
+ */
+export async function aggregateDelete(ctx, doc) {
+    await contactAggregate.deleteIfExists(ctx, doc);
+}
+/**
+ * Replace a contact in the aggregate (when userGroup changes)
+ */
+export async function aggregateReplace(ctx, oldDoc, newDoc) {
+    await contactAggregate.replaceOrInsert(ctx, oldDoc, newDoc);
+}
+/**
+ * Count contacts by userGroup namespace
+ */
+export async function aggregateCountByUserGroup(ctx, userGroup) {
+    return await contactAggregate.count(ctx, { namespace: userGroup });
+}
+/**
+ * Count all contacts across all userGroups
+ */
+export async function aggregateCountTotal(ctx) {
+    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, namespace) {
+    await contactAggregate.clear(ctx, { namespace });
+}

package/dist/component/convex.config.d.ts

@@ -0,0 +1,3 @@
+declare const component: import("convex/server").ComponentDefinition<any>;
+export default component;
+//# sourceMappingURL=convex.config.d.ts.map

package/dist/component/convex.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex.config.d.ts","sourceRoot":"","sources":["../../src/component/convex.config.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,SAAS,kDAA2B,CAAC;AAI3C,eAAe,SAAS,CAAC"}

package/dist/component/convex.config.js

@@ -0,0 +1,5 @@
+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/dist/component/helpers.d.ts

@@ -0,0 +1,16 @@
+import type { HeadersInitParam } from "../types";
+export declare const LOOPS_API_BASE_URL = "https://app.loops.so/api/v1";
+export declare const sanitizeLoopsError: (status: number, _errorText: string) => Error;
+export type LoopsRequestInit = Omit<RequestInit, "body"> & {
+    json?: unknown;
+};
+export declare const loopsFetch: (apiKey: string, path: string, init?: LoopsRequestInit) => Promise<Response>;
+export declare const buildCorsHeaders: (extra?: HeadersInitParam) => Headers;
+export declare const jsonResponse: (data: unknown, init?: ResponseInit) => Response;
+export declare const emptyResponse: (init?: ResponseInit) => Response;
+export declare const readJsonBody: <T>(request: Request) => Promise<T>;
+export declare const booleanFromQuery: (value: string | null) => boolean | undefined;
+export declare const numberFromQuery: (value: string | null, fallback: number) => number;
+export declare const requireLoopsApiKey: () => string;
+export declare const respondError: (error: unknown) => Response;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/component/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/component/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAWjD,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAEhE,eAAO,MAAM,kBAAkB,WACtB,MAAM,cACF,MAAM,KAChB,KAcF,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG;IAC1D,IAAI,CAAC,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,UAAU,WACd,MAAM,QACR,MAAM,SACN,gBAAgB,sBAetB,CAAC;AAEF,eAAO,MAAM,gBAAgB,WAAY,gBAAgB,YAQxD,CAAC;AAEF,eAAO,MAAM,YAAY,SAAU,OAAO,SAAS,YAAY,aAM9D,CAAC;AAEF,eAAO,MAAM,aAAa,UAAW,YAAY,aAKhD,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,CAAC,WAAW,OAAO,KAAG,OAAO,CAAC,CAAC,CAMjE,CAAC;AAEF,eAAO,MAAM,gBAAgB,UAAW,MAAM,GAAG,IAAI,wBAWpD,CAAC;AAEF,eAAO,MAAM,eAAe,UAAW,MAAM,GAAG,IAAI,YAAY,MAAM,WAMrE,CAAC;AAEF,eAAO,MAAM,kBAAkB,cAQ9B,CAAC;AAEF,eAAO,MAAM,YAAY,UAAW,OAAO,aAS1C,CAAC"}

package/dist/component/helpers.js

@@ -0,0 +1,98 @@
+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, _errorText) => {
+    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 const loopsFetch = async (apiKey, path, init = {}) => {
+    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) => {
+    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, init) => {
+    const headers = buildCorsHeaders(init?.headers ?? undefined);
+    headers.set("Content-Type", "application/json");
+    return new Response(JSON.stringify(data), { ...init, headers });
+};
+export const emptyResponse = (init) => {
+    const headers = buildCorsHeaders(init?.headers ?? undefined);
+    return new Response(null, { ...init, headers });
+};
+export const readJsonBody = async (request) => {
+    try {
+        return (await request.json());
+    }
+    catch (_error) {
+        throw new Error("Invalid JSON body");
+    }
+};
+export const booleanFromQuery = (value) => {
+    if (value === null) {
+        return undefined;
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    return undefined;
+};
+export const numberFromQuery = (value, fallback) => {
+    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) => {
+    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/dist/component/http.d.ts

@@ -0,0 +1,3 @@
+declare const http: import("convex/server").HttpRouter;
+export default http;
+//# sourceMappingURL=http.d.ts.map

package/dist/component/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/component/http.ts"],"names":[],"mappings":"AAsBA,QAAA,MAAM,IAAI,oCAAe,CAAC;AAqN1B,eAAe,IAAI,CAAC"}

package/dist/component/http.js

@@ -0,0 +1,208 @@
+import { httpRouter } from "convex/server";
+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(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(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(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(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(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(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/dist/component/mutations.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Internal mutation to store/update a contact in the database
+ */
+export declare const storeContact: import("convex/server").RegisteredMutation<"internal", {
+    firstName?: string | undefined;
+    lastName?: string | undefined;
+    userId?: string | undefined;
+    source?: string | undefined;
+    subscribed?: boolean | undefined;
+    userGroup?: string | undefined;
+    loopsContactId?: string | undefined;
+    email: string;
+}, Promise<null>>;
+/**
+ * Internal mutation to delete a contact from the database
+ */
+export declare const removeContact: import("convex/server").RegisteredMutation<"internal", {
+    email: string;
+}, Promise<null>>;
+/**
+ * Internal mutation to log an email operation for monitoring
+ */
+export declare const logEmailOperation: import("convex/server").RegisteredMutation<"internal", {
+    actorId?: string | undefined;
+    transactionalId?: string | undefined;
+    campaignId?: string | undefined;
+    loopId?: string | undefined;
+    eventName?: string | undefined;
+    messageId?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+    email: string;
+    operationType: "transactional" | "event" | "campaign" | "loop";
+    success: boolean;
+}, Promise<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 declare const backfillContactAggregate: import("convex/server").RegisteredMutation<"public", {
+    batchSize?: number | undefined;
+    clear?: boolean | undefined;
+    cursor?: string | null | undefined;
+}, Promise<{
+    processed: number;
+    cursor: string;
+    isDone: boolean;
+}>>;
+//# sourceMappingURL=mutations.d.ts.map

package/dist/component/mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../src/component/mutations.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;iBA4DvB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa;;iBAkBxB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;iBAmC5B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;GAoCnC,CAAC"}

package/dist/component/mutations.js

@@ -0,0 +1,167 @@
+import { v } from "convex/values";
+import { paginator } from "convex-helpers/server/pagination";
+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 = {
+            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,
+        };
+    },
+});