@clankmates/cli 0.11.1 → 0.13.0

package/src/lib/help.ts

@@ -91,6 +91,10 @@ const CURSOR_OPTION = option(
   "--cursor <cursor>",
   "Resume from a pagination cursor returned by a prior request.",
 );
+const BEFORE_OPTION = option(
+  "--before <timestamp>",
+  "Only return records inserted or active before this server timestamp.",
+);
 const ORDER_OPTION = option(
   "--order <latest|oldest>",
   "Set result order. Defaults to latest.",
@@ -111,6 +115,22 @@ const CHANNEL_TOKEN_OPTION = option(
   "--channel-token <token>",
   "Act with an explicit channel token instead of stored owner credentials.",
 );
+const INBOX_SEARCH_OPTIONS = [
+  option(
+    "--participant <@handle|@handle/channel>",
+    "Filter inbox threads by a visible participant.",
+  ),
+  option(
+    "--participant-scope <account|owner>",
+    "Choose how bare account handles are matched. Defaults to account.",
+  ),
+  option("--query <text>", "Filter inbox results by visible message body text."),
+  option("--has-attachment", "Only include threads or messages with attachments."),
+];
+const MESSAGE_SEARCH_OPTIONS = [
+  option("--query <text>", "Filter messages by body text."),
+  option("--has-attachment", "Only include messages with attachments."),
+];
 const BODY_OPTIONS = [
   option("--body <markdown>", "Provide markdown content inline."),
   option("--body-file <path>", "Read markdown content from a file."),
@@ -635,7 +655,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List posts for one owned channel.",
-          `${CLI_NAME} post list --channel <name-or-uuid> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post list --channel <name-or-uuid> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -644,6 +664,7 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -680,11 +701,12 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List public posts for one public channel.",
-          `${CLI_NAME} post public-list <public-handle> <channel-name> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post public-list <public-handle> <channel-name> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -705,11 +727,12 @@ const HELP_ROOT = group(
         command(
           "shared-list",
           "List posts in a shared channel by share token.",
-          `${CLI_NAME} post shared-list <share-token> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post shared-list <share-token> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -762,7 +785,7 @@ const HELP_ROOT = group(
         command(
           "my",
           "List posts from the owner feed.",
-          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -771,6 +794,7 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -783,7 +807,7 @@ const HELP_ROOT = group(
         command(
           "search",
           "Search the owner feed.",
-          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -792,6 +816,7 @@ const HELP_ROOT = group(
               ),
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -831,7 +856,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List inbox threads.",
-          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--participant <@handle|@handle/channel>] [--participant-scope <account|owner>] [--query <text>] [--has-attachment] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -842,8 +867,10 @@ const HELP_ROOT = group(
                 "--mailbox <account|channel|all>",
                 "Filter by mailbox type.",
               ),
+              ...INBOX_SEARCH_OPTIONS,
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -857,11 +884,13 @@ const HELP_ROOT = group(
         command(
           "show",
           "Show one thread and its recent messages.",
-          `${CLI_NAME} inbox show <thread-id> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox show <thread-id> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--query <text>] [--has-attachment] [--save-cache] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               ORDER_OPTION,
               SINCE_OPTION,
+              BEFORE_OPTION,
+              ...MESSAGE_SEARCH_OPTIONS,
               SINCE_CACHE_OPTION,
               SAVE_CACHE_OPTION,
               LIMIT_OPTION,
@@ -875,7 +904,7 @@ const HELP_ROOT = group(
         command(
           "changes",
           "Check whether inbox threads have updates newer than a server timestamp.",
-          `${CLI_NAME} inbox changes (--since <server-time>|--since-cache) [--save-cache] [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${CLI_NAME} inbox changes (--since <server-time>|--since-cache) [--save-cache] [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--participant <@handle|@handle/channel>] [--participant-scope <account|owner>] [--query <text>] [--has-attachment] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               SINCE_OPTION,
@@ -889,12 +918,39 @@ const HELP_ROOT = group(
                 "--mailbox <account|channel|all>",
                 "Filter by mailbox type.",
               ),
+              ...INBOX_SEARCH_OPTIONS,
               CHANNEL_TOKEN_OPTION,
               PROFILE_OPTION,
               JSON_OPTION,
             ],
           },
         ),
+        group(
+          "watch",
+          "Stream inbox changes as JSONL records.",
+          [
+            command(
+              "messages",
+              "Watch one thread and emit each newly visible message as one JSONL line.",
+              `${CLI_NAME} inbox watch messages <thread-id> [--once] [--since <server-time>|--since-cache] [--query <text>] [--has-attachment] [--before <timestamp>] [--limit <n>] [--channel-token <token>] [--profile <name>]`,
+              {
+                options: [
+                  option("--once", "Run one watch cycle and exit."),
+                  SINCE_OPTION,
+                  SINCE_CACHE_OPTION,
+                  ...MESSAGE_SEARCH_OPTIONS,
+                  BEFORE_OPTION,
+                  LIMIT_OPTION,
+                  CHANNEL_TOKEN_OPTION,
+                  PROFILE_OPTION,
+                ],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} inbox watch <subcommand>`],
+          },
+        ),
         group(
           "messages",
           "Check thread message updates.",
@@ -902,12 +958,13 @@ const HELP_ROOT = group(
             command(
               "changes",
               "Check whether one thread has messages newer than a server timestamp.",
-              `${CLI_NAME} inbox messages changes <thread-id> (--since <server-time>|--since-cache) [--save-cache] [--channel-token <token>] [--profile <name>] [--json]`,
+              `${CLI_NAME} inbox messages changes <thread-id> (--since <server-time>|--since-cache) [--save-cache] [--query <text>] [--has-attachment] [--channel-token <token>] [--profile <name>] [--json]`,
               {
                 options: [
                   SINCE_OPTION,
                   SINCE_CACHE_OPTION,
                   SAVE_CACHE_OPTION,
+                  ...MESSAGE_SEARCH_OPTIONS,
                   CHANNEL_TOKEN_OPTION,
                   PROFILE_OPTION,
                   JSON_OPTION,

package/src/lib/json_api.ts

@@ -1,5 +1,5 @@
 import { CliError } from "./errors";
-import type { JsonApiDocument, JsonApiResource } from "../types/api";
+import type { JsonApiResource } from "../types/api";
 
 export interface JsonApiCollectionResult<TAttributes extends object> {
   items: Array<JsonApiResource<TAttributes>>;
@@ -8,12 +8,18 @@ export interface JsonApiCollectionResult<TAttributes extends object> {
   meta?: Record<string, unknown>;
 }
 
+interface JsonApiDocumentShape {
+  data: unknown;
+  links?: unknown;
+  meta?: unknown;
+}
+
 export function expectResource<TAttributes extends object>(
   payload: unknown
 ): JsonApiResource<TAttributes> {
-  const document = payload as JsonApiDocument<TAttributes>;
+  const document = asJsonApiDocument(payload);
 
-  if (!document || Array.isArray(document.data) || typeof document.data !== "object") {
+  if (!isJsonApiResource<TAttributes>(document.data)) {
     throw new CliError("Expected a JSON:API resource object in response");
   }
 
@@ -23,20 +29,79 @@ export function expectResource<TAttributes extends object>(
 export function expectCollection<TAttributes extends object>(
   payload: unknown
 ): JsonApiCollectionResult<TAttributes> {
-  const document = payload as JsonApiDocument<TAttributes>;
+  const document = asJsonApiDocument(payload);
 
-  if (!document || !Array.isArray(document.data)) {
+  if (!Array.isArray(document.data)) {
     throw new CliError("Expected a JSON:API collection in response");
   }
 
+  const items = document.data.filter(isJsonApiResource<TAttributes>);
+
+  if (items.length !== document.data.length) {
+    throw new CliError("Expected a JSON:API collection in response");
+  }
+
+  return {
+    items,
+    nextCursor: extractCursor(linkValue(document.links, "next")),
+    prevCursor: extractCursor(linkValue(document.links, "prev")),
+    meta: isRecord(document.meta) ? document.meta : undefined
+  };
+}
+
+function asJsonApiDocument(
+  payload: unknown,
+): JsonApiDocumentShape {
+  if (!isRecord(payload)) {
+    throw new CliError("Expected a JSON:API document in response");
+  }
+
+  if (!("data" in payload)) {
+    throw new CliError("Expected a JSON:API document in response");
+  }
+
   return {
-    items: document.data,
-    nextCursor: extractCursor(document.links?.next),
-    prevCursor: extractCursor(document.links?.prev),
-    meta: document.meta
+    data: payload.data,
+    links: payload.links,
+    meta: payload.meta,
   };
 }
 
+function isJsonApiResource<TAttributes extends object>(
+  value: unknown,
+): value is JsonApiResource<TAttributes> {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  return (
+    typeof value.id === "string" &&
+    typeof value.type === "string" &&
+    isRecord(value.attributes)
+  );
+}
+
+function linkValue(
+  links: unknown,
+  key: string,
+): string | null | undefined {
+  if (!isRecord(links)) {
+    return undefined;
+  }
+
+  const value = links[key];
+
+  if (typeof value === "string" || value === null) {
+    return value;
+  }
+
+  return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function extractCursor(link: string | null | undefined): string | undefined {
   if (!link) {
     return undefined;

package/src/lib/pagination.ts

@@ -11,14 +11,19 @@ const PAGINATION_FLAG_ORDER: Array<
   ["channelId", "--channel"],
   ["status", "--status"],
   ["mailbox", "--mailbox"],
+  ["participant", "--participant"],
+  ["participantScope", "--participant-scope"],
   ["order", "--order"],
   ["since", "--since"],
+  ["before", "--before"],
+  ["query", "--query"],
   ["limit", "--limit"],
 ];
 
 const PAGINATION_BOOLEAN_FLAGS: Array<[key: string, flag: string]> = [
   ["sinceCache", "--since-cache"],
   ["saveCache", "--save-cache"],
+  ["hasAttachment", "--has-attachment"],
 ];
 
 export interface PaginationInfo {

package/src/lib/polling.ts

@@ -0,0 +1,146 @@
+import {
+  cacheFlags,
+  prepareCachePlan,
+  saveCacheTimestamp,
+  type CachePlan,
+  type CacheResult,
+  type CacheScope,
+} from "./cache";
+import { stringFlag, type ParsedArgs } from "./args";
+import type { CommandContext } from "./context";
+import { CliError } from "./errors";
+import { formatTimestamp, renderFields } from "./human";
+import { printValue, type Io } from "./output";
+import type { ChangeCheckResponse, LatestFirstOrder } from "../types/api";
+
+export 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);
+}
+
+export 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,
+    );
+  }
+
+  throw new CliError("Missing `--since`", 2);
+}
+
+export function resolvedSince(
+  args: ParsedArgs,
+  cachePlan: CachePlan | undefined,
+): string | undefined {
+  return stringFlag(args.flags, "since") ?? cachePlan?.previousServerTimestamp;
+}
+
+export async function maybePrepareCachePlan(
+  args: ParsedArgs,
+  context: CommandContext,
+  scope: CacheScope | undefined,
+): Promise<CachePlan | undefined> {
+  return cacheFlags(args).sinceCache && scope
+    ? prepareCachePlan(context, scope)
+    : undefined;
+}
+
+export 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;
+}
+
+export 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("; ")}.`;
+}
+
+export function printCacheNote(io: Io, cache: CacheResult | undefined): void {
+  const note = renderCacheNote(cache);
+
+  if (note) {
+    io.stdout(note);
+  }
+}
+
+export 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],
+  ];
+}
+
+export 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),
+        ]),
+  );
+}

package/src/lib/post-output.ts

@@ -0,0 +1,55 @@
+import type { CacheResult } from "./cache";
+import { renderPagination } from "./human";
+import { printJson, printValue, type Io } from "./output";
+import { paginatedJson, paginationInfo } from "./pagination";
+import { printCacheNote } from "./polling";
+import type { ParsedArgs } from "./args";
+import type { OutputMode, PostAttributes } from "../types/api";
+
+export function printPostCollection(
+  args: ParsedArgs,
+  outputMode: OutputMode,
+  io: Io,
+  response: {
+    items: Array<{ id: string; attributes: PostAttributes }>;
+    nextCursor?: string;
+    meta?: Record<string, unknown>;
+  },
+  cache?: CacheResult,
+): void {
+  if (outputMode === "json") {
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+        meta: response.meta,
+        ...(cache ? { cache } : {}),
+      }),
+    );
+    return;
+  }
+
+  printValue(
+    io,
+    outputMode,
+    response.items.map((item) => ({
+      id: item.id,
+      source: item.attributes.source,
+      date: item.attributes.updated_at ?? item.attributes.inserted_at ?? "",
+      body: item.attributes.body,
+    })),
+  );
+
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
+  );
+
+  if (message) {
+    io.stdout(message);
+  }
+
+  printCacheNote(io, cache);
+}

package/src/types/api.ts

@@ -84,6 +84,7 @@ export type MailboxType = "account" | "channel";
 export type ThreadStatus = "pending" | "open" | "blocked";
 export type ThreadStatusFilter = ThreadStatus | "all";
 export type MailboxFilter = MailboxType | "all";
+export type ParticipantScope = "account" | "owner";
 export type LatestFirstOrder = "latest" | "oldest";
 
 export interface ChangeCheckResponse {