@jclvsh/dropspace 2.0.0

package/README.md

@@ -0,0 +1,273 @@
+# @jclvsh/dropspace
+
+MCP server and CLI for the [Dropspace](https://dropspace.dev) API. Lets AI agents (Claude Code, Cursor) and humans manage launches, personas, platform connections, API keys, and webhooks.
+
+## Installation
+
+```bash
+npx @jclvsh/dropspace
+```
+
+Or install globally:
+
+```bash
+npm install -g @jclvsh/dropspace
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable            | Required | Description                                         |
+| ------------------- | -------- | --------------------------------------------------- |
+| `DROPSPACE_API_KEY` | Yes      | Your Dropspace API key                              |
+| `DROPSPACE_API_URL` | No       | API base URL (default: `https://api.dropspace.dev`) |
+
+### Claude Code
+
+Add to your `.claude/settings.json`:
+
+```json
+{
+	"mcpServers": {
+		"dropspace": {
+			"command": "npx",
+			"args": ["-y", "@jclvsh/dropspace"],
+			"env": {
+				"DROPSPACE_API_KEY": "ds_live_your_key_here"
+			}
+		}
+	}
+}
+```
+
+### Cursor
+
+Add to your `.cursor/mcp.json`:
+
+```json
+{
+	"mcpServers": {
+		"dropspace": {
+			"command": "npx",
+			"args": ["-y", "@jclvsh/dropspace"],
+			"env": {
+				"DROPSPACE_API_KEY": "ds_live_your_key_here"
+			}
+		}
+	}
+}
+```
+
+## Available Tools
+
+### Launches
+
+| Tool                   | Description                                                    |
+| ---------------------- | -------------------------------------------------------------- |
+| `list_launches`        | List your launches with pagination                             |
+| `create_launch`        | Create a new launch with content, media, and account selection |
+| `get_launch`           | Get a launch by ID with posting status                         |
+| `update_launch`        | Update a launch's schedule, status, content, or media          |
+| `delete_launch`        | Delete a launch                                                |
+| `publish_launch`       | Publish a launch to all configured platforms                   |
+| `retry_launch`         | Retry failed platforms for a launch                            |
+| `generate_content`     | Generate AI content and video scripts for a launch             |
+| `retry_launch_content` | Retry AI content generation for failed platforms               |
+| `get_launch_analytics` | Get publishing analytics with per-post engagement metrics      |
+| `get_launch_status`    | Get detailed posting status with per-platform logs             |
+
+#### `create_launch` Parameters
+
+| Parameter                     | Type               | Required | Description                                                                                                                                                                                             |
+| ----------------------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`                       | string             | Yes      | Launch title                                                                                                                                                                                            |
+| `product_description`         | string             | Yes      | Product description                                                                                                                                                                                     |
+| `platforms`                   | string[]           | Yes      | Platforms to publish to (1-9)                                                                                                                                                                           |
+| `product_url`                 | string             | No       | Product URL                                                                                                                                                                                             |
+| `scheduled_date`              | string             | No       | ISO 8601 datetime (15+ min in the future)                                                                                                                                                               |
+| `persona_id`                  | string             | No       | Persona ID for tone/style                                                                                                                                                                               |
+| `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`)                                                                                                                                         |
+| `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`)                                                                                                                        |
+| `media_assets`                | object[]           | No       | Pre-uploaded media references (mutually exclusive with `media`)                                                                                                                                         |
+| `media_attach_platforms`      | string[]           | No       | Platforms to attach media to                                                                                                                                                                            |
+| `generate_ai_videos`          | string[]           | No       | Auto-generate AI videos (`"instagram"`, `"tiktok"`)                                                                                                                                                     |
+
+#### `update_launch` Parameters
+
+| Parameter                | Type           | Required | Description                                                                                                                                                                                             |
+| ------------------------ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                     | string         | Yes      | Launch ID                                                                                                                                                                                               |
+| `scheduled_date`         | string \| null | No       | ISO 8601 datetime or null to clear                                                                                                                                                                      |
+| `status`                 | string         | No       | `"draft"`, `"manual"`, `"trigger"`, `"scheduled"`, `"cancelled"`                                                                                                                                        |
+| `platform_contents`      | object         | No       | Per-platform content overrides                                                                                                                                                                          |
+| `dropspace_platforms`    | string[]       | No       | Official dropspace account platforms                                                                                                                                                                    |
+| `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>` |
+| `media`                  | object[]       | No       | Inline media (URL or base64, 1-10 items)                                                                                                                                                                |
+| `media_assets`           | object[]       | No       | Pre-uploaded media references                                                                                                                                                                           |
+| `media_attach_platforms` | string[]       | No       | Platforms to attach media to                                                                                                                                                                            |
+| `media_mode`             | string         | No       | `"images"` or `"video"`                                                                                                                                                                                 |
+
+#### `generate_content` Parameters
+
+| Parameter                | Type     | Required | Description                                                         |
+| ------------------------ | -------- | -------- | ------------------------------------------------------------------- |
+| `id`                     | string   | Yes      | Launch ID                                                           |
+| `platforms`              | string[] | No       | Platforms to generate for (defaults to all)                         |
+| `generate_video_scripts` | string[] | No       | Platforms to generate video scripts for (`"instagram"`, `"tiktok"`) |
+
+### Personas
+
+| Tool              | Description                                      |
+| ----------------- | ------------------------------------------------ |
+| `list_personas`   | List your personas                               |
+| `create_persona`  | Create a new persona for content tone/style      |
+| `get_persona`     | Get a persona by ID with analysis details        |
+| `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 |
+
+#### `analyze_persona` Parameters
+
+| Parameter                | Type          | Required | Description                                |
+| ------------------------ | ------------- | -------- | ------------------------------------------ |
+| `id`                     | string (UUID) | Yes      | Persona ID                                 |
+| `platforms`              | string[]      | No       | Specific platforms to analyze samples from |
+| `include_custom_samples` | boolean       | No       | Include custom writing samples in analysis |
+
+#### `update_persona` Parameters
+
+| Parameter           | Type   | Required | Description                         |
+| ------------------- | ------ | -------- | ----------------------------------- |
+| `id`                | string | Yes      | Persona ID                          |
+| `name`              | string | No       | New persona name (1-100 characters) |
+| `custom_samples`    | array  | No       | Custom writing samples (max 50)     |
+| `twitter_samples`   | array  | No       | Twitter writing samples (max 50)    |
+| `reddit_samples`    | array  | No       | Reddit writing samples (max 50)     |
+| `facebook_samples`  | array  | No       | Facebook writing samples (max 50)   |
+| `instagram_samples` | array  | No       | Instagram writing samples (max 50)  |
+| `tiktok_samples`    | array  | No       | TikTok writing samples (max 50)     |
+| `linkedin_samples`  | array  | No       | LinkedIn writing samples (max 50)   |
+
+### Connections
+
+| Tool               | Description                               |
+| ------------------ | ----------------------------------------- |
+| `list_connections` | List your connected social media accounts |
+
+### Posts
+
+| Tool               | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `delete_post`      | Delete a single published post from its platform       |
+| `delete_all_posts` | Delete all published posts for a launch from platforms |
+
+### API Keys
+
+| Tool                  | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| `get_current_api_key` | Get the current API key's info (no scope required) |
+| `list_api_keys`       | List your API keys (requires admin scope)          |
+| `create_api_key`      | Create a new API key (raw key returned once)       |
+| `rename_api_key`      | Rename an API key                                  |
+| `revoke_api_key`      | Permanently revoke an API key                      |
+
+#### `create_api_key` Parameters
+
+| Parameter | Type     | Required | Description                                                                                    |
+| --------- | -------- | -------- | ---------------------------------------------------------------------------------------------- |
+| `name`    | string   | Yes      | Key name (1-100 characters)                                                                    |
+| `scopes`  | string[] | No       | Permission scopes (defaults to all): `read`, `write`, `delete`, `publish`, `generate`, `admin` |
+
+### Webhooks
+
+| Tool                      | Description                                                  |
+| ------------------------- | ------------------------------------------------------------ |
+| `list_webhooks`           | List your webhooks                                           |
+| `create_webhook`          | Create a webhook endpoint (secret returned once)             |
+| `get_webhook`             | Get a webhook by ID                                          |
+| `update_webhook`          | Update a webhook's URL, events, or active status             |
+| `delete_webhook`          | Delete a webhook                                             |
+| `rotate_webhook_secret`   | Rotate a webhook's signing secret (new secret returned once) |
+| `list_webhook_deliveries` | List delivery attempts for a webhook                         |
+
+#### `create_webhook` Parameters
+
+| Parameter | Type     | Required | Description                                                                                                                      |
+| --------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `url`     | string   | Yes      | HTTPS webhook URL                                                                                                                |
+| `events`  | string[] | Yes      | Events to subscribe to: `launch.completed`, `launch.failed`, `launch.partial`, `media.ready`, `persona.analyzed`, `post.deleted` |
+
+#### `update_webhook` Parameters
+
+| Parameter | Type          | Required | Description                   |
+| --------- | ------------- | -------- | ----------------------------- |
+| `id`      | string (UUID) | Yes      | Webhook ID                    |
+| `url`     | string        | No       | New HTTPS webhook URL         |
+| `events`  | string[]      | No       | New events to subscribe to    |
+| `active`  | boolean       | No       | Enable or disable the webhook |
+
+### Dropspace
+
+| Tool                   | Description                                              |
+| ---------------------- | -------------------------------------------------------- |
+| `get_dropspace_status` | Check which platforms have a connected dropspace account |
+
+### Usage
+
+| Tool        | Description                                             |
+| ----------- | ------------------------------------------------------- |
+| `get_usage` | Get your current plan, usage limits, and billing period |
+
+## API Key & Scopes
+
+Generate an API key at [dropspace.dev/settings](https://dropspace.dev/settings) under the API section.
+
+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                                           |
+
+### Recommended Scopes by Use Case
+
+| Use Case         | Recommended Scopes                                        |
+| ---------------- | --------------------------------------------------------- |
+| AI agents / MCP  | `read`, `write`, `generate`                               |
+| CI/CD publishing | `read`, `publish`                                         |
+| Monitoring       | `read`                                                    |
+| Full management  | `read`, `write`, `delete`, `publish`, `generate`, `admin` |
+
+## Webhook Events
+
+| Event              | Description                                                  |
+| ------------------ | ------------------------------------------------------------ |
+| `launch.completed` | All platforms finished posting successfully                  |
+| `launch.failed`    | Launch posting failed on all platforms                       |
+| `launch.partial`   | Launch posting succeeded on some platforms, failed on others |
+| `media.ready`      | Media generation job completed                               |
+| `persona.analyzed` | Persona AI analysis completed                                |
+| `post.deleted`     | A published post was deleted from its platform               |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run
+DROPSPACE_API_KEY=ds_live_... npm start
+```

package/dist/cli-utils.d.ts

@@ -0,0 +1,4 @@
+export declare function formatOutput(data: unknown, format?: string): void;
+export declare function handleError(error: unknown): never;
+export declare function getFormat(opts: Record<string, unknown>): string;
+export declare function parseList(value: string): string[];

package/dist/cli-utils.js

@@ -0,0 +1,31 @@
+export function formatOutput(data, format = "json") {
+    if (format === "table" && typeof data === "object" && data !== null) {
+        const obj = data;
+        if (Array.isArray(obj.data)) {
+            console.table(obj.data);
+            if (obj.pagination) {
+                const p = obj.pagination;
+                console.error(`\npage ${p.page}/${p.total_pages} (${p.total} total)`);
+            }
+            return;
+        }
+        if (obj.data && typeof obj.data === "object") {
+            console.log(JSON.stringify(obj.data, null, 2));
+            return;
+        }
+    }
+    console.log(JSON.stringify(data, null, 2));
+}
+export function handleError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`error: ${message}`);
+    process.exit(1);
+}
+export function getFormat(opts) {
+    if (opts.json)
+        return "json";
+    return opts.format || "json";
+}
+export function parseList(value) {
+    return value.split(",").map((s) => s.trim()).filter(Boolean);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { DropspaceClient } from "./client.js";
+import { handleError } from "./cli-utils.js";
+import { registerLaunchCommands } from "./commands/launches.js";
+import { registerPersonaCommands } from "./commands/personas.js";
+import { registerConnectionCommands } from "./commands/connections.js";
+import { registerKeyCommands } from "./commands/keys.js";
+import { registerWebhookCommands } from "./commands/webhooks.js";
+import { registerDropspaceCommands } from "./commands/dropspace.js";
+import { registerUsageCommands } from "./commands/usage.js";
+const program = new Command()
+    .name("dropspace")
+    .description("dropspace CLI - manage launches, personas, and more")
+    .version("2.0.0")
+    .option("--json", "output as JSON (default)")
+    .option("--format <fmt>", "output format: json, table", "json");
+try {
+    const client = new DropspaceClient();
+    registerLaunchCommands(program, client);
+    registerPersonaCommands(program, client);
+    registerConnectionCommands(program, client);
+    registerKeyCommands(program, client);
+    registerWebhookCommands(program, client);
+    registerDropspaceCommands(program, client);
+    registerUsageCommands(program, client);
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    handleError(error);
+}

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+export declare class DropspaceClient {
+    private apiKey;
+    private baseUrl;
+    constructor();
+    get<T>(path: string, params?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete(path: string): Promise<void>;
+    private request;
+    private handleError;
+}

package/dist/client.js

@@ -0,0 +1,110 @@
+const REQUEST_TIMEOUT_MS = 30_000;
+export class DropspaceClient {
+    apiKey;
+    baseUrl;
+    constructor() {
+        const apiKey = process.env.DROPSPACE_API_KEY;
+        if (!apiKey) {
+            throw new Error("DROPSPACE_API_KEY environment variable is required");
+        }
+        if (!apiKey.startsWith("ds_live_")) {
+            throw new Error("DROPSPACE_API_KEY must start with 'ds_live_'. Get one at https://dropspace.dev/settings");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (process.env.DROPSPACE_API_URL || "https://api.dropspace.dev").replace(/\/$/, "");
+    }
+    async get(path, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined && value !== "") {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        return this.request(url.toString(), { method: "GET" });
+    }
+    async post(path, body) {
+        return this.request(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    async patch(path, body) {
+        return this.request(`${this.baseUrl}${path}`, {
+            method: "PATCH",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+    }
+    async delete(path) {
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                method: "DELETE",
+                headers: { Authorization: `Bearer ${this.apiKey}` },
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            if (!response.ok && response.status !== 204) {
+                await this.handleError(response);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError") {
+                throw new Error("request timed out after 30s");
+            }
+            throw error;
+        }
+    }
+    async request(url, init) {
+        let response;
+        try {
+            response = await fetch(url, {
+                ...init,
+                headers: {
+                    ...(init.headers || {}),
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError") {
+                throw new Error("request timed out after 30s");
+            }
+            if (error instanceof TypeError) {
+                throw new Error(`network error: ${error.message}. check DROPSPACE_API_URL and your connection`);
+            }
+            throw error;
+        }
+        if (!response.ok) {
+            await this.handleError(response);
+        }
+        return (await response.json());
+    }
+    async handleError(response) {
+        let errorMessage;
+        try {
+            const body = (await response.json());
+            if (body.error) {
+                errorMessage = `[${body.error.code}] ${body.error.message}`;
+                if (body.error.field) {
+                    errorMessage += ` (field: ${body.error.field})`;
+                }
+            }
+            else {
+                errorMessage = `API error: ${response.status} ${response.statusText}`;
+            }
+        }
+        catch {
+            errorMessage = `API error: ${response.status} ${response.statusText}`;
+        }
+        if (response.status === 429) {
+            const retryAfter = response.headers.get("Retry-After");
+            if (retryAfter) {
+                errorMessage += ` — retry after ${retryAfter}s`;
+            }
+        }
+        throw new Error(errorMessage);
+    }
+}

package/dist/commands/connections.d.ts

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

package/dist/commands/connections.js

@@ -0,0 +1,23 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerConnectionCommands(program, client) {
+    const connections = program.command("connections").alias("c").description("manage platform connections");
+    connections
+        .command("list")
+        .description("list connected social media accounts")
+        .option("-p, --page <n>", "page number", "1")
+        .option("-s, --page-size <n>", "items per page (max 100)", "50")
+        .action(async (opts) => {
+        try {
+            const params = {};
+            if (opts.page)
+                params.page = opts.page;
+            if (opts.pageSize)
+                params.page_size = opts.pageSize;
+            const result = await client.get("/connections", params);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/dropspace.d.ts

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

package/dist/commands/dropspace.js

@@ -0,0 +1,15 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerDropspaceCommands(program, client) {
+    program
+        .command("status")
+        .description("check dropspace official account platform connections")
+        .action(async () => {
+        try {
+            const result = await client.get("/dropspace/status");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/keys.d.ts

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

package/dist/commands/keys.js

@@ -0,0 +1,70 @@
+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")
+        .description("get current API key info")
+        .action(async () => {
+        try {
+            const result = await client.get("/keys/me");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    keys
+        .command("list")
+        .description("list API keys (requires admin scope)")
+        .action(async () => {
+        try {
+            const result = await client.get("/keys");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    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)
+        .action(async (opts) => {
+        try {
+            const body = { name: opts.name };
+            if (opts.scopes)
+                body.scopes = opts.scopes;
+            const result = await client.post("/keys", body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    keys
+        .command("rename <id>")
+        .description("rename an API key (requires admin scope)")
+        .requiredOption("-n, --name <name>", "new key name")
+        .action(async (id, opts) => {
+        try {
+            const result = await client.patch(`/keys/${id}`, { name: opts.name });
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    keys
+        .command("revoke <id>")
+        .description("permanently revoke an API key (requires admin scope)")
+        .action(async (id) => {
+        try {
+            await client.delete(`/keys/${id}`);
+            console.log("api key revoked");
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/launches.d.ts

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