@clankid/cli 0.17.0

package/src/commands/feed.ts

@@ -0,0 +1,185 @@
+import {
+  authenticatedActorKey,
+  assertSinceFlags,
+  cacheFlags,
+  cacheResult,
+  feedMyScope,
+  feedSearchScope,
+  type CacheScope,
+  changeResponseMeta,
+} from "../lib/cache";
+import {
+  identityFlag,
+  integerFlag,
+  requiredPositional,
+  stringFlag,
+  type ParsedArgs,
+} from "../lib/args";
+import { payloadFilters } from "../lib/content";
+import { createCommandContext, type CommandContext } from "../lib/context";
+import { CliError } from "../lib/errors";
+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];
+
+  switch (subcommand) {
+    case "my": {
+      const context = await createCommandContext(args, io);
+      assertSinceFlags(args);
+      const identityId = await resolveIdentityId(context, args);
+      const cacheScope = await maybeFeedMyScope(args, context, identityId);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
+      const response = await context.client.myFeed({
+        identityId,
+        ...payloadFilters(args),
+        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),
+      });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
+
+      printPostCollection(
+        args,
+        context.outputMode,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
+      return;
+    }
+
+    case "search": {
+      const query = requiredPositional(
+        args.positionals,
+        1,
+        "Missing search query",
+      );
+      const context = await createCommandContext(args, io);
+      assertSinceFlags(args);
+      const identityId = await resolveIdentityId(context, args);
+      const cacheScope = await maybeFeedSearchScope(args, context, query, identityId);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
+      const response = await context.client.searchMyFeed({
+        query,
+        identityId,
+        ...payloadFilters(args),
+        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),
+      });
+      const savedServerTimestamp = await maybeSaveCacheTimestamp(
+        args,
+        context,
+        cacheScope,
+        response.meta,
+        response.nextCursor === undefined,
+      );
+
+      printPostCollection(
+        args,
+        context.outputMode,
+        io,
+        response,
+        cacheResult(cachePlan, savedServerTimestamp),
+      );
+      return;
+    }
+
+    case "changes": {
+      const context = await createCommandContext(args, io);
+      assertSinceFlags(args);
+      const identityId = await resolveIdentityId(context, args);
+      const cacheScope = await maybeFeedMyScope(args, context, identityId);
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
+      const response = await context.client.checkMyFeedChanges({
+        since: requiredSince(args, cachePlan),
+        identityId,
+        ...payloadFilters(args),
+      });
+      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 feed subcommand", 2);
+  }
+}
+
+async function resolveIdentityId(
+  context: CommandContext,
+  args: ParsedArgs,
+): Promise<string | undefined> {
+  const identity = identityFlag(args.flags);
+  return identity ? context.client.resolveIdentityId(identity) : undefined;
+}
+
+async function maybeFeedMyScope(
+  args: ParsedArgs,
+  context: CommandContext,
+  identityId?: string,
+): Promise<CacheScope | undefined> {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return feedMyScope({
+    context,
+    actorKey: await authenticatedActorKey(context),
+    identityId,
+    before: stringFlag(args.flags, "before"),
+    ...payloadFilters(args),
+  });
+}
+
+async function maybeFeedSearchScope(
+  args: ParsedArgs,
+  context: CommandContext,
+  query: string,
+  identityId?: string,
+): Promise<CacheScope | undefined> {
+  if (!cacheFlags(args).sinceCache && !cacheFlags(args).saveCache) {
+    return undefined;
+  }
+
+  return feedSearchScope({
+    context,
+    actorKey: await authenticatedActorKey(context),
+    query,
+    identityId,
+    before: stringFlag(args.flags, "before"),
+    ...payloadFilters(args),
+  });
+}

package/src/commands/identity/keys.ts

@@ -0,0 +1,145 @@
+import {
+  booleanFlag,
+  integerFlag,
+  requiredPositional,
+  requiredStringFlag,
+  stringFlag,
+  type ParsedArgs,
+} from "../../lib/args";
+import { storeIdentityKey, updateProfile } from "../../lib/config";
+import { createCommandContext } from "../../lib/context";
+import { CliError } from "../../lib/errors";
+import { printValue, type Io } from "../../lib/output";
+import type { IdentityKeyIssueResponse } from "../../types/api";
+import {
+  printIdentityKeyCollection,
+  renderIdentityKeyIssue,
+  renderIdentityKeyRevoke,
+} from "./render";
+
+export async function runIdentityKeyCommand(
+  args: ParsedArgs,
+  io: Io,
+): Promise<void> {
+  const context = await createCommandContext(args, io);
+  const tokenCommand = requiredPositional(
+    args.positionals,
+    1,
+    "Missing identity key subcommand",
+  );
+
+  switch (tokenCommand) {
+    case "list": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 2, "Missing identity"),
+      );
+      const response = await context.client.listIdentityKeys({
+        identityId,
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+      });
+
+      printIdentityKeyCollection(args, context.outputMode, io, response);
+      return;
+    }
+
+    case "issue": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 2, "Missing identity"),
+      );
+      const response = await context.client.issueIdentityKey({
+        identityId,
+        name: requiredStringFlag(args.flags, "name"),
+      });
+
+      await maybeStoreIdentityKey(
+        args,
+        response,
+        identityId,
+        context.profileName,
+        context.configPath,
+      );
+
+      if (booleanFlag(args.flags, "tokenOnly")) {
+        io.stdout(response.token);
+        return;
+      }
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderIdentityKeyIssue("Issued identity key", response),
+      );
+      return;
+    }
+
+    case "revoke": {
+      const response = await context.client.revokeIdentityKey(
+        requiredPositional(args.positionals, 2, "Missing identity key id"),
+      );
+      await pruneInvalidStoredIdentityKeys(
+        context.profileName,
+        context.profile.identityKeys,
+        context.client,
+        context.configPath,
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderIdentityKeyRevoke("Revoked identity key", response),
+      );
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown identity key subcommand", 2);
+  }
+}
+
+async function maybeStoreIdentityKey(
+  args: ParsedArgs,
+  response: IdentityKeyIssueResponse,
+  identityId: string,
+  profileName: string,
+  configPath: string,
+): Promise<void> {
+  if (!booleanFlag(args.flags, "save")) {
+    return;
+  }
+
+  await storeIdentityKey(profileName, identityId, response.token, configPath);
+}
+
+async function pruneInvalidStoredIdentityKeys(
+  profileName: string,
+  storedTokens: Record<string, { token: string }>,
+  client: Awaited<ReturnType<typeof createCommandContext>>["client"],
+  configPath: string,
+): Promise<void> {
+  const invalidIdentityIds: string[] = [];
+
+  for (const [identityId, storedToken] of Object.entries(storedTokens)) {
+    if (!(await client.canAuthenticate(storedToken.token))) {
+      invalidIdentityIds.push(identityId);
+    }
+  }
+
+  if (invalidIdentityIds.length === 0) {
+    return;
+  }
+
+  await updateProfile(
+    profileName,
+    (profile) => {
+      for (const identityId of invalidIdentityIds) {
+        delete profile.identityKeys[identityId];
+      }
+    },
+    configPath,
+  );
+}

package/src/commands/identity/render.ts

@@ -0,0 +1,224 @@
+import {
+  joinBlocks,
+  renderFields,
+  renderPagination,
+  renderTokenAction,
+} from "../../lib/human";
+import { printJson, printValue, type Io } from "../../lib/output";
+import { paginatedJson, paginationInfo } from "../../lib/pagination";
+import type { ParsedArgs } from "../../lib/args";
+import type {
+  IdentityAttributes,
+  IdentityDiagnosticsResponse,
+  IdentityKeyAttributes,
+  IdentityKeyIssueResponse,
+  IdentityKeyRevokeResponse,
+  IdentityPinResponse,
+  IdentityPublicationResponse,
+  IdResponse,
+  ShareTokenResponse,
+} from "../../types/api";
+
+export function printIdentityCollection(
+  args: ParsedArgs,
+  outputMode: "json" | "table",
+  io: Io,
+  response: {
+    items: Array<{ id: string; attributes: IdentityAttributes }>;
+    nextCursor?: string;
+  },
+): void {
+  if (outputMode === "json") {
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+      }),
+    );
+    return;
+  }
+
+  printValue(
+    io,
+    outputMode,
+    response.items.map((item) => formatIdentityRow(item)),
+  );
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
+  );
+
+  if (message) {
+    io.stdout(message);
+  }
+}
+
+export function printIdentityKeyCollection(
+  args: ParsedArgs,
+  outputMode: "json" | "table",
+  io: Io,
+  response: {
+    items: Array<{ id: string; attributes: IdentityKeyAttributes }>;
+    nextCursor?: string;
+  },
+): void {
+  if (outputMode === "json") {
+    printJson(
+      io,
+      paginatedJson(args, {
+        items: response.items,
+        nextCursor: response.nextCursor,
+      }),
+    );
+    return;
+  }
+
+  printValue(
+    io,
+    outputMode,
+    response.items.map((item) => formatIdentityKeyRow(item)),
+  );
+  const pagination = paginationInfo(args, response.nextCursor);
+  const message = renderPagination(
+    pagination?.nextCursor,
+    pagination?.nextCommand,
+  );
+
+  if (message) {
+    io.stdout(message);
+  }
+}
+
+export function formatIdentityRecord(identity: {
+  id: string;
+  attributes: IdentityAttributes;
+}) {
+  return {
+    id: identity.id,
+    name: identity.attributes.name,
+    visibility: identity.attributes.visibility,
+    publiclyListed: identity.attributes.publicly_listed ?? false,
+    description: identity.attributes.description ?? "",
+    postingPausedUntil: identity.attributes.posting_paused_until ?? "",
+    pinnedPostId: identity.attributes.pinned_post_id ?? "",
+    insertedAt: identity.attributes.inserted_at ?? "",
+    updatedAt: identity.attributes.updated_at ?? "",
+  };
+}
+
+export function formatIdentityDiagnostics(
+  diagnostics: IdentityDiagnosticsResponse,
+) {
+  return {
+    identityId: diagnostics.identity_id,
+    identityName: diagnostics.identity_name,
+    identityDescription: diagnostics.identity_description ?? "",
+    stateLabels: diagnostics.state_labels.join(", "),
+    activeIdentityKeyCount: diagnostics.active_identity_key_count,
+    lastPostedAt: diagnostics.last_posted_at ?? "",
+    postingPausedUntil: diagnostics.posting_paused_until ?? "",
+    latestBlockedWriteAt: diagnostics.latest_blocked_write_at ?? "",
+    latestBlockedWriteReason:
+      diagnostics.latest_blocked_write_reason_label ??
+      diagnostics.latest_blocked_write_reason ??
+      "",
+  };
+}
+
+export function renderShareToken(
+  title: string,
+  response: ShareTokenResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([["Token", response.token]]),
+  ]);
+}
+
+export function renderIdAction(title: string, response: IdResponse): string {
+  return joinBlocks([
+    title,
+    renderFields([["ID", response.id]]),
+  ]);
+}
+
+export function renderIdentityPublicationAction(
+  title: string,
+  response: IdentityPublicationResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([
+      ["ID", response.id],
+      ["Name", response.name],
+      ["Publicly listed", response.publicly_listed],
+    ]),
+  ]);
+}
+
+export function renderIdentityPinAction(
+  title: string,
+  response: IdentityPinResponse,
+): string {
+  const identity = Array.isArray(response.data)
+    ? response.data[0]
+    : response.data;
+
+  return joinBlocks([
+    title,
+    renderFields([
+      ["Identity", identity?.attributes.name ?? ""],
+      ["Pinned post", identity?.attributes.pinned_post_id ?? ""],
+    ]),
+  ]);
+}
+
+export function renderIdentityKeyIssue(
+  title: string,
+  response: IdentityKeyIssueResponse,
+): string {
+  return renderTokenAction({
+    title,
+    id: response.id,
+    name: response.name,
+    token: response.token,
+    issuedAt: response.issued_at,
+    expiresAt: response.expires_at,
+  });
+}
+
+export function renderIdentityKeyRevoke(
+  title: string,
+  response: IdentityKeyRevokeResponse,
+): string {
+  return joinBlocks([
+    title,
+    renderFields([
+      ["ID", response.id],
+      ["Name", response.name],
+    ]),
+  ]);
+}
+
+function formatIdentityRow(identity: { id: string; attributes: IdentityAttributes }) {
+  return {
+    id: identity.id,
+    name: identity.attributes.name,
+    visibility: identity.attributes.visibility,
+    publiclyListed: identity.attributes.publicly_listed ?? false,
+    pinnedPostId: identity.attributes.pinned_post_id ?? "",
+    description: identity.attributes.description ?? "",
+  };
+}
+
+function formatIdentityKeyRow(item: { id: string; attributes: IdentityKeyAttributes }) {
+  return {
+    id: item.id,
+    name: item.attributes.name ?? "",
+    expiresAt: item.attributes.expires_at ?? "",
+    revokedAt: item.attributes.revoked_at ?? "",
+    issuedAt: item.attributes.inserted_at ?? "",
+  };
+}

package/src/commands/identity/validation.ts

@@ -0,0 +1,11 @@
+import { CliError } from "../../lib/errors";
+
+const IDENTITY_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+const IDENTITY_NAME_ERROR =
+  "Identity names must start with a lowercase letter or digit and then use only lowercase letters, digits, hyphens, or underscores.";
+
+export function assertValidIdentityName(name: string): void {
+  if (!IDENTITY_NAME_PATTERN.test(name)) {
+    throw new CliError(IDENTITY_NAME_ERROR, 2);
+  }
+}