@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/api/creators.ts

@@ -0,0 +1,463 @@
+// vfrey Creators (spec 017): `creators search | show | watch | export | alerts`, and the helpers the desk route shares.
+// Every call goes through ApiClient; the token is read from the token store in openSession and never leaves this process.
+import { ApiFailure, clean } from "./client.js";
+import { ApiConfigError } from "./config.js";
+import type { ApiIo } from "./commands.js";
+import { formatAge, formatViews, openSession, withInputFix, type TopicsDeps } from "./topics.js";
+import type { BreakoutView, CreatorAlertsResponse, CreatorProfileView, CreatorSummaryView, WatchlistItemView, WatchlistView } from "./types.js";
+
+export type CreatorsDeps = TopicsDeps;
+
+export const CREATOR_PLATFORM_IDS = ["tiktok", "instagram", "youtube"] as const;
+export const CREATOR_SORTS = ["engagement", "growth", "views", "followers"] as const;
+const PLATFORM_NAMES: Record<string, string> = { tiktok: "TikTok", instagram: "Instagram", youtube: "YouTube" };
+const platformName = (p: string): string => PLATFORM_NAMES[p] ?? clean(p);
+export const DEFAULT_WATCHLIST = "Watching";
+
+// ---------- input: "10k-200k", "4%", "@Handle" ----------
+
+/** "10k", "1.5m", "200000" to a number, or null. */
+export function parseCount(text: string): number | null {
+  const m = /^(\d+(?:\.\d+)?)([km]?)$/i.exec(text.trim());
+  if (!m) return null;
+  const unit = m[2]!.toLowerCase();
+  const n = Number(m[1]) * (unit === "k" ? 1_000 : unit === "m" ? 1_000_000 : 1);
+  return Number.isFinite(n) ? Math.round(n) : null;
+}
+
+/** "10k-200k", "10k-" (at least), "-200k" (at most) or "10k" (at least). */
+export function parseFollowers(text: string): { min?: number; max?: number } | null {
+  const t = text.trim();
+  if (!t) return null;
+  if (!t.includes("-")) {
+    const n = parseCount(t);
+    return n === null ? null : { min: n };
+  }
+  const [lo = "", hi = "", ...extra] = t.split("-");
+  if (extra.length > 0 || (!lo && !hi)) return null;
+  const min = lo ? parseCount(lo) : undefined;
+  const max = hi ? parseCount(hi) : undefined;
+  if (min === null || max === null) return null;
+  if (min !== undefined && max !== undefined && min > max) return null;
+  return { ...(min !== undefined ? { min } : {}), ...(max !== undefined ? { max } : {}) };
+}
+
+/** "4%" or "0.04": returns the text the server takes, or null. */
+export function parseEngagement(text: string): string | null {
+  const t = text.trim();
+  return /^(\d+(?:\.\d+)?)(%?)$/.test(t) ? t : null;
+}
+
+export function normalizeHandle(text: string): string {
+  return text.trim().replace(/^@+/, "").toLowerCase();
+}
+
+export interface SearchInput {
+  niche?: string | undefined;
+  platform?: string | undefined;
+  followers?: string | undefined;
+  postsPerWeek?: string | undefined;
+  engagement?: string | undefined;
+  sort?: string | undefined;
+  limit?: string | undefined;
+}
+
+/** Validates the search inputs and returns the server's query fields, or the mistake in the person's words. */
+export function buildSearchQuery(input: SearchInput): { query: Record<string, string> } | { error: string } {
+  const query: Record<string, string> = {};
+  if (input.niche?.trim()) query.niche = input.niche.trim();
+  if (input.platform) {
+    const list = input.platform.split(",").map((p) => p.trim().toLowerCase()).filter(Boolean);
+    if (list.length === 0 || !list.every((p) => (CREATOR_PLATFORM_IDS as readonly string[]).includes(p))) return { error: "--platform must be a comma list of tiktok, instagram, youtube." };
+    query.platforms = list.join(",");
+  }
+  if (input.followers) {
+    const range = parseFollowers(input.followers);
+    if (!range) return { error: "--followers must look like 10k-200k, 10k- (at least) or -200k (at most)." };
+    if (range.min !== undefined) query.followersMin = String(range.min);
+    if (range.max !== undefined) query.followersMax = String(range.max);
+  }
+  if (input.postsPerWeek) {
+    const n = Number(input.postsPerWeek);
+    if (!Number.isFinite(n) || n < 0) return { error: "--posts-per-week must be a number of 0 or more." };
+    query.postsPerWeekMin = String(n);
+  }
+  if (input.engagement) {
+    const e = parseEngagement(input.engagement);
+    if (e === null) return { error: "--engagement must look like 4% or 0.04." };
+    query.engagementMin = e;
+  }
+  if (input.sort) {
+    if (!(CREATOR_SORTS as readonly string[]).includes(input.sort)) return { error: `--sort must be one of ${CREATOR_SORTS.join(", ")}.` };
+    query.sort = input.sort;
+  }
+  if (input.limit !== undefined) {
+    const n = Number(input.limit);
+    if (!Number.isInteger(n) || n < 1 || n > 100) return { error: "--limit must be a whole number from 1 to 100." };
+    query.limit = String(n);
+  }
+  return { query };
+}
+
+const SEARCH_FIX = "list the niche ids with `npx vfrey topics niches`.";
+const PROFILE_FIX = "check the platform and handle, like `npx vfrey creators show @name --platform tiktok`.";
+const WATCH_FIX = "list your watchlists with `npx vfrey creators watch list`.";
+
+// ---------- server calls ----------
+
+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;
+}
+
+export async function searchCreators(deps: CreatorsDeps, query: Record<string, string>, api?: string | null): Promise<CreatorSummaryView[]> {
+  try {
+    return checked(await openSession(deps, api).creatorSearch(query), (a) => Array.isArray(a.creators)).creators;
+  } catch (error) {
+    throw withInputFix(error, SEARCH_FIX);
+  }
+}
+
+export async function fetchProfile(deps: CreatorsDeps, platform: string, handle: string, api?: string | null): Promise<CreatorProfileView> {
+  try {
+    return checked(await openSession(deps, api).creatorProfile(platform, normalizeHandle(handle)), (a) => typeof a.handle === "string");
+  } catch (error) {
+    throw withInputFix(error, PROFILE_FIX);
+  }
+}
+
+export async function fetchAlerts(deps: CreatorsDeps, api?: string | null): Promise<CreatorAlertsResponse> {
+  return checked(await openSession(deps, api).creatorAlerts(), (a) => Array.isArray(a.alerts));
+}
+
+export async function fetchWatchlists(deps: CreatorsDeps, api?: string | null): Promise<WatchlistView[]> {
+  return checked(await openSession(deps, api).watchlists(), (a) => Array.isArray(a.watchlists)).watchlists;
+}
+
+export async function fetchWatchlistItems(deps: CreatorsDeps, id: string, api?: string | null): Promise<{ watchlist: { id: string; name: string }; items: WatchlistItemView[] }> {
+  try {
+    return checked(await openSession(deps, api).watchlistItems(id), (a) => Array.isArray(a.items));
+  } catch (error) {
+    throw withInputFix(error, WATCH_FIX);
+  }
+}
+
+/** A watchlist by id or by (case-insensitive) name. */
+export function findWatchlist(lists: WatchlistView[], key: string): WatchlistView | undefined {
+  const k = key.trim().toLowerCase();
+  return lists.find((w) => w.id === key.trim()) ?? lists.find((w) => w.name.trim().toLowerCase() === k);
+}
+
+/** Adds a creator to a watchlist by name or id, making the watchlist when the name is new. */
+export async function addToWatchlist(deps: CreatorsDeps, key: string, platform: string, handle: string, api?: string | null): Promise<{ watchlist: { id: string; name: string }; created: boolean; madeList: boolean }> {
+  const client = openSession(deps, api);
+  const lists = checked(await client.watchlists(), (a) => Array.isArray(a.watchlists)).watchlists;
+  let list: { id: string; name: string } | undefined = findWatchlist(lists, key);
+  let madeList = false;
+  if (!list) {
+    list = checked(await client.createWatchlist(key.trim()), (a) => typeof a.id === "string");
+    madeList = true;
+  }
+  try {
+    const added = await client.addWatch(list.id, { platform, handle: normalizeHandle(handle) });
+    return { watchlist: list, created: added.created === true, madeList };
+  } catch (error) {
+    throw withInputFix(error, "check the platform and handle, like `npx vfrey creators watch add @name --platform tiktok`.");
+  }
+}
+
+export async function removeFromWatchlist(deps: CreatorsDeps, key: string, platform: string, handle: string, api?: string | null): Promise<{ id: string; name: string }> {
+  const client = openSession(deps, api);
+  const lists = checked(await client.watchlists(), (a) => Array.isArray(a.watchlists)).watchlists;
+  const list = findWatchlist(lists, key);
+  if (!list) throw new ApiFailure(`No watchlist called "${clean(key)}".`, WATCH_FIX, 404, "not_found");
+  try {
+    await client.removeWatch(list.id, platform, normalizeHandle(handle));
+  } catch (error) {
+    throw withInputFix(error, `see who is on it with \`npx vfrey creators watch list --watchlist ${clean(list.name)}\`.`);
+  }
+  return list;
+}
+
+export async function exportWatchlist(deps: CreatorsDeps, key: string, api?: string | null): Promise<string> {
+  const client = openSession(deps, api);
+  const lists = checked(await client.watchlists(), (a) => Array.isArray(a.watchlists)).watchlists;
+  const list = findWatchlist(lists, key);
+  if (!list) throw new ApiFailure(`No watchlist called "${clean(key)}".`, WATCH_FIX, 404, "not_found");
+  return client.watchlistCsv(list.id);
+}
+
+// ---------- formatting: unknown is "—", never 0 ----------
+
+const DASH = "—";
+const count = (n: number | null | undefined): string => (typeof n === "number" && Number.isFinite(n) ? formatViews(n) : DASH);
+const pct = (fraction: number | null | undefined): string => (typeof fraction === "number" && Number.isFinite(fraction) ? `${(fraction * 100).toFixed(1).replace(/\.0$/, "")}%` : DASH);
+const signedPct = (fraction: number | null | undefined): string => (typeof fraction === "number" && Number.isFinite(fraction) ? `${fraction >= 0 ? "+" : ""}${(fraction * 100).toFixed(1).replace(/\.0$/, "")}%` : DASH);
+const httpUrl = (url: unknown): string => (/^https?:\/\//i.test(clean(url)) ? clean(url) : "");
+const nicheList = (c: { niches?: string[] }): string => (c.niches ?? []).map((n) => clean(n)).join(", ") || DASH;
+const growthLabel = (g: { abs?: number; pct?: number } | undefined, pctFallback?: number): string => {
+  if (typeof g?.pct === "number") return signedPct(g.pct);
+  if (typeof g?.abs === "number") return `${g.abs >= 0 ? "+" : ""}${g.abs} followers`;
+  return typeof pctFallback === "number" ? signedPct(pctFallback) : DASH;
+};
+
+export function engagementLabel(c: { engagementRate?: number | null; engagementBasis?: string | null }): string {
+  if (typeof c.engagementRate !== "number") return DASH;
+  return `${pct(c.engagementRate)} of ${c.engagementBasis === "followers" ? "followers" : c.engagementBasis === "views" ? "views" : "views or followers (basis unknown)"}`;
+}
+
+export function postsPerWeekLabel(c: { postsPerWeek?: number | null }, basis?: string | null): string {
+  if (typeof c.postsPerWeek !== "number") return DASH;
+  const n = Number(c.postsPerWeek.toFixed(1));
+  return `${n}${basis === "30d" ? " (last 30 days)" : basis === "sample" ? " (over the recent posts only)" : ""}`;
+}
+
+export function formatSearch(creators: CreatorSummaryView[]): string {
+  if (creators.length === 0) return "No creators match. Loosen a filter, or try another niche.\n";
+  const rows = creators.map((c) => [
+    `@${clean(c.handle)}`,
+    platformName(c.platform),
+    count(c.followers),
+    typeof c.engagementRate === "number" ? `${pct(c.engagementRate)}${c.engagementBasis === "followers" ? " fol" : c.engagementBasis === "views" ? " views" : ""}` : DASH,
+    count(c.medianViews),
+    typeof c.postsPerWeek === "number" ? String(Number(c.postsPerWeek.toFixed(1))) : DASH,
+    signedPct(c.growth30d),
+    nicheList(c),
+  ]);
+  const head = ["Creator", "Platform", "Followers", "Engagement", "Med. views", "Posts/wk", "30d growth", "Niches"];
+  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 [
+    `Creators: ${creators.length}`,
+    "",
+    line(head),
+    ...rows.map(line),
+    "",
+    "— means the number is not known yet. Engagement says what it is a share of (views or followers); do not compare across the two.",
+    "Read one with `npx vfrey creators show @handle --platform tiktok`. Search uses credits; see your balance with `npx vfrey whoami`.",
+    "",
+  ].join("\n");
+}
+
+export function formatProfile(p: CreatorProfileView): string {
+  const s = p.stats ?? {};
+  const lines: string[] = [];
+  lines.push(`@${clean(p.handle)} · ${platformName(p.platform)}${p.displayName ? ` · ${clean(p.displayName)}` : ""}${p.verified ? " · verified" : ""}`);
+  lines.push(`Followers ${count(p.followers)} · Following ${count(p.following)} · Posts ${count(p.postCount)} · Likes ${count(p.totalLikes)}`);
+  lines.push(`Niches: ${nicheList(p)}`);
+  if (p.bio) lines.push(`Bio: ${clean(p.bio)}`);
+  lines.push("");
+  lines.push(`Stats${typeof s.sampleSize === "number" ? ` (from ${s.sampleSize} recent posts)` : ""}`);
+  lines.push(`  Median views    ${count(p.medianViews)}`);
+  lines.push(`  Engagement      ${engagementLabel(p)}`);
+  lines.push(`  Posts per week  ${postsPerWeekLabel(p, s.postsPerWeekBasis)}`);
+  lines.push(`  Follower growth 7d ${growthLabel(s.growth7d, p.growth7d)} · 30d ${growthLabel(s.growth30d, p.growth30d)}`);
+  lines.push(`  Median length   ${typeof s.medianLengthSec === "number" ? `${Math.round(s.medianLengthSec)}s` : DASH}`);
+  if (s.postingTimes && s.postingTimes.bestHours?.length) lines.push(`  Best hours      ${s.postingTimes.bestHours.slice(0, 3).map((h) => `${String(h).padStart(2, "0")}:00`).join(", ")} (${clean(s.postingTimes.timeZone)})`);
+  lines.push("");
+  lines.push(`Formats (${p.formats?.length ?? 0})`);
+  if (!p.formats?.length) lines.push("  None found yet.");
+  for (const f of p.formats ?? []) lines.push(`  ${clean(f.name)} · ${f.postCount} posts · ${(f.terms ?? []).map((t) => clean(t)).join(", ")}`);
+  lines.push("");
+  lines.push(`Hooks (${p.hooks?.length ?? 0})`);
+  if (!p.hooks?.length) lines.push("  None found yet.");
+  for (const h of p.hooks ?? []) lines.push(`  "${clean(h.text)}"`);
+  lines.push("");
+  lines.push(`Top posts (${p.topPosts?.length ?? 0})`);
+  if (!p.topPosts?.length) lines.push("  None found yet.");
+  for (const t of p.topPosts ?? []) {
+    const posted = Date.parse(t.postedAt);
+    lines.push(`  ${httpUrl(t.url) || "(no link)"}  ${count(t.metrics?.views)} views · ${count(t.metrics?.likes)} likes · posted ${Number.isFinite(posted) ? clean(t.postedAt).slice(0, 10) : DASH}${t.caption ? ` · ${clean(t.caption).slice(0, 80)}` : ""}`);
+  }
+  lines.push("");
+  lines.push(p.businessContact ? `Business contact (from their public bio): ${clean(p.businessContact.value)}` : "Business contact: none in their public bio.");
+  if (p.profileAt) lines.push(`Profile data from ${clean(p.profileAt)}${p.refreshed ? " (refreshed now)" : ""}.`);
+  lines.push("Use their formats and hooks to learn what works, then design your own scene. Do not copy their videos.");
+  return lines.join("\n") + "\n";
+}
+
+export function formatWatchlists(lists: WatchlistView[]): string {
+  if (lists.length === 0) return "No watchlists yet. Add a creator with `npx vfrey creators watch add @handle --platform tiktok`.\n";
+  const width = Math.max(...lists.map((l) => clean(l.name).length));
+  return [...lists.map((l) => `${clean(l.name).padEnd(width)}  ${l.items} creator${l.items === 1 ? "" : "s"}  (${clean(l.id)})`), "", "See one with `npx vfrey creators watch list --watchlist NAME`. Watchlists are free.", ""].join("\n");
+}
+
+export function formatWatchItems(answer: { watchlist: { id: string; name: string }; items: WatchlistItemView[] }): string {
+  const lines = [`${clean(answer.watchlist.name)} (${clean(answer.watchlist.id)}): ${answer.items.length}`];
+  if (answer.items.length === 0) lines.push("Nobody yet.");
+  for (const i of answer.items) lines.push(`  @${clean(i.handle)}  ${platformName(i.platform)}  ${count(i.followers)} followers${i.displayName ? `  ${clean(i.displayName)}` : ""}`);
+  lines.push("", `Export with \`npx vfrey creators export --watchlist ${clean(answer.watchlist.id)} > watchlist.csv\`.`);
+  return lines.join("\n") + "\n";
+}
+
+export function formatAlerts(answer: CreatorAlertsResponse): string {
+  const lines = [`Breakouts on creators you watch: ${answer.alerts.length}`, `A post counts when it has ${answer.rule?.multiple ?? 5}x the creator's median views within ${answer.rule?.withinHours ?? 48} hours.`];
+  if (answer.alerts.length === 0) lines.push("", "No breakouts right now.");
+  answer.alerts.forEach((b: BreakoutView, i) => {
+    lines.push("", `${String(i + 1).padStart(2)}. @${clean(b.creator.handle)} (${platformName(b.creator.platform)})  ${b.multiple}x their median`);
+    lines.push(`      ${httpUrl(b.url) || "(no link)"}  ${formatViews(b.views)} views (median ${formatViews(b.medianViews)}) · ${formatAge(b.ageHours)} old`);
+    if (b.caption) lines.push(`      ${clean(b.caption).slice(0, 100)}`);
+  });
+  lines.push("", "Alerts use credits. See your balance with `npx vfrey whoami`.");
+  return lines.join("\n") + "\n";
+}
+
+// ---------- "Study formats": what the agent reads before it designs a scene ----------
+
+/** A file name safe on every system: the handle, lowercased, nothing but a-z 0-9 . _ - */
+export function studyFileName(handle: string): string | null {
+  const h = normalizeHandle(handle);
+  return /^[a-z0-9._-]{1,80}$/.test(h) && !h.startsWith(".") ? `${h}.md` : null;
+}
+
+export function studyMarkdown(p: CreatorProfileView, now: Date = new Date()): string {
+  const out: string[] = [];
+  out.push(`# Formats and hooks: @${clean(p.handle)} (${platformName(p.platform)})`, "");
+  out.push("Read this before you design a scene. Learn what works: the shape of the video, how it opens, how long it runs. Write your own script and visuals. Do not copy their videos, captions or footage.", "");
+  out.push(`Studied ${now.toISOString().slice(0, 10)} from vfrey Creators. Followers ${count(p.followers)}, median views ${count(p.medianViews)}, engagement ${engagementLabel(p)}, median length ${typeof p.stats?.medianLengthSec === "number" ? `${Math.round(p.stats.medianLengthSec)}s` : DASH}.`, "");
+  out.push("## Formats", "");
+  if (!p.formats?.length) out.push("None found yet.");
+  for (const f of p.formats ?? []) out.push(`- ${clean(f.name)}: ${f.postCount} posts. Terms: ${(f.terms ?? []).map((t) => clean(t)).join(", ")}.`);
+  out.push("", "## Hooks (the first sentence of their captions)", "");
+  if (!p.hooks?.length) out.push("None found yet.");
+  for (const h of p.hooks ?? []) out.push(`- ${clean(h.text)}`);
+  out.push("", "## Top posts (for reference)", "");
+  if (!p.topPosts?.length) out.push("None found yet.");
+  for (const t of p.topPosts ?? []) out.push(`- ${httpUrl(t.url) || "(no link)"}: ${count(t.metrics?.views)} views${typeof t.durationSec === "number" ? `, ${Math.round(t.durationSec)}s` : ""}${t.caption ? `. ${clean(t.caption).slice(0, 120)}` : ""}`);
+  return out.join("\n") + "\n";
+}
+
+// ---------- the command ----------
+
+const USAGE = [
+  "usage: npx vfrey creators search [--niche ID] [--platform tiktok,youtube] [--followers 10k-200k] [--posts-per-week N] [--engagement 4%] [--sort engagement|growth|views|followers] [--limit N] [--json]",
+  "       npx vfrey creators show @handle --platform P [--json]",
+  "       npx vfrey creators watch add|remove @handle --platform P [--watchlist NAME] | watch list [--watchlist NAME] [--json]",
+  "       npx vfrey creators export --watchlist ID > file.csv",
+  "       npx vfrey creators alerts [--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.");
+}
+
+/** `--name value`, `--name=value`, bare words as positionals. Unknown flags are an error. */
+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) 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 };
+}
+
+function platformOf(value: string | undefined): string | { error: string } {
+  const p = value?.trim().toLowerCase();
+  if (!p) return { error: "Say which platform: --platform tiktok, instagram or youtube." };
+  return (CREATOR_PLATFORM_IDS as readonly string[]).includes(p) ? p : { error: `--platform must be one of ${CREATOR_PLATFORM_IDS.join(", ")}.` };
+}
+
+// eslint-disable-next-line no-control-regex
+const CSV_UNSAFE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g;
+
+export async function runCreators(args: string[], io: ApiIo): Promise<number> {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const deps: CreatorsDeps = { 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 === "search") {
+      const p = parseArgs(rest, ["--json"], ["--niche", "--platform", "--followers", "--posts-per-week", "--engagement", "--sort", "--limit", "--api"]);
+      if (p.error || p.positionals.length) return refuse(io, p.error ?? `Unexpected "${p.positionals[0]}".`, USAGE);
+      const built = buildSearchQuery({ niche: p.values["--niche"], platform: p.values["--platform"], followers: p.values["--followers"], postsPerWeek: p.values["--posts-per-week"], engagement: p.values["--engagement"], sort: p.values["--sort"], limit: p.values["--limit"] });
+      if ("error" in built) return refuse(io, built.error, USAGE);
+      const creators = await searchCreators(deps, built.query, p.values["--api"]);
+      io.stdout(p.bools.has("--json") ? JSON.stringify({ creators }, null, 2) + "\n" : formatSearch(creators));
+      return 0;
+    }
+    if (sub === "show") {
+      const p = parseArgs(rest, ["--json"], ["--platform", "--api"]);
+      if (p.error) return refuse(io, p.error, USAGE);
+      const handle = p.positionals[0] ? normalizeHandle(p.positionals[0]) : "";
+      if (!handle || p.positionals.length > 1) return refuse(io, "Say which creator: creators show @handle --platform tiktok.", USAGE);
+      const platform = platformOf(p.values["--platform"]);
+      if (typeof platform !== "string") return refuse(io, platform.error, USAGE);
+      const profile = await fetchProfile(deps, platform, handle, p.values["--api"]);
+      io.stdout(p.bools.has("--json") ? JSON.stringify(profile, null, 2) + "\n" : formatProfile(profile));
+      return 0;
+    }
+    if (sub === "watch") {
+      const action = rest[0];
+      if (action !== "add" && action !== "remove" && action !== "list") return refuse(io, "Say what to do: watch add, watch remove or watch list.", USAGE);
+      const p = parseArgs(rest.slice(1), ["--json"], ["--platform", "--watchlist", "--api"]);
+      if (p.error) return refuse(io, p.error, USAGE);
+      const key = p.values["--watchlist"]?.trim();
+      if (action === "list") {
+        if (p.positionals.length) return refuse(io, `Unexpected "${p.positionals[0]}".`, USAGE);
+        const lists = await fetchWatchlists(deps, p.values["--api"]);
+        if (!key) {
+          io.stdout(p.bools.has("--json") ? JSON.stringify({ watchlists: lists }, null, 2) + "\n" : formatWatchlists(lists));
+          return 0;
+        }
+        const list = findWatchlist(lists, key);
+        if (!list) return refuse(io, `No watchlist called "${clean(key)}".`, WATCH_FIX);
+        const items = await fetchWatchlistItems(deps, list.id, p.values["--api"]);
+        io.stdout(p.bools.has("--json") ? JSON.stringify(items, null, 2) + "\n" : formatWatchItems(items));
+        return 0;
+      }
+      const handle = p.positionals[0] ? normalizeHandle(p.positionals[0]) : "";
+      if (!handle || p.positionals.length > 1) return refuse(io, `Say which creator: creators watch ${action} @handle --platform tiktok.`, USAGE);
+      const platform = platformOf(p.values["--platform"]);
+      if (typeof platform !== "string") return refuse(io, platform.error, USAGE);
+      if (action === "add") {
+        const done = await addToWatchlist(deps, key || DEFAULT_WATCHLIST, platform, handle, p.values["--api"]);
+        io.stdout(p.bools.has("--json") ? JSON.stringify(done, null, 2) + "\n" : `✓ ${done.created ? "Added" : "Already on"} @${clean(handle)} (${platformName(platform)}) ${done.created ? "to" : "in"} "${clean(done.watchlist.name)}"${done.madeList ? " (new watchlist)" : ""}. Watching is free; alerts and exports use credits.\n`);
+      } else {
+        const list = await removeFromWatchlist(deps, key || DEFAULT_WATCHLIST, platform, handle, p.values["--api"]);
+        io.stdout(p.bools.has("--json") ? JSON.stringify({ ok: true, watchlist: list }, null, 2) + "\n" : `✓ Removed @${clean(handle)} (${platformName(platform)}) from "${clean(list.name)}".\n`);
+      }
+      return 0;
+    }
+    if (sub === "export") {
+      const p = parseArgs(rest, [], ["--watchlist", "--api"]);
+      if (p.error || p.positionals.length) return refuse(io, p.error ?? `Unexpected "${p.positionals[0]}".`, USAGE);
+      const key = p.values["--watchlist"]?.trim();
+      if (!key) {
+        const lists = await fetchWatchlists(deps, p.values["--api"]);
+        return refuse(io, "Pick a watchlist to export.", `run \`npx vfrey creators export --watchlist ID > file.csv\`. Watchlists: ${lists.slice(0, 12).map((l) => `${clean(l.name)} (${clean(l.id)})`).join(", ") || "none yet"}.`);
+      }
+      const csv = await exportWatchlist(deps, key, p.values["--api"]);
+      io.stdout(csv.replace(CSV_UNSAFE, "").replace(/vfr_[A-Za-z0-9_-]+/g, "[token]"));
+      return 0;
+    }
+    if (sub === "alerts") {
+      const p = parseArgs(rest, ["--json"], ["--api"]);
+      if (p.error || p.positionals.length) return refuse(io, p.error ?? `Unexpected "${p.positionals[0]}".`, USAGE);
+      const answer = await fetchAlerts(deps, p.values["--api"]);
+      io.stdout(p.bools.has("--json") ? JSON.stringify(answer, null, 2) + "\n" : formatAlerts(answer));
+      return 0;
+    }
+    return refuse(io, sub ? `Unknown creators command "${clean(sub)}".` : "Say what to do with creators.", USAGE);
+  } catch (error) {
+    return failure(io, error);
+  }
+}

package/src/api/credentials.ts

@@ -0,0 +1,152 @@
+// Per-user token storage. Never the project's .vfrey folder.
+// macOS: the Keychain through `security`. Otherwise (or when that fails): `<machine home>/credentials.json`, mode 0600, keyed by API host.
+// VFREY_TOKEN overrides both. VFREY_CREDENTIALS_STORE=file skips the Keychain.
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { vfreyHome } from "../home.js";
+
+type Env = Record<string, string | undefined>;
+
+export interface RunResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+/** Runs one program. Injectable so tests never touch the real Keychain. */
+export type Runner = (command: string, args: string[]) => RunResult;
+
+export const defaultRunner: Runner = (command, args) => {
+  const result = spawnSync(command, args, { encoding: "utf8", timeout: 10_000 });
+  return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+};
+
+export interface CredentialDeps {
+  env: Env;
+  homedir?: string;
+  platform?: NodeJS.Platform;
+  run?: Runner;
+}
+
+/** Non-secret facts kept beside the token so `doctor` can answer without the network or the Keychain. */
+export interface AccountHint {
+  org: string;
+  plan: string;
+}
+
+interface FileEntry extends Partial<AccountHint> {
+  token?: string;
+}
+
+export type TokenSource = "env" | "keychain" | "file";
+export type SaveWhere = "keychain" | "file";
+
+const SERVICE = "vfrey";
+
+export function credentialsPath(deps: CredentialDeps): string {
+  return path.join(vfreyHome(deps.env, deps.homedir ?? os.homedir()), "credentials.json");
+}
+
+function useKeychain(deps: CredentialDeps): boolean {
+  return (deps.platform ?? process.platform) === "darwin" && deps.env.VFREY_CREDENTIALS_STORE !== "file";
+}
+
+function readFile(deps: CredentialDeps): Record<string, FileEntry> {
+  const file = credentialsPath(deps);
+  if (!existsSync(file)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, FileEntry>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeFile(deps: CredentialDeps, data: Record<string, FileEntry>): void {
+  const file = credentialsPath(deps);
+  const dir = path.dirname(file);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const temp = `${file}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(temp, 0o600);
+  renameSync(temp, file);
+}
+
+function keychainGet(host: string, deps: CredentialDeps): string | null {
+  const result = (deps.run ?? defaultRunner)("security", ["find-generic-password", "-s", SERVICE, "-a", host, "-w"]);
+  const token = result.stdout.trim();
+  return result.status === 0 && token ? token : null;
+}
+
+/** The token to use for this API host, and where it came from. VFREY_TOKEN wins. */
+export function loadToken(host: string, deps: CredentialDeps): { token: string; source: TokenSource } | null {
+  const fromEnv = deps.env.VFREY_TOKEN?.trim();
+  if (fromEnv) return { token: fromEnv, source: "env" };
+  return loadStoredToken(host, deps);
+}
+
+/** The stored token only, ignoring VFREY_TOKEN. `logout` works on this. */
+export function loadStoredToken(host: string, deps: CredentialDeps): { token: string; source: "keychain" | "file" } | null {
+  if (useKeychain(deps)) {
+    const token = keychainGet(host, deps);
+    if (token) return { token, source: "keychain" };
+  }
+  const token = readFile(deps)[host]?.token;
+  return token ? { token, source: "file" } : null;
+}
+
+/** Stores the token (Keychain first on macOS, else the file) and the non-secret hint. */
+export function saveToken(host: string, token: string, hint: AccountHint, deps: CredentialDeps): { where: SaveWhere; file: string } {
+  const file = credentialsPath(deps);
+  const data = readFile(deps);
+  if (useKeychain(deps)) {
+    const result = (deps.run ?? defaultRunner)("security", ["add-generic-password", "-s", SERVICE, "-a", host, "-w", token, "-U"]);
+    if (result.status === 0) {
+      data[host] = { ...hint };
+      try {
+        writeFile(deps, data);
+      } catch {
+        /* the hint is a courtesy for doctor */
+      }
+      return { where: "keychain", file };
+    }
+  }
+  data[host] = { token, ...hint };
+  writeFile(deps, data);
+  return { where: "file", file };
+}
+
+/** Refreshes the hint without touching the token. */
+export function saveHint(host: string, hint: AccountHint, deps: CredentialDeps): void {
+  const data = readFile(deps);
+  if (!data[host]) return;
+  data[host] = { ...data[host], ...hint };
+  try {
+    writeFile(deps, data);
+  } catch {
+    /* a courtesy */
+  }
+}
+
+export function readHint(host: string, deps: CredentialDeps): AccountHint | null {
+  const entry = readFile(deps)[host];
+  return entry?.org && entry.plan ? { org: entry.org, plan: entry.plan } : null;
+}
+
+/** Removes the stored token and hint from both places. Returns whether anything was removed. */
+export function deleteToken(host: string, deps: CredentialDeps): boolean {
+  let removed = false;
+  if (useKeychain(deps)) {
+    const result = (deps.run ?? defaultRunner)("security", ["delete-generic-password", "-s", SERVICE, "-a", host]);
+    if (result.status === 0) removed = true;
+  }
+  const data = readFile(deps);
+  if (data[host]) {
+    removed = true;
+    delete data[host];
+    if (Object.keys(data).length === 0) rmSync(credentialsPath(deps), { force: true });
+    else writeFile(deps, data);
+  }
+  return removed;
+}