@pylonsync/functions 0.3.375 → 0.3.378

package/dist/types.d.ts

@@ -217,7 +217,7 @@ export interface Scheduler {
  * Transactional email transport.
  *
  * Sends through whatever provider the runtime is configured for
- * (PYLON_EMAIL_PROVIDER env var → SendGrid / Resend / Stack0 / SMTP /
+ * (PYLON_EMAIL_PROVIDER env var → SendGrid / Resend / Stack0 /
  * webhook). Available on action ctx only — sending email is external
  * I/O, not allowed in mutation transactions.
  *
@@ -230,16 +230,49 @@ export interface Scheduler {
  * shared auth key can never be used to send arbitrary mail.
  *
  * The runtime owns provider config + credentials; functions only
- * supply the (to, subject, body) tuple. Failures are surfaced as
- * thrown errors; on success the return is void.
+ * supply the message. Failures are surfaced as thrown errors; on
+ * success the return is void.
  *
  * Use cases: invite emails, password-reset hand-offs, notifications,
- * digest reports. NOT for marketing email — those should go through
- * a dedicated bulk transport, not the transactional path.
+ * digest reports, calendar invites (attach an .ics with contentType
+ * `text/calendar; method=REQUEST` and mail clients render an
+ * RSVP-able event). NOT for marketing email — those should go
+ * through a dedicated bulk transport, not the transactional path.
  */
+export interface EmailAttachment {
+    filename: string;
+    /**
+     * Full MIME content type, passed to the provider VERBATIM —
+     * parameterized types like `text/calendar; method=REQUEST` are
+     * preserved (that parameter is what makes an invite RSVP-able).
+     */
+    contentType: string;
+    /** Base64-encoded file bytes. */
+    content: string;
+}
+export interface EmailOptions {
+    /** Single recipient address. */
+    to: string;
+    subject: string;
+    /**
+     * Plain-text body. Required even with `html` — it's the text/plain
+     * part clients with HTML disabled fall back to.
+     */
+    text: string;
+    /** Optional HTML body; providers send multipart with `text`. */
+    html?: string;
+    /**
+     * Base64 attachments. Limits: at most 20 per email, 15MB of base64
+     * text total (≈11MB of raw file data); larger sends throw before
+     * any network I/O.
+     */
+    attachments?: EmailAttachment[];
+}
 export interface EmailSender {
     /** Send a plain-text email. `to` is a single address. */
     send(to: string, subject: string, body: string): Promise<void>;
+    /** Send with options: HTML body and/or base64 attachments. */
+    send(options: EmailOptions): Promise<void>;
 }
 /**
  * Server-side LLM client. Available on every ctx variant (query,

package/dist/validators.d.ts

@@ -67,6 +67,12 @@ export declare const v: {
     literal: <const TValue extends string | number | boolean>(value: TValue) => Validator<TValue, false>;
     /** Any valid JSON value. */
     any: () => Validator<any, false>;
+    /**
+     * Arbitrary JSON value (object, array, or scalar). The validator-side
+     * match for `field.json()` — accepts any JSON shape but types the arg
+     * as `unknown`, so handlers narrow before use instead of getting `any`.
+     */
+    json: () => Validator<unknown, false>;
 };
 export declare function validateArgs(args: unknown, schema: Record<string, Validator>): {
     valid: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.375",
+  "version": "0.3.378",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/runtime-email.test.ts

@@ -0,0 +1,174 @@
+/**
+ * `ctx.email.send` — options overload and size caps.
+ *
+ * The contract under test:
+ *
+ *   1. The positional form still emits the legacy frame shape.
+ *   2. The options form emits `html` and snake_case attachments, with
+ *      the `contentType` value passed through VERBATIM (parameterized
+ *      types like `text/calendar; method=REQUEST` are load-bearing).
+ *   3. Over-limit attachments throw BEFORE any frame is emitted.
+ *
+ * Same child-process NDJSON harness as runtime-rpc-queue.test.ts.
+ */
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNTIME = join(import.meta.dir, "runtime.ts");
+
+function parseFrames(text: string): Record<string, unknown>[] {
+  return text
+    .split("\n")
+    .filter((l) => l.trim().startsWith("{"))
+    .map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+function spawnRuntime(probeSource: string) {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-email-"));
+  mkdirSync(join(dir, "functions"));
+  writeFileSync(join(dir, "functions", "probe.ts"), probeSource);
+  return Bun.spawn([process.execPath, RUNTIME, "./functions"], {
+    cwd: dir,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+}
+
+function frameReader(proc: ReturnType<typeof Bun.spawn>) {
+  const reader = (proc.stdout as ReadableStream<Uint8Array>).getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  return async function readUntil(
+    pred: (frames: Record<string, unknown>[]) => boolean,
+  ): Promise<Record<string, unknown>[]> {
+    let frames = parseFrames(buffered);
+    while (!pred(frames)) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+      frames = parseFrames(buffered);
+    }
+    return frames;
+  };
+}
+
+test("options form emits html + snake_case attachments with verbatim contentType", async () => {
+  const proc = spawnRuntime(`
+export default {
+  type: "action",
+  handler: async (ctx) => {
+    // Positional form first, then options form.
+    await ctx.email.send("a@t.com", "Plain", "plain body");
+    await ctx.email.send({
+      to: "b@t.com",
+      subject: "Invite",
+      text: "You're invited",
+      html: "<p>hi</p>",
+      attachments: [{
+        filename: "invite.ics",
+        contentType: "text/calendar; method=REQUEST",
+        content: "QkVHSU46VkNBTEVOREFS",
+      }],
+    });
+    return { ok: true };
+  },
+};
+`);
+  const readUntil = frameReader(proc);
+  const send = (msg: Record<string, unknown>) =>
+    (proc.stdin as import("bun").FileSink).write(JSON.stringify(msg) + "\n");
+
+  await readUntil((fs) => fs.some((f) => f.type === "ready"));
+  send({
+    type: "call",
+    call_id: "c_1",
+    fn_name: "probe",
+    fn_type: "action",
+    args: {},
+    auth: { user_id: "u1", is_admin: false, tenant_id: null },
+  });
+
+  let frames = await readUntil((fs) => fs.some((f) => f.type === "send_email"));
+  const first = frames.find((f) => f.type === "send_email")!;
+  expect(first).toMatchObject({ to: "a@t.com", subject: "Plain", body: "plain body" });
+  send({ type: "result", call_id: "c_1", data: { sent: true } });
+
+  frames = await readUntil(
+    (fs) => fs.filter((f) => f.type === "send_email").length >= 2,
+  );
+  const second = frames.filter((f) => f.type === "send_email")[1];
+  expect(second).toMatchObject({
+    to: "b@t.com",
+    subject: "Invite",
+    body: "You're invited",
+    html: "<p>hi</p>",
+    attachments: [
+      {
+        filename: "invite.ics",
+        content_type: "text/calendar; method=REQUEST",
+        content: "QkVHSU46VkNBTEVOREFS",
+      },
+    ],
+  });
+  send({ type: "result", call_id: "c_1", data: { sent: true } });
+
+  frames = await readUntil((fs) => fs.some((f) => f.type === "return"));
+  expect(frames.find((f) => f.type === "return")!.value).toEqual({ ok: true });
+
+  proc.kill();
+  await proc.exited;
+});
+
+test("oversized attachments throw before any frame is emitted", async () => {
+  const proc = spawnRuntime(`
+export default {
+  type: "action",
+  handler: async (ctx) => {
+    try {
+      await ctx.email.send({
+        to: "b@t.com",
+        subject: "Big",
+        text: "x",
+        attachments: [{
+          filename: "huge.bin",
+          contentType: "application/octet-stream",
+          content: "A".repeat(16 * 1024 * 1024),
+        }],
+      });
+      return { threw: false };
+    } catch (err) {
+      return { threw: true, message: String(err.message) };
+    }
+  },
+};
+`);
+  const readUntil = frameReader(proc);
+  const send = (msg: Record<string, unknown>) =>
+    (proc.stdin as import("bun").FileSink).write(JSON.stringify(msg) + "\n");
+
+  await readUntil((fs) => fs.some((f) => f.type === "ready"));
+  send({
+    type: "call",
+    call_id: "c_2",
+    fn_name: "probe",
+    fn_type: "action",
+    args: {},
+    auth: { user_id: "u1", is_admin: false, tenant_id: null },
+  });
+
+  const frames = await readUntil((fs) => fs.some((f) => f.type === "return"));
+  // The reject happened locally: no send_email frame ever hit the wire.
+  expect(frames.filter((f) => f.type === "send_email")).toHaveLength(0);
+  const ret = frames.find((f) => f.type === "return")!.value as {
+    threw: boolean;
+    message: string;
+  };
+  expect(ret.threw).toBe(true);
+  expect(ret.message).toContain("exceeding");
+
+  proc.kill();
+  await proc.exited;
+});

package/src/runtime-rpc-queue.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Legacy (call_id-keyed) RPCs QUEUE instead of rejecting.
+ *
+ * The contract under test:
+ *
+ *   1. An UN-AWAITED `ctx.auth.elevate(...)` followed by
+ *      `ctx.scheduler.runAfter(...)` works: the elevate frame reaches
+ *      the host BEFORE the schedule frame (wire order == call order),
+ *      the schedule reply resolves with the real job id, and the call
+ *      returns normally. Before the queue, this rejected with
+ *      "Internal: concurrent RPC attempted on same call_id".
+ *   2. `Promise.all` over two legacy RPCs serializes: both frames go
+ *      out (second only after the first's reply) and each promise
+ *      resolves with its own reply, not its neighbor's.
+ *
+ * Drives the REAL runtime.ts dispatcher in a child process via a full
+ * `call` frame — the handler is loaded from a temp functions dir, and
+ * we play the host over stdin/stdout NDJSON exactly like the Rust side.
+ */
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNTIME = join(import.meta.dir, "runtime.ts");
+
+/** Collect NDJSON frames from a chunk of the child's stdout. */
+function parseFrames(text: string): Record<string, unknown>[] {
+  return text
+    .split("\n")
+    .filter((l) => l.trim().startsWith("{"))
+    .map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+/** Spawn the runtime against a temp functions dir holding `probe.ts`. */
+function spawnRuntime(probeSource: string) {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-rpcq-"));
+  mkdirSync(join(dir, "functions"));
+  writeFileSync(join(dir, "functions", "probe.ts"), probeSource);
+  const proc = Bun.spawn([process.execPath, RUNTIME, "./functions"], {
+    cwd: dir,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return proc;
+}
+
+/** Incremental frame reader over the child's stdout. */
+function frameReader(proc: ReturnType<typeof Bun.spawn>) {
+  const reader = (proc.stdout as ReadableStream<Uint8Array>).getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  return async function readUntil(
+    pred: (frames: Record<string, unknown>[]) => boolean,
+  ): Promise<Record<string, unknown>[]> {
+    let frames = parseFrames(buffered);
+    while (!pred(frames)) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffered += decoder.decode(value, { stream: true });
+      frames = parseFrames(buffered);
+    }
+    return frames;
+  };
+}
+
+test("un-awaited elevate then runAfter queues: elevate frame first, real job id back", async () => {
+  const proc = spawnRuntime(`
+export default {
+  type: "action",
+  handler: async (ctx) => {
+    // Deliberately NOT awaited — the exact bug pattern under test.
+    ctx.auth.elevate({ admin: true, reason: "test" });
+    const jobId = await ctx.scheduler.runAfter(5000, "internalTarget", { n: 1 });
+    return { jobId, isAdmin: ctx.auth.isAdmin };
+  },
+};
+`);
+  const readUntil = frameReader(proc);
+  const send = (msg: Record<string, unknown>) =>
+    (proc.stdin as import("bun").FileSink).write(JSON.stringify(msg) + "\n");
+
+  await readUntil((fs) => fs.some((f) => f.type === "ready"));
+  send({
+    type: "call",
+    call_id: "c_9",
+    fn_name: "probe",
+    fn_type: "action",
+    args: {},
+    auth: { user_id: "u1", is_admin: false, tenant_id: null },
+  });
+
+  // The elevate frame must arrive BEFORE any schedule frame — and with
+  // its reply outstanding, the schedule frame must not have been sent.
+  let frames = await readUntil((fs) => fs.some((f) => f.type === "elevate_auth"));
+  expect(frames.filter((f) => f.type === "schedule")).toHaveLength(0);
+  send({ type: "result", call_id: "c_9", data: { elevated: true } });
+
+  frames = await readUntil((fs) => fs.some((f) => f.type === "schedule"));
+  const schedule = frames.find((f) => f.type === "schedule")!;
+  expect(schedule).toMatchObject({
+    fn_name: "internalTarget",
+    args: { n: 1 },
+    delay_ms: 5000,
+  });
+  send({ type: "result", call_id: "c_9", data: { id: "job_123" } });
+
+  frames = await readUntil((fs) => fs.some((f) => f.type === "return"));
+  const ret = frames.find((f) => f.type === "return")!;
+  expect(ret.value).toEqual({ jobId: "job_123", isAdmin: true });
+
+  proc.kill();
+  await proc.exited;
+});
+
+test("Promise.all over two legacy RPCs serializes and each resolves its own reply", async () => {
+  const proc = spawnRuntime(`
+export default {
+  type: "action",
+  handler: async (ctx) => {
+    const [a, b] = await Promise.all([
+      ctx.scheduler.runAfter(1000, "first", {}),
+      ctx.scheduler.runAfter(2000, "second", {}),
+    ]);
+    return { a, b };
+  },
+};
+`);
+  const readUntil = frameReader(proc);
+  const send = (msg: Record<string, unknown>) =>
+    (proc.stdin as import("bun").FileSink).write(JSON.stringify(msg) + "\n");
+
+  await readUntil((fs) => fs.some((f) => f.type === "ready"));
+  send({
+    type: "call",
+    call_id: "c_10",
+    fn_name: "probe",
+    fn_type: "action",
+    args: {},
+    auth: { user_id: null, is_admin: true, tenant_id: null },
+  });
+
+  // First schedule frame out; the second must be held until we reply.
+  let frames = await readUntil((fs) => fs.some((f) => f.type === "schedule"));
+  expect(frames.filter((f) => f.type === "schedule")).toHaveLength(1);
+  expect(frames.find((f) => f.type === "schedule")).toMatchObject({
+    fn_name: "first",
+  });
+  send({ type: "result", call_id: "c_10", data: { id: "s1" } });
+
+  frames = await readUntil(
+    (fs) => fs.filter((f) => f.type === "schedule").length >= 2,
+  );
+  expect(frames.filter((f) => f.type === "schedule")[1]).toMatchObject({
+    fn_name: "second",
+  });
+  send({ type: "result", call_id: "c_10", data: { id: "s2" } });
+
+  frames = await readUntil((fs) => fs.some((f) => f.type === "return"));
+  expect(frames.find((f) => f.type === "return")!.value).toEqual({
+    a: "s1",
+    b: "s2",
+  });
+
+  proc.kill();
+  await proc.exited;
+});

package/src/runtime.ts

@@ -18,6 +18,8 @@
 import type {
   DbReader,
   DbWriter,
+  EmailAttachment,
+  EmailOptions,
   EmailSender,
   Stream,
   Scheduler,
@@ -428,34 +430,68 @@ function rpcStreaming(
 }
 
 /**
- * RPC for non-db protocol replies (scheduler.runAfter, nested function
- * calls, etc.) where at-most-one in-flight per call_id is the right
- * contract. Keeps the legacy keying so these reply shapes don't need
- * op_id support on the host.
+ * Tail of the in-order queue of legacy (call_id-keyed) RPCs, per call.
+ * See {@link rpc} for why these serialize.
+ */
+const rpcQueues = new Map<string, Promise<unknown>>();
+
+/**
+ * RPC for non-db protocol replies (scheduler.runAfter, elevate, email,
+ * nested function calls, etc.). These reply frames carry no op_id, so
+ * only one can be in flight per call_id — but instead of rejecting a
+ * second request (the old "concurrent RPC attempted on same call_id"
+ * error), requests QUEUE: each one waits for the previous request on
+ * the same call_id to settle, then sends. The host drains a per-call
+ * channel strictly in order, so wire order == call order and the
+ * replies can't cross.
+ *
+ * This is what makes an un-awaited `ctx.auth.elevate(...)` followed by
+ * `ctx.scheduler.runAfter(...)` behave correctly: the elevate frame is
+ * sent (and replied to) before the schedule frame goes out, so the
+ * host-side admin flag is already set when the schedule arm reads it.
+ * `Promise.all` over these ctx calls serializes for the same reason.
+ *
+ * The timeout starts when the frame is actually SENT, not while the
+ * request is queued behind a predecessor, and each request chains on
+ * the predecessor's SETTLEMENT — a rejected predecessor doesn't poison
+ * the rest of the queue.
  */
 function rpc(callId: string, msg: Record<string, unknown>): Promise<unknown> {
-  return new Promise((resolve, reject) => {
-    if (pendingRpcs.has(callId)) {
-      reject(
-        new Error(
-          `Internal: concurrent RPC attempted on same call_id (${callId})`,
-        ),
-      );
-      return;
-    }
-    const timeout = setTimeout(() => {
-      if (pendingRpcs.has(callId)) {
-        pendingRpcs.delete(callId);
-        reject(
-          new Error(
-            `RPC timed out after ${RPC_TIMEOUT_MS}ms (call_id=${callId})`,
-          ),
-        );
-      }
-    }, RPC_TIMEOUT_MS);
-    pendingRpcs.set(callId, { resolve, reject, timeout });
-    send({ ...msg, call_id: callId });
-  });
+  const prev = rpcQueues.get(callId) ?? Promise.resolve();
+  const run = prev
+    .then(
+      () => undefined,
+      () => undefined,
+    )
+    .then(
+      () =>
+        new Promise((resolve, reject) => {
+          const timeout = setTimeout(() => {
+            if (pendingRpcs.has(callId)) {
+              pendingRpcs.delete(callId);
+              reject(
+                new Error(
+                  `RPC timed out after ${RPC_TIMEOUT_MS}ms (call_id=${callId})`,
+                ),
+              );
+            }
+          }, RPC_TIMEOUT_MS);
+          pendingRpcs.set(callId, { resolve, reject, timeout });
+          send({ ...msg, call_id: callId });
+        }),
+    );
+  rpcQueues.set(callId, run);
+  // Drop the queue entry once this tail settles (if nothing chained
+  // after it) so the map doesn't hold one entry per call_id forever.
+  run.then(
+    () => {
+      if (rpcQueues.get(callId) === run) rpcQueues.delete(callId);
+    },
+    () => {
+      if (rpcQueues.get(callId) === run) rpcQueues.delete(callId);
+    },
+  );
+  return run;
 }
 
 // ---------------------------------------------------------------------------
@@ -705,17 +741,60 @@ function buildScheduler(callId: string): Scheduler {
  * replies success or error. Errors arrive as thrown exceptions on
  * the action's await, just like every other RPC. No silent failures.
  */
+// Mirrors the Rust-side guard in the send_email dispatch arm: attachments
+// ride one NDJSON line, so an oversized payload is an unbounded allocation
+// on both sides of the pipe. Reject before any framing happens.
+const EMAIL_MAX_ATTACHMENT_B64_BYTES = 15 * 1024 * 1024;
+const EMAIL_MAX_ATTACHMENTS = 20;
+
 function buildEmail(callId: string): EmailSender {
-  return {
-    async send(to, subject, body) {
+  async function send(
+    toOrOptions: string | EmailOptions,
+    subject?: string,
+    body?: string,
+  ): Promise<void> {
+    // Options form: first argument is the message object.
+    if (typeof toOrOptions === "object" && toOrOptions !== null) {
+      const opts = toOrOptions;
+      const attachments = opts.attachments ?? [];
+      if (attachments.length > EMAIL_MAX_ATTACHMENTS) {
+        throw new Error(
+          `ctx.email.send: ${attachments.length} attachments exceeds the limit of ${EMAIL_MAX_ATTACHMENTS} per email`,
+        );
+      }
+      const b64Total = attachments.reduce(
+        (n: number, a: EmailAttachment) => n + a.content.length,
+        0,
+      );
+      if (b64Total > EMAIL_MAX_ATTACHMENT_B64_BYTES) {
+        throw new Error(
+          `ctx.email.send: attachments total ${b64Total} base64 bytes, exceeding the ${EMAIL_MAX_ATTACHMENT_B64_BYTES}-byte limit (≈11MB of raw file data)`,
+        );
+      }
       await rpc(callId, {
         type: "send_email",
-        to,
-        subject,
-        body,
+        to: opts.to,
+        subject: opts.subject,
+        body: opts.text,
+        html: opts.html,
+        // Wire fields are snake_case; contentType is the TS-facing name.
+        attachments: attachments.map((a: EmailAttachment) => ({
+          filename: a.filename,
+          content_type: a.contentType,
+          content: a.content,
+        })),
       });
-    },
-  };
+      return;
+    }
+    // Positional form: send(to, subject, body).
+    await rpc(callId, {
+      type: "send_email",
+      to: toOrOptions,
+      subject,
+      body,
+    });
+  }
+  return { send } as EmailSender;
 }
 
 /**

package/src/types.ts

@@ -289,7 +289,7 @@ export interface Scheduler {
  * Transactional email transport.
  *
  * Sends through whatever provider the runtime is configured for
- * (PYLON_EMAIL_PROVIDER env var → SendGrid / Resend / Stack0 / SMTP /
+ * (PYLON_EMAIL_PROVIDER env var → SendGrid / Resend / Stack0 /
  * webhook). Available on action ctx only — sending email is external
  * I/O, not allowed in mutation transactions.
  *
@@ -302,16 +302,51 @@ export interface Scheduler {
  * shared auth key can never be used to send arbitrary mail.
  *
  * The runtime owns provider config + credentials; functions only
- * supply the (to, subject, body) tuple. Failures are surfaced as
- * thrown errors; on success the return is void.
+ * supply the message. Failures are surfaced as thrown errors; on
+ * success the return is void.
  *
  * Use cases: invite emails, password-reset hand-offs, notifications,
- * digest reports. NOT for marketing email — those should go through
- * a dedicated bulk transport, not the transactional path.
+ * digest reports, calendar invites (attach an .ics with contentType
+ * `text/calendar; method=REQUEST` and mail clients render an
+ * RSVP-able event). NOT for marketing email — those should go
+ * through a dedicated bulk transport, not the transactional path.
  */
+export interface EmailAttachment {
+  filename: string;
+  /**
+   * Full MIME content type, passed to the provider VERBATIM —
+   * parameterized types like `text/calendar; method=REQUEST` are
+   * preserved (that parameter is what makes an invite RSVP-able).
+   */
+  contentType: string;
+  /** Base64-encoded file bytes. */
+  content: string;
+}
+
+export interface EmailOptions {
+  /** Single recipient address. */
+  to: string;
+  subject: string;
+  /**
+   * Plain-text body. Required even with `html` — it's the text/plain
+   * part clients with HTML disabled fall back to.
+   */
+  text: string;
+  /** Optional HTML body; providers send multipart with `text`. */
+  html?: string;
+  /**
+   * Base64 attachments. Limits: at most 20 per email, 15MB of base64
+   * text total (≈11MB of raw file data); larger sends throw before
+   * any network I/O.
+   */
+  attachments?: EmailAttachment[];
+}
+
 export interface EmailSender {
   /** Send a plain-text email. `to` is a single address. */
   send(to: string, subject: string, body: string): Promise<void>;
+  /** Send with options: HTML body and/or base64 attachments. */
+  send(options: EmailOptions): Promise<void>;
 }
 
 // ---------------------------------------------------------------------------

package/src/validators.ts

@@ -115,6 +115,13 @@ export const v = {
 
   /** Any valid JSON value. */
   any: (): Validator<any, false> => validator("any"),
+
+  /**
+   * Arbitrary JSON value (object, array, or scalar). The validator-side
+   * match for `field.json()` — accepts any JSON shape but types the arg
+   * as `unknown`, so handlers narrow before use instead of getting `any`.
+   */
+  json: (): Validator<unknown, false> => validator("json"),
 };
 
 // ---------------------------------------------------------------------------
@@ -179,6 +186,10 @@ function validateValue(
         : `${path}: expected null, got ${typeof value}`;
     case "any":
       return null;
+    case "json":
+      // Any JSON shape is legal, including null — presence/absence is
+      // handled by the optional pass above.
+      return null;
     case "literal":
       return value === validator.value
         ? null