rankcontrol 0.1.0 → 0.6.0

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(/\/$/, ""),
   };
 }
 
@@ -39,6 +87,14 @@ export const api = {
   overviewFunnel: () => request("GET", "/api/v1/overview/funnel"),
   visibilityTrend: (days = 30) =>
     request("GET", `/api/v1/visibility/trend?days=${days}`),
+  shareOfVoice: (days = 30) =>
+    request("GET", `/api/v1/visibility/share-of-voice?days=${days}`),
+  citationSources: (days = 30) =>
+    request("GET", `/api/v1/visibility/sources?days=${days}`),
+  citationSentiment: (days = 30) =>
+    request("GET", `/api/v1/visibility/sentiment?days=${days}`),
+  optimizer: (limit = 25) =>
+    request("GET", `/api/v1/content/optimizer?limit=${limit}`),
   citations: (params = {}) => {
     const q = new URLSearchParams();
     if (params.model) q.set("model", params.model);
@@ -55,4 +111,98 @@ export const api = {
     request("POST", "/api/v1/content/plan/commit", opts),
   publishContent: (contentId, confirm = false) =>
     request("POST", "/api/v1/content/publish", { contentId, confirm }),
+  generateContent: (contentId, confirm = false) =>
+    request("POST", "/api/v1/content/generate", { contentId, confirm }),
+  internalLinks: (contentId) =>
+    request(
+      "GET",
+      `/api/v1/content/internal-links?contentId=${encodeURIComponent(contentId)}`
+    ),
+  articleSettings: () => request("GET", "/api/v1/settings/articles"),
+  updateArticleSettings: (opts) =>
+    request("POST", "/api/v1/settings/articles", opts),
+  reschedule: (contentId, targetDayStartMs) =>
+    request("POST", "/api/v1/content/reschedule", { contentId, targetDayStartMs }),
+  sitePages: () => request("GET", "/api/v1/links/pages"),
+  detectSiteLinks: (source, url) =>
+    request("POST", "/api/v1/links/detect", { source, url }),
+  addSitePages: (urls) => request("POST", "/api/v1/links/pages", { urls }),
+  leads: (limit = 100) => request("GET", `/api/v1/leads?limit=${limit}`),
+  repurposeQueue: () => request("GET", "/api/v1/repurpose"),
+  repurposeDrafts: (contentId) =>
+    request(
+      "GET",
+      `/api/v1/repurpose?contentId=${encodeURIComponent(contentId)}`
+    ),
+  repurposeChannels: () => request("GET", "/api/v1/repurpose/channels"),
+  repurposeGenerate: (opts) =>
+    request("POST", "/api/v1/repurpose/generate", opts),
+  repurposeEditDraft: (opts) => request("POST", "/api/v1/repurpose/draft", opts),
+  repurposeMarkPosted: (draftId) =>
+    request("POST", "/api/v1/repurpose/mark-posted", { draftId }),
+  repurposePush: (opts) => request("POST", "/api/v1/repurpose/push", opts),
+  trackedQueries: () => request("GET", "/api/v1/queries"),
+  addQuery: (queryText) => request("POST", "/api/v1/queries", { queryText }),
+  crawlerAccess: () => request("GET", "/api/v1/crawler-access"),
+  trafficOverview: (days = 30) =>
+    request("GET", `/api/v1/analytics/traffic?days=${days}`),
+  team: () => request("GET", "/api/v1/team"),
+  teamInvite: (opts) => request("POST", "/api/v1/team/invite", opts),
+  teamRevoke: (invitationId) =>
+    request("POST", "/api/v1/team/revoke", { invitationId }),
+  teamRemove: (opts) => request("POST", "/api/v1/team/remove", opts),
+  outreachProspects: () => request("GET", "/api/v1/outreach/prospects"),
+  outreachFindContact: (backlinkId) =>
+    request("POST", "/api/v1/outreach/find-contact", { backlinkId }),
+  outreachQueue: (opts) => request("POST", "/api/v1/outreach/queue", opts),
+  outreachDraftReply: (backlinkId) =>
+    request("POST", "/api/v1/outreach/draft-reply", { backlinkId }),
+  contentIdeas: () => request("GET", "/api/v1/content/ideas"),
+  planIdea: (opts) => request("POST", "/api/v1/content/ideas/plan", opts),
+  archiveContent: (contentId) =>
+    request("POST", "/api/v1/content/archive", { contentId }),
+  pageEngagement: () => request("GET", "/api/v1/analytics/engagement"),
+  reportSummary: () => request("GET", "/api/v1/reports/summary"),
+  reportWins: () => request("GET", "/api/v1/reports/wins"),
+  agentActivity: (params = {}) => {
+    const q = new URLSearchParams();
+    if (params.perAgent) q.set("perAgent", String(params.perAgent));
+    if (params.sinceDays) q.set("sinceDays", String(params.sinceDays));
+    const qs = q.toString();
+    return request("GET", `/api/v1/reports/agent-activity${qs ? `?${qs}` : ""}`);
+  },
+  backlinks: (status) =>
+    request(
+      "GET",
+      `/api/v1/backlinks${status ? `?status=${encodeURIComponent(status)}` : ""}`
+    ),
+  backlinkStats: () => request("GET", "/api/v1/backlinks/stats"),
+  outreachStatus: (backlinkId, status) =>
+    request("POST", "/api/v1/outreach/status", { backlinkId, status }),
+  linkNetwork: () => request("GET", "/api/v1/link-network"),
+  linkNetworkOptIn: (optIn, confirm = false) =>
+    request("POST", "/api/v1/link-network/opt-in", { optIn, confirm }),
+  linkNetworkRemovePlacement: (placementId, confirm = false) =>
+    request("POST", "/api/v1/link-network/remove-placement", {
+      placementId,
+      confirm,
+    }),
+  socialThreads: (params = {}) => {
+    const q = new URLSearchParams();
+    if (params.platform) q.set("platform", params.platform);
+    if (params.status) q.set("status", params.status);
+    if (params.age) q.set("age", params.age);
+    const qs = q.toString();
+    return request("GET", `/api/v1/social${qs ? `?${qs}` : ""}`);
+  },
+  socialStats: () => request("GET", "/api/v1/social/stats"),
+  socialStatus: (threadId, status) =>
+    request("POST", "/api/v1/social/status", { threadId, status }),
+  socialDraftReply: (threadId, mentionMode) =>
+    request("POST", "/api/v1/social/draft-reply", { threadId, mentionMode }),
+  support: (opts) => request("POST", "/api/v1/support", opts),
+  brand: () => request("GET", "/api/v1/brand"),
+  brandProfileSet: (opts) => request("POST", "/api/v1/brand/profile", opts),
+  brandProductWrite: (opts) => request("POST", "/api/v1/brand/product", opts),
+  brandIcpWrite: (opts) => request("POST", "/api/v1/brand/icp", opts),
 };

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.");
+  }
+}