@clankid/cli 0.17.0

package/src/lib/args.ts

@@ -0,0 +1,231 @@
+import { parseArgs as parseNodeArgs } from "node:util";
+
+import { CliError } from "./errors";
+
+const CLI_OPTIONS = {
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean" },
+  json: { type: "boolean" },
+  profile: { type: "string" },
+  baseUrl: { type: "string" },
+  "base-url": { type: "string" },
+  output: { type: "string" },
+  host: { type: "string" },
+  masterToken: { type: "string" },
+  "master-token": { type: "string" },
+  readOnlyToken: { type: "string" },
+  "read-only-token": { type: "string" },
+  scope: { type: "string" },
+  name: { type: "string" },
+  description: { type: "string" },
+  email: { type: "string" },
+  handle: { type: "string" },
+  code: { type: "string" },
+  keyName: { type: "string" },
+  "key-name": { type: "string" },
+  bootstrapId: { type: "string" },
+  "bootstrap-id": { type: "string" },
+  localBypass: { type: "boolean" },
+  "local-bypass": { type: "boolean" },
+  save: { type: "boolean" },
+  force: { type: "boolean" },
+  copy: { type: "boolean" },
+  tokenOnly: { type: "boolean" },
+  "token-only": { type: "boolean" },
+  masterTokenStdin: { type: "boolean" },
+  "master-token-stdin": { type: "boolean" },
+  identity: { type: "string" },
+  "identity-id": { type: "string" },
+  from: { type: "string" },
+  identityKey: { type: "string" },
+  "identity-key": { type: "string" },
+  contextPostId: { type: "string" },
+  "context-post-id": { type: "string" },
+  body: { type: "string" },
+  bodyFile: { type: "string" },
+  "body-file": { type: "string" },
+  stdin: { type: "boolean" },
+  content: { type: "string" },
+  payload: { type: "string" },
+  payloadFile: { type: "string" },
+  "payload-file": { type: "string" },
+  payloadStdin: { type: "boolean" },
+  "payload-stdin": { type: "boolean" },
+  payloadContains: { type: "string" },
+  "payload-contains": { type: "string" },
+  payloadPath: { type: "string" },
+  "payload-path": { type: "string" },
+  payloadOp: { type: "string" },
+  "payload-op": { type: "string" },
+  payloadValue: { type: "string" },
+  "payload-value": { type: "string" },
+  schema: { type: "string" },
+  schemaFile: { type: "string" },
+  "schema-file": { type: "string" },
+  schemaStdin: { type: "boolean" },
+  "schema-stdin": { type: "boolean" },
+  limit: { type: "string" },
+  cursor: { type: "string" },
+  before: { type: "string" },
+  order: { type: "string" },
+  since: { type: "string" },
+  sinceCache: { type: "boolean" },
+  "since-cache": { type: "boolean" },
+  saveCache: { type: "boolean" },
+  "save-cache": { type: "boolean" },
+  once: { type: "boolean" },
+  status: { type: "string" },
+  mailbox: { type: "string" },
+  participant: { type: "string" },
+  participantScope: { type: "string" },
+  "participant-scope": { type: "string" },
+  query: { type: "string" },
+  hasAttachment: { type: "boolean" },
+  "has-attachment": { type: "boolean" },
+} as const;
+
+type ParsedValue = string | boolean;
+
+const REMOVED_OPTIONS: Record<string, string> = {
+  "--sender-identity": "`--sender-identity` has been removed. Use `--from` instead.",
+};
+
+export interface ParsedArgs {
+  commandPath: string[];
+  positionals: string[];
+  flags: Record<string, ParsedValue>;
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  rejectRemovedOptions(argv);
+
+  const parsed = parseNodeArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: false,
+    options: CLI_OPTIONS,
+  });
+  const [command, ...positionals] = parsed.positionals;
+
+  return {
+    commandPath: command ? [command] : [],
+    positionals,
+    flags: normalizeFlags(
+      parsed.values as Record<string, ParsedValue | undefined>,
+    ),
+  };
+}
+
+function rejectRemovedOptions(argv: string[]): void {
+  for (const arg of argv) {
+    const option = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+    const message = REMOVED_OPTIONS[option];
+
+    if (message) {
+      throw new CliError(message, 2);
+    }
+  }
+}
+
+export function stringFlag(
+  flags: ParsedArgs["flags"],
+  key: string,
+): string | undefined {
+  const value = flags[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+export function requiredStringFlag(
+  flags: ParsedArgs["flags"],
+  key: string,
+): string {
+  const value = stringFlag(flags, key);
+
+  if (!value) {
+    throw new CliError(`Missing \`${toFlagName(key)}\``, 2);
+  }
+
+  return value;
+}
+
+export function identityFlag(flags: ParsedArgs["flags"]): string | undefined {
+  return stringFlag(flags, "identity") ?? stringFlag(flags, "identityId");
+}
+
+export function requiredIdentityFlag(flags: ParsedArgs["flags"]): string {
+  const value = identityFlag(flags);
+
+  if (!value) {
+    throw new CliError("Missing `--identity`", 2);
+  }
+
+  return value;
+}
+
+export function integerFlag(
+  flags: ParsedArgs["flags"],
+  key: string,
+  options: { min?: number; label?: string } = {},
+): number | undefined {
+  const value = stringFlag(flags, key);
+
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  const minimum = options.min ?? 1;
+
+  if (!Number.isFinite(parsed) || parsed < minimum) {
+    throw new CliError(
+      `${options.label ?? toFlagName(key)} must be an integer >= ${minimum}`,
+      2,
+    );
+  }
+
+  return parsed;
+}
+
+export function booleanFlag(flags: ParsedArgs["flags"], key: string): boolean {
+  return flags[key] === true;
+}
+
+export function requiredPositional(
+  positionals: string[],
+  index: number,
+  message: string,
+): string {
+  const value = positionals[index];
+
+  if (!value) {
+    throw new CliError(message, 2);
+  }
+
+  return value;
+}
+
+function normalizeFlags(
+  values: Record<string, ParsedValue | undefined>,
+): Record<string, ParsedValue> {
+  const flags: Record<string, ParsedValue> = {};
+
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    flags[toCamelCase(key)] = value;
+  }
+
+  return flags;
+}
+
+function toCamelCase(value: string): string {
+  return value.replace(/-([a-z])/g, (_, letter: string) =>
+    letter.toUpperCase(),
+  );
+}
+
+function toFlagName(value: string): string {
+  return `--${value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+}

package/src/lib/body-input.ts

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+
+import { booleanFlag, stringFlag, type ParsedArgs } from "./args";
+import { CliError } from "./errors";
+
+export interface ResolveBodyInputOptions {
+  flags: ParsedArgs["flags"];
+  requireBody?: boolean;
+  readFileText?: (path: string) => Promise<string>;
+  readStdinText?: () => Promise<string>;
+}
+
+export async function resolveBodyInput({
+  flags,
+  requireBody = false,
+  readFileText = (path) => readFile(path, "utf8"),
+  readStdinText = () => readStdin()
+}: ResolveBodyInputOptions): Promise<string | undefined> {
+  const inlineBody = stringFlag(flags, "body");
+  const bodyFile = stringFlag(flags, "bodyFile");
+  const useStdin = booleanFlag(flags, "stdin");
+  const providedCount = [inlineBody !== undefined, bodyFile !== undefined, useStdin].filter(Boolean).length;
+
+  if (requireBody && providedCount === 0) {
+    throw new CliError("Provide exactly one of `--body`, `--body-file`, or `--stdin`", 2);
+  }
+
+  if (providedCount > 1) {
+    throw new CliError("Use only one of `--body`, `--body-file`, or `--stdin`", 2);
+  }
+
+  if (inlineBody !== undefined) {
+    return inlineBody;
+  }
+
+  if (bodyFile !== undefined) {
+    return readFileText(bodyFile);
+  }
+
+  if (useStdin) {
+    return readStdinText();
+  }
+
+  return undefined;
+}
+
+export async function readStdin(stdin: AsyncIterable<unknown> = process.stdin): Promise<string> {
+  let buffer = "";
+
+  for await (const chunk of stdin) {
+    buffer += typeof chunk === "string" ? chunk : Buffer.from(chunk as ArrayBufferLike).toString("utf8");
+  }
+
+  return buffer;
+}

package/src/lib/cache/scopes.ts

@@ -0,0 +1,272 @@
+import { createHash } from "node:crypto";
+
+import type { CommandContext } from "../context";
+import type { PayloadFilters, WhoamiActor } from "../../types/api";
+import type { CacheScope } from "./types";
+
+const PUBLIC_ACTOR_KEY = "public";
+const SHARED_ACTOR_KEY = "shared";
+
+export function actorKey(actor: WhoamiActor): string {
+  if (actor.type === "user") {
+    return `user:${actor.id}:${actor.scope ?? "master"}`;
+  }
+
+  return `identity:${actor.id}`;
+}
+
+export function publicActorKey(): string {
+  return PUBLIC_ACTOR_KEY;
+}
+
+export function sharedActorKey(): string {
+  return SHARED_ACTOR_KEY;
+}
+
+export function feedMyScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  identityId?: string;
+  before?: string;
+} & PayloadFilters): CacheScope {
+  const identity = input.identityId ?? "all";
+  const before = input.before ?? "default";
+  const payload = payloadFilterParts(input);
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:my",
+    parts: ["feed", "my", identity, before, ...payload.parts],
+    params: { identity, before, ...payload.params },
+  });
+}
+
+export function feedSearchScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  query: string;
+  identityId?: string;
+  before?: string;
+} & PayloadFilters): CacheScope {
+  const identity = input.identityId ?? "all";
+  const before = input.before ?? "default";
+  const payload = payloadFilterParts(input);
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "feed:search",
+    parts: ["feed", "search", input.query, identity, before, ...payload.parts],
+    params: { query: input.query, identity, before, ...payload.params },
+  });
+}
+
+export function inboxThreadsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  status?: string;
+  mailbox?: string;
+  participant?: string;
+  participantScope?: string;
+  query?: string;
+  hasAttachment?: boolean;
+  before?: string;
+} & PayloadFilters): CacheScope {
+  const status = input.status ?? "default";
+  const mailbox = input.mailbox ?? "default";
+  const participant = input.participant ?? "default";
+  const participantScope = input.participantScope ?? "default";
+  const query = input.query ?? "default";
+  const hasAttachment = input.hasAttachment ?? false;
+  const before = input.before ?? "default";
+  const payload = payloadFilterParts(input);
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:threads",
+    parts: [
+      "inbox",
+      "threads",
+      status,
+      mailbox,
+      participant,
+      participantScope,
+      query,
+      String(hasAttachment),
+      before,
+      ...payload.parts,
+      input.actorKey,
+    ],
+    params: {
+      status,
+      mailbox,
+      participant,
+      participantScope,
+      query,
+      hasAttachment,
+      before,
+      ...payload.params,
+    },
+  });
+}
+
+export function inboxMessagesScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  threadId: string;
+  query?: string;
+  hasAttachment?: boolean;
+  before?: string;
+} & PayloadFilters): CacheScope {
+  const query = input.query ?? "default";
+  const hasAttachment = input.hasAttachment ?? false;
+  const before = input.before ?? "default";
+  const payload = payloadFilterParts(input);
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "inbox:messages",
+    parts: [
+      "inbox",
+      "messages",
+      input.threadId,
+      query,
+      String(hasAttachment),
+      before,
+      ...payload.parts,
+      input.actorKey,
+    ],
+    params: {
+      threadId: input.threadId,
+      query,
+      hasAttachment,
+      before,
+      ...payload.params,
+    },
+  });
+}
+
+export function ownedPostsScope(input: {
+  context: CommandContext;
+  actorKey: string;
+  identityId: string;
+  before?: string;
+} & PayloadFilters): CacheScope {
+  const before = input.before ?? "default";
+  const payload = payloadFilterParts(input);
+  return scoped({
+    context: input.context,
+    actorKey: input.actorKey,
+    resource: "posts:owned",
+    parts: ["posts", "owned", input.identityId, before, ...payload.parts],
+    params: { identityId: input.identityId, before, ...payload.params },
+  });
+}
+
+export function publicPostsScope(input: {
+  context: CommandContext;
+  publicHandle: string;
+  identityName: string;
+  before?: string;
+} & PayloadFilters): CacheScope {
+  const before = input.before ?? "default";
+  const payload = payloadFilterParts(input);
+  return scoped({
+    context: input.context,
+    actorKey: PUBLIC_ACTOR_KEY,
+    resource: "posts:public",
+    parts: [
+      "posts",
+      "public",
+      input.publicHandle,
+      input.identityName,
+      before,
+      ...payload.parts,
+    ],
+    params: {
+      publicHandle: input.publicHandle,
+      identityName: input.identityName,
+      before,
+      ...payload.params,
+    },
+  });
+}
+
+export function sharedPostsScope(input: {
+  context: CommandContext;
+  shareToken: string;
+  before?: string;
+} & PayloadFilters): CacheScope {
+  const shareTokenHash = hashValue(input.shareToken);
+  const before = input.before ?? "default";
+  const payload = payloadFilterParts(input);
+  return scoped({
+    context: input.context,
+    actorKey: SHARED_ACTOR_KEY,
+    resource: "posts:shared",
+    parts: ["posts", "shared", shareTokenHash, before, ...payload.parts],
+    params: { shareTokenHash, before, ...payload.params },
+  });
+}
+
+export function hashValue(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function scoped(input: {
+  context: CommandContext;
+  actorKey: string;
+  resource: string;
+  parts: string[];
+  params: Record<string, unknown>;
+}): CacheScope {
+  const prefix = [
+    "v1",
+    normalizePart(input.context.profile.baseUrl),
+    normalizePart(input.context.profileName),
+    normalizePart(input.actorKey),
+  ];
+  const scopeKey = [...prefix, ...input.parts.map(normalizePart)].join(":");
+
+  return {
+    scopeKey,
+    resource: input.resource,
+    params: input.params,
+    actorKey: input.actorKey,
+  };
+}
+
+function normalizePart(value: string): string {
+  return encodeURIComponent(value);
+}
+
+function payloadFilterParts(input: PayloadFilters): {
+  parts: string[];
+  params: Record<string, unknown>;
+} {
+  if (
+    input.contentFormat === undefined &&
+    input.payloadContains === undefined &&
+    input.payloadPath === undefined &&
+    input.payloadOp === undefined &&
+    input.payloadValue === undefined
+  ) {
+    return { parts: [], params: {} };
+  }
+
+  const content = input.contentFormat ?? "default";
+  const contains = input.payloadContains ?? "default";
+  const path = input.payloadPath ?? "default";
+  const op = input.payloadOp ?? "default";
+  const value = input.payloadValue ?? "default";
+
+  return {
+    parts: [content, contains, path, op, value],
+    params: {
+      content,
+      payloadContains: contains,
+      payloadPath: path,
+      payloadOp: op,
+      payloadValue: value,
+    },
+  };
+}