outrank-cli 0.1.0

package/src/core/args.js

@@ -0,0 +1,144 @@
+import { readJsonFile, readStdin, resolvePath } from './io.js';
+
+const invalidUsageError = (message) =>
+  Object.assign(new Error(message), {
+    cliCode: 'CLI_INVALID_USAGE',
+    guidance: 'Run the current command again with --help to see the required arguments and input format.',
+  });
+
+export const parseArgs = (argv) => {
+  const positionals = [];
+  const options = new Map();
+  const flags = new Set();
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === '--') {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+
+    if (token === '-h') {
+      flags.add('help');
+      continue;
+    }
+
+    if (token === '-v') {
+      flags.add('version');
+      continue;
+    }
+
+    if (!token.startsWith('--')) {
+      positionals.push(token);
+      continue;
+    }
+
+    const eqIndex = token.indexOf('=');
+    if (eqIndex >= 0) {
+      const key = token.slice(2, eqIndex);
+      const value = token.slice(eqIndex + 1);
+      const current = options.get(key) ?? [];
+      current.push(value);
+      options.set(key, current);
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith('--')) {
+      const current = options.get(key) ?? [];
+      current.push(next);
+      options.set(key, current);
+      i += 1;
+      continue;
+    }
+
+    flags.add(key);
+  }
+
+  return { positionals, options, flags };
+};
+
+export const hasFlag = (parsed, name) => parsed.flags.has(name);
+
+export const getOption = (parsed, name) => {
+  const values = parsed.options.get(name);
+  return values ? values[values.length - 1] : undefined;
+};
+
+export const getOptions = (parsed, name) => parsed.options.get(name) ?? [];
+
+export const getRequiredPositional = (parsed, index, label) => {
+  const value = parsed.positionals[index];
+  if (!value) {
+    throw invalidUsageError(`Missing required argument: ${label}.`);
+  }
+  return value;
+};
+
+export const parseIntegerOption = (parsed, name, { required = false, min, max } = {}) => {
+  const raw = getOption(parsed, name);
+  if (raw === undefined) {
+    if (required) {
+      throw invalidUsageError(`Missing required option: --${name}.`);
+    }
+    return undefined;
+  }
+
+  const value = Number(raw);
+  if (!Number.isInteger(value)) {
+    throw invalidUsageError(`--${name} must be an integer.`);
+  }
+  if (min !== undefined && value < min) {
+    throw invalidUsageError(`--${name} must be >= ${min}.`);
+  }
+  if (max !== undefined && value > max) {
+    throw invalidUsageError(`--${name} must be <= ${max}.`);
+  }
+  return value;
+};
+
+export const readJsonInput = async (parsed) => {
+  const inline = getOption(parsed, 'json');
+  const file = getOption(parsed, 'json-file');
+  const useStdin = hasFlag(parsed, 'json-stdin');
+
+  const sources = [inline ? 'inline' : null, file ? 'file' : null, useStdin ? 'stdin' : null].filter(
+    Boolean,
+  );
+  if (sources.length === 0) {
+    throw invalidUsageError('Provide one of: --json, --json-file, or --json-stdin.');
+  }
+  if (sources.length > 1) {
+    throw invalidUsageError(
+      'Use only one JSON input source: --json, --json-file, or --json-stdin.',
+    );
+  }
+
+  if (inline) {
+    try {
+      return JSON.parse(inline);
+    } catch (error) {
+      throw invalidUsageError(`Invalid JSON in --json: ${error.message}`);
+    }
+  }
+
+  if (file) {
+    try {
+      return await readJsonFile(resolvePath(file));
+    } catch (error) {
+      throw invalidUsageError(error.message);
+    }
+  }
+
+  const stdin = await readStdin();
+  if (!stdin.trim()) {
+    throw invalidUsageError('No JSON was received on stdin.');
+  }
+  try {
+    return JSON.parse(stdin);
+  } catch (error) {
+    throw invalidUsageError(`Invalid JSON from stdin: ${error.message}`);
+  }
+};

package/src/core/config.js

@@ -0,0 +1,80 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { ensureDirectory, fileExists } from './io.js';
+
+const DEFAULT_BASE_URL = 'https://outrank.so';
+
+const getConfigDir = () => process.env.OUTRANK_CONFIG_DIR || path.join(os.homedir(), '.outrank');
+export const getConfigPath = () => path.join(getConfigDir(), 'config.json');
+
+export const loadConfig = async () => {
+  const configPath = getConfigPath();
+  if (!(await fileExists(configPath))) {
+    return {};
+  }
+
+  const raw = await fs.readFile(configPath, 'utf8');
+  try {
+    const config = JSON.parse(raw);
+    return config && typeof config === 'object' ? config : {};
+  } catch {
+    return {};
+  }
+};
+
+export const saveConfig = async (config) => {
+  const configPath = getConfigPath();
+  await ensureDirectory(path.dirname(configPath));
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+};
+
+export const clearStoredAuth = async () => {
+  const configPath = getConfigPath();
+  const current = await loadConfig();
+  if (!(await fileExists(configPath))) {
+    return current;
+  }
+  const next = { ...current };
+  delete next.apiKey;
+  await saveConfig(next);
+  return next;
+};
+
+const normalizeBaseUrl = (value) => {
+  const url = new URL(value || DEFAULT_BASE_URL);
+  return url.origin.replace(/\/$/, '');
+};
+
+export const resolveRuntimeConfig = async (parsed) => {
+  const config = await loadConfig();
+  const apiKey =
+    process.env.OUTRANK_API_KEY ||
+    (parsed ? parsed.options.get('api-key')?.slice(-1)[0] : undefined) ||
+    config.apiKey;
+  const baseUrl =
+    process.env.OUTRANK_BASE_URL ||
+    (parsed ? parsed.options.get('base-url')?.slice(-1)[0] : undefined) ||
+    config.baseUrl ||
+    DEFAULT_BASE_URL;
+
+  return {
+    apiKey,
+    baseUrl: normalizeBaseUrl(baseUrl),
+    config,
+  };
+};
+
+export const storeAuthConfig = async ({ apiKey, baseUrl }) => {
+  const current = await loadConfig();
+  const next = {
+    ...current,
+    ...(apiKey ? { apiKey } : {}),
+    ...(baseUrl ? { baseUrl: normalizeBaseUrl(baseUrl) } : {}),
+  };
+  await saveConfig(next);
+  return next;
+};
+
+export const getDefaultBaseUrl = () => DEFAULT_BASE_URL;

package/src/core/errors.js

@@ -0,0 +1,15 @@
+export const cliError = (code, message, guidance, details) => ({
+  ok: false,
+  error: {
+    code,
+    message,
+    ...(details ? { details } : {}),
+  },
+  agent_guidance: guidance,
+});
+
+export const cliSuccess = (data, guidance) => ({
+  ok: true,
+  data,
+  agent_guidance: guidance,
+});

package/src/core/io.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const emitJson = (value) => {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+};
+
+export const emitAndExit = (value, code = 0) => {
+  emitJson(value);
+  process.exitCode = code;
+};
+
+export const fileExists = async (filePath) => {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const readJsonFile = async (filePath) => {
+  const content = await fs.readFile(filePath, 'utf8');
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${filePath}: ${error.message}`);
+  }
+};
+
+export const ensureDirectory = async (dirPath) => {
+  await fs.mkdir(dirPath, { recursive: true });
+};
+
+export const resolvePath = (value) => path.resolve(process.cwd(), value);
+
+export const readStdin = async () => {
+  if (process.stdin.isTTY) return '';
+
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+};

package/src/index.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+
+import { parseArgs } from './core/args.js';
+import { emitAndExit } from './core/io.js';
+import { cliError, cliSuccess } from './core/errors.js';
+import { handleAuthCommand } from './commands/auth.js';
+import { handleProductsCommand } from './commands/products.js';
+import { handleBillingCommand } from './commands/billing.js';
+import { handleSubscriptionCommand } from './commands/subscription.js';
+import { handleUsageCommand } from './commands/usage.js';
+import { handleKeywordsCommand } from './commands/keywords.js';
+import { handleArticlesCommand } from './commands/articles.js';
+
+const getVersion = () => {
+  try {
+    const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return packageJson.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+};
+
+const ROOT_HELP = `Outrank CLI
+
+Agent-first CLI for Outrank's public agent API.
+
+Usage:
+  outrank-cli <group> <command> [options]
+  outrank-cli <group> --help
+
+Groups:
+  auth        Store or verify API-key authentication.
+  products    List, create, inspect, and configure products, article settings, and Google Search Console.
+  keywords    Inspect, check write status, add, reschedule, delete, suggest, generate, and export keyword plans.
+  articles    Inspect article metadata and bodies, edit content, retry publish, precreate, and generate.
+  subscription Inspect plan, trial, quota, and add-on status.
+  usage       Inspect current usage and quota consumption.
+  billing     Product-slot purchase flows.
+
+Global Auth Options:
+  --api-key <key>      Override the API key for this command only.
+  --base-url <url>     Override the Outrank base URL for this command only.
+
+JSON Input Conventions:
+  Complex write commands accept one of:
+  --json '<object>'
+  --json-file payload.json
+  --json-stdin
+
+Examples:
+  outrank-cli auth login outr_live_xxx
+  outrank-cli auth whoami
+  outrank-cli products list --limit 20
+  outrank-cli keywords list --product 00000000-0000-0000-0000-000000000000 --scope all
+  outrank-cli articles list --product 00000000-0000-0000-0000-000000000000 --status published
+  outrank-cli subscription status
+  outrank-cli usage stats
+  outrank-cli products create --json-file product.json
+  outrank-cli billing portal-url
+  outrank-cli products output-settings update <product-id> --json-file output-settings.json
+  outrank-cli products target-audiences replace <product-id> --json-file target-audiences.json
+  outrank-cli products gsc connect <product-id>
+  outrank-cli products gsc performance <product-id>
+  outrank-cli billing purchase-products quote --additional-products 2
+`;
+
+const main = async () => {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgs(argv);
+  const first = argv[0];
+
+  if (argv.length === 0 || first === '--help' || first === '-h' || first === 'help') {
+    emitAndExit(
+      cliSuccess(
+        {
+          usage: ROOT_HELP.trim(),
+        },
+        'Choose a command group, then run that group with --help for detailed usage.',
+      ),
+    );
+    return;
+  }
+
+  if (first === '--version' || first === '-v' || first === 'version') {
+    emitAndExit(
+      cliSuccess(
+        {
+          version: getVersion(),
+        },
+        'Version returned.',
+      ),
+    );
+    return;
+  }
+
+  const group = argv[0];
+  const rest = argv.slice(1);
+
+  let result;
+  if (group === 'auth') {
+    result = await handleAuthCommand(rest);
+  } else if (group === 'products') {
+    result = await handleProductsCommand(rest);
+  } else if (group === 'keywords') {
+    result = await handleKeywordsCommand(rest);
+  } else if (group === 'articles') {
+    result = await handleArticlesCommand(rest);
+  } else if (group === 'subscription') {
+    result = await handleSubscriptionCommand(rest);
+  } else if (group === 'usage') {
+    result = await handleUsageCommand(rest);
+  } else if (group === 'billing') {
+    result = await handleBillingCommand(rest);
+  } else {
+    throw Object.assign(new Error(`Unknown command group: ${group}.`), {
+      cliCode: 'CLI_INVALID_USAGE',
+      guidance: 'Run `outrank-cli --help` to see the available top-level groups.',
+    });
+  }
+
+  emitAndExit(result, result?.ok === false ? 1 : 0);
+};
+
+main().catch((error) => {
+  const message = error?.message || 'Unexpected CLI failure.';
+  const code = error?.cliCode || 'CLI_UNEXPECTED_ERROR';
+  const guidance =
+    error?.guidance ||
+    'Retry with --help for usage details. If the command and inputs look correct, inspect the error details and try again.';
+
+  emitAndExit(cliError(code, message, guidance), 1);
+});