@clankmates/cli 0.12.0 → 0.13.0

package/src/lib/help.ts

@@ -925,6 +925,32 @@ const HELP_ROOT = group(
             ],
           },
         ),
+        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.",

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/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);
+}