@oppira/cli 0.1.1 → 0.1.2

package/README.md

@@ -53,6 +53,7 @@ Pick either method per profile:
 | `oppira alerts` | `list`, `run` |
 | `oppira battlecard` | `show`, `history`, `regen` |
 | `oppira playbook` | `show`, `bootstrap`, `refresh-section`, `refresh-cluster` |
+| `oppira ads` | `accounts`, `performance`, `campaigns` — your own connected ad accounts *(Pro)* |
 | `oppira discover` | `profiles`, `suggestions`, `dismiss` |
 | `oppira studio` | posts, calendars, comments, templates, image generation, publishing *(Pro)* |
 | `oppira artifact` | `get`, `export` (reports / decks / diagrams) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oppira/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Oppira CLI — terminal control for the adaptive marketing system (competitor intelligence, playbook, studio, ops).",
   "type": "module",
   "bin": {

package/src/commands/ads.js

@@ -0,0 +1,130 @@
+// ads: read the user's OWN connected ad-account data (Meta / Google / TikTok /
+// etc., via the Studio ads integration) — NOT competitor ads (those live under
+// `comp` / the get_competitor_* MCP tools). All REST (JWT), gated on the backend
+// by requireStudioEnabled (Pro/admin) + quota. Degrades to an empty / hasAds:false
+// result when no ad account is connected, so the commands never hard-error.
+import { apiRequest } from '../http.js';
+import { out, kv, table, info } from '../output.js';
+
+export default {
+  description: 'Own ad accounts — connected accounts, performance, campaigns (Pro/admin).',
+  commands: {
+    accounts: {
+      description: 'List your connected ad accounts.',
+      usage: 'ads accounts',
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/ads-channels');
+        const accounts = res?.accounts || [];
+        if (ctx.json) { out(res, ctx); return; }
+        if (accounts.length === 0) { info('(no ad accounts connected — connect one in Studio → Ads)'); return; }
+        const rows = accounts.map((a) => ({
+          platform: a.platform || '—',
+          handle: a.handle || a.displayName || '—',
+          status: a.status || '—',
+          accountId: String(a.accountId || '—'),
+        }));
+        table(rows, [
+          { key: 'platform', label: 'PLATFORM' },
+          { key: 'handle', label: 'HANDLE' },
+          { key: 'status', label: 'STATUS' },
+          { key: 'accountId', label: 'ACCOUNT ID' },
+        ], ctx);
+      },
+    },
+
+    performance: {
+      description: 'Distilled own-ads performance (totals, per-platform, top campaigns, WoW).',
+      usage: 'ads performance [--from 2026-06-01] [--to 2026-06-30]',
+      flags: [
+        { name: 'from', description: 'Window start (YYYY-MM-DD); defaults to 30 days ago' },
+        { name: 'to', description: 'Window end (YYYY-MM-DD); defaults to today' },
+      ],
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/ads-performance', {
+          query: { fromDate: ctx.flag('from'), toDate: ctx.flag('to') },
+        });
+        if (ctx.json) { out(res, ctx); return; }
+        if (!res?.hasAds) { info('(no connected ad accounts, or ad data is unavailable right now)'); return; }
+        const t = res.totals || {};
+        kv({
+          window: res.window ? `${res.window.fromDate} → ${res.window.toDate}` : '—',
+          spend: t.spend,
+          impressions: t.impressions,
+          clicks: t.clicks,
+          ctr: t.ctr !== undefined ? `${t.ctr}%` : '—',
+          cpc: t.cpc,
+          conversions: t.conversions,
+          roas: t.roas,
+          campaigns: `${res.activeCampaignCount ?? '—'} active / ${res.campaignCount ?? '—'} total`,
+        }, ctx);
+        const byPlatform = res.byPlatform || {};
+        const pRows = Object.entries(byPlatform).map(([platform, m]) => ({
+          platform, spend: m.spend, conversions: m.conversions, roas: m.roas,
+        }));
+        if (pRows.length) {
+          info('\nBy platform:');
+          table(pRows, [
+            { key: 'platform', label: 'PLATFORM' },
+            { key: 'spend', label: 'SPEND' },
+            { key: 'conversions', label: 'CONV' },
+            { key: 'roas', label: 'ROAS' },
+          ], ctx);
+        }
+        const top = res.activeCampaigns || [];
+        if (top.length) {
+          info('\nTop active campaigns:');
+          table(top.map((c) => ({
+            name: c.name, platform: c.platform, spend: c.spend, roas: c.roas, conversions: c.conversions,
+          })), [
+            { key: 'name', label: 'CAMPAIGN', max: 34 },
+            { key: 'platform', label: 'PLATFORM' },
+            { key: 'spend', label: 'SPEND' },
+            { key: 'roas', label: 'ROAS' },
+            { key: 'conversions', label: 'CONV' },
+          ], ctx);
+        }
+        info('\n(use --json for the full aggregate incl. WoW deltas)');
+      },
+    },
+
+    campaigns: {
+      description: 'List your ad campaigns with per-campaign metrics.',
+      usage: 'ads campaigns [--status active] [--from ...] [--to ...] [--limit 25]',
+      flags: [
+        { name: 'status', description: 'Status filter, e.g. active / paused' },
+        { name: 'from', description: 'Window start (YYYY-MM-DD)' },
+        { name: 'to', description: 'Window end (YYYY-MM-DD)' },
+        { name: 'limit', description: 'Max campaigns (default 25)' },
+      ],
+      async handler(ctx) {
+        const res = await apiRequest(ctx.profileName, 'GET', '/studio/ads-channels/campaigns', {
+          query: {
+            status: ctx.flag('status'),
+            fromDate: ctx.flag('from'),
+            toDate: ctx.flag('to'),
+            limit: ctx.flag('limit'),
+          },
+        });
+        const campaigns = res?.campaigns || res?.data || [];
+        if (ctx.json) { out(res, ctx); return; }
+        if (!Array.isArray(campaigns) || campaigns.length === 0) { info('(no campaigns)'); return; }
+        const rows = campaigns.map((c) => ({
+          name: c.name || '(unnamed)',
+          platform: c.platform || '—',
+          status: c.status || '—',
+          spend: c.metrics?.spend ?? c.spend ?? '—',
+          roas: c.metrics?.roas ?? c.roas ?? '—',
+          conversions: c.metrics?.conversions ?? c.conversions ?? '—',
+        }));
+        table(rows, [
+          { key: 'name', label: 'CAMPAIGN', max: 34 },
+          { key: 'platform', label: 'PLATFORM' },
+          { key: 'status', label: 'STATUS' },
+          { key: 'spend', label: 'SPEND' },
+          { key: 'roas', label: 'ROAS' },
+          { key: 'conversions', label: 'CONV' },
+        ], ctx);
+      },
+    },
+  },
+};

package/src/commands/discover.js

@@ -1,10 +1,29 @@
 // discover: find social profiles for a company (async job) + manage the
 // weekly competitor suggestions.
 import { apiRequest } from '../http.js';
+import { getCredentials } from '../config.js';
+import { withDb, findUserOrThrow, backendImport } from '../local.js';
 import { out, table, info } from '../output.js';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+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;
+}
+
+// Render a pending-suggestions list as a table (shared by `suggestions` and
+// the post-generation output).
+function renderSuggestions(list, ctx) {
+  const rows = (Array.isArray(list) ? list : []).map((s) => ({
+    id: String(s._id || s.id || '—'),
+    name: s.candidateName || s.name || s.companyName || '—',
+    reason: s.reason || s.rationale || '—',
+  }));
+  table(rows, [{ key: 'id', label: 'ID' }, { key: 'name', label: 'NAME' }, { key: 'reason', label: 'REASON', max: 60 }], ctx);
+}
+
 export default {
   description: 'Discovery — find profiles for a company and manage suggestions.',
   commands: {
@@ -58,17 +77,40 @@ export default {
     },
 
     suggestions: {
-      description: 'List competitor suggestions.',
+      description: 'List competitor suggestions (add --generate to force a fresh run first).',
+      usage: 'discover suggestions [--generate] [--local] [--email you@co.com]',
+      flags: [
+        { name: 'generate', boolean: true, description: 'Force a fresh suggestion run before listing (LLM + web search; rate-limited)' },
+        { name: 'local', boolean: true, description: 'Run the generator engine directly (ops; needs repo + .env)' },
+        { name: 'email', description: 'Target user in --local mode (defaults to logged-in profile)' },
+      ],
       async handler(ctx) {
+        if (ctx.bool('generate')) {
+          if (ctx.useLocal) {
+            const email = opsEmail(ctx);
+            const result = await withDb(async () => {
+              const user = await findUserOrThrow(email);
+              const { generateSuggestionsForUser } = await backendImport('utils/competitorSuggestionGenerator.js');
+              return generateSuggestionsForUser(user, { debounceMinutes: 0 });
+            });
+            if (ctx.json) { out({ success: true, email, result }, ctx); return; }
+            info(`✓ Suggestion generation run for ${email} (local). ${result?.skipped ? `Skipped: ${result.skipped}.` : `Created: ${result?.created ?? 0}.`}`);
+            return;
+          }
+          info('Generating suggestions (LLM + web search — this can take up to a minute)…');
+          const gen = await apiRequest(ctx.profileName, 'POST', '/competitor-suggestions/generate', { body: {} });
+          const list = gen?.data || [];
+          if (ctx.json) { out(gen, ctx); return; }
+          if (gen?.result?.skipped) info(`(generation skipped: ${gen.result.skipped})`);
+          else info(`✓ Generated. ${gen?.result?.created ?? 0} new suggestion(s).`);
+          renderSuggestions(list, ctx);
+          return;
+        }
+
         const res = await apiRequest(ctx.profileName, 'GET', '/competitor-suggestions');
         const list = res?.data || res?.suggestions || res || [];
         if (ctx.json) { out(list, ctx); return; }
-        const rows = (Array.isArray(list) ? list : []).map((s) => ({
-          id: String(s._id || s.id || '—'),
-          name: s.name || s.companyName || '—',
-          reason: s.reason || s.rationale || '—',
-        }));
-        table(rows, [{ key: 'id', label: 'ID' }, { key: 'name', label: 'NAME' }, { key: 'reason', label: 'REASON', max: 60 }], ctx);
+        renderSuggestions(list, ctx);
       },
     },
 

package/src/index.js

@@ -13,11 +13,11 @@ import authGroup from './commands/auth.js';
 import configGroup from './commands/config.js';
 import competitorsGroup from './commands/competitors.js';
 import discoverGroup from './commands/discover.js';
-import scrapeGroup from './commands/scrape.js';
 import insightsGroup from './commands/insights.js';
 import alertsGroup from './commands/alerts.js';
 import battlecardGroup from './commands/battlecard.js';
 import playbookGroup from './commands/playbook.js';
+import adsGroup from './commands/ads.js';
 import studioGroup from './commands/studio.js';
 import artifactGroup from './commands/artifact.js';
 import adminGroup from './commands/admin.js';
@@ -26,7 +26,7 @@ import { askCommand } from './commands/ask.js';
 export function buildProgram() {
   return {
     name: 'oppira',
-    version: '0.1.0',
+    version: '0.1.2',
     description: 'Terminal control for Oppira — competitor intelligence, playbook, studio & ops.',
     groups: {
       auth: authGroup,
@@ -34,11 +34,11 @@ export function buildProgram() {
       competitors: competitorsGroup,
       comp: competitorsGroup, // alias
       discover: discoverGroup,
-      scrape: scrapeGroup,
       insights: insightsGroup,
       alerts: alertsGroup,
       battlecard: battlecardGroup,
       playbook: playbookGroup,
+      ads: adsGroup,
       studio: studioGroup,
       artifact: artifactGroup,
       admin: adminGroup,

package/src/local.js

@@ -1,8 +1,8 @@
 // Ops / "local mode". Runs commands against MongoDB + the backend's engine
 // functions directly, instead of over HTTP. This is how the CLI reaches the
-// cron-only generators (battlecard / insights / alerts / summary) and the
-// intelligent scraper without needing new HTTP endpoints — mirroring the
-// existing one-off scripts in ../scripts (dotenv + mongoose.connect + engine).
+// cron-only generators (battlecard / insights / alerts / summary) without
+// needing new HTTP endpoints — mirroring the existing one-off scripts in
+// ../scripts (dotenv + mongoose.connect + engine).
 //
 // Only usable from a repo checkout with MONGO_URI available; the published
 // customer build never exercises this path.

package/src/commands/scrape.js

@@ -1,93 +0,0 @@
-// 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.`);
-      },
-    },
-  },
-};