@niama/loops 0.2.0

package/dist/client/index.js

@@ -0,0 +1,464 @@
+import { actionGeneric, mutationGeneric, queryGeneric } from "convex/server";
+import { v } from "convex/values";
+export class Loops {
+    options;
+    actions;
+    queries;
+    mutations;
+    _apiKey;
+    constructor(component, options) {
+        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.
+     */
+    get apiKey() {
+        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, contact) {
+        return ctx.runAction(this.actions.addContact, {
+            apiKey: this.apiKey,
+            contact,
+        });
+    }
+    /**
+     * Update an existing contact in Loops
+     */
+    async updateContact(ctx, email, updates) {
+        return ctx.runAction(this.actions.updateContact, {
+            apiKey: this.apiKey,
+            email,
+            ...updates,
+        });
+    }
+    /**
+     * Send a transactional email using a transactional ID
+     */
+    async sendTransactional(ctx, options) {
+        return ctx.runAction(this.actions.sendTransactional, {
+            apiKey: this.apiKey,
+            ...options,
+        });
+    }
+    /**
+     * Send an event to Loops to trigger email workflows
+     */
+    async sendEvent(ctx, options) {
+        return ctx.runAction(this.actions.sendEvent, {
+            apiKey: this.apiKey,
+            ...options,
+        });
+    }
+    /**
+     * Find a contact by email
+     * Retrieves contact information from Loops
+     */
+    async findContact(ctx, email) {
+        return ctx.runAction(this.actions.findContact, {
+            apiKey: this.apiKey,
+            email,
+        });
+    }
+    /**
+     * Batch create contacts
+     * Create multiple contacts in a single API call
+     */
+    async batchCreateContacts(ctx, contacts) {
+        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, email) {
+        return ctx.runAction(this.actions.unsubscribeContact, {
+            apiKey: this.apiKey,
+            email,
+        });
+    }
+    /**
+     * Resubscribe a contact
+     * Resubscribes a previously unsubscribed contact
+     */
+    async resubscribeContact(ctx, email) {
+        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, options) {
+        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, options) {
+        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, options) {
+        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, options) {
+        return ctx.runQuery(this.queries.detectActorSpam, {
+            timeWindowMs: options?.timeWindowMs ?? 3600000,
+            maxEmailsPerActor: options?.maxEmailsPerActor ?? 100,
+        });
+    }
+    /**
+     * Get email operation statistics for monitoring
+     */
+    async getEmailStats(ctx, options) {
+        return ctx.runQuery(this.queries.getEmailStats, {
+            timeWindowMs: options?.timeWindowMs ?? 86400000,
+        });
+    }
+    /**
+     * Detect rapid-fire email sending patterns
+     */
+    async detectRapidFirePatterns(ctx, options) {
+        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, options) {
+        return ctx.runQuery(this.queries.checkRecipientRateLimit, options);
+    }
+    /**
+     * Check if an actor/user can send more emails based on rate limits
+     */
+    async checkActorRateLimit(ctx, options) {
+        return ctx.runQuery(this.queries.checkActorRateLimit, options);
+    }
+    /**
+     * Check global email sending rate limit
+     */
+    async checkGlobalRateLimit(ctx, options) {
+        return ctx.runQuery(this.queries.checkGlobalRateLimit, options);
+    }
+    /**
+     * Delete a contact from Loops
+     */
+    async deleteContact(ctx, email) {
+        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, options) {
+        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, options) {
+        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);
+                },
+            }),
+        };
+    }
+}

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

@@ -0,0 +1,232 @@
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import type * as actions from "../actions.js";
+import type * as aggregates from "../aggregates.js";
+import type * as helpers from "../helpers.js";
+import type * as http from "../http.js";
+import type * as mutations from "../mutations.js";
+import type * as queries from "../queries.js";
+import type * as tables_contacts from "../tables/contacts.js";
+import type * as tables_emailOperations from "../tables/emailOperations.js";
+import type * as validators from "../validators.js";
+import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
+declare const fullApi: ApiFromModules<{
+    actions: typeof actions;
+    aggregates: typeof aggregates;
+    helpers: typeof helpers;
+    http: typeof http;
+    mutations: typeof mutations;
+    queries: typeof queries;
+    "tables/contacts": typeof tables_contacts;
+    "tables/emailOperations": typeof tables_emailOperations;
+    validators: typeof validators;
+}>;
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<typeof fullApi, FunctionReference<any, "public">>;
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<typeof fullApi, FunctionReference<any, "internal">>;
+export declare const components: {
+    contactAggregate: {
+        btree: {
+            aggregateBetween: FunctionReference<"query", "internal", {
+                k1?: any;
+                k2?: any;
+                namespace?: any;
+            }, {
+                count: number;
+                sum: number;
+            }>;
+            aggregateBetweenBatch: FunctionReference<"query", "internal", {
+                queries: Array<{
+                    k1?: any;
+                    k2?: any;
+                    namespace?: any;
+                }>;
+            }, Array<{
+                count: number;
+                sum: number;
+            }>>;
+            atNegativeOffset: FunctionReference<"query", "internal", {
+                k1?: any;
+                k2?: any;
+                namespace?: any;
+                offset: number;
+            }, {
+                k: any;
+                s: number;
+                v: any;
+            }>;
+            atOffset: FunctionReference<"query", "internal", {
+                k1?: any;
+                k2?: any;
+                namespace?: any;
+                offset: number;
+            }, {
+                k: any;
+                s: number;
+                v: any;
+            }>;
+            atOffsetBatch: FunctionReference<"query", "internal", {
+                queries: Array<{
+                    k1?: any;
+                    k2?: any;
+                    namespace?: any;
+                    offset: number;
+                }>;
+            }, Array<{
+                k: any;
+                s: number;
+                v: any;
+            }>>;
+            get: FunctionReference<"query", "internal", {
+                key: any;
+                namespace?: any;
+            }, null | {
+                k: any;
+                s: number;
+                v: any;
+            }>;
+            offset: FunctionReference<"query", "internal", {
+                k1?: any;
+                key: any;
+                namespace?: any;
+            }, number>;
+            offsetUntil: FunctionReference<"query", "internal", {
+                k2?: any;
+                key: any;
+                namespace?: any;
+            }, number>;
+            paginate: FunctionReference<"query", "internal", {
+                cursor?: string;
+                k1?: any;
+                k2?: any;
+                limit: number;
+                namespace?: any;
+                order: "asc" | "desc";
+            }, {
+                cursor: string;
+                isDone: boolean;
+                page: Array<{
+                    k: any;
+                    s: number;
+                    v: any;
+                }>;
+            }>;
+            paginateNamespaces: FunctionReference<"query", "internal", {
+                cursor?: string;
+                limit: number;
+            }, {
+                cursor: string;
+                isDone: boolean;
+                page: Array<any>;
+            }>;
+            validate: FunctionReference<"query", "internal", {
+                namespace?: any;
+            }, any>;
+        };
+        inspect: {
+            display: FunctionReference<"query", "internal", {
+                namespace?: any;
+            }, any>;
+            dump: FunctionReference<"query", "internal", {
+                namespace?: any;
+            }, string>;
+            inspectNode: FunctionReference<"query", "internal", {
+                namespace?: any;
+                node?: string;
+            }, null>;
+            listTreeNodes: FunctionReference<"query", "internal", {
+                take?: number;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                aggregate?: {
+                    count: number;
+                    sum: number;
+                };
+                items: Array<{
+                    k: any;
+                    s: number;
+                    v: any;
+                }>;
+                subtrees: Array<string>;
+            }>>;
+            listTrees: FunctionReference<"query", "internal", {
+                take?: number;
+            }, Array<{
+                _creationTime: number;
+                _id: string;
+                maxNodeSize: number;
+                namespace?: any;
+                root: string;
+            }>>;
+        };
+        public: {
+            clear: FunctionReference<"mutation", "internal", {
+                maxNodeSize?: number;
+                namespace?: any;
+                rootLazy?: boolean;
+            }, null>;
+            delete_: FunctionReference<"mutation", "internal", {
+                key: any;
+                namespace?: any;
+            }, null>;
+            deleteIfExists: FunctionReference<"mutation", "internal", {
+                key: any;
+                namespace?: any;
+            }, any>;
+            init: FunctionReference<"mutation", "internal", {
+                maxNodeSize?: number;
+                namespace?: any;
+                rootLazy?: boolean;
+            }, null>;
+            insert: FunctionReference<"mutation", "internal", {
+                key: any;
+                namespace?: any;
+                summand?: number;
+                value: any;
+            }, null>;
+            makeRootLazy: FunctionReference<"mutation", "internal", {
+                namespace?: any;
+            }, null>;
+            replace: FunctionReference<"mutation", "internal", {
+                currentKey: any;
+                namespace?: any;
+                newKey: any;
+                newNamespace?: any;
+                summand?: number;
+                value: any;
+            }, null>;
+            replaceOrInsert: FunctionReference<"mutation", "internal", {
+                currentKey: any;
+                namespace?: any;
+                newKey: any;
+                newNamespace?: any;
+                summand?: number;
+                value: any;
+            }, any>;
+        };
+    };
+};
+export {};
+//# sourceMappingURL=api.d.ts.map