@vllnt/convex-email 0.1.0-canary.63aca6b

package/src/component/_generated/api.ts

@@ -0,0 +1,56 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as crons from "../crons.js";
+import type * as mutations from "../mutations.js";
+import type * as queries from "../queries.js";
+import type * as validators from "../validators.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  crons: typeof crons;
+  mutations: typeof mutations;
+  queries: typeof queries;
+  validators: typeof validators;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,134 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    mutations: {
+      enqueue: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          from: string;
+          idempotencyKey?: string;
+          maxAttempts: number;
+          messageId: string;
+          payload?: any;
+          subjectRef?: string;
+          to: string;
+          transport: string;
+        },
+        { deduplicated: boolean; messageId: string },
+        Name
+      >;
+      markSending: FunctionReference<
+        "mutation",
+        "internal",
+        { messageId: string },
+        { attempts: number },
+        Name
+      >;
+      markSent: FunctionReference<
+        "mutation",
+        "internal",
+        { messageId: string; providerId?: string },
+        null,
+        Name
+      >;
+      markFailed: FunctionReference<
+        "mutation",
+        "internal",
+        { error?: string; messageId: string },
+        { retried: boolean; status: "queued" | "failed" },
+        Name
+      >;
+      prune: FunctionReference<
+        "mutation",
+        "internal",
+        { batch: number; before?: number },
+        number,
+        Name
+      >;
+    };
+    queries: {
+      get: FunctionReference<
+        "query",
+        "internal",
+        { messageId: string },
+        null | {
+          attempts: number;
+          createdAt: number;
+          error?: string;
+          from: string;
+          idempotencyKey?: string;
+          maxAttempts: number;
+          messageId: string;
+          payload?: any;
+          providerId?: string;
+          status: "queued" | "sending" | "sent" | "failed";
+          subjectRef?: string;
+          to: string;
+          transport: string;
+          updatedAt: number;
+        },
+        Name
+      >;
+      listByStatus: FunctionReference<
+        "query",
+        "internal",
+        {
+          paginationOpts: {
+            cursor: string | null;
+            endCursor?: string | null;
+            id?: number;
+            maximumBytesRead?: number;
+            maximumRowsRead?: number;
+            numItems: number;
+          };
+          status: "queued" | "sending" | "sent" | "failed";
+        },
+        {
+          continueCursor: string;
+          isDone: boolean;
+          page: Array<{
+            attempts: number;
+            createdAt: number;
+            error?: string;
+            from: string;
+            idempotencyKey?: string;
+            maxAttempts: number;
+            messageId: string;
+            payload?: any;
+            providerId?: string;
+            status: "queued" | "sending" | "sent" | "failed";
+            subjectRef?: string;
+            to: string;
+            transport: string;
+            updatedAt: number;
+          }>;
+          pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+          splitCursor?: string | null;
+        },
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/component/_generated/server.ts

@@ -0,0 +1,156 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,9 @@
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("email");
+
+// Nest official child components here, e.g.:
+// import rateLimiter from "@convex-dev/rate-limiter/convex.config";
+// component.use(rateLimiter);
+
+export default component;

package/src/component/crons.ts

@@ -0,0 +1,23 @@
+import { cronJobs } from "convex/server";
+import { api } from "./_generated/api";
+
+/**
+ * Default sweep cadence and page size for the built-in prune cron. The cron is
+ * the component's own self-healing safety net — a host that wants a different
+ * cadence drives `prune` from its own scheduler instead (the client exposes it).
+ * Convex cron definitions are static per deployment, so cadence is a documented
+ * module constant rather than a mount-time option; the page size bounds each
+ * sweep and `prune` self-reschedules until the terminal tail is clean.
+ */
+export const PRUNE_INTERVAL = { hours: 24 } as const;
+
+/** Rows deleted per `prune` pass before the sweep self-reschedules. */
+export const PRUNE_BATCH = 200;
+
+const crons = cronJobs();
+
+crons.interval("email:prune", PRUNE_INTERVAL, api.mutations.prune, {
+  batch: PRUNE_BATCH,
+});
+
+export default crons;

package/src/component/mutations.ts

@@ -0,0 +1,262 @@
+import { ConvexError, v } from "convex/values";
+import { api } from "./_generated/api";
+import { mutation } from "./_generated/server";
+import { jsonValue } from "./validators";
+
+/**
+ * Enqueue an outbound message and return its id immediately — the durable queue
+ * entry. The message is inserted in `queued` state with `attempts: 0`,
+ * `createdAt`/`updatedAt` stamped from the server clock (`Date.now()` inside the
+ * handler — never caller-supplied). The host owns the meaning of `to`/`from`, the
+ * opaque `payload`, and the `transport` adapter name — the component records the
+ * intent and never calls any provider. A transport sender later claims the
+ * message ({@link markSending}) and reports the outcome ({@link markSent} /
+ * {@link markFailed}).
+ *
+ * `messageId` is host-supplied (the host names its own message). The id must be
+ * unique — re-using an existing id throws
+ * `ConvexError({ code: "DUPLICATE_MESSAGE" })`. When `idempotencyKey` is supplied
+ * and a message already carries it, the existing message's id is returned and no
+ * new row is inserted — a retried enqueue (double-submit, at-least-once delivery)
+ * can never produce a duplicate send.
+ */
+export const enqueue = mutation({
+  args: {
+    messageId: v.string(),
+    to: v.string(),
+    from: v.string(),
+    transport: v.string(),
+    payload: v.optional(jsonValue),
+    subjectRef: v.optional(v.string()),
+    idempotencyKey: v.optional(v.string()),
+    maxAttempts: v.number(),
+  },
+  returns: v.object({ messageId: v.string(), deduplicated: v.boolean() }),
+  handler: async (ctx, args) => {
+    if (args.idempotencyKey !== undefined) {
+      const dupe = await ctx.db
+        .query("messages")
+        .withIndex("by_idempotency_key", (q) =>
+          q.eq("idempotencyKey", args.idempotencyKey),
+        )
+        .unique();
+      if (dupe !== null) {
+        return { messageId: dupe.messageId, deduplicated: true };
+      }
+    }
+
+    const existing = await ctx.db
+      .query("messages")
+      .withIndex("by_message_id", (q) => q.eq("messageId", args.messageId))
+      .unique();
+    if (existing !== null) {
+      throw new ConvexError({
+        code: "DUPLICATE_MESSAGE",
+        message: `message "${args.messageId}" already exists`,
+      });
+    }
+
+    const now = Date.now();
+    await ctx.db.insert("messages", {
+      messageId: args.messageId,
+      to: args.to,
+      from: args.from,
+      transport: args.transport,
+      status: "queued",
+      payload: args.payload,
+      subjectRef: args.subjectRef,
+      idempotencyKey: args.idempotencyKey,
+      attempts: 0,
+      maxAttempts: args.maxAttempts,
+      createdAt: now,
+      updatedAt: now,
+    });
+    return { messageId: args.messageId, deduplicated: false };
+  },
+});
+
+/**
+ * Claim a `queued` message for a send attempt: move it to `sending` and increment
+ * `attempts`. A transport sender calls this before dispatching, so concurrent
+ * flushers don't double-send the same row. Re-claiming an already-`sending`
+ * message is rejected (another sender owns it). A terminal message is rejected.
+ *
+ * @throws `ConvexError({ code: "NOT_FOUND" })` when no message has `messageId`.
+ * @throws `ConvexError({ code: "TERMINAL_STATE" })` when the message is terminal.
+ * @throws `ConvexError({ code: "INVALID_TRANSITION" })` when the message is
+ *   already `sending` (claimed by another sender).
+ */
+export const markSending = mutation({
+  args: { messageId: v.string() },
+  returns: v.object({ attempts: v.number() }),
+  handler: async (ctx, args) => {
+    const msg = await ctx.db
+      .query("messages")
+      .withIndex("by_message_id", (q) => q.eq("messageId", args.messageId))
+      .unique();
+    if (msg === null) {
+      throw new ConvexError({
+        code: "NOT_FOUND",
+        message: `message "${args.messageId}" not found`,
+      });
+    }
+    if (msg.status === "sent" || msg.status === "failed") {
+      throw new ConvexError({
+        code: "TERMINAL_STATE",
+        message: `message "${args.messageId}" is already ${msg.status} and cannot transition`,
+      });
+    }
+    if (msg.status === "sending") {
+      throw new ConvexError({
+        code: "INVALID_TRANSITION",
+        message: `message "${args.messageId}" is already sending`,
+      });
+    }
+
+    const attempts = msg.attempts + 1;
+    await ctx.db.patch(msg._id, {
+      status: "sending",
+      attempts,
+      updatedAt: Date.now(),
+    });
+    return { attempts };
+  },
+});
+
+/**
+ * Record a successful send — the message moves to terminal `sent`, recording the
+ * transport's own `providerId` (its message handle, opaque to the component) and
+ * clearing any prior `error`. Idempotent against a replayed callback: re-marking
+ * an already-`sent` message is a no-op (the recorded `providerId` is preserved).
+ * Any other terminal state (`failed`) is rejected — a `failed` message is final.
+ *
+ * @throws `ConvexError({ code: "NOT_FOUND" })` when no message has `messageId`.
+ * @throws `ConvexError({ code: "TERMINAL_STATE" })` when the message is already
+ *   `failed` (a final state may not be transitioned out of).
+ */
+export const markSent = mutation({
+  args: { messageId: v.string(), providerId: v.optional(v.string()) },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const msg = await ctx.db
+      .query("messages")
+      .withIndex("by_message_id", (q) => q.eq("messageId", args.messageId))
+      .unique();
+    if (msg === null) {
+      throw new ConvexError({
+        code: "NOT_FOUND",
+        message: `message "${args.messageId}" not found`,
+      });
+    }
+    if (msg.status === "sent") {
+      return null;
+    }
+    if (msg.status === "failed") {
+      throw new ConvexError({
+        code: "TERMINAL_STATE",
+        message: `message "${args.messageId}" is already failed and cannot transition`,
+      });
+    }
+
+    await ctx.db.patch(msg._id, {
+      status: "sent",
+      providerId: args.providerId,
+      error: undefined,
+      updatedAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+/**
+ * Record a failed send attempt, recording the host-supplied `error`. The outcome
+ * depends on the retry budget: if `attempts < maxAttempts` the message returns to
+ * `queued` for another attempt (`retried: true`); once attempts are exhausted it
+ * lands in terminal `failed` (`retried: false`). The host's backoff scheduler
+ * re-claims a re-queued message when ready. An already-`sent` message is rejected
+ * (it succeeded); an already-`failed` message is rejected (it is terminal).
+ *
+ * @throws `ConvexError({ code: "NOT_FOUND" })` when no message has `messageId`.
+ * @throws `ConvexError({ code: "TERMINAL_STATE" })` when the message is already
+ *   `sent` or `failed`.
+ */
+export const markFailed = mutation({
+  args: { messageId: v.string(), error: v.optional(v.string()) },
+  returns: v.object({ status: v.union(v.literal("queued"), v.literal("failed")), retried: v.boolean() }),
+  handler: async (ctx, args) => {
+    const msg = await ctx.db
+      .query("messages")
+      .withIndex("by_message_id", (q) => q.eq("messageId", args.messageId))
+      .unique();
+    if (msg === null) {
+      throw new ConvexError({
+        code: "NOT_FOUND",
+        message: `message "${args.messageId}" not found`,
+      });
+    }
+    if (msg.status === "sent" || msg.status === "failed") {
+      throw new ConvexError({
+        code: "TERMINAL_STATE",
+        message: `message "${args.messageId}" is already ${msg.status} and cannot transition`,
+      });
+    }
+
+    const retried = msg.attempts < msg.maxAttempts;
+    const status = retried ? ("queued" as const) : ("failed" as const);
+    await ctx.db.patch(msg._id, {
+      status,
+      error: args.error,
+      updatedAt: Date.now(),
+    });
+    return { status, retried };
+  },
+});
+
+/**
+ * Delete up to `batch` terminal messages whose `updatedAt < before`, oldest first
+ * — `sent` then `failed`, each via the `by_status_updated` index. `before`
+ * defaults to the server clock (`Date.now()`) when omitted, so the built-in cron
+ * sweeps exactly the messages terminal-and-stale as of the run. If a full batch
+ * was removed there may be more, so the sweep self-reschedules through
+ * `ctx.scheduler` until a short batch signals the tail is clean. Idempotent: only
+ * ever removes already-terminal, past-retention rows. Queued and sending messages
+ * are never pruned.
+ */
+export const prune = mutation({
+  args: { before: v.optional(v.number()), batch: v.number() },
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    const before = args.before ?? Date.now();
+
+    // Both terminal states, queried explicitly (no query-in-loop): sent first,
+    // then failed for whatever batch budget remains.
+    const sent = await ctx.db
+      .query("messages")
+      .withIndex("by_status_updated", (q) =>
+        q.eq("status", "sent").lt("updatedAt", before),
+      )
+      .take(args.batch);
+    const failed =
+      sent.length < args.batch
+        ? await ctx.db
+            .query("messages")
+            .withIndex("by_status_updated", (q) =>
+              q.eq("status", "failed").lt("updatedAt", before),
+            )
+            .take(args.batch - sent.length)
+        : [];
+
+    for (const row of [...sent, ...failed]) {
+      await ctx.db.delete(row._id);
+    }
+    const removed = sent.length + failed.length;
+
+    if (removed === args.batch) {
+      await ctx.scheduler.runAfter(0, api.mutations.prune, {
+        before,
+        batch: args.batch,
+      });
+    }
+    return removed;
+  },
+});