@jclvsh/dropspace 2.8.0 → 2.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @jclvsh/dropspace
 
-MCP server and CLI for the [Dropspace](https://www.dropspace.dev) API. Lets AI agents (Claude Code, Cursor) and humans manage launches, personas, media generation, boosts, autopilot, platform connections, API keys, and webhooks. 54 tools across 12 categories.
+MCP server and CLI for the [Dropspace](https://www.dropspace.dev) API. Lets AI agents (Claude Code, Cursor) and humans manage launches, personas, media generation, boosts, autopilot, recommendations, platform connections, API keys, and webhooks. 59 tools across 13 categories.
 
 ## Installation
 
@@ -55,6 +55,7 @@ dropspace launches --help
 | status      | dropspace official account connections                                                                                                    | 1     |
 | usage       | plan, limits, and billing period                                                                                                          | 1     |
 | autopilot   | status, configure, review, approve, reject, run, runs                                                                                     | 7     |
+| recommendations (recs) | list, apply, dismiss                                                                                                           | 3     |
 
 ## MCP Server Configuration
 
@@ -176,6 +177,8 @@ Add to your `.cursor/mcp.json`:
 | `update_persona`  | Update a persona's name or writing samples       |
 | `delete_persona`  | Delete a persona                                 |
 | `analyze_persona` | Trigger AI analysis of a persona's writing style |
+| `finalize_persona` | Accept a completed analysis so the persona is usable |
+| `discard_persona_analysis` | Discard a pending analysis result |
 
 #### `analyze_persona` Parameters
 
@@ -310,6 +313,16 @@ Add to your `.cursor/mcp.json`:
 
 Autopilot is available on pro and premium plans.
 
+### Recommendations
+
+| Tool                     | Description                                                                                          |
+| ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `list_recommendations`   | List actionable insights from your organic post performance (winners, boost/promote/pause signals)    |
+| `apply_recommendation`   | Apply the one-click action: draft launch, PAUSED boost (needs `ad_account_id`), autopilot queue, directive |
+| `dismiss_recommendation` | Dismiss a pending recommendation                                                                      |
+
+Applying never publishes or spends by itself — drafts need scheduling and boosts need explicit activation.
+
 ## API Key & Scopes
 
 Generate an API key at [www.dropspace.dev/settings](https://www.dropspace.dev/settings) under the API section.

package/dist/cli-utils.d.ts

@@ -1,4 +1,58 @@
+/**
+ * Shared CLI + MCP output helpers.
+ *
+ * The CLI consumes these for terminal output (table / JSON / structured exit
+ * codes). MCP tools consume `formatMcpError` so error responses surface the
+ * structured `{success, error: {code, message}}` envelope to the LLM instead
+ * of a flattened message string — lets the model branch on `error.code`
+ * without regex-extracting the bracketed prefix.
+ */
 export declare function formatOutput(data: unknown, format?: string): void;
+/**
+ * Map a fleet error-code prefix to a CLI exit code.
+ *
+ * Convention so shell scripts can branch on failure type without parsing stderr:
+ * - 0: success (not handled here)
+ * - 1: generic / unknown
+ * - 2: input / validation (SERVER_VALIDATION_FAILED, SERVER_BAD_REQUEST)
+ * - 3: rate limit
+ * - 4: auth (AUTH_*, APIKEY_*)
+ * - 5: payment / billing (PAYMENT_*, BILLING_*)
+ * - 6: not found (any *_NOT_FOUND)
+ *
+ * Domain-specific codes (e.g. CAMP_001, LAUNCH_001) are categorized by their
+ * suffix shape — *_NOT_FOUND maps to 6, others fall through to 1.
+ */
+export declare function exitCodeForMessage(message: string): number;
 export declare function handleError(error: unknown): never;
+/**
+ * Parse the `[CODE] message (field: x)` string format that the API client's
+ * handleError builds, recovering the structured fields.
+ *
+ * Returns `{code, message, field?}`. Falls back to `{code: "UNKNOWN_ERROR", message}`
+ * when no bracketed code is present (shouldn't happen for API errors, but safe
+ * for client-side throws like network timeouts).
+ */
+export declare function parseErrorMessage(raw: string): {
+    code: string;
+    message: string;
+    field?: string;
+};
+/**
+ * Format an error caught in an MCP tool handler as the structured response
+ * the MCP SDK returns to the model.
+ *
+ * Returns the canonical v1 error envelope `{success: false, error: {code, message, field?}}`
+ * as JSON text inside the MCP `content` block, plus `isError: true` so the SDK
+ * surfaces it as an error to the model. Lets the LLM read `error.code`
+ * structurally instead of regexing it out of a flattened message.
+ */
+export declare function formatMcpError(error: unknown): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};
 export declare function getFormat(opts: Record<string, unknown>): string;
 export declare function parseList(value: string): string[];

package/dist/cli-utils.js

@@ -1,3 +1,12 @@
+/**
+ * Shared CLI + MCP output helpers.
+ *
+ * The CLI consumes these for terminal output (table / JSON / structured exit
+ * codes). MCP tools consume `formatMcpError` so error responses surface the
+ * structured `{success, error: {code, message}}` envelope to the LLM instead
+ * of a flattened message string — lets the model branch on `error.code`
+ * without regex-extracting the bracketed prefix.
+ */
 export function formatOutput(data, format = "json") {
     if (format === "table" && typeof data === "object" && data !== null) {
         const obj = data;
@@ -16,10 +25,94 @@ export function formatOutput(data, format = "json") {
     }
     console.log(JSON.stringify(data, null, 2));
 }
+/**
+ * Map a fleet error-code prefix to a CLI exit code.
+ *
+ * Convention so shell scripts can branch on failure type without parsing stderr:
+ * - 0: success (not handled here)
+ * - 1: generic / unknown
+ * - 2: input / validation (SERVER_VALIDATION_FAILED, SERVER_BAD_REQUEST)
+ * - 3: rate limit
+ * - 4: auth (AUTH_*, APIKEY_*)
+ * - 5: payment / billing (PAYMENT_*, BILLING_*)
+ * - 6: not found (any *_NOT_FOUND)
+ *
+ * Domain-specific codes (e.g. CAMP_001, LAUNCH_001) are categorized by their
+ * suffix shape — *_NOT_FOUND maps to 6, others fall through to 1.
+ */
+export function exitCodeForMessage(message) {
+    const codeMatch = message.match(/\[([A-Z]+)_(\d+|[A-Z_]+)\]/);
+    if (!codeMatch)
+        return 1;
+    const prefix = codeMatch[1];
+    const suffix = codeMatch[2];
+    // Suffix-based: *_NOT_FOUND → 6 regardless of prefix
+    if (suffix.includes("NOT_FOUND"))
+        return 6;
+    switch (prefix) {
+        case "AUTH":
+        case "APIKEY":
+            return 4;
+        case "RATE":
+            return 3;
+        case "PAYMENT":
+        case "BILLING":
+            return 5;
+        case "SERVER":
+            // SERVER_002/005 = validation; SERVER_003 = not found; rest = generic
+            if (suffix === "002" || suffix === "005")
+                return 2;
+            if (suffix === "003")
+                return 6;
+            return 1;
+        default:
+            return 1;
+    }
+}
 export function handleError(error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`error: ${message}`);
-    process.exit(1);
+    process.exit(exitCodeForMessage(message));
+}
+/**
+ * Parse the `[CODE] message (field: x)` string format that the API client's
+ * handleError builds, recovering the structured fields.
+ *
+ * Returns `{code, message, field?}`. Falls back to `{code: "UNKNOWN_ERROR", message}`
+ * when no bracketed code is present (shouldn't happen for API errors, but safe
+ * for client-side throws like network timeouts).
+ */
+export function parseErrorMessage(raw) {
+    // Format: "[CODE] message (field: x)" — code optional, field optional
+    const match = raw.match(/^\[([A-Z_0-9]+)\]\s+(.*?)(?:\s+\(field:\s+([^)]+)\))?$/);
+    if (!match)
+        return { code: "UNKNOWN_ERROR", message: raw };
+    return {
+        code: match[1],
+        message: match[2],
+        ...(match[3] && { field: match[3] }),
+    };
+}
+/**
+ * Format an error caught in an MCP tool handler as the structured response
+ * the MCP SDK returns to the model.
+ *
+ * Returns the canonical v1 error envelope `{success: false, error: {code, message, field?}}`
+ * as JSON text inside the MCP `content` block, plus `isError: true` so the SDK
+ * surfaces it as an error to the model. Lets the LLM read `error.code`
+ * structurally instead of regexing it out of a flattened message.
+ */
+export function formatMcpError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const parsed = parseErrorMessage(raw);
+    const envelope = {
+        success: false,
+        error: parsed,
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+        isError: true,
+    };
 }
 export function getFormat(opts) {
     if (opts.json)

package/dist/cli.js

@@ -15,6 +15,7 @@ import { registerCreditCommands } from "./commands/credits.js";
 import { registerMediaCommands } from "./commands/media.js";
 import { registerBoostCommands } from "./commands/boosts.js";
 import { registerAutopilotCommands } from "./commands/autopilot.js";
+import { registerRecommendationCommands } from "./commands/recommendations.js";
 const program = new Command()
     .name("dropspace")
     .description("dropspace CLI - manage launches, personas, boosts, and more")
@@ -34,6 +35,7 @@ try {
     registerMediaCommands(program, client);
     registerBoostCommands(program, client);
     registerAutopilotCommands(program, client);
+    registerRecommendationCommands(program, client);
     await program.parseAsync(process.argv);
 }
 catch (error) {

package/dist/commands/recommendations.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { DropspaceClient } from "../client.js";
+export declare function registerRecommendationCommands(program: Command, client: DropspaceClient): void;

package/dist/commands/recommendations.js

@@ -0,0 +1,60 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerRecommendationCommands(program, client) {
+    const recommendations = program
+        .command("recommendations")
+        .alias("recs")
+        .description("actionable insights from your organic post performance");
+    recommendations
+        .command("list")
+        .description("list recommendations")
+        .option("--status <status>", "filter: pending, applied, dismissed, expired")
+        .option("--launch <id>", "only recommendations for this launch")
+        .option("-p, --page <n>", "page number", "1")
+        .option("-s, --page-size <n>", "items per page (max 100)", "20")
+        .action(async (opts) => {
+        try {
+            const params = {};
+            if (opts.status)
+                params.status = opts.status;
+            if (opts.launch)
+                params.launch_id = opts.launch;
+            if (opts.page)
+                params.page = opts.page;
+            if (opts.pageSize)
+                params.page_size = opts.pageSize;
+            const result = await client.get("/recommendations", params);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    recommendations
+        .command("apply <id>")
+        .description("apply a recommendation (repost/cross-post create a DRAFT launch; boost creates a PAUSED boost; promote queues into autopilot; pause adds a directive)")
+        .option("--ad-account <id>", "meta ad account id (required for boost_winner)")
+        .action(async (id, opts) => {
+        try {
+            const body = {};
+            if (opts.adAccount)
+                body.ad_account_id = opts.adAccount;
+            const result = await client.post(`/recommendations/${id}/apply`, body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    recommendations
+        .command("dismiss <id>")
+        .description("dismiss a recommendation")
+        .action(async (id) => {
+        try {
+            const result = await client.post(`/recommendations/${id}/dismiss`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/index.js

@@ -13,9 +13,10 @@ import { registerCreditTools } from "./tools/credits.js";
 import { registerMediaTools } from "./tools/media.js";
 import { registerBoostTools } from "./tools/boosts.js";
 import { registerAutopilotTools } from "./tools/autopilot.js";
+import { registerRecommendationTools } from "./tools/recommendations.js";
 const server = new McpServer({
     name: "dropspace",
-    version: "2.8.0",
+    version: "2.9.0",
 });
 const client = new DropspaceClient();
 registerLaunchTools(server, client);
@@ -29,5 +30,6 @@ registerCreditTools(server, client);
 registerMediaTools(server, client);
 registerBoostTools(server, client);
 registerAutopilotTools(server, client);
+registerRecommendationTools(server, client);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/recommendations.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DropspaceClient } from "../client.js";
+export declare function registerRecommendationTools(server: McpServer, client: DropspaceClient): void;

package/dist/tools/recommendations.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+function ok(result) {
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+function err(error) {
+    return {
+        content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+        isError: true,
+    };
+}
+export function registerRecommendationTools(server, client) {
+    server.tool("list_recommendations", "list actionable recommendations computed from your organic post performance: winners to repost, cross-post, or boost, autopilot promote signals, and underperformer pause signals. dropspace sweeps post metrics every 30 minutes and compares each post to your own per-platform baseline.", {
+        status: z
+            .enum(["pending", "applied", "dismissed", "expired"])
+            .optional()
+            .describe("filter by status (default: all)"),
+        launch_id: z.string().optional().describe("only recommendations for this launch"),
+        page: z.number().int().positive().optional().describe("page number (default: 1)"),
+        page_size: z.number().int().min(1).max(100).optional().describe("items per page (default: 20, max: 100)"),
+    }, async ({ status, launch_id, page, page_size }) => {
+        try {
+            const params = {};
+            if (status !== undefined)
+                params.status = status;
+            if (launch_id !== undefined)
+                params.launch_id = launch_id;
+            if (page !== undefined)
+                params.page = String(page);
+            if (page_size !== undefined)
+                params.page_size = String(page_size);
+            return ok(await client.get("/recommendations", params));
+        }
+        catch (error) {
+            return err(error);
+        }
+    });
+    server.tool("apply_recommendation", "apply a recommendation's one-click action. repost_winner and cross_post create a DRAFT launch seeded with the winning content (nothing publishes until scheduled); boost_winner creates a PAUSED meta boost and requires ad_account_id (activation, and therefore spend, is a separate step); promote_winner queues the winner into autopilot; pause_underperformer adds a standing directive to the autopilot config.", {
+        recommendation_id: z.string().describe("the recommendation to apply"),
+        ad_account_id: z
+            .string()
+            .optional()
+            .describe("meta ad account id — required for boost_winner recommendations, ignored otherwise"),
+    }, async ({ recommendation_id, ad_account_id }) => {
+        try {
+            return ok(await client.post(`/recommendations/${recommendation_id}/apply`, ad_account_id ? { ad_account_id } : {}));
+        }
+        catch (error) {
+            return err(error);
+        }
+    });
+    server.tool("dismiss_recommendation", "dismiss a pending recommendation so it stops showing everywhere.", {
+        recommendation_id: z.string().describe("the recommendation to dismiss"),
+    }, async ({ recommendation_id }) => {
+        try {
+            return ok(await client.post(`/recommendations/${recommendation_id}/dismiss`));
+        }
+        catch (error) {
+            return err(error);
+        }
+    });
+}

package/dist/types.d.ts

@@ -392,3 +392,34 @@ export interface AutopilotRun {
     started_at: string;
     completed_at: string | null;
 }
+/** Actionable insight computed from organic post performance */
+export interface Recommendation {
+    id: string;
+    rec_type: "repost_winner" | "cross_post" | "boost_winner" | "promote_winner" | "pause_underperformer";
+    status: "pending" | "applied" | "dismissed" | "expired";
+    platform: string;
+    launch_id: string | null;
+    posting_log_id: string | null;
+    payload: unknown;
+    score: number | null;
+    baseline: number | null;
+    expires_at: string | null;
+    applied_launch_id: string | null;
+    applied_at: string | null;
+    dismissed_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** What applying a recommendation actually did */
+export interface RecommendationApplyOutcome {
+    kind: "launch_draft" | "boost_created" | "autopilot_queued" | "directive_added";
+    launch_id?: string;
+    boost_id?: string;
+    boost_status?: string;
+    dedupe_key?: string;
+    directive?: string;
+}
+export interface RecommendationApplyResponse {
+    recommendation: Recommendation;
+    outcome: RecommendationApplyOutcome;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/dropspace",
-	"version": "2.8.0",
+	"version": "2.9.0",
 	"description": "MCP server and CLI for the Dropspace API",
 	"type": "module",
 	"main": "dist/index.js",