@indigoai-us/hq-cli 5.69.0 → 5.71.0

package/src/commands/dm.ts

@@ -702,11 +702,422 @@ async function runDmRequests(): Promise<void> {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Receive side — reading DMs (inbox, 1:1 thread, channel/group history).
+// The backend read endpoints (GET /v1/notify/inbox, GET /v1/notify/thread,
+// GET /v1/notify/channels/{id}/messages) already back the HQ Sync menubar; the
+// commands below expose the same reads from the CLI.
+// ---------------------------------------------------------------------------
+
+/** One incoming DM as returned by GET /v1/notify/inbox. */
+export interface DmInboxEvent {
+  eventId: string;
+  fromPersonUid?: string;
+  fromEmail?: string;
+  fromDisplayName?: string;
+  body: string;
+  createdAt: string;
+  details?: string;
+  prompt?: string;
+  acknowledgedAt?: string;
+}
+
+/** One message in a 1:1 thread as returned by GET /v1/notify/thread. */
+export interface DmThreadMessage {
+  eventId: string;
+  fromPersonUid?: string;
+  fromEmail?: string;
+  fromDisplayName?: string;
+  body: string;
+  createdAt: string;
+  direction: "in" | "out";
+  details?: string;
+  prompt?: string;
+}
+
+/** One channel/group message from GET /v1/notify/channels/{id}/messages. */
+export interface ChannelMessageItem {
+  eventId?: string;
+  messageId?: string;
+  fromPersonUid?: string;
+  fromEmail?: string;
+  fromDisplayName?: string;
+  body: string;
+  createdAt: string;
+}
+
+/**
+ * Human label for a message sender — display name, else email, else uid. Pure →
+ * unit-testable.
+ */
+export function senderLabel(m: {
+  fromDisplayName?: string;
+  fromEmail?: string;
+  fromPersonUid?: string;
+}): string {
+  return (
+    m.fromDisplayName?.trim() ||
+    m.fromEmail?.trim() ||
+    m.fromPersonUid?.trim() ||
+    "unknown"
+  );
+}
+
+/**
+ * Render an ISO timestamp as a compact relative age ("3m ago", "2h ago",
+ * "5d ago"), falling back to a YYYY-MM-DD date for anything older than a week or
+ * an unparseable input. `nowMs` is injected so the formatting is unit-testable.
+ * Pure.
+ */
+export function formatRelativeTime(iso: string, nowMs: number): string {
+  const t = new Date(iso).getTime();
+  if (isNaN(t)) return iso;
+  const diff = nowMs - t;
+  if (diff < 60_000) return "just now";
+  const mins = Math.floor(diff / 60_000);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  return new Date(t).toISOString().slice(0, 10);
+}
+
+/** A DM is unread until the recipient acks it. Pure. */
+export function isUnread(e: { acknowledgedAt?: string }): boolean {
+  return !e.acknowledgedAt;
+}
+
+/** Event ids of the unread messages in a fetched inbox page. Pure. */
+export function unreadEventIds(events: DmInboxEvent[]): string[] {
+  return events
+    .filter(isUnread)
+    .map((e) => e.eventId)
+    .filter((id): id is string => typeof id === "string" && id.length > 0);
+}
+
+/** Keep only the unread messages. Pure. */
+export function filterUnread(events: DmInboxEvent[]): DmInboxEvent[] {
+  return events.filter(isUnread);
+}
+
+/**
+ * Collapse a message body to a single trimmed line for list rendering, capped
+ * so one row stays readable. Pure.
+ */
+export function firstLine(body: string, max = 240): string {
+  const oneLine = (body ?? "").replace(/\s+/g, " ").trim();
+  if (oneLine.length <= max) return oneLine;
+  return oneLine.slice(0, max - 1) + "…";
+}
+
+/**
+ * Turn a person identifier into the query the thread endpoint expects. An email
+ * rides `withEmail` (server resolves it); a prs_/agt_ uid rides `withPersonUid`.
+ * A bare name is rejected — resolve it first with `hq people resolve`. Pure →
+ * unit-testable. Throws with a user-facing message on an invalid identifier.
+ */
+export function buildThreadQuery(identifier: string): Record<string, string> {
+  const rcpt = detectRecipient(identifier);
+  if (!rcpt) {
+    throw new Error(
+      `Invalid person '${identifier}': pass an email or a personUid/agentUid (prs_… / agt_…). Resolve a name first with \`hq people resolve\`.`,
+    );
+  }
+  if (rcpt.toEmail) return { withEmail: rcpt.toEmail };
+  return { withPersonUid: rcpt.toPersonUid! };
+}
+
+/** Render one inbox row (marker · age · sender · first line of body). */
+export function formatInboxEvent(e: DmInboxEvent, nowMs: number): string {
+  const marker = isUnread(e) ? chalk.cyan("●") : " ";
+  const when = chalk.dim(formatRelativeTime(e.createdAt, nowMs));
+  const who = chalk.bold(senderLabel(e));
+  const email =
+    e.fromEmail && e.fromDisplayName ? chalk.dim(` <${e.fromEmail}>`) : "";
+  return `${marker} ${when}  ${who}${email}\n    ${firstLine(e.body)}`;
+}
+
+/** Render one 1:1 thread line, tagged by direction. */
+export function formatThreadMessage(m: DmThreadMessage, nowMs: number): string {
+  const arrow = m.direction === "out" ? chalk.dim("→") : chalk.cyan("←");
+  const who = m.direction === "out" ? "you" : senderLabel(m);
+  const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
+  return `${arrow} ${chalk.bold(who)} ${when}\n    ${firstLine(m.body)}`;
+}
+
+/** Render one channel/group message line. */
+export function formatChannelMessage(
+  m: ChannelMessageItem,
+  nowMs: number,
+): string {
+  const who = chalk.bold(senderLabel(m));
+  const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
+  return `${who} ${when}\n    ${firstLine(m.body)}`;
+}
+
+/** POST /v1/notify/inbox/ack — idempotently mark messages read. */
+async function ackEvents(token: string, eventIds: string[]): Promise<void> {
+  if (eventIds.length === 0) return;
+  const res = await vaultApiFetch({
+    token,
+    path: "/v1/notify/inbox/ack",
+    method: "POST",
+    body: { eventIds },
+  });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new Error(
+      friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+    );
+  }
+}
+
+interface DmInboxOpts {
+  limit?: string;
+  unread?: boolean;
+  markRead?: boolean;
+  json?: boolean;
+}
+
+async function runDmInbox(opts: DmInboxOpts): Promise<void> {
+  try {
+    const token = await ensureCognitoToken();
+    const query: Record<string, string> = {};
+    if (opts.limit) query.limit = opts.limit;
+    const res = await vaultApiFetch({ token, path: "/v1/notify/inbox", query });
+    if (!res.ok) {
+      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+      console.error(
+        chalk.red(
+          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+        ),
+      );
+      process.exit(1);
+    }
+    const data = (await res.json()) as {
+      events?: DmInboxEvent[];
+      nextCursor?: string;
+    };
+    const all = data.events ?? [];
+    const shown = opts.unread ? filterUnread(all) : all;
+
+    if (opts.json) {
+      console.log(JSON.stringify(shown, null, 2));
+    } else if (shown.length === 0) {
+      console.log(
+        chalk.dim(opts.unread ? "No unread messages." : "No messages yet."),
+      );
+    } else {
+      const unreadCount = filterUnread(all).length;
+      const suffix = unreadCount > 0 ? ` (${unreadCount} unread)` : "";
+      console.log(
+        chalk.green(
+          `${shown.length} message${shown.length === 1 ? "" : "s"}${suffix}:`,
+        ),
+      );
+      const now = Date.now();
+      for (const e of shown) console.log(`\n${formatInboxEvent(e, now)}`);
+      if (data.nextCursor) {
+        console.log(
+          chalk.dim("\nMore messages available — raise --limit to see them."),
+        );
+      }
+    }
+
+    // Ack every unread message on the fetched page (not just the filtered view).
+    if (opts.markRead) {
+      const ids = unreadEventIds(all);
+      await ackEvents(token, ids);
+      if (!opts.json && ids.length > 0) {
+        console.log(chalk.dim(`\nMarked ${ids.length} read.`));
+      }
+    }
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
+interface DmThreadOpts {
+  limit?: string;
+  ack?: boolean;
+  json?: boolean;
+}
+
+async function runDmThread(
+  identifier: string,
+  opts: DmThreadOpts,
+): Promise<void> {
+  try {
+    const query = buildThreadQuery(identifier);
+    if (opts.limit) query.limit = opts.limit;
+    const token = await ensureCognitoToken();
+    const res = await vaultApiFetch({
+      token,
+      path: "/v1/notify/thread",
+      query,
+    });
+    if (!res.ok) {
+      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+      console.error(
+        chalk.red(
+          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+        ),
+      );
+      process.exit(1);
+    }
+    const data = (await res.json()) as { messages?: DmThreadMessage[] };
+    const messages = data.messages ?? [];
+    // The server returns newest-first; read a conversation oldest-first.
+    const ordered = [...messages].reverse();
+
+    if (opts.json) {
+      console.log(JSON.stringify(ordered, null, 2));
+    } else if (ordered.length === 0) {
+      console.log(chalk.dim(`No messages with ${identifier} yet.`));
+    } else {
+      console.log(
+        chalk.green(
+          `${ordered.length} message${ordered.length === 1 ? "" : "s"} with ${identifier}:`,
+        ),
+      );
+      const now = Date.now();
+      for (const m of ordered) console.log(`\n${formatThreadMessage(m, now)}`);
+    }
+
+    // Mark the incoming messages read unless the caller opted out. Best-effort:
+    // a read is a side effect, not the point of the command, so an ack failure
+    // is surfaced but does not fail the read.
+    if (opts.ack !== false) {
+      const inIds = messages
+        .filter((m) => m.direction === "in")
+        .map((m) => m.eventId)
+        .filter((id): id is string => typeof id === "string" && id.length > 0);
+      try {
+        await ackEvents(token, inIds);
+      } catch (ackErr) {
+        console.error(
+          chalk.dim(
+            `(could not mark read: ${
+              ackErr instanceof Error ? ackErr.message : String(ackErr)
+            })`,
+          ),
+        );
+      }
+    }
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * Resolve a `hq dm channel <target>` argument to a channelId. Accepts a channel
+ * name (bare or `#name`) resolved against the caller's channels, or a raw
+ * channelId (the only way to address an unnamed group DM — copy it from
+ * `hq channels`). Throws a user-facing message when nothing matches or a name is
+ * ambiguous.
+ */
+async function resolveChannelId(token: string, target: string): Promise<string> {
+  const raw = target.trim().replace(/^#/, "");
+  if (!raw) throw new Error("A channel name or id is required.");
+  const channels = await fetchChannels(token);
+  const named = matchChannelsByName(channels, raw);
+  if (named.length === 1) return named[0].channelId;
+  if (named.length > 1) {
+    throw new Error(
+      `'${raw}' matches ${named.length} channels — pass the channel id instead (see \`hq channels\`).`,
+    );
+  }
+  const byId = channels.find((c) => c.channelId === raw);
+  if (byId) return byId.channelId;
+  throw new Error(
+    `No channel named or with id '${raw}' — run \`hq channels\` to see yours.`,
+  );
+}
+
+interface DmChannelOpts {
+  limit?: string;
+  markRead?: boolean;
+  json?: boolean;
+}
+
+async function runDmChannel(
+  target: string,
+  opts: DmChannelOpts,
+): Promise<void> {
+  try {
+    const token = await ensureCognitoToken();
+    const channelId = await resolveChannelId(token, target);
+    const query: Record<string, string> = {};
+    if (opts.limit) query.limit = opts.limit;
+    const res = await vaultApiFetch({
+      token,
+      path: `/v1/notify/channels/${encodeURIComponent(channelId)}/messages`,
+      query,
+    });
+    if (!res.ok) {
+      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+      console.error(
+        chalk.red(
+          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+        ),
+      );
+      process.exit(1);
+    }
+    const data = (await res.json()) as { messages?: ChannelMessageItem[] };
+    const messages = data.messages ?? [];
+    const ordered = [...messages].reverse(); // oldest-first for reading
+
+    if (opts.json) {
+      console.log(JSON.stringify(ordered, null, 2));
+    } else if (ordered.length === 0) {
+      console.log(chalk.dim("No messages in this channel yet."));
+    } else {
+      console.log(
+        chalk.green(
+          `${ordered.length} message${ordered.length === 1 ? "" : "s"}:`,
+        ),
+      );
+      const now = Date.now();
+      for (const m of ordered) console.log(`\n${formatChannelMessage(m, now)}`);
+    }
+
+    if (opts.markRead) {
+      // messages are newest-first from the server; advance the read cursor to
+      // the newest one we saw.
+      const newest = messages[0]?.createdAt;
+      const readRes = await vaultApiFetch({
+        token,
+        path: `/v1/notify/channels/${encodeURIComponent(channelId)}/read`,
+        method: "POST",
+        body: newest ? { lastReadAt: newest } : {},
+      });
+      if (!opts.json && readRes.ok) {
+        console.log(chalk.dim("\nMarked read."));
+      }
+    }
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
 export function registerDmCommand(program: Command): void {
   const dm = program
     .command("dm")
     .description(
-      "Send a direct message and manage connection requests.",
+      "Send and read direct messages, and manage connection requests.",
     );
 
   dm
@@ -746,6 +1157,43 @@ export function registerDmCommand(program: Command): void {
       },
     );
 
+  dm
+    .command("inbox")
+    .description("List your recent incoming direct messages.")
+    .option("--limit <n>", "Max messages to fetch (server-capped)")
+    .option("--unread", "Show only unread messages")
+    .option("--mark-read", "Mark the fetched messages as read after listing")
+    .option("--json", "Output raw JSON instead of a list")
+    .action(async (opts: DmInboxOpts) => {
+      await runDmInbox(opts);
+    });
+
+  dm
+    .command("thread <person>")
+    .alias("read")
+    .description(
+      "Show your two-way conversation with a person (email, personUid, or agentUid). Reads oldest-first and marks their messages read unless --no-ack.",
+    )
+    .option("--limit <n>", "Max messages to fetch (server-capped)")
+    .option("--no-ack", "Do not mark the incoming messages as read")
+    .option("--json", "Output raw JSON instead of a transcript")
+    .action(async (person: string, opts: DmThreadOpts) => {
+      await runDmThread(person, opts);
+    });
+
+  dm
+    .command("channel <target>")
+    .alias("history")
+    .description(
+      "Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`.",
+    )
+    .option("--limit <n>", "Max messages to fetch (server-capped)")
+    .option("--mark-read", "Advance your read marker to the newest message")
+    .option("--json", "Output raw JSON instead of a transcript")
+    .action(async (target: string, opts: DmChannelOpts) => {
+      await runDmChannel(target, opts);
+    });
+
   dm
     .command("requests")
     .description("List your pending incoming connection requests.")