@clankmates/cli 0.11.0 → 0.12.0

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,
@@ -30,6 +44,7 @@ import type {
   MailboxFilter,
   MessageAttachmentAttributes,
   MessageAttributes,
+  ParticipantScope,
   ThreadAttributes,
   ThreadStatusFilter,
   WhoamiActor,
@@ -42,32 +57,85 @@ 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 participantScope = parseParticipantScope(
+        stringFlag(args.flags, "participantScope"),
+      );
+      const cacheScope = await maybeInboxThreadsScope(
+        args,
+        context,
+        channelToken,
+        status,
+        mailbox,
+        participantScope,
+      );
+      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"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
-        since: stringFlag(args.flags, "since"),
+        since: resolvedSince(args, cachePlan),
+        participant: stringFlag(args.flags, "participant"),
+        participantScope,
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
         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"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
-        since: stringFlag(args.flags, "since"),
+        since: resolvedSince(args, cachePlan),
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
         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
@@ -85,22 +153,54 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
               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 participantScope = parseParticipantScope(
+        stringFlag(args.flags, "participantScope"),
+      );
+      const cacheScope = await maybeInboxThreadsScope(
+        args,
+        context,
+        channelToken,
+        status,
+        mailbox,
+        participantScope,
+      );
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
       const response = await context.client.checkInboxThreadChanges({
-        since: requiredSince(args),
-        status: parseStatusFilter(stringFlag(args.flags, "status")),
-        mailbox: parseMailboxFilter(stringFlag(args.flags, "mailbox")),
+        since: requiredSince(args, cachePlan, "inbox thread"),
+        status,
+        mailbox,
+        participant: stringFlag(args.flags, "participant"),
+        participantScope,
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
         channelToken,
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        changeResponseMeta(response),
+        response.has_updates === false,
+      );
 
-      printChangeCheckResponse(context, io, response);
+      printChangeCheckResponse(
+        context,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
@@ -626,6 +726,18 @@ function parseMailboxFilter(value: string | undefined): MailboxFilter | undefine
   throw new CliError("--mailbox must be one of: account, channel, all", 2);
 }
 
+function parseParticipantScope(value: string | undefined): ParticipantScope | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "account" || value === "owner") {
+    return value;
+  }
+
+  throw new CliError("--participant-scope must be one of: account, owner", 2);
+}
+
 function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | undefined {
   if (!value) {
     return undefined;
@@ -638,9 +750,28 @@ function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | un
   throw new CliError("--order must be one of: latest, oldest", 2);
 }
 
-function requiredSince(args: ParsedArgs): string {
+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);
   }
@@ -657,13 +788,37 @@ async function runInboxMessagesCommand(
 
   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: requiredPositional(args.positionals, 2, "Missing thread id"),
-        since: requiredSince(args),
-        channelToken: stringFlag(args.flags, "channelToken"),
+        threadId,
+        since: requiredSince(args, cachePlan, "inbox message"),
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
+        channelToken,
       });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        changeResponseMeta(response),
+        response.has_updates === false,
+      );
 
-      printChangeCheckResponse(context, io, response);
+      printChangeCheckResponse(
+        context,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
       return;
     }
 
@@ -676,12 +831,13 @@ function printChangeCheckResponse(
   context: CommandContext,
   io: Io,
   response: ChangeCheckResponse,
+  cache?: CacheResult,
 ): void {
   printValue(
     io,
     context.outputMode,
     context.outputMode === "json"
-      ? response
+      ? { ...response, ...(cache ? { cache } : {}) }
       : renderFields([
           ["Has updates", response.has_updates ? "yes" : "no"],
           ["Server time", formatTimestamp(response.server_time)],
@@ -691,6 +847,7 @@ function printChangeCheckResponse(
               ? undefined
               : `${response.recommended_poll_after_ms}ms`,
           ],
+          ...cacheFields(cache),
         ]),
   );
 }
@@ -803,6 +960,7 @@ async function printThreadCollection(
     meta?: Record<string, unknown>;
   },
   channelToken?: string,
+  cache?: CacheResult,
 ): Promise<void> {
   if (context.outputMode === "json") {
     printJson(
@@ -811,6 +969,7 @@ async function printThreadCollection(
         items: response.items,
         nextCursor: response.nextCursor,
         meta: response.meta,
+        ...(cache ? { cache } : {}),
       }),
     );
     return Promise.resolve();
@@ -848,6 +1007,8 @@ async function printThreadCollection(
   if (message) {
     io.stdout(message);
   }
+
+  printCacheNote(io, cache);
 }
 
 function renderThreadWithMessages(
@@ -858,6 +1019,7 @@ function renderThreadWithMessages(
     nextCursor?: string;
   },
   publicUsers: Map<string, string>,
+  cache?: CacheResult,
 ): string {
   const attrs = thread.attributes;
   const messageBlocks =
@@ -929,6 +1091,7 @@ function renderThreadWithMessages(
     ),
     renderSection("Messages", messageBlocks),
     renderPagination(pagination?.nextCursor, pagination?.nextCommand),
+    renderCacheNote(cache),
   ]);
 }
 
@@ -982,6 +1145,117 @@ 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,
+  participantScope: ParticipantScope | undefined,
+): Promise<CacheScope | undefined> {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return inboxThreadsScope({
+    context,
+    actorKey: await authenticatedActorKey(context, channelToken),
+    status,
+    mailbox,
+    participant: stringFlag(args.flags, "participant"),
+    participantScope,
+    query: stringFlag(args.flags, "query"),
+    hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
+    before: stringFlag(args.flags, "before"),
+  });
+}
+
+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,
+    query: stringFlag(args.flags, "query"),
+    hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
+    before: stringFlag(args.flags, "before"),
+  });
+}
+
+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;