rankcontrol 0.1.0 → 0.2.0

package/README.md

@@ -9,13 +9,21 @@ Every command calls the same authed, rate-limited, org-scoped API the RankContro
 
 ## Auth
 
-Create an API key in **RankControl → Settings → API**, then:
+The easy way — approve in your browser (you must be logged in to RankControl):
+
+```bash
+npx rankcontrol login
+```
+
+That opens your dashboard, you check the confirmation code matches, pick the permissions to grant, and the CLI stores a scoped key in `~/.rankcontrol/config.json`. `npx rankcontrol logout` removes it (revoke the key itself in Settings → API).
+
+The headless way (CI, servers, MCP `env` blocks) — create a key in **RankControl → Settings → API**, then:
 
 ```bash
 export RANKCONTROL_API_KEY=rctrl_pk_...
 ```
 
-Scopes are set per key. Read-only keys work for all `get_*`/`list_*` tools.
+The env var wins over the stored config when both exist. Scopes are set per key; read-only keys work for all `get_*`/`list_*` tools.
 
 ## CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rankcontrol",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "RankControl CLI + MCP server: drive your SEO/AI-visibility workspace from the terminal or any AI agent",
   "license": "MIT",
   "homepage": "https://rctrl.com",

package/src/cli.mjs

@@ -16,9 +16,9 @@ export function runCli(argv) {
   program
     .name("rankcontrol")
     .description(
-      "RankControl from the terminal. Auth: export RANKCONTROL_API_KEY=rctrl_pk_... (Settings → API)"
+      "RankControl from the terminal. Auth: `rankcontrol login` (browser approval) or export RANKCONTROL_API_KEY=rctrl_pk_..."
     )
-    .version("0.1.0");
+    .version("0.2.0");
 
   program
     .command("mcp")
@@ -28,6 +28,23 @@ export function runCli(argv) {
       await startMcpServer().catch(fail);
     });
 
+  program
+    .command("login")
+    .description("Authenticate via your browser (approves a scoped API key into ~/.rankcontrol)")
+    .option("--scopes <a,b,c>", "Scopes to request (default: reads + write:content + write:publish)")
+    .action(async (opts) => {
+      const { login } = await import("./login.mjs");
+      await login({ scopes: opts.scopes ? list(opts.scopes) : undefined }).catch(fail);
+    });
+
+  program
+    .command("logout")
+    .description("Remove locally stored credentials")
+    .action(async () => {
+      const { logout } = await import("./login.mjs");
+      logout();
+    });
+
   program
     .command("funnel")
     .description("AI pipeline last 30 days: crawls, AI visits, AI leads")

package/src/client.mjs

@@ -1,15 +1,63 @@
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 const DEFAULT_BASE = "https://api.rctrl.com";
+const DEFAULT_APP = "https://rctrl.com";
+
+const CONFIG_DIR = join(homedir(), ".rankcontrol");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+export function readStoredConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeStoredConfig(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", {
+    mode: 0o600,
+  });
+  return CONFIG_FILE;
+}
+
+export function deleteStoredConfig() {
+  if (!existsSync(CONFIG_FILE)) return false;
+  rmSync(CONFIG_FILE);
+  return true;
+}
 
 export function getConfig() {
-  const apiKey = process.env.RANKCONTROL_API_KEY;
+  const stored = readStoredConfig();
+  const apiKey = process.env.RANKCONTROL_API_KEY || stored?.apiKey;
   if (!apiKey) {
     throw new Error(
-      "RANKCONTROL_API_KEY is not set. Create a key in RankControl → Settings → API, then export RANKCONTROL_API_KEY=rctrl_pk_..."
+      "Not authenticated. Run `rankcontrol login`, or create a key in RankControl → Settings → API and export RANKCONTROL_API_KEY=rctrl_pk_..."
     );
   }
   return {
     apiKey,
+    baseUrl: (
+      process.env.RANKCONTROL_API_URL ||
+      stored?.baseUrl ||
+      DEFAULT_BASE
+    ).replace(/\/$/, ""),
+    appUrl: (
+      process.env.RANKCONTROL_APP_URL ||
+      stored?.appUrl ||
+      DEFAULT_APP
+    ).replace(/\/$/, ""),
+  };
+}
+
+// Unauthenticated variant for the login flow itself
+export function getBaseUrls() {
+  return {
     baseUrl: (process.env.RANKCONTROL_API_URL || DEFAULT_BASE).replace(/\/$/, ""),
+    appUrl: (process.env.RANKCONTROL_APP_URL || DEFAULT_APP).replace(/\/$/, ""),
   };
 }
 

package/src/login.mjs

@@ -0,0 +1,111 @@
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import {
+  getBaseUrls,
+  writeStoredConfig,
+  deleteStoredConfig,
+} from "./client.mjs";
+
+const DEFAULT_SCOPES = [
+  "read:citations",
+  "read:content",
+  "read:leads",
+  "read:analytics",
+  "write:content",
+  "write:publish",
+];
+
+function openBrowser(url) {
+  if (process.env.RANKCONTROL_NO_BROWSER) return false;
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+  try {
+    spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function login({ scopes } = {}) {
+  const { baseUrl, appUrl } = getBaseUrls();
+  const requested = scopes?.length ? scopes : DEFAULT_SCOPES;
+
+  const startRes = await fetch(`${baseUrl}/api/v1/auth/device/start`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      scopes: requested,
+      clientName: `CLI on ${hostname()}`,
+    }),
+  });
+  const startJson = await startRes.json();
+  if (!startRes.ok) {
+    throw new Error(startJson?.error || `Login start failed (HTTP ${startRes.status})`);
+  }
+  const { deviceCode, userCode, verificationPath, pollIntervalSeconds } =
+    startJson.data;
+
+  const url = `${appUrl}${verificationPath}`;
+  console.log(`\nConfirmation code: ${userCode}`);
+  console.log(`Approve access in your browser: ${url}`);
+  console.log("(check that the code on the page matches the one above)\n");
+  openBrowser(url);
+
+  const deadline = Date.now() + 10 * 60 * 1000;
+  process.stdout.write("Waiting for approval");
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, (pollIntervalSeconds || 3) * 1000));
+    process.stdout.write(".");
+
+    const pollRes = await fetch(`${baseUrl}/api/v1/auth/device/poll`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ deviceCode }),
+    }).catch(() => null);
+    if (!pollRes) continue;
+    const pollJson = await pollRes.json().catch(() => null);
+    const status = pollJson?.data?.status;
+
+    if (status === "pending") continue;
+    process.stdout.write("\n");
+
+    if (status === "complete") {
+      const file = writeStoredConfig({
+        apiKey: pollJson.data.apiKey,
+        keyPrefix: pollJson.data.keyPrefix,
+        orgName: pollJson.data.orgName,
+        ...(process.env.RANKCONTROL_API_URL
+          ? { baseUrl: process.env.RANKCONTROL_API_URL }
+          : {}),
+        ...(process.env.RANKCONTROL_APP_URL
+          ? { appUrl: process.env.RANKCONTROL_APP_URL }
+          : {}),
+      });
+      console.log(`Logged in to ${pollJson.data.orgName} (key ${pollJson.data.keyPrefix}...).`);
+      console.log(`Credentials saved to ${file}`);
+      return;
+    }
+    if (status === "denied") throw new Error("Login request was denied in the browser.");
+    if (status === "expired") throw new Error("Login request expired. Run login again.");
+    throw new Error(pollJson?.error || `Unexpected login status: ${status}`);
+  }
+  process.stdout.write("\n");
+  throw new Error("Timed out waiting for approval. Run login again.");
+}
+
+export function logout() {
+  const removed = deleteStoredConfig();
+  if (removed) {
+    console.log("Local credentials removed.");
+    console.log(
+      "The key itself is still active: revoke it in RankControl → Settings → API if this machine should lose access permanently."
+    );
+  } else {
+    console.log("No stored credentials found.");
+  }
+}

package/src/mcp.mjs

@@ -29,7 +29,7 @@ const plannedTitle = z.object({
 });
 
 export async function startMcpServer() {
-  const server = new McpServer({ name: "rankcontrol", version: "0.1.0" });
+  const server = new McpServer({ name: "rankcontrol", version: "0.2.0" });
 
   server.tool(
     "get_overview_funnel",