@jclvsh/dropspace 2.0.4 → 2.2.0

package/README.md

@@ -9,6 +9,7 @@ npm install -g @jclvsh/dropspace
 ```
 
 This installs two binaries:
+
 - `dropspace` — CLI for terminal use
 - `dropspace-mcp` — MCP server for AI agents
 
@@ -41,15 +42,15 @@ dropspace launches --help
 
 ### CLI Commands
 
-| Group | Commands | Count |
-| --- | --- | --- |
-| launches | list, create, get, update, delete, publish, retry, generate, retry-content, analytics, batch-analytics, status, delete-post, delete-posts | 14 |
-| personas | list, create, get, update, delete, analyze | 6 |
-| connections | list | 1 |
-| keys | me, list, create, rename, revoke | 5 |
-| webhooks | list, create, get, update, delete, rotate-secret, deliveries | 7 |
-| status | dropspace official account connections | 1 |
-| usage | plan, limits, and billing period | 1 |
+| Group       | Commands                                                                                                                                  | Count |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| launches    | list, create, get, update, delete, publish, retry, generate, retry-content, analytics, batch-analytics, status, delete-post, delete-posts | 14    |
+| personas    | list, create, get, update, delete, analyze                                                                                                | 6     |
+| connections | list                                                                                                                                      | 1     |
+| keys        | me, list, create, rename, revoke                                                                                                          | 5     |
+| webhooks    | list, create, get, update, delete, rotate-secret, deliveries                                                                              | 7     |
+| status      | dropspace official account connections                                                                                                    | 1     |
+| usage       | plan, limits, and billing period                                                                                                          | 1     |
 
 ## MCP Server Configuration
 
@@ -269,14 +270,14 @@ Generate an API key at [www.dropspace.dev/settings](https://www.dropspace.dev/se
 
 API keys support scoped permissions:
 
-| Scope      | Access                                                                 |
-| ---------- | ---------------------------------------------------------------------- |
-| `read`     | List and read launches, personas, connections, dropspace status        |
-| `write`    | Create and update launches, personas                                   |
-| `delete`   | Delete launches, personas                                              |
-| `publish`  | Publish and retry launches                                             |
-| `generate` | Generate AI content, retry content generation                          |
-| `admin`    | Manage API keys and webhooks                                           |
+| Scope      | Access                                                          |
+| ---------- | --------------------------------------------------------------- |
+| `read`     | List and read launches, personas, connections, dropspace status |
+| `write`    | Create and update launches, personas                            |
+| `delete`   | Delete launches, personas                                       |
+| `publish`  | Publish and retry launches                                      |
+| `generate` | Generate AI content, retry content generation                   |
+| `admin`    | Manage API keys and webhooks                                    |
 
 ### Recommended Scopes by Use Case
 

package/dist/cli-utils.js

@@ -27,5 +27,8 @@ export function getFormat(opts) {
     return opts.format || "json";
 }
 export function parseList(value) {
-    return value.split(",").map((s) => s.trim()).filter(Boolean);
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
 }

package/dist/cli.js

@@ -11,6 +11,8 @@ import { registerKeyCommands } from "./commands/keys.js";
 import { registerWebhookCommands } from "./commands/webhooks.js";
 import { registerDropspaceCommands } from "./commands/dropspace.js";
 import { registerUsageCommands } from "./commands/usage.js";
+import { registerCreditCommands } from "./commands/credits.js";
+import { registerMediaCommands } from "./commands/media.js";
 const program = new Command()
     .name("dropspace")
     .description("dropspace CLI - manage launches, personas, and more")
@@ -26,6 +28,8 @@ try {
     registerWebhookCommands(program, client);
     registerDropspaceCommands(program, client);
     registerUsageCommands(program, client);
+    registerCreditCommands(program, client);
+    registerMediaCommands(program, client);
     await program.parseAsync(process.argv);
 }
 catch (error) {

package/dist/commands/credits.d.ts

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

package/dist/commands/credits.js

@@ -0,0 +1,32 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerCreditCommands(program, client) {
+    const credits = program.command("credits").description("manage MPP credit balance and packs");
+    credits
+        .command("balance")
+        .description("get current credit balance and available packs")
+        .action(async () => {
+        try {
+            const result = await client.get("/credits");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    credits
+        .command("purchase")
+        .description("purchase a credit pack (MPP auth only — API key and x402 callers are rejected)")
+        .option("--pack <id>", "pack ID (defaults to the standard pack)")
+        .action(async (opts) => {
+        try {
+            const body = {};
+            if (opts.pack)
+                body.pack = opts.pack;
+            const result = await client.post("/credits/purchase", body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/keys.js

@@ -1,8 +1,7 @@
 import { formatOutput, handleError, getFormat, parseList } from "../cli-utils.js";
 export function registerKeyCommands(program, client) {
     const keys = program.command("keys").alias("k").description("manage API keys");
-    keys
-        .command("me")
+    keys.command("me")
         .description("get current API key info")
         .action(async () => {
         try {
@@ -13,8 +12,7 @@ export function registerKeyCommands(program, client) {
             handleError(error);
         }
     });
-    keys
-        .command("list")
+    keys.command("list")
         .description("list API keys (requires admin scope)")
         .action(async () => {
         try {
@@ -25,8 +23,7 @@ export function registerKeyCommands(program, client) {
             handleError(error);
         }
     });
-    keys
-        .command("create")
+    keys.command("create")
         .description("create a new API key (requires admin scope)")
         .requiredOption("-n, --name <name>", "key name")
         .option("--scopes <list>", "comma-separated scopes: read,write,delete,publish,generate,admin", parseList)
@@ -42,8 +39,7 @@ export function registerKeyCommands(program, client) {
             handleError(error);
         }
     });
-    keys
-        .command("rename <id>")
+    keys.command("rename <id>")
         .description("rename an API key (requires admin scope)")
         .requiredOption("-n, --name <name>", "new key name")
         .action(async (id, opts) => {
@@ -55,8 +51,7 @@ export function registerKeyCommands(program, client) {
             handleError(error);
         }
     });
-    keys
-        .command("revoke <id>")
+    keys.command("revoke <id>")
         .description("permanently revoke an API key (requires admin scope)")
         .action(async (id) => {
         try {
@@ -67,4 +62,15 @@ export function registerKeyCommands(program, client) {
             handleError(error);
         }
     });
+    keys.command("rotate <id>")
+        .description("rotate an API key — old key is revoked, new key returned once (requires admin scope)")
+        .action(async (id) => {
+        try {
+            const result = await client.post(`/keys/${id}/rotate`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/commands/media.d.ts

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

package/dist/commands/media.js

@@ -0,0 +1,60 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerMediaCommands(program, client) {
+    const media = program.command("media").alias("m").description("generate AI images and videos");
+    media
+        .command("generate")
+        .description("submit an AI image or video generation job (returns 202 with job_id)")
+        .requiredOption("-t, --type <type>", "generation type: image, video, or script_video")
+        .requiredOption("--launch <id>", "launch ID this media is for")
+        .requiredOption("--platform <platform>", "target platform")
+        .option("--prompt <text>", "explicit prompt (required for script_video)")
+        .option("-d, --description <text>", "product description (used to derive prompt)")
+        .option("--reference <url>", "reference image URL")
+        .option("--aspect <ratio>", "aspect ratio (e.g. 1:1, 16:9, 9:16)")
+        .option("--duration <n>", "video duration in seconds (4, 6, or 8)")
+        .option("--seed <n>", "RNG seed for reproducibility")
+        .option("--negative-prompt <text>", "things to avoid in the generation")
+        .action(async (opts) => {
+        try {
+            const body = {
+                type: opts.type,
+                launch_id: opts.launch,
+                platform: opts.platform,
+            };
+            if (opts.prompt)
+                body.prompt = opts.prompt;
+            if (opts.description)
+                body.product_description = opts.description;
+            if (opts.reference)
+                body.reference_image_url = opts.reference;
+            const options = {};
+            if (opts.aspect)
+                options.aspect_ratio = opts.aspect;
+            if (opts.duration)
+                options.duration_seconds = parseInt(opts.duration, 10);
+            if (opts.seed)
+                options.seed = parseInt(opts.seed, 10);
+            if (opts.negativePrompt)
+                options.negative_prompt = opts.negativePrompt;
+            if (Object.keys(options).length > 0)
+                body.options = options;
+            const result = await client.post("/media/generate", body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    media
+        .command("job <id>")
+        .description("poll the status of a media generation job")
+        .action(async (id) => {
+        try {
+            const result = await client.get(`/media/${id}`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/index.js

@@ -9,9 +9,11 @@ import { registerKeyTools } from "./tools/keys.js";
 import { registerWebhookTools } from "./tools/webhooks.js";
 import { registerDropspaceTools } from "./tools/dropspace.js";
 import { registerUsageTools } from "./tools/usage.js";
+import { registerCreditTools } from "./tools/credits.js";
+import { registerMediaTools } from "./tools/media.js";
 const server = new McpServer({
     name: "dropspace",
-    version: "2.0.3",
+    version: "2.2.0",
 });
 const client = new DropspaceClient();
 registerLaunchTools(server, client);
@@ -21,5 +23,7 @@ registerKeyTools(server, client);
 registerWebhookTools(server, client);
 registerDropspaceTools(server, client);
 registerUsageTools(server, client);
+registerCreditTools(server, client);
+registerMediaTools(server, client);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/credits.d.ts

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

package/dist/tools/credits.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+export function registerCreditTools(server, client) {
+    server.tool("get_credit_balance", "get current MPP credit balance and available packs. API key callers always see balance 0 (credits are for MPP/x402 agent identities).", {}, async () => {
+        try {
+            const result = await client.get("/credits");
+            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("purchase_credit_pack", "purchase a credit pack via MPP (Stripe-based agent payment). API key and x402 wallet callers receive 400/401 — credits are MPP-only.", {
+        pack: z.string().optional().describe("pack ID (defaults to the standard pack if omitted)"),
+    }, async ({ pack }) => {
+        try {
+            const body = {};
+            if (pack)
+                body.pack = pack;
+            const result = await client.post("/credits/purchase", body);
+            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/keys.js

@@ -1,5 +1,8 @@
 import { z } from "zod";
-const SCOPES = ["read", "write", "delete", "publish", "generate", "admin"];
+// Cross-repo canonical scope vocabulary (2026-05-07): read/write/generate/send/admin.
+// Pre-rename: `delete` was folded into `write` (soft-deletes are writes); `publish` is now `send`.
+// Existing keys with legacy scope values continue to authenticate via SCOPE_ALIASES on the server.
+const SCOPES = ["read", "write", "generate", "send", "admin"];
 export function registerKeyTools(server, client) {
     server.tool("get_current_api_key", "get the current API key's info — name, scopes, and prefix (no scope required)", {}, async () => {
         try {
@@ -104,4 +107,25 @@ export function registerKeyTools(server, client) {
             };
         }
     });
+    server.tool("rotate_api_key", "rotate an API key — revokes the old key and returns a new one with the same name and scopes. The new raw key is shown once; store it immediately. The old key stops authenticating as soon as this returns. (requires admin scope)", {
+        id: z.string().uuid().describe("API key ID to rotate"),
+    }, async ({ id }) => {
+        try {
+            const result = await client.post(`/keys/${id}/rotate`);
+            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/media.d.ts

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

package/dist/tools/media.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+const PLATFORMS = [
+    "facebook",
+    "linkedin",
+    "linkedin-community",
+    "twitter",
+    "reddit",
+    "instagram",
+    "tiktok",
+    "youtube",
+    "substack",
+    "producthunt",
+    "hackernews",
+];
+const ASPECT_RATIOS = ["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "21:9"];
+export function registerMediaTools(server, client) {
+    server.tool("generate_media", "submit an AI image or video generation job for a launch. Returns 202 with a job_id; poll get_media_job for completion. Requires generate scope. script_video requires platform=instagram|tiktok and prompt is required (not just product_description). video and script_video only support 16:9 and 9:16 aspect ratios.", {
+        type: z.enum(["image", "video", "script_video"]).describe("generation type"),
+        launch_id: z.string().uuid().describe("launch ID this media is for"),
+        platform: z.enum(PLATFORMS).describe("target platform"),
+        prompt: z.string().optional().describe("explicit prompt — required for script_video"),
+        product_description: z
+            .string()
+            .optional()
+            .describe("product description (used to derive prompt when no explicit prompt is given)"),
+        reference_image_url: z
+            .string()
+            .url()
+            .optional()
+            .describe("reference image URL — guides image style/composition via the edit endpoint"),
+        options: z
+            .object({
+            aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe("aspect ratio"),
+            duration_seconds: z
+                .union([z.literal(4), z.literal(6), z.literal(8)])
+                .optional()
+                .describe("video duration in seconds (4, 6, or 8)"),
+            seed: z.number().optional().describe("RNG seed for reproducibility"),
+            negative_prompt: z.string().optional().describe("things to avoid in the generation"),
+        })
+            .optional()
+            .describe("generation options"),
+    }, async (args) => {
+        try {
+            const result = await client.post("/media/generate", args);
+            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_media_job", "poll the status of a media generation job. Returns the result_url when complete.", {
+        job_id: z.string().uuid().describe("media job ID returned by generate_media"),
+    }, async ({ job_id }) => {
+        try {
+            const result = await client.get(`/media/${job_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/types.d.ts

@@ -1,5 +1,6 @@
 /** Paginated API response wrapper */
 export interface PaginatedResponse<T> {
+    success: true;
     data: T[];
     pagination: {
         page: number;
@@ -10,14 +11,18 @@ export interface PaginatedResponse<T> {
 }
 /** Single-item API response wrapper */
 export interface DataResponse<T> {
+    success: true;
     data: T;
 }
 /** API error response */
 export interface ApiErrorResponse {
+    success: false;
     error: {
         code: string;
         message: string;
+        requestId: string;
         field?: string;
+        details?: Record<string, unknown>;
     };
 }
 /** Launch resource */
@@ -255,3 +260,52 @@ export interface RetryContentResponse {
     still_failing: string[];
     rate_limited: string[];
 }
+/** Credit pack offering */
+export interface CreditPack {
+    id: string;
+    credits: number;
+    price_usd: string;
+}
+/** Credit balance response (shape varies by auth type) */
+export interface CreditBalance {
+    balance: number;
+    packs?: CreditPack[];
+    purchase_endpoint?: string;
+    message?: string;
+}
+/** Credit pack purchase response */
+export interface CreditPurchaseResult {
+    credits_added: number;
+    new_balance: number;
+    pack: CreditPack;
+}
+/** Media generation job (initial response from POST /media/generate) */
+export interface MediaGenerationStarted {
+    status: "processing";
+    job_id: string;
+    fal_request_id: string;
+    generation_type: "image" | "video";
+    usage: {
+        used: number;
+        limit: number | "unlimited";
+        remaining: number | "unlimited";
+    };
+    plan: string;
+}
+/** Media generation job state (from GET /media/:jobId) */
+export interface MediaGenerationJob {
+    id: string;
+    generation_type: "image" | "video";
+    model_id: string;
+    prompt: string;
+    result_url: string | null;
+    status: string;
+    progress: number | null;
+    error_message: string | null;
+    launch_id: string | null;
+    reference_image_url: string | null;
+    created_at: string;
+    completed_at: string | null;
+}
+/** Response when rotating an API key (includes new raw key, shown once) */
+export type RotateApiKeyResponse = CreateApiKeyResponse;

package/package.json

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