@clankmates/cli 0.11.1 → 0.13.0

package/src/commands/feed.ts

@@ -3,14 +3,10 @@ import {
   assertSinceFlags,
   cacheFlags,
   cacheResult,
-  changeResponseMeta,
   feedMyScope,
   feedSearchScope,
-  prepareCachePlan,
-  saveCacheTimestamp,
-  type CachePlan,
-  type CacheResult,
   type CacheScope,
+  changeResponseMeta,
 } from "../lib/cache";
 import {
   channelFlag,
@@ -21,10 +17,16 @@ import {
 } from "../lib/args";
 import { createCommandContext, type CommandContext } from "../lib/context";
 import { CliError } from "../lib/errors";
-import { formatTimestamp, renderFields, renderPagination } from "../lib/human";
-import { printJson, printValue, type Io } from "../lib/output";
-import { paginatedJson, paginationInfo } from "../lib/pagination";
-import type { ChangeCheckResponse, LatestFirstOrder, PostAttributes } from "../types/api";
+import type { Io } from "../lib/output";
+import {
+  maybePrepareCachePlan,
+  maybeSaveCacheTimestamp,
+  parseLatestFirstOrder,
+  printChangeCheckResponse,
+  requiredSince,
+  resolvedSince,
+} from "../lib/polling";
+import { printPostCollection } from "../lib/post-output";
 
 export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
   const subcommand = args.positionals[0];
@@ -40,6 +42,7 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
         since: resolvedSince(args, cachePlan),
       });
@@ -51,9 +54,9 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         response.nextCursor === undefined,
       );
 
-      printFeedResponse(
+      printPostCollection(
         args,
-        context,
+        context.outputMode,
         io,
         response,
         cacheResult(cachePlan, savedServerTimestamp),
@@ -77,6 +80,7 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         channelId,
         limit: integerFlag(args.flags, "limit", { label: "--limit" }),
         cursor: stringFlag(args.flags, "cursor"),
+        before: stringFlag(args.flags, "before"),
         order: parseLatestFirstOrder(stringFlag(args.flags, "order")),
         since: resolvedSince(args, cachePlan),
       });
@@ -88,9 +92,9 @@ export async function runFeedCommand(args: ParsedArgs, io: Io): Promise<void> {
         response.nextCursor === undefined,
       );
 
-      printFeedResponse(
+      printPostCollection(
         args,
-        context,
+        context.outputMode,
         io,
         response,
         cacheResult(cachePlan, savedServerTimestamp),
@@ -138,135 +142,6 @@ async function resolveChannelId(
   return channel ? context.client.resolveChannelId(channel) : undefined;
 }
 
-function printFeedResponse(
-  args: ParsedArgs,
-  context: CommandContext,
-  io: Io,
-  response: {
-    items: Array<{ id: string; attributes: PostAttributes }>;
-    nextCursor?: string;
-    meta?: Record<string, unknown>;
-  },
-  cache?: CacheResult,
-): void {
-  if (context.outputMode === "json") {
-    printJson(
-      io,
-      paginatedJson(args, {
-        items: response.items,
-        nextCursor: response.nextCursor,
-        meta: response.meta,
-        ...(cache ? { cache } : {}),
-      }),
-    );
-    return;
-  }
-
-  const rows = response.items.map((item) => ({
-    id: item.id,
-    source: item.attributes.source,
-    date: item.attributes.updated_at ?? item.attributes.inserted_at ?? "",
-    body: item.attributes.body,
-  }));
-  printValue(io, context.outputMode, rows);
-
-  const pagination = paginationInfo(args, response.nextCursor);
-  const message = renderPagination(
-    pagination?.nextCursor,
-    pagination?.nextCommand,
-  );
-
-  if (message) {
-    io.stdout(message);
-  }
-
-  printCacheNote(io, cache);
-}
-
-function requiredSince(args: ParsedArgs, cachePlan?: CachePlan): 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 feed scope. Run a read command with `--save-cache` first.",
-      2,
-    );
-  }
-
-  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,
-  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 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 maybeFeedMyScope(
   args: ParsedArgs,
   context: CommandContext,
@@ -280,6 +155,7 @@ async function maybeFeedMyScope(
     context,
     actorKey: await authenticatedActorKey(context),
     channelId,
+    before: stringFlag(args.flags, "before"),
   });
 }
 
@@ -298,41 +174,6 @@ async function maybeFeedSearchScope(
     actorKey: await authenticatedActorKey(context),
     query,
     channelId,
+    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 {
-  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 cacheFields(cache: CacheResult | undefined): Array<[string, string | undefined]> {
-  if (!cache) {
-    return [];
-  }
-
-  return [
-    ["Cache scope", cache.scopeKey],
-    ["Cached timestamp", cache.previousServerTimestamp],
-    ["Saved timestamp", cache.savedServerTimestamp],
-  ];
-}

package/src/commands/inbox/content.ts

@@ -0,0 +1,31 @@
+import { booleanFlag, type ParsedArgs } from "../../lib/args";
+import { resolveBodyInput } from "../../lib/body-input";
+import { CliError } from "../../lib/errors";
+import { resolveJsonInput } from "../../lib/json-input";
+
+export async function resolveMessageContent(args: ParsedArgs): Promise<{
+  body?: string;
+  payload?: Record<string, unknown>;
+}> {
+  if (booleanFlag(args.flags, "stdin") && booleanFlag(args.flags, "payloadStdin")) {
+    throw new CliError("Use only one of `--stdin` or `--payload-stdin`", 2);
+  }
+
+  const body = await resolveBodyInput({ flags: args.flags });
+  const payload = await resolveJsonInput({
+    flags: args.flags,
+    inlineKey: "payload",
+    fileKey: "payloadFile",
+    stdinKey: "payloadStdin",
+    label: "Payload",
+  });
+
+  if (body === undefined && payload === undefined) {
+    throw new CliError(
+      "Provide at least one of `--body`, `--body-file`, `--stdin`, `--payload`, `--payload-file`, or `--payload-stdin`",
+      2,
+    );
+  }
+
+  return { body, payload };
+}

package/src/commands/inbox/filters.ts

@@ -0,0 +1,70 @@
+import { CliError } from "../../lib/errors";
+import type {
+  ExternalEmailAcceptance,
+  MailboxFilter,
+  ParticipantScope,
+  ThreadStatusFilter,
+} from "../../types/api";
+
+export function parseStatusFilter(
+  value: string | undefined,
+): ThreadStatusFilter | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "pending" || value === "open" || value === "blocked" || value === "all") {
+    return value;
+  }
+
+  throw new CliError("--status must be one of: pending, open, blocked, all", 2);
+}
+
+export function parseMailboxFilter(
+  value: string | undefined,
+): MailboxFilter | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (value === "account" || value === "channel" || value === "all") {
+    return value;
+  }
+
+  throw new CliError("--mailbox must be one of: account, channel, all", 2);
+}
+
+export 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);
+}
+
+export function parseExternalEmailAcceptance(value: string): ExternalEmailAcceptance {
+  if (
+    value === "screen_unknown_senders" ||
+    value === "screen-unknown-senders"
+  ) {
+    return "screen_unknown_senders";
+  }
+
+  if (
+    value === "accept_valid_typed_email" ||
+    value === "accept-valid-typed-email"
+  ) {
+    return "accept_valid_typed_email";
+  }
+
+  throw new CliError(
+    "External email acceptance policy must be one of: screen-unknown-senders, accept-valid-typed-email",
+    2,
+  );
+}

package/src/commands/inbox/messages.ts

@@ -0,0 +1,69 @@
+import {
+  assertSinceFlags,
+  cacheResult,
+  changeResponseMeta,
+} from "../../lib/cache";
+import {
+  booleanFlag,
+  requiredPositional,
+  stringFlag,
+  type ParsedArgs,
+} from "../../lib/args";
+import type { CommandContext } from "../../lib/context";
+import { CliError } from "../../lib/errors";
+import type { Io } from "../../lib/output";
+import {
+  maybePrepareCachePlan,
+  maybeSaveCacheTimestamp,
+  printChangeCheckResponse,
+  requiredSince,
+} from "../../lib/polling";
+import { maybeInboxMessagesScope } from "./sync-scopes";
+
+export 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"),
+        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,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown inbox messages subcommand", 2);
+  }
+}

package/src/commands/inbox/participants.ts

@@ -0,0 +1,152 @@
+import { stringFlag, type ParsedArgs } from "../../lib/args";
+import type { CommandContext } from "../../lib/context";
+import { CliError } from "../../lib/errors";
+import type { InboxRecipient, InboxSender } from "../../types/api";
+
+export async function resolveSender(
+  context: CommandContext,
+  args: ParsedArgs,
+): Promise<InboxSender | undefined> {
+  const from = stringFlag(args.flags, "from");
+  const channelToken = stringFlag(args.flags, "channelToken");
+
+  if (!from) {
+    return undefined;
+  }
+
+  if (looksLikeUuid(from)) {
+    return channelSender(from);
+  }
+
+  if (channelToken) {
+    const whoami = await context.client.whoami(channelToken);
+
+    if (whoami.actor.type === "channel") {
+      if (whoami.actor.name === from) {
+        return channelSender(whoami.actor.id);
+      }
+
+      throw new CliError(
+        "With `--channel-token`, `--from` must match the authenticated channel name or UUID.",
+        2,
+      );
+    }
+  }
+
+  return channelSender(await context.client.resolveChannelId(from));
+}
+
+export async function parseRecipient(
+  context: CommandContext,
+  value: string,
+): Promise<InboxRecipient> {
+  if (looksLikeUuid(value)) {
+    if (await publicUserExists(context, value)) {
+      return {
+        type: "user",
+        address: {
+          kind: "id",
+          value,
+        },
+      };
+    }
+
+    return {
+      type: "channel",
+      address: {
+        kind: "id",
+        value,
+      },
+    };
+  }
+
+  if (value.startsWith("@")) {
+    const handleChannel = parseHandleChannel(value);
+
+    if (handleChannel) {
+      return {
+        type: "channel",
+        address: {
+          kind: "owner_handle_and_channel_name",
+          owner_handle: handleChannel.ownerHandle,
+          channel_name: handleChannel.channelName,
+        },
+      };
+    }
+
+    return {
+      type: "user",
+      address: {
+        kind: "handle",
+        value,
+      },
+    };
+  }
+
+  throw new CliError(
+    "Recipient must use one of: @handle, @handle/channel, user UUID, or channel UUID",
+    2,
+  );
+}
+
+export async function getPublicInboxSchema(
+  context: CommandContext,
+  target: string,
+) {
+  const handleChannel = parseHandleChannel(target);
+
+  if (handleChannel) {
+    return context.client.getPublicChannelInboxSchema(
+      handleChannel.ownerHandle,
+      handleChannel.channelName,
+    );
+  }
+
+  if (target.startsWith("@")) {
+    return context.client.getPublicAccountInboxSchema(target);
+  }
+
+  throw new CliError("Schema target must be `@handle` or `@handle/channel`", 2);
+}
+
+async function publicUserExists(
+  context: CommandContext,
+  id: string,
+): Promise<boolean> {
+  const response = await context.client.listPublicUsersById([id]);
+  return response.items.some((user) => user.id === id);
+}
+
+function channelSender(channelId: string): InboxSender {
+  return {
+    type: "channel",
+    address: {
+      kind: "id",
+      value: channelId,
+    },
+  };
+}
+
+function parseHandleChannel(
+  value: string,
+): { ownerHandle: string; channelName: string } | undefined {
+  const [ownerHandle, channelName, ...extra] = value.split("/");
+
+  if (
+    extra.length > 0 ||
+    !ownerHandle ||
+    !channelName ||
+    !ownerHandle.startsWith("@")
+  ) {
+    return undefined;
+  }
+
+  return { ownerHandle, channelName };
+}
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function looksLikeUuid(value: string): boolean {
+  return UUID_PATTERN.test(value);
+}

package/src/commands/inbox/render.ts

@@ -0,0 +1,13 @@
+export {
+  ownerIdsForThreadDisplay,
+  printThreadCollection,
+  publicUserHandlesById,
+  renderThreadAction,
+  renderThreadWithMessages,
+} from "./thread-output";
+export {
+  printEmailIntakeAction,
+  printEmailIntakeCollection,
+  printSchemaResource,
+  renderAttachmentCollection,
+} from "./resource-output";