@clankmates/cli 0.12.0 → 0.13.0

package/src/commands/inbox/thread-output.ts

@@ -0,0 +1,344 @@
+import type { ParsedArgs } from "../../lib/args";
+import type { CommandContext } from "../../lib/context";
+import type { CacheResult } from "../../lib/cache";
+import {
+  formatTimestamp,
+  indent,
+  joinBlocks,
+  renderFields,
+  renderPagination,
+  renderSection,
+  shortId,
+} from "../../lib/human";
+import { printJson, printValue, type Io } from "../../lib/output";
+import { paginatedJson, paginationInfo } from "../../lib/pagination";
+import { printCacheNote, renderCacheNote } from "../../lib/polling";
+import type {
+  MessageAttributes,
+  ThreadAttributes,
+  WhoamiActor,
+} from "../../types/api";
+
+export 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);
+}
+
+export 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),
+  ]);
+}
+
+export 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,
+      ],
+    ]),
+  ]);
+}
+
+export 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))));
+}
+
+export 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;
+}
+
+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 formatActor(
+  kind: "user" | "channel" | "email-sender",
+  id?: string | null,
+): string {
+  if (!id) {
+    return "-";
+  }
+
+  return `${kind}:${shortId(id)}`;
+}
+
+function formatUserActor(
+  id: string | null | undefined,
+  publicUsers: Map<string, string>,
+): string {
+  if (!id) {
+    return "-";
+  }
+
+  return publicUsers.get(id) ?? formatActor("user", 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);
+}

package/src/commands/inbox/watch.ts

@@ -0,0 +1,203 @@
+import {
+  assertSinceFlags,
+  authenticatedActorKey,
+  cacheFlags,
+  extractServerTimestamp,
+  inboxMessagesScope,
+  prepareCachePlan,
+  saveCacheTimestamp,
+  type CacheScope,
+} from "../../lib/cache";
+import {
+  booleanFlag,
+  integerFlag,
+  requiredPositional,
+  stringFlag,
+  type ParsedArgs,
+} from "../../lib/args";
+import type { CommandContext } from "../../lib/context";
+import { CliError } from "../../lib/errors";
+import type { Io } from "../../lib/output";
+
+export async function runInboxWatchCommand(
+  context: CommandContext,
+  args: ParsedArgs,
+  io: Io,
+): Promise<void> {
+  const subcommand = args.positionals[1];
+
+  switch (subcommand) {
+    case "messages": {
+      const threadId = requiredPositional(args.positionals, 2, "Missing thread id");
+      assertSinceFlags(args);
+      const channelToken = stringFlag(args.flags, "channelToken");
+      const scope = inboxMessagesScope({
+        context,
+        actorKey: await authenticatedActorKey(context, channelToken),
+        threadId,
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
+        before: stringFlag(args.flags, "before"),
+      });
+      const initialPlan = await prepareCachePlan(context, scope);
+      let since =
+        stringFlag(args.flags, "since") ??
+        initialPlan.previousServerTimestamp ??
+        (await initialMessageWatchSince({
+          context,
+          args,
+          scope,
+          threadId,
+          channelToken,
+        }));
+
+      do {
+        const result = await runMessageWatchCycle({
+          context,
+          io,
+          args,
+          scope,
+          threadId,
+          channelToken,
+          since,
+        });
+
+        since = result.nextSince ?? since;
+
+        if (booleanFlag(args.flags, "once")) {
+          return;
+        }
+
+        await sleep(result.pollAfterMs);
+      } while (true);
+    }
+
+    default:
+      throw new CliError("Unknown inbox watch subcommand", 2);
+  }
+}
+
+async function initialMessageWatchSince(input: {
+  context: CommandContext;
+  args: ParsedArgs;
+  scope: CacheScope;
+  threadId: string;
+  channelToken?: string;
+}): Promise<string> {
+  if (cacheFlags(input.args).sinceCache) {
+    throw new CliError(
+      "No cached server timestamp for this inbox message scope. Run a read command with `--save-cache` first.",
+      2,
+    );
+  }
+
+  return bootstrapMessageWatchSince(input);
+}
+
+async function bootstrapMessageWatchSince(input: {
+  context: CommandContext;
+  args: ParsedArgs;
+  scope: CacheScope;
+  threadId: string;
+  channelToken?: string;
+}): Promise<string> {
+  const response = await input.context.client.listMessagesForThread({
+    threadId: input.threadId,
+    limit: 1,
+    before: stringFlag(input.args.flags, "before"),
+    order: "latest",
+    query: stringFlag(input.args.flags, "query"),
+    hasAttachment: booleanFlag(input.args.flags, "hasAttachment") || undefined,
+    channelToken: input.channelToken,
+  });
+  const savedServerTimestamp = await saveCacheTimestamp(
+    input.context,
+    input.scope,
+    response.meta,
+  );
+
+  if (!savedServerTimestamp) {
+    throw new CliError(
+      "Watch startup response did not include a server timestamp. Use `--since` explicitly.",
+      1,
+    );
+  }
+
+  return savedServerTimestamp;
+}
+
+async function runMessageWatchCycle(input: {
+  context: CommandContext;
+  io: Io;
+  args: ParsedArgs;
+  scope: CacheScope;
+  threadId: string;
+  channelToken?: string;
+  since: string;
+}): Promise<{ nextSince?: string; pollAfterMs: number }> {
+  let cursor: string | undefined;
+  let latestMeta: Record<string, unknown> | undefined;
+  let pollAfterMs = DEFAULT_WATCH_POLL_AFTER_MS;
+
+  do {
+    const response = await input.context.client.listMessagesForThread({
+      threadId: input.threadId,
+      limit: integerFlag(input.args.flags, "limit", { label: "--limit" }),
+      cursor,
+      before: stringFlag(input.args.flags, "before"),
+      order: "oldest",
+      since: input.since,
+      query: stringFlag(input.args.flags, "query"),
+      hasAttachment: booleanFlag(input.args.flags, "hasAttachment") || undefined,
+      channelToken: input.channelToken,
+    });
+
+    latestMeta = response.meta;
+    pollAfterMs = recommendedPollAfterMs(response.meta) ?? pollAfterMs;
+
+    for (const message of response.items) {
+      input.io.stdout(
+        JSON.stringify({
+          kind: "message",
+          source: "inbox.messages",
+          threadId: input.threadId,
+          messageId: message.id,
+          message,
+          meta: {
+            cacheScope: input.scope.scopeKey,
+            serverTime: extractServerTimestamp(response.meta),
+          },
+        }),
+      );
+    }
+
+    cursor = response.nextCursor;
+  } while (cursor);
+
+  const savedServerTimestamp = await saveCacheTimestamp(
+    input.context,
+    input.scope,
+    latestMeta,
+  );
+
+  return {
+    nextSince: savedServerTimestamp,
+    pollAfterMs,
+  };
+}
+
+const DEFAULT_WATCH_POLL_AFTER_MS = 5_000;
+
+function recommendedPollAfterMs(meta: Record<string, unknown> | undefined): number | undefined {
+  const value = meta?.recommended_poll_after_ms;
+
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return undefined;
+  }
+
+  return value;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}