@clankmates/cli 0.12.0 → 0.13.0

package/src/commands/inbox.ts

@@ -1,16 +1,7 @@
 import {
   assertSinceFlags,
-  authenticatedActorKey,
-  cacheFlags,
   cacheResult,
   changeResponseMeta,
-  inboxMessagesScope,
-  inboxThreadsScope,
-  prepareCachePlan,
-  saveCacheTimestamp,
-  type CachePlan,
-  type CacheResult,
-  type CacheScope,
 } from "../lib/cache";
 import {
   booleanFlag,
@@ -19,35 +10,45 @@ import {
   stringFlag,
   type ParsedArgs,
 } from "../lib/args";
-import { resolveBodyInput } from "../lib/body-input";
 import { createCommandContext, type CommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
+import { printValue, type Io } from "../lib/output";
+import { paginatedJson } from "../lib/pagination";
 import {
-  formatTimestamp,
-  indent,
-  joinBlocks,
-  renderFields,
-  renderPagination,
-  renderSection,
-  shortId,
-} from "../lib/human";
-import { resolveJsonInput } from "../lib/json-input";
-import { printJson, printValue, type Io } from "../lib/output";
-import { paginatedJson, paginationInfo } from "../lib/pagination";
+  maybePrepareCachePlan,
+  maybeSaveCacheTimestamp,
+  parseLatestFirstOrder,
+  printChangeCheckResponse,
+  requiredSince,
+  resolvedSince,
+} from "../lib/polling";
+import { resolveMessageContent } from "./inbox/content";
+import {
+  parseMailboxFilter,
+  parseParticipantScope,
+  parseStatusFilter,
+} from "./inbox/filters";
+import {
+  parseRecipient,
+  resolveSender,
+} from "./inbox/participants";
+import {
+  ownerIdsForThreadDisplay,
+  publicUserHandlesById,
+  printThreadCollection,
+  renderAttachmentCollection,
+  renderThreadAction,
+  renderThreadWithMessages,
+} from "./inbox/render";
+import { runInboxMessagesCommand } from "./inbox/messages";
+import { runSchemaCommand } from "./inbox/schema";
+import { runScreeningCommand } from "./inbox/screening";
+import { maybeInboxMessagesScope, maybeInboxThreadsScope } from "./inbox/sync-scopes";
+import { runInboxWatchCommand } from "./inbox/watch";
 import type {
-  ChangeCheckResponse,
-  ExternalEmailAcceptance,
-  ExternalEmailIntakeAttributes,
-  InboxRecipient,
-  InboxSender,
-  LatestFirstOrder,
   MailboxFilter,
-  MessageAttachmentAttributes,
-  MessageAttributes,
   ParticipantScope,
-  ThreadAttributes,
   ThreadStatusFilter,
-  WhoamiActor,
 } from "../types/api";
 
 export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
@@ -204,6 +205,11 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       return;
     }
 
+    case "watch": {
+      await runInboxWatchCommand(context, args, io);
+      return;
+    }
+
     case "messages": {
       await runInboxMessagesCommand(context, args, io);
       return;
@@ -360,1215 +366,3 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
       throw new CliError("Unknown inbox subcommand", 2);
   }
 }
-
-async function resolveMessageContent(args: ParsedArgs): Promise<{
-  body?: string;
-  payload?: Record<string, unknown>;
-}> {
-  if (booleanFlag(args.flags, "stdin") && booleanFlag(args.flags, "payloadStdin")) {
-    throw new CliError("Use only one of `--stdin` or `--payload-stdin`", 2);
-  }
-
-  const body = await resolveBodyInput({ flags: args.flags });
-  const payload = await resolveJsonInput({
-    flags: args.flags,
-    inlineKey: "payload",
-    fileKey: "payloadFile",
-    stdinKey: "payloadStdin",
-    label: "Payload",
-  });
-
-  if (body === undefined && payload === undefined) {
-    throw new CliError(
-      "Provide at least one of `--body`, `--body-file`, `--stdin`, `--payload`, `--payload-file`, or `--payload-stdin`",
-      2,
-    );
-  }
-
-  return { body, payload };
-}
-
-async function runSchemaCommand(
-  context: CommandContext,
-  args: ParsedArgs,
-  io: Io,
-): Promise<void> {
-  const subcommand = args.positionals[1];
-
-  switch (subcommand) {
-    case "show": {
-      const target = requiredPositional(
-        args.positionals,
-        2,
-        "Missing schema target",
-      );
-      const schema = await getPublicInboxSchema(context, target);
-      printSchemaResource(context, io, schema);
-      return;
-    }
-
-    case "set": {
-      const scope = requiredPositional(
-        args.positionals,
-        2,
-        "Missing schema scope",
-      );
-      const inboxSchema = await requiredInboxSchema(args);
-
-      if (scope === "account") {
-        printSchemaResource(
-          context,
-          io,
-          await context.client.setAccountInboxSchema(inboxSchema),
-          "Updated account inbox schema",
-        );
-        return;
-      }
-
-      if (scope === "channel") {
-        const channelRef = requiredPositional(
-          args.positionals,
-          3,
-          "Missing channel name or id",
-        );
-        const channelId = await context.client.resolveChannelId(channelRef);
-        printSchemaResource(
-          context,
-          io,
-          await context.client.setChannelInboxSchema({
-            channelId,
-            inboxSchema,
-          }),
-          "Updated channel inbox schema",
-        );
-        return;
-      }
-
-      throw new CliError("Schema scope must be `account` or `channel`", 2);
-    }
-
-    case "remove": {
-      const scope = requiredPositional(
-        args.positionals,
-        2,
-        "Missing schema scope",
-      );
-
-      if (scope === "account") {
-        printSchemaResource(
-          context,
-          io,
-          await context.client.removeAccountInboxSchema(),
-          "Removed account inbox schema",
-        );
-        return;
-      }
-
-      if (scope === "channel") {
-        const channelRef = requiredPositional(
-          args.positionals,
-          3,
-          "Missing channel name or id",
-        );
-        const channelId = await context.client.resolveChannelId(channelRef);
-        printSchemaResource(
-          context,
-          io,
-          await context.client.removeChannelInboxSchema(channelId),
-          "Removed channel inbox schema",
-        );
-        return;
-      }
-
-      throw new CliError("Schema scope must be `account` or `channel`", 2);
-    }
-
-    case "acceptance": {
-      const scope = requiredPositional(
-        args.positionals,
-        2,
-        "Missing schema acceptance scope",
-      );
-
-      if (scope === "account") {
-        const externalEmailAcceptance = parseExternalEmailAcceptance(
-          requiredPositional(
-            args.positionals,
-            3,
-            "Missing external email acceptance policy",
-          ),
-        );
-
-        printSchemaResource(
-          context,
-          io,
-          await context.client.setAccountExternalEmailAcceptance(
-            externalEmailAcceptance,
-          ),
-          "Updated account inbox acceptance",
-        );
-        return;
-      }
-
-      if (scope === "channel") {
-        const channelRef = requiredPositional(
-          args.positionals,
-          3,
-          "Missing channel name or id",
-        );
-        const externalEmailAcceptance = parseExternalEmailAcceptance(
-          requiredPositional(
-            args.positionals,
-            4,
-            "Missing external email acceptance policy",
-          ),
-        );
-        const channelId = await context.client.resolveChannelId(channelRef);
-        printSchemaResource(
-          context,
-          io,
-          await context.client.setChannelExternalEmailAcceptance({
-            channelId,
-            externalEmailAcceptance,
-          }),
-          "Updated channel inbox acceptance",
-        );
-        return;
-      }
-
-      throw new CliError("Schema acceptance scope must be `account` or `channel`", 2);
-    }
-
-    default:
-      throw new CliError("Unknown inbox schema subcommand", 2);
-  }
-}
-
-async function requiredInboxSchema(
-  args: ParsedArgs,
-): Promise<Record<string, unknown>> {
-  const schema = await resolveJsonInput({
-    flags: args.flags,
-    inlineKey: "schema",
-    fileKey: "schemaFile",
-    stdinKey: "schemaStdin",
-    label: "Inbox schema",
-  });
-
-  if (!schema) {
-    throw new CliError(
-      "Provide exactly one of `--schema`, `--schema-file`, or `--schema-stdin`",
-      2,
-    );
-  }
-
-  return schema;
-}
-
-function parseExternalEmailAcceptance(value: string): ExternalEmailAcceptance {
-  if (
-    value === "screen_unknown_senders" ||
-    value === "screen-unknown-senders"
-  ) {
-    return "screen_unknown_senders";
-  }
-
-  if (
-    value === "accept_valid_typed_email" ||
-    value === "accept-valid-typed-email"
-  ) {
-    return "accept_valid_typed_email";
-  }
-
-  throw new CliError(
-    "External email acceptance policy must be one of: screen-unknown-senders, accept-valid-typed-email",
-    2,
-  );
-}
-
-async function runScreeningCommand(
-  context: CommandContext,
-  args: ParsedArgs,
-  io: Io,
-): Promise<void> {
-  const subcommand = args.positionals[1];
-  const channelToken = stringFlag(args.flags, "channelToken");
-
-  switch (subcommand) {
-    case "list": {
-      const response = await context.client.listEmailScreeningIntakes({
-        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
-        cursor: stringFlag(args.flags, "cursor"),
-        channelToken,
-      });
-
-      printEmailIntakeCollection(args, context, io, response);
-      return;
-    }
-
-    case "processing": {
-      const response = await context.client.listEmailProcessingIntakes({
-        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
-        cursor: stringFlag(args.flags, "cursor"),
-        channelToken,
-      });
-
-      printEmailIntakeCollection(args, context, io, response);
-      return;
-    }
-
-    case "approve": {
-      const intake = await context.client.approveEmailIntake({
-        intakeId: requiredPositional(args.positionals, 2, "Missing intake id"),
-        channelToken,
-      });
-
-      printEmailIntakeAction(context, io, "Approved email intake", intake);
-      return;
-    }
-
-    case "approve-once": {
-      const intake = await context.client.approveEmailIntakeOnce({
-        intakeId: requiredPositional(args.positionals, 2, "Missing intake id"),
-        channelToken,
-      });
-
-      printEmailIntakeAction(context, io, "Approved email intake once", intake);
-      return;
-    }
-
-    case "ignore": {
-      const intake = await context.client.ignoreEmailIntake({
-        intakeId: requiredPositional(args.positionals, 2, "Missing intake id"),
-        channelToken,
-      });
-
-      printEmailIntakeAction(context, io, "Ignored email intake", intake);
-      return;
-    }
-
-    default:
-      throw new CliError("Unknown inbox screening subcommand", 2);
-  }
-}
-
-async function resolveSender(
-  context: CommandContext,
-  args: ParsedArgs,
-): Promise<InboxSender | undefined> {
-  const from = stringFlag(args.flags, "from");
-  const channelToken = stringFlag(args.flags, "channelToken");
-
-  if (!from) {
-    return undefined;
-  }
-
-  if (looksLikeUuid(from)) {
-    return channelSender(from);
-  }
-
-  if (channelToken) {
-    const whoami = await context.client.whoami(channelToken);
-
-    if (whoami.actor.type === "channel") {
-      if (whoami.actor.name === from) {
-        return channelSender(whoami.actor.id);
-      }
-
-      throw new CliError(
-        "With `--channel-token`, `--from` must match the authenticated channel name or UUID.",
-        2,
-      );
-    }
-  }
-
-  return channelSender(await context.client.resolveChannelId(from));
-}
-
-const UUID_PATTERN =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
-function looksLikeUuid(value: string): boolean {
-  return UUID_PATTERN.test(value);
-}
-
-function channelSender(channelId: string): InboxSender {
-  return {
-    type: "channel",
-    address: {
-      kind: "id",
-      value: channelId,
-    },
-  };
-}
-
-function parseStatusFilter(value: string | undefined): ThreadStatusFilter | undefined {
-  if (!value) {
-    return undefined;
-  }
-
-  if (value === "pending" || value === "open" || value === "blocked" || value === "all") {
-    return value;
-  }
-
-  throw new CliError("--status must be one of: pending, open, blocked, all", 2);
-}
-
-function parseMailboxFilter(value: string | undefined): MailboxFilter | undefined {
-  if (!value) {
-    return undefined;
-  }
-
-  if (value === "account" || value === "channel" || value === "all") {
-    return value;
-  }
-
-  throw new CliError("--mailbox must be one of: account, channel, all", 2);
-}
-
-function parseParticipantScope(value: string | undefined): ParticipantScope | undefined {
-  if (!value) {
-    return undefined;
-  }
-
-  if (value === "account" || value === "owner") {
-    return value;
-  }
-
-  throw new CliError("--participant-scope must be one of: account, owner", 2);
-}
-
-function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | undefined {
-  if (!value) {
-    return undefined;
-  }
-
-  if (value === "latest" || value === "oldest") {
-    return value;
-  }
-
-  throw new CliError("--order must be one of: latest, oldest", 2);
-}
-
-function requiredSince(
-  args: ParsedArgs,
-  cachePlan?: CachePlan,
-  label = "resource",
-): string {
-  const since = stringFlag(args.flags, "since");
-
-  if (since) {
-    return since;
-  }
-
-  if (cachePlan?.previousServerTimestamp) {
-    return cachePlan.previousServerTimestamp;
-  }
-
-  if (cacheFlags(args).sinceCache) {
-    throw new CliError(
-      `No cached server timestamp for this ${label} scope. Run a read command with \`--save-cache\` first.`,
-      2,
-    );
-  }
-
-  if (!since) {
-    throw new CliError("Missing `--since`", 2);
-  }
-
-  return since;
-}
-
-async function runInboxMessagesCommand(
-  context: CommandContext,
-  args: ParsedArgs,
-  io: Io,
-): Promise<void> {
-  const subcommand = args.positionals[1];
-
-  switch (subcommand) {
-    case "changes": {
-      assertSinceFlags(args);
-      const threadId = requiredPositional(args.positionals, 2, "Missing thread id");
-      const channelToken = stringFlag(args.flags, "channelToken");
-      const cacheScope = await maybeInboxMessagesScope(
-        args,
-        context,
-        channelToken,
-        threadId,
-      );
-      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
-      const response = await context.client.checkThreadMessageChanges({
-        threadId,
-        since: requiredSince(args, cachePlan, "inbox message"),
-        query: stringFlag(args.flags, "query"),
-        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
-        channelToken,
-      });
-      const savedServerTimestamp = await maybeSaveCacheTimestamp(
-        args,
-        context,
-        cacheScope,
-        changeResponseMeta(response),
-        response.has_updates === false,
-      );
-
-      printChangeCheckResponse(
-        context,
-        io,
-        response,
-        cacheResult(cachePlan, savedServerTimestamp),
-      );
-      return;
-    }
-
-    default:
-      throw new CliError("Unknown inbox messages subcommand", 2);
-  }
-}
-
-function printChangeCheckResponse(
-  context: CommandContext,
-  io: Io,
-  response: ChangeCheckResponse,
-  cache?: CacheResult,
-): void {
-  printValue(
-    io,
-    context.outputMode,
-    context.outputMode === "json"
-      ? { ...response, ...(cache ? { cache } : {}) }
-      : renderFields([
-          ["Has updates", response.has_updates ? "yes" : "no"],
-          ["Server time", formatTimestamp(response.server_time)],
-          [
-            "Recommended poll",
-            response.recommended_poll_after_ms === undefined
-              ? undefined
-              : `${response.recommended_poll_after_ms}ms`,
-          ],
-          ...cacheFields(cache),
-        ]),
-  );
-}
-
-async function parseRecipient(
-  context: CommandContext,
-  value: string,
-): Promise<InboxRecipient> {
-  if (looksLikeUuid(value)) {
-    if (await publicUserExists(context, value)) {
-      return {
-        type: "user",
-        address: {
-          kind: "id",
-          value,
-        },
-      };
-    }
-
-    return {
-      type: "channel",
-      address: {
-        kind: "id",
-        value,
-      },
-    };
-  }
-
-  if (value.startsWith("@")) {
-    const handleChannel = parseHandleChannel(value);
-
-    if (handleChannel) {
-      return {
-        type: "channel",
-        address: {
-          kind: "owner_handle_and_channel_name",
-          owner_handle: handleChannel.ownerHandle,
-          channel_name: handleChannel.channelName,
-        },
-      };
-    }
-
-    return {
-      type: "user",
-      address: {
-        kind: "handle",
-        value,
-      },
-    };
-  }
-
-  throw new CliError(
-    "Recipient must use one of: @handle, @handle/channel, user UUID, or channel UUID",
-    2,
-  );
-}
-
-async function publicUserExists(
-  context: CommandContext,
-  id: string,
-): Promise<boolean> {
-  const response = await context.client.listPublicUsersById([id]);
-  return response.items.some((user) => user.id === id);
-}
-
-function parseHandleChannel(
-  value: string,
-): { ownerHandle: string; channelName: string } | undefined {
-  const [ownerHandle, channelName, ...extra] = value.split("/");
-
-  if (
-    extra.length > 0 ||
-    !ownerHandle ||
-    !channelName ||
-    !ownerHandle.startsWith("@")
-  ) {
-    return undefined;
-  }
-
-  return { ownerHandle, channelName };
-}
-
-async function getPublicInboxSchema(
-  context: CommandContext,
-  target: string,
-) {
-  const handleChannel = parseHandleChannel(target);
-
-  if (handleChannel) {
-    return context.client.getPublicChannelInboxSchema(
-      handleChannel.ownerHandle,
-      handleChannel.channelName,
-    );
-  }
-
-  if (target.startsWith("@")) {
-    return context.client.getPublicAccountInboxSchema(target);
-  }
-
-  throw new CliError("Schema target must be `@handle` or `@handle/channel`", 2);
-}
-
-async function printThreadCollection(
-  args: ParsedArgs,
-  context: CommandContext,
-  io: Io,
-  response: {
-    items: Array<{ id: string; attributes: ThreadAttributes }>;
-    nextCursor?: string;
-    meta?: Record<string, unknown>;
-  },
-  channelToken?: string,
-  cache?: CacheResult,
-): Promise<void> {
-  if (context.outputMode === "json") {
-    printJson(
-      io,
-      paginatedJson(args, {
-        items: response.items,
-        nextCursor: response.nextCursor,
-        meta: response.meta,
-        ...(cache ? { cache } : {}),
-      }),
-    );
-    return Promise.resolve();
-  }
-
-  const actor = (await context.client.whoami(channelToken)).actor;
-  const peers = response.items.map((item) => threadPeer(item.attributes, actor));
-  const ownerIds = ownerIdsForThreadList(peers);
-  const publicUsers =
-    ownerIds.length === 0
-      ? new Map<string, string>()
-      : publicUserHandlesById(
-          (await context.client.listPublicUsersById(ownerIds)).items,
-        );
-
-  printValue(
-    io,
-    context.outputMode,
-    response.items.map((item, index) => ({
-      id: item.id,
-      with: formatThreadPeer(peers[index], publicUsers),
-      mailboxType: item.attributes.mailbox_type,
-      status: item.attributes.status,
-      lastMessageAt: item.attributes.last_message_at ?? "",
-      openedAt: item.attributes.opened_at ?? "",
-      expiresAt: item.attributes.expires_at ?? "",
-    })),
-  );
-  const pagination = paginationInfo(args, response.nextCursor);
-  const message = renderPagination(
-    pagination?.nextCursor,
-    pagination?.nextCommand,
-  );
-
-  if (message) {
-    io.stdout(message);
-  }
-
-  printCacheNote(io, cache);
-}
-
-function renderThreadWithMessages(
-  args: ParsedArgs,
-  thread: { id: string; attributes: ThreadAttributes },
-  messages: {
-    items: Array<{ id: string; attributes: MessageAttributes }>;
-    nextCursor?: string;
-  },
-  publicUsers: Map<string, string>,
-  cache?: CacheResult,
-): string {
-  const attrs = thread.attributes;
-  const messageBlocks =
-    messages.items.length === 0
-      ? "No messages."
-      : messages.items
-          .map((message) => renderMessage(message, publicUsers))
-          .join("\n\n");
-  const pagination = paginationInfo(args, messages.nextCursor);
-
-  return joinBlocks([
-    `Thread ${thread.id}`,
-    renderFields([
-      ["Mailbox", attrs.mailbox_type],
-      ["Status", attrs.status],
-      ["Last message", formatTimestamp(attrs.last_message_at)],
-      ["Opened", formatTimestamp(attrs.opened_at)],
-      [
-        "Expires",
-        attrs.expires_at ? formatTimestamp(attrs.expires_at) : undefined,
-      ],
-    ]),
-    renderSection(
-      "Participants",
-      renderFields([
-        ["A owner", formatUserActor(attrs.participant_a_owner_id, publicUsers)],
-        ["A channel", formatActor("channel", attrs.participant_a_channel_id)],
-        ["A seen", formatTimestamp(attrs.participant_a_seen_at)],
-        [
-          "A archived",
-          attrs.participant_a_archived_at
-            ? formatTimestamp(attrs.participant_a_archived_at)
-            : undefined,
-        ],
-        [
-          "A blocked",
-          attrs.participant_a_blocked_at
-            ? formatTimestamp(attrs.participant_a_blocked_at)
-            : undefined,
-        ],
-        [
-          "A resolved",
-          attrs.participant_a_resolved_at
-            ? formatTimestamp(attrs.participant_a_resolved_at)
-            : undefined,
-        ],
-        ["B owner", formatUserActor(attrs.participant_b_owner_id, publicUsers)],
-        ["B channel", formatActor("channel", attrs.participant_b_channel_id)],
-        ["B seen", formatTimestamp(attrs.participant_b_seen_at)],
-        [
-          "B archived",
-          attrs.participant_b_archived_at
-            ? formatTimestamp(attrs.participant_b_archived_at)
-            : undefined,
-        ],
-        [
-          "B blocked",
-          attrs.participant_b_blocked_at
-            ? formatTimestamp(attrs.participant_b_blocked_at)
-            : undefined,
-        ],
-        [
-          "B resolved",
-          attrs.participant_b_resolved_at
-            ? formatTimestamp(attrs.participant_b_resolved_at)
-            : undefined,
-        ],
-      ]),
-    ),
-    renderSection("Messages", messageBlocks),
-    renderPagination(pagination?.nextCursor, pagination?.nextCommand),
-    renderCacheNote(cache),
-  ]);
-}
-
-function renderMessage(
-  message: {
-    id: string;
-    attributes: MessageAttributes;
-  },
-  publicUsers: Map<string, string>,
-): string {
-  const attrs = message.attributes;
-  const headingParts = [
-    formatTimestamp(attrs.inserted_at),
-    shortId(message.id),
-    formatUserActor(attrs.sender_owner_id, publicUsers),
-    formatActor("channel", attrs.sender_channel_id),
-    formatActor("email-sender", attrs.external_email_sender_id),
-  ].filter((part) => part !== "-");
-  const contextPost = attrs.context_post_id
-    ? `Context post: ${attrs.context_post_id}\n`
-    : "";
-  const payload = attrs.payload
-    ? `\n\nPayload\n${indent(JSON.stringify(attrs.payload, null, 2))}`
-    : "";
-
-  return `${headingParts.join("  ")}\n${indent(`${contextPost}${attrs.body}`)}${payload}`;
-}
-
-function printSchemaResource(
-  context: CommandContext,
-  io: Io,
-  resource: {
-    id: string;
-    attributes: {
-      public_handle?: string | null;
-      name?: string | null;
-      inbox_schema?: Record<string, unknown> | null;
-      inbox_schema_hash?: string | null;
-      inbox_schema_updated_at?: string | null;
-      external_email_acceptance?: ExternalEmailAcceptance | null;
-    };
-  },
-  action?: string,
-): void {
-  printValue(
-    io,
-    context.outputMode,
-    context.outputMode === "json"
-      ? resource
-      : renderSchemaResource(resource, action),
-  );
-}
-
-async function maybePrepareCachePlan(
-  args: ParsedArgs,
-  context: CommandContext,
-  scope: CacheScope | undefined,
-): Promise<CachePlan | undefined> {
-  return cacheFlags(args).sinceCache && scope
-    ? prepareCachePlan(context, scope)
-    : undefined;
-}
-
-async function maybeSaveCacheTimestamp(
-  args: ParsedArgs,
-  context: CommandContext,
-  scope: CacheScope | undefined,
-  meta: Record<string, unknown> | undefined,
-  shouldSave: boolean,
-): Promise<string | undefined> {
-  return cacheFlags(args).saveCache && scope && shouldSave
-    ? saveCacheTimestamp(context, scope, meta)
-    : undefined;
-}
-
-async function maybeInboxThreadsScope(
-  args: ParsedArgs,
-  context: CommandContext,
-  channelToken: string | undefined,
-  status: ThreadStatusFilter | undefined,
-  mailbox: MailboxFilter | undefined,
-  participantScope: ParticipantScope | undefined,
-): Promise<CacheScope | undefined> {
-  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
-    return undefined;
-  }
-
-  return inboxThreadsScope({
-    context,
-    actorKey: await authenticatedActorKey(context, channelToken),
-    status,
-    mailbox,
-    participant: stringFlag(args.flags, "participant"),
-    participantScope,
-    query: stringFlag(args.flags, "query"),
-    hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
-    before: stringFlag(args.flags, "before"),
-  });
-}
-
-async function maybeInboxMessagesScope(
-  args: ParsedArgs,
-  context: CommandContext,
-  channelToken: string | undefined,
-  threadId: string,
-): Promise<CacheScope | undefined> {
-  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
-    return undefined;
-  }
-
-  return inboxMessagesScope({
-    context,
-    actorKey: await authenticatedActorKey(context, channelToken),
-    threadId,
-    query: stringFlag(args.flags, "query"),
-    hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
-    before: stringFlag(args.flags, "before"),
-  });
-}
-
-function resolvedSince(
-  args: ParsedArgs,
-  cachePlan: CachePlan | undefined,
-): string | undefined {
-  return stringFlag(args.flags, "since") ?? cachePlan?.previousServerTimestamp;
-}
-
-function printCacheNote(io: Io, cache: CacheResult | undefined): void {
-  const note = renderCacheNote(cache);
-
-  if (note) {
-    io.stdout(note);
-  }
-}
-
-function renderCacheNote(cache: CacheResult | undefined): string | undefined {
-  if (!cache) {
-    return undefined;
-  }
-
-  const details = [
-    cache.previousServerTimestamp
-      ? `used ${cache.previousServerTimestamp}`
-      : cache.hit
-        ? "used cache"
-        : "no cached timestamp",
-    cache.savedServerTimestamp ? `saved ${cache.savedServerTimestamp}` : undefined,
-  ].filter(Boolean);
-
-  return `Cache: ${details.join("; ")}.`;
-}
-
-function cacheFields(cache: CacheResult | undefined): Array<[string, string | undefined]> {
-  if (!cache) {
-    return [];
-  }
-
-  return [
-    ["Cache scope", cache.scopeKey],
-    ["Cached timestamp", cache.previousServerTimestamp],
-    ["Saved timestamp", cache.savedServerTimestamp],
-  ];
-}
-
-function renderSchemaResource(
-  resource: {
-    id: string;
-    attributes: {
-      public_handle?: string | null;
-      name?: string | null;
-      inbox_schema?: Record<string, unknown> | null;
-      inbox_schema_hash?: string | null;
-      inbox_schema_updated_at?: string | null;
-      external_email_acceptance?: ExternalEmailAcceptance | null;
-    };
-  },
-  action?: string,
-): string {
-  const attrs = resource.attributes;
-  const schema = attrs.inbox_schema
-    ? JSON.stringify(attrs.inbox_schema, null, 2)
-    : "No inbox schema.";
-
-  return joinBlocks([
-    action,
-    `Inbox schema ${resource.id}`,
-    renderFields([
-      ["Handle", attrs.public_handle],
-      ["Channel", attrs.name],
-      ["Email acceptance", attrs.external_email_acceptance],
-      ["Hash", attrs.inbox_schema_hash],
-      ["Updated", formatTimestamp(attrs.inbox_schema_updated_at)],
-    ]),
-    renderSection("Schema", indent(schema)),
-  ]);
-}
-
-function printEmailIntakeCollection(
-  args: ParsedArgs,
-  context: CommandContext,
-  io: Io,
-  response: {
-    items: Array<{ id: string; attributes: ExternalEmailIntakeAttributes }>;
-    nextCursor?: string;
-  },
-): void {
-  printValue(
-    io,
-    context.outputMode,
-    context.outputMode === "json"
-      ? paginatedJson(args, {
-          items: response.items,
-          nextCursor: response.nextCursor,
-        })
-      : renderEmailIntakeCollection(args, response),
-  );
-}
-
-function printEmailIntakeAction(
-  context: CommandContext,
-  io: Io,
-  action: string,
-  intake: { id: string; attributes: ExternalEmailIntakeAttributes },
-): void {
-  printValue(
-    io,
-    context.outputMode,
-    context.outputMode === "json"
-      ? intake
-      : joinBlocks([`${action}: ${intake.id}`, renderEmailIntake(intake)]),
-  );
-}
-
-function renderEmailIntakeCollection(
-  args: ParsedArgs,
-  response: {
-    items: Array<{ id: string; attributes: ExternalEmailIntakeAttributes }>;
-    nextCursor?: string;
-  },
-): string {
-  const body =
-    response.items.length === 0
-      ? "No email intakes."
-      : response.items.map((intake) => renderEmailIntake(intake)).join("\n\n");
-
-  const pagination = paginationInfo(args, response.nextCursor);
-  return joinBlocks([
-    body,
-    renderPagination(pagination?.nextCursor, pagination?.nextCommand),
-  ]);
-}
-
-function renderEmailIntake(intake: {
-  id: string;
-  attributes: ExternalEmailIntakeAttributes;
-}): string {
-  const attrs = intake.attributes;
-
-  return joinBlocks([
-    `Email intake ${intake.id}`,
-    renderFields([
-      ["Subject", attrs.subject ?? ""],
-      ["Status", attrs.status ?? ""],
-      ["Decision", attrs.decision ?? ""],
-      ["Sender", formatActor("email-sender", attrs.external_email_sender_id)],
-      ["Target channel", formatActor("channel", attrs.target_channel_id)],
-      ["Raw recipient", attrs.raw_recipient ?? ""],
-      ["Received count", formatOptionalNumber(attrs.received_count)],
-      ["Attachment count", formatOptionalNumber(attrs.attachment_count)],
-      ["Attachments withheld", formatOptionalBoolean(attrs.attachments_withheld)],
-      ["Last received", formatTimestamp(attrs.last_received_at)],
-      ["Released", formatTimestamp(attrs.released_at)],
-      ["Released thread", formatActor("thread", attrs.released_thread_id)],
-    ]),
-    attrs.body ? renderSection("Body", indent(attrs.body)) : "",
-  ]);
-}
-
-function renderAttachmentCollection(
-  args: ParsedArgs,
-  response: {
-    items: Array<{ id: string; attributes: MessageAttachmentAttributes }>;
-    nextCursor?: string;
-  },
-): string {
-  const body =
-    response.items.length === 0
-      ? "No attachments."
-      : response.items
-          .map((attachment) => {
-            const attrs = attachment.attributes;
-
-            return joinBlocks([
-              `Attachment ${attachment.id}`,
-              renderFields([
-                ["Name", attrs.name ?? ""],
-                ["Content type", attrs.content_type ?? ""],
-                ["Content length", formatOptionalNumber(attrs.content_length)],
-                ["Message", formatActor("message", attrs.message_id)],
-              ]),
-            ]);
-          })
-          .join("\n\n");
-
-  const pagination = paginationInfo(args, response.nextCursor);
-  return joinBlocks([
-    body,
-    renderPagination(pagination?.nextCursor, pagination?.nextCommand),
-  ]);
-}
-
-function renderThreadAction(
-  action: string,
-  thread: { id: string; attributes: ThreadAttributes },
-): string {
-  const attrs = thread.attributes;
-
-  return joinBlocks([
-    `${action}: ${thread.id}`,
-    renderFields([
-      ["Mailbox", attrs.mailbox_type],
-      ["Status", attrs.status],
-      ["Last message", formatTimestamp(attrs.last_message_at)],
-      ["Opened", formatTimestamp(attrs.opened_at)],
-      [
-        "Expires",
-        attrs.expires_at ? formatTimestamp(attrs.expires_at) : undefined,
-      ],
-    ]),
-  ]);
-}
-
-function formatActor(
-  kind: "user" | "channel" | "email-sender" | "thread" | "message",
-  id?: string | null,
-): string {
-  if (!id) {
-    return "-";
-  }
-
-  return `${kind}:${shortId(id)}`;
-}
-
-function formatOptionalBoolean(value?: boolean | null): string {
-  if (value === undefined || value === null) {
-    return "";
-  }
-
-  return value ? "yes" : "no";
-}
-
-function formatOptionalNumber(value?: number | null): string {
-  if (value === undefined || value === null) {
-    return "";
-  }
-
-  return String(value);
-}
-
-function formatUserActor(
-  id: string | null | undefined,
-  publicUsers: Map<string, string>,
-): string {
-  if (!id) {
-    return "-";
-  }
-
-  return publicUsers.get(id) ?? formatActor("user", id);
-}
-
-function ownerIdsForThreadDisplay(
-  thread: { attributes: ThreadAttributes },
-  messages: Array<{ attributes: MessageAttributes }>,
-): string[] {
-  const ids = [
-    thread.attributes.participant_a_owner_id,
-    thread.attributes.participant_b_owner_id,
-    ...messages.map((message) => message.attributes.sender_owner_id),
-  ];
-
-  return Array.from(new Set(ids.filter((id): id is string => Boolean(id))));
-}
-
-function ownerIdsForThreadList(
-  peers: Array<ThreadPeer>,
-): string[] {
-  return Array.from(
-    new Set(
-      peers
-        .map((peer) => peer.ownerId)
-        .filter((id): id is string => Boolean(id)),
-    ),
-  );
-}
-
-interface ThreadPeer {
-  ownerId?: string | null;
-  channelId?: string | null;
-}
-
-function threadPeer(attrs: ThreadAttributes, actor: WhoamiActor): ThreadPeer {
-  const side = threadActorSide(attrs, actor);
-
-  if (side === "a") {
-    return {
-      ownerId: attrs.participant_b_owner_id,
-      channelId: attrs.participant_b_channel_id,
-    };
-  }
-
-  if (side === "b") {
-    return {
-      ownerId: attrs.participant_a_owner_id,
-      channelId: attrs.participant_a_channel_id,
-    };
-  }
-
-  return {
-    ownerId: attrs.participant_a_owner_id,
-    channelId: attrs.participant_a_channel_id,
-  };
-}
-
-function threadActorSide(
-  attrs: ThreadAttributes,
-  actor: WhoamiActor,
-): "a" | "b" | undefined {
-  if (actor.type === "channel") {
-    if (attrs.participant_a_channel_id === actor.id) {
-      return "a";
-    }
-
-    if (attrs.participant_b_channel_id === actor.id) {
-      return "b";
-    }
-  }
-
-  const ownerId = actor.type === "user" ? actor.id : actor.owner_id;
-
-  if (attrs.participant_a_owner_id === ownerId) {
-    return "a";
-  }
-
-  if (attrs.participant_b_owner_id === ownerId) {
-    return "b";
-  }
-
-  return undefined;
-}
-
-function formatThreadPeer(
-  peer: ThreadPeer | undefined,
-  publicUsers: Map<string, string>,
-): string {
-  if (!peer) {
-    return "-";
-  }
-
-  if (peer.channelId) {
-    return formatActor("channel", peer.channelId);
-  }
-
-  return formatUserActor(peer.ownerId, publicUsers);
-}
-
-function publicUserHandlesById(
-  users: Array<{ id: string; attributes: { public_handle?: string | null } }>,
-): Map<string, string> {
-  const handles = new Map<string, string>();
-
-  for (const user of users) {
-    const handle = user.attributes.public_handle?.trim();
-
-    if (handle) {
-      handles.set(user.id, `@${handle}`);
-    }
-  }
-
-  return handles;
-}