@sprid/cli 0.1.6 → 0.1.8

package/src/commands/publishing.mjs

@@ -0,0 +1,109 @@
+// sprid post schedule | publish | schedule-batch: putting a post in front of
+// an audience, through the same tools an agent calls. Publishing now is public
+// and cannot be taken back, so it asks unless --yes. A booking can be taken
+// back (`sprid queue cancel <publishId>`), so scheduling does not ask.
+//
+// TikTok's privacy level, comment/duet/stitch permissions and the
+// commercial-content disclosure have no defaults and are never remembered, so
+// a TikTok destination needs them in --options every time.
+
+import { UsageError } from "../args.mjs";
+import { C, OK } from "../format.mjs";
+import { callTool, listFlag, readJson, show } from "../tools.mjs";
+import { confirm } from "./reviews.mjs";
+
+const POST_REF = /^([1-9]\d*|[A-Za-z][A-Za-z0-9]{1,4}-\d+)$/;
+const TIKTOK_FIELDS = "privacyLevel, disableComment, disableDuet, disableStitch and the commercial-content answers";
+
+export const PUBLISHING_VERBS = ["schedule", "publish", "schedule-batch"];
+
+export async function publishing(ctx) {
+  const [verb, ref] = ctx.positionals;
+  if (verb === "schedule-batch") return scheduleBatch(ctx);
+  const usage = verb === "publish"
+    ? "sprid post publish <postId> [--platforms a,b] [--options <options.json>] [--yes]"
+    : "sprid post schedule <postId> (--at ISO|--next|--queue-end) [--platforms a,b] [--time HH:MM] [--shift-later] [--options <options.json>]";
+  if (!POST_REF.test(String(ref ?? ""))) throw new UsageError(usage);
+  const id = /^\d+$/.test(ref) ? Number(ref) : String(ref).toUpperCase();
+  const base = { id, ...(await destination(ctx)) };
+  return verb === "publish" ? publish(ctx, base) : schedule(ctx, base, usage);
+}
+
+/** Platforms and per-platform options, shared by every verb here. */
+async function destination(ctx) {
+  const platforms = listFlag(ctx.flags.platforms);
+  const options = typeof ctx.flags.options === "string" ? await readJson(ctx, ctx.flags.options) : undefined;
+  if (platforms?.includes("tiktok") && !options?.tiktok) {
+    throw new UsageError(`TikTok needs its answers every time: put ${TIKTOK_FIELDS} under "tiktok" in --options <options.json>.`);
+  }
+  return { ...(platforms ? { platforms } : {}), ...(options ? { options } : {}) };
+}
+
+async function schedule(ctx, base, usage) {
+  const when = typeof ctx.flags.at === "string" ? { when: ctx.flags.at }
+    : ctx.flags.next ? { nextFreeSlot: true }
+    : ctx.flags["queue-end"] ? { queueEnd: true }
+    : null;
+  if (!when) throw new UsageError(usage);
+  const args = {
+    ...base,
+    ...when,
+    ...(typeof ctx.flags.time === "string" ? { time: ctx.flags.time } : {}),
+    ...(ctx.flags["shift-later"] ? { shiftLater: true } : {}),
+  };
+  const res = await callTool(ctx, "schedule_post", args);
+  if (ctx.json) {
+    ctx.out(res);
+    return 0;
+  }
+  const at = String(res?.scheduledFor ?? "").replace("T", " ").slice(0, 16);
+  for (const r of res?.scheduled ?? []) ctx.print(`  ${C.ok(OK)} ${r.platform} ${at} UTC  ${C.dim(`publish ${r.publishId}`)}`);
+  for (const e of res?.errors ?? []) ctx.print(`  ${C.bad("✗")} ${e.platform ?? ""} ${e.error ?? e.message ?? JSON.stringify(e)}`);
+  if (res?.scheduled?.length) ctx.print(C.dim("  Undo one: sprid queue cancel <publishId>"));
+  return res?.errors?.length ? 1 : 0;
+}
+
+async function publish(ctx, base) {
+  if (!ctx.flags.yes) {
+    const where = base.platforms?.join(", ") ?? "every destination the post is for";
+    const msg = "Publishing is public and cannot be undone. Re-run with --yes to publish without the prompt.";
+    if (ctx.json || !ctx.stdin?.isTTY) {
+      if (ctx.json) ctx.out({ ok: false, error: msg, post: base.id, platforms: base.platforms ?? null });
+      else {
+        ctx.print(`  Will publish post ${base.id} to ${where} now.`);
+        ctx.warn(`  ✗ ${msg}`);
+      }
+      return 2;
+    }
+    ctx.print(`  Will publish post ${base.id} to ${where} now.\n`);
+    if (!(await confirm(ctx, "  Publish it? [y/N] "))) {
+      ctx.print("  Not published.");
+      return 1;
+    }
+  }
+  const res = await callTool(ctx, "publish_post", base);
+  if (ctx.json) ctx.out(res);
+  else {
+    show(ctx, res);
+    ctx.print(C.dim(`  Receipts: sprid post deliveries ${base.id}`));
+  }
+  return 0;
+}
+
+async function scheduleBatch(ctx) {
+  const usage = "sprid post schedule-batch --account <slug> --ids 1,2,3 [--cadence daily|every-other-day|weekdays] [--times 09:00,18:00] [--start YYYY-MM-DD] [--platforms a,b] [--skip-busy] [--dry-run]";
+  const ids = listFlag(ctx.flags.ids);
+  if (typeof ctx.flags.account !== "string" || !ids) throw new UsageError(usage);
+  const args = {
+    account: ctx.flags.account,
+    postIds: ids.map((v) => (/^\d+$/.test(v) ? Number(v) : v.toUpperCase())),
+    ...(await destination(ctx)),
+    ...(typeof ctx.flags.cadence === "string" ? { cadence: ctx.flags.cadence } : {}),
+    ...(listFlag(ctx.flags.times) ? { times: listFlag(ctx.flags.times) } : {}),
+    ...(typeof ctx.flags.start === "string" ? { startDayIso: ctx.flags.start } : {}),
+    ...(ctx.flags["skip-busy"] ? { skipBusyDays: true } : {}),
+    ...(ctx.flags["dry-run"] ? { dryRun: true } : {}),
+  };
+  show(ctx, await callTool(ctx, "schedule_batch", args));
+  return 0;
+}

package/src/commands/status.mjs

@@ -194,7 +194,15 @@ export async function queue(ctx) {
     else ctx.print(`  ${C.ok(OK)} Publish ${id} is back on the queue${row?.scheduledFor ? ` for ${dayTime(row.scheduledFor)}` : ""}.`);
     return 0;
   }
-  if (sub) throw usage("sprid queue [retry <publishId>]");
+  if (sub === "cancel") {
+    const id = Number(arg);
+    if (!Number.isInteger(id) || id <= 0) throw usage("sprid queue cancel <publishId>");
+    await ctx.api().del(`/api/publishes/${id}`);
+    if (ctx.json) ctx.out({ ok: true, publishId: id });
+    else ctx.print(`  ${C.ok(OK)} Booking ${id} cancelled. The post stays as it is.`);
+    return 0;
+  }
+  if (sub) throw usage("sprid queue [retry|cancel <publishId>]");
   const view = await fetchStatus(ctx);
   const q = view.queue ?? {};
   if (ctx.json) {

package/src/commands/tool.mjs

@@ -0,0 +1,59 @@
+// sprid tool: every server tool from the terminal, for the ones no named
+// command covers yet. Same handler, scopes and gates as an MCP client's call.
+
+import { UsageError } from "../args.mjs";
+import { C } from "../format.mjs";
+import { callTool, listTools, show, toolArgs } from "../tools.mjs";
+
+const USAGE = "sprid tool list [--search <words>] | describe <name> | call <name> [--file args.json] [--args '<json>']";
+
+export async function tool(ctx) {
+  const [sub, name] = ctx.positionals;
+  if (sub === "list" || !sub) return list(ctx);
+  if (sub === "describe" && name) return describe(ctx, name);
+  if (sub === "call" && name) {
+    show(ctx, await callTool(ctx, name, await toolArgs(ctx)));
+    return 0;
+  }
+  throw new UsageError(USAGE);
+}
+
+async function list(ctx) {
+  const words = typeof ctx.flags.search === "string" ? ctx.flags.search.toLowerCase().split(/\s+/).filter(Boolean) : [];
+  const tools = (await listTools(ctx)).filter((t) => {
+    const hay = `${t.name} ${t.description ?? ""}`.toLowerCase();
+    return words.every((w) => hay.includes(w));
+  });
+  if (ctx.json) {
+    ctx.out({ tools: tools.map(({ name, description }) => ({ name, description })) });
+    return 0;
+  }
+  if (tools.length === 0) {
+    ctx.print("  No tool matches.");
+    return 0;
+  }
+  const width = Math.max(...tools.map((t) => t.name.length));
+  for (const t of tools) ctx.print(`  ${t.name.padEnd(width)}  ${C.dim(firstSentence(t.description))}`);
+  ctx.print(C.dim(`\n  ${tools.length} tools. Run one: sprid tool call <name> --file args.json`));
+  return 0;
+}
+
+async function describe(ctx, name) {
+  const hit = (await listTools(ctx)).find((t) => t.name === name);
+  if (!hit) throw new UsageError(`No tool "${name}" for this token. List them: sprid tool list --search <words>`);
+  if (ctx.json) {
+    ctx.out(hit);
+    return 0;
+  }
+  ctx.print(`  ${hit.name}\n`);
+  ctx.print(`  ${hit.description ?? ""}\n`);
+  ctx.print(JSON.stringify(hit.inputSchema ?? {}, null, 2));
+  return 0;
+}
+
+function firstSentence(text = "") {
+  const s = String(text).replace(/\s+/g, " ").trim();
+  const cut = s.search(/\.\s/);
+  const one = cut > 0 ? s.slice(0, cut + 1) : s;
+  return one.length > 110 ? one.slice(0, 109) + "…" : one;
+}

package/src/docs/commands.mjs

@@ -38,6 +38,7 @@ export const COMMAND_GROUPS = [
   { title: 'Installation and updates', entries: [
     ['doctor', 'sprid doctor [--json] [--offline] [--apply-updates]', 'Check the running CLI against the npm latest release. --apply-updates is a between-jobs boundary and installs compatible updates only after explicit opt-in.'],
     ['update', 'sprid update [--check] [--yes]', 'Update the running installation and verify its new version. --check only reports; potentially breaking releases require --yes. Project installs use their own package manager and lockfile.'],
+    ['telemetry', 'sprid telemetry [status|on|off]', 'Show or change usage telemetry. When on, each command sends its name, exit code, duration and versions to your Sprid account, never arguments or file contents. DO_NOT_TRACK=1 or SPRID_TELEMETRY=0 turns it off for one shell.'],
     ['update', 'sprid update --auto on|off', 'Opt this installation into or out of compatible updates at job boundaries. Default off. Agents must have user approval before enabling.'],
   ] },
   { title: 'Store assets and releases', entries: [
@@ -68,6 +69,10 @@ export const COMMAND_GROUPS = [
     ['connect', 'sprid connect <service> --app <slug> --key <file> …', 'Save a store or analytics key. Read sprid docs <service> for the required fields.'],
     ['connect', 'sprid connect <service> --app <slug> --key-from-clipboard …', 'Save a key you just copied from the provider. It is read from the clipboard, never printed or written to disk, and the clipboard is cleared after saving. Not for services whose key is a downloaded file.'],
     ['connect', 'sprid connect <platform> --account <slug>', 'Connect a publishing account through the platform’s sign-in page.'],
+    ['connect', 'sprid connect meta-ads --account <slug> [--page <id>] [--ad-account <id>] [--dataset <id>]', 'Connect the Meta ad account Sprid runs campaigns in. When the Facebook profile manages several Pages or ad accounts, Sprid lists their ids; run it again with --page and --ad-account. --dataset is the Events Manager dataset id conversion campaigns report to.'],
+    ['connect', 'sprid connect google-ads --account <slug> [--ad-account <customer id>]', 'Connect the Google Ads account that promotes YouTube videos. When the Google login reaches several accounts, Sprid lists their ids; run it again with --ad-account.'],
+    ['connect', 'sprid connect tiktok-ads --account <slug> [--ad-account <advertiser id>]', 'Connect the TikTok ad account that promotes TikTok posts as Spark Ads. When the login reaches several advertisers, Sprid lists their ids; run it again with --ad-account.'],
+    ['connect', 'sprid connect tiktok-comments --account <slug>', 'Let the Inbox read and answer comments on your TikTok posts. Sign in with the TikTok account that publishes them; this is separate from TikTok publishing and from TikTok Ads.'],
     ['connect', 'sprid connect ga4|plausible|umami --app <slug> --key <file> … [--use]', 'PostHog, Google Analytics, Plausible and Umami all count the same website visits, so Sprid reads one of them and never adds them together. --use makes this one the source the traffic card reports from.'],
     ['pinterest', 'sprid pinterest boards --account <slug> [--channel <id>] [--bookmark <token>]', 'List boards and sections for the exact connected Pinterest channel; a returned bookmark reads the next page.'],
     ['pinterest', 'sprid pinterest create --account <slug> --name <name> [--description <text>] [--privacy public|secret]', 'Create a board in the exact connected Pinterest account. Older connections must reconnect once to grant board creation permission.'],
@@ -92,10 +97,27 @@ export const COMMAND_GROUPS = [
     ['marketing-review', 'sprid marketing-review query --app <slug> --query-file <query.sql>', 'Run a read-only PostHog query through the app’s stored connection.'],
     ['queue', 'sprid queue', 'Show what is scheduled and what failed.'],
     ['queue', 'sprid queue retry <publishId>', 'Retry a failed or missed publish.'],
+    ['queue', 'sprid queue cancel <publishId>', 'Cancel a booking. The post itself is unchanged and can be scheduled again.'],
+    ['post', 'sprid post schedule <postId> (--at ISO|--next|--queue-end) [--platforms a,b] [--time HH:MM] [--shift-later] [--options <options.json>]', 'Book a post: at a time, the next free slot, or after everything already booked. --shift-later moves later bookings down a slot. TikTok needs its privacy and interaction answers under "tiktok" in --options every time.'],
+    ['post', 'sprid post schedule-batch --account <slug> --ids 1,2,3 [--cadence daily|every-other-day|weekdays] [--times 09:00] [--start YYYY-MM-DD] [--platforms a,b] [--skip-busy] [--dry-run]', 'Place a list of posts on a cadence in one call. --dry-run returns the plan without booking anything.'],
+    ['post', 'sprid post publish <postId> [--platforms a,b] [--options <options.json>] [--yes]', 'Publish now. Public and not reversible, so it asks unless --yes. Read the receipts with sprid post deliveries.'],
+    ['inbox', 'sprid inbox [--view needs_you|all|done] [--kind all|comment|review] [--accounts a,b] [--app <slug>] [--intent <intent>] [--limit N]', 'Comments on posts and ads plus store reviews, as one ranked queue.'],
+    ['inbox', 'sprid inbox draft <commentId> [--count N]', 'Draft replies in the account’s reply voice. Nothing is sent.'],
+    ['inbox', 'sprid inbox reply <commentId> --text "…" [--yes]', 'Send a public reply to a comment. Asks unless --yes. Store reviews are answered with sprid reviews reply.'],
+    ['inbox', 'sprid inbox done|flag|reopen <c:id|r:id>', 'File an item without replying, mark a comment urgent, or put an item back in Needs you. Nothing is sent to the platform.'],
     ['reviews', 'sprid reviews [--app <slug>] [--unanswered] [--max-rating N] [--limit N]', 'Read store reviews.'],
     ['reviews', 'sprid reviews draft <id>', 'Draft a reply using the workspace’s model key. Nothing is sent.'],
     ['reviews', 'sprid reviews reply <id> [--text "…"] [--yes]', 'Review and send a public reply. --yes skips the confirmation.'],
   ] },
+  { title: 'Paid ads', entries: [
+    ['ads', 'sprid ads [overview] --account <slug>', 'Spend against the cap, what is live and what the connected Meta Ads channel can do.'],
+    ['ads', 'sprid ads status|council|metrics <adSetId> --account <slug> [--days N]', 'Delivery and rejections from Meta, the weekly judgement, or the numbers for one ad set.'],
+    ['ads', 'sprid ads create campaign|set|creative|ad|batch --file <args.json> --account <slug>', 'Create paused objects. The file holds the tool’s arguments; sprid tool describe create_ad_set shows them.'],
+    ['ads', 'sprid ads launch <adSetId> --account <slug> [--yes]', 'Show what launching commits, then start spending. Needs a token holding ads:spend.'],
+    ['ads', 'sprid ads budget <adSetId> --daily-cents N --account <slug> [--yes]', 'Change a daily budget, checked against the account’s caps. Needs ads:spend.'],
+    ['ads', 'sprid ads pause <adSetId> --account <slug> [--yes]', 'Pause an ad set. Resuming restarts Meta’s learning phase.'],
+    ['ads', 'sprid ads close <adSetId> --account <slug>', 'End an ad set and write its post-mortem.'],
+  ] },
   { title: 'Build your own media', entries: [
     ['post', 'sprid post init [--kind text|composed|stills|own]', 'Choose how this repo builds posts.'],
     ['post', 'sprid post new <slug> [--lane <name>]', 'Create a post specification.'],
@@ -115,6 +137,11 @@ export const COMMAND_GROUPS = [
     ['invite', 'sprid invite <email> [--role editor|admin] [--account <slug>]', 'Invite a collaborator.'],
     ['upgrade', 'sprid upgrade [pulse|push|founding]', 'Open checkout for a plan.'],
     ['mcp', 'sprid mcp [--surface core|all]', 'Connect an MCP client through the CLI’s saved login.'],
+    ['events', 'sprid events [list] [--days N]', 'The milestones Insights draws on its graphs.'],
+    ['events', 'sprid events add --kind release|listing|screenshots|submission|note --label "…" [--app <slug>] [--areas social,store,search,revenue,product,ads] [--why "…"] [--at ISO]', 'Log a change with the graphs it can explain and why, so the next read of those graphs can be explained.'],
+    ['tool', 'sprid tool list [--search <words>]', 'Every server tool this token can call, the same set an MCP client sees.'],
+    ['tool', 'sprid tool describe <name>', 'A tool’s description and input schema.'],
+    ['tool', 'sprid tool call <name> [--file args.json] [--args \'<json>\']', 'Run any tool with the same scopes and checks as an agent’s call. Prints the result as JSON.'],
     ['help', 'sprid help [<command> [<subcommand>]|environment|exit-codes] [--json]', 'Read focused help without authentication. JSON includes the installed command catalog.'],
     ['completion', 'sprid completion bash|zsh|fish', 'Print a shell completion script. Source it in your shell; Sprid never edits shell configuration.'],
   ] },
@@ -128,6 +155,7 @@ export const CLI_NOTES = [
   'Use -w/--workspace <slug|id> for one command, or sprid use to remember your choice.',
   'sprid login stores its token in ~/.sprid/credentials.json. SPRID_PAT overrides it.',
   'SPRID_URL overrides the API address. SPRID_APP_URL overrides the web app address.',
+  'Usage telemetry (command, exit code, duration, versions) goes to your Sprid account when signed in. sprid telemetry off, DO_NOT_TRACK=1 or SPRID_TELEMETRY=0 stops it.',
 ];
 
 export const COMMAND_EXAMPLES = {
@@ -138,6 +166,10 @@ export const COMMAND_EXAMPLES = {
   post: ['sprid post create --file draft.json', 'sprid post get 123 --json', 'sprid post preview --id 123', 'sprid post check launch --deep'],
   media: ['sprid media upload cover.jpg detail.jpg --account myapp', 'sprid media build launch'],
   'marketing-review': ['sprid marketing-review --app myapp --days 7 --json', 'sprid marketing-review capabilities --app myapp --source gsc --json'],
+  ads: ['sprid ads --account myapp', 'sprid ads launch 12 --account myapp'],
+  inbox: ['sprid inbox --view needs_you', 'sprid inbox reply 88 --text "Thanks, fixed in 1.4"'],
+  events: ['sprid events add --kind release --label "1.4" --areas store,product --why "New onboarding"'],
+  tool: ['sprid tool list --search schedule', 'sprid tool call post_queue --args \'{"id":123}\''],
   completion: ['source <(sprid completion bash)', 'source <(sprid completion zsh)', 'sprid completion fish | source'],
 };