rankcontrol 0.8.2 → 0.9.0

package/README.md

@@ -43,7 +43,7 @@ npx rankcontrol query-edit <queryId> "new text"
 npx rankcontrol query-track <queryId> off      # pause weekly checks (frees a slot)
 npx rankcontrol query-remove <queryId>
 npx rankcontrol competitors
-npx rankcontrol competitor-add "Acme" https://acme.com
+npx rankcontrol competitor-add "Acme"                 # site resolved from the name; pass a URL to override
 npx rankcontrol competitor-remove <competitorId>
 
 # Content pipeline
@@ -96,8 +96,8 @@ npx rankcontrol network-remove-placement <placementId> --confirm
 npx rankcontrol repurpose [contentId]  # published articles + social drafts (8 platforms)
 npx rankcontrol repurpose-generate <contentId> --platforms twitter --confirm
 npx rankcontrol repurpose-edit <draftId> --title "New hook"
-npx rankcontrol repurpose-channels     # Postiz channel ids
-npx rankcontrol repurpose-push <draftId> --channels <id> --confirm
+npx rankcontrol repurpose-channels     # Postiz and Buffer channel ids
+npx rankcontrol repurpose-push <draftId> --channels <id> --confirm            # --scheduler postiz|buffer when both are connected
 npx rankcontrol repurpose-mark-posted <draftId>
 npx rankcontrol social                 # Reddit/X threads where your articles fit
 npx rankcontrol social-stats

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "rankcontrol",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "RankControl CLI + MCP server: drive your SEO/AI-visibility workspace from the terminal or any AI agent",
   "license": "MIT",
+  "scripts": {
+    "prepublishOnly": "node ../../scripts/check-package-parity.mjs"
+  },
   "homepage": "https://rctrl.com",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -63,6 +63,11 @@ export function runCli(argv) {
     .description("Composite visibility score blending AI citation rate with Google and Bing rank share, with subscores")
     .action(() => api.visibilityScore().then(out).catch(fail));
 
+  program
+    .command("expedition")
+    .description("First-run setup progress: five acts with per-step completion and the current act")
+    .action(() => api.expedition().then(out).catch(fail));
+
   program
     .command("visibility")
     .description("Daily AI visibility score trend from the stored weekly citation checks")
@@ -228,9 +233,9 @@ export function runCli(argv) {
 
   program
     .command("competitor-add")
-    .description("Track a competitor (max 10)")
+    .description("Track a competitor (max 10); the site is resolved from the name when omitted")
     .argument("<name>", "Competitor name")
-    .argument("<websiteUrl>", "Competitor website URL")
+    .argument("[websiteUrl]", "Competitor website URL (optional)")
     .action((name, websiteUrl) =>
       api.addCompetitor(name, websiteUrl).then(out).catch(fail)
     );
@@ -487,11 +492,10 @@ export function runCli(argv) {
 
   program
     .command("reschedule <contentId> <date>")
-    .description("Move a planned article to a day (YYYY-MM-DD, local time; needs the flexible schedule)")
+    .description("Move a planned article to a day (YYYY-MM-DD in the workspace's timezone; needs the flexible schedule)")
     .action((contentId, date) => {
-      const day = new Date(`${date}T00:00:00`);
-      if (Number.isNaN(day.getTime())) return fail(new Error("Date must be YYYY-MM-DD"));
-      return api.reschedule(contentId, day.getTime()).then(out).catch(fail);
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return fail(new Error("Date must be YYYY-MM-DD"));
+      return api.reschedule(contentId, date).then(out).catch(fail);
     });
 
   program
@@ -567,20 +571,22 @@ export function runCli(argv) {
 
   program
     .command("repurpose-channels")
-    .description("Connected Postiz channels (ids needed for repurpose-push)")
+    .description("Connected Postiz and Buffer channels (ids needed for repurpose-push)")
     .action(() => api.repurposeChannels().then(out).catch(fail));
 
   program
     .command("repurpose-push <draftId>")
-    .description("Send a draft to Postiz (dry run unless --confirm)")
-    .option("--channels <id1,id2>", "Postiz channel ids (see repurpose-channels)")
-    .option("--when <now|schedule|draft>", "Postiz mode", "now")
+    .description("Send a draft to Postiz or Buffer (dry run unless --confirm)")
+    .option("--scheduler <postiz|buffer>", "Which scheduler (required when both are connected)")
+    .option("--channels <id1,id2>", "Channel ids (see repurpose-channels)")
+    .option("--when <now|schedule|draft|queue>", "Mode; queue is Buffer only", "now")
     .option("--date <iso>", "ISO time for --when schedule")
     .option("--confirm", "Actually push (publicly visible)")
     .action((draftId, opts) =>
       api
         .repurposePush({
           draftId,
+          scheduler: opts.scheduler,
           integrationIds: opts.channels ? list(opts.channels) : undefined,
           scheduleType: opts.when,
           date: opts.date,

package/src/client.mjs

@@ -103,6 +103,7 @@ export const api = {
     return request("GET", `/api/v1/citations${qs ? `?${qs}` : ""}`);
   },
   visibilityScore: () => request("GET", "/api/v1/visibility/score"),
+  expedition: () => request("GET", "/api/v1/expedition"),
   planningCapacity: () => request("GET", "/api/v1/content/planning-capacity"),
   jobs: (limit = 20) => request("GET", `/api/v1/jobs?limit=${limit}`),
   content: () => request("GET", "/api/v1/content"),
@@ -123,8 +124,8 @@ export const api = {
   articleSettings: () => request("GET", "/api/v1/settings/articles"),
   updateArticleSettings: (opts) =>
     request("POST", "/api/v1/settings/articles", opts),
-  reschedule: (contentId, targetDayStartMs) =>
-    request("POST", "/api/v1/content/reschedule", { contentId, targetDayStartMs }),
+  reschedule: (contentId, date) =>
+    request("POST", "/api/v1/content/reschedule", { contentId, date }),
   sitePages: () => request("GET", "/api/v1/links/pages"),
   detectSiteLinks: (source, url) =>
     request("POST", "/api/v1/links/detect", { source, url }),

package/src/login.mjs

@@ -13,13 +13,10 @@ const DEFAULT_SCOPES = [
   "read:content",
   "read:analytics",
   "write:content",
-  "write:queries",
   "write:backlinks",
   "write:social",
   "write:publish",
-  "manage:integrations",
   "manage:org",
-  "trigger:agents",
 ];
 
 function openBrowser(url) {

package/src/mcp.mjs

@@ -29,7 +29,7 @@ const plannedTitle = z.object({
 });
 
 export async function startMcpServer() {
-  const server = new McpServer({ name: "rankcontrol", version: "0.8.2" });
+  const server = new McpServer({ name: "rankcontrol", version: "0.9.0" });
 
   server.tool(
     "get_overview_funnel",
@@ -62,6 +62,13 @@ export async function startMcpServer() {
     run(() => api.visibilityScore())
   );
 
+  server.tool(
+    "get_setup_progress",
+    "First-run setup progress for the workspace: five acts from first article live through analytics, each with per-step completion, plus the current act. Use to tell the user what remains to finish setting up.",
+    {},
+    run(() => api.expedition())
+  );
+
   server.tool(
     "get_citability_report",
     "Published pages ranked by citability score (how extractable each page is for AI answers), worst first, each with its top open fixes. Use to decide which articles to improve.",
@@ -229,10 +236,13 @@ export async function startMcpServer() {
 
   server.tool(
     "add_competitor",
-    "Track a competitor (max 10). They enter weekly share-of-voice comparisons against the org's own citation rate.",
+    "Track a competitor (max 10). They enter weekly share-of-voice comparisons against the org's own citation rate. Omit websiteUrl to have the site resolved from the name.",
     {
       name: z.string().describe("Competitor name"),
-      websiteUrl: z.string().describe("Competitor website URL"),
+      websiteUrl: z
+        .string()
+        .optional()
+        .describe("Competitor website URL (optional; resolved from the name when omitted)"),
     },
     run(({ name, websiteUrl }) => api.addCompetitor(name, websiteUrl))
   );
@@ -432,14 +442,14 @@ export async function startMcpServer() {
 
   server.tool(
     "get_article_settings",
-    "The workspace article policy: per-article defaults (auto-write, auto-publish, images, title-in-hero, section infographics, Related Reading, YouTube, emojis, link counts, global instructions) plus the flexible-scheduling flag.",
+    "The workspace article policy: per-article defaults (auto-write, auto-publish, images, title-in-hero, section infographics, Related Reading, YouTube, emojis, link counts, global instructions) plus the flexible-scheduling flag. News and trending articles always publish manually, regardless of auto-publish.",
     {},
     run(() => api.articleSettings())
   );
 
   const articleSettingsShape = {
     autoPublish: z.boolean().optional(),
-    autoGenerate: z.boolean().optional().describe("Off = fully manual mode: articles are written only on demand (generate_article) and publish only from the editor"),
+    autoGenerate: z.boolean().optional().describe("Off = fully manual mode: articles are written only on demand (generate_article) and publish only from the editor. Turning it on needs a connected publishing destination."),
     includeInfographics: z.boolean().optional().describe("AI hero + section images"),
     titleInHeroImage: z.boolean().optional().describe("Write the post title into the hero image"),
     includeSectionInfographics: z.boolean().optional().describe("Informational panels in 2,000+ word articles"),
@@ -474,12 +484,12 @@ export async function startMcpServer() {
 
   server.tool(
     "reschedule_article",
-    "Move a PLANNED article to another day (requires the flexible schedule; max 5/day; the exact hour is placed automatically). Pass the target day as epoch ms of local midnight.",
+    "Move a PLANNED article to another day (requires the flexible schedule; max 5/day; the exact hour is placed automatically). Pass the target day as YYYY-MM-DD in the workspace's timezone.",
     {
       contentId: z.string(),
-      targetDayStartMs: z.number().describe("Epoch ms of the target day's local midnight"),
+      date: z.string().describe("Target day as YYYY-MM-DD in the workspace's timezone"),
     },
-    run(({ contentId, targetDayStartMs }) => api.reschedule(contentId, targetDayStartMs))
+    run(({ contentId, date }) => api.reschedule(contentId, date))
   );
 
   server.tool(
@@ -572,26 +582,30 @@ export async function startMcpServer() {
 
   server.tool(
     "list_postiz_channels",
-    "Connected Postiz social channels (id, name, platform). Channel ids are required by push_repurpose_draft.",
+    "Connected social channels across Postiz and Buffer (scheduler, id, name, platform). Channel ids are required by push_repurpose_draft.",
     {},
     run(() => api.repurposeChannels())
   );
 
   server.tool(
     "push_repurpose_draft",
-    "Send a repurpose draft to connected Postiz channels (post now, schedule, or save as a Postiz draft). PUBLICLY VISIBLE side effect: defaults to a DRY RUN; a human should approve before calling again with confirm=true.",
+    "Send a repurpose draft to a connected scheduler's channels: Postiz or Buffer (post now, schedule, save as a draft, or add to Buffer's queue). PUBLICLY VISIBLE side effect: defaults to a DRY RUN; a human should approve before calling again with confirm=true.",
     {
       draftId: z.string(),
+      scheduler: z
+        .enum(["postiz", "buffer"])
+        .optional()
+        .describe("Which scheduler; required when both are connected"),
       integrationIds: z
         .array(z.string())
         .optional()
         .describe(
-          "Postiz channel ids from list_postiz_channels (required with confirm)"
+          "Channel ids from list_postiz_channels (required with confirm)"
         ),
       scheduleType: z
-        .enum(["now", "schedule", "draft"])
+        .enum(["now", "schedule", "draft", "queue"])
         .optional()
-        .describe("Default now"),
+        .describe("Default now; queue is Buffer only"),
       date: z.string().optional().describe("ISO time for scheduleType=schedule"),
       confirm: z.boolean().optional(),
     },
@@ -655,13 +669,13 @@ export async function startMcpServer() {
 
   server.tool(
     "list_backlinks",
-    "The workspace's backlink table, newest first.",
+    "The workspace's backlink table, newest first. Each row carries its source (index, outreach, managed, network).",
     {
       status: z
         .string()
         .optional()
         .describe(
-          "Filter: discovered, verified, lost, identified, contacted, replied, link_placed, rejected"
+          "Filter: discovered, verified, lost, placed, identified, contacted, replied, link_placed, rejected"
         ),
     },
     run(({ status }) => api.backlinks(status))