@niama/loops 0.2.0

package/dist/component/validators.js

@@ -0,0 +1,167 @@
+import { v } from "convex/values";
+/**
+ * Validators for Loops API requests and component operations
+ */
+/**
+ * Validator for contact data
+ * Used for creating and updating contacts
+ */
+export const contactValidator = 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()),
+});
+/**
+ * Validator for transactional email requests
+ */
+export const transactionalEmailValidator = v.object({
+    transactionalId: v.optional(v.string()),
+    email: v.string(),
+    dataVariables: v.optional(v.record(v.string(), v.any())),
+    idempotencyKey: v.optional(v.string()),
+});
+/**
+ * Validator for event requests
+ * Used for sending events that trigger email workflows
+ */
+export const eventValidator = v.object({
+    email: v.string(),
+    eventName: v.string(),
+    eventProperties: v.optional(v.record(v.string(), v.any())),
+});
+/**
+ * Validator for operation type enum
+ */
+export const operationTypeValidator = v.union(v.literal("transactional"), v.literal("event"), v.literal("campaign"), v.literal("loop"));
+/**
+ * Common return validators used across functions
+ */
+export const successResponseValidator = v.object({
+    success: v.boolean(),
+});
+export const successWithIdResponseValidator = v.object({
+    success: v.boolean(),
+    id: v.optional(v.string()),
+});
+export const successWithMessageIdResponseValidator = v.object({
+    success: v.boolean(),
+    messageId: v.optional(v.string()),
+});
+export const successWithWarningResponseValidator = v.object({
+    success: v.boolean(),
+    warning: v.optional(v.string()),
+});
+/**
+ * Contact document validator for query returns
+ */
+export const contactDocValidator = v.object({
+    _id: v.string(),
+    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.boolean(),
+    userGroup: v.optional(v.string()),
+    loopsContactId: v.optional(v.string()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+/**
+ * Paginated contacts response validator
+ */
+export const paginatedContactsResponseValidator = v.object({
+    contacts: v.array(contactDocValidator),
+    continueCursor: v.union(v.string(), v.null()),
+    isDone: v.boolean(),
+});
+/**
+ * Rate limit response validator
+ */
+export const rateLimitResponseValidator = v.object({
+    allowed: v.boolean(),
+    count: v.number(),
+    limit: v.number(),
+    timeWindowMs: v.number(),
+    retryAfter: v.optional(v.number()),
+});
+/**
+ * Email stats response validator
+ */
+export const emailStatsResponseValidator = v.object({
+    totalOperations: v.number(),
+    successfulOperations: v.number(),
+    failedOperations: v.number(),
+    operationsByType: v.record(v.string(), v.number()),
+    uniqueRecipients: v.number(),
+    uniqueActors: v.number(),
+});
+/**
+ * Spam detection validators
+ */
+export const recipientSpamValidator = v.object({
+    email: v.string(),
+    count: v.number(),
+    timeWindowMs: v.number(),
+});
+export const actorSpamValidator = v.object({
+    actorId: v.string(),
+    count: v.number(),
+    timeWindowMs: v.number(),
+});
+export const rapidFirePatternValidator = v.object({
+    email: v.optional(v.string()),
+    actorId: v.optional(v.string()),
+    count: v.number(),
+    timeWindowMs: v.number(),
+    firstTimestamp: v.number(),
+    lastTimestamp: v.number(),
+});
+/**
+ * Batch create response validator
+ */
+export const batchCreateResponseValidator = v.object({
+    success: v.boolean(),
+    created: v.optional(v.number()),
+    failed: v.optional(v.number()),
+    results: v.optional(v.array(v.object({
+        email: v.string(),
+        success: v.boolean(),
+        error: v.optional(v.string()),
+    }))),
+});
+/**
+ * Find contact response validator
+ * Note: Loops API returns additional fields beyond our contact model
+ */
+export const findContactResponseValidator = v.object({
+    success: v.boolean(),
+    contact: v.optional(v.object({
+        id: v.optional(v.union(v.string(), v.null())),
+        email: v.optional(v.union(v.string(), v.null())),
+        firstName: v.optional(v.union(v.string(), v.null())),
+        lastName: v.optional(v.union(v.string(), v.null())),
+        source: v.optional(v.union(v.string(), v.null())),
+        subscribed: v.optional(v.union(v.boolean(), v.null())),
+        userGroup: v.optional(v.union(v.string(), v.null())),
+        userId: v.optional(v.union(v.string(), v.null())),
+        createdAt: v.optional(v.union(v.string(), v.null())),
+        // Additional fields from Loops API
+        audienceId: v.optional(v.union(v.string(), v.null())),
+        timestamp: v.optional(v.union(v.string(), v.null())),
+        dataVariables: v.optional(v.any()),
+        mailingLists: v.optional(v.any()),
+    })),
+});
+/**
+ * Backfill response validator
+ */
+export const backfillResponseValidator = v.object({
+    processed: v.number(),
+    cursor: v.union(v.string(), v.null()),
+    isDone: v.boolean(),
+});

package/dist/test.d.ts

@@ -0,0 +1,78 @@
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+/**
+ * Register the Loops component with the test convex instance.
+ *
+ * @param t - The test convex instance from convexTest().
+ * @param name - The name of the component as registered in convex.config.ts.
+ * @param modules - The modules object from import.meta.glob. Required.
+ */
+export declare function register(t: TestConvex<SchemaDefinition<GenericSchema, boolean>>, name?: string, modules?: Record<string, () => Promise<unknown>>): void;
+export { schema };
+declare const _default: {
+    register: typeof register;
+    schema: SchemaDefinition<{
+        contacts: import("convex/server").TableDefinition<import("convex/values").VObject<{
+            firstName?: string | undefined;
+            lastName?: string | undefined;
+            userId?: string | undefined;
+            source?: string | undefined;
+            subscribed?: boolean | undefined;
+            userGroup?: string | undefined;
+            loopsContactId?: string | undefined;
+            email: string;
+            createdAt: number;
+            updatedAt: number;
+        }, {
+            email: import("convex/values").VString<string, "required">;
+            firstName: import("convex/values").VString<string | undefined, "optional">;
+            lastName: import("convex/values").VString<string | undefined, "optional">;
+            userId: import("convex/values").VString<string | undefined, "optional">;
+            source: import("convex/values").VString<string | undefined, "optional">;
+            subscribed: import("convex/values").VBoolean<boolean | undefined, "optional">;
+            userGroup: import("convex/values").VString<string | undefined, "optional">;
+            loopsContactId: import("convex/values").VString<string | undefined, "optional">;
+            createdAt: import("convex/values").VFloat64<number, "required">;
+            updatedAt: import("convex/values").VFloat64<number, "required">;
+        }, "required", "email" | "firstName" | "lastName" | "userId" | "source" | "subscribed" | "userGroup" | "loopsContactId" | "createdAt" | "updatedAt">, {
+            email: ["email", "_creationTime"];
+            userId: ["userId", "_creationTime"];
+            userGroup: ["userGroup", "_creationTime"];
+            source: ["source", "_creationTime"];
+            subscribed: ["subscribed", "_creationTime"];
+        }, {}, {}>;
+        emailOperations: import("convex/server").TableDefinition<import("convex/values").VObject<{
+            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";
+            timestamp: number;
+            success: boolean;
+        }, {
+            operationType: import("convex/values").VUnion<"transactional" | "event" | "campaign" | "loop", [import("convex/values").VLiteral<"transactional", "required">, import("convex/values").VLiteral<"event", "required">, import("convex/values").VLiteral<"campaign", "required">, import("convex/values").VLiteral<"loop", "required">], "required", never>;
+            email: import("convex/values").VString<string, "required">;
+            actorId: import("convex/values").VString<string | undefined, "optional">;
+            transactionalId: import("convex/values").VString<string | undefined, "optional">;
+            campaignId: import("convex/values").VString<string | undefined, "optional">;
+            loopId: import("convex/values").VString<string | undefined, "optional">;
+            eventName: import("convex/values").VString<string | undefined, "optional">;
+            timestamp: import("convex/values").VFloat64<number, "required">;
+            success: import("convex/values").VBoolean<boolean, "required">;
+            messageId: import("convex/values").VString<string | undefined, "optional">;
+            metadata: import("convex/values").VRecord<Record<string, any> | undefined, import("convex/values").VString<string, "required">, import("convex/values").VAny<any, "required", string>, "optional", string>;
+        }, "required", "email" | "operationType" | "actorId" | "transactionalId" | "campaignId" | "loopId" | "eventName" | "timestamp" | "success" | "messageId" | "metadata" | `metadata.${string}`>, {
+            email: ["email", "timestamp", "_creationTime"];
+            actorId: ["actorId", "timestamp", "_creationTime"];
+            operationType: ["operationType", "timestamp", "_creationTime"];
+            timestamp: ["timestamp", "_creationTime"];
+        }, {}, {}>;
+    }, true>;
+};
+export default _default;
+//# sourceMappingURL=test.d.ts.map

package/dist/test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../src/test.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,MAAM,MAAM,uBAAuB,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACvB,CAAC,EAAE,UAAU,CAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,EACvD,IAAI,GAAE,MAAgB,EACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,QAQhD;AAED,OAAO,EAAE,MAAM,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAElB,wBAAoC"}

package/dist/test.js

@@ -0,0 +1,16 @@
+import schema from "./component/schema.js";
+/**
+ * Register the Loops component with the test convex instance.
+ *
+ * @param t - The test convex instance from convexTest().
+ * @param name - The name of the component as registered in convex.config.ts.
+ * @param modules - The modules object from import.meta.glob. Required.
+ */
+export function register(t, name = "loops", modules) {
+    if (!modules) {
+        throw new Error("modules parameter is required. Pass import.meta.glob from your test file.");
+    }
+    t.registerComponent(name, schema, modules);
+}
+export { schema };
+export default { register, schema };

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+import type { GenericActionCtx, GenericDataModel, GenericMutationCtx, GenericQueryCtx } from "convex/server";
+export type RunQueryCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+export type RunMutationCtx = Pick<GenericMutationCtx<GenericDataModel>, "runQuery" | "runMutation">;
+export type RunActionCtx = Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation" | "runAction">;
+export type HeadersInitParam = ConstructorParameters<typeof Headers>[0];
+export interface ContactPayload {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    userId?: string;
+    source?: string;
+    subscribed?: boolean;
+    userGroup?: string;
+}
+export interface UpdateContactPayload extends Partial<ContactPayload> {
+    email: string;
+    dataVariables?: Record<string, unknown>;
+}
+export interface DeleteContactPayload {
+    email?: string;
+}
+export interface TransactionalPayload {
+    transactionalId?: string;
+    email?: string;
+    dataVariables?: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+export interface EventPayload {
+    email?: string;
+    eventName?: string;
+    eventProperties?: Record<string, unknown>;
+}
+export interface TriggerPayload {
+    loopId?: string;
+    email?: string;
+    dataVariables?: Record<string, unknown>;
+    eventName?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,MAAM,eAAe,CAAC;AAGvB,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,UAAU,CAAC,CAAC;AAE9E,MAAM,MAAM,cAAc,GAAG,IAAI,CAChC,kBAAkB,CAAC,gBAAgB,CAAC,EACpC,UAAU,GAAG,aAAa,CAC1B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,IAAI,CAC9B,gBAAgB,CAAC,gBAAgB,CAAC,EAClC,UAAU,GAAG,aAAa,GAAG,WAAW,CACxC,CAAC;AAGF,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAGxE,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAqB,SAAQ,OAAO,CAAC,cAAc,CAAC;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/package.json

@@ -0,0 +1,112 @@
+{
+	"name": "@niama/loops",
+	"version": "0.2.0",
+	"description": "Convex component for integrating with Loops.so email marketing platform",
+	"license": "Apache-2.0",
+	"type": "module",
+	"main": "dist/client/index.js",
+	"types": "dist/client/index.d.ts",
+	"keywords": [
+		"convex",
+		"component",
+		"loops",
+		"loops.so",
+		"email",
+		"email-marketing",
+		"transactional-email",
+		"newsletter",
+		"typescript"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/robertalv/loops.git"
+	},
+	"bugs": {
+		"url": "https://github.com/robertalv/loops/issues"
+	},
+	"homepage": "https://github.com/robertalv/loops#readme",
+	"files": [
+		"dist",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"exports": {
+		"./package.json": "./package.json",
+		".": {
+			"types": "./dist/client/index.d.ts",
+			"default": "./dist/client/index.js"
+		},
+		"./convex.config": {
+			"types": "./dist/component/convex.config.d.ts",
+			"default": "./dist/component/convex.config.js"
+		},
+		"./convex.config.js": {
+			"types": "./dist/component/convex.config.d.ts",
+			"default": "./dist/component/convex.config.js"
+		},
+		"./_generated/component": {
+			"types": "./dist/component/_generated/component.d.ts"
+		},
+		"./_generated/component.js": {
+			"types": "./dist/component/_generated/component.d.ts"
+		},
+		"./test": "./src/test.ts"
+	},
+	"scripts": {
+		"dev": "run-p -r 'dev:backend' 'dev:frontend' 'build:watch'",
+		"dev:backend": "convex dev --live-component-sources --typecheck-components",
+		"dev:frontend": "bun --hot example/src/index.tsx",
+		"build": "tsc --project tsconfig.build.json",
+		"build:watch": "chokidar 'tsconfig*.json' 'src/**/*.ts' -i '**/*.test.*' -i '**/test-setup.ts' -c 'bun run build' --initial",
+		"clean": "rm -rf dist node_modules",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
+		"test:coverage": "bun test --coverage",
+		"test:bail": "bun test --bail",
+		"lint": "biome lint .",
+		"lint:fix": "biome lint --write .",
+		"format": "biome format --write .",
+		"check": "biome check .",
+		"check:fix": "biome check --write .",
+		"typecheck": "tsc --noEmit",
+		"attw": "attw $(npm pack -s) --exclude-entrypoints ./convex.config ./test --profile esm-only --ignore-rules internal-resolution-error",
+		"prepare": "npm run build || true",
+		"changeset": "changeset",
+		"ci:version": "changeset version && bun update",
+		"ci:publish": "changeset publish",
+		"preversion": "bun run clean && bun install && run-p test lint typecheck attw",
+		"version": "pbcopy <<<$npm_package_version; vim CHANGELOG.md && biome format --write CHANGELOG.md && git add CHANGELOG.md",
+		"postversion": "git push --follow-tags",
+		"alpha": "bun run preversion && npm version prerelease --preid alpha && npm publish --tag alpha",
+		"release": "bun run preversion && npm version patch && npm publish"
+	},
+	"dependencies": {
+		"@convex-dev/aggregate": "^0.2.1"
+	},
+	"peerDependencies": {
+		"convex": "^1.0.0"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.2",
+		"@biomejs/biome": "2.3.0",
+		"@changesets/changelog-github": "^0.5.1",
+		"@changesets/cli": "^2.29.7",
+		"@commitlint/cli": "^20.1.0",
+		"@commitlint/types": "^20.0.0",
+		"@types/bun": "^1.3.1",
+		"@types/react": "^19.2.2",
+		"@types/react-dom": "^19.2.2",
+		"bun-plugin-tailwind": "^0.1.2",
+		"chokidar-cli": "^3.0.0",
+		"commitlint-config-gitmoji": "^2.3.1",
+		"convex": "^1.28.0",
+		"convex-helpers": "^0.1.104",
+		"convex-test": "^0.0.38",
+		"npm-run-all": "^4.1.5",
+		"pkg-pr-new": "^0.0.60",
+		"react": "^19.2.0",
+		"react-dom": "^19.2.0",
+		"tailwindcss": "^4.1.16"
+	}
+}