@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/api/mail.ts

@@ -0,0 +1,333 @@
+// vfrey Mail (spec 018): `mail draft | drafts | show | approve | send | discard | identity`, and the helpers the desk route shares.
+// Drafting is free and sends nothing. Approving and sending are two separate commands a person runs, one draft at a time:
+// no command here ever approves or sends as a side effect of another.
+import { ApiFailure, clean } from "./client.js";
+import { ApiConfigError } from "./config.js";
+import type { ApiIo } from "./commands.js";
+import { openSession, type TopicsDeps } from "./topics.js";
+import { normalizeHandle, CREATOR_PLATFORM_IDS } from "./creators.js";
+import { MAIL_KINDS, MAIL_STATUSES, type MailDraftBody, type MailDraftPatch, type MailDraftView, type MailIdentityBody, type MailIdentityView } from "./types.js";
+
+export type MailDeps = TopicsDeps;
+
+const DASH = "—";
+const PERSON_ONLY = "an agent token can't approve or send; a person signs in with `npx vfrey login` and runs it.";
+
+// ---------- every server refusal, in the person's words ----------
+
+/** Maps one server refusal to a `✗` message and a `Fix:` that names the next command. `id` is the draft it was about. */
+export function mailFailure(error: unknown, id?: string): unknown {
+  if (!(error instanceof ApiFailure)) return error;
+  const { status, code } = error;
+  const text = error.message;
+  const mk = (message: string, fix: string) => new ApiFailure(message, fix, status, code);
+  const show = id ? `\`npx vfrey mail show --id ${clean(id)}\`` : "`npx vfrey mail drafts`";
+  if (status === 401 || code === "not_live" || code === "not_signed_in") return error;
+  if (status === 402 && code === "plan_required") return mk("Mail is not in your plan: it needs the Mail add-on.", error.fix.replace(/^upgrade your plan/, "add the Mail add-on"));
+  if (status === 402) return error;
+  if (status === 403) return mk(text || "Only a person can do that.", PERSON_ONLY);
+  if (status === 404) {
+    if (/creator/i.test(text)) return mk(text, "look the creator up with `npx vfrey creators show @handle --platform tiktok`, or draft without --creator.");
+    return mk(text || "No such draft.", "list your drafts with `npx vfrey mail drafts`.");
+  }
+  if (status === 409) {
+    if (/Approve this draft/i.test(text)) return mk(text, `ask the person to check ${show}; only if they say so for this draft, they run \`npx vfrey mail approve --id ${id ? clean(id) : "ID"}\`.`);
+    if (/reply-to|Confirm your/i.test(text)) return mk(text, "open the confirmation link emailed to your reply-to address, then check it with `npx vfrey mail identity`. Resend the link by running `npx vfrey mail identity` with the same flags.");
+    if (/cannot be mailed|suppress/i.test(text)) return mk("This address cannot be mailed: its owner opted out or it bounced.", "use another recipient: `npx vfrey mail draft --to OTHER_EMAIL ...`. Do not try to get around it.");
+    if (/sender identity/i.test(text)) return mk(text, 'set it up first: `npx vfrey mail identity --from-name "Ana" --reply-to you@example.com --postal-address "1 Main St, City, Country"`.');
+    if (/already sent/i.test(text)) return mk(text, "nothing to do. See it with `npx vfrey mail drafts --status sent`.");
+    if (/changed/i.test(text)) return mk(text, `read it again with ${show}.`);
+    return mk(text, `check where it stands with ${show}.`);
+  }
+  if (status === 429) {
+    if (/limit of/i.test(text)) return mk(text, "send the rest after the reset time named above. The limit protects your sending reputation.");
+    if (/verification/i.test(text)) return mk(text, "wait an hour, then save your identity again.");
+    return mk(text || "Too many requests.", "wait a minute and try again.");
+  }
+  if (status === 503) {
+    if (code === "capacity_paused") return error;
+    return mk(text || "Mail is paused or not set up on this server.", "try again later. Nothing was sent or charged. If you run your own server, check the mail secret and provider settings.");
+  }
+  if (status === 400) return mk(text, "fix what it names, then run the command again. `npx vfrey mail --help` lists the flags.");
+  return error;
+}
+
+function checked<T>(value: T | null | undefined, ok: (v: T) => boolean): T {
+  if (value === null || value === undefined || !ok(value)) throw new ApiFailure("The vfrey server sent an answer this version does not understand.", "update vfrey with `npx vfrey update`.");
+  return value;
+}
+const isDraft = (a: { draft?: MailDraftView }) => typeof a.draft?.id === "string";
+
+// ---------- server calls (one per command; none calls another) ----------
+
+export async function createMailDraft(deps: MailDeps, body: MailDraftBody, api?: string | null): Promise<MailDraftView> {
+  try {
+    return checked(await openSession(deps, api).mailDraft(body), isDraft).draft;
+  } catch (error) {
+    throw mailFailure(error);
+  }
+}
+
+export async function listMailDrafts(deps: MailDeps, query: { status?: string; limit?: number } = {}, api?: string | null): Promise<MailDraftView[]> {
+  try {
+    return checked(await openSession(deps, api).mailDrafts(query), (a) => Array.isArray(a.drafts)).drafts;
+  } catch (error) {
+    throw mailFailure(error);
+  }
+}
+
+export async function getMailDraft(deps: MailDeps, id: string, api?: string | null): Promise<MailDraftView> {
+  try {
+    return checked(await openSession(deps, api).mailGet(id), isDraft).draft;
+  } catch (error) {
+    throw mailFailure(error, id);
+  }
+}
+
+export async function editMailDraft(deps: MailDeps, id: string, patch: MailDraftPatch, api?: string | null): Promise<MailDraftView> {
+  try {
+    return checked(await openSession(deps, api).mailEdit(id, patch), isDraft).draft;
+  } catch (error) {
+    throw mailFailure(error, id);
+  }
+}
+
+/** Approves one draft. Sends nothing. Only the `approve` subcommand and the desk's Approve button reach this. */
+export async function approveMailDraft(deps: MailDeps, id: string, api?: string | null): Promise<MailDraftView> {
+  try {
+    return checked(await openSession(deps, api).mailApprove(id), isDraft).draft;
+  } catch (error) {
+    throw mailFailure(error, id);
+  }
+}
+
+/** Sends one already-approved draft. Only the `send` subcommand and the desk's Send button reach this. */
+export async function sendMailDraft(deps: MailDeps, id: string, api?: string | null): Promise<MailDraftView> {
+  try {
+    return checked(await openSession(deps, api).mailSend(id), isDraft).draft;
+  } catch (error) {
+    throw mailFailure(error, id);
+  }
+}
+
+export async function discardMailDraft(deps: MailDeps, id: string, api?: string | null): Promise<MailDraftView> {
+  try {
+    return checked(await openSession(deps, api).mailDiscard(id), isDraft).draft;
+  } catch (error) {
+    throw mailFailure(error, id);
+  }
+}
+
+export async function getMailIdentity(deps: MailDeps, api?: string | null): Promise<MailIdentityView | null> {
+  try {
+    const answer = checked(await openSession(deps, api).mailIdentity(), (a) => "identity" in a);
+    return answer.identity;
+  } catch (error) {
+    throw mailFailure(error);
+  }
+}
+
+export interface IdentityInput {
+  fromName?: string | undefined;
+  replyTo?: string | undefined;
+  postalAddress?: string | undefined;
+  org?: string | undefined;
+}
+
+/** Saves the identity. Fields not given keep what is already saved. A new reply-to is emailed a link and sends nothing until it is opened. */
+export async function saveMailIdentity(deps: MailDeps, input: IdentityInput, api?: string | null): Promise<{ identity: MailIdentityView; verificationEmailed: boolean }> {
+  const client = openSession(deps, api);
+  try {
+    const existing = checked(await client.mailIdentity(), (a) => "identity" in a).identity;
+    const body = {
+      fromName: input.fromName ?? existing?.fromName ?? "",
+      replyTo: input.replyTo ?? existing?.replyTo ?? "",
+      postalAddress: input.postalAddress ?? existing?.postalAddress ?? "",
+      ...(input.org !== undefined ? { senderOrg: input.org } : existing?.senderOrg ? { senderOrg: existing.senderOrg } : {}),
+    };
+    const missing = [!body.fromName && "--from-name", !body.replyTo && "--reply-to", !body.postalAddress && "--postal-address"].filter(Boolean);
+    if (missing.length) throw new ApiFailure(`Your sender identity needs ${missing.join(", ")}.`, 'run `npx vfrey mail identity --from-name "Ana" --reply-to you@example.com --postal-address "1 Main St, City, Country"`.', undefined, "bad_request");
+    return checked(await client.mailSaveIdentity(body as MailIdentityBody), (a) => typeof a.identity?.replyTo === "string");
+  } catch (error) {
+    throw mailFailure(error);
+  }
+}
+
+// ---------- formatting ----------
+
+const clip = (t: string, n: number): string => (t.length > n ? `${t.slice(0, n - 1)}…` : t);
+const when = (iso: string | null | undefined): string => {
+  const t = iso ? Date.parse(iso) : NaN;
+  return Number.isFinite(t) ? new Date(t).toISOString().slice(0, 16).replace("T", " ") + " UTC" : DASH;
+};
+const recipient = (d: MailDraftView): string => (d.toName ? `${clean(d.toName)} <${clean(d.to)}>` : clean(d.to)) || "(no recipient yet)";
+
+export function statusLine(d: MailDraftView): string {
+  if (d.status === "sent") return `sent ${when(d.sentAt)}${d.deliveryStatus ? ` (${clean(d.deliveryStatus)})` : ""}`;
+  if (d.status === "approved") return `approved ${when(d.approvedAt)}, not sent yet`;
+  if (d.status === "failed") return `failed${d.error ? `: ${clean(d.error)}` : ""} (approve again to retry)`;
+  if (d.status === "discarded") return "discarded";
+  return "draft, not approved";
+}
+
+/** The next step for a draft in this status, as commands. Never says to run them for the person. */
+export function nextSteps(d: MailDraftView): string[] {
+  const id = clean(d.id);
+  if (d.status === "draft" || d.status === "failed") return [`A person reads it, and only if they say so for this draft: \`npx vfrey mail approve --id ${id}\`, then \`npx vfrey mail send --id ${id}\`.`, `Approving sends nothing. Edit it in the dashboard (\`npx vfrey open\`) or drop it with \`npx vfrey mail discard --id ${id}\`.`];
+  if (d.status === "approved") return [`Send it, only if the person says so: \`npx vfrey mail send --id ${id}\`.`];
+  return [];
+}
+
+export function formatDraft(d: MailDraftView, head?: string): string {
+  const lines = [];
+  if (head) lines.push(head, "");
+  lines.push(`Id:      ${clean(d.id)}`, `To:      ${recipient(d)}`, `Subject: ${clean(d.subject)}`, `Kind:    ${clean(d.kind)}${d.creatorRef ? ` · ${clean(d.creatorRef)}` : ""}`, `Status:  ${statusLine(d)}`, "", d.text.replace(/\r/g, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, "").replace(/vfr_[A-Za-z0-9_-]+/g, "[token]").trimEnd(), "");
+  const next = nextSteps(d);
+  if (next.length) lines.push(...next, "");
+  return lines.join("\n");
+}
+
+export function formatDrafts(drafts: MailDraftView[], status?: string): string {
+  if (drafts.length === 0) return `No ${status ? `${status} ` : ""}drafts. Write one with \`npx vfrey mail draft --kind creator_collab --creator @handle --platform tiktok --need "..."\`.\n`;
+  const rows = drafts.map((d) => [clean(d.id), d.status, clip(recipient(d), 36), clip(clean(d.subject), 48), clean(d.kind), when(d.createdAt).slice(0, 10)]);
+  const head = ["Id", "Status", "To", "Subject", "Kind", "Created"];
+  const width = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i]!.length)));
+  const line = (r: string[]) => r.map((cell, i) => cell.padEnd(width[i]!)).join("  ").trimEnd();
+  return [`Drafts: ${drafts.length}`, "", line(head), ...rows.map(line), "", "Read one with `npx vfrey mail show --id ID`. Nothing here is sent until a person approves and sends that draft.", ""].join("\n");
+}
+
+export function formatIdentity(identity: MailIdentityView | null, emailed?: boolean): string {
+  if (!identity) return 'No sender identity yet. Every message carries your name and postal address, so set it first:\n  npx vfrey mail identity --from-name "Ana" --reply-to you@example.com --postal-address "1 Main St, City, Country" [--org "Ana Co"]\n';
+  const lines = [
+    `From name:       ${clean(identity.fromName)}${identity.senderOrg ? ` (${clean(identity.senderOrg)})` : ""}`,
+    `Reply-to:        ${clean(identity.replyTo)}`,
+    `Postal address:  ${clean(identity.postalAddress)}`,
+    `Verified:        ${identity.verified ? `yes, ${when(identity.verifiedAt)}` : "NO. Nothing can be sent until the reply-to address is confirmed."}`,
+  ];
+  if (!identity.verified) lines.push("", emailed ? `We emailed a confirmation link to ${clean(identity.replyTo)}. Open it (it works for 24 hours), then check with \`npx vfrey mail identity\`.` : `Open the link we emailed to ${clean(identity.replyTo)}. Lost it? Run \`npx vfrey mail identity\` with the same flags to send a new one.`);
+  return lines.join("\n") + "\n";
+}
+
+// ---------- the command ----------
+
+const USAGE = [
+  "usage: npx vfrey mail draft --kind sponsor|brand|creator_collab|client_update --need TEXT [--creator @handle --platform P] [--to EMAIL] [--to-name N] [--tone T] [--json]",
+  "       npx vfrey mail drafts [--status draft|approved|sent|failed|discarded] [--json]",
+  "       npx vfrey mail show --id ID [--json]",
+  "       npx vfrey mail approve --id ID    (a person; sends nothing)",
+  "       npx vfrey mail send --id ID       (a person; the draft must be approved)",
+  "       npx vfrey mail discard --id ID",
+  "       npx vfrey mail identity [--from-name N --reply-to EMAIL --postal-address A --org NAME] [--json].",
+].join("\n");
+
+function refuse(io: ApiIo, message: string, fix: string): number {
+  io.stderr(`✗ ${message}\nFix: ${fix}\n`);
+  return 1;
+}
+
+function failure(io: ApiIo, error: unknown): number {
+  if (error instanceof ApiFailure || error instanceof ApiConfigError) return refuse(io, error.message, error.fix);
+  return refuse(io, error instanceof Error ? clean(error.message) : "Something went wrong.", "run `npx vfrey doctor` and check the line above.");
+}
+
+function parseArgs(args: string[], boolFlags: string[], valueFlags: string[]): { bools: Set<string>; values: Record<string, string>; positionals: string[]; error?: string } {
+  const bools = new Set<string>();
+  const values: Record<string, string> = {};
+  const positionals: string[] = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]!;
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    const name = eq > 0 ? arg.slice(0, eq) : arg;
+    if (boolFlags.includes(name)) bools.add(name);
+    else if (valueFlags.includes(name)) {
+      const next = args[i + 1];
+      const value = eq > 0 ? arg.slice(eq + 1) : next !== undefined && !next.startsWith("--") ? args[(i += 1)]! : "";
+      if (!value.trim()) return { bools, values, positionals, error: `${name} needs a value.` };
+      values[name] = value;
+    } else return { bools, values, positionals, error: `Unknown option "${arg}".` };
+  }
+  return { bools, values, positionals };
+}
+
+const json = (v: unknown): string => JSON.stringify(v, null, 2) + "\n";
+
+export async function runMail(args: string[], io: ApiIo): Promise<number> {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const deps: MailDeps = { env: io.env, ...(io.homedir ? { homedir: io.homedir } : {}), ...(io.platform ? { platform: io.platform } : {}), ...(io.run ? { run: io.run } : {}), ...(io.fetch ? { fetch: io.fetch } : {}), ...(io.timeoutMs ? { timeoutMs: io.timeoutMs } : {}) };
+  try {
+    if (sub === "draft") {
+      const p = parseArgs(rest, ["--json"], ["--kind", "--creator", "--platform", "--to", "--to-name", "--need", "--tone", "--api"]);
+      if (p.error || p.positionals.length) return refuse(io, p.error ?? `Unexpected "${p.positionals[0]}".`, USAGE);
+      const kind = p.values["--kind"]?.trim().toLowerCase();
+      if (!kind || !(MAIL_KINDS as readonly string[]).includes(kind)) return refuse(io, kind ? `--kind must be one of ${MAIL_KINDS.join(", ")}.` : "Say what kind of message: --kind sponsor, brand, creator_collab or client_update.", USAGE);
+      const need = p.values["--need"]?.trim();
+      if (!need) return refuse(io, "Say what the message should ask or say: --need TEXT.", 'for example `npx vfrey mail draft --kind creator_collab --creator @ana.cooks --platform tiktok --need "a paid 30 second demo of our app"`.');
+      const body: MailDraftBody = { kind, need };
+      const creator = p.values["--creator"];
+      const platform = p.values["--platform"]?.trim().toLowerCase();
+      if (creator) {
+        const handle = normalizeHandle(creator);
+        if (!platform || !(CREATOR_PLATFORM_IDS as readonly string[]).includes(platform)) return refuse(io, "Say which platform the creator is on: --platform tiktok, instagram or youtube.", USAGE);
+        if (!/^[a-z0-9._-]{1,80}$/i.test(handle)) return refuse(io, "That creator handle does not look right.", "use letters, numbers, dots, dashes and underscores, like @ana.cooks.");
+        body.creator = { platform, handle };
+      } else if (platform) return refuse(io, "--platform goes with --creator.", USAGE);
+      if (p.values["--to"]) body.to = p.values["--to"].trim();
+      if (p.values["--to-name"]) body.toName = p.values["--to-name"].trim();
+      if (p.values["--tone"]) body.tone = p.values["--tone"].trim();
+      const draft = await createMailDraft(deps, body, p.values["--api"]);
+      io.stdout(p.bools.has("--json") ? json({ draft }) : formatDraft(draft, `✓ Draft written. Nothing was sent, and nothing is sent until a person approves and sends it.`));
+      return 0;
+    }
+    if (sub === "drafts") {
+      const p = parseArgs(rest, ["--json"], ["--status", "--api"]);
+      if (p.error || p.positionals.length) return refuse(io, p.error ?? `Unexpected "${p.positionals[0]}".`, USAGE);
+      const status = p.values["--status"]?.trim().toLowerCase();
+      if (status && !(MAIL_STATUSES as readonly string[]).includes(status)) return refuse(io, `--status must be one of ${MAIL_STATUSES.join(", ")}.`, USAGE);
+      const drafts = await listMailDrafts(deps, status ? { status } : {}, p.values["--api"]);
+      io.stdout(p.bools.has("--json") ? json({ drafts }) : formatDrafts(drafts, status));
+      return 0;
+    }
+    if (sub === "show" || sub === "approve" || sub === "send" || sub === "discard") {
+      const p = parseArgs(rest, ["--json"], ["--id", "--api"]);
+      if (p.error || p.positionals.length) return refuse(io, p.error ?? `Unexpected "${p.positionals[0]}".`, USAGE);
+      const id = p.values["--id"]?.trim();
+      if (!id) return refuse(io, `Say which draft: mail ${sub} --id ID.`, "list your drafts with `npx vfrey mail drafts`.");
+      const want = p.bools.has("--json");
+      if (sub === "show") {
+        const draft = await getMailDraft(deps, id, p.values["--api"]);
+        io.stdout(want ? json({ draft }) : formatDraft(draft));
+      } else if (sub === "approve") {
+        const draft = await approveMailDraft(deps, id, p.values["--api"]);
+        io.stdout(want ? json({ draft }) : `✓ Approved ${clean(draft.id)} for ${recipient(draft)}. Nothing was sent.\nSend it, only if the person says so: \`npx vfrey mail send --id ${clean(draft.id)}\`.\n`);
+      } else if (sub === "send") {
+        const draft = await sendMailDraft(deps, id, p.values["--api"]);
+        io.stdout(want ? json({ draft }) : `✓ Sent ${clean(draft.id)} to ${recipient(draft)} at ${when(draft.sentAt)}.\nOne send was charged. Replies go to your reply-to address. See it with \`npx vfrey mail show --id ${clean(draft.id)}\`.\n`);
+      } else {
+        const draft = await discardMailDraft(deps, id, p.values["--api"]);
+        io.stdout(want ? json({ draft }) : `✓ Discarded ${clean(draft.id)}. It will not be sent.\n`);
+      }
+      return 0;
+    }
+    if (sub === "identity") {
+      const p = parseArgs(rest, ["--json"], ["--from-name", "--reply-to", "--postal-address", "--org", "--api"]);
+      if (p.error || p.positionals.length) return refuse(io, p.error ?? `Unexpected "${p.positionals[0]}".`, USAGE);
+      const changing = ["--from-name", "--reply-to", "--postal-address", "--org"].some((f) => p.values[f] !== undefined);
+      if (!changing) {
+        const identity = await getMailIdentity(deps, p.values["--api"]);
+        io.stdout(p.bools.has("--json") ? json({ identity }) : formatIdentity(identity));
+        return 0;
+      }
+      const saved = await saveMailIdentity(deps, { fromName: p.values["--from-name"], replyTo: p.values["--reply-to"]?.toLowerCase(), postalAddress: p.values["--postal-address"], org: p.values["--org"] }, p.values["--api"]);
+      io.stdout(p.bools.has("--json") ? json(saved) : `✓ Saved your sender identity.\n\n${formatIdentity(saved.identity, saved.verificationEmailed)}`);
+      return 0;
+    }
+    return refuse(io, sub ? `Unknown mail command "${clean(sub)}".` : "Say what to do with mail.", USAGE);
+  } catch (error) {
+    return failure(io, error);
+  }
+}

package/src/api/topics.ts

@@ -0,0 +1,207 @@
+// vfrey Topics (spec 016): `vfrey topics`, `topics niches`, `topics request`, and the one session helper the series source and the desk route share.
+// Every call goes through ApiClient; the token is read from the token store here and never leaves this process.
+import os from "node:os";
+import { ApiClient, ApiFailure, clean, type FetchLike } from "./client.js";
+import { ApiConfigError, apiHost, resolveApiUrl } from "./config.js";
+import { loadToken, type CredentialDeps, type Runner } from "./credentials.js";
+import type { ApiIo } from "./commands.js";
+import type { NicheView, TopicsResponse } from "./types.js";
+import type { Topic, TopicEvidence } from "@vfrey/contracts";
+
+type Env = Record<string, string | undefined>;
+
+/** What a topics call needs: where the server is and how to find the token. */
+export interface TopicsDeps {
+  env: Env;
+  homedir?: string;
+  platform?: NodeJS.Platform;
+  run?: Runner;
+  fetch?: FetchLike;
+  timeoutMs?: number;
+}
+
+function credsOf(deps: TopicsDeps): CredentialDeps {
+  return { env: deps.env, homedir: deps.homedir ?? os.homedir(), ...(deps.platform ? { platform: deps.platform } : {}), ...(deps.run ? { run: deps.run } : {}) };
+}
+
+/** A client for the signed-in person. Throws ApiFailure (not live, not signed in) or ApiConfigError. */
+export function openSession(deps: TopicsDeps, api?: string | null): ApiClient {
+  const base = resolveApiUrl(deps.env, api ?? null);
+  if (!base) {
+    throw new ApiFailure("vfrey accounts are not live yet.", "free features work without an account. If you run your own vfrey server, set VFREY_API_URL or pass --api <url>.", undefined, "not_live");
+  }
+  const found = loadToken(apiHost(base), credsOf(deps));
+  if (!found) throw new ApiFailure("You are not signed in.", "run `npx vfrey login`.", undefined, "not_signed_in");
+  return new ApiClient({ baseUrl: base, token: found.token, ...(deps.fetch ? { fetch: deps.fetch } : {}), ...(deps.timeoutMs ? { timeoutMs: deps.timeoutMs } : {}) });
+}
+
+/** Input mistakes the server names (400, 404, 409) get a Fix that fits them. */
+export function withInputFix(error: unknown, fix: string): unknown {
+  if (error instanceof ApiFailure && (error.status === 400 || error.status === 404 || error.status === 409)) {
+    return new ApiFailure(error.message, fix, error.status, error.code);
+  }
+  return error;
+}
+
+export async function fetchTopics(deps: TopicsDeps, query: { niche: string; limit?: number; since?: string }, api?: string | null): Promise<TopicsResponse> {
+  const client = openSession(deps, api);
+  try {
+    const answer = await client.topics(query);
+    if (!answer || !Array.isArray(answer.topics)) {
+      throw new ApiFailure("The vfrey server sent an answer this version does not understand.", "update vfrey with `npx vfrey update`.");
+    }
+    return answer;
+  } catch (error) {
+    throw withInputFix(error, "list the niche ids with `npx vfrey topics niches`.");
+  }
+}
+
+export async function fetchNiches(deps: TopicsDeps, api?: string | null): Promise<NicheView[]> {
+  const answer = await openSession(deps, api).niches();
+  if (!answer || !Array.isArray(answer.niches)) {
+    throw new ApiFailure("The vfrey server sent an answer this version does not understand.", "update vfrey with `npx vfrey update`.");
+  }
+  return answer.niches;
+}
+
+// ---------- formatting ----------
+
+export function formatViews(views: number | undefined | null): string {
+  if (typeof views !== "number" || !Number.isFinite(views)) return "—";
+  if (views >= 1_000_000) return `${(views / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+  if (views >= 1_000) return `${(views / 1_000).toFixed(1).replace(/\.0$/, "")}K`;
+  return String(Math.round(views));
+}
+
+export function formatAge(hours: number | undefined | null): string {
+  if (typeof hours !== "number" || !Number.isFinite(hours) || hours < 0) return "—";
+  if (hours < 1) return "<1h";
+  if (hours < 48) return `${Math.round(hours)}h`;
+  return `${Math.round(hours / 24)}d`;
+}
+
+const httpUrl = (url: unknown): string => {
+  const text = clean(url);
+  return /^https?:\/\//i.test(text) ? text : "";
+};
+
+function evidenceLine(item: TopicEvidence): string {
+  const url = httpUrl(item.url) || "(no link)";
+  return `${url}  ${formatViews(item.views)} views · ${formatAge(item.ageHours)} old${item.why ? ` · ${clean(item.why)}` : ""}`;
+}
+
+export function formatTopics(answer: TopicsResponse, nicheId: string): string {
+  const name = answer.niche ? clean(answer.niche.name) : clean(nicheId);
+  const lines = [`Topics for ${name} (${clean(answer.niche?.id ?? nicheId)}): ${answer.topics.length}`];
+  if (answer.topics.length === 0) lines.push("No topics yet. The niche is collected on a schedule; try again later.");
+  answer.topics.forEach((topic: Topic, index) => {
+    lines.push("", `${String(index + 1).padStart(2)}. ${clean(topic.title)}  score ${Number(topic.score).toFixed(1)}  ${(topic.platforms ?? []).map((p) => clean(p)).join(", ")}`);
+    for (const item of topic.evidence ?? []) lines.push(`      ${evidenceLine(item)}`);
+  });
+  const run = answer.lastRun;
+  if (run && !/^(ok|success|succeeded|done)$/i.test(run.status)) lines.push("", `Note: the last collection was ${clean(run.status)} (${clean(run.at)}); these are the last stored topics.`);
+  else if (answer.lastCollectedAt) lines.push("", `Collected ${clean(answer.lastCollectedAt)}.`);
+  lines.push("Topics use credits. See your balance with `npx vfrey whoami`.");
+  return lines.join("\n") + "\n";
+}
+
+export function formatNiches(niches: NicheView[]): string {
+  if (niches.length === 0) return "No niches yet.\n";
+  const width = Math.max(...niches.map((n) => clean(n.id).length));
+  const lines = niches.map((n) => `${clean(n.id).padEnd(width)}  ${clean(n.name)}${n.custom ? " (yours)" : ""}  ${(n.platforms ?? []).map((p) => clean(p)).join(", ")}  [${(n.keywords ?? []).map((k) => clean(k)).join(", ")}]`);
+  return [...lines, "", "Read one with `npx vfrey topics --niche ID`. Listing niches is free."].join("\n") + "\n";
+}
+
+// ---------- the command ----------
+
+const USAGE = "usage: npx vfrey topics [--niche ID] [--limit N] [--since ISO] [--json] | topics niches [--json] | topics request --name N --keywords a,b [--hashtags a,b] [--platforms tiktok,youtube].";
+
+function refuse(io: ApiIo, message: string, fix: string): number {
+  io.stderr(`✗ ${message}\nFix: ${fix}\n`);
+  return 1;
+}
+
+function failure(io: ApiIo, error: unknown): number {
+  if (error instanceof ApiFailure || error instanceof ApiConfigError) return refuse(io, error.message, error.fix);
+  return refuse(io, error instanceof Error ? clean(error.message) : "Something went wrong.", "run `npx vfrey doctor` and check the line above.");
+}
+
+/** Reads `--name value` and `--name=value` flags. Unknown flags are an error. */
+function parseFlags(args: string[], boolFlags: string[], valueFlags: string[]): { bools: Set<string>; values: Record<string, string>; error?: string } {
+  const bools = new Set<string>();
+  const values: Record<string, string> = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]!;
+    const eq = arg.indexOf("=");
+    const name = eq > 0 ? arg.slice(0, eq) : arg;
+    if (boolFlags.includes(name)) bools.add(name);
+    else if (valueFlags.includes(name)) {
+      const value = eq > 0 ? arg.slice(eq + 1) : args[i + 1] && !args[i + 1]!.startsWith("--") ? args[(i += 1)]! : "";
+      if (!value) return { bools, values, error: `${name} needs a value.` };
+      values[name] = value;
+    } else return { bools, values, error: `Unknown option "${arg}".` };
+  }
+  return { bools, values };
+}
+
+const list = (text: string): string[] => text.split(",").map((part) => part.trim()).filter(Boolean);
+
+export async function runTopics(args: string[], io: ApiIo): Promise<number> {
+  const sub = args[0] === "niches" || args[0] === "request" ? args[0] : null;
+  const rest = sub ? args.slice(1) : args;
+  const deps: TopicsDeps = { env: io.env, ...(io.homedir ? { homedir: io.homedir } : {}), ...(io.platform ? { platform: io.platform } : {}), ...(io.run ? { run: io.run } : {}), ...(io.fetch ? { fetch: io.fetch } : {}), ...(io.timeoutMs ? { timeoutMs: io.timeoutMs } : {}) };
+  try {
+    if (sub === "niches") {
+      const p = parseFlags(rest, ["--json"], ["--api"]);
+      if (p.error) return refuse(io, p.error, USAGE);
+      const niches = await fetchNiches(deps, p.values["--api"]);
+      io.stdout(p.bools.has("--json") ? JSON.stringify({ niches }, null, 2) + "\n" : formatNiches(niches));
+      return 0;
+    }
+    if (sub === "request") {
+      const p = parseFlags(rest, ["--json"], ["--name", "--keywords", "--hashtags", "--platforms", "--api"]);
+      if (p.error) return refuse(io, p.error, USAGE);
+      const name = p.values["--name"]?.trim();
+      const keywords = list(p.values["--keywords"] ?? "");
+      if (!name || keywords.length === 0) return refuse(io, "A niche request needs --name and --keywords.", USAGE);
+      const body: { name: string; keywords: string[]; hashtags?: string[]; platforms?: never } = { name, keywords };
+      if (p.values["--hashtags"]) body.hashtags = list(p.values["--hashtags"]);
+      const client = openSession(deps, p.values["--api"]);
+      let answer;
+      try {
+        answer = await client.requestNiche({ ...body, ...(p.values["--platforms"] ? { platforms: list(p.values["--platforms"]) as never } : {}) });
+      } catch (error) {
+        throw withInputFix(error, "check the name, keywords and platforms, or list your niches with `npx vfrey topics niches`.");
+      }
+      if (p.bools.has("--json")) io.stdout(JSON.stringify(answer, null, 2) + "\n");
+      else {
+        const cost = typeof answer.creditsCharged === "number" ? ` It cost ${answer.creditsCharged} credits.` : "";
+        io.stdout(`✓ Requested niche "${clean(answer.niche.name)}" (${clean(answer.niche.id)}).${cost} It is collected on the next run.\nRead it later with \`npx vfrey topics --niche ${clean(answer.niche.id)}\`. See your credits with \`npx vfrey whoami\`.\n`);
+      }
+      return 0;
+    }
+    const p = parseFlags(rest, ["--json"], ["--niche", "--limit", "--since", "--api"]);
+    if (p.error) return refuse(io, p.error, USAGE);
+    const query: { niche: string; limit?: number; since?: string } = { niche: "" };
+    if (p.values["--limit"] !== undefined) {
+      const limit = Number(p.values["--limit"]);
+      if (!Number.isInteger(limit) || limit < 1 || limit > 100) return refuse(io, "--limit must be a whole number from 1 to 100.", USAGE);
+      query.limit = limit;
+    }
+    if (p.values["--since"] !== undefined) {
+      if (Number.isNaN(new Date(p.values["--since"]).getTime())) return refuse(io, "--since must be an ISO date, like 2026-10-26T00:00:00Z.", USAGE);
+      query.since = p.values["--since"];
+    }
+    const nicheId = p.values["--niche"]?.trim();
+    if (!nicheId) {
+      const niches = await fetchNiches(deps, p.values["--api"]);
+      return refuse(io, "Pick a niche to read topics for.", `run \`npx vfrey topics --niche ID\`. Niches: ${niches.slice(0, 12).map((n) => clean(n.id)).join(", ") || "none yet"}.`);
+    }
+    query.niche = nicheId;
+    const answer = await fetchTopics(deps, query, p.values["--api"]);
+    io.stdout(p.bools.has("--json") ? JSON.stringify(answer, null, 2) + "\n" : formatTopics(answer, nicheId));
+    return 0;
+  } catch (error) {
+    return failure(io, error);
+  }
+}