@oppira/cli 0.1.0

package/src/commands/scrape.js

@@ -0,0 +1,93 @@
+// scrape: on-demand intelligent scrape (local engine) + raw per-platform
+// endpoints (remote). The intelligent path is the one that mirrors S3, recomputes
+// summaries, and fires battlecard/profile triggers — the raw path hits a single
+// Apify actor and bypasses that pipeline (and is currently unauthenticated).
+import { apiRequest } from '../http.js';
+import { getCredentials } from '../config.js';
+import { withDb, findUserOrThrow, findCompetitorsForUser, backendImport } from '../local.js';
+import { out, info } from '../output.js';
+
+// CLI short form → canonical platform key used by scrapeCompetitorIntelligent.
+const PLATFORM_ALIASES = {
+  fb: 'facebook', facebook: 'facebook',
+  ig: 'instagram', instagram: 'instagram',
+  x: 'x', twitter: 'x',
+  li: 'linkedin', linkedin: 'linkedin',
+};
+
+const RAW_ENDPOINTS = {
+  facebook: '/scrape-facebook',
+  'facebook-posts': '/scrape-facebook-posts',
+  'facebook-ads': '/scrape-facebook-ads',
+  'google-ads': '/scrape-google-ads',
+  instagram: '/scrape-instagram',
+  twitter: '/scrape-twitter',
+  linkedin: '/scrape-linkedin',
+  trustpilot: '/scrape-trustpilot',
+};
+
+function opsEmail(ctx) {
+  const email = ctx.flag('email') || getCredentials(ctx.profileName).email;
+  if (!email) throw new Error('Provide --email (or log in) to select the target user.');
+  return email;
+}
+
+export default {
+  description: 'Scraping — on-demand intelligent scrape (ops) + raw per-platform.',
+  commands: {
+    run: {
+      description: 'Intelligent on-demand scrape of a competitor now (ops / local mode).',
+      usage: 'scrape run <competitor> [--platforms fb,ig,x,li] [--email you@co.com]',
+      flags: [
+        { name: 'platforms', description: 'Comma list to limit (fb,ig,x,li); default all social' },
+        { name: 'email', description: 'Target user (defaults to logged-in profile)' },
+      ],
+      async handler(ctx) {
+        const email = opsEmail(ctx);
+        const nameQuery = ctx.arg(0);
+        if (!nameQuery) throw new Error('Usage: oppira scrape run <competitor> [--platforms fb,ig]');
+
+        let allowedPlatforms = null;
+        if (ctx.flag('platforms')) {
+          allowedPlatforms = String(ctx.flag('platforms')).split(',')
+            .map((p) => PLATFORM_ALIASES[p.trim().toLowerCase()])
+            .filter(Boolean);
+          if (allowedPlatforms.length === 0) throw new Error('No valid platforms in --platforms (use fb,ig,x,li).');
+        }
+
+        const result = await withDb(async () => {
+          const user = await findUserOrThrow(email);
+          const competitors = await findCompetitorsForUser(user, nameQuery);
+          if (competitors.length === 0) throw new Error(`No competitor matches "${nameQuery}" for ${email}.`);
+          if (competitors.length > 1) throw new Error(`Ambiguous: ${competitors.map((c) => c.name).join(', ')}.`);
+          const { scrapeCompetitorIntelligent } = await backendImport('utils/scraperUtils.js');
+          info(`Scraping "${competitors[0].name}"${allowedPlatforms ? ` (${allowedPlatforms.join(', ')})` : ''}…`);
+          // requireScrapingFlag:false → on-demand semantics (scrape platforms not
+          // currently mid-scrape), rather than the cron's flag-driven path.
+          return scrapeCompetitorIntelligent(competitors[0], user, allowedPlatforms, { requireScrapingFlag: false });
+        });
+        if (ctx.json) { out({ success: true, email, competitor: nameQuery, result }, ctx); return; }
+        info(`✓ Scrape complete for "${nameQuery}".`);
+      },
+    },
+
+    raw: {
+      description: 'Call a single raw platform scraper (remote). Bypasses the intelligent pipeline.',
+      usage: 'scrape raw <platform> --url <url>   (platforms: ' + Object.keys(RAW_ENDPOINTS).join(', ') + ')',
+      flags: [{ name: 'url', description: 'Profile / page URL to scrape' }],
+      async handler(ctx) {
+        const platform = ctx.arg(0);
+        const endpoint = RAW_ENDPOINTS[platform];
+        if (!endpoint) throw new Error(`Unknown platform "${platform}". One of: ${Object.keys(RAW_ENDPOINTS).join(', ')}`);
+        const url = ctx.flag('url');
+        if (!url) throw new Error('Usage: oppira scrape raw <platform> --url <url>');
+        const email = getCredentials(ctx.profileName).email;
+        const res = await apiRequest(ctx.profileName, 'POST', endpoint, {
+          body: { url, userEmails: email || '' },
+        });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Raw ${platform} scrape done.`);
+      },
+    },
+  },
+};

package/src/commands/studio.js

@@ -0,0 +1,185 @@
+// studio: content-creation surface (Pro/admin). v1 covers the high-value
+// surfaces — posts, calendars, comment inbox, plus generate/publish/draft-reply
+// actions. Deeper template/image/policy/ads coverage is the plan's final phase.
+import { apiRequest } from '../http.js';
+import { out, table, info } from '../output.js';
+
+export default {
+  description: 'Studio — content calendar, posts, comment inbox (Pro/admin).',
+  commands: {
+    posts: {
+      description: 'List Studio posts.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/posts');
+        const list = res?.data || res?.posts || res || [];
+        if (ctx.json) { out(list, ctx); return; }
+        const rows = (Array.isArray(list) ? list : []).map((p) => ({
+          id: String(p._id || p.id || '—'),
+          status: p.status || '—',
+          channel: p.channel || (p.channels && p.channels.join(',')) || '—',
+          scheduled: p.scheduledAt || p.publishAt || '—',
+          body: (p.body || p.caption || '').slice(0, 40),
+        }));
+        table(rows, [
+          { key: 'id', label: 'ID' }, { key: 'status', label: 'STATUS' },
+          { key: 'channel', label: 'CHANNEL' }, { key: 'scheduled', label: 'SCHEDULED' },
+          { key: 'body', label: 'BODY', max: 42 },
+        ], ctx);
+      },
+    },
+
+    publish: {
+      description: 'Publish a Studio post now.',
+      usage: 'studio publish <postId>',
+      async handler(ctx) {
+        const id = ctx.arg(0);
+        if (!id) throw new Error('Usage: oppira studio publish <postId>');
+        const res = await apiRequest(ctx.profileName, 'POST', `/studio/posts/${id}/publish`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Publish requested for post ${id}. ${res?.message || ''}`);
+      },
+    },
+
+    calendars: {
+      description: 'List content calendars.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/calendars');
+        out(res?.data || res, ctx);
+      },
+    },
+
+    'calendar-generate': {
+      description: 'Generate a content calendar week.',
+      usage: 'studio calendar-generate [--week 2026-07-20] [--prompt "..."]',
+      flags: [
+        { name: 'week', description: 'Week start date (YYYY-MM-DD)' },
+        { name: 'prompt', description: 'Optional steering prompt' },
+      ],
+      async handler(ctx) {
+        const body = {};
+        if (ctx.flag('week')) body.weekStart = ctx.flag('week');
+        if (ctx.flag('prompt')) body.userPrompt = ctx.flag('prompt');
+        const res = await apiRequest(ctx.profileName, 'POST', '/studio/calendar/generate', { body });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Calendar generation triggered. ${res?.message || ''}`);
+      },
+    },
+
+    comments: {
+      description: 'List Studio comment inbox (add --unread for the unread count).',
+      flags: [{ name: 'unread', boolean: true, description: 'Show unread count only' }],
+      async handler(ctx) {
+        if (ctx.bool('unread')) {
+          const res = await apiRequest(ctx.profileName, 'GET', '/studio/comments/unread-count');
+          out(res?.data || res, ctx);
+          return;
+        }
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/comments');
+        const list = res?.data || res?.comments || res || [];
+        if (ctx.json) { out(list, ctx); return; }
+        const rows = (Array.isArray(list) ? list : []).map((c) => ({
+          id: String(c._id || c.id || '—'),
+          channel: c.channel || '—',
+          author: c.author || c.authorName || '—',
+          text: (c.text || c.message || '').slice(0, 50),
+          read: c.read || c.isRead ? 'yes' : 'no',
+        }));
+        table(rows, [
+          { key: 'id', label: 'ID' }, { key: 'channel', label: 'CHANNEL' },
+          { key: 'author', label: 'AUTHOR' }, { key: 'text', label: 'TEXT', max: 52 },
+          { key: 'read', label: 'READ' },
+        ], ctx);
+      },
+    },
+
+    'draft-reply': {
+      description: 'Draft an AI reply for a comment.',
+      usage: 'studio draft-reply <commentId>',
+      async handler(ctx) {
+        const id = ctx.arg(0);
+        if (!id) throw new Error('Usage: oppira studio draft-reply <commentId>');
+        const res = await apiRequest(ctx.profileName, 'POST', `/studio/comments/${id}/draft-reply`, { body: {} });
+        out(res?.data || res, ctx);
+      },
+    },
+
+    templates: {
+      description: 'List image templates.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/templates');
+        out(res?.data || res, ctx);
+      },
+    },
+
+    formats: {
+      description: 'List the format menu.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/formats');
+        out(res?.data || res, ctx);
+      },
+    },
+
+    settings: {
+      description: 'Show content settings.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/settings');
+        out(res?.data || res, ctx);
+      },
+    },
+
+    channels: {
+      description: 'List connected publishing channels.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/channels');
+        out(res?.data || res, ctx);
+      },
+    },
+
+    assets: {
+      description: 'List the asset library.',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/assets');
+        out(res?.data || res, ctx);
+      },
+    },
+
+    policy: {
+      description: 'Show the content policy (add --regenerate to rebuild it).',
+      flags: [{ name: 'regenerate', boolean: true, description: 'Regenerate the policy' }],
+      async handler(ctx) {
+        if (ctx.bool('regenerate')) {
+          const res = await apiRequest(ctx.profileName, 'POST', '/studio/policy/regenerate', { body: {} });
+          if (ctx.json) { out(res, ctx); return; }
+          info(`✓ Content policy regeneration triggered. ${res?.message || ''}`);
+          return;
+        }
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/policy');
+        out(res?.data || res, ctx);
+      },
+    },
+
+    retry: {
+      description: 'Retry a failed Studio post.',
+      usage: 'studio retry <postId>',
+      async handler(ctx) {
+        const id = ctx.arg(0);
+        if (!id) throw new Error('Usage: oppira studio retry <postId>');
+        const res = await apiRequest(ctx.profileName, 'POST', `/studio/posts/${id}/retry`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Retry requested for post ${id}. ${res?.message || ''}`);
+      },
+    },
+
+    'generate-image': {
+      description: 'Generate the image for a Studio post.',
+      usage: 'studio generate-image <postId>',
+      async handler(ctx) {
+        const id = ctx.arg(0);
+        if (!id) throw new Error('Usage: oppira studio generate-image <postId>');
+        const res = await apiRequest(ctx.profileName, 'POST', `/studio/posts/${id}/generate-image`, { body: {} });
+        if (ctx.json) { out(res, ctx); return; }
+        info(`✓ Image generation triggered for post ${id}. ${res?.message || ''}`);
+      },
+    },
+  },
+};

package/src/config.js

@@ -0,0 +1,97 @@
+// Config + credential store under ~/.oppira. Config (non-secret: api url,
+// default output) and credentials (tokens, api key) live in separate files so
+// the credential file can be locked down to 0600. Everything is keyed by
+// profile, so one install can talk to prod + staging + multiple accounts.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const CONFIG_DIR = process.env.OPPIRA_CONFIG_DIR || path.join(os.homedir(), '.oppira');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const CREDENTIALS_FILE = path.join(CONFIG_DIR, 'credentials.json');
+
+const DEFAULT_API_URL = process.env.OPPIRA_API_URL || 'http://localhost:3008';
+
+function ensureDir() {
+  if (!fs.existsSync(CONFIG_DIR)) fs.mkdirSync(CONFIG_DIR, { recursive: true });
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+export function loadConfig() {
+  const cfg = readJson(CONFIG_FILE, null);
+  if (cfg && cfg.profiles) return cfg;
+  return {
+    currentProfile: 'default',
+    profiles: { default: { apiUrl: DEFAULT_API_URL, output: 'table' } },
+  };
+}
+
+export function saveConfig(cfg) {
+  ensureDir();
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2));
+}
+
+function loadCredentials() {
+  return readJson(CREDENTIALS_FILE, {});
+}
+
+function saveCredentials(creds) {
+  ensureDir();
+  fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2));
+  try { fs.chmodSync(CREDENTIALS_FILE, 0o600); } catch { /* best-effort on Windows */ }
+}
+
+// Resolve the active profile name: --profile flag > env > config current.
+export function resolveProfileName(flags = {}) {
+  return flags.profile || process.env.OPPIRA_PROFILE || loadConfig().currentProfile || 'default';
+}
+
+export function getProfile(name) {
+  const cfg = loadConfig();
+  const profileName = name || cfg.currentProfile || 'default';
+  const profile = cfg.profiles[profileName] || { apiUrl: DEFAULT_API_URL, output: 'table' };
+  return { name: profileName, ...profile };
+}
+
+export function setProfileValue(name, key, value) {
+  const cfg = loadConfig();
+  if (!cfg.profiles[name]) cfg.profiles[name] = { apiUrl: DEFAULT_API_URL, output: 'table' };
+  cfg.profiles[name][key] = value;
+  saveConfig(cfg);
+  return cfg.profiles[name];
+}
+
+export function useProfile(name) {
+  const cfg = loadConfig();
+  if (!cfg.profiles[name]) cfg.profiles[name] = { apiUrl: DEFAULT_API_URL, output: 'table' };
+  cfg.currentProfile = name;
+  saveConfig(cfg);
+  return cfg;
+}
+
+export function getCredentials(profileName) {
+  return loadCredentials()[profileName] || {};
+}
+
+export function setCredentials(profileName, patch) {
+  const creds = loadCredentials();
+  creds[profileName] = { ...(creds[profileName] || {}), ...patch };
+  saveCredentials(creds);
+  return creds[profileName];
+}
+
+export function clearCredentials(profileName) {
+  const creds = loadCredentials();
+  delete creds[profileName];
+  saveCredentials(creds);
+}
+
+export const paths = { CONFIG_DIR, CONFIG_FILE, CREDENTIALS_FILE };

package/src/framework.js

@@ -0,0 +1,121 @@
+// Tiny dependency-free command framework. Enough structure for a full
+// subcommand tree (`oppira <group> <command> [args] [--flags]`) plus top-level
+// commands (`oppira ask "..."`), with generated help and typed flag parsing —
+// without pulling in commander/yargs, so the CLI runs with just `node`.
+
+const GLOBAL_BOOLEAN_FLAGS = new Set(['json', 'local', 'help', 'version', 'yes']);
+
+// Parse argv into { positionals, flags }. Rules:
+//   --key value   → flags.key = "value"      (unless value looks like a flag)
+//   --key=value   → flags.key = "value"
+//   --flag        → flags.flag = true        (boolean; also when next is a flag)
+//   -k            → treated as long flag "k"
+// Known booleans (global + per-command) never consume the next token.
+export function parseArgs(tokens, booleanFlags = new Set()) {
+  const positionals = [];
+  const flags = {};
+  const bools = new Set([...GLOBAL_BOOLEAN_FLAGS, ...booleanFlags]);
+
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok === '--') { positionals.push(...tokens.slice(i + 1)); break; }
+    if (tok.startsWith('--') || (tok.startsWith('-') && tok.length === 2 && Number.isNaN(Number(tok)))) {
+      const raw = tok.replace(/^--?/, '');
+      const eq = raw.indexOf('=');
+      if (eq !== -1) {
+        flags[raw.slice(0, eq)] = raw.slice(eq + 1);
+        continue;
+      }
+      const key = raw;
+      const next = tokens[i + 1];
+      if (bools.has(key) || next === undefined || next.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+      continue;
+    }
+    positionals.push(tok);
+  }
+  return { positionals, flags };
+}
+
+// A small helper the handlers receive, so they don't reach into raw flags.
+export function makeContext({ positionals, flags }) {
+  return {
+    positionals,
+    flags,
+    arg(i) { return positionals[i]; },
+    flag(name, fallback = undefined) {
+      return Object.prototype.hasOwnProperty.call(flags, name) ? flags[name] : fallback;
+    },
+    bool(name) { return flags[name] === true || flags[name] === 'true'; },
+    get json() { return this.bool('json'); },
+    get useLocal() { return this.bool('local'); },
+  };
+}
+
+function pad(str, width) { return String(str).padEnd(width, ' '); }
+
+export function renderProgramHelp(program) {
+  const lines = [];
+  lines.push(`${program.name} v${program.version} — ${program.description}`);
+  lines.push('');
+  lines.push('Usage:');
+  lines.push(`  ${program.name} <command> [subcommand] [args] [--flags]`);
+  lines.push('');
+  lines.push('Command groups:');
+  const groupWidth = Math.max(...Object.keys(program.groups).map((g) => g.length)) + 2;
+  for (const [name, group] of Object.entries(program.groups)) {
+    lines.push(`  ${pad(name, groupWidth)}${group.description}`);
+  }
+  if (program.topLevel && Object.keys(program.topLevel).length) {
+    lines.push('');
+    lines.push('Top-level commands:');
+    const tlWidth = Math.max(...Object.keys(program.topLevel).map((c) => c.length)) + 2;
+    for (const [name, cmd] of Object.entries(program.topLevel)) {
+      lines.push(`  ${pad(name, tlWidth)}${cmd.description}`);
+    }
+  }
+  lines.push('');
+  lines.push('Global flags:');
+  lines.push('  --json            Machine-readable JSON output (scripting / agents)');
+  lines.push('  --local           Run against MongoDB + engines directly (ops mode; needs repo + MONGO_URI)');
+  lines.push('  --profile <name>  Use a named config profile (default: current)');
+  lines.push('  --help, --version');
+  lines.push('');
+  lines.push(`Run "${program.name} <group> --help" to list a group's commands.`);
+  return lines.join('\n');
+}
+
+export function renderGroupHelp(program, groupName, group) {
+  const lines = [];
+  lines.push(`${program.name} ${groupName} — ${group.description}`);
+  lines.push('');
+  lines.push('Commands:');
+  const width = Math.max(...Object.keys(group.commands).map((c) => c.length)) + 2;
+  for (const [name, cmd] of Object.entries(group.commands)) {
+    lines.push(`  ${pad(name, width)}${cmd.description || ''}`);
+  }
+  return lines.join('\n');
+}
+
+export function renderCommandHelp(program, path, cmd) {
+  const lines = [];
+  lines.push(`${program.name} ${path} — ${cmd.description || ''}`);
+  if (cmd.usage) { lines.push(''); lines.push('Usage:'); lines.push(`  ${program.name} ${cmd.usage}`); }
+  if (cmd.flags && cmd.flags.length) {
+    lines.push('');
+    lines.push('Flags:');
+    const width = Math.max(...cmd.flags.map((f) => f.name.length)) + 4;
+    for (const f of cmd.flags) lines.push(`  --${pad(f.name, width)}${f.description || ''}`);
+  }
+  return lines.join('\n');
+}
+
+export function collectBooleanFlags(cmd) {
+  const set = new Set();
+  for (const f of cmd?.flags || []) if (f.boolean) set.add(f.name);
+  return set;
+}

package/src/http.js

@@ -0,0 +1,157 @@
+// Authenticated HTTP client for the Oppira REST API. Handles the JWT dance
+// (15-min access token + refresh) transparently: on an expired-token response
+// it refreshes once using the stored refresh token and retries. Falls back to
+// the durable `ca_` API key when no JWT session is present (works on /mcp today,
+// and on REST once the auth enabler ships — see the CLI plan).
+
+import { getProfile, getCredentials, setCredentials } from './config.js';
+
+export class ApiError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function joinUrl(base, pathname) {
+  return `${base.replace(/\/$/, '')}/${pathname.replace(/^\//, '')}`;
+}
+
+// Extract the refreshToken value from a Set-Cookie header list.
+function extractRefreshCookie(res) {
+  const cookies = typeof res.headers.getSetCookie === 'function'
+    ? res.headers.getSetCookie()
+    : [res.headers.get('set-cookie')].filter(Boolean);
+  for (const c of cookies) {
+    const m = /(?:^|;\s*)refreshToken=([^;]+)/.exec(c);
+    if (m) return decodeURIComponent(m[1]);
+  }
+  return null;
+}
+
+async function parseBody(res) {
+  const text = await res.text();
+  if (!text) return null;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+export async function login(profileName, email, password) {
+  const profile = getProfile(profileName);
+  const res = await fetch(joinUrl(profile.apiUrl, '/users/login'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  });
+  const body = await parseBody(res);
+  if (!res.ok) {
+    throw new ApiError(body?.message || `Login failed (${res.status})`, { status: res.status, body });
+  }
+  const refreshToken = extractRefreshCookie(res);
+  const creds = {
+    accessToken: body.accessToken,
+    refreshToken,
+    email: body.user?.email || email,
+    apiKey: body.user?.apiKey || undefined,
+  };
+  setCredentials(profile.name, creds);
+  return { user: body.user, accessToken: body.accessToken };
+}
+
+async function refreshAccessToken(profile) {
+  const creds = getCredentials(profile.name);
+  if (!creds.refreshToken) return null;
+  const res = await fetch(joinUrl(profile.apiUrl, '/users/refresh-token'), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      // The refresh handler reads the cookie OR body.refreshToken — send both.
+      Cookie: `refreshToken=${encodeURIComponent(creds.refreshToken)}`,
+    },
+    body: JSON.stringify({ refreshToken: creds.refreshToken }),
+  });
+  if (!res.ok) return null;
+  const body = await parseBody(res);
+  const rotated = extractRefreshCookie(res);
+  const patch = { accessToken: body.accessToken };
+  if (rotated) patch.refreshToken = rotated;
+  setCredentials(profile.name, patch);
+  return body.accessToken;
+}
+
+function authHeader(creds) {
+  if (creds.accessToken) return `Bearer ${creds.accessToken}`;
+  if (creds.apiKey) return `Bearer ${creds.apiKey}`;
+  return null;
+}
+
+function isExpiredTokenResponse(status, body) {
+  if (status === 401) return true;
+  if (status === 403 && typeof body?.message === 'string' && /expired|invalid/i.test(body.message)) return true;
+  return false;
+}
+
+// Core authenticated request. `pathname` is relative to the profile's apiUrl.
+export async function apiRequest(profileName, method, pathname, { body, query } = {}) {
+  const profile = getProfile(profileName);
+  let creds = getCredentials(profile.name);
+
+  let url = joinUrl(profile.apiUrl, pathname);
+  if (query && Object.keys(query).length) {
+    const qs = new URLSearchParams(
+      Object.entries(query).filter(([, v]) => v !== undefined && v !== null)
+    ).toString();
+    if (qs) url += `?${qs}`;
+  }
+
+  const doFetch = async () => {
+    // Identify as the CLI (diagnostics / telemetry). Limits are client-agnostic.
+    const headers = { 'Content-Type': 'application/json', 'X-Oppira-Client': 'oppira-cli' };
+    const auth = authHeader(creds);
+    if (auth) headers.Authorization = auth;
+    let res;
+    try {
+      res = await fetch(url, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      });
+    } catch (err) {
+      // Connection refused / DNS / TLS — surface something actionable instead
+      // of the bare "fetch failed".
+      throw new ApiError(
+        `Cannot reach ${profile.apiUrl} (profile "${profile.name}"). Is the API running? Set it with: oppira config set-url <url>`,
+        { status: 0, body: { cause: err?.message } }
+      );
+    }
+    return { res, parsed: await parseBody(res) };
+  };
+
+  let { res, parsed } = await doFetch();
+
+  // One transparent refresh-and-retry on an expired access token.
+  if (isExpiredTokenResponse(res.status, parsed) && creds.refreshToken) {
+    const newToken = await refreshAccessToken(profile);
+    if (newToken) {
+      creds = getCredentials(profile.name);
+      ({ res, parsed } = await doFetch());
+    }
+  }
+
+  if (!res.ok) {
+    // Preserve quota / plan-gate shapes for callers to render nicely.
+    const msg = parsed?.message || parsed?.error || `Request failed (${res.status})`;
+    throw new ApiError(msg, { status: res.status, body: parsed });
+  }
+  return parsed;
+}
+
+export function requireAuth(profileName) {
+  const profile = getProfile(profileName);
+  const creds = getCredentials(profile.name);
+  if (!creds.accessToken && !creds.apiKey) {
+    throw new ApiError(`Not logged in for profile "${profile.name}". Run: oppira auth login`);
+  }
+  return creds;
+}