@clankmates/cli 0.10.3 → 0.11.1

package/src/lib/help.ts

@@ -91,6 +91,22 @@ const CURSOR_OPTION = option(
   "--cursor <cursor>",
   "Resume from a pagination cursor returned by a prior request.",
 );
+const ORDER_OPTION = option(
+  "--order <latest|oldest>",
+  "Set result order. Defaults to latest.",
+);
+const SINCE_OPTION = option(
+  "--since <server-time>",
+  "Filter to records newer than a server timestamp watermark.",
+);
+const SINCE_CACHE_OPTION = option(
+  "--since-cache",
+  "Use the locally cached server timestamp for this read scope.",
+);
+const SAVE_CACHE_OPTION = option(
+  "--save-cache",
+  "Save the response server timestamp for this read scope.",
+);
 const CHANNEL_TOKEN_OPTION = option(
   "--channel-token <token>",
   "Act with an explicit channel token instead of stored owner credentials.",
@@ -342,6 +358,46 @@ const HELP_ROOT = group(
         usage: [`${CLI_NAME} setup <subcommand>`],
       },
     ),
+    group(
+      "cache",
+      "Inspect and clear local sync timestamp cache state.",
+      [
+        command(
+          "status",
+          "Show cached server timestamp scopes for the selected profile.",
+          `${CLI_NAME} cache status [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "clear",
+          "Clear cached server timestamp scopes.",
+          `${CLI_NAME} cache clear [--scope <scope-key>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--scope <scope-key>", "Clear exactly one cached scope."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "path",
+          "Print the SQLite cache database path.",
+          `${CLI_NAME} cache path [--json]`,
+          {
+            options: [JSON_OPTION],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} cache <subcommand>`],
+        notes: [
+          "The cache stores server timestamp watermarks only; it does not store message bodies, post bodies, or tokens.",
+        ],
+      },
+    ),
     group(
       "user",
       "Read public account data.",
@@ -579,13 +635,17 @@ const HELP_ROOT = group(
         command(
           "list",
           "List posts for one owned channel.",
-          `${CLI_NAME} post list --channel <name-or-uuid> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${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]`,
           {
             options: [
               option(
                 "--channel <name-or-uuid>",
                 "Select the channel whose posts should be listed.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -620,9 +680,18 @@ const HELP_ROOT = group(
         command(
           "public-list",
           "List public posts for one public channel.",
-          `${CLI_NAME} post public-list <public-handle> <channel-name> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${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]`,
           {
-            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+            options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
           },
         ),
         command(
@@ -636,9 +705,18 @@ const HELP_ROOT = group(
         command(
           "shared-list",
           "List posts in a shared channel by share token.",
-          `${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${CLI_NAME} post shared-list <share-token> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
-            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+            options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
           },
         ),
         command(
@@ -684,13 +762,17 @@ const HELP_ROOT = group(
         command(
           "my",
           "List posts from the owner feed.",
-          `${CLI_NAME} feed my [--channel <name-or-uuid>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${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]`,
           {
             options: [
               option(
                 "--channel <name-or-uuid>",
                 "Filter the feed to one owned channel.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -701,13 +783,17 @@ const HELP_ROOT = group(
         command(
           "search",
           "Search the owner feed.",
-          `${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          `${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]`,
           {
             options: [
               option(
                 "--channel <name-or-uuid>",
                 "Filter the search to one owned channel.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -715,6 +801,24 @@ const HELP_ROOT = group(
             ],
           },
         ),
+        command(
+          "changes",
+          "Check whether the owner feed has updates newer than a server timestamp.",
+          `${CLI_NAME} feed changes (--since <server-time>|--since-cache) [--save-cache] [--channel <name-or-uuid>] [--profile <name>] [--json]`,
+          {
+            options: [
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              option(
+                "--channel <name-or-uuid>",
+                "Check updates within one owned channel.",
+              ),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
       ],
       {
         usage: [`${CLI_NAME} feed <subcommand>`],
@@ -727,7 +831,7 @@ const HELP_ROOT = group(
         command(
           "list",
           "List inbox threads.",
-          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${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]`,
           {
             options: [
               option(
@@ -738,6 +842,10 @@ const HELP_ROOT = group(
                 "--mailbox <account|channel|all>",
                 "Filter by mailbox type.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -749,9 +857,13 @@ const HELP_ROOT = group(
         command(
           "show",
           "Show one thread and its recent messages.",
-          `${CLI_NAME} inbox show <thread-id> [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
+          `${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]`,
           {
             options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -760,6 +872,53 @@ 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]`,
+          {
+            options: [
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              option(
+                "--status <pending|open|blocked|all>",
+                "Filter by thread status.",
+              ),
+              option(
+                "--mailbox <account|channel|all>",
+                "Filter by mailbox type.",
+              ),
+              CHANNEL_TOKEN_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        group(
+          "messages",
+          "Check thread message updates.",
+          [
+            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]`,
+              {
+                options: [
+                  SINCE_OPTION,
+                  SINCE_CACHE_OPTION,
+                  SAVE_CACHE_OPTION,
+                  CHANNEL_TOKEN_OPTION,
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} inbox messages <subcommand>`],
+          },
+        ),
         command(
           "attachments",
           "List attachment metadata for one message.",

package/src/lib/pagination.ts

@@ -11,9 +11,16 @@ const PAGINATION_FLAG_ORDER: Array<
   ["channelId", "--channel"],
   ["status", "--status"],
   ["mailbox", "--mailbox"],
+  ["order", "--order"],
+  ["since", "--since"],
   ["limit", "--limit"],
 ];
 
+const PAGINATION_BOOLEAN_FLAGS: Array<[key: string, flag: string]> = [
+  ["sinceCache", "--since-cache"],
+  ["saveCache", "--save-cache"],
+];
+
 export interface PaginationInfo {
   nextCursor: string;
   nextCommand?: string;
@@ -65,6 +72,12 @@ function paginationFlagParts(args: ParsedArgs): string[] {
     seenFlags.add(flag);
   }
 
+  for (const [key, flag] of PAGINATION_BOOLEAN_FLAGS) {
+    if (args.flags[key] === true) {
+      parts.push(flag);
+    }
+  }
+
   return parts;
 }
 

package/src/lib/paths.ts

@@ -16,3 +16,29 @@ export function getConfigPath(): string {
 
   return path.join(os.homedir(), ".config", "clankmates", "config.json");
 }
+
+export function getCachePath(): string {
+  const explicit = process.env.CLANKMATES_CACHE_PATH;
+
+  if (explicit) {
+    return explicit;
+  }
+
+  const xdg = process.env.XDG_CACHE_HOME;
+
+  if (xdg) {
+    return path.join(xdg, "clankmates", "clankm-cache.sqlite");
+  }
+
+  if (process.platform === "darwin") {
+    return path.join(
+      os.homedir(),
+      "Library",
+      "Caches",
+      "clankmates",
+      "clankm-cache.sqlite",
+    );
+  }
+
+  return path.join(os.homedir(), ".cache", "clankmates", "clankm-cache.sqlite");
+}

package/src/types/api.ts

@@ -84,6 +84,13 @@ export type MailboxType = "account" | "channel";
 export type ThreadStatus = "pending" | "open" | "blocked";
 export type ThreadStatusFilter = ThreadStatus | "all";
 export type MailboxFilter = MailboxType | "all";
+export type LatestFirstOrder = "latest" | "oldest";
+
+export interface ChangeCheckResponse {
+  has_updates: boolean;
+  server_time?: string;
+  recommended_poll_after_ms?: number;
+}
 
 export type InboxRecipient =
   | { type: "user"; address: { kind: "handle"; value: string } }