@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/api/client.ts

@@ -0,0 +1,282 @@
+// The one vfrey API client. Every paid command uses it: it adds the token, maps failures to the CLI's ✗ and Fix: lines,
+// and never prints the token.
+import {
+  CLI_CLIENT_ID,
+  isApiError,
+  type ApiError,
+  type DeviceCodeResponse,
+  type DeviceTokenErrorCode,
+  type DeviceTokenResponse,
+  type MeResponse,
+  type NicheRequestBody,
+  type OrgsResponse,
+  type OrgSwitchResponse,
+  type NicheRequestResponse,
+  type NichesResponse,
+  type TopicsResponse,
+  type CreatorAlertsResponse,
+  type CreatorProfileView,
+  type CreatorSearchResponse,
+  type MailDraftBody,
+  type MailDraftPatch,
+  type MailDraftView,
+  type MailIdentityBody,
+  type MailIdentityView,
+  type WatchlistItemView,
+  type WatchlistView,
+} from "./types.js";
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** A refusal the CLI prints as `✗ <message>` and `Fix: <fix>`. */
+export class ApiFailure extends Error {
+  constructor(message: string, readonly fix: string, readonly status?: number, readonly code?: string) {
+    super(message);
+  }
+}
+
+export interface ClientOptions {
+  baseUrl: string;
+  token?: string | null;
+  fetch?: FetchLike;
+  timeoutMs?: number;
+}
+
+const TOKEN_SHAPE = /vfr_[A-Za-z0-9_-]+/g;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
+
+/** Text from the server, safe to print: no control characters (no terminal escapes), no token. */
+export function clean(text: unknown, token?: string | null): string {
+  let out = String(text ?? "").replace(CONTROL, " ").replace(TOKEN_SHAPE, "[token]");
+  if (token) out = out.split(token).join("[token]");
+  return out.trim();
+}
+
+const DEVICE_ERRORS = new Set<string>(["authorization_pending", "slow_down", "access_denied", "expired_token"]);
+
+export class ApiClient {
+  private readonly fetchFn: FetchLike;
+  private readonly timeoutMs: number;
+  readonly host: string;
+
+  constructor(private readonly options: ClientOptions) {
+    this.fetchFn = options.fetch ?? ((input, init) => fetch(input, init));
+    this.timeoutMs = options.timeoutMs ?? 15_000;
+    this.host = new URL(options.baseUrl).host;
+  }
+
+  private async send(method: string, path: string, body?: unknown): Promise<{ status: number; json: unknown; text: string }> {
+    const headers: Record<string, string> = { accept: "application/json" };
+    if (this.options.token) headers.authorization = `Bearer ${this.options.token}`;
+    if (body !== undefined) headers["content-type"] = "application/json";
+    let response: Response;
+    try {
+      response = await this.fetchFn(`${this.options.baseUrl}${path}`, {
+        method,
+        headers,
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        redirect: "error",
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (error) {
+      const timedOut = error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+      throw new ApiFailure(
+        timedOut ? `${this.host} did not answer in ${Math.round(this.timeoutMs / 1000)} seconds.` : `Could not reach ${this.host}.`,
+        "check your connection and try again. Free features work without vfrey accounts.",
+      );
+    }
+    let text = "";
+    try {
+      text = await response.text();
+    } catch {
+      text = "";
+    }
+    let json: unknown = null;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      json = null;
+    }
+    return { status: response.status, json, text };
+  }
+
+  /** Maps a non-2xx answer to the CLI's refusal. */
+  private fail(status: number, json: unknown, path = ""): ApiFailure {
+    const token = this.options.token;
+    const err = isApiError(json) ? (json as ApiError).error : null;
+    const message = err ? clean(err.message, token) : "";
+    if (status === 401) return new ApiFailure("You are not signed in, or this token was revoked.", "run `npx vfrey login`.", 401, "unauthorized");
+    if (status === 503 && err?.code === "capacity_paused") {
+      return new ApiFailure("vfrey is paused for new data right now.", "try again later. Cached results still work.", 503, "capacity_paused");
+    }
+    if (status === 402 && err?.code === "credits_required") {
+      const url = err.buyCreditsUrl ? clean(err.buyCreditsUrl, token) : "";
+      const need = typeof err.required === "number" ? ` It needs ${err.required} credits` : "";
+      const have = typeof err.balance === "number" ? `${need ? "; you have" : " You have"} ${err.balance}` : "";
+      const detail = need || have ? `${need}${have}.` : "";
+      return new ApiFailure(`${message || "Not enough credits."}${detail ? ` ${detail.trim()}` : ""}`, url ? `Buy credits: ${url}` : "buy credits on your vfrey billing page.", 402, "credits_required");
+    }
+    if (status === 402) {
+      const url = err?.upgradeUrl ? clean(err.upgradeUrl, token) : "";
+      return new ApiFailure(message || "This feature is not in your plan.", url ? `upgrade your plan at ${url}` : "upgrade your plan at your vfrey billing page.", 402, "plan_required");
+    }
+    if (status === 429 && err?.code === "rate_limited") {
+      return new ApiFailure(message || "Too many requests.", "wait a minute and try again.", 429, "rate_limited");
+    }
+    if (status === 429) {
+      const resets = err?.resetsAt ? clean(err.resetsAt, token) : "";
+      const url = err?.upgradeUrl ? clean(err.upgradeUrl, token) : "";
+      const fix = resets ? `your limit resets at ${resets}${url ? `, or upgrade at ${url}` : ""}.` : "wait a little and try again.";
+      // The server names the meter when it can; otherwise the route says which one ran out.
+      const named = (err as { meter?: unknown } | null)?.meter;
+      const meter = typeof named === "string" && named ? clean(named, token)
+        : /^\/api\/v1\/(topics|niches)/.test(path) ? "topics.requests" : /^\/api\/v1\/creators\/(tiktok|instagram|youtube)\//.test(path) ? "creators.profiles" : "";
+      return new ApiFailure(`You reached this month's limit${meter ? ` for ${meter}` : ""}.`, fix, 429, err?.code ?? "limit_reached");
+    }
+    return new ApiFailure(message || `The vfrey server answered ${status}.`, status >= 500 ? "try again in a moment." : "run `npx vfrey doctor` and check the line above.", status, err?.code);
+  }
+
+  /** A JSON request. Throws ApiFailure for network trouble and any non-2xx answer. */
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const { status, json } = await this.send(method, path, body);
+    if (status < 200 || status >= 300) throw this.fail(status, json, path);
+    return json as T;
+  }
+
+  /** A request whose answer is plain text (a CSV export). Same refusals as `request`. */
+  async requestText(method: string, path: string): Promise<string> {
+    const { status, json, text } = await this.send(method, path);
+    if (status < 200 || status >= 300) throw this.fail(status, json, path);
+    return text;
+  }
+
+  /** Creator search (spec 017). Reads the server's index; costs credits. */
+  creatorSearch(query: Record<string, string>): Promise<CreatorSearchResponse> {
+    return this.request<CreatorSearchResponse>("GET", `/api/v1/creators/search?${new URLSearchParams(query).toString()}`);
+  }
+
+  creatorProfile(platform: string, handle: string): Promise<CreatorProfileView> {
+    return this.request<CreatorProfileView>("GET", `/api/v1/creators/${encodeURIComponent(platform)}/${encodeURIComponent(handle)}`);
+  }
+
+  creatorAlerts(): Promise<CreatorAlertsResponse> {
+    return this.request<CreatorAlertsResponse>("GET", "/api/v1/creators/alerts");
+  }
+
+  watchlists(): Promise<{ watchlists: WatchlistView[] }> {
+    return this.request("GET", "/api/v1/watchlists");
+  }
+
+  createWatchlist(name: string): Promise<{ id: string; name: string }> {
+    return this.request("POST", "/api/v1/watchlists", { name });
+  }
+
+  watchlistItems(id: string): Promise<{ watchlist: { id: string; name: string }; items: WatchlistItemView[] }> {
+    return this.request("GET", `/api/v1/watchlists/${encodeURIComponent(id)}/items`);
+  }
+
+  addWatch(id: string, body: { platform: string; handle: string }): Promise<{ ok: boolean; created: boolean }> {
+    return this.request("POST", `/api/v1/watchlists/${encodeURIComponent(id)}/items`, body);
+  }
+
+  removeWatch(id: string, platform: string, handle: string): Promise<{ ok: boolean }> {
+    return this.request("DELETE", `/api/v1/watchlists/${encodeURIComponent(id)}/items?${new URLSearchParams({ platform, handle }).toString()}`);
+  }
+
+  watchlistCsv(id: string): Promise<string> {
+    return this.requestText("GET", `/api/v1/watchlists/${encodeURIComponent(id)}/export.csv`);
+  }
+
+  // ---------- Mail (spec 018). Draft, approve and send are three separate calls; nothing here chains them. ----------
+
+  mailDraft(body: MailDraftBody): Promise<{ draft: MailDraftView }> {
+    return this.request("POST", "/api/v1/mail/drafts", body);
+  }
+
+  mailDrafts(query: { status?: string; limit?: number } = {}): Promise<{ drafts: MailDraftView[] }> {
+    const params = new URLSearchParams();
+    if (query.status) params.set("status", query.status);
+    if (query.limit) params.set("limit", String(query.limit));
+    const qs = params.toString();
+    return this.request("GET", `/api/v1/mail/drafts${qs ? `?${qs}` : ""}`);
+  }
+
+  mailGet(id: string): Promise<{ draft: MailDraftView }> {
+    return this.request("GET", `/api/v1/mail/drafts/${encodeURIComponent(id)}`);
+  }
+
+  mailEdit(id: string, patch: MailDraftPatch): Promise<{ draft: MailDraftView }> {
+    return this.request("PATCH", `/api/v1/mail/drafts/${encodeURIComponent(id)}`, patch);
+  }
+
+  mailApprove(id: string): Promise<{ draft: MailDraftView }> {
+    return this.request("POST", `/api/v1/mail/drafts/${encodeURIComponent(id)}/approve`, {});
+  }
+
+  mailSend(id: string): Promise<{ draft: MailDraftView }> {
+    return this.request("POST", `/api/v1/mail/drafts/${encodeURIComponent(id)}/send`, {});
+  }
+
+  mailDiscard(id: string): Promise<{ draft: MailDraftView }> {
+    return this.request("POST", `/api/v1/mail/drafts/${encodeURIComponent(id)}/discard`, {});
+  }
+
+  mailIdentity(): Promise<{ identity: MailIdentityView | null }> {
+    return this.request("GET", "/api/v1/mail/identity");
+  }
+
+  mailSaveIdentity(body: MailIdentityBody): Promise<{ identity: MailIdentityView; verificationEmailed: boolean }> {
+    return this.request("POST", "/api/v1/mail/identity", body);
+  }
+
+  /** Ranked topics for one niche. Costs credits on the server. */
+  topics(query: { niche: string; limit?: number; since?: string }): Promise<TopicsResponse> {
+    const params = new URLSearchParams({ niche: query.niche });
+    if (query.limit !== undefined) params.set("limit", String(query.limit));
+    if (query.since) params.set("since", query.since);
+    return this.request<TopicsResponse>("GET", `/api/v1/topics?${params.toString()}`);
+  }
+
+  niches(): Promise<NichesResponse> {
+    return this.request<NichesResponse>("GET", "/api/v1/niches");
+  }
+
+  requestNiche(body: NicheRequestBody): Promise<NicheRequestResponse> {
+    return this.request<NicheRequestResponse>("POST", "/api/v1/niches", body);
+  }
+
+  me(): Promise<MeResponse> {
+    return this.request<MeResponse>("GET", "/api/v1/me");
+  }
+
+  /** The orgs this user belongs to (spec 019 A). */
+  orgs(): Promise<OrgsResponse> {
+    return this.request<OrgsResponse>("GET", "/api/v1/orgs");
+  }
+
+  /** Trades this token for one bound to another org. The server revokes the token used for the call. */
+  switchOrg(orgId: string): Promise<OrgSwitchResponse> {
+    return this.request<OrgSwitchResponse>("POST", "/api/v1/orgs/switch", { orgId });
+  }
+
+  /** Revokes the calling token. */
+  async revokeCurrentToken(): Promise<void> {
+    const { status, json } = await this.send("DELETE", "/api/v1/tokens/current");
+    if (status < 200 || status >= 300) throw this.fail(status, json);
+  }
+
+  deviceCode(): Promise<DeviceCodeResponse> {
+    return this.request<DeviceCodeResponse>("POST", "/api/v1/device/code", { client_id: CLI_CLIENT_ID });
+  }
+
+  /** One poll. The four device errors come back as data (whatever status carries them); anything else throws. */
+  async deviceToken(deviceCode: string): Promise<DeviceTokenResponse> {
+    const { status, json } = await this.send("POST", "/api/v1/device/token", { device_code: deviceCode, client_id: CLI_CLIENT_ID });
+    const body = json as { error?: unknown; access_token?: unknown } | null;
+    if (body && typeof body.error === "string" && DEVICE_ERRORS.has(body.error)) return { error: body.error as DeviceTokenErrorCode };
+    if (status >= 200 && status < 300 && body && typeof body.access_token === "string") return json as DeviceTokenResponse;
+    if (status >= 200 && status < 300) throw new ApiFailure("The vfrey server sent an answer this version does not understand.", "update vfrey with `npx vfrey update`.", status);
+    throw this.fail(status, json);
+  }
+}

package/src/api/commands.ts

@@ -0,0 +1,330 @@
+// `vfrey login`, `logout`, `whoami`, and the doctor account line.
+import os from "node:os";
+import { ApiClient, ApiFailure, clean, type FetchLike } from "./client.js";
+import { apiHost, ApiConfigError, resolveApiUrl } from "./config.js";
+import { deleteToken, loadStoredToken, loadToken, readHint, saveHint, saveToken, type CredentialDeps, type Runner } from "./credentials.js";
+import { formatUserCode, type MeResponse, type OrgSummary } from "./types.js";
+
+type Env = Record<string, string | undefined>;
+
+export interface ApiIo {
+  env: Env;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  homedir?: string;
+  platform?: NodeJS.Platform;
+  run?: Runner;
+  fetch?: FetchLike;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  /** Opens a URL in the browser. Defaults to the `open` package. */
+  openUrl?: (url: string) => Promise<void>;
+  timeoutMs?: number;
+}
+
+const NOT_LIVE_FIX = "free features work without an account. If you run your own vfrey server, set VFREY_API_URL or pass --api <url>.";
+
+function creds(io: ApiIo): CredentialDeps {
+  return { env: io.env, homedir: io.homedir ?? os.homedir(), ...(io.platform ? { platform: io.platform } : {}), ...(io.run ? { run: io.run } : {}) };
+}
+
+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 client(io: ApiIo, base: string, token?: string | null): ApiClient {
+  return new ApiClient({ baseUrl: base, token: token ?? null, ...(io.fetch ? { fetch: io.fetch } : {}), ...(io.timeoutMs ? { timeoutMs: io.timeoutMs } : {}) });
+}
+
+/** The flag value after `--api`, or `--api=URL`. */
+function flagValue(args: string[], name: string): string | null | undefined {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]!;
+    if (arg === name) return args[i + 1] && !args[i + 1]!.startsWith("--") ? args[i + 1]! : null;
+    if (arg.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+  }
+  return undefined;
+}
+
+/** Parses the flags these commands share. Returns an error text for an unknown or malformed flag. */
+function parse(args: string[], allowed: string[], valued: string[]): { flags: Set<string>; api?: string; error?: string } {
+  const flags = new Set<string>();
+  let api: string | undefined;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]!;
+    const name = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+    if (!allowed.includes(name) && !valued.includes(name)) return { flags, error: `Unknown option "${arg}".` };
+    if (valued.includes(name)) {
+      const value = flagValue(args, name);
+      if (!value) return { flags, error: `${name} needs a value.` };
+      api = value;
+      if (!arg.includes("=")) i += 1;
+    } else flags.add(name);
+  }
+  return { flags, ...(api ? { api } : {}) };
+}
+
+function resolve(io: ApiIo, api?: string): string | null {
+  return resolveApiUrl(io.env, api ?? null);
+}
+
+function notLive(io: ApiIo): number {
+  return refuse(io, "vfrey accounts are not live yet.", NOT_LIVE_FIX);
+}
+
+const defaultSleep = (ms: number) => new Promise<void>((done) => setTimeout(done, ms));
+
+async function defaultOpen(url: string): Promise<void> {
+  const { default: open } = await import("open");
+  await open(url);
+}
+
+function browserUrl(url: string): string | null {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.href : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function runLogin(args: string[], io: ApiIo): Promise<number> {
+  const parsed = parse(args, ["--no-browser"], ["--api"]);
+  if (parsed.error) return refuse(io, parsed.error, "usage: npx vfrey login [--api URL] [--no-browser].");
+  try {
+    const base = resolve(io, parsed.api);
+    if (!base) return notLive(io);
+    const host = apiHost(base);
+    const api = client(io, base);
+    const sleep = io.sleep ?? defaultSleep;
+    const now = io.now ?? Date.now;
+
+    const code = await api.deviceCode();
+    const link = browserUrl(code.verification_uri_complete);
+    if (!link) return refuse(io, "The server sent a sign-in link that is not a web address.", "check the API address and try again.");
+    io.stdout(`Open ${link} and confirm the code ${formatUserCode(code.user_code)}\n`);
+    if (!parsed.flags.has("--no-browser") && !io.env.VFREY_NO_BROWSER) {
+      try {
+        await (io.openUrl ?? defaultOpen)(link);
+      } catch {
+        /* the link is printed: the person can open it themselves */
+      }
+    }
+
+    const deadline = now() + (Number.isFinite(code.expires_in) ? code.expires_in : 600) * 1000;
+    let intervalSec = Number.isFinite(code.interval) && code.interval >= 0 ? code.interval : 5;
+    let networkErrors = 0;
+    for (;;) {
+      await sleep(intervalSec * 1000);
+      if (now() >= deadline) return refuse(io, "The sign-in code expired.", "run `npx vfrey login` again.");
+      let answer;
+      try {
+        answer = await api.deviceToken(code.device_code);
+        networkErrors = 0;
+      } catch (error) {
+        if (error instanceof ApiFailure && error.status === undefined && (networkErrors += 1) < 3) continue;
+        if (error instanceof ApiFailure && error.status === 429) {
+          intervalSec += 5;
+          continue;
+        }
+        throw error;
+      }
+      if ("access_token" in answer) {
+        const org = clean(answer.org.name);
+        let plan = "";
+        try {
+          plan = clean((await client(io, base, answer.access_token).me()).plan);
+        } catch {
+          /* signed in all the same; the plan shows on whoami */
+        }
+        let saved;
+        try {
+          saved = saveToken(host, answer.access_token, { org, plan }, creds(io));
+        } catch {
+          return refuse(io, "Signed in, but the token could not be saved on this machine.", "make the vfrey home folder writable (VFREY_HOME), then run `npx vfrey login` again.");
+        }
+        io.stdout(`✓ Signed in to ${org}${plan ? ` (${plan})` : ""}\n`);
+        if (saved.where === "file") io.stdout(`Token saved in ${saved.file} (readable only by you).\n`);
+        if (io.env.VFREY_TOKEN) io.stderr("Note: VFREY_TOKEN is set in this shell and overrides the token you just saved.\n");
+        return 0;
+      }
+      if (answer.error === "slow_down") intervalSec += 5;
+      else if (answer.error === "access_denied") return refuse(io, "Sign-in was denied in the browser.", "run `npx vfrey login` again and choose Approve.");
+      else if (answer.error === "expired_token") return refuse(io, "The sign-in code expired.", "run `npx vfrey login` again.");
+    }
+  } catch (error) {
+    return failure(io, error);
+  }
+}
+
+export async function runLogout(args: string[], io: ApiIo): Promise<number> {
+  const parsed = parse(args, [], ["--api"]);
+  if (parsed.error) return refuse(io, parsed.error, "usage: npx vfrey logout [--api URL].");
+  try {
+    const base = resolve(io, parsed.api);
+    if (!base) {
+      io.stdout("✓ Not signed in (vfrey accounts are not live yet).\n");
+      return 0;
+    }
+    const host = apiHost(base);
+    const stored = loadStoredToken(host, creds(io));
+    if (!stored) {
+      io.stdout(`✓ Not signed in to ${host}.\n`);
+      if (io.env.VFREY_TOKEN) io.stderr("Note: VFREY_TOKEN is set in this shell; unset it to stop using that token.\n");
+      return 0;
+    }
+    try {
+      await client(io, base, stored.token).revokeCurrentToken();
+    } catch (error) {
+      // 401 means the server already treats the token as revoked. Anything else leaves it live: say so, still sign out here.
+      if (!(error instanceof ApiFailure && error.status === 401)) {
+        io.stderr(`! Could not revoke the token on ${host} (${error instanceof ApiFailure ? error.message : "unknown error"}). It stays valid there until you revoke it at ${base}/settings/tokens.\n`);
+      }
+    }
+    deleteToken(host, creds(io));
+    io.stdout(`✓ Signed out of ${host}\n`);
+    if (io.env.VFREY_TOKEN) io.stderr("Note: VFREY_TOKEN is set in this shell; unset it to stop using that token.\n");
+    return 0;
+  } catch (error) {
+    return failure(io, error);
+  }
+}
+
+function formatMe(me: MeResponse): string {
+  const lines = [
+    `✓ Signed in as ${clean(me.user.email)}`,
+    `Org: ${clean(me.org.name)} (${clean(me.org.role)})`,
+    `Plan: ${clean(me.plan)}`,
+    `Entitlements: ${Object.entries(me.entitlements).map(([name, on]) => `${clean(name)} ${on ? "yes" : "no"}`).join(", ")}`,
+  ];
+  if (me.credits) {
+    const soon = me.credits.expiringSoon > 0 ? ` (${me.credits.expiringSoon} expiring soon)` : "";
+    lines.push(`Credits: ${me.credits.balance}${soon}`);
+  }
+  const meters = Object.entries(me.usage ?? {});
+  if (meters.length > 0) {
+    lines.push("Usage this month:");
+    for (const [meter, reading] of meters) {
+      lines.push(`  ${clean(meter)}: ${reading.used} of ${reading.limit ?? "unlimited"}, resets ${clean(reading.resetsAt)}`);
+    }
+  }
+  if (me.upgradeUrl) lines.push(`Upgrade or manage: ${clean(me.upgradeUrl)}`);
+  return lines.join("\n") + "\n";
+}
+
+export async function runWhoami(args: string[], io: ApiIo): Promise<number> {
+  const parsed = parse(args, ["--json"], ["--api"]);
+  if (parsed.error) return refuse(io, parsed.error, "usage: npx vfrey whoami [--json] [--api URL].");
+  try {
+    const base = resolve(io, parsed.api);
+    if (!base) return notLive(io);
+    const host = apiHost(base);
+    const found = loadToken(host, creds(io));
+    if (!found) return refuse(io, "You are not signed in.", "run `npx vfrey login`.");
+    const me = await client(io, base, found.token).me();
+    if (found.source !== "env") saveHint(host, { org: clean(me.org.name), plan: clean(me.plan) }, creds(io));
+    io.stdout(parsed.flags.has("--json") ? JSON.stringify(me, null, 2) + "\n" : formatMe(me));
+    return 0;
+  } catch (error) {
+    return failure(io, error);
+  }
+}
+
+const ORG_USAGE = "usage: npx vfrey org list [--json] [--api URL] | npx vfrey org use ORG [--api URL].";
+
+/** The org named by an id or an exact name (any case). Null when none match; "many" when a name is not unique. */
+function pickOrg(orgs: OrgSummary[], wanted: string): OrgSummary | null | "many" {
+  const byId = orgs.find((o) => o.id === wanted);
+  if (byId) return byId;
+  const byName = orgs.filter((o) => o.name.toLowerCase() === wanted.toLowerCase());
+  return byName.length === 1 ? byName[0]! : byName.length > 1 ? "many" : null;
+}
+
+/**
+ * `vfrey org list` and `vfrey org use ORG` (spec 019 A). A token is bound to one org for life, so `use` asks the server
+ * to trade the stored token for one bound to the chosen org (the server checks membership and revokes the old one),
+ * then stores the new token. A token from VFREY_TOKEN is never replaced: it stays what the shell says it is.
+ */
+export async function runOrg(args: string[], io: ApiIo): Promise<number> {
+  const [sub, ...rest] = args;
+  if (sub !== "list" && sub !== "use") return refuse(io, sub ? `Unknown org command "${clean(sub)}".` : "Say what to do with orgs.", ORG_USAGE);
+  const positional: string[] = [];
+  const flagArgs: string[] = [];
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i]!;
+    if (arg.startsWith("--")) {
+      flagArgs.push(arg);
+      if (arg === "--api" && rest[i + 1] !== undefined) flagArgs.push(rest[(i += 1)]!);
+    } else positional.push(arg);
+  }
+  const parsed = parse(flagArgs, sub === "list" ? ["--json"] : [], ["--api"]);
+  if (parsed.error) return refuse(io, parsed.error, ORG_USAGE);
+  if (positional.length > (sub === "use" ? 1 : 0)) return refuse(io, `Unexpected "${clean(positional[sub === "use" ? 1 : 0])}".`, ORG_USAGE);
+  const wanted = sub === "use" ? positional[0] : undefined;
+  if (sub === "use" && !wanted) return refuse(io, "Say which org to use.", "run `npx vfrey org list`, then `npx vfrey org use ORG` with its name or id.");
+  try {
+    const base = resolve(io, parsed.api);
+    if (!base) return notLive(io);
+    const host = apiHost(base);
+    const found = loadToken(host, creds(io));
+    if (!found) return refuse(io, "You are not signed in.", "run `npx vfrey login`.");
+    const api = client(io, base, found.token);
+    const { orgs } = await api.orgs();
+    if (sub === "list") {
+      if (parsed.flags.has("--json")) io.stdout(JSON.stringify({ orgs }, null, 2) + "\n");
+      else io.stdout(orgs.map((o) => `${o.current ? "*" : " "} ${clean(o.name)} (${clean(o.role)})  ${clean(o.id)}`).join("\n") + "\n");
+      return 0;
+    }
+    const target = pickOrg(orgs, wanted!);
+    if (target === "many") return refuse(io, `More than one org is named "${clean(wanted)}".`, "use the id from `npx vfrey org list`.");
+    if (!target) return refuse(io, `You are not in an org called "${clean(wanted)}".`, "run `npx vfrey org list` to see yours.");
+    if (target.current) {
+      io.stdout(`✓ Already using ${clean(target.name)} (${clean(target.role)})\n`);
+      return 0;
+    }
+    if (found.source === "env") return refuse(io, "VFREY_TOKEN is set, and that token is bound to one org.", "unset VFREY_TOKEN, run `npx vfrey login`, then `npx vfrey org use` again.");
+    let switched;
+    try {
+      switched = await api.switchOrg(target.id);
+    } catch (error) {
+      if (error instanceof ApiFailure && error.status === 403) return refuse(io, "This token is fixed to its org.", `run \`npx vfrey login\` while ${clean(target.name)} is selected in the vfrey console.`);
+      throw error;
+    }
+    let plan = "";
+    try {
+      plan = clean((await client(io, base, switched.access_token).me()).plan);
+    } catch {
+      /* switched all the same; the plan shows on whoami */
+    }
+    try {
+      saveToken(host, switched.access_token, { org: clean(switched.org.name), plan }, creds(io));
+    } catch {
+      return refuse(io, "Switched, but the new token could not be saved on this machine.", "make the vfrey home folder writable (VFREY_HOME), then run `npx vfrey login`.");
+    }
+    io.stdout(`✓ Now using ${clean(switched.org.name)} (${clean(switched.org.role)})\n`);
+    return 0;
+  } catch (error) {
+    return failure(io, error);
+  }
+}
+
+/** The doctor line. Local only (no network, no Keychain), and never a failure. */
+export function accountLine(env: Env, homedir: string = os.homedir()): string {
+  const none = "not signed in (free features work without it)";
+  try {
+    const base = resolveApiUrl(env, null);
+    if (!base) return none;
+    const host = apiHost(base);
+    const hint = readHint(host, { env, homedir });
+    if (env.VFREY_TOKEN?.trim()) return hint ? `signed in as ${hint.org} (${hint.plan}) with VFREY_TOKEN` : "signed in with VFREY_TOKEN";
+    return hint ? `signed in as ${hint.org} (${hint.plan})` : none;
+  } catch {
+    return none;
+  }
+}

package/src/api/config.ts

@@ -0,0 +1,34 @@
+// Where the vfrey accounts server is. Set DEFAULT_API_URL at release, when the console is deployed.
+
+type Env = Record<string, string | undefined>;
+
+/** The release-time default. Unset until the server is live: `login` then refuses without any network call. */
+export const DEFAULT_API_URL: string | null = null;
+
+export class ApiConfigError extends Error {
+  constructor(message: string, readonly fix: string) {
+    super(message);
+  }
+}
+
+/** `--api URL`, else VFREY_API_URL, else the release default. Null means accounts are not live. */
+export function resolveApiUrl(env: Env, flag?: string | null): string | null {
+  const raw = (flag ?? env.VFREY_API_URL ?? DEFAULT_API_URL ?? "").trim();
+  if (!raw) return null;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new ApiConfigError(`"${raw}" is not a URL.`, "pass a full address such as https://vfrey.example.com with --api or VFREY_API_URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new ApiConfigError(`${url.origin} is not https. vfrey sends your token only over https (or to this machine).`, "use an https:// address.");
+  }
+  return url.origin;
+}
+
+/** The key a token is stored under: the API's host (with port when it has one). */
+export function apiHost(base: string): string {
+  return new URL(base).host;
+}