@jclvsh/dropspace 2.3.1 → 2.6.0

package/dist/cli.js

@@ -13,9 +13,10 @@ import { registerDropspaceCommands } from "./commands/dropspace.js";
 import { registerUsageCommands } from "./commands/usage.js";
 import { registerCreditCommands } from "./commands/credits.js";
 import { registerMediaCommands } from "./commands/media.js";
+import { registerBoostCommands } from "./commands/boosts.js";
 const program = new Command()
     .name("dropspace")
-    .description("dropspace CLI - manage launches, personas, and more")
+    .description("dropspace CLI - manage launches, personas, boosts, and more")
     .version(pkg.version)
     .option("--json", "output as JSON (default)")
     .option("--format <fmt>", "output format: json, table", "json");
@@ -30,6 +31,7 @@ try {
     registerUsageCommands(program, client);
     registerCreditCommands(program, client);
     registerMediaCommands(program, client);
+    registerBoostCommands(program, client);
     await program.parseAsync(process.argv);
 }
 catch (error) {

package/dist/commands/boosts.d.ts

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

package/dist/commands/boosts.js

@@ -0,0 +1,90 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerBoostCommands(program, client) {
+    const boosts = program.command("boosts").alias("b").description("manage paid boosts on meta");
+    boosts
+        .command("create")
+        .description("create a paid boost on meta for an organic facebook or instagram launch (starts PAUSED)")
+        .requiredOption("-l, --launch-id <id>", "launch id with a successful facebook OR instagram post")
+        .requiredOption("-b, --daily-budget-cents <n>", "daily budget in cents (100 - 10000 = $1 - $100)")
+        .requiredOption("-d, --duration-days <n>", "campaign duration in days (1 - 7)")
+        .option("--platform <platform>", "ad platform: facebook | instagram", "facebook")
+        .option("--objective <objective>", "campaign objective (phase 1: engagement)", "engagement")
+        .option("--ad-account-id <id>", "explicit meta ad account id (e.g. 'act_123'); defaults to the first active one")
+        .action(async (opts) => {
+        try {
+            const body = {
+                platform: opts.platform ?? "facebook",
+                daily_budget_cents: parseInt(opts.dailyBudgetCents, 10),
+                duration_days: parseInt(opts.durationDays, 10),
+                objective: opts.objective ?? "engagement",
+            };
+            if (opts.adAccountId)
+                body.ad_account_id = opts.adAccountId;
+            const result = await client.post(`/launches/${opts.launchId}/boost`, body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    boosts
+        .command("list <launch-id>")
+        .description("list all boosts attached to a specific launch")
+        .action(async (launchId) => {
+        try {
+            const result = await client.get(`/launches/${launchId}/boost`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    boosts
+        .command("get <launch-id> <boost-id>")
+        .description("get a boost by id with current performance metrics")
+        .action(async (launchId, boostId) => {
+        try {
+            const result = await client.get(`/launches/${launchId}/boost/${boostId}`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    boosts
+        .command("activate <launch-id> <boost-id>")
+        .description("flip a PAUSED boost to ACTIVE on meta — ad spend starts immediately")
+        .action(async (launchId, boostId) => {
+        try {
+            const result = await client.post(`/launches/${launchId}/boost/${boostId}/activate`, {});
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    boosts
+        .command("cancel <launch-id> <boost-id>")
+        .description("cancel a boost — deletes the campaign on meta and soft-deletes the record")
+        .action(async (launchId, boostId) => {
+        try {
+            await client.delete(`/launches/${launchId}/boost/${boostId}`);
+            formatOutput({ success: true, boost_id: boostId }, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    boosts
+        .command("performance <launch-id> <boost-id>")
+        .description("fetch latest performance metrics (impressions, clicks, reach, spend)")
+        .action(async (launchId, boostId) => {
+        try {
+            const result = await client.get(`/launches/${launchId}/boost/${boostId}`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/index.js

@@ -11,9 +11,10 @@ import { registerDropspaceTools } from "./tools/dropspace.js";
 import { registerUsageTools } from "./tools/usage.js";
 import { registerCreditTools } from "./tools/credits.js";
 import { registerMediaTools } from "./tools/media.js";
+import { registerBoostTools } from "./tools/boosts.js";
 const server = new McpServer({
     name: "dropspace",
-    version: "2.2.0",
+    version: "2.5.0",
 });
 const client = new DropspaceClient();
 registerLaunchTools(server, client);
@@ -25,5 +26,6 @@ registerDropspaceTools(server, client);
 registerUsageTools(server, client);
 registerCreditTools(server, client);
 registerMediaTools(server, client);
+registerBoostTools(server, client);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/boosts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Launch boost MCP tools — paid amplification of organic Facebook launches.
+ *
+ * Phase 1: facebook only, engagement objective, auto-targeting. API key auth.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DropspaceClient } from "../client.js";
+export declare function registerBoostTools(server: McpServer, client: DropspaceClient): void;

package/dist/tools/boosts.js

@@ -0,0 +1,105 @@
+/**
+ * Launch boost MCP tools — paid amplification of organic Facebook launches.
+ *
+ * Phase 1: facebook only, engagement objective, auto-targeting. API key auth.
+ */
+import { z } from "zod";
+const platformSchema = z.enum(["facebook", "instagram"]).describe("ad platform — facebook or instagram (IG boost requires the IG business account linked to one of the user's facebook pages)");
+const objectiveSchema = z.literal("engagement").describe("campaign objective (phase 1: engagement only)");
+const launchIdParam = z.string().uuid().describe("launch ID to boost — must have a successful facebook post");
+const boostIdParam = z.string().uuid().describe("boost ID");
+export function registerBoostTools(server, client) {
+    server.tool("create_boost", "create a paid boost on meta for an organic facebook or instagram launch. boost starts PAUSED — call activate_boost to start ad spend.", {
+        launch_id: launchIdParam,
+        daily_budget_cents: z
+            .number()
+            .int()
+            .min(100)
+            .max(10000)
+            .describe("daily ad budget in cents ($1 - $100). billed by meta to the user's ad account."),
+        duration_days: z.number().int().min(1).max(7).describe("how many days the boost runs (1-7)"),
+        platform: platformSchema.optional(),
+        objective: objectiveSchema.optional(),
+        ad_account_id: z
+            .string()
+            .optional()
+            .describe("explicit meta ad account id (e.g. 'act_123'). defaults to the first active ad account."),
+    }, async (args) => {
+        try {
+            const result = await client.post(`/launches/${args.launch_id}/boost`, {
+                platform: args.platform ?? "facebook",
+                daily_budget_cents: args.daily_budget_cents,
+                duration_days: args.duration_days,
+                objective: args.objective ?? "engagement",
+                ...(args.ad_account_id ? { ad_account_id: args.ad_account_id } : {}),
+            });
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("list_boosts", "list all boosts attached to a specific launch", { launch_id: launchIdParam }, async ({ launch_id }) => {
+        try {
+            const result = await client.get(`/launches/${launch_id}/boost`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_boost", "fetch a single boost by id with current performance metrics", { launch_id: launchIdParam, boost_id: boostIdParam }, async ({ launch_id, boost_id }) => {
+        try {
+            const result = await client.get(`/launches/${launch_id}/boost/${boost_id}`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("activate_boost", "flip a PAUSED boost to ACTIVE on meta. ad spend begins immediately. cannot be undone — use cancel_boost to stop.", { launch_id: launchIdParam, boost_id: boostIdParam }, async ({ launch_id, boost_id }) => {
+        try {
+            const result = await client.post(`/launches/${launch_id}/boost/${boost_id}/activate`, {});
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("cancel_boost", "cancel a boost — deletes the campaign on meta and soft-deletes the dropspace record. final, irreversible.", { launch_id: launchIdParam, boost_id: boostIdParam }, async ({ launch_id, boost_id }) => {
+        try {
+            await client.delete(`/launches/${launch_id}/boost/${boost_id}`);
+            return { content: [{ type: "text", text: JSON.stringify({ success: true, boost_id }, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("get_boost_performance", "fetch latest performance metrics for a boost (impressions, clicks, reach, spend). triggers a meta-side refresh if data is stale.", { launch_id: launchIdParam, boost_id: boostIdParam }, async ({ launch_id, boost_id }) => {
+        try {
+            const result = await client.get(`/launches/${launch_id}/boost/${boost_id}`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    });
+}

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": { "privacy_level": "PUBLIC_TO_EVERYONE"|"FOLLOWER_OF_CREATOR"|"MUTUAL_FOLLOW_FRIENDS"|"SELF_ONLY" (required before publish), "allow_comments"?, "allow_duet"?, "allow_stitch"?, "is_commercial"?, "is_your_brand"?, "is_branded_content"?, "auto_add_music"? (booleans) }. 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). 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()

package/dist/types.d.ts

@@ -316,3 +316,28 @@ export interface MediaGenerationJob {
 }
 /** Response when rotating an API key (includes new raw key, shown once) */
 export type RotateApiKeyResponse = CreateApiKeyResponse;
+/** Launch boost resource */
+export interface Boost {
+    id: string;
+    launch_id: string;
+    platform: "facebook" | "instagram";
+    post_id: string;
+    status: "paused" | "active" | "completed" | "failed" | "canceled";
+    objective: "engagement";
+    daily_budget_cents: number;
+    duration_days: number;
+    meta_ad_account_id: string;
+    meta_campaign_id: string | null;
+    meta_adset_id: string | null;
+    meta_ad_id: string | null;
+    impressions: number | null;
+    clicks: number | null;
+    reach: number | null;
+    total_spend_cents: number | null;
+    failure_reason: string | null;
+    created_at: string;
+    updated_at: string;
+    activated_at: string | null;
+    ended_at: string | null;
+    last_synced_at: string | null;
+}

package/package.json

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