@jclvsh/dropspace 2.8.0 → 2.10.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
 
@@ -135,7 +136,7 @@ Add to your `.cursor/mcp.json`:
 | `dropspace_platforms`         | string[]           | No       | Platforms to post via official dropspace accounts                                                                                                                                                       |
 | `media_mode`                  | string             | No       | `"images"` or `"video"`                                                                                                                                                                                 |
 | `user_platform_accounts`      | object             | No       | Map of platform key to token_id (UUID). Simple keys: `twitter`, `reddit`, `instagram`, `tiktok`. LinkedIn: `linkedin:personal` or `linkedin:organization:<org_id>`. Facebook: `facebook:page:<page_id>` |
-| `platform_contents`           | object             | No       | Per-platform content (mutually exclusive with `custom_content`)                                                                                                                                         |
+| `platform_contents`           | object             | No       | Per-platform content (mutually exclusive with `custom_content`). Reddit accepts `metadata.subreddits` (string[], max 10, no `r/` prefix — one post per subreddit, each retryable) and `metadata.first_comment` (max 1500) |
 | `custom_content`              | string \| string[] | No       | Single content for all platforms, or array of tweets for twitter thread mode (mutually exclusive with `platform_contents`)                                                                              |
 | `custom_content_reddit_title` | string             | No       | Reddit title (required with `custom_content` + reddit)                                                                                                                                                  |
 | `media`                       | object[]           | No       | Inline media, URL or base64 (1-10 items, mutually exclusive with `media_assets`)                                                                                                                        |
@@ -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/launches.js

@@ -31,7 +31,7 @@ export function registerLaunchCommands(program, client) {
         .option("--persona <id>", "persona ID for tone/style")
         .option("--dropspace-platforms <list>", "platforms for official dropspace accounts", parseList)
         .option("--media-mode <mode>", "media mode: images or video")
-        .option("--platform-contents <json>", "per-platform content as JSON string")
+        .option("--platform-contents <json>", 'per-platform content as JSON string. reddit supports metadata.subreddits (string[], max 10, no r/ prefix — one post per subreddit) and metadata.first_comment (max 1500). e.g. \'{"reddit":{"title":"...","content":"...","metadata":{"subreddits":["SideProject"],"first_comment":"..."}}}\'')
         .option("--custom-content <text>", "single content string for all platforms")
         .option("--reddit-title <title>", "reddit title (with custom-content)")
         .option("--user-accounts <json>", "platform-to-token_id map as JSON string")
@@ -98,7 +98,7 @@ export function registerLaunchCommands(program, client) {
         .option("--schedule <datetime>", "ISO 8601 schedule datetime (empty to clear)")
         .option("--status <status>", "status: draft, manual, trigger, scheduled, cancelled")
         .option("--persona <id>", "persona ID (empty to clear)")
-        .option("--platform-contents <json>", "per-platform content as JSON string")
+        .option("--platform-contents <json>", 'per-platform content as JSON string. reddit supports metadata.subreddits (string[], max 10, no r/ prefix — one post per subreddit) and metadata.first_comment (max 1500). e.g. \'{"reddit":{"title":"...","content":"...","metadata":{"subreddits":["SideProject"],"first_comment":"..."}}}\'')
         .option("--dropspace-platforms <list>", "official dropspace account platforms", parseList)
         .option("--user-accounts <json>", "platform-to-token_id map as JSON string")
         .option("--media-mode <mode>", "media mode: images or video")

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/launches.js

@@ -102,7 +102,7 @@ export function registerLaunchTools(server, client) {
         platform_contents: z
             .record(z.string(), z.record(z.string(), z.unknown()))
             .optional()
-            .describe('per-platform content — each value needs "content" (string). Reddit also requires "title" (max 300). Twitter supports "thread" (string[], max 6, each ≤280 or ≤25,000 for X Premium) instead of "content". TikTok supports "tiktok_settings": { "publish_mode"?: "direct"|"draft" (default "direct"; "draft" uploads to the TikTok inbox to finish and publish in-app), "privacy_level": "PUBLIC_TO_EVERYONE"|"FOLLOWER_OF_CREATOR"|"MUTUAL_FOLLOW_FRIENDS"|"SELF_ONLY" (required before publish in direct mode; not required for draft), "allow_comments"?, "allow_duet"?, "allow_stitch"?, "is_commercial"?, "is_your_brand"?, "is_branded_content"?, "auto_add_music"? (booleans, direct mode) }. YouTube requires video and supports "title" (max 100 chars). character limits: Twitter 280/tweet (25,000 for X Premium), LinkedIn 3000, Instagram 2200, Reddit 3000, Facebook 3000, TikTok 4000, YouTube 5000 (description). X Premium status is auto-detected from the connected account. mutually exclusive with custom_content'),
+            .describe('per-platform content — each value needs "content" (string). Reddit also requires "title" (max 300) and supports "metadata": { "subreddits": string[] (max 10, names without the r/ prefix — posts the launch once per subreddit, each tracked and retryable on its own; omit to post to the default community), "first_comment": string (max 1500 — posted as a comment under each reddit post once it goes live) }. each subreddit has its own rules: many restrict or ban promotional posts and posting where the account has no history gets filtered, so target a few genuinely relevant subreddits rather than blasting. Twitter supports "thread" (string[], max 6, each ≤280 or ≤25,000 for X Premium) instead of "content". TikTok supports "tiktok_settings": { "publish_mode"?: "direct"|"draft" (default "direct"; "draft" uploads to the TikTok inbox to finish and publish in-app), "privacy_level": "PUBLIC_TO_EVERYONE"|"FOLLOWER_OF_CREATOR"|"MUTUAL_FOLLOW_FRIENDS"|"SELF_ONLY" (required before publish in direct mode; not required for draft), "allow_comments"?, "allow_duet"?, "allow_stitch"?, "is_commercial"?, "is_your_brand"?, "is_branded_content"?, "auto_add_music"? (booleans, direct mode) }. YouTube requires video and supports "title" (max 100 chars). character limits: Twitter 280/tweet (25,000 for X Premium), LinkedIn 3000, Instagram 2200, Reddit 3000, Facebook 3000, TikTok 4000, YouTube 5000 (description). X Premium status is auto-detected from the connected account. mutually exclusive with custom_content'),
         custom_content: z
             .union([z.string().min(1), z.array(z.string()).min(1).max(6)])
             .optional()
@@ -216,7 +216,7 @@ export function registerLaunchTools(server, client) {
         platform_contents: z
             .record(z.string(), z.record(z.string(), z.unknown()))
             .optional()
-            .describe('per-platform content update (deep-merged with existing). each value can include "content" (string). Twitter supports "thread" (string[]) instead. Reddit "title" is optional on update. TikTok "tiktok_settings" is deep-merged — you can update individual fields (e.g. just "privacy_level") without overwriting the rest. see create_launch for full field details'),
+            .describe('per-platform content update (deep-merged with existing). each value can include "content" (string). Twitter supports "thread" (string[]) instead. Reddit "title" is optional on update, and "metadata" accepts "subreddits" (string[], max 10, no r/ prefix — one post per subreddit) and "first_comment" (string, max 1500). TikTok "tiktok_settings" is deep-merged — you can update individual fields (e.g. just "privacy_level") without overwriting the rest. see create_launch for full field details'),
         dropspace_platforms: z.array(z.enum(PLATFORMS)).optional().describe("official dropspace account platforms"),
         user_platform_accounts: z
             .record(z.string(), z.string())

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.10.0",
 	"description": "MCP server and CLI for the Dropspace API",
 	"type": "module",
 	"main": "dist/index.js",