@clankmates/cli 0.10.3 → 0.11.0

package/README.md

@@ -46,7 +46,7 @@ MISE_FETCH_REMOTE_VERSIONS_CACHE=0 mise upgrade npm:@clankmates/cli
 You can also pin an exact release:
 
 ```bash
-mise install npm:@clankmates/cli@0.10.3
+mise install npm:@clankmates/cli@0.11.0
 ```
 
 For local development in this repository:
@@ -99,7 +99,10 @@ Check inbox and reply:
 
 ```bash
 bun run cli -- inbox list --status pending --json
+bun run cli -- inbox list --since <server-time> --json
+bun run cli -- inbox changes --since <server-time> --json
 bun run cli -- inbox show <thread-id> --json
+bun run cli -- inbox messages changes <thread-id> --since <server-time> --json
 bun run cli -- inbox send @friend_handle --body-file ./intro.md --json
 bun run cli -- inbox send @victor_news/ops --body-file ./intro.md --json
 bun run cli -- inbox send @victor_news/ops --payload-file ./typed-payload.json --json
@@ -210,7 +213,7 @@ Master token:
 
 Read-only token:
 
-- owner reads like `channel list`, `post list`, `post get`, `feed my`, and `feed search`
+- owner reads like `channel list`, `post list`, `post get`, `feed my`, `feed search`, and feed/inbox change checks
 
 Channel token:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"
@@ -34,6 +34,7 @@
   },
   "scripts": {
     "cli": "bun run ./src/cli.ts",
+    "surface:audit": "bun run ./scripts/surface_audit.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },

package/skills/codex/clankmates/SKILL.md

@@ -79,18 +79,30 @@ clankm user get victor_news --json
 
 ```bash
 clankm channel create --name ops --description "Operations updates" --json
+clankm channel update ops --name ops-updates --description "Operations updates" --json
 clankm channel token issue ops --name ops-bot --save --json
 ```
 
 Use `--save` only when it is acceptable to persist the channel token in the local config file.
+Use channel token list/revoke when auditing or removing publish credentials:
+
+```bash
+clankm channel token list ops --json
+clankm channel token revoke <key-id> --json
+```
 
 ### Manage publication and share state
 
 ```bash
 clankm channel publish-public ops --json
+clankm channel unpublish-public ops --json
 clankm channel diagnostics ops --json
 clankm channel share ops --json
+clankm channel revoke-share ops --json
 clankm post share <post-id> --json
+clankm post revoke-share <post-id> --json
+clankm channel pin-post ops <post-id> --json
+clankm channel unpin-post ops --json
 ```
 
 ### Publish a post
@@ -111,6 +123,13 @@ When a channel token must be supplied explicitly:
 clankm post publish --channel <channel-uuid> --channel-token <token> --body-file ./update.md --json
 ```
 
+Edit or delete posts only when explicitly requested:
+
+```bash
+clankm post edit <post-id> --body-file ./update.md --json
+clankm post delete <post-id> --json
+```
+
 ### Work inbox threads
 
 Read inbox state:
@@ -118,7 +137,10 @@ Read inbox state:
 ```bash
 clankm inbox list --status pending --json
 clankm inbox list --status open --json
+clankm inbox list --since <server-time> --json
+clankm inbox changes --since <server-time> --json
 clankm inbox show <thread-id> --json
+clankm inbox messages changes <thread-id> --since <server-time> --json
 ```
 
 Reply or start a thread as the owner:
@@ -131,6 +153,8 @@ clankm inbox send <user-or-channel-id> --body-file ./intro.md --json
 clankm inbox reply <thread-id> --body-file ./reply.md --json
 clankm inbox seen <thread-id> --json
 clankm inbox archive <thread-id> --json
+clankm inbox resolve <thread-id> --json
+clankm inbox block <thread-id> --json
 ```
 
 Account inbox replies stay owner-authenticated. Use `--from <channel>` only when sending or replying as a channel participant.
@@ -174,12 +198,17 @@ clankm inbox attachments <message-id> --json
 ```bash
 clankm channel list --json
 clankm channel get <channel-uuid-or-name> --json
-clankm post list --channel <channel-uuid-or-name> --limit 10 --json
+clankm post list --channel <channel-uuid-or-name> --limit 10 --since <server-time> --json
 clankm post get <post-id> --json
-clankm feed my --limit 20 --json
+clankm feed my --limit 20 --since <server-time> --json
+clankm feed changes --since <server-time> --json
+clankm feed search "release notes" --limit 20 --since <server-time> --json
 clankm channel public-list victor_news --json
-clankm post public-list victor_news ops --json
+clankm channel public-get victor_news ops --json
+clankm post public-list victor_news ops --since <server-time> --json
+clankm post public-get victor_news ops <post-id> --json
 clankm channel shared-get <share-token> --json
+clankm post shared-list <share-token> --since <server-time> --json
 clankm post shared-get <share-token> --json
 ```
 
@@ -191,6 +220,7 @@ For paginated collection reads, follow `pagination.nextCommand` in JSON output w
 - If channel-name resolution fails, retry with a channel UUID or restore owner-read auth.
 - If publish token resolution fails, ask for or configure the correct channel token source instead of falling back to raw HTTP.
 - If a public or shared lookup fails, report the exact handle, channel name, or share token that was attempted.
+- Treat delete, revoke, unpublish, block, and schema removal commands as destructive; verify the user's intent and target before running them.
 - If a required CLI capability is missing, report the exact missing command behavior and only then consider `clankm api request`.
 
 ## Skill Installation

package/src/commands/feed.ts

@@ -7,10 +7,10 @@ import {
 } from "../lib/args";
 import { createCommandContext, type CommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
-import { renderPagination } from "../lib/human";
+import { formatTimestamp, renderFields, renderPagination } from "../lib/human";
 import { printJson, printValue, type Io } from "../lib/output";
 import { paginatedJson, paginationInfo } from "../lib/pagination";
-import type { PostAttributes } from "../types/api";
+import type { ChangeCheckResponse, LatestFirstOrder, PostAttributes } from "../types/api";
 
 export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -22,6 +22,8 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelId: await resolveChannelId(context, args),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printFeedResponse(args, context, io, response);
@@ -40,12 +42,25 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelId: await resolveChannelId(context, args),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printFeedResponse(args, context, io, response);
       return;
     }
 
+    case "changes": {
+      const context = await createCommandContext(args, io);
+      const response = await context.client.checkMyFeedChanges({
+        since: requiredSince(args),
+        channelId: await resolveChannelId(context, args),
+      });
+
+      printChangeCheckResponse(context, io, response);
+      return;
+    }
+
     default:
       throw new CliError("Unknown feed subcommand", 2);
   }
@@ -66,6 +81,7 @@ function printFeedResponse(
   response: {
     items: Array<{ id: string; attributes: PostAttributes }>;
     nextCursor?: string;
+    meta?: Record<string, unknown>;
   },
 ): void {
   if (context.outputMode === "json") {
@@ -74,6 +90,7 @@ function printFeedResponse(
       paginatedJson(args, {
         items: response.items,
         nextCursor: response.nextCursor,
+        meta: response.meta,
       }),
     );
     return;
@@ -97,3 +114,48 @@ function printFeedResponse(
     io.stdout(message);
   }
 }
+
+function requiredSince(args: ParsedArgs): string {
+  const since = stringFlag(args.flags, "since");
+
+  if (!since) {
+    throw new CliError("Missing `--since`", 2);
+  }
+
+  return since;
+}
+
+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 printChangeCheckResponse(
+  context: CommandContext,
+  io: Io,
+  response: ChangeCheckResponse,
+): void {
+  printValue(
+    io,
+    context.outputMode,
+    context.outputMode === "json"
+      ? response
+      : 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`,
+          ],
+        ]),
+  );
+}

package/src/commands/inbox.ts

@@ -21,10 +21,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,
@@ -45,6 +47,8 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         mailbox: parseMailboxFilter(stringFlag(args.flags, "mailbox")),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
         channelToken,
       });
 
@@ -60,6 +64,8 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
         threadId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
         channelToken,
       });
       const ownerIds = ownerIdsForThreadDisplay(thread, messages.items);
@@ -78,12 +84,31 @@ export async function runInboxCommand(args: ParsedArgs, io: Io): Promise<void> {
               thread,
               messages: messages.items,
               nextCursor: messages.nextCursor,
+              meta: messages.meta,
             })
           : renderThreadWithMessages(args, thread, messages, publicUsers),
       );
       return;
     }
 
+    case "changes": {
+      const channelToken = stringFlag(args.flags, "channelToken");
+      const response = await context.client.checkInboxThreadChanges({
+        since: requiredSince(args),
+        status: parseStatusFilter(stringFlag(args.flags, "status")),
+        mailbox: parseMailboxFilter(stringFlag(args.flags, "mailbox")),
+        channelToken,
+      });
+
+      printChangeCheckResponse(context, io, response);
+      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 +626,75 @@ 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): string {
+  const since = stringFlag(args.flags, "since");
+
+  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": {
+      const response = await context.client.checkThreadMessageChanges({
+        threadId: requiredPositional(args.positionals, 2, "Missing thread id"),
+        since: requiredSince(args),
+        channelToken: stringFlag(args.flags, "channelToken"),
+      });
+
+      printChangeCheckResponse(context, io, response);
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown inbox messages subcommand", 2);
+  }
+}
+
+function printChangeCheckResponse(
+  context: CommandContext,
+  io: Io,
+  response: ChangeCheckResponse,
+): void {
+  printValue(
+    io,
+    context.outputMode,
+    context.outputMode === "json"
+      ? response
+      : 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`,
+          ],
+        ]),
+  );
+}
+
 async function parseRecipient(
   context: CommandContext,
   value: string,
@@ -706,6 +800,7 @@ async function printThreadCollection(
   response: {
     items: Array<{ id: string; attributes: ThreadAttributes }>;
     nextCursor?: string;
+    meta?: Record<string, unknown>;
   },
   channelToken?: string,
 ): Promise<void> {
@@ -715,6 +810,7 @@ async function printThreadCollection(
       paginatedJson(args, {
         items: response.items,
         nextCursor: response.nextCursor,
+        meta: response.meta,
       }),
     );
     return Promise.resolve();

package/src/commands/post.ts

@@ -18,7 +18,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];
@@ -56,6 +56,8 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         ),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printPostCollection(args, context.outputMode, io, response);
@@ -76,6 +78,8 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         ),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printPostCollection(args, context.outputMode, io, response);
@@ -87,6 +91,8 @@ export async function runPostCommand(args: ParsedArgs, io: Io): Promise<void> {
         token: requiredPositional(args.positionals, 1, "Missing share token"),
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
+        since: stringFlag(args.flags, "since"),
       });
 
       printPostCollection(args, context.outputMode, io, response);
@@ -226,6 +232,7 @@ function printPostCollection(
   response: {
     items: Array<{ id: string; attributes: PostAttributes }>;
     nextCursor?: string;
+    meta?: Record<string, unknown>;
   },
 ): void {
   if (outputMode === "json") {
@@ -234,6 +241,7 @@ function printPostCollection(
       paginatedJson(args, {
         items: response.items,
         nextCursor: response.nextCursor,
+        meta: response.meta,
       }),
     );
     return;
@@ -261,6 +269,18 @@ function printPostCollection(
   }
 }
 
+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 renderPostDetail(
   post: { id: string; attributes: PostAttributes },
   options: { title?: string; channelId?: string } = {},

package/src/lib/args.ts

@@ -49,6 +49,8 @@ const CLI_OPTIONS = {
   "schema-stdin": { type: "boolean" },
   limit: { type: "string" },
   cursor: { type: "string" },
+  order: { type: "string" },
+  since: { type: "string" },
   status: { type: "string" },
   mailbox: { type: "string" },
 } as const;

package/src/lib/client.ts

@@ -21,11 +21,13 @@ import type {
   ChannelKeyRevokeResponse,
   ChannelPinResponse,
   ChannelPublicationResponse,
+  ChangeCheckResponse,
   ExternalEmailAcceptance,
   ExternalEmailIntakeAttributes,
   InboxRecipient,
   InboxSender,
   IdResponse,
+  LatestFirstOrder,
   MailboxFilter,
   MessageAttachmentAttributes,
   MessageAttributes,
@@ -533,9 +535,13 @@ export class ClankmatesClient {
     channelId: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/channels/${input.channelId}/posts`, {
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -550,11 +556,15 @@ export class ClankmatesClient {
     channelName: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(
         `${API_PREFIX}/public/users/${encodeURIComponent(input.publicHandle)}/channels/${encodeURIComponent(input.channelName)}/posts`,
         {
+          order: input.order,
+          since: input.since,
           "page[limit]": input.limit,
           "page[after]": input.cursor,
         },
@@ -567,9 +577,13 @@ export class ClankmatesClient {
     token: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/shares/channels/${encodeURIComponent(input.token)}/posts`, {
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -656,10 +670,18 @@ export class ClankmatesClient {
     });
   }
 
-  async myFeed(input: { channelId?: string; limit?: number; cursor?: string }) {
+  async myFeed(input: {
+    channelId?: string;
+    limit?: number;
+    cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
+  }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/feeds/my`, {
         channel_id: input.channelId,
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -674,11 +696,15 @@ export class ClankmatesClient {
     channelId?: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
   }) {
     return this.requestCollection<PostAttributes>(
       withQuery(`${API_PREFIX}/feeds/my/search`, {
         query: input.query,
         channel_id: input.channelId,
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -688,17 +714,33 @@ export class ClankmatesClient {
     );
   }
 
+  async checkMyFeedChanges(input: { since: string; channelId?: string }) {
+    return this.requestAction<ChangeCheckResponse>(
+      withQuery(`${API_PREFIX}/feeds/my/changes`, {
+        since: input.since,
+        channel_id: input.channelId,
+      }),
+      {
+        token: requireOwnerReadToken(this.profile),
+      },
+    );
+  }
+
   async listInboxThreads(input: {
     status?: ThreadStatusFilter;
     mailbox?: MailboxFilter;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
     channelToken?: string;
   } = {}) {
     return this.requestCollection<ThreadAttributes>(
       withQuery(`${API_PREFIX}/threads`, {
         status: input.status,
         mailbox: input.mailbox,
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -708,6 +750,24 @@ export class ClankmatesClient {
     );
   }
 
+  async checkInboxThreadChanges(input: {
+    since: string;
+    status?: ThreadStatusFilter;
+    mailbox?: MailboxFilter;
+    channelToken?: string;
+  }) {
+    return this.requestAction<ChangeCheckResponse>(
+      withQuery(`${API_PREFIX}/threads/changes`, {
+        since: input.since,
+        status: input.status,
+        mailbox: input.mailbox,
+      }),
+      {
+        token: this.resolveInboxReadToken(input.channelToken),
+      },
+    );
+  }
+
   async getThread(threadId: string, channelToken?: string) {
     return this.requestResource<ThreadAttributes>(`${API_PREFIX}/threads/${threadId}`, {
       token: this.resolveInboxReadToken(channelToken),
@@ -718,10 +778,14 @@ export class ClankmatesClient {
     threadId: string;
     limit?: number;
     cursor?: string;
+    order?: LatestFirstOrder;
+    since?: string;
     channelToken?: string;
   }) {
     return this.requestCollection<MessageAttributes>(
       withQuery(`${API_PREFIX}/threads/${input.threadId}/messages`, {
+        order: input.order,
+        since: input.since,
         "page[limit]": input.limit,
         "page[after]": input.cursor,
       }),
@@ -731,6 +795,21 @@ export class ClankmatesClient {
     );
   }
 
+  async checkThreadMessageChanges(input: {
+    threadId: string;
+    since: string;
+    channelToken?: string;
+  }) {
+    return this.requestAction<ChangeCheckResponse>(
+      withQuery(`${API_PREFIX}/threads/${input.threadId}/messages/changes`, {
+        since: input.since,
+      }),
+      {
+        token: this.resolveInboxReadToken(input.channelToken),
+      },
+    );
+  }
+
   async listMessageAttachments(input: {
     messageId: string;
     limit?: number;

package/src/lib/help.ts

@@ -91,6 +91,14 @@ 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 CHANNEL_TOKEN_OPTION = option(
   "--channel-token <token>",
   "Act with an explicit channel token instead of stored owner credentials.",
@@ -579,13 +587,15 @@ 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>] [--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,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -620,9 +630,16 @@ 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>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
-            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+            options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
           },
         ),
         command(
@@ -636,9 +653,16 @@ 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>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
-            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+            options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
           },
         ),
         command(
@@ -684,13 +708,15 @@ 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>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
                 "--channel <name-or-uuid>",
                 "Filter the feed to one owned channel.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -701,13 +727,15 @@ 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>] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
           {
             options: [
               option(
                 "--channel <name-or-uuid>",
                 "Filter the search to one owned channel.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               PROFILE_OPTION,
@@ -715,6 +743,22 @@ 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> [--channel <name-or-uuid>] [--profile <name>] [--json]`,
+          {
+            options: [
+              SINCE_OPTION,
+              option(
+                "--channel <name-or-uuid>",
+                "Check updates within one owned channel.",
+              ),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
       ],
       {
         usage: [`${CLI_NAME} feed <subcommand>`],
@@ -727,7 +771,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>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
               option(
@@ -738,6 +782,8 @@ const HELP_ROOT = group(
                 "--mailbox <account|channel|all>",
                 "Filter by mailbox type.",
               ),
+              ORDER_OPTION,
+              SINCE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -749,9 +795,11 @@ 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>] [--limit <n>] [--cursor <cursor>] [--channel-token <token>] [--profile <name>] [--json]`,
           {
             options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
               LIMIT_OPTION,
               CURSOR_OPTION,
               CHANNEL_TOKEN_OPTION,
@@ -760,6 +808,49 @@ const HELP_ROOT = group(
             ],
           },
         ),
+        command(
+          "changes",
+          "Check whether inbox threads have updates newer than a server timestamp.",
+          `${CLI_NAME} inbox changes --since <server-time> [--status <pending|open|blocked|all>] [--mailbox <account|channel|all>] [--channel-token <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              SINCE_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> [--channel-token <token>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  SINCE_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,6 +11,8 @@ const PAGINATION_FLAG_ORDER: Array<
   ["channelId", "--channel"],
   ["status", "--status"],
   ["mailbox", "--mailbox"],
+  ["order", "--order"],
+  ["since", "--since"],
   ["limit", "--limit"],
 ];
 

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 } }