@clankmates/cli 0.11.0 → 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,
@@ -42,32 +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: stringFlag(args.flags, "since"),
+        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: stringFlag(args.flags, "since"),
+        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
@@ -85,22 +140,46 @@ 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 cacheScope = await maybeInboxThreadsScope(
+        args,
+        context,
+        channelToken,
+        status,
+        mailbox,
+      );
+      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,
         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;
     }
 
@@ -638,9 +717,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 +755,35 @@ 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"),
+        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 +796,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 +812,7 @@ function printChangeCheckResponse(
               ? undefined
               : `${response.recommended_poll_after_ms}ms`,
           ],
+          ...cacheFields(cache),
         ]),
   );
 }
@@ -803,6 +925,7 @@ async function printThreadCollection(
     meta?: Record<string, unknown>;
   },
   channelToken?: string,
+  cache?: CacheResult,
 ): Promise<void> {
   if (context.outputMode === "json") {
     printJson(
@@ -811,6 +934,7 @@ async function printThreadCollection(
         items: response.items,
         nextCursor: response.nextCursor,
         meta: response.meta,
+        ...(cache ? { cache } : {}),
       }),
     );
     return Promise.resolve();
@@ -848,6 +972,8 @@ async function printThreadCollection(
   if (message) {
     io.stdout(message);
   }
+
+  printCacheNote(io, cache);
 }
 
 function renderThreadWithMessages(
@@ -858,6 +984,7 @@ function renderThreadWithMessages(
     nextCursor?: string;
   },
   publicUsers: Map<string, string>,
+  cache?: CacheResult,
 ): string {
   const attrs = thread.attributes;
   const messageBlocks =
@@ -929,6 +1056,7 @@ function renderThreadWithMessages(
     ),
     renderSection("Messages", messageBlocks),
     renderPagination(pagination?.nextCursor, pagination?.nextCommand),
+    renderCacheNote(cache),
   ]);
 }
 
@@ -982,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,
@@ -50,52 +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: stringFlag(args.flags, "since"),
+        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: stringFlag(args.flags, "since"),
+        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: stringFlag(args.flags, "since"),
+        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;
     }
 
@@ -234,6 +305,7 @@ function printPostCollection(
     nextCursor?: string;
     meta?: Record<string, unknown>;
   },
+  cache?: CacheResult,
 ): void {
   if (outputMode === "json") {
     printJson(
@@ -242,6 +314,7 @@ function printPostCollection(
         items: response.items,
         nextCursor: response.nextCursor,
         meta: response.meta,
+        ...(cache ? { cache } : {}),
       }),
     );
     return;
@@ -267,6 +340,8 @@ function printPostCollection(
   if (message) {
     io.stdout(message);
   }
+
+  printCacheNote(io, cache);
 }
 
 function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | undefined {
@@ -281,6 +356,93 @@ function parseLatestFirstOrder(value: string | undefined): LatestFirstOrder | un
   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(
   post: { id: string; attributes: PostAttributes },
   options: { title?: string; channelId?: string } = {},

package/src/lib/args.ts

@@ -51,6 +51,10 @@ const CLI_OPTIONS = {
   cursor: { type: "string" },
   order: { type: "string" },
   since: { type: "string" },
+  sinceCache: { type: "boolean" },
+  "since-cache": { type: "boolean" },
+  saveCache: { type: "boolean" },
+  "save-cache": { type: "boolean" },
   status: { type: "string" },
   mailbox: { type: "string" },
 } as const;