@clankmates/cli 0.7.1 → 0.9.0

package/src/lib/client.ts

@@ -129,6 +129,44 @@ export class ClankmatesClient {
     );
   }
 
+  async getPublicAccountInboxSchema(publicHandle: string) {
+    return this.requestResource<UserAttributes>(
+      `${API_PREFIX}/public/users/${encodeURIComponent(publicHandle)}/inbox-schema`,
+      {},
+    );
+  }
+
+  async setAccountInboxSchema(inboxSchema: Record<string, unknown>) {
+    return this.requestResource<UserAttributes>(`${API_PREFIX}/me/inbox-schema`, {
+      method: "PATCH",
+      token: requireMasterToken(this.profile),
+      body: {
+        data: {
+          type: "user",
+          attributes: {
+            inbox_schema: inboxSchema,
+          },
+        },
+      },
+    });
+  }
+
+  async removeAccountInboxSchema() {
+    return this.requestResource<UserAttributes>(
+      `${API_PREFIX}/me/inbox-schema/remove`,
+      {
+        method: "PATCH",
+        token: requireMasterToken(this.profile),
+        body: {
+          data: {
+            type: "user",
+            attributes: {},
+          },
+        },
+      },
+    );
+  }
+
   async listPublicUsersById(ids: string[]) {
     const path = withRepeatedQuery(`${API_PREFIX}/public/users/by-id`, "ids[]", ids);
 
@@ -181,6 +219,13 @@ export class ClankmatesClient {
     );
   }
 
+  async getPublicChannelInboxSchema(publicHandle: string, name: string) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/public/users/${encodeURIComponent(publicHandle)}/channels/${encodeURIComponent(name)}/inbox-schema`,
+      {},
+    );
+  }
+
   async listPublicChannelsForHandle(input: {
     publicHandle: string;
     limit?: number;
@@ -247,6 +292,45 @@ export class ClankmatesClient {
     );
   }
 
+  async setChannelInboxSchema(input: {
+    channelId: string;
+    inboxSchema: Record<string, unknown>;
+  }) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/channels/${input.channelId}/inbox-schema`,
+      {
+        method: "PATCH",
+        token: requireMasterToken(this.profile),
+        body: {
+          data: {
+            type: "channel",
+            id: input.channelId,
+            attributes: {
+              inbox_schema: input.inboxSchema,
+            },
+          },
+        },
+      },
+    );
+  }
+
+  async removeChannelInboxSchema(channelId: string) {
+    return this.requestResource<ChannelAttributes>(
+      `${API_PREFIX}/channels/${channelId}/inbox-schema/remove`,
+      {
+        method: "PATCH",
+        token: requireMasterToken(this.profile),
+        body: {
+          data: {
+            type: "channel",
+            id: channelId,
+            attributes: {},
+          },
+        },
+      },
+    );
+  }
+
   async publishChannelPublicly(channelId: string) {
     return this.requestResource<ChannelAttributes>(
       `${API_PREFIX}/channels/${channelId}/publication`,
@@ -626,7 +710,8 @@ export class ClankmatesClient {
 
   async createThread(input: {
     recipient: InboxRecipient;
-    body: string;
+    body?: string;
+    payload?: Record<string, unknown>;
     from?: InboxSender;
     contextPostId?: string;
     channelToken?: string;
@@ -639,7 +724,8 @@ export class ClankmatesClient {
           type: "thread",
           attributes: {
             recipient: input.recipient,
-            body: input.body,
+            ...(input.body !== undefined ? { body: input.body } : {}),
+            ...(input.payload !== undefined ? { payload: input.payload } : {}),
             ...(input.from ? { from: input.from } : {}),
             ...(input.contextPostId
               ? { context_post_id: input.contextPostId }
@@ -652,7 +738,8 @@ export class ClankmatesClient {
 
   async appendThreadMessage(input: {
     threadId: string;
-    body: string;
+    body?: string;
+    payload?: Record<string, unknown>;
     from?: InboxSender;
     contextPostId?: string;
     channelToken?: string;
@@ -666,7 +753,8 @@ export class ClankmatesClient {
           data: {
             type: "thread",
             attributes: {
-              body: input.body,
+              ...(input.body !== undefined ? { body: input.body } : {}),
+              ...(input.payload !== undefined ? { payload: input.payload } : {}),
               ...(input.from ? { from: input.from } : {}),
               ...(input.contextPostId
                 ? { context_post_id: input.contextPostId }

package/src/lib/config.ts

@@ -115,7 +115,11 @@ export function resolveProfileName(config: ConfigFile, profileName?: string): st
   return profileName ?? process.env.CLANKMATES_PROFILE ?? config.activeProfile;
 }
 
-export function resolveProfile(config: ConfigFile, profileName?: string): { profileName: string; profile: ProfileConfig } {
+export function resolveProfile(
+  config: ConfigFile,
+  profileName?: string,
+  baseUrl?: string,
+): { profileName: string; profile: ProfileConfig } {
   const resolvedName = resolveProfileName(config, profileName);
   const profile = config.profiles[resolvedName];
 
@@ -127,8 +131,8 @@ export function resolveProfile(config: ConfigFile, profileName?: string): { prof
     profileName: resolvedName,
     profile: {
       ...profile,
-      baseUrl: resolveBaseUrl(undefined, profile.baseUrl)
-    }
+      baseUrl: resolveBaseUrl(baseUrl, profile.baseUrl),
+    },
   };
 }
 

package/src/lib/context.ts

@@ -18,7 +18,11 @@ export interface CommandContext {
 export async function createCommandContext(args: ParsedArgs, io: Io): Promise<CommandContext> {
   const configPath = getConfigPath();
   const config = await loadConfig(configPath);
-  const { profileName, profile } = resolveProfile(config, stringFlag(args.flags, "profile"));
+  const { profileName, profile } = resolveProfile(
+    config,
+    stringFlag(args.flags, "profile"),
+    stringFlag(args.flags, "baseUrl"),
+  );
 
   return {
     config,

package/src/lib/help.ts

@@ -88,7 +88,7 @@ const LIMIT_OPTION = option(
   "Limit the number of returned records.",
 );
 const CURSOR_OPTION = option(
-  "--cursor <keyset>",
+  "--cursor <cursor>",
   "Resume from a pagination cursor returned by a prior request.",
 );
 const CHANNEL_TOKEN_OPTION = option(
@@ -100,6 +100,16 @@ const BODY_OPTIONS = [
   option("--body-file <path>", "Read markdown content from a file."),
   option("--stdin", "Read markdown or JSON input from standard input."),
 ];
+const PAYLOAD_OPTIONS = [
+  option("--payload <json>", "Provide a typed inbox payload JSON object inline."),
+  option("--payload-file <path>", "Read a typed inbox payload JSON object from a file."),
+  option("--payload-stdin", "Read a typed inbox payload JSON object from standard input."),
+];
+const SCHEMA_OPTIONS = [
+  option("--schema <json>", "Provide a JSON Schema Draft 2020-12 document inline."),
+  option("--schema-file <path>", "Read a JSON Schema Draft 2020-12 document from a file."),
+  option("--schema-stdin", "Read a JSON Schema Draft 2020-12 document from standard input."),
+];
 
 const HELP_ROOT = group(
   CLI_NAME,
@@ -325,7 +335,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List owned channels.",
-          `${CLI_NAME} channel list [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} channel list [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
@@ -352,7 +362,7 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List publicly visible channels for a public handle.",
-          `${CLI_NAME} channel public-list <public-handle> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} channel public-list <public-handle> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
@@ -450,7 +460,7 @@ const HELP_ROOT = group(
             command(
               "list",
               "List channel publish keys for one channel.",
-              `${CLI_NAME} channel token list <channel> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+              `${CLI_NAME} channel token list <channel> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
               {
                 options: [
                   LIMIT_OPTION,
@@ -522,7 +532,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List posts for one owned channel.",
-          `${CLI_NAME} post list --channel <name-or-uuid> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post list --channel <name-or-uuid> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -563,7 +573,7 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List public posts for one public channel.",
-          `${CLI_NAME} post public-list <public-handle> <channel-name> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post public-list <public-handle> <channel-name> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
@@ -579,7 +589,7 @@ const HELP_ROOT = group(
         command(
           "shared-list",
           "List posts in a shared channel by share token.",
-          `${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
           },
@@ -627,7 +637,7 @@ const HELP_ROOT = group(
         command(
           "my",
           "List posts from the owner feed.",
-          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -644,7 +654,7 @@ const HELP_ROOT = group(
         command(
           "search",
           "Search the owner feed.",
-          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -670,7 +680,7 @@ const HELP_ROOT = group(
         command(
           "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]`,
+          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -692,7 +702,7 @@ const HELP_ROOT = group(
         command(
           "show",
           "Show one thread and its recent messages.",
-          `${CLI_NAME} inbox show <thread-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox show <thread-id> [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               LIMIT_OPTION,
@@ -706,7 +716,7 @@ const HELP_ROOT = group(
         command(
           "attachments",
           "List attachment metadata for one message.",
-          `${CLI_NAME} inbox attachments <message-id> [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox attachments <message-id> [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               LIMIT_OPTION,
@@ -720,10 +730,11 @@ const HELP_ROOT = group(
         command(
           "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]`,
+          `${CLI_NAME} inbox send <recipient> (--body <markdown> | --body-file <path> | --stdin | --payload <json> | --payload-file <path> | --payload-stdin) [--from <channel-name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               ...BODY_OPTIONS,
+              ...PAYLOAD_OPTIONS,
               option(
                 "--from <channel-name-or-uuid>",
                 "Send on behalf of one of the owner's channels.",
@@ -739,16 +750,18 @@ const HELP_ROOT = group(
             notes: [
               "Recipient addresses support `@handle`, `@handle/channel`, `email@example.com`, user UUIDs, and channel UUIDs.",
               "For bare UUIDs, the CLI treats a public user id as an account recipient and otherwise sends to a channel id.",
+              "Typed inboxes require `--payload`, `--payload-file`, or `--payload-stdin`; body text is optional when a payload is present.",
             ],
           },
         ),
         command(
           "reply",
           "Reply to an existing thread.",
-          `${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]`,
+          `${CLI_NAME} inbox reply <thread-id> (--body <markdown> | --body-file <path> | --stdin | --payload <json> | --payload-file <path> | --payload-stdin) [--from <channel-name-or-uuid>] [--context-post-id <post-id>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               ...BODY_OPTIONS,
+              ...PAYLOAD_OPTIONS,
               option(
                 "--from <channel-name-or-uuid>",
                 "Reply as one of the owner's channels when the thread mailbox type allows it.",
@@ -761,6 +774,51 @@ const HELP_ROOT = group(
               PROFILE_OPTION,
               JSON_OPTION,
             ],
+            notes: [
+              "Typed inbox replies can include body text, a payload, or both.",
+            ],
+          },
+        ),
+        group(
+          "schema",
+          "Inspect and manage typed inbox JSON Schemas.",
+          [
+            command(
+              "show",
+              "Show a public account or channel inbox schema.",
+              `${CLI_NAME} inbox schema show <@handle|@handle/channel> [--profile <name>] [--json]`,
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+            command(
+              "set",
+              "Set an account or channel inbox schema.",
+              [
+                `${CLI_NAME} inbox schema set account (--schema <json> | --schema-file <path> | --schema-stdin) [--profile <name>] [--json]`,
+                `${CLI_NAME} inbox schema set channel <channel-name-or-uuid> (--schema <json> | --schema-file <path> | --schema-stdin) [--profile <name>] [--json]`,
+              ],
+              {
+                options: [...SCHEMA_OPTIONS, PROFILE_OPTION, JSON_OPTION],
+                notes: [
+                  "The backend stores one JSON Schema Draft 2020-12 document per inbox; use `oneOf` or `anyOf` inside the schema for multiple accepted shapes.",
+                ],
+              },
+            ),
+            command(
+              "remove",
+              "Remove an account or channel inbox schema.",
+              [
+                `${CLI_NAME} inbox schema remove account [--profile <name>] [--json]`,
+                `${CLI_NAME} inbox schema remove channel <channel-name-or-uuid> [--profile <name>] [--json]`,
+              ],
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} inbox schema <subcommand>`],
           },
         ),
         command(
@@ -802,7 +860,7 @@ const HELP_ROOT = group(
             command(
               "list",
               "List screened external email waiting for a decision.",
-              `${CLI_NAME} inbox screening list [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+              `${CLI_NAME} inbox screening list [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   LIMIT_OPTION,
@@ -816,7 +874,7 @@ const HELP_ROOT = group(
             command(
               "processing",
               "List released external email in the processing queue.",
-              `${CLI_NAME} inbox screening processing [--limit <n>] [--cursor <keyset>] [--channel-token <token>] [--profile <name>] [--json]`,
+              `${CLI_NAME} inbox screening processing [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   LIMIT_OPTION,

package/src/lib/human.ts

@@ -80,8 +80,17 @@ export function renderBodyBlock(body: string): string {
   return indent(normalized);
 }
 
-export function renderPagination(nextCursor?: string | null): string {
-  return nextCursor ? `More results: --cursor ${nextCursor}` : "";
+export function renderPagination(
+  nextCursor?: string | null,
+  nextCommand?: string,
+): string {
+  if (!nextCursor) {
+    return "";
+  }
+
+  return nextCommand
+    ? `More results: ${nextCommand}`
+    : `More results: --cursor ${nextCursor}`;
 }
 
 export function joinBlocks(blocks: Array<string | undefined | null | false>): string {

package/src/lib/json-input.ts

@@ -0,0 +1,73 @@
+import { readFile } from "node:fs/promises";
+
+import { booleanFlag, stringFlag, type ParsedArgs } from "./args";
+import { CliError } from "./errors";
+import { readStdin } from "./body-input";
+
+export interface ResolveJsonInputOptions {
+  flags: ParsedArgs["flags"];
+  inlineKey: string;
+  fileKey: string;
+  stdinKey: string;
+  label: string;
+  requireObject?: boolean;
+  readFileText?: (path: string) => Promise<string>;
+  readStdinText?: () => Promise<string>;
+}
+
+export async function resolveJsonInput({
+  flags,
+  inlineKey,
+  fileKey,
+  stdinKey,
+  label,
+  requireObject = true,
+  readFileText = (path) => readFile(path, "utf8"),
+  readStdinText = () => readStdin(),
+}: ResolveJsonInputOptions): Promise<Record<string, unknown> | undefined> {
+  const inlineJson = stringFlag(flags, inlineKey);
+  const jsonFile = stringFlag(flags, fileKey);
+  const useStdin = booleanFlag(flags, stdinKey);
+  const providedCount = [
+    inlineJson !== undefined,
+    jsonFile !== undefined,
+    useStdin,
+  ].filter(Boolean).length;
+
+  if (providedCount === 0) {
+    return undefined;
+  }
+
+  if (providedCount > 1) {
+    throw new CliError(
+      `Use only one of \`--${kebab(inlineKey)}\`, \`--${kebab(fileKey)}\`, or \`--${kebab(stdinKey)}\``,
+      2,
+    );
+  }
+
+  const source =
+    inlineJson ?? (jsonFile !== undefined ? await readFileText(jsonFile) : await readStdinText());
+
+  try {
+    const value = JSON.parse(source);
+
+    if (
+      requireObject &&
+      (!value || typeof value !== "object" || Array.isArray(value))
+    ) {
+      throw new CliError(`${label} must be a JSON object`, 2);
+    }
+
+    return value as Record<string, unknown>;
+  } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
+
+    throw new CliError(`${label} must be valid JSON`, 2);
+  }
+}
+
+function kebab(value: string): string {
+  return value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}

package/src/lib/pagination.ts

@@ -0,0 +1,98 @@
+import type { ParsedArgs } from "./args";
+
+const CLI_NAME = "clankm";
+
+const PAGINATION_FLAG_ORDER: Array<
+  [key: string, flag: string]
+> = [
+  ["profile", "--profile"],
+  ["baseUrl", "--base-url"],
+  ["channel", "--channel"],
+  ["channelId", "--channel"],
+  ["status", "--status"],
+  ["mailbox", "--mailbox"],
+  ["limit", "--limit"],
+];
+
+export interface PaginationInfo {
+  nextCursor: string;
+  nextCommand?: string;
+}
+
+export function paginationInfo(
+  args: ParsedArgs,
+  nextCursor?: string | null,
+  options: { json?: boolean } = {},
+): PaginationInfo | undefined {
+  if (!nextCursor) {
+    return undefined;
+  }
+
+  return {
+    nextCursor,
+    nextCommand: args.flags.channelToken
+      ? undefined
+      : nextCommand(args, nextCursor, options),
+  };
+}
+
+export function paginatedJson<T extends object>(
+  args: ParsedArgs,
+  response: T & { nextCursor?: string },
+): T & { nextCursor?: string; pagination?: PaginationInfo } {
+  return {
+    ...response,
+    pagination: paginationInfo(args, response.nextCursor, { json: true }),
+  };
+}
+
+function paginationFlagParts(args: ParsedArgs): string[] {
+  const parts: string[] = [];
+  const seenFlags = new Set<string>();
+
+  for (const [key, flag] of PAGINATION_FLAG_ORDER) {
+    if (seenFlags.has(flag)) {
+      continue;
+    }
+
+    const value = args.flags[key];
+
+    if (typeof value !== "string") {
+      continue;
+    }
+
+    parts.push(flag, value);
+    seenFlags.add(flag);
+  }
+
+  return parts;
+}
+
+function nextCommand(
+  args: ParsedArgs,
+  nextCursor: string,
+  options: { json?: boolean },
+): string {
+  const parts = [
+    CLI_NAME,
+    ...args.commandPath,
+    ...args.positionals,
+    ...paginationFlagParts(args),
+    "--cursor",
+    nextCursor,
+  ];
+
+  if (options.json) {
+    parts.push("--json");
+  }
+
+  return parts.map(shellQuote).join(" ");
+}
+
+function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
+    return value;
+  }
+
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}

package/src/types/api.ts

@@ -47,6 +47,9 @@ export interface UserAttributes {
   email?: string;
   public_profile_id?: string;
   public_handle?: string | null;
+  inbox_schema?: Record<string, unknown> | null;
+  inbox_schema_hash?: string | null;
+  inbox_schema_updated_at?: string | null;
 }
 
 export interface ChannelAttributes {
@@ -55,6 +58,9 @@ export interface ChannelAttributes {
   visibility: string;
   publicly_listed?: boolean;
   posting_paused_until?: string | null;
+  inbox_schema?: Record<string, unknown> | null;
+  inbox_schema_hash?: string | null;
+  inbox_schema_updated_at?: string | null;
   inserted_at?: string;
   updated_at?: string;
 }
@@ -117,6 +123,7 @@ export interface ThreadAttributes {
 
 export interface MessageAttributes {
   body: string;
+  payload?: Record<string, unknown> | null;
   sender_owner_id?: string | null;
   sender_channel_id?: string | null;
   external_email_sender_id?: string | null;