@series-a/cli 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,14 +4,30 @@ All notable changes to this package are documented here. This project follows
 [Semantic Versioning](https://semver.org/) and uses
 [Changesets](https://github.com/changesets/changesets) to manage releases.
 
+## 1.5.0 — Calendar control, references, analytics report, safer campaign holds
+
+Version follows 1.4.1, the latest release on npm (it was published without a changelog entry).
+
+- Calendar: `calendar schedule <id> --at <iso>` moves or reschedules a post, `calendar unschedule <id>` cancels it and keeps the content as a draft, and `calendar delete <id>` removes it. All three cancel on Taplio first when Taplio owns the post. `content unschedule <id>` does the same from the content side.
+- Links: `references list|show|library|verify` shows the published links stored for each post and checks they still resolve.
+- Reports: `advisoros analytics report [--days n] [--format md|json] [--out file]` writes a full branded performance report (summary, outreach funnel, campaigns, content, revenue impact).
+- Campaigns (server-side, no CLI change needed): LinkedIn holds now last only until the time Madnion gives; with no time given the campaign retries within 5 minutes and asks Madnion again. "If accepted" always checks LinkedIn at send time, so someone who just accepted is no longer sent down the "No" path. Slow-setup campaigns always send at least one action per run. Wrong-name checks no longer block normal greetings such as "Hi, thanks for connecting".
+- Agents run Monday to Friday (UTC); manual runs still work on weekends.
+- Blog generation is white-label: no platform name or platform links in workspace content.
+
 ## 1.4.0 — Company news, brand imagery fix, API reliability
 
 Version jumps from 0.28.0 to 1.4.0 because npm already has releases up to 1.3.2.
 
+- Images on posts: `--image <url-or-file>` (repeat up to 8) on `content create|update|schedule` and `calendar create|update`; `--clear-images` on updates. Local JPG/PNG/GIF/WebP files (≤7 MB) are uploaded automatically.
+- Fix: scheduling or re-timing an existing calendar post no longer wipes its images, text, hashtags or CTA.
+- Image limits: posts scheduled through Taplio only carry the first image, because that is all Taplio accepts. Uploaded image files are publicly viewable by link — workspace settings block new public storage folders, so files are saved in the knowledge base's existing public folder.
+
 - New `advisoros leads company-refresh <ids...>` fetches company details and recent company news for contacts through Brave Search. It only works when the workspace's "Company news" switch is on, each company is refreshed at most once every 14 days, and every lookup is billed as `web_search` credits.
 - `brand set-imagery` works again for workspaces whose owner is stored in the older `ws_…` format. Before, it failed with "One of the supplied ids is not a valid identifier".
 - API reliability: the CLI, MCP and Agent API briefly returned 503 because the server function crashed on startup. That is fixed. No change is needed on the CLI side.
 - Server-side agent fixes also reach CLI-triggered runs: Market Research, News Monitor, Competitive Intel, Social Listening and the Intelligence Synthesizer no longer crash when the AI sends its lists in a different format.
+- New Firecrawl commands (through Madnion, billed as workspace credits): `knowledge import-site <url> --limit N` (up to 25 pages into the knowledge base), `knowledge parse <file>` (PDF/Word up to 5 MB), and `research start|status|cancel|list` for deep research jobs with a credit cap (only when the workspace's Deep research switch is on). Agent API: new `research` resource.
 - Campaigns: "Stop if replied (else continue)" checks only that contact's own saved replies (it never spends a LinkedIn read), and each contact's branches and waits are tracked separately.
 
 ## 0.28.0 — Instantly email campaigns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@series-a/cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "AdvisorPro command-line interface — drive leads, campaigns, sequences and agents from your terminal.",
   "type": "module",
   "bin": {

package/src/commands/references.mjs

@@ -0,0 +1,76 @@
+import { call } from "../api.mjs";
+import { emit, fail, ctxFrom, withCommonOpts } from "../ui.mjs";
+
+const ok = (v) => (v === null || v === undefined ? "" : v ? "" : " (dead)");
+
+function printList(d) {
+  for (const r of d.references || []) {
+    const date = r.published_at ? String(r.published_at).slice(0, 10) : "----------";
+    process.stdout.write(`${date}  ${r.id}  ${r.title || "(untitled)"}\n`);
+    if (r.blog_url) process.stdout.write(`            blog:     ${r.blog_url}${ok(r.blog_ok)}\n`);
+    if (r.linkedin_url) process.stdout.write(`            linkedin: ${r.linkedin_url}${ok(r.linkedin_ok)}\n`);
+    if (r.missing_link) process.stdout.write(`            MISSING LINK — published but no address saved\n`);
+  }
+  for (const v of d.videos || []) process.stdout.write(`video       ${v.id}  ${v.title}\n            ${v.video_url}\n`);
+  process.stdout.write(`\n${d.total ?? 0} published post(s), ${d.missing_link_count ?? 0} without a saved link in this page.\n`);
+}
+
+export function registerReferences(program) {
+  const r = program
+    .command("references")
+    .alias("refs")
+    .description("Published links (blog, LinkedIn, video) that actually went out — the same list AI writers and replies use");
+
+  withCommonOpts(r.command("list"))
+    .description("List published links")
+    .option("--channel <c>", "blog | linkedin | video | all", "all")
+    .option("--since <date>", "only posts published on/after this date (YYYY-MM-DD)")
+    .option("--search <text>", "filter by title")
+    .option("--missing", "only published posts with no saved link")
+    .option("--limit <n>", "max rows (default 100, max 500)")
+    .action(async function (o) {
+      try {
+        const res = await call("references", "list", {
+          channel: o.channel, since: o.since, search: o.search, missing: !!o.missing,
+          limit: o.limit ? Number(o.limit) : undefined,
+        }, ctxFrom(this));
+        emit(this, res, printList);
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(r.command("show <id>"))
+    .alias("get")
+    .description("Show one published post's links and publishing records")
+    .action(async function (id) {
+      try {
+        const res = await call("references", "show", { id }, ctxFrom(this));
+        emit(this, res, (d) => {
+          printList({ references: [d.reference], total: 1, missing_link_count: d.reference?.missing_link ? 1 : 0 });
+          for (const x of d.distributions || []) process.stdout.write(`  ${x.platform} ${x.status} ${x.platform_url || "-"}\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(r.command("library"))
+    .description("Show exactly what the AI writers see, ranked for a topic")
+    .option("--topic <text>", "topic to rank by")
+    .option("--limit <n>", "how many (default 15)")
+    .action(async function (o) {
+      try {
+        const res = await call("references", "library", { topic: o.topic, limit: o.limit ? Number(o.limit) : undefined }, ctxFrom(this));
+        emit(this, res, (d) => {
+          for (const i of d.library || []) process.stdout.write(`${i.kind.padEnd(8)} ${i.title}\n         ${i.canonical_url || i.linkedin_url || i.video_url || ""}\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(r.command("verify"))
+    .description("Re-check that published links still work")
+    .option("--dry-run", "check without saving results")
+    .action(async function (o) {
+      try {
+        const res = await call("references", "verify", { dry_run: !!o.dryRun }, ctxFrom(this));
+        emit(this, res, (d) => process.stdout.write(JSON.stringify(d.verify, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+}

package/src/commands/research.mjs

@@ -0,0 +1,71 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { call } from "../api.mjs";
+import { emit, fail, ctxFrom, withCommonOpts, table } from "../ui.mjs";
+
+const jobLine = (j) => `${j.id}  ${j.kind}  ${j.status}  ${j.credits_used ?? 0} credits`;
+
+export function registerResearch(program) {
+  const kb = program.commands.find((c) => c.name() === "knowledge") ?? program.command("knowledge");
+
+  withCommonOpts(kb.command("import-site <url>"))
+    .description("Import a whole website's key pages into the knowledge base (Firecrawl via Madnion)")
+    .option("--limit <n>", "maximum pages (1-25)", "10")
+    .action(async function (url, opts) {
+      try {
+        const limit = Math.max(1, Math.min(25, Number(opts.limit) || 10));
+        const r = await call("research", "crawl", { url, limit, save_to_knowledge: true }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Import started: ${jobLine(d.job || {})}\n  Check with: advisoros research status ${d.job?.id}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(kb.command("parse <file>"))
+    .description("Extract text from a PDF or Word document (max 5 MB) into the knowledge base")
+    .action(async function (file) {
+      try {
+        const buf = await readFile(file);
+        if (buf.length > 5 * 1024 * 1024) throw new Error("File is larger than 5 MB");
+        const r = await call("research", "parse", { filename: basename(file), file_base64: buf.toString("base64"), save_to_knowledge: true }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Parsed ${basename(file)} (${(d.markdown || "").length} characters)\n`));
+      } catch (e) { fail(e); }
+    });
+
+  const rs = program.command("research").description("Deep research and long Firecrawl jobs (off until enabled per workspace)");
+
+  withCommonOpts(rs.command("start <question...>"))
+    .description("Start a deep research job (needs the workspace's Deep research switch on)")
+    .option("--max-credits <n>", "credit cap for this job", "200")
+    .action(async function (question, opts) {
+      try {
+        const r = await call("research", "start", { prompt: question.join(" "), max_credits: Number(opts.maxCredits) || 200 }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ Research started: ${jobLine(d.job || {})}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(rs.command("status <id>"))
+    .description("Show a job's progress and result")
+    .action(async function (id) {
+      try {
+        const r = await call("research", "status", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`${jobLine(d.job || {})}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(rs.command("cancel <id>"))
+    .description("Cancel a running job and release its unused credit hold")
+    .action(async function (id) {
+      try {
+        const r = await call("research", "cancel", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`✓ ${jobLine(d.job || { id, status: "cancelled" })}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(rs.command("list"))
+    .description("List recent Firecrawl jobs for this workspace")
+    .action(async function () {
+      try {
+        const r = await call("research", "list", {}, ctxFrom(this));
+        emit(this, r, (d) => table((d.jobs || []).map((j) => ({ id: j.id, kind: j.kind, status: j.status, credits: j.credits_used ?? 0, created: j.created_at }))));
+      } catch (e) { fail(e); }
+    });
+}

package/src/commands/resources.mjs

@@ -2,6 +2,30 @@ import { readFile } from "node:fs/promises";
 import { call } from "../api.mjs";
 import { emit, fail, ctxFrom, withCommonOpts, table, truncate, confirmDestructive } from "../ui.mjs";
 
+const IMG_TYPES = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".gif": "image/gif", ".webp": "image/webp" };
+const collect = (v, prev = []) => prev.concat([v]);
+/** URLs pass through; local files are uploaded to workspace storage first. */
+async function resolveImages(list, cmd) {
+  if (!list || !list.length) return undefined;
+  if (list.length > 8) throw new Error("At most 8 images per post");
+  const out = [];
+  for (const item of list) {
+    if (/^https?:\/\//i.test(item)) { out.push(item); continue; }
+    const ext = (item.match(/\.[a-z0-9]+$/i)?.[0] || "").toLowerCase();
+    const type = IMG_TYPES[ext];
+    if (!type) throw new Error(`${item}: use a JPG, PNG, GIF or WebP file, or an http(s) link`);
+    const buf = await readFile(item);
+    if (buf.length > 7 * 1024 * 1024) throw new Error(`${item}: larger than 7 MB`);
+    const r = await call("media", "upload", { content_type: type, data_base64: buf.toString("base64") }, ctxFrom(cmd));
+    const url = r?.data?.url ?? r?.url;
+    if (!url) throw new Error(`${item}: upload failed`);
+    out.push(url);
+  }
+  return out;
+}
+const mediaFrom = async (opts, cmd) => (opts.clearImages ? [] : await resolveImages(opts.image, cmd));
+const IMG_OPT = ["--image <url-or-file>", "attach an image (repeat up to 8; first is the cover)", collect];
+
 function parseCsv(text) {
   // Tiny CSV parser: header row + comma-separated values, quoted fields supported.
   const lines = text.split(/\r?\n/).filter((l) => l.trim().length);
@@ -1161,11 +1185,14 @@ export function registerContent(program) {
     .option("--tags <csv>", "tags")
     .option("--scheduled <ts>", "ISO timestamp (sets status=scheduled)")
     .option("--campaign <id>", "campaign_id")
+    .option(...IMG_OPT)
     .action(async function (opts) {
       try {
         let body = opts.body;
         if (opts.bodyFile) body = await readFile(opts.bodyFile, "utf8");
+        const media_urls = await resolveImages(opts.image, this);
         const r = await call("content", "create", {
+          media_urls,
           title: opts.title, type: opts.type, body: body ?? "",
           target_platforms: opts.platforms ? opts.platforms.split(",").map((s) => s.trim()) : undefined,
           tags: opts.tags ? opts.tags.split(",").map((s) => s.trim()) : undefined,
@@ -1185,11 +1212,15 @@ export function registerContent(program) {
     .option("--platforms <csv>")
     .option("--tags <csv>")
     .option("--scheduled <ts>")
+    .option(...IMG_OPT)
+    .option("--clear-images", "remove all images")
     .action(async function (id, opts) {
       try {
         let body = opts.body;
         if (opts.bodyFile) body = await readFile(opts.bodyFile, "utf8");
+        const media_urls = await mediaFrom(opts, this);
         const r = await call("content", "update", {
+          media_urls,
           id, title: opts.title, body, status: opts.status,
           target_platforms: opts.platforms ? opts.platforms.split(",").map((s) => s.trim()) : undefined,
           tags: opts.tags ? opts.tags.split(",").map((s) => s.trim()) : undefined,
@@ -1205,9 +1236,12 @@ export function registerContent(program) {
     .option("--publish-as <p>", "personal | company")
     .option("--company-page <id>", "company page id when publishing as company")
     .option("--timezone <tz>", "IANA timezone label to store")
+    .option("--image <url-or-file>", "override the draft's images for this post (repeatable)", collect)
     .action(async function (id, ts, opts) {
       try {
+        const media_urls = await resolveImages(opts.image, this);
         const r = await call("content", "schedule", {
+          media_urls,
           id, scheduled_for: ts, channel: opts.channel,
           publish_as: opts.publishAs, company_page_id: opts.companyPage, timezone: opts.timezone,
         }, ctxFrom(this));
@@ -1422,11 +1456,14 @@ export function registerCalendar(program) {
     .option("--campaign <id>", "campaign_id")
     .option("--status <s>", "draft | scheduled | published", "draft")
     .option("--at <iso>", "ISO timestamp — schedules the post immediately via the live engine")
+    .option(...IMG_OPT)
     .action(async function (opts) {
       try {
         let content = opts.content;
         if (opts.contentFile) content = await readFile(opts.contentFile, "utf8");
+        const media_urls = await resolveImages(opts.image, this);
         const r = await call("calendar", "create", {
+          media_urls,
           scheduled_for: opts.at,
           title: opts.title, scheduled_date: opts.date, scheduled_time: opts.time,
           platform: opts.platform, content: content ?? "",
@@ -1448,11 +1485,15 @@ export function registerCalendar(program) {
     .option("--platform <p>")
     .option("--hashtags <csv>")
     .option("--cta <text>")
+    .option(...IMG_OPT)
+    .option("--clear-images", "remove all images")
     .action(async function (id, opts) {
       try {
         let content = opts.content;
         if (opts.contentFile) content = await readFile(opts.contentFile, "utf8");
+        const media_urls = await mediaFrom(opts, this);
         const r = await call("calendar", "update", {
+          media_urls,
           id, title: opts.title, scheduled_date: opts.date, scheduled_time: opts.time,
           content, status: opts.status, platform: opts.platform,
           hashtags: opts.hashtags ? opts.hashtags.split(",").map((s) => s.trim()) : undefined,

package/src/index.mjs

@@ -1,6 +1,8 @@
 import { registerStrategies } from "./commands/strategies.mjs";
 import { registerVoice } from "./commands/voice.mjs";
 import { registerBrand } from "./commands/brand.mjs";
+import { registerReferences } from "./commands/references.mjs";
+import { registerResearch } from "./commands/research.mjs";
 import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { registerAuth } from "./commands/auth.mjs";
@@ -38,11 +40,13 @@ registerInbox(program);
 registerContent(program);
 registerCalendar(program);
 registerKnowledge(program);
+registerResearch(program);
 registerSignals(program);
 registerPipelines(program);
 registerStrategies(program);
 registerVoice(program);
 registerBrand(program);
+registerReferences(program);
 registerAuthority(program);
 registerEmail(program);
 registerBriefs(program);