@series-a/cli 0.6.2 → 0.13.1

package/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.
 
+## 0.13.0 — Full lifecycle + scheduling engine
+
+- Campaign lifecycle is complete from the terminal: `campaigns update` (name, goal, sequence, sender accounts, daily send limit — no longer create-time-only), `launch`, `pause`, `resume`, `archive`, `clone`, and `delete` (dry-run preview by default, `--force` to execute, blocked when the campaign has dispatched activity unless forced).
+- Sequence editing: `sequences update-step`, `delete-step`, and `replace-steps` — steps are no longer append-only. Graph validation flags disconnected nodes and cycles before launch.
+- Scheduling engine awareness: calendar/schedule commands report whether a workspace will publish via Taplio (when connected) or the built-in cron scheduler, so automation targets the right engine.
+- Live counts after writes: campaign and sequence mutations re-read the record and return live stats, clearly separated from the stored snapshot which may lag.
+- Clearer errors under load: the API now returns a typed 429 with retry-after guidance instead of empty lists during heavy automation; the CLI surfaces this plainly.
+
+## 0.12.0 — Agent audit trail
+
+- `advisoros audit list/show/stats` — query the durable per-workspace audit log of every CLI/MCP/Agent API action (actor, surface, action, outcome, duration, correlation ID).
+- CLI requests now send actor/client/version headers so audit records attribute actions to the right user and CLI version.
+- `login` persists the profile email for audit attribution.
+
+## 0.11.0 — Video management
+
+- `videos` resource group: `list`, `show`, `create`, `generate`, `update`, `publish`, `unpublish`, `refresh`, `delete` against video projects, with workspace scoping and destructive-action confirmation.
+
+## 0.10.0 — Calendar & Command Centre write access
+
+- Full content calendar read/write/delete/schedule via CLI, with bulk operations and engine-aware scheduling (Taplio when connected, built-in cron otherwise).
+- Command Centre content management: update, approve, schedule, unschedule, and publish-now actions.
+
+## 0.9.0 — Tone of Voice
+
+- Full Tone of Voice support: workspace configuration, writing-sample references, benchmark pinning, voice cards, scoring/redrafting, and report CRUD.
+
+## 0.8.0 — Content Strategy
+
+- Full content strategy read/write: create, list, show, update, delete strategies; manage strategy posts; retry/resume generation.
+
+## 0.7.0 — Hardening & admin keys
+
+- Shared typed errors with machine-readable codes across all commands.
+- Cursor pagination up to 1,000 items per page.
+- Destructive actions require explicit confirmation (`--confirm` / `--force`).
+- `login --admin` for admin API keys, `--as-agent` impersonation flag, and `whoami` scope reporting.
+- Admin keys (`advos_admin_…`) authorize from key scope alone and work across all workspaces.
+
 ## 0.6.1 — Campaign editing
 
 - `campaigns` — added `update`/`edit` (name, description, goal, sequence, sender accounts, daily send limit, launch stage, status). Mirrors the new `update_campaign` MCP tool.

package/README.md

@@ -40,6 +40,19 @@ npx @series-a/cli@latest login
 # Prompts for API key + workspace ID (the 6-char slug, e.g. dmw9wj)
 ```
 
+### Admin login
+
+Admin keys (`advos_admin_…`) are detected automatically — no workspace prompt:
+
+```bash
+advisoros login --admin
+# ✓ Logged in as admin profile "default" — N workspaces reachable
+
+advisoros workspaces list                       # admin-only, no workspace needed
+advisoros campaigns list --workspace dmw9wj     # pass workspace per command
+advisoros whoami                                # shows scope: admin (cross-workspace)
+```
+
 Multiple workspaces?
 
 ```bash
@@ -188,6 +201,35 @@ JOB=$(advisoros agents run lead-intelligence --input '{}' --json | jq -r '.run.j
 watch -n 5 "advisoros agents job $JOB --json | jq '{status,progress}'"
 ```
 
+## Safety rails
+
+Anything that stops sending, un-enrols leads or deletes data now asks first.
+
+```bash
+# Launch is a dry run until you confirm — preflight runs server-side.
+advisoros campaigns preflight 9884b9ec
+advisoros campaigns launch 9884b9ec            # shows blockers, changes nothing
+advisoros campaigns launch 9884b9ec --confirm  # actually launches
+
+# Destructive commands prompt; scripts must pass --yes.
+advisoros campaigns delete 9884b9ec --dry-run
+advisoros campaigns delete 9884b9ec --yes
+advisoros sequences delete-step 6b60d6ad --yes
+```
+
+A campaign with no leads, no sequence, no steps or no sender account is
+**refused**, not silently activated. `--force` overrides once you know why.
+
+New commands: `campaigns preflight|archive|clone|delete|remove-leads`,
+`sequences delete|update-step|delete-step`.
+
+## Reading more than 200 rows
+
+List commands accept `--limit` up to 1000 and every list response carries
+`pagination` (`total`, `limit`, `offset`, `next_cursor`, `has_more`). If you ask
+for more than the maximum, the response says it was clamped instead of quietly
+truncating.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -238,3 +280,23 @@ git push --follow-tags
 
 See [`docs/agent-api.md`](../../docs/agent-api.md) for the underlying `/agent-api` envelope.
 
+
+
+## Admin keys
+
+Admin keys (`advos_admin_…`) are authorised by the key itself — they do **not** need an
+`agent_workspace_bindings` row. `agent_name` is an audit label only.
+
+```bash
+advisoros login --admin --profile ops     # no workspace prompt; prints reachable workspace count
+advisoros whoami --profile ops            # scope: admin (cross-workspace) + reachable count
+advisoros workspaces list --profile ops   # every reachable workspace (paginated, up to 1000)
+advisoros analytics overview --workspace dmw9wj --profile ops
+```
+
+Caller identity is overridable: `--as-agent <name>` on any command, `ADVISOROS_AGENT_NAME`
+in the environment, or the `agentName` stored on the profile at login (default `advisoros-cli`).
+
+Workspace-scoped keys are unchanged: they can only reach their own workspace (403 otherwise)
+and cannot use the `workspaces` resource. An agent without bindings now gets a typed 403
+explaining to use an admin key, instead of a 500.

package/package.json

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

package/src/api.mjs

@@ -1,5 +1,15 @@
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
 import { getProfile, DEFAULTS } from "./config.mjs";
 
+const CLI_VERSION = (() => {
+  try {
+    return createRequire(import.meta.url)("../package.json").version;
+  } catch {
+    return "unknown";
+  }
+})();
+
 export class AdvisorOSApiError extends Error {
   constructor(message, { status, body } = {}) {
     super(message);
@@ -26,7 +36,16 @@ export async function call(resource, action, params = {}, opts = {}) {
     process.env.ADVISOROS_BASE_URL ||
     stored?.baseUrl ||
     DEFAULTS.baseUrl;
-  const agentName = opts.agentName || stored?.agentName || "advisoros-cli";
+  const agentName =
+    opts.agentName ||
+    process.env.ADVISOROS_AGENT_NAME ||
+    stored?.agentName ||
+    "advisoros-cli";
+
+  const actorEmail =
+    opts.actorEmail || process.env.ADVISOROS_ACTOR_EMAIL || stored?.email || null;
+  const actorUserId =
+    opts.actorUserId || process.env.ADVISOROS_ACTOR_USER_ID || stored?.userId || null;
 
   if (!apiKey) {
     throw new AdvisorOSApiError(
@@ -55,6 +74,12 @@ export async function call(resource, action, params = {}, opts = {}) {
       headers: {
         "Content-Type": "application/json",
         "x-service-account-key": apiKey,
+        "x-surface": "cli",
+        "x-client-name": "advisoros-cli",
+        "x-client-version": CLI_VERSION,
+        "x-correlation-id": opts.correlationId || randomUUID(),
+        ...(actorUserId ? { "x-actor-user-id": actorUserId } : {}),
+        ...(actorEmail ? { "x-actor-email": actorEmail } : {}),
       },
       body: JSON.stringify(body),
     });

package/src/commands/auth.mjs

@@ -10,8 +10,11 @@ export function registerAuth(program) {
     .description("Save an API key + workspace to ~/.advisoros/config.json")
     .option("-p, --profile <name>", "profile name", "default")
     .option("--api-key <key>", "API key (otherwise prompted)")
-    .option("--workspace <id>", "workspace id (otherwise prompted)")
+    .option("--workspace <id>", "workspace id (otherwise prompted, unless --admin)")
+    .option("--admin", "admin key login — verify cross-workspace, no workspace required", false)
     .option("--base-url <url>", "agent-api base URL", DEFAULTS.baseUrl)
+    .option("--as-agent <name>", "caller identity to send as agent_name", "advisoros-cli")
+    .option("--email <email>", "your email — recorded on the audit trail for every action")
     .action(async (opts) => {
       try {
         let { apiKey, workspace, baseUrl, profile } = opts;
@@ -19,13 +22,16 @@ export function registerAuth(program) {
           const r = await prompts({
             type: "password",
             name: "v",
-            message: "API key (from Settings → API Keys)",
+            message: "API key (from Settings → API Keys; advos_admin_… for admin)",
             validate: (v) => v && v.length > 10 ? true : "Required",
           });
           apiKey = r.v;
         }
         if (!apiKey) return fail(new Error("Aborted"));
-        if (!workspace) {
+
+        const isAdmin = opts.admin || apiKey.startsWith("advos_admin_");
+
+        if (!isAdmin && !workspace) {
           const r = await prompts({
             type: "text",
             name: "v",
@@ -34,14 +40,31 @@ export function registerAuth(program) {
           });
           workspace = r.v;
         }
-        if (!workspace) return fail(new Error("Aborted"));
+        if (!isAdmin && !workspace) return fail(new Error("Aborted"));
+
+        const agentName = opts.asAgent || "advisoros-cli";
+
+        if (isAdmin) {
+          // Verify the admin key cross-workspace; no workspace slug needed.
+          const verify = await call("workspaces", "list", { limit: 1000 }, {
+            apiKey, baseUrl, agentName,
+          });
+          const count = verify?.pagination?.total ?? verify?.workspaces?.length ?? 0;
+          await setProfile(profile, { apiKey, baseUrl, admin: true, agentName, ...(opts.email ? { email: opts.email } : {}), ...(workspace ? { workspaceId: workspace } : {}) });
+          process.stdout.write(chalk.green(
+            `\n✓ Logged in as admin profile "${profile}" — ${count} workspaces reachable\n` +
+            `  Config: ${CONFIG_PATH}\n` +
+            `  Tip: pass --workspace <slug> per command, or set ADVISOROS_WORKSPACE_ID.\n`,
+          ));
+          return;
+        }
 
         // Verify the credentials with a cheap round-trip.
         const verify = await call("agents", "list", {}, {
-          apiKey, workspaceId: workspace, baseUrl,
+          apiKey, workspaceId: workspace, baseUrl, agentName,
         });
         const count = verify?.agents?.length ?? 0;
-        await setProfile(profile, { apiKey, workspaceId: workspace, baseUrl });
+        await setProfile(profile, { apiKey, workspaceId: workspace, baseUrl, agentName, ...(opts.email ? { email: opts.email } : {}) });
         process.stdout.write(chalk.green(
           `\n✓ Logged in as profile "${profile}" — workspace ${workspace} (${count} agents visible)\n` +
           `  Config: ${CONFIG_PATH}\n`,
@@ -58,9 +81,24 @@ export function registerAuth(program) {
         const p = await getProfile(opts.profile);
         if (!p) return fail(new Error(`Profile "${opts.profile}" not found. Run \`advisoros login\`.`));
         const masked = p.apiKey ? p.apiKey.slice(0, 8) + "…" + p.apiKey.slice(-4) : "(none)";
+        const isAdmin = Boolean(p.admin) || String(p.apiKey || "").startsWith("advos_admin_");
+
+        let reachable = null;
+        if (isAdmin) {
+          try {
+            const r = await call("workspaces", "list", { limit: 1000 }, {
+              apiKey: p.apiKey, baseUrl: p.baseUrl, agentName: p.agentName,
+            });
+            reachable = r?.pagination?.total ?? r?.workspaces?.length ?? null;
+          } catch { reachable = null; }
+        }
+
         process.stdout.write(
           `profile:    ${opts.profile}\n` +
-          `workspace:  ${p.workspaceId}\n` +
+          `scope:      ${isAdmin ? "admin (cross-workspace)" : "workspace"}\n` +
+          `workspace:  ${p.workspaceId || "(none — pass --workspace per command)"}\n` +
+          (isAdmin ? `reachable:  ${reachable == null ? "(could not verify)" : `${reachable} workspaces`}\n` : "") +
+          `agent:      ${p.agentName || "advisoros-cli"}\n` +
           `base url:   ${p.baseUrl || DEFAULTS.baseUrl}\n` +
           `api key:    ${masked}\n`,
         );

package/src/commands/insights.mjs

@@ -1,6 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { call } from "../api.mjs";
-import { emit, fail, ctxFrom, withCommonOpts, table, truncate } from "../ui.mjs";
+import { emit, fail, ctxFrom, withCommonOpts, table, truncate, confirmDestructive } from "../ui.mjs";
 
 const n = (v) => (v == null ? "" : String(v));
 
@@ -782,6 +782,115 @@ export function registerVideo(program) {
         emit(this, r, (d) => process.stdout.write(`${d.share_url ?? "not shared"}\n`));
       } catch (e) { fail(e); }
     });
+
+  withCommonOpts(v.command("avatars"))
+    .description("List the avatars curated for this workspace")
+    .action(async function () {
+      try {
+        const r = await call("video", "avatars", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["avatar_id", "name", "gender", "voice", "default"],
+            (d.avatars || []).map((x) => [
+              truncate(x.avatar_id, 20), truncate(x.avatar_name, 24), n(x.gender),
+              truncate(n(x.default_voice_id), 20), x.is_default ? "yes" : "",
+            ]),
+          ) + `\n${d.avatars?.length ?? 0} rows\n`);
+          if (d.note) process.stdout.write(`${d.note}\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("create"))
+    .description("Generate a new AI video (talking head or explainer)")
+    .option("--prompt <text>", "brief or script context")
+    .option("--source-url <url>", "generate an explainer from a web page")
+    .option("--content-item <id>", "generate from a content item")
+    .option("--kind <k>", "talking_head | explainer", "talking_head")
+    .option("--avatar <id>", "avatar_id (see `video avatars`)")
+    .option("--voice <id>", "voice_id")
+    .option("--style <s>", "professional | casual | educational | inspirational")
+    .option("--format <f>", "platform format (e.g. linkedin, shorts)")
+    .option("--duration <n>", "target duration in seconds")
+    .option("--script-mode <m>", "verbatim to use --prompt as the exact script")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        if (!o.prompt && !o.sourceUrl && !o.contentItem) {
+          throw new Error("Provide --prompt, --source-url or --content-item");
+        }
+        const r = await call("video", "create", {
+          prompt: o.prompt,
+          source_url: o.sourceUrl,
+          content_item_id: o.contentItem,
+          video_kind: o.kind,
+          avatar_id: o.avatar,
+          voice_id: o.voice,
+          style: o.style,
+          video_format: o.format,
+          target_duration: o.duration ? Number(o.duration) : undefined,
+          script_mode: o.scriptMode,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.video ?? d, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("update <id>"))
+    .description("Update video metadata (title, episode label, CTA)")
+    .option("--title <t>")
+    .option("--episode <label>")
+    .option("--cta-type <t>", "book_call | visit_site | subscribe | custom | none")
+    .option("--cta-label <l>")
+    .option("--cta-url <u>")
+    .option("--summary <s>")
+    .action(async function (id) {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("video", "update", {
+          id, title: o.title, episode_label: o.episode,
+          cta_type: o.ctaType, cta_label: o.ctaLabel, cta_url: o.ctaUrl, summary: o.summary,
+        }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.video, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("publish <id>"))
+    .description("Make the video publicly shareable")
+    .action(async function (id) {
+      try {
+        const r = await call("video", "publish", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`${d.share_url ?? "published"}\n`));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("unpublish <id>"))
+    .description("Revoke the public share link")
+    .action(async function (id) {
+      try {
+        const r = await call("video", "unpublish", { id }, ctxFrom(this));
+        emit(this, r, () => process.stdout.write("unpublished\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("refresh <id>"))
+    .description("Re-check the render status with the provider")
+    .action(async function (id) {
+      try {
+        const r = await call("video", "refresh", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.video ?? d, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(v.command("delete <id>"))
+    .description("Delete a video project")
+    .option("--yes", "skip confirmation")
+    .action(async function (id) {
+      try {
+        await confirmDestructive(this, `Delete video project ${id}. This cannot be undone.`);
+        const r = await call("video", "delete", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(`deleted ${d.deleted}\n`));
+      } catch (e) { fail(e); }
+    });
 }
 
 export function registerWatchlist(program) {
@@ -950,6 +1059,64 @@ export function registerActivity(program) {
     });
 }
 
+export function registerAudit(program) {
+  const a = program.command("audit").description("Audit trail of CLI / agent / assistant actions");
+
+  withCommonOpts(a.command("list"))
+    .description("List audited actions (newest first)")
+    .option("--status <s>", "ok | denied | error")
+    .option("--surface <s>", "cli | mcp | api | internal")
+    .option("--resource <r>", "e.g. leads, campaigns, content")
+    .option("--actor <email>", "filter by person")
+    .option("--writes", "only actions that changed data")
+    .option("--since <iso>", "ISO timestamp lower bound")
+    .option("--until <iso>", "ISO timestamp upper bound")
+    .option("--limit <n>", "max rows", "50")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("audit", "list", {
+          status: o.status, surface: o.surface, resource: o.resource,
+          actor_email: o.actor, writes_only: !!o.writes,
+          since: o.since, until: o.until, limit: Number(o.limit),
+        }, ctxFrom(this));
+        emit(this, r, (d) => {
+          process.stdout.write(table(
+            ["when", "who", "from", "action", "status", "ms"],
+            (d.entries || []).map((x) => [
+              n(x.created_at).replace("T", " ").slice(0, 19),
+              truncate(x.actor_email || x.agent_name || "-", 24),
+              n(x.surface),
+              truncate(`${x.resource}.${x.action}`, 28),
+              n(x.status),
+              n(x.duration_ms),
+            ]),
+          ) + `\n${d.entries?.length ?? 0} rows\n`);
+        });
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(a.command("show <id>"))
+    .description("Full request and outcome for one audited action")
+    .action(async function (id) {
+      try {
+        const r = await call("audit", "get", { id }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d.entry, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+
+  withCommonOpts(a.command("stats"))
+    .description("Rolled-up audit summary")
+    .option("--since <iso>", "ISO timestamp lower bound")
+    .action(async function () {
+      try {
+        const o = this.optsWithGlobals();
+        const r = await call("audit", "stats", { since: o.since }, ctxFrom(this));
+        emit(this, r, (d) => process.stdout.write(JSON.stringify(d, null, 2) + "\n"));
+      } catch (e) { fail(e); }
+    });
+}
+
 export function registerWorkspacesExtras(program) {
   const w = program.command("workspaces").description("Workspaces (admin keys only)");
 
@@ -1024,11 +1191,36 @@ export function registerIntegrations(program) {
     });
 
   withCommonOpts(i.command("check <platform>"))
-    .description("Health-check one integration")
+    .description("Health-check one integration (e.g. linkedin_tool, resend)")
     .action(async function (platform) {
       try {
         const r = await call("integrations", "check", { platform }, ctxFrom(this));
         emit(this, r, (d) => process.stdout.write(JSON.stringify(d, null, 2) + "\n"));
       } catch (e) { fail(e); }
     });
+
+  withCommonOpts(i.command("health"))
+    .description("Live verdict: is Resend configured and are LinkedIn seats connected?")
+    .action(async function () {
+      try {
+        const r = await call("integrations", "health", {}, ctxFrom(this));
+        emit(this, r, (d) => {
+          const flag = d.healthy ? "✔ healthy" : "✖ issues: " + (d.issues || []).join(", ");
+          process.stdout.write(`${flag}\n`);
+          process.stdout.write(table(
+            ["integration", "state", "detail"],
+            [
+              ["resend", d.resend?.state ?? "unknown",
+                d.resend?.configured ? `from=${d.resend?.from_email ?? "?"}` : (d.resend?.detail ?? "not configured")],
+              ...(d.linkedin?.seats?.length
+                ? d.linkedin.seats.map((s) => [
+                    `linkedin:${truncate(s.display_name || s.account_id || "?", 22)}`,
+                    s.state, s.connection_status ?? "",
+                  ])
+                : [["linkedin", d.linkedin?.verdict ?? "unknown", "no seats"]]),
+            ],
+          ) + "\n");
+        });
+      } catch (e) { fail(e); }
+    });
 }