@dench.com/cli 3.6.6-staging.386 → 3.7.0-staging.387

package/email-inbox.ts

@@ -0,0 +1,169 @@
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { assertNoUnknownFlags, getFlag, hasFlag } from "./lib/cli-args";
+
+export const EMAIL_INBOX_HELP = `
+  dench email inbox search [--mailbox <id|email>] [--from <email>] [--to <email>] [--subject <text>] [--after <ISO-date|milliseconds>] [--before <ISO-date|milliseconds>] [--direction inbound|outbound] [--limit 1..50] [--cursor <cursor>] [--json]
+  dench email inbox thread <thread-handle> [--limit 1..50] [--cursor <cursor>] [--json]
+  dench email inbox message <message-handle> [--format text|html] [--max-bytes 1..100000] [--json]
+
+Search reads synced headers only; it does not contact the provider or search message bodies.
+--from/--to match exact addresses (to includes cc/bcc); --subject is a case-insensitive substring.
+--after is inclusive, --before exclusive; date-only values mean midnight UTC. Older undated rows use createdAt.
+isDone means the persisted scan ended, not that the provider's entire mailbox has been synced.
+coverage.privacyLimited reports older rows omitted when complete record privacy cannot be established.
+Keep the returned cursor through empty filtered pages. Thread/message handles come from these results.
+`;
+
+export type EmailInboxCliContext = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+  sessionToken?: string;
+};
+function valueFlag(args: string[], name: string) {
+  const present = args.includes(name);
+  const value = getFlag(args, name);
+  if (present && (!value?.trim() || value.startsWith("--")))
+    throw new Error(`${name} requires a value`);
+  return value;
+}
+function integerFlag(args: string[], name: string, maximum: number) {
+  const raw = valueFlag(args, name);
+  if (raw === undefined) return undefined;
+  const value = Number(raw);
+  if (
+    !/^\d+$/.test(raw) ||
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > maximum
+  )
+    throw new Error(`${name} must be an integer from 1 to ${maximum}`);
+  return value;
+}
+function dateFlag(args: string[], name: string) {
+  const raw = valueFlag(args, name);
+  if (raw === undefined) return undefined;
+  if (/^-?\d+$/.test(raw)) {
+    const value = Number(raw);
+    if (Number.isSafeInteger(value)) return value;
+  }
+  const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(raw);
+  if (dateOnly || /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(raw)) {
+    const value = Date.parse(dateOnly ? `${raw}T00:00:00.000Z` : raw);
+    const day = raw.slice(0, 10);
+    const calendar = Date.parse(`${day}T00:00:00.000Z`);
+    if (
+      Number.isFinite(value) &&
+      Number.isFinite(calendar) &&
+      new Date(calendar).toISOString().slice(0, 10) === day
+    )
+      return value;
+  }
+  throw new Error(
+    `${name} must be YYYY-MM-DD, an ISO timestamp with timezone, or Unix milliseconds`,
+  );
+}
+export async function runEmailInboxCommand(
+  ctx: EmailInboxCliContext,
+): Promise<void> {
+  const args = [...ctx.args];
+  if (
+    !args.length ||
+    args.includes("--help") ||
+    args.includes("-h") ||
+    args[0] === "help"
+  ) {
+    console.log(EMAIL_INBOX_HELP.trim());
+    return;
+  }
+  const command = args.shift();
+  const jsonOutput = hasFlag(args, "--json") || ctx.jsonOutput;
+  const input: Record<string, unknown> = {};
+  const add = (key: string, value: unknown) => {
+    if (value !== undefined) input[key] = value;
+  };
+  if (command === "search") {
+    for (const flag of ["mailbox", "from", "to", "subject"])
+      add(flag, valueFlag(args, `--${flag}`));
+    add("after", dateFlag(args, "--after"));
+    add("before", dateFlag(args, "--before"));
+    const direction = valueFlag(args, "--direction");
+    if (
+      direction !== undefined &&
+      direction !== "inbound" &&
+      direction !== "outbound"
+    )
+      throw new Error("--direction must be inbound or outbound");
+    add("direction", direction);
+    if (
+      typeof input.after === "number" &&
+      typeof input.before === "number" &&
+      input.after >= input.before
+    )
+      throw new Error("--after must be earlier than --before");
+  } else if (command === "thread" || command === "message") {
+    const handle = args.shift();
+    if (
+      !handle?.startsWith(`email-${command}:`) ||
+      handle.length <= `email-${command}:`.length
+    )
+      throw new Error(
+        `Use an exact ${command} handle returned by email inbox search`,
+      );
+    input[`${command}Handle`] = handle;
+  } else
+    throw new Error("Unknown inbox command. Run `dench email inbox --help`.");
+  if (command === "message") {
+    const format = valueFlag(args, "--format");
+    if (format !== undefined && format !== "text" && format !== "html")
+      throw new Error("--format must be text or html");
+    add("format", format);
+    add("maxBytes", integerFlag(args, "--max-bytes", 100_000));
+  } else {
+    add("limit", integerFlag(args, "--limit", 50));
+    add("cursor", valueFlag(args, "--cursor"));
+  }
+  assertNoUnknownFlags(args, "email inbox");
+  if (args.length)
+    throw new Error(
+      `Unexpected inbox argument: ${args[0]}. Run \`dench email inbox --help\`.`,
+    );
+  const result = await ctx.convex.query(
+    makeFunctionReference<"query">(`functions/emailInbox:${command}`),
+    {
+      ...input,
+      ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+    },
+  );
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (command === "message") {
+    console.log(
+      `${result.header.subject}\nFrom: ${result.header.from.email}\n\n${result.body.content}`,
+    );
+    if (result.body.truncated)
+      console.log(
+        `\nBody truncated to the requested byte limit (${result.body.totalBytes} bytes stored).`,
+      );
+  } else {
+    for (const row of result.page)
+      console.log(
+        `${new Date(row.at).toISOString()}  ${row.from.email}  ${row.subject}\n  ${row.messageHandle}  ${row.threadHandle}`,
+      );
+    if (!result.page.length) console.log("No matching headers on this page.");
+    if (!result.isDone)
+      console.log(
+        `Continue with --cursor ${JSON.stringify(result.continueCursor)}`,
+      );
+  }
+  if (result.coverage.privacyLimited)
+    console.log(
+      "Some older messages were omitted because their full record privacy scope is unavailable.",
+    );
+  console.log(
+    `Synced mailbox: ${result.coverage.mailboxEmail} (${result.coverage.phase}); provider completeness is not established.`,
+  );
+}

package/email.ts

@@ -1,17 +1,20 @@
 import { createHash, createHmac, randomUUID } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
-import type { ConvexHttpClient } from "convex/browser";
+import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
+import { EMAIL_INBOX_HELP, runEmailInboxCommand } from "./email-inbox";
 import {
   assertNoUnknownFlags,
   getFlag,
   hasFlag,
+  isHelpRequest,
   parseJson,
 } from "./lib/cli-args";
 import { denchConfigDirectory } from "./lib/config-path.mjs";
+import { waitForNativeEmail } from "./lib/native-email-wait";
 
-type EmailCliContext = {
+export type EmailCliContext = {
   convex: ConvexHttpClient;
   args: string[];
   jsonOutput: boolean;
@@ -19,9 +22,21 @@ type EmailCliContext = {
   bearerToken?: string;
   gatewayBaseUrl?: string;
   gatewayHeaders?: Record<string, string>;
+  /** Injectable read transport; it must honor the supplied observation deadline. */
+  readNativeReceipt?: (
+    draftId: string,
+    signal: AbortSignal,
+  ) => Promise<unknown>;
 };
 
-class EmailCliError extends Error {}
+class EmailCliError extends Error {
+  constructor(
+    message: string,
+    readonly code = "invalid_arguments",
+  ) {
+    super(message);
+  }
+}
 
 type JsonRecord = Record<string, unknown>;
 
@@ -48,6 +63,7 @@ function requireBearerToken(ctx: EmailCliContext): string {
   if (!token) {
     throw new EmailCliError(
       "No Dench credential found. Set DENCH_API_KEY or run `dench signin`.",
+      "login_required",
     );
   }
   return token;
@@ -59,6 +75,7 @@ async function callGateway(
   path: string,
   body?: JsonRecord,
 ) {
+  if (method === "POST") assertEmailArgs(ctx);
   const baseUrl = resolveGatewayBaseUrl(ctx);
   const response = await fetch(`${baseUrl}${path}`, {
     method,
@@ -74,6 +91,7 @@ async function callGateway(
   if (!response.ok) {
     throw new EmailCliError(
       `Email service returned ${response.status}: ${text.slice(0, 500)}`,
+      "upstream_failed",
     );
   }
   const payload = text ? JSON.parse(text) : {};
@@ -85,6 +103,7 @@ async function callMutation(
   name: string,
   args: JsonRecord,
 ) {
+  assertEmailArgs(ctx);
   const ref = makeFunctionReference<"mutation">(name);
   return await ctx.convex.mutation(ref, {
     ...args,
@@ -105,6 +124,7 @@ async function callAction(
   name: string,
   args: JsonRecord,
 ) {
+  assertEmailArgs(ctx);
   const ref = makeFunctionReference<"action">(name);
   return await ctx.convex.action(ref, {
     ...args,
@@ -362,17 +382,20 @@ function toRecipients(rows: JsonRecord[]) {
   });
 }
 
-export function emailHelp() {
-  console.log(`dench email — outbound email from a connected inbox (or Dench Emailing Service)
+export function emailHelpText() {
+  return `dench email — outbound email from a connected inbox (or Dench Emailing Service)
 
 Usage:
+${EMAIL_INBOX_HELP}
   dench email draft create --to <email> --subject <subject> --text <body> [--mailbox <id/email>] [--request-id <id>] [--json]
   dench email draft show <id> [--json]
-  dench email draft update|send <id> --revision <n> [--json]
+  dench email draft update <id> --revision <n> [--to <email>] [--subject <subject>] [--text <body>] [--mailbox <id>] [--json]
+  dench email draft send <id> --revision <n> [--request-id <id>] [--wait <seconds>|--no-wait] [--json]
+  dench email draft senders [--json]  # available Gmail/Outlook mailboxes
   dench email draft attach <id> --revision <n> --file <path> [--content-type <mime>] [--json]  # up to 5 MB/file
   dench email draft signature <id> [--json]  # read signature HTML; insert visibly into the body
   # Identical native create/send invocations reuse a saved request ID. Use --request-id <new-id> for another identical email.
-  dench email send --mailbox <id/email> --to <email> --subject <subject> --text <body> [--request-id <id>] [--json]
+  dench email send --to <email> [--subject <subject>] (--text <body> | --html <body> | --text-file <path> | --html-file <path>) [--mailbox <id/email>] [--cc <emails>] [--bcc <emails>] [--request-id <id>] [--wait <seconds>|--no-wait] [--json]  # native default; observe the same receipt for 10s by default (--wait 0..60)
   dench email identity verify --from founder@example.com [--private] [--json]
   dench email identity verify --domain example.com [--from founder@example.com] [--private] [--json]
   dench email identity list [--domain example.com] [--json]
@@ -443,10 +466,15 @@ Email + LinkedIn multichannel sequences (see \`dench campaign\` — the fuller s
   dench email multichannel enroll-from-object --sequence <id> --object lead --entries id1,id2 [--email-field Email] [--linkedin-field "POC LinkedIn URL"] [--relation-field Contact] [--reverse] [--allow-duplicates] [--json]
   dench email multichannel launch --sequence <id> [--ack-linkedin-risk] [--json]
   dench email multichannel pause|resume|archive --sequence <id> [--json]
-  (see \`dench campaign help\` for the same campaigns with schedule, view-based add, launch checks and the Now/Next feed)`);
+  (see \`dench campaign help\` for the same campaigns with schedule, view-based add, launch checks and the Now/Next feed)`;
 }
 
 export async function runEmailCommand(ctx: EmailCliContext): Promise<void> {
+  if (isHelpRequest(ctx.args)) {
+    const { commandHelp } = await import("./lib/command-help");
+    console.log(commandHelp(["email", ...ctx.args], emailHelpText()));
+    return;
+  }
   ctx.args = ctx.args.flatMap((arg) => {
     const split = arg.startsWith("--") ? arg.indexOf("=") : -1;
     return split > 2 ? [arg.slice(0, split), arg.slice(split + 1)] : [arg];
@@ -454,7 +482,11 @@ export async function runEmailCommand(ctx: EmailCliContext): Promise<void> {
   ctx.jsonOutput = hasFlag(ctx.args, "--json") || ctx.jsonOutput;
   const group = ctx.args.shift();
   if (!group || group === "help" || group === "--help" || group === "-h") {
-    emailHelp();
+    console.log(emailHelpText());
+    return;
+  }
+  if (group === "inbox") {
+    await runEmailInboxCommand(ctx);
     return;
   }
   if (group === "draft") {
@@ -524,14 +556,20 @@ function parseAddressList(
 }
 
 async function runSend(ctx: EmailCliContext) {
-  if (ctx.args.includes("--mailbox")) {
+  const wait = waitFlag(ctx.args);
+  if (!ctx.args.includes("--from")) {
     const content = {
       ...(await draftContent(ctx)),
-      mailbox: requiredFlag(ctx.args, "--mailbox"),
+      mailbox: getFlag(ctx.args, "--mailbox"),
       threadId: getFlag(ctx.args, "--thread") ?? process.env.DENCH_THREAD_ID,
       mode: "send",
     };
-    const payload = await createNativeEmail(ctx, content);
+    if (!Array.isArray(content.to) || content.to.length === 0)
+      throw new EmailCliError("Sending requires --to <email>");
+    const created = await createNativeEmail(ctx, content);
+    const payload = wait
+      ? await observeNativeEmail(ctx, created, wait)
+      : created;
     out(ctx, payload, JSON.stringify(payload, null, 2));
     return;
   }
@@ -575,6 +613,50 @@ async function runSend(ctx: EmailCliContext) {
   );
 }
 
+function waitFlag(args: string[]): number {
+  const noWait = hasFlag(args, "--no-wait");
+  const raw = getFlag(args, "--wait");
+  if (raw !== undefined && noWait)
+    throw new EmailCliError("Use --wait or --no-wait, not both");
+  const seconds = raw === undefined ? 10 : Number(raw);
+  if (
+    raw?.trim() === "" ||
+    !Number.isFinite(seconds) ||
+    seconds < 0 ||
+    seconds > 60
+  )
+    throw new EmailCliError(
+      "--wait must be a finite number of seconds from 0 to 60",
+    );
+  return noWait ? 0 : seconds * 1000;
+}
+
+function observeNativeEmail(
+  ctx: EmailCliContext,
+  receipt: unknown,
+  waitMs: number,
+) {
+  return waitForNativeEmail(
+    receipt,
+    ctx.readNativeReceipt ??
+      ((draftId, signal) => {
+        const reader = new ConvexHttpClient(ctx.convex.url, {
+          logger: false,
+          fetch: new Proxy(fetch, {
+            apply(target, _receiver, [input, init]) {
+              return target(input, { ...init, signal });
+            },
+          }),
+        });
+        return reader.query(
+          makeFunctionReference<"query">("functions/emailDrafts:get"),
+          { draftId, sessionToken: ctx.sessionToken },
+        );
+      }),
+    waitMs,
+  );
+}
+
 /** Persist before HTTP. Identical invocations recover the same request even
  * after the CLI process dies; an explicit new --request-id starts another email. */
 async function createNativeEmail(ctx: EmailCliContext, content: JsonRecord) {
@@ -615,7 +697,7 @@ async function createNativeEmail(ctx: EmailCliContext, content: JsonRecord) {
 }
 
 function assertEmailArgs(ctx: EmailCliContext) {
-  assertNoUnknownFlags(ctx.args, "dench email");
+  assertNoUnknownFlags(ctx.args, "email");
   if (ctx.args.length)
     throw new EmailCliError(`Unexpected argument: ${ctx.args[0]}`);
 }
@@ -671,6 +753,7 @@ async function runDraft(ctx: EmailCliContext) {
             draftId,
           });
   } else if (sub === "update" || sub === "send") {
+    const wait = sub === "send" ? waitFlag(ctx.args) : 0;
     const draftId = draftIdArg(ctx);
     const expectedRevision = revisionArg(ctx);
     const args =
@@ -690,6 +773,7 @@ async function runDraft(ctx: EmailCliContext) {
           };
     assertEmailArgs(ctx);
     result = await callMutation(ctx, `functions/emailDrafts:${sub}`, args);
+    if (wait) result = await observeNativeEmail(ctx, result, wait);
   } else if (sub === "attach") {
     const draftId = draftIdArg(ctx);
     const expectedRevision = revisionArg(ctx);
@@ -1146,6 +1230,8 @@ async function runCampaign(ctx: EmailCliContext) {
   const sub = ctx.args.shift();
   if (sub === "create") {
     const sender = await campaignSenderArgs(ctx);
+    const scheduledAt = getFlag(ctx.args, "--scheduled-at");
+    const maxRecipients = getFlag(ctx.args, "--max-recipients");
     const payload = await callMutation(
       ctx,
       "functions/emailCampaigns:createCampaign",
@@ -1153,12 +1239,8 @@ async function runCampaign(ctx: EmailCliContext) {
         name: requiredFlag(ctx.args, "--name"),
         ...sender,
         templateId: requiredFlag(ctx.args, "--template"),
-        scheduledAt: getFlag(ctx.args, "--scheduled-at")
-          ? Date.parse(requiredFlag(ctx.args, "--scheduled-at"))
-          : undefined,
-        maxRecipients: getFlag(ctx.args, "--max-recipients")
-          ? Number(requiredFlag(ctx.args, "--max-recipients"))
-          : undefined,
+        scheduledAt: scheduledAt ? Date.parse(scheduledAt) : undefined,
+        maxRecipients: maxRecipients ? Number(maxRecipients) : undefined,
       },
     );
     out(
@@ -1377,7 +1459,7 @@ async function runSequence(ctx: EmailCliContext) {
         ...sender,
         replyToMode: getFlag(ctx.args, "--reply-to-mode"),
         stopOnReply,
-        stopOnClick: getFlag(ctx.args, "--stop-on-click") !== undefined,
+        stopOnClick: hasFlag(ctx.args, "--stop-on-click"),
       },
     );
     out(
@@ -1426,7 +1508,7 @@ async function runSequence(ctx: EmailCliContext) {
     const payload = await callQuery(
       ctx,
       "functions/emailSequences:listSequences",
-      { includeArchived: getFlag(ctx.args, "--all") !== undefined },
+      { includeArchived: hasFlag(ctx.args, "--all") },
     );
     out(ctx, payload, JSON.stringify(payload, null, 2));
     return;