@clankid/cli 0.17.0

package/src/commands/identity.ts

@@ -0,0 +1,295 @@
+import {
+  booleanFlag,
+  integerFlag,
+  requiredPositional,
+  requiredStringFlag,
+  stringFlag,
+  type ParsedArgs,
+} from "../lib/args";
+import { createCommandContext } from "../lib/context";
+import { CliError } from "../lib/errors";
+import { printValue, type Io } from "../lib/output";
+import {
+  formatIdentityDiagnostics,
+  formatIdentityRecord,
+  printIdentityCollection,
+  renderIdentityPinAction,
+  renderIdentityPublicationAction,
+  renderIdAction,
+  renderShareToken,
+} from "./identity/render";
+import { runIdentityKeyCommand } from "./identity/keys";
+import { assertValidIdentityName } from "./identity/validation";
+
+export async function runIdentityCommand(
+  args: ParsedArgs,
+  io: Io,
+): Promise<void> {
+  const subcommand = args.positionals[0];
+  const context = await createCommandContext(args, io);
+
+  switch (subcommand) {
+    case "list": {
+      const response = await context.client.listIdentities({
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+      });
+
+      printIdentityCollection(args, context.outputMode, io, response);
+      return;
+    }
+
+    case "get": {
+      const identity = await context.client.resolveOwnedIdentity(
+        requiredPositional(args.positionals, 1, "Missing identity"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json" ? identity : formatIdentityRecord(identity),
+      );
+      return;
+    }
+
+    case "diagnostics": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 1, "Missing identity"),
+      );
+      const diagnostics = await context.client.getIdentityDiagnostics(identityId);
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? diagnostics
+          : formatIdentityDiagnostics(diagnostics),
+      );
+      return;
+    }
+
+    case "public-list": {
+      const response = await context.client.listPublicIdentitiesForHandle({
+        publicHandle: requiredPositional(
+          args.positionals,
+          1,
+          "Missing public handle",
+        ),
+        limit: integerFlag(args.flags, "limit", { label: "--limit" }),
+        cursor: stringFlag(args.flags, "cursor"),
+      });
+
+      printIdentityCollection(args, context.outputMode, io, response);
+      return;
+    }
+
+    case "public-get": {
+      const identity = await context.client.getPublicIdentityByHandle(
+        requiredPositional(args.positionals, 1, "Missing public handle"),
+        requiredPositional(args.positionals, 2, "Missing public identity name"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json" ? identity : formatIdentityRecord(identity),
+      );
+      return;
+    }
+
+    case "shared-get": {
+      const identity = await context.client.getSharedIdentity(
+        requiredPositional(args.positionals, 1, "Missing share token"),
+      );
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json" ? identity : formatIdentityRecord(identity),
+      );
+      return;
+    }
+
+    case "create": {
+      const name = requiredStringFlag(args.flags, "name");
+      assertValidIdentityName(name);
+
+      const identity = await context.client.createIdentity({
+        name,
+        description: stringFlag(args.flags, "description"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json" ? identity : formatIdentityRecord(identity),
+      );
+      return;
+    }
+
+    case "update": {
+      const identityRef = requiredPositional(
+        args.positionals,
+        1,
+        "Missing identity",
+      );
+      const name = stringFlag(args.flags, "name");
+      const description = stringFlag(args.flags, "description");
+
+      if (name === undefined && description === undefined) {
+        throw new CliError(
+          "Provide at least one of `--name` or `--description`.",
+          2,
+        );
+      }
+
+      if (name !== undefined) {
+        assertValidIdentityName(name);
+      }
+
+      const identityId = await context.client.resolveIdentityId(identityRef);
+      const identity = await context.client.updateIdentity({
+        identityId,
+        name,
+        description,
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json" ? identity : formatIdentityRecord(identity),
+      );
+      return;
+    }
+
+    case "publish-public": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 1, "Missing identity"),
+      );
+      const identity = await context.client.publishIdentityPublicly(identityId);
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json" ? identity : formatIdentityRecord(identity),
+      );
+      return;
+    }
+
+    case "unpublish-public": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 1, "Missing identity"),
+      );
+      const response = await context.client.unpublishIdentityPublicly(identityId);
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderIdentityPublicationAction("Unpublished identity", response),
+      );
+      return;
+    }
+
+    case "share": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 1, "Missing identity"),
+      );
+      const response = await context.client.shareIdentity(identityId);
+
+      if (booleanFlag(args.flags, "tokenOnly")) {
+        io.stdout(response.token);
+        return;
+      }
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderShareToken("Issued identity share token", response),
+      );
+      return;
+    }
+
+    case "revoke-share": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 1, "Missing identity"),
+      );
+      const response = await context.client.revokeIdentityShare(identityId);
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderIdAction("Revoked identity share token", response),
+      );
+      return;
+    }
+
+    case "pin-post": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 1, "Missing identity"),
+      );
+      const response = await context.client.pinIdentityPost({
+        identityId,
+        postId: requiredPositional(args.positionals, 2, "Missing post id"),
+        identityKey: stringFlag(args.flags, "identityKey"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderIdentityPinAction("Pinned identity post", response),
+      );
+      return;
+    }
+
+    case "unpin-post": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 1, "Missing identity"),
+      );
+      const response = await context.client.unpinIdentityPost({
+        identityId,
+        identityKey: stringFlag(args.flags, "identityKey"),
+      });
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? response
+          : renderIdentityPinAction("Unpinned identity post", response),
+      );
+      return;
+    }
+
+    case "delete": {
+      const identityId = await context.client.resolveIdentityId(
+        requiredPositional(args.positionals, 1, "Missing identity"),
+      );
+      await context.client.deleteIdentity(identityId);
+
+      printValue(
+        io,
+        context.outputMode,
+        context.outputMode === "json"
+          ? { ok: true, id: identityId }
+          : `Deleted identity ${identityId}.`,
+      );
+      return;
+    }
+
+    case "key": {
+      await runIdentityKeyCommand(args, io);
+      return;
+    }
+
+    default:
+      throw new CliError("Unknown identity subcommand", 2);
+  }
+}

package/src/commands/inbox/content.ts

@@ -0,0 +1,13 @@
+import { type ParsedArgs } from "../../lib/args";
+import { resolveStructuredContentInput } from "../../lib/content";
+
+export async function resolveMessageContent(args: ParsedArgs): Promise<{
+  body?: string;
+  payload?: Record<string, unknown>;
+  contentFormat?: "markdown" | "json";
+}> {
+  return resolveStructuredContentInput(args, {
+    requireContent: true,
+    label: "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 === "identity" || value === "all") {
+    return value;
+  }
+
+  throw new CliError("--mailbox must be one of: account, identity, 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,71 @@
+import {
+  assertSinceFlags,
+  cacheResult,
+  changeResponseMeta,
+} from "../../lib/cache";
+import {
+  booleanFlag,
+  requiredPositional,
+  stringFlag,
+  type ParsedArgs,
+} from "../../lib/args";
+import { payloadFilters } from "../../lib/content";
+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 identityKey = stringFlag(args.flags, "identityKey");
+      const cacheScope = await maybeInboxMessagesScope(
+        args,
+        context,
+        identityKey,
+        threadId,
+      );
+      const cachePlan = await maybePrepareCachePlan(args, context, cacheScope);
+      const response = await context.client.checkThreadMessageChanges({
+        threadId,
+        since: requiredSince(args, cachePlan, "inbox message"),
+        ...payloadFilters(args),
+        query: stringFlag(args.flags, "query"),
+        hasAttachment: booleanFlag(args.flags, "hasAttachment") || undefined,
+        identityKey,
+      });
+      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 identityKey = stringFlag(args.flags, "identityKey");
+
+  if (!from) {
+    return undefined;
+  }
+
+  if (looksLikeUuid(from)) {
+    return identitySender(from);
+  }
+
+  if (identityKey) {
+    const whoami = await context.client.whoami(identityKey);
+
+    if (whoami.actor.type === "identity") {
+      if (whoami.actor.name === from) {
+        return identitySender(whoami.actor.id);
+      }
+
+      throw new CliError(
+        "With `--identity-key`, `--from` must match the authenticated identity name or UUID.",
+        2,
+      );
+    }
+  }
+
+  return identitySender(await context.client.resolveIdentityId(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: "identity",
+      address: {
+        kind: "id",
+        value,
+      },
+    };
+  }
+
+  if (value.startsWith("@")) {
+    const handleIdentity = parseHandleIdentity(value);
+
+    if (handleIdentity) {
+      return {
+        type: "identity",
+        address: {
+          kind: "owner_handle_and_identity_name",
+          owner_handle: handleIdentity.ownerHandle,
+          identity_name: handleIdentity.identityName,
+        },
+      };
+    }
+
+    return {
+      type: "user",
+      address: {
+        kind: "handle",
+        value,
+      },
+    };
+  }
+
+  throw new CliError(
+    "Recipient must use one of: @handle, @handle/identity, user UUID, or identity UUID",
+    2,
+  );
+}
+
+export async function getPublicInboxSchema(
+  context: CommandContext,
+  target: string,
+) {
+  const handleIdentity = parseHandleIdentity(target);
+
+  if (handleIdentity) {
+    return context.client.getPublicIdentityInboxSchema(
+      handleIdentity.ownerHandle,
+      handleIdentity.identityName,
+    );
+  }
+
+  if (target.startsWith("@")) {
+    return context.client.getPublicAccountInboxSchema(target);
+  }
+
+  throw new CliError("Schema target must be `@handle` or `@handle/identity`", 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 identitySender(identityId: string): InboxSender {
+  return {
+    type: "identity",
+    address: {
+      kind: "id",
+      value: identityId,
+    },
+  };
+}
+
+function parseHandleIdentity(
+  value: string,
+): { ownerHandle: string; identityName: string } | undefined {
+  const [ownerHandle, identityName, ...extra] = value.split("/");
+
+  if (
+    extra.length > 0 ||
+    !ownerHandle ||
+    !identityName ||
+    !ownerHandle.startsWith("@")
+  ) {
+    return undefined;
+  }
+
+  return { ownerHandle, identityName };
+}
+
+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";