@primitivedotdev/sdk 0.19.0 → 0.21.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { A as UnknownEvent, C as ParsedDataFailed, D as RawContentDownloadOnly, E as RawContent, M as WebhookAttachment, N as WebhookEvent, O as RawContentInline, S as ParsedDataComplete, T as ParsedStatus, _ as ForwardResultInline, a as DmarcPolicy, b as KnownWebhookEvent, c as EmailAnalysis, d as EventType, f as ForwardAnalysis, g as ForwardResultAttachmentSkipped, h as ForwardResultAttachmentAnalyzed, i as DkimSignature, j as ValidateEmailAuthResult, k as SpfResult, l as EmailAuth, m as ForwardResult, n as AuthVerdict, o as DmarcResult, p as ForwardOriginalSender, r as DkimResult, s as EmailAddress, t as AuthConfidence, u as EmailReceivedEvent, v as ForwardVerdict, w as ParsedError, x as ParsedData, y as ForwardVerification } from "./types-9vXGZjPd.js";
 import { a as buildReplySubject, c as parseHeaderAddress, i as buildForwardSubject, n as ReceivedEmailAddress, o as formatAddress, r as ReceivedEmailThread, s as normalizeReceivedEmail, t as ReceivedEmail } from "./received-email-DNjpq_Wt.js";
-import { a as PrimitiveApiError, c as PrimitiveClientOptions, d as SendInput, f as SendResult, g as createPrimitiveClient, l as ReplyInput, m as client, n as ForwardInput, p as SendThreadInput, s as PrimitiveClient } from "./index-oRkCqj6u.js";
+import { _ as createPrimitiveClient, c as PrimitiveClient, f as SendInput, h as client, l as PrimitiveClientOptions, m as SendThreadInput, o as PrimitiveApiError, p as SendResult, r as ForwardInput, u as ReplyInput } from "./index-QTYQpSFt.js";
 import { A as VerifyOptions, B as PAYLOAD_ERRORS, C as signStandardWebhooksPayload, D as PRIMITIVE_CONFIRMED_HEADER, E as LEGACY_SIGNATURE_HEADER, F as VerifyDownloadTokenResult, G as VERIFICATION_ERRORS, H as RAW_EMAIL_ERRORS, I as generateDownloadToken, J as WebhookPayloadErrorCode, K as WebhookErrorCode, L as verifyDownloadToken, M as verifyWebhookSignature, N as GenerateDownloadTokenOptions, O as PRIMITIVE_SIGNATURE_HEADER, P as VerifyDownloadTokenOptions, Q as WebhookVerificationErrorCode, R as safeValidateEmailReceivedEvent, S as StandardWebhooksVerifyOptions, T as LEGACY_CONFIRMED_HEADER, U as RawEmailDecodeError, V as PrimitiveWebhookError, W as RawEmailDecodeErrorCode, X as WebhookValidationErrorCode, Y as WebhookValidationError, Z as WebhookVerificationError, _ as emailReceivedEventJsonSchema, a as confirmedHeaders, b as STANDARD_WEBHOOK_TIMESTAMP_HEADER, c as handleWebhook, d as isRawIncluded, f as parseWebhookEvent, g as validateEmailAuth, h as WEBHOOK_VERSION, i as WebhookHeaders, j as signWebhookPayload, k as SignResult, l as isDownloadExpired, m as verifyRawEmailDownload, n as HandleWebhookOptions, o as decodeRawEmail, p as receive, q as WebhookPayloadError, r as ReceiveRequestOptions, s as getDownloadTimeRemaining, t as DecodeRawEmailOptions, u as isEmailReceivedEvent, v as STANDARD_WEBHOOK_ID_HEADER, w as verifyStandardWebhooksSignature, x as StandardWebhooksSignResult, y as STANDARD_WEBHOOK_SIGNATURE_HEADER, z as validateEmailReceivedEvent } from "./index-CDlwyxdp.js";
 
 //#region src/index.d.ts

package/dist/index.js

@@ -1,5 +1,5 @@
 import { a as parseHeaderAddress, i as normalizeReceivedEmail, n as buildReplySubject, r as formatAddress, t as buildForwardSubject } from "./received-email-D6tKtWwW.js";
-import { a as client, i as PrimitiveClient, r as PrimitiveApiError, s as createPrimitiveClient } from "./api-C5VR_Opg.js";
+import { a as PrimitiveClient, c as createPrimitiveClient, i as PrimitiveApiError, o as client } from "./api-BjzvA2Fy.js";
 import { A as PRIMITIVE_CONFIRMED_HEADER, B as RAW_EMAIL_ERRORS, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, G as WebhookVerificationError, H as VERIFICATION_ERRORS, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, R as PAYLOAD_ERRORS, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, U as WebhookPayloadError, V as RawEmailDecodeError, W as WebhookValidationError, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict, z as PrimitiveWebhookError } from "./webhook-rUjGV6Zu.js";
 //#region src/index.ts
 const primitive = {

package/dist/oclif/api-command.js

@@ -224,6 +224,19 @@ export function readJsonBody(flags) {
     }
     return undefined;
 }
+// Read a UTF-8 text file off disk, mapping any failure to a CLIError
+// tagged with the originating flag so the user sees which path failed
+// to open. Used by hand-rolled commands that take a file-input flag
+// (e.g. functions:deploy --file).
+export function readTextFileFlag(path, flagLabel) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw cliError(`Could not read ${flagLabel} ${path}: ${detail}`);
+    }
+}
 export function extractErrorPayload(raw) {
     if (raw &&
         typeof raw === "object" &&
@@ -320,9 +333,12 @@ export function removeStaleSavedCredentialOnUnauthorized(params) {
     }
     const baseUrlDiffersFromSaved = params.baseUrlOverridden &&
         params.auth.credentials !== null &&
-        params.auth.baseUrl !== params.auth.credentials.base_url;
+        params.auth.apiBaseUrl1 !== params.auth.credentials.api_base_url_1;
     if (baseUrlDiffersFromSaved) {
-        process.stderr.write("Saved Primitive CLI credentials were rejected by the overridden API base URL. The local credential was not removed; check --base-url / PRIMITIVE_API_URL, or run `primitive logout` to remove it.\n");
+        // Override env vars (PRIMITIVE_API_BASE_URL_1 / _2) are intentionally
+        // not advertised in --help; this hint is the only customer-visible
+        // mention. They're for internal staging/local testing.
+        process.stderr.write("Saved Primitive CLI credentials were rejected by the overridden API base URL. The local credential was not removed; unset PRIMITIVE_API_BASE_URL_1, or run `primitive logout` to remove the stored credential.\n");
         return false;
     }
     deleteCliCredentials(params.configDir);
@@ -368,10 +384,45 @@ export async function runWithTiming(enabled, fn) {
 // own static flags. Lives here so the flag's description and short
 // name stay consistent across the hand-coded and generated commands.
 export const TIME_FLAG_DESCRIPTION = "Print the wall-clock duration of this command to stderr after it completes (e.g. `[time: 1.34s]`). Useful for measuring `--wait` send latency, comparing CLI overhead, or capturing timing in scripts.";
+// Shared description text for the api-base-url override flags. Keeps
+// the wording identical across every command that includes them. The
+// flags themselves are hidden from --help (internal staging/local-only).
+export const API_BASE_URL_1_FLAG_DESCRIPTION = "Override the primary API base URL. Internal testing only; not documented to customers.";
+export const API_BASE_URL_2_FLAG_DESCRIPTION = "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.";
+// Helper: was either api-base-url override set by the caller? Used by
+// removeStaleSavedCredentialOnUnauthorized to decide whether to
+// preserve the saved credential when a 401 comes back.
+export function baseUrlOverriddenFromFlags(flags) {
+    return (typeof flags["api-base-url-1"] === "string" ||
+        typeof flags["api-base-url-2"] === "string");
+}
+// Helper: resolve auth from a parsed-flags bag. Mirrors what every CLI
+// command does inline so the api-base-url-1 / api-base-url-2 mapping
+// stays in one place as we add more migration knobs.
+export function resolveCliAuthFromFlags(flags, configDir) {
+    return resolveCliAuth({
+        apiKey: typeof flags["api-key"] === "string"
+            ? flags["api-key"]
+            : undefined,
+        apiBaseUrl1: typeof flags["api-base-url-1"] === "string"
+            ? flags["api-base-url-1"]
+            : undefined,
+        apiBaseUrl2: typeof flags["api-base-url-2"] === "string"
+            ? flags["api-base-url-2"]
+            : undefined,
+        configDir,
+    });
+}
+// Operations that route to the attachments-supporting host
+// (apiBaseUrl2) instead of the primary API host. Internal to the CLI:
+// as more operations migrate to host 2 over time, add their generated
+// sdkName here. Today it is just /send-mail.
+const HOST_2_OPERATIONS = new Set(["sendEmail"]);
 // Reserved flag names the body-field expander must never overwrite.
 // `--raw-body` and `--body-file` are the JSON escape hatches.
-// `--api-key`, `--base-url`, `--output` are infra. Path and query
-// params get added before body fields and take precedence.
+// `--api-key`, `--api-base-url-1`, `--api-base-url-2`, `--output` are
+// infra. Path and query params get added before body fields and take
+// precedence.
 //
 // Note: `--body` is intentionally NOT reserved here. The naive
 // agent expectation (per AGX walkthrough) is that --body means
@@ -386,7 +437,8 @@ export const TIME_FLAG_DESCRIPTION = "Print the wall-clock duration of this comm
 // send` defines its own --body for the message text.
 const RESERVED_FLAG_NAMES = new Set([
     "api-key",
-    "base-url",
+    "api-base-url-1",
+    "api-base-url-2",
     "raw-body",
     "body-file",
     "output",
@@ -425,9 +477,20 @@ function buildFlags(operation) {
             description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
             env: "PRIMITIVE_API_KEY",
         }),
-        "base-url": Flags.string({
-            description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
-            env: "PRIMITIVE_API_URL",
+        // Two override knobs for the dual-host setup. Hidden because they
+        // are for internal staging/local testing only. Production users
+        // should not override; the defaults route correctly. Env vars
+        // PRIMITIVE_API_BASE_URL_1 and PRIMITIVE_API_BASE_URL_2 carry the
+        // same semantics. Both are intentionally absent from --help output.
+        "api-base-url-1": Flags.string({
+            description: "Override the primary API base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "api-base-url-2": Flags.string({
+            description: "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_2",
+            hidden: true,
         }),
         time: Flags.boolean({
             description: TIME_FLAG_DESCRIPTION,
@@ -530,19 +593,24 @@ export function createOperationCommand(operation) {
             const { flags } = await this.parse(OperationCommand);
             const parsedFlags = flags;
             await runWithTiming(parsedFlags.time === true, async () => {
-                const baseUrlOverridden = typeof parsedFlags["base-url"] === "string";
+                const baseUrlOverridden = typeof parsedFlags["api-base-url-1"] === "string" ||
+                    typeof parsedFlags["api-base-url-2"] === "string";
                 const auth = resolveCliAuth({
                     apiKey: typeof parsedFlags["api-key"] === "string"
                         ? parsedFlags["api-key"]
                         : undefined,
-                    baseUrl: typeof parsedFlags["base-url"] === "string"
-                        ? parsedFlags["base-url"]
+                    apiBaseUrl1: typeof parsedFlags["api-base-url-1"] === "string"
+                        ? parsedFlags["api-base-url-1"]
+                        : undefined,
+                    apiBaseUrl2: typeof parsedFlags["api-base-url-2"] === "string"
+                        ? parsedFlags["api-base-url-2"]
                         : undefined,
                     configDir: this.config.configDir,
                 });
                 const apiClient = new PrimitiveApiClient({
                     apiKey: auth.apiKey,
-                    baseUrl: auth.baseUrl,
+                    apiBaseUrl1: auth.apiBaseUrl1,
+                    apiBaseUrl2: auth.apiBaseUrl2,
                 });
                 // Two body sources, merged: explicit JSON via --body /
                 // --body-file (the base) plus per-field flags (the
@@ -588,9 +656,15 @@ export function createOperationCommand(operation) {
                     throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --raw-body / --body-file.`);
                 }
                 const operationFn = operations[operation.sdkName];
+                // Operations in HOST_2_OPERATIONS route to the attachments-
+                // supporting send host (apiBaseUrl2). Today that's only
+                // sendEmail; the list grows as we migrate more endpoints.
+                const targetClient = HOST_2_OPERATIONS.has(operation.sdkName)
+                    ? apiClient._sendClient
+                    : apiClient.client;
                 const result = await operationFn({
                     body,
-                    client: apiClient.client,
+                    client: targetClient,
                     parseAs: operation.binaryResponse ? "blob" : "auto",
                     path: collectValues(operation.pathParams, parsedFlags),
                     query: collectValues(operation.queryParams, parsedFlags),

package/dist/oclif/auth.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
-import { DEFAULT_BASE_URL } from "../api/index.js";
+import { DEFAULT_API_BASE_URL_1, DEFAULT_API_BASE_URL_2, } from "../api/index.js";
 const CREDENTIALS_FILE = "credentials.json";
 const CREDENTIALS_LOCK_DIR = "credentials.lock";
 const CREDENTIALS_LOCK_STALE_MS = 30 * 60 * 1000;
@@ -16,10 +16,34 @@ function requireString(value, key) {
     }
     return raw;
 }
+/**
+ * Sentinel returned by parseCredentials when the on-disk credentials
+ * were written by a pre-dual-host CLI version (i.e. they have
+ * `base_url` instead of `api_base_url_1`). The caller treats this as
+ * "no saved credentials" after auto-cleaning the stale file. Defined
+ * as a class-tagged error so loadCliCredentials can distinguish it
+ * from a genuine malformed-credentials error.
+ */
+class StaleCredentialFormatError extends Error {
+    constructor() {
+        super("stale_credential_format");
+        this.name = "StaleCredentialFormatError";
+    }
+}
 function parseCredentials(raw) {
     if (!isRecord(raw)) {
         throw new Error(`Stored Primitive CLI credentials are malformed: expected a JSON object. ${MALFORMED_CREDENTIALS_HINT}`);
     }
+    // Stored credentials from an older CLI version used the field name
+    // `base_url`; the dual-host rename moved this to `api_base_url_1`.
+    // Detect the old shape specifically so loadCliCredentials can wipe
+    // the stale file and emit a clear "you've been logged out" notice
+    // instead of every command hard-failing with a generic "malformed"
+    // error that doesn't surface the actual fix (re-login).
+    if (typeof raw.api_base_url_1 !== "string" &&
+        typeof raw.base_url === "string") {
+        throw new StaleCredentialFormatError();
+    }
     const orgName = raw.org_name;
     if (orgName !== null && typeof orgName !== "string") {
         throw new Error(`Stored Primitive CLI credentials are malformed: org_name must be a string or null. ${MALFORMED_CREDENTIALS_HINT}`);
@@ -30,19 +54,25 @@ function parseCredentials(raw) {
         key_prefix: requireString(raw, "key_prefix"),
         org_id: requireString(raw, "org_id"),
         org_name: orgName,
-        base_url: requireString(raw, "base_url"),
+        api_base_url_1: requireString(raw, "api_base_url_1"),
         created_at: requireString(raw, "created_at"),
     };
 }
 export function credentialsPath(configDir) {
     return join(configDir, CREDENTIALS_FILE);
 }
-export function normalizeBaseUrl(baseUrl) {
-    const trimmed = baseUrl?.trim();
+function normalize(url, fallback) {
+    const trimmed = url?.trim();
     if (!trimmed)
-        return DEFAULT_BASE_URL;
+        return fallback;
     return trimmed.replace(/\/+$/, "");
 }
+export function normalizeApiBaseUrl1(url) {
+    return normalize(url, DEFAULT_API_BASE_URL_1);
+}
+export function normalizeApiBaseUrl2(url) {
+    return normalize(url, DEFAULT_API_BASE_URL_2);
+}
 export function loadCliCredentials(configDir) {
     const path = credentialsPath(configDir);
     let contents;
@@ -62,6 +92,24 @@ export function loadCliCredentials(configDir) {
         return parseCredentials(JSON.parse(contents));
     }
     catch (error) {
+        if (error instanceof StaleCredentialFormatError) {
+            // Saved credentials were written by a pre-dual-host CLI version.
+            // The format is incompatible (base_url vs api_base_url_1) and
+            // cannot be recovered. Clear the file so the caller sees "no
+            // saved credentials" and emit a one-shot notice telling the
+            // user they need to log back in. Idempotent: once the file is
+            // gone, this branch never fires again.
+            try {
+                rmSync(path, { force: true });
+            }
+            catch {
+                // Best-effort cleanup; if the unlink fails (permissions,
+                // racing process), the next CLI invocation will hit this
+                // path again and try once more.
+            }
+            process.stderr.write("You've been logged out: your saved Primitive CLI credentials were created by an older CLI version and are no longer compatible. Run `primitive login` to re-authenticate.\n");
+            return null;
+        }
         if (error instanceof SyntaxError) {
             throw new Error("Stored Primitive CLI credentials are not valid JSON. Run `primitive logout` and then `primitive login`.");
         }
@@ -140,10 +188,15 @@ export function acquireCliCredentialsLock(configDir, options = {}) {
 }
 export function resolveCliAuth(params) {
     const apiKey = params.apiKey?.trim();
+    // Host 2 (api_base_url_2) is never stored; either set by env/flag or
+    // falls back to the production default. The login flow only deals
+    // with host 1.
+    const apiBaseUrl2 = normalizeApiBaseUrl2(params.apiBaseUrl2);
     if (apiKey) {
         return {
             apiKey,
-            baseUrl: normalizeBaseUrl(params.baseUrl),
+            apiBaseUrl1: normalizeApiBaseUrl1(params.apiBaseUrl1),
+            apiBaseUrl2,
             credentials: null,
             source: "flag-or-env",
         };
@@ -152,16 +205,18 @@ export function resolveCliAuth(params) {
     if (credentials) {
         return {
             apiKey: credentials.api_key,
-            baseUrl: params.baseUrl
-                ? normalizeBaseUrl(params.baseUrl)
-                : credentials.base_url,
+            apiBaseUrl1: params.apiBaseUrl1
+                ? normalizeApiBaseUrl1(params.apiBaseUrl1)
+                : credentials.api_base_url_1,
+            apiBaseUrl2,
             credentials,
             source: "stored",
         };
     }
     return {
         apiKey: undefined,
-        baseUrl: normalizeBaseUrl(params.baseUrl),
+        apiBaseUrl1: normalizeApiBaseUrl1(params.apiBaseUrl1),
+        apiBaseUrl2,
         credentials: null,
         source: "none",
     };

package/dist/oclif/commands/emails-latest.js

@@ -80,6 +80,9 @@ export function formatRow(email, idWidth) {
     const subjectCol = truncate(subject, SUBJECT_DISPLAY_WIDTH);
     return `${id}  ${received}  ${from}  ${to}  ${subjectCol}`;
 }
+export function formatHeader(idWidth) {
+    return `${"ID".padEnd(idWidth)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
+}
 class EmailsLatestCommand extends Command {
     static description = `Print the N most recent inbound emails as a one-line-per-row text table. Designed for quick triage and visual scanning. For programmatic access, use \`primitive emails:list-emails\` (full JSON envelope, cursor pagination, filters) or pass \`--json\` here for the same raw shape without pagination/filters.
 
@@ -88,19 +91,25 @@ class EmailsLatestCommand extends Command {
   Output streams: the column header line is written to STDERR so the row data on STDOUT stays grep/awk-friendly. \`--json\` writes everything (including the envelope) to STDOUT and is equivalent to running \`emails:list-emails --limit N\` for the same N.`;
     static summary = "Show the most recent inbound emails as a compact table";
     static examples = [
-        "<%= config.bin %> emails:latest",
-        "<%= config.bin %> emails:latest --limit 25",
-        "<%= config.bin %> emails:latest | head -1 | awk '{print $1}'  # full UUID since piped",
-        "<%= config.bin %> emails:latest --json | jq '.data[0].id'",
+        "<%= config.bin %> emails latest",
+        "<%= config.bin %> emails latest --limit 25",
+        "<%= config.bin %> emails latest | head -1 | awk '{print $1}'  # full UUID since piped",
+        "<%= config.bin %> emails latest --json | jq '.data[0].id'",
     ];
     static flags = {
         "api-key": Flags.string({
             description: "Primitive API key (defaults to PRIMITIVE_API_KEY or saved `primitive login` credentials)",
             env: "PRIMITIVE_API_KEY",
         }),
-        "base-url": Flags.string({
-            description: "API base URL (defaults to PRIMITIVE_API_URL or production)",
-            env: "PRIMITIVE_API_URL",
+        "api-base-url-1": Flags.string({
+            description: "Override the primary API base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_1",
+            hidden: true,
+        }),
+        "api-base-url-2": Flags.string({
+            description: "Override the attachments-supporting send host base URL. Internal testing only; not documented to customers.",
+            env: "PRIMITIVE_API_BASE_URL_2",
+            hidden: true,
         }),
         limit: Flags.integer({
             description: `Number of rows to print (1-${MAX_LIMIT}, default ${DEFAULT_LIMIT}).`,
@@ -121,15 +130,18 @@ class EmailsLatestCommand extends Command {
     async run() {
         const { flags } = await this.parse(EmailsLatestCommand);
         await runWithTiming(flags.time, async () => {
-            const baseUrlOverridden = flags["base-url"] !== undefined;
+            const baseUrlOverridden = flags["api-base-url-1"] !== undefined ||
+                flags["api-base-url-2"] !== undefined;
             const auth = resolveCliAuth({
                 apiKey: flags["api-key"],
-                baseUrl: flags["base-url"],
+                apiBaseUrl1: flags["api-base-url-1"],
+                apiBaseUrl2: flags["api-base-url-2"],
                 configDir: this.config.configDir,
             });
             const apiClient = new PrimitiveApiClient({
                 apiKey: auth.apiKey,
-                baseUrl: auth.baseUrl,
+                apiBaseUrl1: auth.apiBaseUrl1,
+                apiBaseUrl2: auth.apiBaseUrl2,
             });
             const result = await listEmails({
                 client: apiClient.client,
@@ -163,8 +175,7 @@ class EmailsLatestCommand extends Command {
             }
             const idWidth = pickIdWidth(Boolean(process.stdout.isTTY));
             // Header on stderr so the table itself stays grep-friendly.
-            const header = `${"ID".padEnd(idWidth)}  ${"RECEIVED (UTC)".padEnd(RECEIVED_DISPLAY_WIDTH)}  ${"FROM".padEnd(ADDRESS_DISPLAY_WIDTH)}  ${"TO".padEnd(ADDRESS_DISPLAY_WIDTH)}  SUBJECT`;
-            process.stderr.write(`${header}\n`);
+            process.stderr.write(`${formatHeader(idWidth)}\n`);
             for (const row of rows) {
                 this.log(formatRow(row, idWidth));
             }

package/dist/oclif/commands/emails-poll.js

@@ -0,0 +1,121 @@
+import { searchEmails } from "../../api/generated/sdk.gen.js";
+export const DEFAULT_EMAIL_POLL_INTERVAL_SECONDS = 2;
+export const DEFAULT_EMAIL_POLL_PAGE_SIZE = 50;
+export const MAX_EMAIL_POLL_PAGE_SIZE = 100;
+function quoteDslValue(value) {
+    if (/^[^\s"]+$/.test(value))
+        return value;
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function combineQ(q, domain) {
+    const parts = [
+        q?.trim(),
+        domain ? `domain:${quoteDslValue(domain.trim())}` : undefined,
+    ].filter((part) => Boolean(part));
+    return parts.length > 0 ? parts.join(" ") : undefined;
+}
+export function normalizeIsoDate(value, label) {
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new Error(`${label} must be a valid date or ISO-8601 timestamp.`);
+    }
+    return parsed.toISOString();
+}
+export function filtersFromFlags(flags) {
+    return {
+        body: flags.body,
+        domain: flags.domain,
+        domainId: flags["domain-id"],
+        from: flags.from,
+        hasAttachment: flags["has-attachment"],
+        q: flags.q,
+        spamScoreGte: flags["spam-score-gte"],
+        spamScoreLt: flags["spam-score-lt"],
+        subject: flags.subject,
+        to: flags.to,
+    };
+}
+export function sinceFromFlags(flags) {
+    if (flags.since)
+        return normalizeIsoDate(flags.since, "--since");
+    return flags["include-existing"] ? undefined : new Date().toISOString();
+}
+export function buildEmailSearchQuery(params) {
+    const query = {
+        include_facets: "false",
+        limit: params.pageSize,
+        snippet: "false",
+        sort: "received_at_asc",
+    };
+    const q = combineQ(params.filters.q, params.filters.domain);
+    if (q)
+        query.q = q;
+    if (params.filters.body)
+        query.body = params.filters.body;
+    if (params.filters.domainId)
+        query.domain_id = params.filters.domainId;
+    if (params.filters.from)
+        query.from = params.filters.from;
+    if (params.filters.hasAttachment !== undefined) {
+        query.has_attachment = params.filters.hasAttachment ? "true" : "false";
+    }
+    if (params.filters.spamScoreGte !== undefined) {
+        query.spam_score_gte = params.filters.spamScoreGte;
+    }
+    if (params.filters.spamScoreLt !== undefined) {
+        query.spam_score_lt = params.filters.spamScoreLt;
+    }
+    if (params.filters.subject)
+        query.subject = params.filters.subject;
+    if (params.filters.to)
+        query.to = params.filters.to;
+    if (params.since)
+        query.date_from = params.since;
+    if (params.cursor)
+        query.cursor = params.cursor;
+    return query;
+}
+export function encodeReceivedAtSearchCursor(email) {
+    const raw = `r|${new Date(email.received_at).toISOString()}|${email.id}`;
+    return Buffer.from(raw, "utf8").toString("base64url");
+}
+export function cursorFromRows(rows) {
+    const last = rows.at(-1);
+    return last ? encodeReceivedAtSearchCursor(last) : null;
+}
+export function collectNewAcceptedEmails(rows, seenIds) {
+    const fresh = [];
+    for (const row of rows) {
+        if (row.status !== "accepted" && row.status !== "completed")
+            continue;
+        if (seenIds.has(row.id))
+            continue;
+        seenIds.add(row.id);
+        fresh.push(row);
+    }
+    return fresh;
+}
+export async function fetchEmailSearchPage(params) {
+    const result = await searchEmails({
+        client: params.apiClient.client,
+        query: buildEmailSearchQuery({
+            cursor: params.cursor,
+            filters: params.filters,
+            pageSize: params.pageSize,
+            since: params.since,
+        }),
+        responseStyle: "fields",
+    });
+    if (result.error)
+        return { ok: false, error: result.error };
+    const envelope = result.data;
+    const rows = envelope?.data ?? [];
+    return {
+        ok: true,
+        cursor: envelope?.meta.cursor ?? cursorFromRows(rows),
+        rows,
+    };
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}