@clankmates/cli 0.10.3 → 0.11.1

package/src/commands/inbox.ts

@@ -1,3 +1,17 @@
+import {
+  assertSinceFlags,
+  authenticatedActorKey,
+  cacheFlags,
+  cacheResult,
+  changeResponseMeta,
+  inboxMessagesScope,
+  inboxThreadsScope,
+  prepareCachePlan,
+  saveCacheTimestamp,
+  type CachePlan,
+  type CacheResult,
+  type CacheScope,
+} from "../lib/cache";
 import {
   booleanFlag,
   integerFlag,
@@ -21,10 +35,12 @@ import { resolveJsonInput } from "../lib/json-input";
 import { printJson, printValue, type Io } from "../lib/output";
 import { paginatedJson, paginationInfo } from "../lib/pagination";
 import type {
+  ChangeCheckResponse,
   ExternalEmailAcceptance,
   ExternalEmailIntakeAttributes,
   InboxRecipient,
   InboxSender,
+  LatestFirstOrder,
   MailboxFilter,
   MessageAttachmentAttributes,
   MessageAttributes,
@@ -40,28 +56,73 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
   switch (subcommand) {
     case "list": {
       const channelToken = stringFlag(args.flags, "channelToken");
+      assertSinceFlags(args);
+      const status = parseStatusFilter(stringFlag(args.flags, "status"));
+      const mailbox = parseMailboxFilter(stringFlag(args.flags, "mailbox"));
+      const cacheScope = await maybeInboxThreadsScope(
+        args,
+        context,
+        channelToken,
+        status,
+        mailbox,
+      );
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.listInboxThreads({
-        status: parseStatusFilter(stringFlag(args.flags, "status")),
-        mailbox: parseMailboxFilter(stringFlag(args.flags, "mailbox")),
+        status,
+        mailbox,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: resolvedSince(args, cachePlan),
         channelToken,
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
 
-      await printThreadCollection(args, context, io, response, channelToken);
+      await printThreadCollection(
+        args,
+        context,
+        io,
+        response,
+        channelToken,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
     case "show": {
       const threadId = requiredPositional(args.positionals, 1, "Missing thread id");
       const channelToken = stringFlag(args.flags, "channelToken");
+      assertSinceFlags(args);
+      const cacheScope = await maybeInboxMessagesScope(
+        args,
+        context,
+        channelToken,
+        threadId,
+      );
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const thread = await context.client.getThread(threadId, channelToken);
       const messages = await context.client.listMessagesForThread({
         threadId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: resolvedSince(args, cachePlan),
         channelToken,
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        messages.meta,
+        messages.nextCursor === undefined,
+      );
+      const cache = cacheResult(cachePlan, savedServerTimestamp);
       const ownerIds = ownerIdsForThreadDisplay(thread, messages.items);
       const publicUsers =
         context.outputMode === "json" || ownerIds.length === 0
@@ -78,12 +139,55 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
               thread,
               messages: messages.items,
               nextCursor: messages.nextCursor,
+              meta: messages.meta,
+              ...(cache ? { cache } : {}),
             })
-          : renderThreadWithMessages(args, thread, messages, publicUsers),
+          : renderThreadWithMessages(args, thread, messages, publicUsers, cache),
       );
       return;
     }
 
+    case "changes": {
+      const channelToken = stringFlag(args.flags, "channelToken");
+      assertSinceFlags(args);
+      const status = parseStatusFilter(stringFlag(args.flags, "status"));
+      const mailbox = parseMailboxFilter(stringFlag(args.flags, "mailbox"));
+      const cacheScope = await maybeInboxThreadsScope(
+        args,
+        context,
+        channelToken,
+        status,
+        mailbox,
+      );
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
+      const response = await context.client.checkInboxThreadChanges({
+        since: requiredSince(args, cachePlan, "inbox thread"),
+        status,
+        mailbox,
+        channelToken,
+      });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        changeResponseMeta(response),
+        response.has_updates === false,
+      );
+
+      printChangeCheckResponse(
+        context,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
+      return;
+    }
+
+    case "messages": {
+      await runInboxMessagesCommand(context, args, io);
+      return;
+    }
+
     case "attachments": {
       const messageId = requiredPositional(args.positionals, 1, "Missing message id");
       const response = await context.client.listMessageAttachments({
@@ -601,6 +705,118 @@ function parseMailboxFilter(value: string | undefined): MailboxFilter | undefine
   throw new CliError("--mailbox must be one of: account, channel, all", 2);
 }
 
+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);
+}
+
+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,
+    );
+  }
+
+  if (!since) {
+    throw new CliError("Missing `--since`", 2);
+  }
+
+  return since;
+}
+
+async function runInboxMessagesCommand(
+  context: CommandContext,
+  args: ParsedArgs,
+  io: Io,
+): Promise<void> {
+  const subcommand = args.positionals[1];
+
+  switch (subcommand) {
+    case "changes": {
+      assertSinceFlags(args);
+      const threadId = requiredPositional(args.positionals, 2, "Missing thread id");
+      const channelToken = stringFlag(args.flags, "channelToken");
+      const cacheScope = await maybeInboxMessagesScope(
+        args,
+        context,
+        channelToken,
+        threadId,
+      );
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
+      const response = await context.client.checkThreadMessageChanges({
+        threadId,
+        since: requiredSince(args, cachePlan, "inbox message"),
+        channelToken,
+      });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        changeResponseMeta(response),
+        response.has_updates === false,
+      );
+
+      printChangeCheckResponse(
+        context,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown inbox messages subcommand", 2);
+  }
+}
+
+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),
+        ]),
+  );
+}
+
 async function parseRecipient(
   context: CommandContext,
   value: string,
@@ -706,8 +922,10 @@ async function printThreadCollection(
   response: {
     items: Array<{ id: string; attributes: ThreadAttributes }>;
     nextCursor?: string;
+    meta?: Record<string, unknown>;
   },
   channelToken?: string,
+  cache?: CacheResult,
 ): Promise<void> {
   if (context.outputMode === "json") {
     printJson(
@@ -715,6 +933,8 @@ async function printThreadCollection(
       paginatedJson(args, {
         items: response.items,
         nextCursor: response.nextCursor,
+        meta: response.meta,
+        ...(cache ? { cache } : {}),
       }),
     );
     return Promise.resolve();
@@ -752,6 +972,8 @@ async function printThreadCollection(
   if (message) {
     io.stdout(message);
   }
+
+  printCacheNote(io, cache);
 }
 
 function renderThreadWithMessages(
@@ -762,6 +984,7 @@ function renderThreadWithMessages(
     nextCursor?: string;
   },
   publicUsers: Map<string, string>,
+  cache?: CacheResult,
 ): string {
   const attrs = thread.attributes;
   const messageBlocks =
@@ -833,6 +1056,7 @@ function renderThreadWithMessages(
     ),
     renderSection("Messages", messageBlocks),
     renderPagination(pagination?.nextCursor, pagination?.nextCommand),
+    renderCacheNote(cache),
   ]);
 }
 
@@ -886,6 +1110,108 @@ function printSchemaResource(
   );
 }
 
+async function maybePrepareCachePlan(
+  args: ParsedArgs,
+  context: CommandContext,
+  scope: CacheScope | undefined,
+): Promise<CachePlan | undefined> {
+  return cacheFlags(args).sinceCache && scope
+    ? prepareCachePlan(context, scope)
+    : undefined;
+}
+
+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;
+}
+
+async function maybeInboxThreadsScope(
+  args: ParsedArgs,
+  context: CommandContext,
+  channelToken: string | undefined,
+  status: ThreadStatusFilter | undefined,
+  mailbox: MailboxFilter | undefined,
+): Promise<CacheScope | undefined> {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return inboxThreadsScope({
+    context,
+    actorKey: await authenticatedActorKey(context, channelToken),
+    status,
+    mailbox,
+  });
+}
+
+async function maybeInboxMessagesScope(
+  args: ParsedArgs,
+  context: CommandContext,
+  channelToken: string | undefined,
+  threadId: string,
+): Promise<CacheScope | undefined> {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return inboxMessagesScope({
+    context,
+    actorKey: await authenticatedActorKey(context, channelToken),
+    threadId,
+  });
+}
+
+function resolvedSince(
+  args: ParsedArgs,
+  cachePlan: CachePlan | undefined,
+): string | undefined {
+  return stringFlag(args.flags, "since") ?? cachePlan?.previousServerTimestamp;
+}
+
+function printCacheNote(io: Io, cache: CacheResult | undefined): void {
+  const note = renderCacheNote(cache);
+
+  if (note) {
+    io.stdout(note);
+  }
+}
+
+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("; ")}.`;
+}
+
+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],
+  ];
+}
+
 function renderSchemaResource(
   resource: {
     id: string;

package/src/commands/post.ts

@@ -1,3 +1,17 @@
+import {
+  assertSinceFlags,
+  authenticatedActorKey,
+  cacheFlags,
+  cacheResult,
+  ownedPostsScope,
+  prepareCachePlan,
+  publicPostsScope,
+  saveCacheTimestamp,
+  sharedPostsScope,
+  type CachePlan,
+  type CacheResult,
+  type CacheScope,
+} from "../lib/cache";
 import {
   booleanFlag,
   integerFlag,
@@ -18,7 +32,7 @@ import {
 } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
 import { paginatedJson, paginationInfo } from "../lib/pagination";
-import type { PostAttributes, ShareTokenResponse } from "../types/api";
+import type { LatestFirstOrder, PostAttributes, ShareTokenResponse } from "../types/api";
 
 export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -50,46 +64,109 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
     }
 
     case "list": {
+      assertSinceFlags(args);
+      const channelId = await context.client.resolveChannelId(
+        requiredChannelFlag(args.flags),
+      );
+      const cacheScope = await maybeOwnedPostsScope(args, context, channelId);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.listChannelPosts({
-        channelId: await context.client.resolveChannelId(
-          requiredChannelFlag(args.flags),
-        ),
+        channelId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: resolvedSince(args, cachePlan),
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
 
-      printPostCollection(args, context.outputMode, io, response);
+      printPostCollection(
+        args,
+        context.outputMode,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
     case "public-list": {
+      assertSinceFlags(args);
+      const publicHandle = requiredPositional(
+        args.positionals,
+        1,
+        "Missing public handle",
+      );
+      const channelName = requiredPositional(
+        args.positionals,
+        2,
+        "Missing public channel name",
+      );
+      const cacheScope = maybePublicPostsScope(
+        args,
+        context,
+        publicHandle,
+        channelName,
+      );
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.listPublicChannelPosts({
-        publicHandle: requiredPositional(
-          args.positionals,
-          1,
-          "Missing public handle",
-        ),
-        channelName: requiredPositional(
-          args.positionals,
-          2,
-          "Missing public channel name",
-        ),
+        publicHandle,
+        channelName,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: resolvedSince(args, cachePlan),
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
 
-      printPostCollection(args, context.outputMode, io, response);
+      printPostCollection(
+        args,
+        context.outputMode,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
     case "shared-list": {
+      assertSinceFlags(args);
+      const token = requiredPositional(args.positionals, 1, "Missing share token");
+      const cacheScope = maybeSharedPostsScope(args, context, token);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.listSharedChannelPosts({
-        token: requiredPositional(args.positionals, 1, "Missing share token"),
+        token,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: resolvedSince(args, cachePlan),
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
 
-      printPostCollection(args, context.outputMode, io, response);
+      printPostCollection(
+        args,
+        context.outputMode,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
@@ -226,7 +303,9 @@ function printPostCollection(
   response: {
     items: Array<{ id: string; attributes: PostAttributes }>;
     nextCursor?: string;
+    meta?: Record<string, unknown>;
   },
+  cache?: CacheResult,
 ): void {
   if (outputMode === "json") {
     printJson(
@@ -234,6 +313,8 @@ function printPostCollection(
       paginatedJson(args, {
         items: response.items,
         nextCursor: response.nextCursor,
+        meta: response.meta,
+        ...(cache ? { cache } : {}),
       }),
     );
     return;
@@ -259,6 +340,107 @@ function printPostCollection(
   if (message) {
     io.stdout(message);
   }
+
+  printCacheNote(io, cache);
+}
+
+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);
+}
+
+async function maybePrepareCachePlan(
+  args: ParsedArgs,
+  context: Awaited<ReturnType<typeof createCommandContext>>,
+  scope: CacheScope | undefined,
+): Promise<CachePlan | undefined> {
+  return cacheFlags(args).sinceCache && scope
+    ? prepareCachePlan(context, scope)
+    : undefined;
+}
+
+async function maybeSaveCacheTimestamp(
+  args: ParsedArgs,
+  context: Awaited<ReturnType<typeof createCommandContext>>,
+  scope: CacheScope | undefined,
+  meta: Record<string, unknown> | undefined,
+  shouldSave: boolean,
+): Promise<string | undefined> {
+  return cacheFlags(args).saveCache && scope && shouldSave
+    ? saveCacheTimestamp(context, scope, meta)
+    : undefined;
+}
+
+async function maybeOwnedPostsScope(
+  args: ParsedArgs,
+  context: Awaited<ReturnType<typeof createCommandContext>>,
+  channelId: string,
+): Promise<CacheScope | undefined> {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return ownedPostsScope({
+    context,
+    actorKey: await authenticatedActorKey(context),
+    channelId,
+  });
+}
+
+function maybePublicPostsScope(
+  args: ParsedArgs,
+  context: Awaited<ReturnType<typeof createCommandContext>>,
+  publicHandle: string,
+  channelName: string,
+): CacheScope | undefined {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return publicPostsScope({ context, publicHandle, channelName });
+}
+
+function maybeSharedPostsScope(
+  args: ParsedArgs,
+  context: Awaited<ReturnType<typeof createCommandContext>>,
+  shareToken: string,
+): CacheScope | undefined {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return sharedPostsScope({ context, shareToken });
+}
+
+function resolvedSince(
+  args: ParsedArgs,
+  cachePlan: CachePlan | undefined,
+): string | undefined {
+  return stringFlag(args.flags, "since") ?? cachePlan?.previousServerTimestamp;
+}
+
+function printCacheNote(io: Io, cache: CacheResult | undefined): void {
+  if (!cache) {
+    return;
+  }
+
+  const details = [
+    cache.previousServerTimestamp
+      ? `used ${cache.previousServerTimestamp}`
+      : cache.hit
+        ? "used cache"
+        : "no cached timestamp",
+    cache.savedServerTimestamp ? `saved ${cache.savedServerTimestamp}` : undefined,
+  ].filter(Boolean);
+
+  io.stdout(`Cache: ${details.join("; ")}.`);
 }
 
 function renderPostDetail(