@brew.new/cli 0.8.0 → 0.10.0

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createInterface } from 'readline/promises';
+import { BrewApiError, BrewConnectionError, BrewTimeoutError, createBrewClient, GENERATE_IMAGE_DEFAULT_TIMEOUT_MS, GIF_DEFAULT_TIMEOUT_MS, AUDIT_EMAIL_DEFAULT_TIMEOUT_MS, EDIT_EMAIL_DEFAULT_TIMEOUT_MS, GENERATE_EMAIL_DEFAULT_TIMEOUT_MS, IMPORT_EMAIL_DEFAULT_TIMEOUT_MS, IMPORT_FIGMA_DEFAULT_TIMEOUT_MS, PREVIEW_EMAIL_CLIENTS_DEFAULT_TIMEOUT_MS } from '@brew.new/sdk';
 import { CommanderError, Command } from 'commander';
-import { BrewApiError, createBrewClient, AUDIT_EMAIL_DEFAULT_TIMEOUT_MS } from '@brew.new/sdk';
 import { readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
@@ -12,6 +12,35 @@ var EXIT_RUNTIME = 1;
 var EXIT_USAGE = 2;
 var EXIT_AUTH = 3;
 var EXIT_CONFIRM = 4;
+var EXIT_INTERRUPTED = 130;
+var EXIT_TERMINATED = 143;
+function exitCodeForSignal(signal) {
+  return signal === "SIGINT" ? EXIT_INTERRUPTED : EXIT_TERMINATED;
+}
+var CliInterruptError = class extends Error {
+  signal;
+  constructor(signal) {
+    super(signal === "SIGINT" ? "Interrupted." : "Terminated.");
+    this.name = "CliInterruptError";
+    this.signal = signal;
+  }
+};
+var CliTimeoutError = class extends Error {
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`No complete response within ${timeoutMs}ms.`);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var CliConnectionError = class extends Error {
+  constructor(cause) {
+    super("The connection failed before a complete response arrived.", {
+      cause
+    });
+    this.name = "CliConnectionError";
+  }
+};
 var CliUsageError = class extends Error {
 };
 var CliAuthError = class extends Error {
@@ -88,6 +117,9 @@ var ConfirmationRequiredError = class extends Error {
   }
 };
 function toExitCode(error) {
+  if (error instanceof CliInterruptError) {
+    return exitCodeForSignal(error.signal);
+  }
   if (error instanceof ConfirmationRequiredError) {
     return EXIT_CONFIRM;
   }
@@ -103,7 +135,40 @@ function toExitCode(error) {
   }
   return EXIT_RUNTIME;
 }
-function toErrorEnvelope(error) {
+function toErrorEnvelope(error, context = {}) {
+  const envelope = baseEnvelope(error, context);
+  const drain = context.drain;
+  return withReplayAdvice(
+    drain === void 0 ? envelope : { ...envelope, progress: drain },
+    error,
+    context
+  );
+}
+function baseEnvelope(error, context) {
+  if (error instanceof CliInterruptError) {
+    return {
+      code: "CLI_INTERRUPTED",
+      type: "cancelled",
+      message: `${error.signal === "SIGINT" ? "Interrupted" : "Terminated"} (${error.signal}) ${context.request === void 0 ? "before any request was sent." : `while waiting for ${context.request.method} ${pathOnly(context.request.path)}.`}`
+    };
+  }
+  if (isTimeoutError(error)) {
+    return {
+      code: "CLI_TIMEOUT",
+      type: "service_unavailable",
+      message: timeoutMessage(error, context),
+      suggestion: "Retry the request. Reuse the same Idempotency-Key for a POST request."
+    };
+  }
+  if (error instanceof BrewConnectionError || error instanceof CliConnectionError) {
+    const cause = error.cause instanceof Error && error.cause.message !== "" ? `: ${error.cause.message}` : "";
+    return {
+      code: "CLI_CONNECTION",
+      type: "service_unavailable",
+      message: error instanceof BrewConnectionError ? error.message : `${error.message.replace(/\.$/, "")}${context.request === void 0 ? "" : ` (${context.request.method} ${pathOnly(context.request.path)})`}${cause}.`,
+      suggestion: "Check the connection and retry the request."
+    };
+  }
   if (error instanceof BrewApiError || error instanceof CliApiError) {
     const details = readErrorDetails(error);
     return {
@@ -133,14 +198,6 @@ function toErrorEnvelope(error) {
       message: error.message
     };
   }
-  if (isTimeoutError(error)) {
-    return {
-      code: "CLI_TIMEOUT",
-      type: "service_unavailable",
-      message: "The request timed out before the API responded.",
-      suggestion: "Retry the request. Reuse the same Idempotency-Key for a POST request."
-    };
-  }
   if (error instanceof CommandAbortedError) {
     return {
       code: "CLI_ABORTED",
@@ -155,7 +212,60 @@ function toErrorEnvelope(error) {
   }
   return { code: "CLI_UNEXPECTED", type: "internal_error", message };
 }
-function printError(ctx, error) {
+var IN_PROGRESS_CODE = "IDEMPOTENCY_IN_PROGRESS";
+function withReplayAdvice(envelope, error, context) {
+  if (!isUnknownOutcome(envelope)) {
+    return envelope;
+  }
+  const isInProgress = envelope.code === IN_PROGRESS_CODE || error instanceof BrewTimeoutError && error.inProgress || error instanceof BrewConnectionError && error.inProgress;
+  const holdNote = isInProgress ? " The first attempt is still running on the server, which holds its key for up to 15 minutes: until then a replay answers 409 IDEMPOTENCY_IN_PROGRESS, so wait and re-run." : "";
+  if (context.request === void 0) {
+    return envelope.code === "CLI_INTERRUPTED" ? { ...envelope, suggestion: "Nothing was sent." } : envelope;
+  }
+  if (context.isRead === true || context.request.method === "GET") {
+    return envelope.code === "CLI_INTERRUPTED" ? { ...envelope, suggestion: "It only reads; nothing was changed." } : envelope;
+  }
+  const key = errorIdempotencyKey(error) ?? context.request.idempotencyKey;
+  if (context.replays !== true || key === void 0) {
+    return {
+      ...envelope,
+      suggestion: `${pathOnly(context.request.path)} may already have been changed, and this route does not replay a request: check its current state before running it again.`
+    };
+  }
+  const retryCommand = context.retryCommand?.(key);
+  return {
+    ...envelope,
+    suggestion: `The API keeps working after the CLI disconnects, so this may still complete. Re-run with --idempotency-key ${key} to get its result instead of running it twice (the key replays for 24 hours${context.readsStdin === true ? "; pipe the same input to it again" : ""}).${holdNote}`,
+    idempotencyKey: key,
+    ...retryCommand === void 0 ? {} : { retryCommand }
+  };
+}
+function isUnknownOutcome(envelope) {
+  if (envelope.code === "CLI_INTERRUPTED" || envelope.code === "CLI_TIMEOUT" || envelope.code === "CLI_CONNECTION" || envelope.code === IN_PROGRESS_CODE) {
+    return true;
+  }
+  return envelope.status !== void 0 && envelope.status >= 500;
+}
+function errorIdempotencyKey(error) {
+  if (error instanceof BrewApiError || error instanceof BrewTimeoutError || error instanceof BrewConnectionError) {
+    return error.idempotencyKey;
+  }
+  return void 0;
+}
+function timeoutMessage(error, context) {
+  if (error instanceof BrewTimeoutError) {
+    return error.message;
+  }
+  if (error instanceof CliTimeoutError) {
+    const request = context.request;
+    return request === void 0 ? error.message : `${error.message.replace(/\.$/, "")} (${request.method} ${pathOnly(request.path)}).`;
+  }
+  return "The request timed out before the API responded.";
+}
+function pathOnly(path) {
+  return path.split("?")[0] ?? path;
+}
+function printError(ctx, error, context = {}) {
   if (error instanceof ConfirmationRequiredError) {
     ctx.io.stdout.write(`${JSON.stringify(error.envelope)}
 `);
@@ -168,7 +278,7 @@ function printError(ctx, error) {
     }
     return;
   }
-  const envelope = toErrorEnvelope(error);
+  const envelope = toErrorEnvelope(error, context);
   if (ctx.mode === "json") {
     ctx.io.stderr.write(`${JSON.stringify({ error: envelope })}
 `);
@@ -181,6 +291,15 @@ function printError(ctx, error) {
   if (envelope.suggestion) {
     lines.push(envelope.suggestion);
   }
+  if (envelope.retryCommand) {
+    lines.push(`Re-run: ${envelope.retryCommand}`);
+  }
+  if (envelope.progress) {
+    const { rowsFetched, pagesFetched, resumeCursor } = envelope.progress;
+    lines.push(
+      `Fetched ${rowsFetched} rows in ${pagesFetched} pages before stopping${resumeCursor === void 0 ? "." : `; resume with --cursor ${resumeCursor} --all.`}`
+    );
+  }
   if (envelope.docs) {
     lines.push(`Docs: ${envelope.docs}`);
   }
@@ -219,7 +338,7 @@ function apiErrorStatus(error) {
   }
 }
 function isTimeoutError(error) {
-  return typeof error === "object" && error !== null && "name" in error && error.name === "TimeoutError";
+  return error instanceof BrewTimeoutError || typeof error === "object" && error !== null && "name" in error && error.name === "TimeoutError";
 }
 
 // src/lib/confirm.ts
@@ -255,22 +374,58 @@ Proceed? [y/N] `);
   });
 }
 function buildConfirmCommand(rawArgv) {
+  return ["brew-cli", ...rerunTokens(rawArgv), "--yes"].join(" ");
+}
+function buildRetryCommand(rawArgv, idempotencyKey) {
+  return [
+    "brew-cli",
+    ...rerunTokens(rawArgv, { dropIdempotencyKey: true }),
+    "--idempotency-key",
+    shellQuote(idempotencyKey)
+  ].join(" ");
+}
+function rerunTokens(rawArgv, options = {}) {
   const tokens = [];
   for (let index = 0; index < rawArgv.length; index += 1) {
     const token = rawArgv[index];
     if (token === void 0) {
       continue;
     }
-    if (token === "--api-key") {
+    if (token === "--api-key" || options.dropIdempotencyKey === true && token === "--idempotency-key") {
       index += 1;
       continue;
     }
-    if (token.startsWith("--api-key=")) {
+    if (token.startsWith("--api-key=") || options.dropIdempotencyKey === true && token.startsWith("--idempotency-key=")) {
+      continue;
+    }
+    if (token.startsWith("--header=")) {
+      if (!isCredentialHeader(token.slice("--header=".length))) {
+        tokens.push(shellQuote(token));
+      }
+      continue;
+    }
+    if (token === "--header") {
+      const values = [];
+      while (index + 1 < rawArgv.length && !(rawArgv[index + 1] ?? "").startsWith("-")) {
+        index += 1;
+        const value = rawArgv[index] ?? "";
+        if (!isCredentialHeader(value)) {
+          values.push(shellQuote(value));
+        }
+      }
+      if (values.length > 0) {
+        tokens.push("--header", ...values);
+      }
       continue;
     }
     tokens.push(shellQuote(token));
   }
-  return ["brew-cli", ...tokens, "--yes"].join(" ");
+  return tokens;
+}
+var CREDENTIAL_HEADER_NAME = /authorization|cookie|api-?key|auth|token|secret|passw(or)?d|session|signature|credential/i;
+function isCredentialHeader(header) {
+  const name = /^\s*([^:\s]+)\s*:/.exec(header)?.[1];
+  return name !== void 0 && CREDENTIAL_HEADER_NAME.test(name);
 }
 function shellQuote(token) {
   if (/^[A-Za-z0-9@%+=:,./_-]+$/.test(token)) {
@@ -281,7 +436,7 @@ function shellQuote(token) {
 
 // src/version.ts
 var CLI_NAME = "brew-cli";
-var CLI_VERSION = "0.8.0" ;
+var CLI_VERSION = "0.10.0" ;
 var CONFIG_KEYS = ["apiKey", "brandId", "apiUrl"];
 function isConfigKey(value) {
   return CONFIG_KEYS.includes(value);
@@ -384,12 +539,18 @@ function resolveAuth(input) {
   const apiKeySource = keyFromFlag ? "flag" : keyFromEnv ? "env" : "config";
   return { apiKey, apiKeySource, brandId, apiUrl };
 }
-function buildSdkClient(auth) {
+function buildSdkClient(auth, transport) {
   return createBrewClient({
     apiKey: auth.apiKey,
     baseUrl: auth.apiUrl,
     userAgent: `${CLI_NAME}/${CLI_VERSION}`,
-    ...auth.brandId === void 0 ? {} : { brandId: auth.brandId }
+    ...auth.brandId === void 0 ? {} : { brandId: auth.brandId },
+    // Client-wide, so every call the command makes observes the interrupt
+    // and the deadline without each command file threading a signal.
+    signal: transport.signal,
+    fetch: transport.fetch,
+    ...transport.timeoutMs === void 0 ? {} : { timeoutMs: transport.timeoutMs },
+    ...transport.maxRetries === void 0 ? {} : { maxRetries: transport.maxRetries }
   });
 }
 function isOrgLevelPath(url) {
@@ -466,6 +627,114 @@ function formatCell(value) {
   return String(value);
 }
 
+// src/lib/transport.ts
+function apiPathOf(url) {
+  const index = url.pathname.indexOf("/v1/");
+  const path = index === -1 ? url.pathname : url.pathname.slice(index);
+  return `${path}${url.search}`;
+}
+function createTransportState() {
+  let lastRequest;
+  let attempts = 0;
+  let drain;
+  return {
+    lastRequest: () => lastRequest,
+    attempts: () => attempts,
+    record: (request) => {
+      lastRequest = request;
+      attempts += 1;
+    },
+    drain: () => drain,
+    setDrain: (progress2) => {
+      drain = progress2;
+    }
+  };
+}
+function recordingFetch(state) {
+  return (input, init) => {
+    if (init?.signal?.aborted === true) {
+      return globalThis.fetch(input, init);
+    }
+    const url = new URL(
+      typeof input === "string" || input instanceof URL ? input : input.url
+    );
+    state.record({
+      method: (init?.method ?? "GET").toUpperCase(),
+      path: apiPathOf(url),
+      idempotencyKey: new Headers(init?.headers).get("idempotency-key") ?? void 0
+    });
+    return globalThis.fetch(input, init);
+  };
+}
+function anySignal(signals) {
+  const present = signals.filter(
+    (signal) => signal !== void 0
+  );
+  const [only, ...rest] = present;
+  if (only !== void 0 && rest.length === 0) {
+    return { signal: only, release: () => void 0 };
+  }
+  if (typeof AbortSignal.any === "function") {
+    return { signal: AbortSignal.any(present), release: () => void 0 };
+  }
+  const controller = new AbortController();
+  const alreadyAborted = present.find((signal) => signal.aborted);
+  if (alreadyAborted !== void 0) {
+    controller.abort(alreadyAborted.reason);
+    return { signal: controller.signal, release: () => void 0 };
+  }
+  const listeners = present.map((source) => {
+    const onAbort = () => {
+      controller.abort(source.reason);
+    };
+    source.addEventListener("abort", onAbort, { once: true });
+    return { source, onAbort };
+  });
+  return {
+    signal: controller.signal,
+    release: () => {
+      for (const { source, onAbort } of listeners) {
+        source.removeEventListener("abort", onAbort);
+      }
+    }
+  };
+}
+var DURATION = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/;
+var UNIT_MS = { ms: 1, s: 1e3, m: 6e4, h: 36e5 };
+var MAX_TIMEOUT_MS = 24 * 36e5;
+function parseTimeoutFlag(value) {
+  if (value === void 0) {
+    return;
+  }
+  const match = typeof value === "string" ? DURATION.exec(value.trim()) : null;
+  const unit = match?.[2] ?? "s";
+  const ms = match === null ? Number.NaN : Math.round(Number(match[1]) * UNIT_MS[unit]);
+  if (!(ms >= 1 && ms <= MAX_TIMEOUT_MS)) {
+    throw new CliUsageError(
+      `--timeout takes a positive duration up to 24h: 90, 90s, 1500ms or 5m (a bare number is seconds); got "${String(value)}".`
+    );
+  }
+  return ms;
+}
+function parseMaxRetriesFlag(value) {
+  if (value === void 0) {
+    return;
+  }
+  const parsed = typeof value === "string" && value.trim() !== "" ? Number(value) : Number.NaN;
+  if (!(Number.isInteger(parsed) && parsed >= 0 && parsed <= 10)) {
+    throw new CliUsageError(
+      `--max-retries takes a whole number from 0 to 10; got "${String(value)}".`
+    );
+  }
+  return parsed;
+}
+function resolveBudget(input) {
+  if (input.timeoutMs !== void 0) {
+    return { deadlineMs: input.timeoutMs, attemptMs: input.timeoutMs };
+  }
+  return { deadlineMs: input.defaultTimeoutMs, attemptMs: void 0 };
+}
+
 // src/lib/context.ts
 function makeContext(input) {
   const globals = readGlobalFlags(input.flags);
@@ -473,12 +742,38 @@ function makeContext(input) {
     isJsonFlag: globals.json,
     isTtyOut: input.io.isTtyOut
   });
+  const budget = resolveBudget({
+    timeoutMs: globals.timeoutMs,
+    defaultTimeoutMs: input.traits?.defaultTimeoutMs
+  });
+  const deadline = new AbortController();
+  let deadlineTimer;
+  const { signal } = anySignal([input.io.signal, deadline.signal]);
+  const transport = createTransportState();
   const cache = /* @__PURE__ */ new Map();
-  return {
+  const ctx = {
     io: input.io,
     mode,
     globals,
     rawArgv: input.rawArgv,
+    signal,
+    budget,
+    transport,
+    traits: input.traits,
+    startDeadline: () => {
+      const ms = budget.deadlineMs;
+      if (ms === void 0 || deadlineTimer !== void 0) {
+        return;
+      }
+      deadlineTimer = setTimeout(() => {
+        deadline.abort(new CliTimeoutError(ms));
+      }, ms);
+    },
+    stopDeadline: () => {
+      if (deadlineTimer !== void 0) {
+        clearTimeout(deadlineTimer);
+      }
+    },
     client: (options) => {
       const key = options?.allowAnonymous === true ? "anonymous" : "authed";
       const existing = cache.get(key);
@@ -490,11 +785,20 @@ function makeContext(input) {
         env: input.io.env,
         allowAnonymous: options?.allowAnonymous === true
       });
-      const client = buildSdkClient(auth);
+      const client = buildSdkClient(auth, sdkTransportFor(ctx));
       cache.set(key, client);
       return client;
     }
   };
+  return ctx;
+}
+function sdkTransportFor(ctx) {
+  return {
+    signal: ctx.signal,
+    fetch: recordingFetch(ctx.transport),
+    timeoutMs: ctx.budget.attemptMs,
+    maxRetries: ctx.globals.maxRetries
+  };
 }
 function makeFallbackContext(io, rawArgv) {
   const flags = {
@@ -510,7 +814,9 @@ function readGlobalFlags(flags) {
     yes: flags.yes === true,
     apiKey: readStringFlag(flags.apiKey),
     brand: readStringFlag(flags.brand),
-    apiUrl: readStringFlag(flags.apiUrl)
+    apiUrl: readStringFlag(flags.apiUrl),
+    timeoutMs: parseTimeoutFlag(flags.timeout),
+    maxRetries: parseMaxRetriesFlag(flags.maxRetries)
   };
 }
 function readStringFlag(value) {
@@ -542,6 +848,14 @@ var GLOBAL_FLAGS = [
   {
     flag: "--api-url <url>",
     summary: "API base URL (else BREW_API_URL, else https://brew.new/api)"
+  },
+  {
+    flag: "--timeout <duration>",
+    summary: "Give up after this long, retries and the response body included (90s, 1500ms, 5m)"
+  },
+  {
+    flag: "--max-retries <n>",
+    summary: "Retries after a transient failure, 0-10 (default 2; raw requests make one attempt)"
   }
 ];
 function asSdkInput(value) {
@@ -653,10 +967,69 @@ var IDEMPOTENCY_FLAG = {
   flag: "--idempotency-key <key>",
   summary: "Idempotency-Key for safe retries (auto-generated otherwise)"
 };
+var NON_REPLAYING_IDEMPOTENCY_FLAG = {
+  flag: "--idempotency-key <key>",
+  summary: "Accepted for compatibility only: this route never replays, so a retry runs again"
+};
 var INPUT_FLAG = {
   flag: "--input <json>",
   summary: "Full JSON request body, or - to read stdin (flags override it)"
 };
+var LONG_RUNNING_ROUTES = [
+  {
+    method: "POST",
+    path: "/v1/emails",
+    timeoutMs: GENERATE_EMAIL_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "PATCH",
+    path: "/v1/emails/{emailId}",
+    timeoutMs: EDIT_EMAIL_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/emails/audit",
+    timeoutMs: AUDIT_EMAIL_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/emails/{emailId}/client-previews",
+    timeoutMs: PREVIEW_EMAIL_CLIENTS_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/emails/import",
+    timeoutMs: IMPORT_EMAIL_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/emails/figma",
+    timeoutMs: IMPORT_FIGMA_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/content/gif",
+    timeoutMs: GIF_DEFAULT_TIMEOUT_MS
+  },
+  {
+    method: "POST",
+    path: "/v1/content/generate-image",
+    timeoutMs: GENERATE_IMAGE_DEFAULT_TIMEOUT_MS
+  }
+];
+function longRunningTimeoutMs(input) {
+  const bare = input.path.split("?")[0] ?? input.path;
+  return LONG_RUNNING_ROUTES.find(
+    (route) => route.method === input.method && matchesTemplate(route.path, bare)
+  )?.timeoutMs;
+}
+function matchesTemplate(template, path) {
+  const want = template.split("/");
+  const have = path.split("/");
+  return want.length === have.length && want.every(
+    (segment, index) => segment.startsWith("{") && segment.endsWith("}") ? (have[index] ?? "") !== "" : segment === have[index]
+  );
+}
 
 // src/lib/paginate.ts
 async function collectAll(ctx, fetchPage) {
@@ -664,7 +1037,20 @@ async function collectAll(ctx, fetchPage) {
   let cursor;
   let pageCount = 0;
   for (; ; ) {
-    const page = await fetchPage(cursor);
+    let page;
+    try {
+      ctx.signal.throwIfAborted();
+      page = await fetchPage(cursor);
+    } catch (error) {
+      if (pageCount > 0) {
+        ctx.transport.setDrain({
+          rowsFetched: rows.length,
+          pagesFetched: pageCount,
+          ...cursor === void 0 ? {} : { resumeCursor: cursor }
+        });
+      }
+      throw error;
+    }
     rows.push(...page.data);
     pageCount += 1;
     const next = page.pagination?.cursor ?? null;
@@ -857,6 +1243,106 @@ var analyticsCampaignsCommand = defineCommand({
   }
 });
 
+// src/commands/analytics/event-counts.ts
+var ROW_ONLY_KEYS = {
+  cursor: "A grouped count is not paged; drop `cursor`.",
+  automationRunId: "`groupBy` and `bucket` count email events and do not combine with `automationRunId`."
+};
+var analyticsEventCountsCommand = defineCommand({
+  path: ["analytics", "event-counts"],
+  summary: "Count email events per field and/or period (clicks per link, events per day, unsubscribe reasons)",
+  sdkMethod: "analytics.eventCounts",
+  route: { method: "GET", path: "/v1/analytics/events" },
+  commandClass: "read",
+  flags: [
+    {
+      flag: "--group-by <fields>",
+      summary: "One or two comma-separated fields: eventType, emailId, automationId, sendId, source, link, recipientDomain, unsubscribeReason"
+    },
+    {
+      flag: "--bucket <period>",
+      summary: "Count per UTC day, week (Monday start) or month"
+    },
+    { flag: "--since <datetime>", summary: "Window start (ISO-8601)" },
+    { flag: "--until <datetime>", summary: "Window end (ISO-8601)" },
+    {
+      flag: "--event-type <type>",
+      summary: "Only one email event type (e.g. clicked)"
+    },
+    { flag: "--send-id <sendId>", summary: "Only one send" },
+    { flag: "--email-id <emailId>", summary: "Only one design" },
+    {
+      flag: "--recipient <rules>",
+      summary: "CSV of recipient rules (max 10): an address, @domain, or substring; prefix ! to exclude"
+    },
+    INPUT_FLAG
+  ],
+  examples: [
+    "brew-cli analytics event-counts --send-id snd_123 --event-type clicked --group-by link",
+    "brew-cli analytics event-counts --group-by eventType --bucket day",
+    "brew-cli analytics event-counts --group-by unsubscribeReason --json"
+  ],
+  run: async ({ ctx, flags }) => {
+    const base = await readJsonFlag(ctx, flags.input, "--input");
+    const input = mergeInput(base, {
+      groupBy: flagString(flags.groupBy),
+      bucket: flagString(flags.bucket),
+      from: flagString(flags.since),
+      to: flagString(flags.until),
+      eventType: flagString(flags.eventType),
+      sendId: flagString(flags.sendId),
+      emailId: flagString(flags.emailId),
+      recipient: flagString(flags.recipient)
+    });
+    if (input.groupBy === void 0 && input.bucket === void 0) {
+      throw new CliUsageError(
+        "Pass --group-by, --bucket, or both (`analytics events` lists the rows)."
+      );
+    }
+    for (const [key, reason] of Object.entries(ROW_ONLY_KEYS)) {
+      if (input[key] !== void 0) {
+        throw new CliUsageError(reason);
+      }
+    }
+    const { limit: _pageSize, ...counted } = input;
+    const body = await ctx.client().analytics.eventCounts(
+      asSdkInput({
+        ...counted,
+        ...counted.groupBy === void 0 ? {} : { groupBy: toFieldList(counted.groupBy) }
+      })
+    );
+    return { data: body, human: renderCounts(body) };
+  }
+});
+function toFieldList(value) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  return value.split(",").map((field) => field.trim()).filter((field) => field !== "");
+}
+function renderCounts(body) {
+  if (body.groups.length === 0) {
+    return `No events counted (total ${body.count}).`;
+  }
+  const rows = body.groups.map((group) => ({
+    group: Object.entries(group.key ?? {}).map(([field, value]) => `${field}=${String(value)}`).join(" "),
+    ...group.bucket === void 0 ? {} : { bucket: group.bucket },
+    count: group.count
+  }));
+  const table = renderTable(rows, [
+    ...rows.some((row) => row.group !== "") ? [{ key: "group", header: "GROUP" }] : [],
+    ...rows.some((row) => "bucket" in row) ? [{ key: "bucket", header: "PERIOD" }] : [],
+    { key: "count", header: "COUNT" }
+  ]);
+  const footer = [
+    `total ${body.count}`,
+    body.otherCount > 0 ? `${body.otherCount} in unlisted groups` : "",
+    body.truncated ? `truncated (counted from ${body.coveredFrom ?? "?"})` : ""
+  ].filter(Boolean).join(" \xB7 ");
+  return `${table}
+${footer}`;
+}
+
 // src/commands/analytics/events.ts
 var analyticsEventsCommand = defineCommand({
   path: ["analytics", "events"],
@@ -1206,6 +1692,66 @@ var analyticsTriggerInstancesListCommand = defineCommand({
 });
 
 // src/lib/raw-request.ts
+var DEFAULT_ATTEMPT_TIMEOUT_MS = 3e4;
+async function rawFetch(ctx, request) {
+  const attempt = new AbortController();
+  const timer = setTimeout(() => {
+    attempt.abort(new CliTimeoutError(request.timeoutMs));
+  }, request.timeoutMs);
+  const combined = anySignal([ctx.signal, attempt.signal]);
+  const { signal } = combined;
+  if (signal.aborted) {
+    clearTimeout(timer);
+    combined.release();
+    throw signal.reason;
+  }
+  ctx.transport.record({
+    method: request.method,
+    path: apiPathOf(new URL(request.url)),
+    idempotencyKey: request.headers.get("idempotency-key") ?? void 0
+  });
+  try {
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers: request.headers,
+      signal,
+      ...request.body === void 0 ? {} : { body: request.body }
+    });
+    return { response, text: await readBodyText(response, signal) };
+  } catch (error) {
+    if (signal.aborted) {
+      throw signal.reason;
+    }
+    throw new CliConnectionError(error);
+  } finally {
+    clearTimeout(timer);
+    combined.release();
+  }
+}
+async function readBodyText(response, signal) {
+  if (response.body === null) {
+    return "";
+  }
+  const reader = response.body.getReader();
+  const onAbort = () => {
+    reader.cancel(signal.reason).catch(() => void 0);
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  const decoder = new TextDecoder();
+  let text = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      signal.throwIfAborted();
+      if (done) {
+        return text + decoder.decode();
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
 async function rawRequest(ctx, request) {
   const auth = resolveAuth({
     globals: ctx.globals,
@@ -1229,13 +1775,13 @@ async function rawRequest(ctx, request) {
       url.searchParams.set(key, value);
     }
   }
-  const response = await fetch(url, {
+  const { response, text } = await rawFetch(ctx, {
     method: request.method,
+    url: url.toString(),
     headers,
     ...hasBody ? { body: JSON.stringify(request.body) } : {},
-    ...request.signal === void 0 ? {} : { signal: request.signal }
+    timeoutMs: ctx.budget.attemptMs ?? DEFAULT_ATTEMPT_TIMEOUT_MS
   });
-  const text = await response.text();
   const parsed = tryParseJson(text);
   if (!response.ok) {
     throw responseToApiError(response, parsed);
@@ -1337,7 +1883,7 @@ var apiCommand = defineCommand({
     },
     {
       flag: "--idempotency-key <key>",
-      summary: "Idempotency-Key header for safe POST retries"
+      summary: "Idempotency-Key header for safe POST retries (a POST gets one generated otherwise)"
     }
   ],
   examples: [
@@ -1369,7 +1915,7 @@ var apiCommand = defineCommand({
       auth,
       path,
       hasJsonBody: body !== void 0,
-      idempotencyKey: typeof flags.idempotencyKey === "string" ? flags.idempotencyKey : void 0
+      idempotencyKey: typeof flags.idempotencyKey === "string" && flags.idempotencyKey !== "" ? flags.idempotencyKey : method === "POST" ? crypto.randomUUID() : void 0
     });
     for (const header of readHeaderFlags(flags.header)) {
       const separator = header.indexOf(":");
@@ -1383,12 +1929,16 @@ var apiCommand = defineCommand({
         header.slice(separator + 1).trim()
       );
     }
-    const response = await fetch(`${auth.apiUrl}${path}`, {
+    const { response, text } = await rawFetch(ctx, {
       method,
+      url: `${auth.apiUrl}${path}`,
       headers,
-      ...body === void 0 ? {} : { body }
+      ...body === void 0 ? {} : { body },
+      // --timeout, else the SDK's own default for this route when it is a
+      // long-running one (`api POST /v1/emails` waits as long as `emails
+      // generate`), else the SDK's 30 s.
+      timeoutMs: ctx.budget.attemptMs ?? longRunningTimeoutMs({ method, path: barePath }) ?? DEFAULT_ATTEMPT_TIMEOUT_MS
     });
-    const text = await response.text();
     const parsed = tryParseJson(text);
     if (!response.ok) {
       throw responseToApiError(response, parsed);
@@ -1451,7 +2001,9 @@ var apiKeysCreateCommand = defineCommand({
       summary: "Bind the NEW key to this brand id (omit for an organization-wide key); not the acting --brand"
     },
     INPUT_FLAG,
-    IDEMPOTENCY_FLAG
+    // The route never replays (a replay would disclose the plaintext key
+    // again): a retry mints a second key, whatever the key says.
+    NON_REPLAYING_IDEMPOTENCY_FLAG
   ],
   examples: [
     "brew-cli api-keys create --name CI --permissions emails domains",
@@ -1495,9 +2047,31 @@ var apiKeysListCommand = defineCommand({
   sdkMethod: "apiKeys.list",
   route: { method: "GET", path: "/v1/api-keys" },
   commandClass: "read",
+  flags: [LIMIT_FLAG, CURSOR_FLAG, ALL_FLAG],
   examples: ["brew-cli api-keys list", "brew-cli api-keys list --json"],
-  run: async ({ ctx }) => {
-    const result = await ctx.client().apiKeys.list();
+  run: async ({ ctx, flags }) => {
+    const limit = flagInt(flags.limit, "--limit");
+    const cursor = flagString(flags.cursor);
+    if (limit === void 0 && cursor === void 0 && flags.all !== true) {
+      const result2 = await ctx.client().apiKeys.list();
+      return { data: result2, human: renderApiKeys(result2.data) };
+    }
+    const page = (after) => rawRequest(ctx, {
+      method: "GET",
+      path: "/v1/api-keys",
+      query: {
+        limit: limit === void 0 ? void 0 : String(limit),
+        cursor: after
+      }
+    });
+    if (flags.all === true) {
+      const rows = await collectAll(ctx, (next) => page(next ?? cursor));
+      return {
+        data: { data: rows, pagination: { cursor: null, hasMore: false } },
+        human: renderApiKeys(rows)
+      };
+    }
+    const result = await page(cursor);
     return { data: result, human: renderApiKeys(result.data) };
   }
 });
@@ -1694,6 +2268,10 @@ var audiencesListCommand = defineCommand({
       flag: "--include <tokens>",
       summary: "0.6 flag: includes ride the detail read now (`audiences get --include count,build`)"
     },
+    {
+      flag: "--search <text>",
+      summary: "Only audiences whose name contains this text"
+    },
     LIMIT_FLAG,
     CURSOR_FLAG,
     ALL_FLAG,
@@ -1710,6 +2288,7 @@ var audiencesListCommand = defineCommand({
       throw includeRidesDetailRead("audiences get");
     }
     const input = mergeInput(base, {
+      search: flagString(flags.search),
       limit: flagInt(flags.limit, "--limit"),
       cursor: flagString(flags.cursor)
     });
@@ -1748,23 +2327,41 @@ function renderAudiences(rows) {
 // src/commands/audiences/update.ts
 var audiencesUpdateCommand = defineCommand({
   path: ["audiences", "update"],
-  summary: "Update an audience segment (name and/or filters)",
+  summary: "Update an audience segment: its name, its filters, or its members by email",
   sdkMethod: "audiences.update",
   route: { method: "PATCH", path: "/v1/audiences/{audienceId}" },
   commandClass: "write",
   args: [
     { name: "audienceId", summary: "Audience id to update", isRequired: true }
   ],
-  flags: [{ flag: "--name <name>", summary: "New audience name" }, INPUT_FLAG],
+  flags: [
+    { flag: "--name <name>", summary: "New audience name" },
+    {
+      flag: "--add-email <addresses...>",
+      summary: "Add these contacts by email, repeatable (refused when the filters cannot express it exactly)"
+    },
+    {
+      flag: "--remove-email <addresses...>",
+      summary: "Remove these contacts by email, repeatable (same rule)"
+    },
+    INPUT_FLAG
+  ],
   examples: [
     'brew-cli audiences update aud_3k9sQ --name "VIP customers"',
+    "brew-cli audiences update aud_3k9sQ --add-email ada@example.com --remove-email bo@example.com",
     `brew-cli audiences update aud_3k9sQ --input '{"filters":{"filters":[{"field":"plan","operator":"equals","value":"vip"}],"logicalOperator":"and"}}'`
   ],
   run: async ({ ctx, args, flags }) => {
     const base = await readJsonFlag(ctx, flags.input, "--input");
-    const input = mergeInput(base, { name: flagString(flags.name) });
+    const input = mergeInput(base, {
+      name: flagString(flags.name),
+      addEmails: toStringArray(flags.addEmail),
+      removeEmails: toStringArray(flags.removeEmail)
+    });
     if (Object.keys(input).length === 0) {
-      throw new CliUsageError("Nothing to update \u2014 pass --name or --input.");
+      throw new CliUsageError(
+        "Nothing to update \u2014 pass --name, --add-email, --remove-email or --input."
+      );
     }
     const result = await ctx.client().audiences.update(
       asSdkInput({
@@ -2117,7 +2714,16 @@ var automationsListCommand = defineCommand({
   sdkMethod: "automations.list",
   route: { method: "GET", path: "/v1/automations" },
   commandClass: "read",
-  flags: [LIMIT_FLAG, CURSOR_FLAG, ALL_FLAG, INPUT_FLAG],
+  flags: [
+    {
+      flag: "--search <text>",
+      summary: "Only automations whose name matches these words"
+    },
+    LIMIT_FLAG,
+    CURSOR_FLAG,
+    ALL_FLAG,
+    INPUT_FLAG
+  ],
   examples: [
     "brew-cli automations list",
     "brew-cli automations list --all --json"
@@ -2125,6 +2731,7 @@ var automationsListCommand = defineCommand({
   run: async ({ ctx, flags }) => {
     const base = await readJsonFlag(ctx, flags.input, "--input");
     const input = mergeInput(base, {
+      search: flagString(flags.search),
       limit: flagInt(flags.limit, "--limit"),
       cursor: flagString(flags.cursor)
     });
@@ -2513,17 +3120,14 @@ var FORMAT_FLAG = {
 var FORMATS = /* @__PURE__ */ new Set(["json", "ts", "zod", "jsonschema", "skill"]);
 var ENFORCEMENT_MODES = /* @__PURE__ */ new Set(["off", "prune", "strict"]);
 var VALIDATE_ENFORCEMENT_MODES = /* @__PURE__ */ new Set(["prune", "strict"]);
-function formatQuery(value) {
+function formatOption(value) {
   const format = flagString(value);
-  if (format === void 0) {
-    return "";
-  }
-  if (!FORMATS.has(format)) {
+  if (format !== void 0 && !FORMATS.has(format)) {
     throw new CliUsageError(
       `Unknown --format '${format}' (expected json | ts | zod | jsonschema | skill).`
     );
   }
-  return `?format=${format}`;
+  return format;
 }
 function contentHuman(body) {
   return typeof body.content === "string" ? { human: body.content } : {};
@@ -2531,8 +3135,7 @@ function contentHuman(body) {
 var automationsTriggersContractGetCommand = defineCommand({
   path: ["automations", "triggers", "contract", "get"],
   summary: "Read a trigger payload contract: stored when declared, derived otherwise; --format renders ts/zod/jsonschema/skill",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "automations.triggers.getContract",
   route: {
     method: "GET",
     path: "/v1/automations/triggers/{triggerEventId}/contract"
@@ -2552,18 +3155,20 @@ var automationsTriggersContractGetCommand = defineCommand({
     "brew-cli automations triggers contract get tri_signup --format skill --json | jq -r .content"
   ],
   run: async ({ ctx, args, flags }) => {
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/automations/triggers/${encodeURIComponent(args.triggerEventId ?? "")}/contract${formatQuery(flags.format)}`
-    });
+    const format = formatOption(flags.format);
+    const body = await ctx.client().automations.triggers.getContract(
+      asSdkInput({
+        triggerEventId: args.triggerEventId ?? "",
+        ...format === void 0 ? {} : { format }
+      })
+    );
     return { data: body, ...contentHuman(body) };
   }
 });
 var automationsTriggersContractPutCommand = defineCommand({
   path: ["automations", "triggers", "contract", "put"],
   summary: "Declare (or replace) the stored payload contract for a trigger \u2014 tree-validated before any write; omitting --enforcement leaves the stored setting unchanged",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "automations.triggers.putContract",
   route: {
     method: "PUT",
     path: "/v1/automations/triggers/{triggerEventId}/contract"
@@ -2615,19 +3220,19 @@ var automationsTriggersContractPutCommand = defineCommand({
         "Empty contract body \u2014 pass --input (fields and/or name) or --enforcement <mode>."
       );
     }
-    const body = await rawRequest(ctx, {
-      method: "PUT",
-      path: `/v1/automations/triggers/${encodeURIComponent(args.triggerEventId ?? "")}/contract`,
-      body: requestBody
-    });
+    const body = await ctx.client().automations.triggers.putContract(
+      asSdkInput({
+        ...requestBody,
+        triggerEventId: args.triggerEventId ?? ""
+      })
+    );
     return { data: body };
   }
 });
 var automationsTriggersContractValidateCommand = defineCommand({
   path: ["automations", "triggers", "contract", "validate"],
   summary: "Dry-run a payload against a trigger's contract (the fire path's validator) \u2014 never fires; invalid payloads still exit 0",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "automations.triggers.validatePayload",
   route: {
     method: "POST",
     path: "/v1/automations/triggers/{triggerEventId}/contract/validate"
@@ -2662,14 +3267,13 @@ var automationsTriggersContractValidateCommand = defineCommand({
         `Unknown --enforcement '${enforcement}' (expected prune | strict).`
       );
     }
-    const body = await rawRequest(ctx, {
-      method: "POST",
-      path: `/v1/automations/triggers/${encodeURIComponent(args.triggerEventId ?? "")}/contract/validate`,
-      body: {
+    const body = await ctx.client().automations.triggers.validatePayload(
+      asSdkInput({
+        triggerEventId: args.triggerEventId ?? "",
         payload,
         ...enforcement !== void 0 ? { enforcement } : {}
-      }
-    });
+      })
+    );
     return { data: body };
   }
 });
@@ -3038,21 +3642,36 @@ var brandGetCommand = defineCommand({
 });
 
 // src/commands/brand/get-images.ts
+var RETIRED_FILTERS = {
+  type: "--type (type) was retired by the API: use --kind logo|brand|generated.",
+  aspectRatio: "--aspect-ratio (aspectRatio) was retired by the API: every image carries its width and height."
+};
 var brandGetImagesCommand = defineCommand({
   path: ["brand", "get-images"],
-  summary: "Browse or semantically search the brand's image library",
+  summary: "Browse or semantically search the brand's assets (logos, brand images, images made with Brew)",
   sdkMethod: "brand.getImages",
   route: { method: "GET", path: "/v1/brand/images" },
   commandClass: "read",
   flags: [
     {
       flag: "--query <text>",
-      summary: "Semantic search over image descriptions"
+      summary: "Semantic search over what the images show (1 credit per new search; logos are not searchable)"
+    },
+    {
+      flag: "--kind <kind>",
+      summary: "logo, brand (from the site or uploaded) or generated"
+    },
+    {
+      flag: "--sort <order>",
+      summary: "Browse order: newest (default) or oldest; ignored by --query"
+    },
+    {
+      flag: "--type <type>",
+      summary: "Retired by the API: use --kind"
     },
-    { flag: "--type <type>", summary: "Filter by image category" },
     {
       flag: "--aspect-ratio <ratio>",
-      summary: "Filter by aspect ratio (e.g. 16:9)"
+      summary: "Retired by the API: rows carry width and height instead of a shape filter"
     },
     LIMIT_FLAG,
     CURSOR_FLAG,
@@ -3061,48 +3680,61 @@ var brandGetImagesCommand = defineCommand({
   ],
   examples: [
     "brew-cli brand get-images",
-    'brew-cli brand get-images --query "team photo" --aspect-ratio 16:9'
+    "brew-cli brand get-images --kind generated --sort oldest --all",
+    'brew-cli brand get-images --query "team photo" --kind brand'
   ],
   run: async ({ ctx, flags }) => {
     const base = await readJsonFlag(ctx, flags.input, "--input");
     const input = mergeInput(base, {
       q: flagString(flags.query),
-      type: flagString(flags.type),
-      aspectRatio: flagString(flags.aspectRatio),
+      kind: flagString(flags.kind),
+      sort: flagString(flags.sort),
       limit: flagInt(flags.limit, "--limit"),
-      cursor: flagString(flags.cursor)
+      cursor: flagString(flags.cursor),
+      type: flagString(flags.type),
+      aspectRatio: flagString(flags.aspectRatio)
     });
-    const brand = ctx.client().brand;
+    for (const [key, message] of Object.entries(RETIRED_FILTERS)) {
+      if (input[key] !== void 0) {
+        throw new CliUsageError(message);
+      }
+    }
+    const page = (cursor) => ctx.client().brand.getImages(
+      asSdkInput(
+        cursor === void 0 ? input : { ...input, cursor }
+      )
+    );
     if (flags.all === true) {
-      const rows = await collectAll(
-        ctx,
-        (cursor) => brand.getImages(
-          asSdkInput({
-            ...input,
-            ...cursor === void 0 ? {} : { cursor }
-          })
-        )
-      );
+      const rows = await collectAll(ctx, page);
       return {
         data: { data: rows, pagination: { cursor: null, hasMore: false } },
-        human: renderImages(rows)
+        human: renderAssets(rows)
       };
     }
-    const result = await brand.getImages(
-      asSdkInput(input)
-    );
-    return { data: result, human: renderImages(result.data) };
+    const result = await page(void 0);
+    return { data: result, human: renderAssets(result.data) };
   }
 });
-function renderImages(rows) {
+function renderAssets(rows) {
   if (rows.length === 0) {
-    return "No brand images found.";
+    return "No brand assets found.";
   }
-  return renderTable(rows, [
-    { key: "url", header: "URL" },
-    { key: "category", header: "CATEGORY" },
-    { key: "aspectRatio", header: "ASPECT" }
-  ]);
+  return renderTable(
+    rows.map((row) => ({
+      assetId: row.assetId,
+      kind: row.kind,
+      url: row.url,
+      size: row.width !== void 0 && row.height !== void 0 ? `${row.width}x${row.height}` : "",
+      added: row.addedAt ?? ""
+    })),
+    [
+      { key: "assetId", header: "ASSET ID" },
+      { key: "kind", header: "KIND" },
+      { key: "url", header: "URL" },
+      { key: "size", header: "SIZE" },
+      { key: "added", header: "ADDED" }
+    ]
+  );
 }
 
 // src/commands/brand/update.ts
@@ -3204,10 +3836,43 @@ var brandsListCommand = defineCommand({
   sdkMethod: "brands.list",
   route: { method: "GET", path: "/v1/brands" },
   commandClass: "read",
-  examples: ["brew-cli brands list --json"],
-  run: async ({ ctx }) => ({
-    data: await ctx.client().brands.list()
-  })
+  flags: [
+    {
+      flag: "--status <status>",
+      summary: "Only brands in one lifecycle state: extracting | completed | failed | deleting"
+    },
+    LIMIT_FLAG,
+    CURSOR_FLAG,
+    ALL_FLAG
+  ],
+  examples: [
+    "brew-cli brands list --json",
+    "brew-cli brands list --status completed",
+    "brew-cli brands list --all --json"
+  ],
+  run: async ({ ctx, flags }) => {
+    const input = {
+      status: flagString(flags.status),
+      limit: flagInt(flags.limit, "--limit"),
+      cursor: flagString(flags.cursor)
+    };
+    const brands = ctx.client().brands;
+    if (flags.all === true) {
+      const rows = await collectAll(
+        ctx,
+        (cursor) => brands.list(
+          asSdkInput({
+            ...input,
+            ...cursor === void 0 ? {} : { cursor }
+          })
+        )
+      );
+      return {
+        data: { data: rows, pagination: { cursor: null, hasMore: false } }
+      };
+    }
+    return { data: await brands.list(asSdkInput(input)) };
+  }
 });
 
 // src/commands/chats/get.ts
@@ -3350,6 +4015,90 @@ var contactsCountCommand = defineCommand({
   }
 });
 
+// src/commands/contacts/count-by.ts
+var contactsCountByCommand = defineCommand({
+  path: ["contacts", "count-by"],
+  summary: "Count contacts per field value, email domain, or signup period (largest group first)",
+  sdkMethod: "contacts.countBy",
+  route: { method: "POST", path: "/v1/contacts/search" },
+  commandClass: "read",
+  flags: [
+    {
+      flag: "--group-by <fields>",
+      summary: "One or two comma-separated fields: a contact field, a custom field, or emailDomain"
+    },
+    {
+      flag: "--bucket <period>",
+      summary: "Count per UTC day, week or month of createdAt"
+    },
+    { flag: "--search <text>", summary: "Free-text search" },
+    {
+      flag: "--filter <filters...>",
+      summary: "Structured filter field:operator[:value], repeatable"
+    },
+    { flag: "--audience <audienceId>", summary: "Scope to one audience" },
+    { flag: "--logic <logic>", summary: "Filter combinator: and | or" },
+    INPUT_FLAG
+  ],
+  examples: [
+    "brew-cli contacts count-by --group-by emailDomain",
+    "brew-cli contacts count-by --bucket month --filter subscribed:equals:true",
+    "brew-cli contacts count-by --group-by country,plan --json"
+  ],
+  run: async ({ ctx, flags }) => {
+    const base = await readJsonFlag(ctx, flags.input, "--input");
+    const input = mergeInput(base, {
+      groupBy: flagString(flags.groupBy),
+      bucket: flagString(flags.bucket),
+      search: flagString(flags.search),
+      filters: parseFilterFlags(flags.filter),
+      audienceId: flagString(flags.audience),
+      logic: flagString(flags.logic)
+    });
+    if (input.groupBy === void 0 && input.bucket === void 0) {
+      throw new CliUsageError(
+        "Pass --group-by, --bucket, or both (`contacts count` gives the total alone)."
+      );
+    }
+    const body = await ctx.client().contacts.countBy(
+      asSdkInput({
+        ...input,
+        ...input.groupBy === void 0 ? {} : { groupBy: toFieldList2(input.groupBy) }
+      })
+    );
+    return { data: body, human: renderCounts2(body) };
+  }
+});
+function toFieldList2(value) {
+  if (typeof value !== "string") {
+    return value;
+  }
+  return value.split(",").map((field) => field.trim()).filter((field) => field !== "");
+}
+function renderCounts2(body) {
+  const groups = body.groups ?? [];
+  if (groups.length === 0) {
+    return `No contacts counted (total ${body.count}).`;
+  }
+  const rows = groups.map((group) => ({
+    group: Object.entries(group.key).map(([field, value]) => `${field}=${String(value)}`).join(" "),
+    ...group.bucket === void 0 || group.bucket === null ? {} : { bucket: group.bucket },
+    count: group.count
+  }));
+  const table = renderTable(rows, [
+    ...rows.some((row) => row.group !== "") ? [{ key: "group", header: "GROUP" }] : [],
+    ...rows.some((row) => "bucket" in row) ? [{ key: "bucket", header: "PERIOD" }] : [],
+    { key: "count", header: "COUNT" }
+  ]);
+  const otherCount = body.otherCount ?? 0;
+  const footer = [
+    `total ${body.count}`,
+    otherCount > 0 ? `${otherCount} in unlisted groups` : ""
+  ].filter(Boolean).join(" \xB7 ");
+  return `${table}
+${footer}`;
+}
+
 // src/commands/contacts/delete.ts
 var contactsDeleteCommand = defineCommand({
   path: ["contacts", "delete"],
@@ -3439,35 +4188,65 @@ var contactsGetCommand = defineCommand({
 // src/commands/contacts/import-csv.ts
 var contactsImportCsvCommand = defineCommand({
   path: ["contacts", "import-csv"],
-  summary: "Bulk-import contacts from a CSV file or stdin",
+  summary: "Bulk-import contacts from a CSV file or stdin (free; --validate costs 2 credits per address)",
   sdkMethod: "contacts.importCsv",
   route: { method: "POST", path: "/v1/contacts/import-csv" },
   commandClass: "write",
   flags: [
-    { flag: "--file <path>", summary: "CSV file to import, or - for stdin" },
+    {
+      flag: "--file <path>",
+      summary: "CSV file to import, or - for stdin (or csv in --input)"
+    },
     {
       flag: "--mapping <pairs...>",
       summary: "Column mapping csvColumn=fieldName, repeatable"
     },
+    {
+      flag: "--date-order <order>",
+      summary: "month_first or day_first: how to read dates like 03/04/2026 (a day over 12 in the column wins; default month-first, with a DATE_ORDER_ASSUMED warning)"
+    },
+    {
+      flag: "--validate",
+      summary: "Deliverability-check every imported address (2 credits per address)"
+    },
+    {
+      flag: "--consent-source <source>",
+      summary: "Stamp a marketing consent record on every row: api, form or import (sets the source of a record given in --input)"
+    },
+    INPUT_FLAG,
     IDEMPOTENCY_FLAG
   ],
   examples: [
     "brew-cli contacts import-csv --file contacts.csv",
-    "cat contacts.csv | brew-cli contacts import-csv --file - --mapping Email=email"
+    "cat contacts.csv | brew-cli contacts import-csv --file - --mapping Email=email",
+    "brew-cli contacts import-csv --file eu-signups.csv --date-order day_first --consent-source import"
   ],
   run: async ({ ctx, flags }) => {
-    const csv = await readTextFlag(ctx, flags.file, "--file");
-    if (csv === void 0 || csv.trim() === "") {
+    if (flags.input === "-" && flags.file === "-") {
+      throw new CliUsageError("Only one of --input and --file can read stdin.");
+    }
+    const base = await readJsonFlag(ctx, flags.input, "--input");
+    const consentSource = flagString(flags.consentSource);
+    const input = mergeInput(base, {
+      csv: await readTextFlag(ctx, flags.file, "--file"),
+      mapping: parseKeyValues(flags.mapping, "--mapping"),
+      dateOrder: flagString(flags.dateOrder),
+      validate: flags.validate === true ? true : void 0
+    });
+    if (typeof input.csv !== "string" || input.csv.trim() === "") {
       throw new CliUsageError(
-        "--file is required (a CSV path, or - for stdin)."
+        "Pass the CSV with --file (a path, or - for stdin) or as csv in --input."
       );
     }
-    const mapping = parseKeyValues(flags.mapping, "--mapping");
+    if (consentSource !== void 0) {
+      const record = input.consent;
+      input.consent = {
+        ...typeof record === "object" && record !== null ? record : {},
+        source: consentSource
+      };
+    }
     const result = await ctx.client().contacts.importCsv(
-      asSdkInput({
-        csv,
-        ...mapping === void 0 ? {} : { mapping }
-      }),
+      asSdkInput(input),
       requestOptions(flags)
     );
     return { data: result };
@@ -3826,14 +4605,13 @@ var contentAddImageCommand = defineCommand({
     return { data: result };
   }
 });
-
-// src/commands/content/generate-image.ts
 var contentGenerateImageCommand = defineCommand({
   path: ["content", "generate-image"],
   summary: "Generate or edit an image from a prompt",
   sdkMethod: "content.generateImage",
   route: { method: "POST", path: "/v1/content/generate-image" },
   commandClass: "write",
+  defaultTimeoutMs: GENERATE_IMAGE_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   flags: [
     { flag: "--prompt <text>", summary: "What to generate" },
@@ -3874,14 +4652,13 @@ var contentGenerateImageCommand = defineCommand({
     return { data: result };
   }
 });
-
-// src/commands/content/gif.ts
 var contentGifCommand = defineCommand({
   path: ["content", "gif"],
   summary: "Create an animated GIF from a prompt, image, or video",
   sdkMethod: "content.gif",
   route: { method: "POST", path: "/v1/content/gif" },
   commandClass: "write",
+  defaultTimeoutMs: GIF_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   flags: [
     { flag: "--from <source>", summary: "prompt | image | video" },
@@ -4063,32 +4840,35 @@ var contentTransformCommand = defineCommand({
 var contractsInferCommand = defineCommand({
   path: ["contracts", "infer"],
   summary: "Draft a payload contract from a real example payload \u2014 nothing is saved; PUT the draft on a trigger",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "payloadContracts.infer",
   route: { method: "POST", path: "/v1/payload-contracts/infer" },
   commandClass: "read",
   flags: [INPUT_FLAG],
   examples: [
     `brew-cli contracts infer --input '{"email":"jane@example.com","order":{"total":9.5}}'`
   ],
-  // Accepts either the bare example object or `{ example: {...} }`.
-  // Un-inferable spots (nulls, empty arrays) come back under `issues`.
+  // Accepts either the bare example object or `{ example: {...} }`; only the
+  // envelope carries `subjectKind` (a bare example may have its own field of
+  // that name). Un-inferable spots (nulls, empty arrays) come back under
+  // `issues`.
   run: async ({ ctx, flags }) => {
     const input = mergeInput(
       await readJsonFlag(ctx, flags.input, "--input"),
       {}
     );
-    const example = input.example ?? input;
+    const isEnvelope = input.example !== void 0;
+    const example = isEnvelope ? input.example : input;
     if (typeof example !== "object" || example === null || Array.isArray(example) || Object.keys(example).length === 0) {
       throw new CliUsageError(
         "--input with a non-empty example object is required (the JSON your system sends)."
       );
     }
-    const body = await rawRequest(ctx, {
-      method: "POST",
-      path: "/v1/payload-contracts/infer",
-      body: { example }
-    });
+    const body = await ctx.client().payloadContracts.infer(
+      asSdkInput({
+        example,
+        ...isEnvelope && input.subjectKind !== void 0 ? { subjectKind: input.subjectKind } : {}
+      })
+    );
     return { data: body };
   }
 });
@@ -4125,24 +4905,8 @@ var dataRunCommand = defineCommand({
   }
 });
 
-// src/skip-list.ts
-var SDK_SKIP_LIST = [
-  {
-    sdkPath: "automations.triggers.getContract",
-    reason: "covered by `automations triggers contract get` (raw route, bound pre-SDK-v9; SDK-method migration tracked separately)"
-  },
-  {
-    sdkPath: "automations.triggers.putContract",
-    reason: "covered by `automations triggers contract put` (raw route, bound pre-SDK-v9)"
-  },
-  {
-    sdkPath: "automations.triggers.validatePayload",
-    reason: "covered by `automations triggers contract validate` (raw route, bound pre-SDK-v9)"
-  },
-  {
-    sdkPath: "payloadContracts.infer",
-    reason: "covered by `contracts infer` (raw route, bound pre-SDK-v9)"
-  },
+// src/skip-list.ts
+var SDK_SKIP_LIST = [
   {
     sdkPath: "contacts.searchAll",
     reason: "auto-pager covered by `contacts search --all`"
@@ -4187,7 +4951,9 @@ function buildManifest() {
       "1": "API or runtime error",
       "2": "usage error",
       "3": "authentication error",
-      "4": "confirmation required (re-run with --yes)"
+      "4": "confirmation required (re-run with --yes)",
+      "130": "interrupted by SIGINT (Ctrl-C); the CLI then re-raises the signal",
+      "143": "terminated by SIGTERM; the CLI then re-raises the signal"
     },
     confirmationProtocol: {
       exitCode: 4,
@@ -4295,6 +5061,7 @@ var doctorCommand = defineCommand({
       isReachable = health.status === "ok";
       apiVersion = health.version ?? null;
     } catch (error) {
+      rethrowIfStopped(ctx);
       reachabilityError = error instanceof Error ? error.message : String(error);
     }
     let isAuthValid = null;
@@ -4305,6 +5072,7 @@ var doctorCommand = defineCommand({
         isAuthValid = true;
         plan = usage.plan?.key ?? null;
       } catch (error) {
+        rethrowIfStopped(ctx);
         if ((error instanceof BrewApiError || error instanceof CliApiError) && (error.status === 401 || error.status === 403)) {
           isAuthValid = false;
         }
@@ -4330,6 +5098,7 @@ var doctorCommand = defineCommand({
         extraLocally = [...localOps].filter((op) => !liveOps.has(op));
         isSurfaceChecked = true;
       } catch {
+        rethrowIfStopped(ctx);
       }
     }
     const isHealthy = isReachable && isAuthValid !== false && isSurfaceChecked && missingLocally.length === 0;
@@ -4367,6 +5136,9 @@ ${missingLocally.map((op) => `      ${op}`).join("\n")}` : "--  surface not chec
     };
   }
 });
+function rethrowIfStopped(ctx) {
+  ctx.signal.throwIfAborted();
+}
 
 // src/commands/domains/add.ts
 var domainsAddCommand = defineCommand({
@@ -4513,6 +5285,193 @@ function renderDomains(rows) {
   ]);
 }
 
+// src/commands/domains/unsubscribes/add.ts
+var domainsUnsubscribesAddCommand = defineCommand({
+  path: ["domains", "unsubscribes", "add"],
+  summary: "Add addresses to a marketing domain's unsubscribe list (that domain only)",
+  sdkMethod: "domains.unsubscribes.add",
+  route: { method: "POST", path: "/v1/domains/{domainId}/unsubscribes" },
+  commandClass: "write",
+  args: [
+    { name: "domainId", summary: "Marketing domain id", isRequired: true }
+  ],
+  flags: [
+    {
+      flag: "--email <addresses...>",
+      summary: "Address to suppress, repeatable (up to 1,000)"
+    },
+    IDEMPOTENCY_FLAG
+  ],
+  examples: [
+    "brew-cli domains unsubscribes add dom_123 --email ada@example.com --email bo@example.com"
+  ],
+  run: async ({ ctx, args, flags }) => {
+    const emails = toStringArray(flags.email);
+    if (emails === void 0) {
+      throw new CliUsageError("Pass at least one --email.");
+    }
+    const body = await ctx.client().domains.unsubscribes.add(
+      { domainId: args.domainId ?? "", emails: [...emails] },
+      requestOptions(flags)
+    );
+    return { data: body };
+  }
+});
+
+// src/commands/domains/unsubscribes/export.ts
+var domainsUnsubscribesExportCommand = defineCommand({
+  path: ["domains", "unsubscribes", "export"],
+  summary: "A domain's unsubscribe list as CSV (truncated when capped)",
+  sdkMethod: "domains.unsubscribes.export",
+  route: {
+    method: "GET",
+    path: "/v1/domains/{domainId}/unsubscribes/export"
+  },
+  commandClass: "read",
+  args: [
+    { name: "domainId", summary: "Marketing domain id", isRequired: true }
+  ],
+  flags: [
+    {
+      flag: "--scope <scope>",
+      summary: "any (default), domain or all"
+    }
+  ],
+  examples: [
+    "brew-cli domains unsubscribes export dom_123 > optouts.csv",
+    "brew-cli domains unsubscribes export dom_123 --scope all --json"
+  ],
+  run: async ({ ctx, args, flags }) => {
+    const scope = flagString(flags.scope);
+    const body = await ctx.client().domains.unsubscribes.export(
+      asSdkInput({
+        domainId: args.domainId ?? "",
+        ...scope === void 0 ? {} : { scope }
+      })
+    );
+    return { data: body, human: body.csv };
+  }
+});
+
+// src/commands/domains/unsubscribes/import.ts
+var domainsUnsubscribesImportCommand = defineCommand({
+  path: ["domains", "unsubscribes", "import"],
+  summary: "Add every address in a CSV to a domain's unsubscribe list",
+  sdkMethod: "domains.unsubscribes.import",
+  route: {
+    method: "POST",
+    path: "/v1/domains/{domainId}/unsubscribes/import"
+  },
+  commandClass: "write",
+  args: [
+    { name: "domainId", summary: "Marketing domain id", isRequired: true }
+  ],
+  flags: [
+    { flag: "--file <path>", summary: "CSV file, or - for stdin" },
+    {
+      flag: "--column <header>",
+      summary: "The column holding the addresses (by header)"
+    },
+    IDEMPOTENCY_FLAG
+  ],
+  examples: [
+    "brew-cli domains unsubscribes import dom_123 --file optouts.csv --column Email"
+  ],
+  run: async ({ ctx, args, flags }) => {
+    const csv = await readTextFlag(ctx, flags.file, "--file");
+    if (csv === void 0 || csv.trim() === "") {
+      throw new CliUsageError(
+        "--file is required (a CSV path, or - for stdin)."
+      );
+    }
+    const column = flagString(flags.column);
+    const body = await ctx.client().domains.unsubscribes.import(
+      {
+        domainId: args.domainId ?? "",
+        csv,
+        ...column === void 0 ? {} : { column }
+      },
+      requestOptions(flags)
+    );
+    return { data: body };
+  }
+});
+
+// src/commands/domains/unsubscribes/list.ts
+var domainsUnsubscribesListCommand = defineCommand({
+  path: ["domains", "unsubscribes", "list"],
+  summary: "One page of a marketing domain's unsubscribe list, newest first",
+  sdkMethod: "domains.unsubscribes.list",
+  route: { method: "GET", path: "/v1/domains/{domainId}/unsubscribes" },
+  commandClass: "read",
+  args: [
+    { name: "domainId", summary: "Marketing domain id", isRequired: true }
+  ],
+  flags: [
+    { flag: "--q <text>", summary: "Search by address" },
+    {
+      flag: "--scope <scope>",
+      summary: "any (default), domain (this list only) or all (brand-wide opt-outs)"
+    },
+    LIMIT_FLAG,
+    CURSOR_FLAG
+  ],
+  examples: [
+    "brew-cli domains unsubscribes list dom_123",
+    "brew-cli domains unsubscribes list dom_123 --scope domain --q ada"
+  ],
+  run: async ({ ctx, args, flags }) => {
+    const limit = flagInt(flags.limit, "--limit");
+    const q = flagString(flags.q);
+    const scope = flagString(flags.scope);
+    const cursor = flagString(flags.cursor);
+    const body = await ctx.client().domains.unsubscribes.list(
+      asSdkInput({
+        domainId: args.domainId ?? "",
+        ...q === void 0 ? {} : { q },
+        ...scope === void 0 ? {} : { scope },
+        ...limit === void 0 ? {} : { limit },
+        ...cursor === void 0 ? {} : { cursor }
+      })
+    );
+    return { data: body, human: renderRows(body.data) };
+  }
+});
+function renderRows(rows) {
+  if (rows.length === 0) {
+    return "No unsubscribes on this list.";
+  }
+  return renderTable(rows, [
+    { key: "email", header: "EMAIL" },
+    { key: "scope", header: "SCOPE" },
+    { key: "unsubscribedAt", header: "UNSUBSCRIBED" }
+  ]);
+}
+
+// src/commands/domains/unsubscribes/remove.ts
+var domainsUnsubscribesRemoveCommand = defineCommand({
+  path: ["domains", "unsubscribes", "remove"],
+  summary: "Take one address off a domain's unsubscribe list (never re-subscribes a brand-wide opt-out)",
+  sdkMethod: "domains.unsubscribes.remove",
+  route: {
+    method: "DELETE",
+    path: "/v1/domains/{domainId}/unsubscribes/{email}"
+  },
+  commandClass: "write",
+  args: [
+    { name: "domainId", summary: "Marketing domain id", isRequired: true },
+    { name: "email", summary: "Address to remove", isRequired: true }
+  ],
+  flags: [],
+  examples: ["brew-cli domains unsubscribes remove dom_123 ada@example.com"],
+  run: async ({ ctx, args }) => ({
+    data: await ctx.client().domains.unsubscribes.remove({
+      domainId: args.domainId ?? "",
+      email: args.email ?? ""
+    })
+  })
+});
+
 // src/commands/domains/update.ts
 var domainsUpdateCommand = defineCommand({
   path: ["domains", "update"],
@@ -4586,6 +5545,7 @@ var emailsAuditCommand = defineCommand({
   sdkMethod: "emails.auditEmail",
   route: { method: "POST", path: "/v1/emails/audit" },
   commandClass: "write",
+  defaultTimeoutMs: AUDIT_EMAIL_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   flags: [
     {
@@ -4629,19 +5589,11 @@ var emailsAuditCommand = defineCommand({
         "--file is required (a path, or - for stdin), or emailHtml via --input."
       );
     }
-    const signal = AbortSignal.timeout(AUDIT_EMAIL_DEFAULT_TIMEOUT_MS);
-    try {
-      const result = await ctx.client().emails.auditEmail(asSdkInput(input), {
-        signal,
-        ...requestOptions(flags) ?? {}
-      });
-      return { data: result };
-    } catch (error) {
-      if (signal.aborted) {
-        throw signal.reason;
-      }
-      throw error;
-    }
+    const result = await ctx.client().emails.auditEmail(
+      asSdkInput(input),
+      requestOptions(flags)
+    );
+    return { data: result };
   }
 });
 
@@ -4658,19 +5610,41 @@ var emailsCloneCommand = defineCommand({
       flag: "--email-version-id <id>",
       summary: "Exact source version to clone (default: latest)"
     },
+    {
+      flag: "--title <title>",
+      summary: "Name for the clone (default: Copy of <source title>)"
+    },
+    {
+      flag: "--group-id <groupId>",
+      summary: "File the clone under an existing group (grp_\u2026), or ungrouped"
+    },
+    {
+      flag: "--group-name <name>",
+      summary: "File the clone under a group found (or created) by this name; not with --group-id"
+    },
     IDEMPOTENCY_FLAG
   ],
   examples: [
     "brew-cli emails clone eml_2SmZOWV3ZQ7W5x6g3m4p",
-    "brew-cli emails clone eml_2SmZOWV3ZQ7W5x6g3m4p --email-version-id emv_9f2kX"
+    "brew-cli emails clone eml_2SmZOWV3ZQ7W5x6g3m4p --email-version-id emv_9f2kX",
+    'brew-cli emails clone eml_2SmZOWV3ZQ7W5x6g3m4p --title "Fall sale (B)" --group-name "Fall campaign"'
   ],
   run: async ({ ctx, args, flags }) => {
     const emailVersionId = flagString(flags.emailVersionId);
+    const title = flagString(flags.title);
+    const groupId = flagString(flags.groupId);
+    const groupName = flagString(flags.groupName);
+    if (groupId !== void 0 && groupName !== void 0) {
+      throw new CliUsageError("Pass --group-id or --group-name, not both.");
+    }
     return {
       data: await ctx.client().emails.clone(
         asSdkInput({
           emailId: args.emailId ?? "",
-          ...emailVersionId === void 0 ? {} : { emailVersionId }
+          ...emailVersionId === void 0 ? {} : { emailVersionId },
+          ...title === void 0 ? {} : { title },
+          ...groupId === void 0 ? {} : { groupId },
+          ...groupName === void 0 ? {} : { groupName }
         }),
         requestOptions(flags)
       )
@@ -4757,8 +5731,6 @@ var emailsDeleteCommand = defineCommand({
     data: await ctx.client().emails.delete({ emailId: args.emailId ?? "" })
   })
 });
-
-// src/commands/emails/edit.ts
 var ENVELOPE_FIELDS = ["title", "subjectLine", "groupId"];
 function isText(value) {
   return typeof value === "string" && value !== "";
@@ -4769,6 +5741,7 @@ var emailsEditCommand = defineCommand({
   sdkMethod: "emails.edit",
   route: { method: "PATCH", path: "/v1/emails/{emailId}" },
   commandClass: "write",
+  defaultTimeoutMs: EDIT_EMAIL_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   args: [{ name: "emailId", summary: "Design id to edit", isRequired: true }],
   flags: [
@@ -4835,8 +5808,7 @@ var emailsEditCommand = defineCommand({
       isPromptEdit ? "Editing email\u2026 (typically 30-90s)" : envelope.length === 1 && envelope[0] === "subjectLine" ? "Setting the subject line\u2026" : "Updating the design (no AI run)\u2026"
     );
     const result = await ctx.client().emails.edit(
-      asSdkInput({ ...input, emailId: args.emailId ?? "" }),
-      { timeoutMs: 24e4 }
+      asSdkInput({ ...input, emailId: args.emailId ?? "" })
     );
     return { data: result };
   }
@@ -4853,12 +5825,16 @@ var emailsExportCommand = defineCommand({
   flags: [
     {
       flag: "--provider <provider>",
-      summary: "Connected ESP: braze, hubspot, klaviyo, mailchimp, iterable, postmark, onesignal, mailgun, sendgrid"
+      summary: "Connected ESP: braze, brevo, hubspot, klaviyo, mailchimp, mailjet, iterable, postmark, onesignal, mailgun, sendgrid"
     },
     {
       flag: "--template-name <name>",
       summary: "Template name in the ESP (default: the email title)"
     },
+    {
+      flag: "--sender-email <email>",
+      summary: "Brevo or Mailjet: the active sender to use (omit when the account has exactly one)"
+    },
     {
       flag: "--dry-run",
       summary: "Validate design, ownership, and ESP connection without creating a template"
@@ -4873,16 +5849,18 @@ var emailsExportCommand = defineCommand({
     const provider = flagString(flags.provider);
     if (provider === void 0) {
       throw new CliUsageError(
-        "--provider is required: braze, hubspot, klaviyo, mailchimp, iterable, postmark, onesignal, mailgun, or sendgrid."
+        "--provider is required: braze, brevo, hubspot, klaviyo, mailchimp, mailjet, iterable, postmark, onesignal, mailgun, or sendgrid."
       );
     }
     const templateName = flagString(flags.templateName);
+    const senderEmail = flagString(flags.senderEmail);
     return {
       data: await ctx.client().emails.export(
         asSdkInput({
           emailId: args.emailId ?? "",
           provider,
           ...templateName === void 0 ? {} : { templateName },
+          ...senderEmail === void 0 ? {} : { senderEmail },
           // The spec field is snake_case, unlike the rest of the API surface.
           ...flags.dryRun === true ? { dryRun: true } : {}
         }),
@@ -4891,14 +5869,13 @@ var emailsExportCommand = defineCommand({
     };
   }
 });
-
-// src/commands/emails/generate.ts
 var emailsGenerateCommand = defineCommand({
   path: ["emails", "generate"],
   summary: "Generate a new on-brand email design from a prompt",
   sdkMethod: "emails.generate",
   route: { method: "POST", path: "/v1/emails" },
   commandClass: "write",
+  defaultTimeoutMs: GENERATE_EMAIL_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   flags: [
     { flag: "--prompt <text>", summary: "What the email should be" },
@@ -4942,10 +5919,10 @@ var emailsGenerateCommand = defineCommand({
       );
     }
     progress(ctx, "Generating email\u2026 (typically 30-90s)");
-    const result = await ctx.client().emails.generate(asSdkInput(input), {
-      timeoutMs: 24e4,
-      ...requestOptions(flags) ?? {}
-    });
+    const result = await ctx.client().emails.generate(
+      asSdkInput(input),
+      requestOptions(flags)
+    );
     return { data: result };
   }
 });
@@ -4967,20 +5944,39 @@ var emailsGetCommand = defineCommand({
   flags: [
     {
       flag: "--include <tokens>",
-      summary: "Comma-separated expansions: html, versions"
+      summary: "Comma-separated expansions: html, versions, text, links"
+    },
+    {
+      flag: "--email-version-id <emailVersionId>",
+      summary: "Read this saved version instead of the current head (ids from --include versions)"
+    },
+    {
+      flag: "--run-id <runId>",
+      summary: "Read the version a generate or edit run produced (the runId it returned)"
     }
   ],
   examples: [
     "brew-cli emails get eml_2SmZOWV3ZQ7W5x6g3m4p",
-    "brew-cli emails get eml_2SmZOWV3ZQ7W5x6g3m4p --include html,versions"
+    "brew-cli emails get eml_2SmZOWV3ZQ7W5x6g3m4p --include html,versions",
+    "brew-cli emails get eml_2SmZOWV3ZQ7W5x6g3m4p --include text,links",
+    "brew-cli emails get eml_2SmZOWV3ZQ7W5x6g3m4p --email-version-id emv_2SmZOWV3ZQ7W5x6g3m4p --include html"
   ],
   run: async ({ ctx, args, flags }) => {
+    const emailId = args.emailId ?? "";
     const include = flagString(flags.include);
+    const emailVersionId = flagString(flags.emailVersionId);
+    const runId = flagString(flags.runId);
+    if (emailVersionId !== void 0 && runId !== void 0) {
+      throw new CliUsageError(
+        "Pass --email-version-id or --run-id, not both: each selects the version to read."
+      );
+    }
     return {
-      data: await ctx.client().emails.get(
-        args.emailId ?? "",
-        include === void 0 ? void 0 : { include }
-      )
+      data: await ctx.client().emails.get(emailId, {
+        ...include === void 0 ? {} : { include },
+        ...emailVersionId === void 0 ? {} : { emailVersionId },
+        ...runId === void 0 ? {} : { runId }
+      })
     };
   }
 });
@@ -4989,8 +5985,7 @@ var emailsGetCommand = defineCommand({
 var emailsGetAuditCommand = defineCommand({
   path: ["emails", "get-audit"],
   summary: "Read a saved email audit: one page of its findings (free; never reruns the audit)",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "emails.getAudit",
   route: { method: "GET", path: "/v1/emails/audits/{auditId}" },
   commandClass: "read",
   args: [
@@ -5000,7 +5995,12 @@ var emailsGetAuditCommand = defineCommand({
       isRequired: true
     }
   ],
-  flags: [LIMIT_FLAG, CURSOR_FLAG],
+  // Its own page size: a saved audit pages 1-50 findings (default 10), not
+  // the shared list's 1-100.
+  flags: [
+    { flag: "--limit <n>", summary: "Findings per page, 1-50 (default 10)" },
+    CURSOR_FLAG
+  ],
   examples: [
     "brew-cli emails get-audit 6f1e2d3c-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
     "brew-cli emails get-audit 6f1e2d3c-4b5a-4c7d-8e9f-0a1b2c3d4e5f --limit 20"
@@ -5009,13 +6009,10 @@ var emailsGetAuditCommand = defineCommand({
   // says whether one exists.
   run: async ({ ctx, args, flags }) => {
     const limit = flagInt(flags.limit, "--limit");
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/emails/audits/${encodeURIComponent(args.auditId ?? "")}`,
-      query: {
-        cursor: flagString(flags.cursor),
-        limit: limit === void 0 ? void 0 : String(limit)
-      }
+    const cursor = flagString(flags.cursor);
+    const body = await ctx.client().emails.getAudit(args.auditId ?? "", {
+      ...cursor === void 0 ? {} : { cursor },
+      ...limit === void 0 ? {} : { limit }
     });
     return { data: body };
   }
@@ -5025,8 +6022,7 @@ var emailsGetAuditCommand = defineCommand({
 var emailsGetClientPreviewCommand = defineCommand({
   path: ["emails", "get-client-preview"],
   summary: "Poll a client-preview rendering job: per-client screenshot links once it settles (free; never re-renders)",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "emails.getClientPreview",
   route: { method: "GET", path: "/v1/emails/client-previews/{previewId}" },
   commandClass: "read",
   args: [
@@ -5045,10 +6041,7 @@ var emailsGetClientPreviewCommand = defineCommand({
   // `failed`; each client then carries its `imageUrl`, or a `reason` and
   // whether it is `retryable`.
   run: async ({ ctx, args }) => {
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/emails/client-previews/${encodeURIComponent(args.previewId ?? "")}`
-    });
+    const body = await ctx.client().emails.getClientPreview(args.previewId ?? "");
     return { data: body };
   }
 });
@@ -5262,14 +6255,13 @@ var emailsGroupsUpdateCommand = defineCommand({
     };
   }
 });
-
-// src/commands/emails/import.ts
 var emailsImportCommand = defineCommand({
   path: ["emails", "import"],
   summary: "Import existing HTML, MJML, or JSX as a new editable design",
   sdkMethod: "emails.import",
   route: { method: "POST", path: "/v1/emails/import" },
   commandClass: "write",
+  defaultTimeoutMs: IMPORT_EMAIL_DEFAULT_TIMEOUT_MS,
   flags: [
     {
       flag: "--file <path>",
@@ -5315,14 +6307,13 @@ var emailsImportCommand = defineCommand({
     return { data: result };
   }
 });
-
-// src/commands/emails/import-figma.ts
 var emailsImportFigmaCommand = defineCommand({
   path: ["emails", "import-figma"],
   summary: "Convert one Figma frame into an editable design (deterministic, free)",
   sdkMethod: "emails.importFigma",
   route: { method: "POST", path: "/v1/emails/figma" },
   commandClass: "write",
+  defaultTimeoutMs: IMPORT_FIGMA_DEFAULT_TIMEOUT_MS,
   flags: [
     {
       flag: "--url <figmaUrl>",
@@ -5340,6 +6331,14 @@ var emailsImportFigmaCommand = defineCommand({
       flag: "--subject-line <text>",
       summary: "The design's default inbox subject line"
     },
+    {
+      flag: "--group-id <groupId>",
+      summary: "File the design under an existing group (grp_\u2026), or ungrouped"
+    },
+    {
+      flag: "--group-name <name>",
+      summary: "File the design under a group found (or created) by this name; not with --group-id"
+    },
     IDEMPOTENCY_FLAG
   ],
   examples: [
@@ -5356,13 +6355,20 @@ var emailsImportFigmaCommand = defineCommand({
     const title = flagString(flags.title);
     const format = flagString(flags.format);
     const subjectLine = flagString(flags.subjectLine);
+    const groupId = flagString(flags.groupId);
+    const groupName = flagString(flags.groupName);
+    if (groupId !== void 0 && groupName !== void 0) {
+      throw new CliUsageError("Pass --group-id or --group-name, not both.");
+    }
     return {
       data: await ctx.client().emails.importFigma(
         asSdkInput({
           figmaUrl,
           ...title === void 0 ? {} : { title },
           ...format === void 0 ? {} : { format },
-          ...subjectLine === void 0 ? {} : { subjectLine }
+          ...subjectLine === void 0 ? {} : { subjectLine },
+          ...groupId === void 0 ? {} : { groupId },
+          ...groupName === void 0 ? {} : { groupName }
         }),
         requestOptions(flags)
       )
@@ -5408,6 +6414,10 @@ var emailsListCommand = defineCommand({
   route: { method: "GET", path: "/v1/emails" },
   commandClass: "read",
   flags: [
+    {
+      flag: "--search <text>",
+      summary: "Only designs whose title contains this text, or whose title, subject, preview or text matches its words"
+    },
     {
       flag: "--status <status>",
       summary: "Filter by status: generating | ready | failed"
@@ -5467,6 +6477,7 @@ var emailsListCommand = defineCommand({
     );
     const base = await readJsonFlag(ctx, flags.input, "--input");
     const input = mergeInput(base, {
+      search: flagString(flags.search),
       status: flagString(flags.status),
       groupId: flagString(flags.groupId),
       sortBy: flagString(flags.sortBy) ?? flagString(flags.sort) ?? legacy.sortBy,
@@ -5541,14 +6552,13 @@ function renderEmails(rows) {
     { key: "updatedAt", header: "UPDATED" }
   ]);
 }
-
-// src/commands/emails/preview-clients.ts
 var emailsPreviewClientsCommand = defineCommand({
   path: ["emails", "preview-clients"],
   summary: "Start a rendering job across real email clients (10 credits); poll it with `emails get-client-preview`",
   sdkMethod: "emails.previewClients",
   route: { method: "POST", path: "/v1/emails/{emailId}/client-previews" },
   commandClass: "write",
+  defaultTimeoutMs: PREVIEW_EMAIL_CLIENTS_DEFAULT_TIMEOUT_MS,
   isCredited: true,
   args: [
     { name: "emailId", summary: "Design id to preview", isRequired: true }
@@ -5828,8 +6838,48 @@ var fieldsListCommand = defineCommand({
   sdkMethod: "fields.list",
   route: { method: "GET", path: "/v1/fields" },
   commandClass: "read",
-  examples: ["brew-cli fields list"],
-  run: async ({ ctx }) => ({ data: await ctx.client().fields.list() })
+  flags: [
+    {
+      flag: "--include <tokens>",
+      summary: "Expansions: coverage (per-field fill stats: percent of contacts with a value, and top values)"
+    },
+    {
+      flag: "--audience-id <audienceId>",
+      summary: "Scope --include coverage to one saved audience (ignored without it)"
+    },
+    LIMIT_FLAG,
+    CURSOR_FLAG,
+    ALL_FLAG
+  ],
+  examples: [
+    "brew-cli fields list",
+    "brew-cli fields list --include coverage",
+    "brew-cli fields list --include coverage --audience-id aud_2SmZOWV3ZQ7W5x6g3m4p --all --json"
+  ],
+  run: async ({ ctx, flags }) => {
+    const input = {
+      include: flagString(flags.include),
+      audienceId: flagString(flags.audienceId),
+      limit: flagInt(flags.limit, "--limit"),
+      cursor: flagString(flags.cursor)
+    };
+    const fields = ctx.client().fields;
+    if (flags.all === true) {
+      const rows = await collectAll(
+        ctx,
+        (cursor) => fields.list(
+          asSdkInput({
+            ...input,
+            ...cursor === void 0 ? {} : { cursor }
+          })
+        )
+      );
+      return {
+        data: { data: rows, pagination: { cursor: null, hasMore: false } }
+      };
+    }
+    return { data: await fields.list(asSdkInput(input)) };
+  }
 });
 
 // src/commands/flows/get.ts
@@ -6024,9 +7074,31 @@ var integrationsListCommand = defineCommand({
   sdkMethod: "integrations.list",
   route: { method: "GET", path: "/v1/integrations" },
   commandClass: "read",
+  flags: [LIMIT_FLAG, CURSOR_FLAG, ALL_FLAG],
   examples: ["brew-cli integrations list", "brew-cli integrations list --json"],
-  run: async ({ ctx }) => {
-    const result = await ctx.client().integrations.list();
+  run: async ({ ctx, flags }) => {
+    const limit = flagInt(flags.limit, "--limit");
+    const cursor = flagString(flags.cursor);
+    if (limit === void 0 && cursor === void 0 && flags.all !== true) {
+      const result2 = await ctx.client().integrations.list();
+      return { data: result2, human: renderIntegrations(result2.data) };
+    }
+    const page = (after) => rawRequest(ctx, {
+      method: "GET",
+      path: "/v1/integrations",
+      query: {
+        limit: limit === void 0 ? void 0 : String(limit),
+        cursor: after
+      }
+    });
+    if (flags.all === true) {
+      const rows = await collectAll(ctx, (next) => page(next ?? cursor));
+      return {
+        data: { data: rows, pagination: { cursor: null, hasMore: false } },
+        human: renderIntegrations(rows)
+      };
+    }
+    const result = await page(cursor);
     return { data: result, human: renderIntegrations(result.data) };
   }
 });
@@ -6066,7 +7138,7 @@ var loginCommand = defineCommand({
       globals: { ...ctx.globals, apiKey: candidate },
       env: ctx.io.env
     });
-    await buildSdkClient(auth).usage.get();
+    await buildSdkClient(auth, sdkTransportFor(ctx)).usage.get();
     const path = updateConfig(ctx.io.env, { apiKey: candidate });
     progress(ctx, `Logged in. Key stored in ${path} (0600).`);
     return {
@@ -6193,8 +7265,7 @@ var sendsResumeCommand = defineCommand({
 var templatesGetCommand = defineCommand({
   path: ["templates", "get"],
   summary: "Fetch one public template: its links and the referenceEmailId to remix; --include html adds its HTML",
-  sdkMethod: null,
-  isRawTransport: true,
+  sdkMethod: "templates.get",
   route: { method: "GET", path: "/v1/templates/{templateId}" },
   commandClass: "read",
   args: [
@@ -6215,11 +7286,11 @@ var templatesGetCommand = defineCommand({
     "brew-cli templates get seed-vercel-newsletter --include html --json"
   ],
   run: async ({ ctx, args, flags }) => {
-    const body = await rawRequest(ctx, {
-      method: "GET",
-      path: `/v1/templates/${encodeURIComponent(args.templateId ?? "")}`,
-      query: { include: flagString(flags.include) }
-    });
+    const include = flagString(flags.include);
+    const body = await ctx.client().templates.get(
+      args.templateId ?? "",
+      include === void 0 ? void 0 : { include: asSdkInput(include) }
+    );
     return { data: body };
   }
 });
@@ -6505,6 +7576,7 @@ var whoamiCommand = defineCommand({
       if (error instanceof BrewApiError && (error.status === 401 || error.status === 403)) {
         throw error;
       }
+      ctx.signal.throwIfAborted();
       progress(
         ctx,
         "Warning: could not reach /v1/usage \u2014 showing local credential state only."
@@ -6535,6 +7607,7 @@ var ALL_COMMANDS = [
   contactsSearchCommand,
   contactsGetCommand,
   contactsCountCommand,
+  contactsCountByCommand,
   contactsUpsertCommand,
   contactsUpsertManyCommand,
   contactsUpdateCommand,
@@ -6618,6 +7691,7 @@ var ALL_COMMANDS = [
   analyticsCampaignsCommand,
   analyticsAutomationsCommand,
   analyticsEventsCommand,
+  analyticsEventCountsCommand,
   analyticsSendsListCommand,
   analyticsSendsGetCommand,
   analyticsTriggerInstancesListCommand,
@@ -6637,6 +7711,11 @@ var ALL_COMMANDS = [
   domainsHealthCommand,
   domainsUpdateCommand,
   domainsDeleteCommand,
+  domainsUnsubscribesListCommand,
+  domainsUnsubscribesAddCommand,
+  domainsUnsubscribesRemoveCommand,
+  domainsUnsubscribesImportCommand,
+  domainsUnsubscribesExportCommand,
   contentGenerateImageCommand,
   contentGifCommand,
   contentTransformCommand,
@@ -6695,6 +7774,7 @@ Environment:
 Exit codes:
   0 success \xB7 1 API/runtime error \xB7 2 usage error \xB7 3 auth error
   4 confirmation required (re-run with --yes)
+  130 interrupted (SIGINT) \xB7 143 terminated (SIGTERM)
 
 Agents: run \`${CLI_NAME} docs --agent\` for the machine-readable manifest.
 `;
@@ -6712,8 +7792,8 @@ async function run(argv, io, commands = ALL_COMMANDS) {
     (text) => {
       commanderStderr.push(text);
     },
-    (code) => {
-      commandExitCode = code;
+    (code2) => {
+      commandExitCode = code2;
     }
   );
   const flushCommanderStderr = () => {
@@ -6733,9 +7813,51 @@ async function run(argv, io, commands = ALL_COMMANDS) {
     }
     flushCommanderStderr();
     const ctx = activeContext ?? makeFallbackContext(io, argv);
-    printError(ctx, error);
-    return toExitCode(error);
+    const reported = reportedError(ctx, error);
+    printError(ctx, reported, errorContextFor(ctx, commands));
+    return toExitCode(reported);
+  }
+}
+function reportedError(ctx, error) {
+  if (!ctx.signal.aborted) {
+    return error;
+  }
+  if (error instanceof BrewApiError || error instanceof CliApiError) {
+    return error;
   }
+  return ctx.signal.reason;
+}
+function errorContextFor(ctx, commands) {
+  const request = ctx.transport.lastRequest();
+  const drain = ctx.transport.drain();
+  const bound = request === void 0 ? void 0 : commandFor(request, commands);
+  const isRead = bound === void 0 ? ctx.traits?.isRead : bound.commandClass === "read";
+  return {
+    ...request === void 0 ? {} : { request },
+    ...drain === void 0 ? {} : { drain },
+    ...isRead === void 0 ? {} : { isRead },
+    replays: bound === void 0 ? ctx.traits?.replays === true : (bound.flags ?? []).includes(IDEMPOTENCY_FLAG),
+    readsStdin: readsStdin(ctx.rawArgv),
+    retryCommand: (key) => buildRetryCommand(ctx.rawArgv, key)
+  };
+}
+function commandFor(request, commands) {
+  const apiPath = request.path.split("?")[0] ?? "";
+  return commands.find(
+    (spec) => spec.route !== void 0 && spec.route.method === request.method && matchesTemplate(spec.route.path, apiPath)
+  );
+}
+function readsStdin(rawArgv) {
+  return rawArgv.some(
+    (token, index) => token === "-" && ["--input", "--file", "--data"].includes(rawArgv[index - 1] ?? "")
+  );
+}
+function traitsOf(spec) {
+  return {
+    isRead: spec.commandClass === "read",
+    replays: (spec.flags ?? []).includes(IDEMPOTENCY_FLAG),
+    defaultTimeoutMs: spec.defaultTimeoutMs
+  };
 }
 function handleCommanderError(error, ctx, flush) {
   const isHelpCode = error.code === "commander.helpDisplayed" || error.code === "commander.help";
@@ -6824,16 +7946,21 @@ function registerCommand(program, spec, io, rawArgv, onContext, onExitCode) {
       },
       {}
     );
-    const ctx = makeContext({ io, flags, rawArgv });
+    const ctx = makeContext({ io, flags, rawArgv, traits: traitsOf(spec) });
     onContext?.(ctx);
     const invocation = { ctx, args: positional, flags };
     await enforceConfirmation(spec, invocation);
-    const outcome = await spec.run(invocation);
-    if (outcome !== void 0) {
-      printData(ctx, outcome.data, outcome.human);
-      if (outcome.exitCode !== void 0 && outcome.exitCode !== 0) {
-        onExitCode?.(outcome.exitCode);
+    ctx.startDeadline();
+    try {
+      const outcome = await spec.run(invocation);
+      if (outcome !== void 0) {
+        printData(ctx, outcome.data, outcome.human);
+        if (outcome.exitCode !== void 0 && outcome.exitCode !== 0) {
+          onExitCode?.(outcome.exitCode);
+        }
       }
+    } finally {
+      ctx.stopDeadline();
     }
   });
 }
@@ -6872,20 +7999,77 @@ function buildCommandHelpFooter(spec) {
   return lines.join("\n");
 }
 
+// src/lib/interrupt.ts
+function createInterrupter(input) {
+  const controller = new AbortController();
+  const graceMs = input.graceMs ?? 3e3;
+  let first;
+  let grace;
+  const forceExit = (signal, why) => {
+    input.stderr.write(`
+brew-cli: ${why}; exiting without waiting.
+`);
+    input.exit(exitCodeForSignal(signal));
+  };
+  const trigger = (signal) => {
+    if (first !== void 0) {
+      forceExit(signal, `${signal} received twice`);
+      return;
+    }
+    first = signal;
+    controller.abort(new CliInterruptError(signal));
+    grace = setTimeout(() => {
+      forceExit(signal, `still stopping ${graceMs / 1e3}s after ${signal}`);
+    }, graceMs);
+    grace.unref?.();
+  };
+  input.source.on("SIGINT", () => {
+    trigger("SIGINT");
+  });
+  input.source.on("SIGTERM", () => {
+    trigger("SIGTERM");
+  });
+  return {
+    signal: controller.signal,
+    trigger,
+    received: () => first,
+    settle: () => {
+      if (grace !== void 0) {
+        clearTimeout(grace);
+      }
+    }
+  };
+}
+
 // src/bin.ts
-function realIo() {
+function realIo(interrupter2) {
+  const { signal } = interrupter2;
   return {
     stdout: process.stdout,
     stderr: process.stderr,
     isTtyOut: process.stdout.isTTY === true,
     isTtyIn: process.stdin.isTTY === true,
     env: process.env,
+    signal,
     readStdin: async () => {
+      const stop = () => {
+        process.stdin.destroy();
+      };
+      signal.addEventListener("abort", stop, { once: true });
       process.stdin.setEncoding("utf8");
       let data = "";
-      for await (const chunk of process.stdin) {
-        data += chunk;
+      try {
+        for await (const chunk of process.stdin) {
+          data += chunk;
+        }
+      } catch (error) {
+        if (!signal.aborted) {
+          throw error;
+        }
+      } finally {
+        signal.removeEventListener("abort", stop);
       }
+      signal.throwIfAborted();
       return data;
     },
     readLine: async (prompt) => {
@@ -6893,14 +8077,34 @@ function realIo() {
         input: process.stdin,
         output: process.stderr
       });
+      rl.on("SIGINT", () => {
+        interrupter2.trigger("SIGINT");
+      });
       try {
-        return await rl.question(prompt);
+        return await rl.question(prompt, { signal });
       } finally {
         rl.close();
       }
     }
   };
 }
-process.exitCode = await run(process.argv.slice(2), realIo());
+var interrupter = createInterrupter({
+  source: process,
+  stderr: process.stderr,
+  exit: (code2) => process.exit(code2)
+});
+var code = await run(process.argv.slice(2), realIo(interrupter));
+interrupter.settle();
+process.exitCode = code;
+var received = interrupter.received();
+if (received !== void 0 && code === exitCodeForSignal(received) && process.platform !== "win32") {
+  await new Promise((resolve) => {
+    process.stderr.write("", () => {
+      resolve();
+    });
+  });
+  process.removeAllListeners(received);
+  process.kill(process.pid, received);
+}
 //# sourceMappingURL=bin.js.map
 //# sourceMappingURL=bin.js.map