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

package/dist/component/mutations.js

@@ -0,0 +1,243 @@
+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" : "failed";
+        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;
+    },
+});
+//# sourceMappingURL=mutations.js.map

package/dist/component/mutations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.js","sourceRoot":"","sources":["../../src/component/mutations.ts"],"names":[],"mappings":"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"}

package/dist/component/queries.d.ts

@@ -0,0 +1,59 @@
+/** The current envelope for one message, or `null` if no such id is held. */
+export declare const get: import("convex/server").RegisteredQuery<"public", {
+    messageId: string;
+}, Promise<{
+    messageId: string;
+    to: string;
+    from: string;
+    transport: string;
+    status: "queued" | "sending" | "sent" | "failed";
+    payload: any;
+    subjectRef: string | undefined;
+    idempotencyKey: string | undefined;
+    providerId: string | undefined;
+    attempts: number;
+    maxAttempts: number;
+    error: string | undefined;
+    createdAt: number;
+    updatedAt: number;
+} | null>>;
+/**
+ * Page messages in one `status`, oldest first via the `by_status` index. Takes
+ * the standard Convex `paginationOpts` and returns the standard paginated
+ * envelope (`page`, `isDone`, `continueCursor`) so the host can poll the
+ * `queued` backlog to flush, watch `sending`, or audit a terminal `sent`/`failed`
+ * history reactively.
+ */
+export declare const listByStatus: import("convex/server").RegisteredQuery<"public", {
+    status: "queued" | "sending" | "sent" | "failed";
+    paginationOpts: {
+        id?: number;
+        endCursor?: string | null;
+        maximumRowsRead?: number;
+        maximumBytesRead?: number;
+        numItems: number;
+        cursor: string | null;
+    };
+}, Promise<{
+    page: {
+        messageId: string;
+        to: string;
+        from: string;
+        transport: string;
+        status: "queued" | "sending" | "sent" | "failed";
+        payload: any;
+        subjectRef: string | undefined;
+        idempotencyKey: string | undefined;
+        providerId: string | undefined;
+        attempts: number;
+        maxAttempts: number;
+        error: string | undefined;
+        createdAt: number;
+        updatedAt: number;
+    }[];
+    isDone: boolean;
+    continueCursor: import("convex/server").Cursor;
+    splitCursor?: import("convex/server").Cursor | null;
+    pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+}>>;
+//# sourceMappingURL=queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/component/queries.ts"],"names":[],"mappings":"AA0BA,6EAA6E;AAC7E,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;UAUd,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuBvB,CAAC"}

package/dist/component/queries.js

@@ -0,0 +1,61 @@
+import { v } from "convex/values";
+import { paginationOptsValidator } from "convex/server";
+import { query } from "./_generated/server";
+import { messageStatus, messageView } from "./validators";
+/** Project a stored message row to its public view (drops internal fields). */
+function view(msg) {
+    return {
+        messageId: msg.messageId,
+        to: msg.to,
+        from: msg.from,
+        transport: msg.transport,
+        status: msg.status,
+        payload: msg.payload,
+        subjectRef: msg.subjectRef,
+        idempotencyKey: msg.idempotencyKey,
+        providerId: msg.providerId,
+        attempts: msg.attempts,
+        maxAttempts: msg.maxAttempts,
+        error: msg.error,
+        createdAt: msg.createdAt,
+        updatedAt: msg.updatedAt,
+    };
+}
+/** The current envelope for one message, or `null` if no such id is held. */
+export const get = query({
+    args: { messageId: v.string() },
+    returns: v.union(v.null(), messageView),
+    handler: async (ctx, args) => {
+        const msg = await ctx.db
+            .query("messages")
+            .withIndex("by_message_id", (q) => q.eq("messageId", args.messageId))
+            .unique();
+        return msg === null ? null : view(msg);
+    },
+});
+/**
+ * Page messages in one `status`, oldest first via the `by_status` index. Takes
+ * the standard Convex `paginationOpts` and returns the standard paginated
+ * envelope (`page`, `isDone`, `continueCursor`) so the host can poll the
+ * `queued` backlog to flush, watch `sending`, or audit a terminal `sent`/`failed`
+ * history reactively.
+ */
+export const listByStatus = query({
+    args: { status: messageStatus, paginationOpts: paginationOptsValidator },
+    returns: v.object({
+        page: v.array(messageView),
+        isDone: v.boolean(),
+        continueCursor: v.string(),
+        splitCursor: v.optional(v.union(v.string(), v.null())),
+        pageStatus: v.optional(v.union(v.literal("SplitRecommended"), v.literal("SplitRequired"), v.null())),
+    }),
+    handler: async (ctx, args) => {
+        const result = await ctx.db
+            .query("messages")
+            .withIndex("by_status", (q) => q.eq("status", args.status))
+            .order("asc")
+            .paginate(args.paginationOpts);
+        return { ...result, page: result.page.map(view) };
+    },
+});
+//# sourceMappingURL=queries.js.map

package/dist/component/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/component/queries.ts"],"names":[],"mappings":"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"}

package/dist/component/schema.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Sandboxed table — the outbound-email queue's own concern. A `messageId` is a
+ * host-opaque string that uniquely names one queued message; `to`/`from` are the
+ * opaque envelope addresses; `transport` names the host-configured adapter (never
+ * a baked-in vendor); `status` tracks the lifecycle. `payload` carries the opaque
+ * rendered message host data (never inspected). `subjectRef` is an opaque host
+ * ref (e.g. the addressee subject) for subject-centric listing; `idempotencyKey`
+ * deduplicates double-enqueue; `attempts`/`maxAttempts` drive retry-vs-terminal.
+ *
+ * Indexes: `by_message_id` (lookup), `by_idempotency_key` (dedup), `by_status`
+ * (poll a status queue oldest-first), `by_subject` (subject-centric listing), and
+ * `by_status_updated` (retention sweep — prune terminal rows oldest-first).
+ */
+declare const _default: import("convex/server").SchemaDefinition<{
+    messages: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        payload?: any;
+        subjectRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        providerId?: string | undefined;
+        error?: string | undefined;
+        messageId: string;
+        to: string;
+        from: string;
+        transport: string;
+        maxAttempts: number;
+        status: "queued" | "sending" | "sent" | "failed";
+        attempts: number;
+        createdAt: number;
+        updatedAt: number;
+    }, {
+        messageId: import("convex/values").VString<string, "required">;
+        to: import("convex/values").VString<string, "required">;
+        from: import("convex/values").VString<string, "required">;
+        transport: import("convex/values").VString<string, "required">;
+        status: import("convex/values").VUnion<"queued" | "sending" | "sent" | "failed", [import("convex/values").VLiteral<"queued", "required">, import("convex/values").VLiteral<"sending", "required">, import("convex/values").VLiteral<"sent", "required">, import("convex/values").VLiteral<"failed", "required">], "required", never>;
+        payload: import("convex/values").VAny<any, "optional", string>;
+        subjectRef: import("convex/values").VString<string | undefined, "optional">;
+        idempotencyKey: import("convex/values").VString<string | undefined, "optional">;
+        providerId: import("convex/values").VString<string | undefined, "optional">;
+        attempts: import("convex/values").VFloat64<number, "required">;
+        maxAttempts: import("convex/values").VFloat64<number, "required">;
+        error: import("convex/values").VString<string | undefined, "optional">;
+        createdAt: import("convex/values").VFloat64<number, "required">;
+        updatedAt: import("convex/values").VFloat64<number, "required">;
+    }, "required", "messageId" | "to" | "from" | "transport" | "payload" | "subjectRef" | "idempotencyKey" | "maxAttempts" | "providerId" | "error" | "status" | "attempts" | "createdAt" | "updatedAt" | `payload.${string}`>, {
+        by_message_id: ["messageId", "_creationTime"];
+        by_idempotency_key: ["idempotencyKey", "_creationTime"];
+        by_status: ["status", "createdAt", "_creationTime"];
+        by_subject: ["subjectRef", "createdAt", "_creationTime"];
+        by_status_updated: ["status", "updatedAt", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACH,wBAsBG"}

package/dist/component/schema.js

@@ -0,0 +1,40 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+import { jsonValue, messageStatus } from "./validators";
+/**
+ * Sandboxed table — the outbound-email queue's own concern. A `messageId` is a
+ * host-opaque string that uniquely names one queued message; `to`/`from` are the
+ * opaque envelope addresses; `transport` names the host-configured adapter (never
+ * a baked-in vendor); `status` tracks the lifecycle. `payload` carries the opaque
+ * rendered message host data (never inspected). `subjectRef` is an opaque host
+ * ref (e.g. the addressee subject) for subject-centric listing; `idempotencyKey`
+ * deduplicates double-enqueue; `attempts`/`maxAttempts` drive retry-vs-terminal.
+ *
+ * Indexes: `by_message_id` (lookup), `by_idempotency_key` (dedup), `by_status`
+ * (poll a status queue oldest-first), `by_subject` (subject-centric listing), and
+ * `by_status_updated` (retention sweep — prune terminal rows oldest-first).
+ */
+export default defineSchema({
+    messages: defineTable({
+        messageId: v.string(),
+        to: v.string(),
+        from: v.string(),
+        transport: v.string(),
+        status: messageStatus,
+        payload: v.optional(jsonValue),
+        subjectRef: v.optional(v.string()),
+        idempotencyKey: v.optional(v.string()),
+        providerId: v.optional(v.string()),
+        attempts: v.number(),
+        maxAttempts: v.number(),
+        error: v.optional(v.string()),
+        createdAt: v.number(),
+        updatedAt: v.number(),
+    })
+        .index("by_message_id", ["messageId"])
+        .index("by_idempotency_key", ["idempotencyKey"])
+        .index("by_status", ["status", "createdAt"])
+        .index("by_subject", ["subjectRef", "createdAt"])
+        .index("by_status_updated", ["status", "updatedAt"]),
+});
+//# sourceMappingURL=schema.js.map

package/dist/component/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,eAAe,YAAY,CAAC;IAC1B,QAAQ,EAAE,WAAW,CAAC;QACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;QACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;QAChB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAC9B,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAClC,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACtC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;QACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;QACvB,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;KACtB,CAAC;SACC,KAAK,CAAC,eAAe,EAAE,CAAC,WAAW,CAAC,CAAC;SACrC,KAAK,CAAC,oBAAoB,EAAE,CAAC,gBAAgB,CAAC,CAAC;SAC/C,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;SAC3C,KAAK,CAAC,YAAY,EAAE,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;SAChD,KAAK,CAAC,mBAAmB,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;CACvD,CAAC,CAAC"}

package/dist/component/validators.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Opaque host-owned data stored on a message — its `payload` (rendered body,
+ * template name + data, headers, attachment refs — whatever the host's transport
+ * needs to send). The component never inspects it; it is last-resort arbitrary
+ * data, aliased here rather than left bare in function signatures. The host
+ * narrows it at the {@link Email} client boundary via an optional
+ * `payloadValidator` parser.
+ *
+ * This is the single documented `v.any()` escape hatch in the component; the lint
+ * rule `convex-rules/no-bare-v-any` is satisfied by routing every arbitrary host
+ * payload through this alias instead of a bare `v.any()`.
+ */
+export declare const jsonValue: import("convex/values").VAny<any, "required", string>;
+/** The four lifecycle states a message moves through. */
+export declare const messageStatus: import("convex/values").VUnion<"queued" | "sending" | "sent" | "failed", [import("convex/values").VLiteral<"queued", "required">, import("convex/values").VLiteral<"sending", "required">, import("convex/values").VLiteral<"sent", "required">, import("convex/values").VLiteral<"failed", "required">], "required", never>;
+/**
+ * Public projection of a message returned by {@link get}. `payload` is opaque
+ * host data; `transport` names the host-configured adapter the message is routed
+ * through (never a baked-in vendor); `providerId` is the transport's own message
+ * handle recorded on a successful send; `error` is the host-supplied failure
+ * reason recorded on a failed attempt.
+ */
+export declare const messageView: import("convex/values").VObject<{
+    payload?: any;
+    subjectRef?: string | undefined;
+    idempotencyKey?: string | undefined;
+    providerId?: string | undefined;
+    error?: string | undefined;
+    messageId: string;
+    to: string;
+    from: string;
+    transport: string;
+    maxAttempts: number;
+    status: "queued" | "sending" | "sent" | "failed";
+    attempts: number;
+    createdAt: number;
+    updatedAt: number;
+}, {
+    messageId: import("convex/values").VString<string, "required">;
+    to: import("convex/values").VString<string, "required">;
+    from: import("convex/values").VString<string, "required">;
+    transport: import("convex/values").VString<string, "required">;
+    status: import("convex/values").VUnion<"queued" | "sending" | "sent" | "failed", [import("convex/values").VLiteral<"queued", "required">, import("convex/values").VLiteral<"sending", "required">, import("convex/values").VLiteral<"sent", "required">, import("convex/values").VLiteral<"failed", "required">], "required", never>;
+    payload: import("convex/values").VAny<any, "optional", string>;
+    subjectRef: import("convex/values").VString<string | undefined, "optional">;
+    idempotencyKey: import("convex/values").VString<string | undefined, "optional">;
+    providerId: import("convex/values").VString<string | undefined, "optional">;
+    attempts: import("convex/values").VFloat64<number, "required">;
+    maxAttempts: import("convex/values").VFloat64<number, "required">;
+    error: import("convex/values").VString<string | undefined, "optional">;
+    createdAt: import("convex/values").VFloat64<number, "required">;
+    updatedAt: import("convex/values").VFloat64<number, "required">;
+}, "required", "messageId" | "to" | "from" | "transport" | "payload" | "subjectRef" | "idempotencyKey" | "maxAttempts" | "providerId" | "error" | "status" | "attempts" | "createdAt" | "updatedAt" | `payload.${string}`>;
+//# sourceMappingURL=validators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,uDAAU,CAAC;AAEjC,yDAAyD;AACzD,eAAO,MAAM,aAAa,8TAKzB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0NAetB,CAAC"}

package/dist/component/validators.js

@@ -0,0 +1,40 @@
+import { v } from "convex/values";
+/**
+ * Opaque host-owned data stored on a message — its `payload` (rendered body,
+ * template name + data, headers, attachment refs — whatever the host's transport
+ * needs to send). The component never inspects it; it is last-resort arbitrary
+ * data, aliased here rather than left bare in function signatures. The host
+ * narrows it at the {@link Email} client boundary via an optional
+ * `payloadValidator` parser.
+ *
+ * This is the single documented `v.any()` escape hatch in the component; the lint
+ * rule `convex-rules/no-bare-v-any` is satisfied by routing every arbitrary host
+ * payload through this alias instead of a bare `v.any()`.
+ */
+export const jsonValue = v.any();
+/** The four lifecycle states a message moves through. */
+export const messageStatus = v.union(v.literal("queued"), v.literal("sending"), v.literal("sent"), v.literal("failed"));
+/**
+ * Public projection of a message returned by {@link get}. `payload` is opaque
+ * host data; `transport` names the host-configured adapter the message is routed
+ * through (never a baked-in vendor); `providerId` is the transport's own message
+ * handle recorded on a successful send; `error` is the host-supplied failure
+ * reason recorded on a failed attempt.
+ */
+export const messageView = v.object({
+    messageId: v.string(),
+    to: v.string(),
+    from: v.string(),
+    transport: v.string(),
+    status: messageStatus,
+    payload: v.optional(jsonValue),
+    subjectRef: v.optional(v.string()),
+    idempotencyKey: v.optional(v.string()),
+    providerId: v.optional(v.string()),
+    attempts: v.number(),
+    maxAttempts: v.number(),
+    error: v.optional(v.string()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+//# sourceMappingURL=validators.js.map

package/dist/component/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/component/validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;AAEjC,yDAAyD;AACzD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAClC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EACnB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACpB,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EACjB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CACpB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,aAAa;IACrB,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC9B,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACtC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC"}

package/dist/jmap/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The optional generic-JMAP transport adapter — a `./jmap` entry the host imports
+ * into its OWN Convex action to actually send queued messages over a JMAP server's
+ * HTTP API (Stalwart, Fastmail, Cyrus, any JMAP server). It is NOT part of the
+ * sandboxed component: the component records intent + status and never sends.
+ *
+ * Unlike `./smtp`, this layer is **pure** and dependency-free: it drives an
+ * injected `fetch` (the host's runtime `fetch`), so it needs no `nodemailer`, no
+ * `"use node"` action (JMAP is plain HTTP — `fetch` runs in a normal Convex
+ * action), and is 100%-covered with a fake `fetch` (no excluded wrapper).
+ *
+ * Tree-shake boundary: a backend-only consumer importing `@vllnt/convex-email`
+ * (the `.` entry) pulls ZERO JMAP code. Importing this `./jmap` entry is the
+ * explicit opt-in.
+ *
+ * JMAP is a protocol (RFC 8620/8621), not a vendor — Stalwart is one configured
+ * server (`{ endpoint, token }`), never baked in, so this is `./jmap`, never
+ * `./stalwart`.
+ */
+export { validateJmapConfig, buildEmailCreate, buildSubmitRequest, parseSubmitResponse, sendViaJmap, discoverJmapSession, createJmapSender, } from "./send.js";
+export type { JmapConfig, JmapMessage, JmapSendResult, JmapSender, JmapFetch, JmapRequestInit, JmapResponse, JmapDiscoverOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/jmap/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jmap/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,SAAS,EACT,eAAe,EACf,YAAY,EACZ,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/jmap/index.js

@@ -0,0 +1,21 @@
+/**
+ * The optional generic-JMAP transport adapter — a `./jmap` entry the host imports
+ * into its OWN Convex action to actually send queued messages over a JMAP server's
+ * HTTP API (Stalwart, Fastmail, Cyrus, any JMAP server). It is NOT part of the
+ * sandboxed component: the component records intent + status and never sends.
+ *
+ * Unlike `./smtp`, this layer is **pure** and dependency-free: it drives an
+ * injected `fetch` (the host's runtime `fetch`), so it needs no `nodemailer`, no
+ * `"use node"` action (JMAP is plain HTTP — `fetch` runs in a normal Convex
+ * action), and is 100%-covered with a fake `fetch` (no excluded wrapper).
+ *
+ * Tree-shake boundary: a backend-only consumer importing `@vllnt/convex-email`
+ * (the `.` entry) pulls ZERO JMAP code. Importing this `./jmap` entry is the
+ * explicit opt-in.
+ *
+ * JMAP is a protocol (RFC 8620/8621), not a vendor — Stalwart is one configured
+ * server (`{ endpoint, token }`), never baked in, so this is `./jmap`, never
+ * `./stalwart`.
+ */
+export { validateJmapConfig, buildEmailCreate, buildSubmitRequest, parseSubmitResponse, sendViaJmap, discoverJmapSession, createJmapSender, } from "./send.js";
+//# sourceMappingURL=index.js.map