@clankmates/cli 0.5.2 → 0.6.1

package/src/commands/post.ts

@@ -9,8 +9,14 @@ import {
 import { resolveBodyInput } from "../lib/body-input";
 import { createCommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
+import {
+  formatTimestamp,
+  joinBlocks,
+  renderBodyBlock,
+  renderFields,
+} from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
-import type { PostAttributes } from "../types/api";
+import type { PostAttributes, ShareTokenResponse } from "../types/api";
 
 export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -36,12 +42,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              channelId,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post, { channelId, title: "Published post" }),
       );
       return;
     }
@@ -105,11 +106,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post, { title: "Updated post" }),
       );
       return;
     }
@@ -141,11 +138,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post),
       );
       return;
     }
@@ -170,11 +163,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post),
       );
       return;
     }
@@ -189,11 +178,7 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         context.outputMode,
         context.outputMode === "json"
           ? post
-          : {
-              id: post.id,
-              source: post.attributes.source,
-              body: post.attributes.body,
-            },
+          : renderPostDetail(post),
       );
       return;
     }
@@ -208,7 +193,13 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         return;
       }
 
-      printValue(io, context.outputMode, response);
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderShareToken("Issued post share token", response),
+      );
       return;
     }
 
@@ -253,3 +244,37 @@ function printPostCollection(
     })),
   );
 }
+
+function renderPostDetail(
+  post: { id: string; attributes: PostAttributes },
+  options: { title?: string; channelId?: string } = {},
+): string {
+  return joinBlocks([
+    options.title ?? `Post ${post.id}`,
+    renderFields([
+      ["ID", post.id],
+      ["Channel", options.channelId],
+      ["Source", post.attributes.source],
+      [
+        "Inserted",
+        post.attributes.inserted_at
+          ? formatTimestamp(post.attributes.inserted_at)
+          : undefined,
+      ],
+      [
+        "Updated",
+        post.attributes.updated_at
+          ? formatTimestamp(post.attributes.updated_at)
+          : undefined,
+      ],
+    ]),
+    "Body\n" + renderBodyBlock(post.attributes.body),
+  ]);
+}
+
+function renderShareToken(title: string, response: ShareTokenResponse): string {
+  return joinBlocks([
+    title,
+    renderFields([["Token", response.token]]),
+  ]);
+}

package/src/lib/args.ts

@@ -26,8 +26,7 @@ const CLI_OPTIONS = {
   "token-only": { type: "boolean" },
   channel: { type: "string" },
   "channel-id": { type: "string" },
-  senderChannel: { type: "string" },
-  "sender-channel": { type: "string" },
+  from: { type: "string" },
   channelToken: { type: "string" },
   "channel-token": { type: "string" },
   contextPostId: { type: "string" },
@@ -38,10 +37,16 @@ const CLI_OPTIONS = {
   stdin: { type: "boolean" },
   limit: { type: "string" },
   cursor: { type: "string" },
+  status: { type: "string" },
+  mailbox: { type: "string" },
 } as const;
 
 type ParsedValue = string | boolean;
 
+const REMOVED_OPTIONS: Record<string, string> = {
+  "--sender-channel": "`--sender-channel` has been removed. Use `--from` instead.",
+};
+
 export interface ParsedArgs {
   commandPath: string[];
   positionals: string[];
@@ -49,6 +54,8 @@ export interface ParsedArgs {
 }
 
 export function parseArgs(argv: string[]): ParsedArgs {
+  rejectRemovedOptions(argv);
+
   const parsed = parseNodeArgs({
     args: argv,
     allowPositionals: true,
@@ -66,6 +73,17 @@ export function parseArgs(argv: string[]): ParsedArgs {
   };
 }
 
+function rejectRemovedOptions(argv: string[]): void {
+  for (const arg of argv) {
+    const option = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+    const message = REMOVED_OPTIONS[option];
+
+    if (message) {
+      throw new CliError(message, 2);
+    }
+  }
+}
+
 export function stringFlag(
   flags: ParsedArgs["flags"],
   key: string,

package/src/lib/client.ts

@@ -20,12 +20,16 @@ import type {
   ChannelKeyIssueResponse,
   ChannelKeyRevokeResponse,
   ChannelPublicationResponse,
+  InboxRecipient,
+  InboxSender,
   IdResponse,
+  MailboxFilter,
   MessageAttributes,
   PostAttributes,
   ProfileConfig,
   ShareTokenResponse,
   ThreadAttributes,
+  ThreadStatusFilter,
   UserAttributes,
   WhoamiResponse,
 } from "../types/api";
@@ -535,29 +539,17 @@ export class ClankmatesClient {
     );
   }
 
-  async listInboxRequests(input: {
+  async listInboxThreads(input: {
+    status?: ThreadStatusFilter;
+    mailbox?: MailboxFilter;
     limit?: number;
     cursor?: string;
     channelToken?: string;
   } = {}) {
     return this.requestCollection<ThreadAttributes>(
-      withQuery(`${API_PREFIX}/inbox/requests`, {
-        "page[limit]": input.limit,
-        "page[after]": input.cursor,
-      }),
-      {
-        token: this.resolveInboxReadToken(input.channelToken),
-      },
-    );
-  }
-
-  async listInboxConversations(input: {
-    limit?: number;
-    cursor?: string;
-    channelToken?: string;
-  } = {}) {
-    return this.requestCollection<ThreadAttributes>(
-      withQuery(`${API_PREFIX}/inbox/conversations`, {
+      withQuery(`${API_PREFIX}/threads`, {
+        status: input.status,
+        mailbox: input.mailbox,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -590,53 +582,23 @@ export class ClankmatesClient {
     );
   }
 
-  async sendAccountIntro(input: {
-    email: string;
-    body: string;
-    senderChannelId?: string;
-    contextPostId?: string;
-    channelToken?: string;
-  }) {
-    return this.requestResource<ThreadAttributes>(`${API_PREFIX}/inbox/account-intros`, {
-      method: "POST",
-      token: this.resolveInboxWriteToken(input.channelToken),
-      body: {
-        data: {
-          type: "thread",
-          attributes: {
-            email: input.email,
-            body: input.body,
-            ...(input.senderChannelId
-              ? { sender_channel_id: input.senderChannelId }
-              : {}),
-            ...(input.contextPostId
-              ? { context_post_id: input.contextPostId }
-              : {}),
-          },
-        },
-      },
-    });
-  }
-
-  async sendChannelIntro(input: {
-    channelId: string;
+  async createThread(input: {
+    recipient: InboxRecipient;
     body: string;
-    senderChannelId?: string;
+    from?: InboxSender;
     contextPostId?: string;
     channelToken?: string;
   }) {
-    return this.requestResource<ThreadAttributes>(`${API_PREFIX}/inbox/channel-intros`, {
+    return this.requestResource<ThreadAttributes>(`${API_PREFIX}/threads`, {
       method: "POST",
       token: this.resolveInboxWriteToken(input.channelToken),
       body: {
         data: {
           type: "thread",
           attributes: {
-            channel_id: input.channelId,
+            recipient: input.recipient,
             body: input.body,
-            ...(input.senderChannelId
-              ? { sender_channel_id: input.senderChannelId }
-              : {}),
+            ...(input.from ? { from: input.from } : {}),
             ...(input.contextPostId
               ? { context_post_id: input.contextPostId }
               : {}),
@@ -646,27 +608,24 @@ export class ClankmatesClient {
     });
   }
 
-  async replyToThread(input: {
+  async appendThreadMessage(input: {
     threadId: string;
     body: string;
-    senderChannelId?: string;
+    from?: InboxSender;
     contextPostId?: string;
     channelToken?: string;
   }) {
     return this.requestResource<ThreadAttributes>(
-      `${API_PREFIX}/threads/${input.threadId}/reply`,
+      `${API_PREFIX}/threads/${input.threadId}/messages`,
       {
-        method: "PATCH",
+        method: "POST",
         token: this.resolveInboxWriteToken(input.channelToken),
         body: {
           data: {
             type: "thread",
-            id: input.threadId,
             attributes: {
               body: input.body,
-              ...(input.senderChannelId
-                ? { sender_channel_id: input.senderChannelId }
-                : {}),
+              ...(input.from ? { from: input.from } : {}),
               ...(input.contextPostId
                 ? { context_post_id: input.contextPostId }
                 : {}),

package/src/lib/help.ts

@@ -696,14 +696,22 @@ const HELP_ROOT = group(
     ),
     group(
       "inbox",
-      "Read inbox threads and act on conversations.",
+      "Read and manage inbox threads.",
       [
         command(
-          "requests",
-          "List inbox requests.",
-          `${CLI_NAME} inbox requests [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          "list",
+          "List inbox threads.",
+          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
+              option(
+                "--status <pending|open|blocked|all>",
+                "Filter by thread status.",
+              ),
+              option(
+                "--mailbox <account|channel|all>",
+                "Filter by mailbox type.",
+              ),
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -713,9 +721,9 @@ const HELP_ROOT = group(
           },
         ),
         command(
-          "conversations",
-          "List inbox conversations.",
-          `${CLI_NAME} inbox conversations [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          "show",
+          "Show one thread and its recent messages.",
+          `${CLI_NAME} inbox show <thread-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               LIMIT_OPTION,
@@ -727,37 +735,14 @@ const HELP_ROOT = group(
           },
         ),
         command(
-          "get",
-          "Fetch one thread by id.",
-          `${CLI_NAME} inbox get <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
-          {
-            options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
-          },
-        ),
-        command(
-          "messages",
-          "List messages for one thread.",
-          `${CLI_NAME} inbox messages <thread-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          "send",
+          "Send a first message to a recipient address.",
+          `${CLI_NAME} inbox send <recipient> (--body <markdown> | --body-file <path> | --stdin) [--from <channel-name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
-              LIMIT_OPTION,
-              CURSOR_OPTION,
-              CHANNEL_TOKEN_OPTION,
-              PROFILE_OPTION,
-              JSON_OPTION,
-            ],
-          },
-        ),
-        command(
-          "send-account-intro",
-          "Start an intro thread to an account email address.",
-          `${CLI_NAME} inbox send-account-intro --email <email> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
-          {
-            options: [
-              option("--email <email>", "Target account email address."),
               ...BODY_OPTIONS,
               option(
-                "--sender-channel <name-or-uuid>",
+                "--from <channel-name-or-uuid>",
                 "Send on behalf of one of the owner's channels.",
               ),
               option(
@@ -768,38 +753,20 @@ const HELP_ROOT = group(
               PROFILE_OPTION,
               JSON_OPTION,
             ],
-          },
-        ),
-        command(
-          "send-channel-intro",
-          "Start an intro thread to a channel id.",
-          `${CLI_NAME} inbox send-channel-intro <channel-id> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
-          {
-            options: [
-              ...BODY_OPTIONS,
-              option(
-                "--sender-channel <name-or-uuid>",
-                "Send on behalf of one of the owner's channels.",
-              ),
-              option(
-                "--context-post-id <post-id>",
-                "Attach a post id as conversation context.",
-              ),
-              CHANNEL_TOKEN_OPTION,
-              PROFILE_OPTION,
-              JSON_OPTION,
+            notes: [
+              "Recipient addresses support `email:<email>`, `user:<uuid>`, `user:@handle`, `channel:<uuid>`, and `channel:@handle/<channel-name>`.",
             ],
           },
         ),
         command(
           "reply",
           "Reply to an existing thread.",
-          `${CLI_NAME} inbox reply <thread-id> (--body <markdown> | --body-file <path> | --stdin) [--sender-channel <name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox reply <thread-id> (--body <markdown> | --body-file <path> | --stdin) [--from <channel-name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               ...BODY_OPTIONS,
               option(
-                "--sender-channel <name-or-uuid>",
+                "--from <channel-name-or-uuid>",
                 "Reply as one of the owner's channels when the thread mailbox type allows it.",
               ),
               option(
@@ -810,15 +777,12 @@ const HELP_ROOT = group(
               PROFILE_OPTION,
               JSON_OPTION,
             ],
-            notes: [
-              "`--sender-channel` only applies to channel inbox threads; account threads reply as the owner.",
-            ],
           },
         ),
         command(
-          "mark-seen",
+          "seen",
           "Mark one thread as seen.",
-          `${CLI_NAME} inbox mark-seen <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox seen <thread-id> [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [CHANNEL_TOKEN_OPTION, PROFILE_OPTION, JSON_OPTION],
           },

package/src/lib/human.ts

@@ -0,0 +1,134 @@
+export type FieldValue = string | number | boolean | null | undefined;
+
+export function formatEmpty(value: FieldValue): string {
+  if (value === null || value === undefined || value === "") {
+    return "-";
+  }
+
+  return String(value);
+}
+
+export function formatTimestamp(value?: string | null): string {
+  if (!value) {
+    return "-";
+  }
+
+  const timestamp = Date.parse(value);
+
+  if (Number.isNaN(timestamp)) {
+    return value;
+  }
+
+  return formatLocalTimestamp(new Date(timestamp));
+}
+
+export function shortId(id?: string | null): string {
+  if (!id) {
+    return "-";
+  }
+
+  return id.length > 12 ? `${id.slice(0, 8)}...` : id;
+}
+
+export function renderFields(fields: Array<[label: string, value: FieldValue]>): string {
+  const visibleFields = fields.filter(([, value]) => value !== undefined);
+
+  if (visibleFields.length === 0) {
+    return "";
+  }
+
+  const labelWidth = Math.max(...visibleFields.map(([label]) => label.length));
+
+  return visibleFields
+    .map(([label, value]) => `${label.padEnd(labelWidth)}  ${formatEmpty(value)}`)
+    .join("\n");
+}
+
+export function renderSection(title: string, body: string): string {
+  const trimmed = body.trimEnd();
+
+  if (!trimmed) {
+    return "";
+  }
+
+  return `${title}\n${trimmed}`;
+}
+
+export function renderBullets(items: string[]): string {
+  if (items.length === 0) {
+    return "-";
+  }
+
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+export function indent(text: string, spaces = 2): string {
+  const prefix = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => (line ? `${prefix}${line}` : ""))
+    .join("\n");
+}
+
+export function renderBodyBlock(body: string): string {
+  const normalized = body.replace(/\r\n/g, "\n").trimEnd();
+
+  if (!normalized) {
+    return indent("(empty)");
+  }
+
+  return indent(normalized);
+}
+
+export function renderPagination(nextCursor?: string | null): string {
+  return nextCursor ? `More results: --cursor ${nextCursor}` : "";
+}
+
+export function joinBlocks(blocks: Array<string | undefined | null | false>): string {
+  return blocks.filter(Boolean).join("\n\n");
+}
+
+export function renderTokenAction(input: {
+  title: string;
+  id?: string | null;
+  name?: string | null;
+  token?: string | null;
+  issuedAt?: string | null;
+  expiresAt?: string | null;
+}): string {
+  return joinBlocks([
+    input.title,
+    renderFields([
+      ["ID", input.id],
+      ["Name", input.name],
+      ["Token", input.token],
+      ["Issued", input.issuedAt ? formatTimestamp(input.issuedAt) : undefined],
+      ["Expires", input.expiresAt ? formatTimestamp(input.expiresAt) : undefined],
+    ]),
+  ]);
+}
+
+function formatLocalTimestamp(value: Date): string {
+  const year = value.getFullYear();
+  const month = padDatePart(value.getMonth() + 1);
+  const day = padDatePart(value.getDate());
+  const hours = padDatePart(value.getHours());
+  const minutes = padDatePart(value.getMinutes());
+  const seconds = padDatePart(value.getSeconds());
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} ${formatTimezoneOffset(value)}`;
+}
+
+function formatTimezoneOffset(value: Date): string {
+  const offsetMinutes = -value.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const absoluteMinutes = Math.abs(offsetMinutes);
+  const hours = padDatePart(Math.floor(absoluteMinutes / 60));
+  const minutes = padDatePart(absoluteMinutes % 60);
+
+  return `${sign}${hours}:${minutes}`;
+}
+
+function padDatePart(value: number): string {
+  return String(value).padStart(2, "0");
+}

package/src/types/api.ts

@@ -67,10 +67,38 @@ export interface PostAttributes {
 
 export type MailboxType = "account" | "channel";
 export type ThreadStatus = "pending" | "open" | "blocked";
+export type ThreadStatusFilter = ThreadStatus | "all";
+export type MailboxFilter = MailboxType | "all";
+
+export type InboxRecipient =
+  | { type: "user"; address: { kind: "email"; value: string } }
+  | { type: "user"; address: { kind: "handle"; value: string } }
+  | { type: "user"; address: { kind: "id"; value: string } }
+  | { type: "channel"; address: { kind: "id"; value: string } }
+  | {
+      type: "channel";
+      address: {
+        kind: "owner_handle_and_channel_name";
+        owner_handle: string;
+        channel_name: string;
+      };
+    };
+
+export interface InboxSender {
+  type: "channel";
+  address: {
+    kind: "id";
+    value: string;
+  };
+}
 
 export interface ThreadAttributes {
   mailbox_type: MailboxType;
   status: ThreadStatus;
+  participant_a_owner_id?: string | null;
+  participant_a_channel_id?: string | null;
+  participant_b_owner_id?: string | null;
+  participant_b_channel_id?: string | null;
   opened_at?: string | null;
   expires_at?: string | null;
   last_message_at?: string;
@@ -88,6 +116,9 @@ export interface ThreadAttributes {
 
 export interface MessageAttributes {
   body: string;
+  sender_owner_id?: string | null;
+  sender_channel_id?: string | null;
+  thread_id?: string | null;
   context_post_id?: string | null;
   inserted_at?: string;
 }