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

package/src/component/queries.ts

@@ -0,0 +1,70 @@
+import { v } from "convex/values";
+import { paginationOptsValidator } from "convex/server";
+import { query } from "./_generated/server";
+import { messageStatus, messageView } from "./validators";
+import type { Doc } from "./_generated/dataModel";
+
+/** Project a stored message row to its public view (drops internal fields). */
+function view(msg: Doc<"messages">) {
+  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) };
+  },
+});

package/src/component/schema.ts

@@ -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"]),
+});

package/src/component/validators.ts

@@ -0,0 +1,47 @@
+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(),
+});

package/src/jmap/index.ts

@@ -0,0 +1,39 @@
+/**
+ * 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";