@jclvsh/dropspace 2.24.0 → 2.24.1

package/README.md

@@ -13,6 +13,8 @@ This installs two binaries:
 - `dropspace` — CLI for terminal use
 - `dropspace-mcp` — MCP server for AI agents
 
+Imported as a library, the package resolves only through its `exports` map (`.`, `./hosted`, `./tool-policy`, `./policy`, `./package.json`); deep imports of `dist/*` are not supported.
+
 ## CLI
 
 ```bash

package/dist/client.d.ts

@@ -7,7 +7,7 @@ export interface DropspaceClientOptions {
 export declare class DropspaceClient {
     private apiKey;
     private baseUrl;
-    /** True when the base URL was injected; the network-error hint then names the URL, not an env var. */
+    /** True when the base URL was injected; the network-error hint then names no URL or env var. */
     private hasInjectedBaseUrl;
     constructor(options?: DropspaceClientOptions);
     get<T>(path: string, params?: Record<string, string>): Promise<T>;
@@ -25,6 +25,8 @@ export declare class DropspaceClient {
         replayed: boolean;
     }>;
     private request;
+    /** Read a JSON body; a timeout while the body streams gets the same message as one during fetch. */
+    private readJson;
     private send;
     private handleError;
 }

package/dist/client.js

@@ -2,7 +2,7 @@ const REQUEST_TIMEOUT_MS = 30_000;
 export class DropspaceClient {
     apiKey;
     baseUrl;
-    /** True when the base URL was injected; the network-error hint then names the URL, not an env var. */
+    /** True when the base URL was injected; the network-error hint then names no URL or env var. */
     hasInjectedBaseUrl;
     constructor(options = {}) {
         const apiKey = options.apiKey ?? process.env.DROPSPACE_API_KEY;
@@ -10,7 +10,9 @@ export class DropspaceClient {
             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://www.dropspace.dev/settings");
+            // An injected key came from a hosted caller, who never set the env var.
+            const subject = options.apiKey !== undefined ? "api key" : "DROPSPACE_API_KEY";
+            throw new Error(`${subject} must start with 'ds_live_'. Get one at https://www.dropspace.dev/settings`);
         }
         this.apiKey = apiKey;
         this.hasInjectedBaseUrl = Boolean(options.baseUrl);
@@ -78,13 +80,25 @@ export class DropspaceClient {
             body: JSON.stringify(body),
         });
         return {
-            result: (await response.json()),
+            result: await this.readJson(response),
             replayed: response.headers.get("Idempotent-Replayed") === "true",
         };
     }
     async request(url, init) {
         const response = await this.send(url, init);
-        return (await response.json());
+        return this.readJson(response);
+    }
+    /** Read a JSON body; a timeout while the body streams gets the same message as one during fetch. */
+    async readJson(response) {
+        try {
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError") {
+                throw new Error("request timed out after 30s");
+            }
+            throw error;
+        }
     }
     async send(url, init) {
         let response;
@@ -104,7 +118,7 @@ export class DropspaceClient {
             }
             if (error instanceof TypeError) {
                 throw new Error(this.hasInjectedBaseUrl
-                    ? `network error: ${error.message} reaching ${this.baseUrl}`
+                    ? `network error reaching the api: ${error.message}`
                     : `network error: ${error.message}. check DROPSPACE_API_URL and your connection`);
             }
             throw error;

package/dist/hosted-transport.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Serve one MCP request over HTTP. LOCKSTEP across every apps/<app>/packages/mcp.
+ *
+ * Stateless: a fresh transport per request, no sessions, JSON responses - so it runs on
+ * serverless functions where consecutive requests from one client can land on different
+ * instances. Only POST is meaningful; the host must not route GET here (a stateless GET
+ * opens an event stream that never ends).
+ */
+export declare function serveStatelessMcp(server: McpServer, request: Request): Promise<Response>;

package/dist/hosted-transport.js

@@ -0,0 +1,17 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+/**
+ * Serve one MCP request over HTTP. LOCKSTEP across every apps/<app>/packages/mcp.
+ *
+ * Stateless: a fresh transport per request, no sessions, JSON responses - so it runs on
+ * serverless functions where consecutive requests from one client can land on different
+ * instances. Only POST is meaningful; the host must not route GET here (a stateless GET
+ * opens an event stream that never ends).
+ */
+export async function serveStatelessMcp(server, request) {
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    await server.connect(transport);
+    return transport.handleRequest(request);
+}

package/dist/hosted.d.ts

@@ -6,10 +6,5 @@ export interface HostedMcpOptions {
     /** Reported as serverInfo.version */
     version: string;
 }
-/**
- * Serve one MCP request over HTTP. Stateless: a fresh server and transport per request,
- * no sessions, JSON responses - so it runs on serverless functions where consecutive
- * requests from one client can land on different instances. Only POST is meaningful;
- * the host must not route GET here (a stateless GET opens an event stream that never ends).
- */
+/** One hosted MCP request: a per-request client and server over the stateless transport. */
 export declare function handleHostedMcpRequest(request: Request, options: HostedMcpOptions): Promise<Response>;

package/dist/hosted.js

@@ -1,19 +1,9 @@
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { DropspaceClient } from "./client.js";
+import { serveStatelessMcp } from "./hosted-transport.js";
 import { createDropspaceServer } from "./server.js";
-/**
- * Serve one MCP request over HTTP. Stateless: a fresh server and transport per request,
- * no sessions, JSON responses - so it runs on serverless functions where consecutive
- * requests from one client can land on different instances. Only POST is meaningful;
- * the host must not route GET here (a stateless GET opens an event stream that never ends).
- */
-export async function handleHostedMcpRequest(request, options) {
+/** One hosted MCP request: a per-request client and server over the stateless transport. */
+export function handleHostedMcpRequest(request, options) {
     const client = new DropspaceClient({ apiKey: options.apiKey, baseUrl: options.baseUrl });
     const server = createDropspaceServer({ client, version: options.version, profile: "hosted" });
-    const transport = new WebStandardStreamableHTTPServerTransport({
-        sessionIdGenerator: undefined,
-        enableJsonResponse: true,
-    });
-    await server.connect(transport);
-    return transport.handleRequest(request);
+    return serveStatelessMcp(server, request);
 }

package/dist/idempotency.d.ts

@@ -4,7 +4,7 @@
  * The REST API dedupes a request that repeats a key within 24 hours (per key + endpoint)
  * and answers with the original response plus `Idempotent-Replayed: true`. Deriving the
  * key from the arguments means a retry after a timeout - by an agent, or by a person
- * pressing "try again" in an MCP client - returns the launch that was already created
+ * pressing "try again" in an MCP client - returns the record that was already created
  * instead of creating a second one.
  */
 export declare function contentIdempotencyKey(args: unknown): Promise<string>;

package/dist/idempotency.js

@@ -4,7 +4,7 @@
  * The REST API dedupes a request that repeats a key within 24 hours (per key + endpoint)
  * and answers with the original response plus `Idempotent-Replayed: true`. Deriving the
  * key from the arguments means a retry after a timeout - by an agent, or by a person
- * pressing "try again" in an MCP client - returns the launch that was already created
+ * pressing "try again" in an MCP client - returns the record that was already created
  * instead of creating a second one.
  */
 function stable(value) {

package/dist/policy.d.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Generic tool-policy machinery. LOCKSTEP across every apps/<app>/packages/mcp
+ * (byte-identical; scripts/check-lockstep-identity.sh enforces it). The per-app
+ * table lives in tool-policy.ts next to this file.
+ *
+ * class:
+ *   read      - retrieves information; changes nothing.
+ *   write     - changes the app's own data, reversibly; nothing leaves the app.
+ *   sensitive - publishes, sends, or deletes on an external platform, deletes a record
+ *               with no user-facing restore, spends money, handles credentials, or
+ *               switches on automatic sending or posting.
+ * hosted: whether the app's hosted endpoint (api.<brand>/mcp) serves the tool.
+ * category: the documentation grouping every docs count is computed from.
+ */
+export type ToolClass = "read" | "write" | "sensitive";
+export type ToolProfile = "full" | "hosted";
+export interface ToolPolicy<Category extends string = string> {
+    class: ToolClass;
+    hosted: boolean;
+    category: Category;
+}
+export type PolicyTable<Category extends string = string> = Record<string, ToolPolicy<Category>>;
+export declare function toolPolicyFor<C extends string>(table: PolicyTable<C>, name: string): ToolPolicy<C>;
+export declare function isToolEnabledIn<C extends string>(table: PolicyTable<C>, name: string, profile: ToolProfile): boolean;
+export declare function toolAnnotationsFor<C extends string>(table: PolicyTable<C>, name: string): {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+};
+/** Tool names in a category, in table order. */
+export declare function toolsInCategoryOf<C extends string>(table: PolicyTable<C>, category: C): string[];
+/**
+ * A stand-in for McpServer that every register*Tools(server, client) function can be
+ * handed. It is the one place a tool is filtered by profile and given its annotations.
+ */
+export declare function createPolicyRegistrar<C extends string>(server: McpServer, table: PolicyTable<C>, profile: ToolProfile): McpServer;

package/dist/policy.js

@@ -0,0 +1,33 @@
+export function toolPolicyFor(table, name) {
+    const policy = table[name];
+    if (!policy) {
+        throw new Error(`tool "${name}" has no entry in tool-policy.ts - classify it before registering`);
+    }
+    return policy;
+}
+export function isToolEnabledIn(table, name, profile) {
+    const { hosted } = toolPolicyFor(table, name);
+    return profile === "full" || hosted;
+}
+export function toolAnnotationsFor(table, name) {
+    const toolClass = toolPolicyFor(table, name).class;
+    return { readOnlyHint: toolClass === "read", destructiveHint: toolClass === "sensitive" };
+}
+/** Tool names in a category, in table order. */
+export function toolsInCategoryOf(table, category) {
+    return Object.keys(table).filter((name) => table[name].category === category);
+}
+/**
+ * A stand-in for McpServer that every register*Tools(server, client) function can be
+ * handed. It is the one place a tool is filtered by profile and given its annotations.
+ */
+export function createPolicyRegistrar(server, table, profile) {
+    const registerAnnotated = server.tool.bind(server);
+    return {
+        tool(name, description, schema, handler) {
+            if (!isToolEnabledIn(table, name, profile))
+                return;
+            registerAnnotated(name, description, schema, toolAnnotationsFor(table, name), handler);
+        },
+    };
+}

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { DropspaceClient } from "./client.js";
-import { type ToolProfile } from "./tool-policy.js";
+import { type ToolProfile } from "./policy.js";
 export interface CreateDropspaceServerOptions {
     client: DropspaceClient;
     version: string;

package/dist/server.js

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { isToolEnabled, toolAnnotations } from "./tool-policy.js";
+import { createPolicyRegistrar } from "./policy.js";
+import { TOOL_POLICY } from "./tool-policy.js";
 import { registerLaunchTools } from "./tools/launches.js";
 import { registerPersonaTools } from "./tools/personas.js";
 import { registerConnectionTools } from "./tools/connections.js";
@@ -16,16 +17,7 @@ import { registerRedditTools } from "./tools/reddit.js";
 import { registerAudienceTools } from "./tools/audience.js";
 export function createDropspaceServer({ client, version, profile }) {
     const server = new McpServer({ name: "dropspace", version });
-    const registerAnnotated = server.tool.bind(server);
-    // Every register*Tools function calls server.tool(name, description, schema, handler).
-    // This stand-in is the one place a tool is filtered by profile and given its annotations.
-    const registrar = {
-        tool(name, description, schema, handler) {
-            if (!isToolEnabled(name, profile))
-                return;
-            registerAnnotated(name, description, schema, toolAnnotations(name), handler);
-        },
-    };
+    const registrar = createPolicyRegistrar(server, TOOL_POLICY, profile);
     registerLaunchTools(registrar, client);
     registerPersonaTools(registrar, client);
     registerConnectionTools(registrar, client);

package/dist/tool-policy.d.ts

@@ -1,12 +1,7 @@
 /**
  * The one place a tool is classified.
  *
- * class:
- *   read      - retrieves information; changes nothing.
- *   write     - changes dropspace data only, reversibly; nothing leaves dropspace.
- *   sensitive - publishes, schedules, or deletes on a social platform, deletes a record
- *               inside dropspace with no user-facing restore, spends money, handles
- *               credentials, or switches on something that will publish later.
+ * classes are defined in policy.ts; this file only assigns them.
  *
  * hosted: whether the hosted endpoint (https://api.dropspace.dev/mcp) serves the tool.
  * The stdio server serves every tool. Left off hosted: credits and boosts (payments and
@@ -19,21 +14,15 @@
  * Registering a tool with no entry here throws, and __tests__/server.test.ts fails on
  * any mismatch between this table and what the package registers.
  */
-export type ToolClass = "read" | "write" | "sensitive";
-export type ToolProfile = "full" | "hosted";
+import { type PolicyTable, type ToolClass, type ToolPolicy, type ToolProfile } from "./policy.js";
+export type { ToolClass, ToolPolicy, ToolProfile };
 export declare const TOOL_CATEGORIES: readonly ["launches", "posts", "personas", "media", "connections", "boosts", "credits", "API keys", "webhooks", "dropspace", "usage", "autopilot", "recommendations", "reddit engagement", "audience"];
 export type ToolCategory = (typeof TOOL_CATEGORIES)[number];
-export interface ToolPolicy {
-    class: ToolClass;
-    hosted: boolean;
-    category: ToolCategory;
-}
-export declare const TOOL_POLICY: Record<string, ToolPolicy>;
-export declare function toolPolicy(name: string): ToolPolicy;
-export declare function isToolEnabled(name: string, profile: ToolProfile): boolean;
-export declare function toolAnnotations(name: string): {
+export declare const TOOL_POLICY: PolicyTable<ToolCategory>;
+export declare const toolPolicy: (name: string) => ToolPolicy<"launches" | "personas" | "connections" | "webhooks" | "usage" | "credits" | "media" | "boosts" | "autopilot" | "recommendations" | "audience" | "dropspace" | "posts" | "API keys" | "reddit engagement">;
+export declare const isToolEnabled: (name: string, profile: ToolProfile) => boolean;
+export declare const toolAnnotations: (name: string) => {
     readOnlyHint: boolean;
     destructiveHint: boolean;
 };
-/** Tool names in a category, in table order. */
-export declare function toolsInCategory(category: ToolCategory): string[];
+export declare const toolsInCategory: (category: ToolCategory) => string[];

package/dist/tool-policy.js

@@ -1,12 +1,7 @@
 /**
  * The one place a tool is classified.
  *
- * class:
- *   read      - retrieves information; changes nothing.
- *   write     - changes dropspace data only, reversibly; nothing leaves dropspace.
- *   sensitive - publishes, schedules, or deletes on a social platform, deletes a record
- *               inside dropspace with no user-facing restore, spends money, handles
- *               credentials, or switches on something that will publish later.
+ * classes are defined in policy.ts; this file only assigns them.
  *
  * hosted: whether the hosted endpoint (https://api.dropspace.dev/mcp) serves the tool.
  * The stdio server serves every tool. Left off hosted: credits and boosts (payments and
@@ -19,6 +14,7 @@
  * Registering a tool with no entry here throws, and __tests__/server.test.ts fails on
  * any mismatch between this table and what the package registers.
  */
+import { isToolEnabledIn, toolAnnotationsFor, toolPolicyFor, toolsInCategoryOf, } from "./policy.js";
 export const TOOL_CATEGORIES = [
     "launches",
     "posts",
@@ -141,22 +137,7 @@ export const TOOL_POLICY = {
     test_webhook: localOnly("webhooks", "write"),
     rotate_webhook_secret: localOnly("webhooks", "sensitive"),
 };
-export function toolPolicy(name) {
-    const policy = TOOL_POLICY[name];
-    if (!policy) {
-        throw new Error(`tool "${name}" has no entry in tool-policy.ts - classify it before registering`);
-    }
-    return policy;
-}
-export function isToolEnabled(name, profile) {
-    const policy = toolPolicy(name);
-    return profile === "full" || policy.hosted;
-}
-export function toolAnnotations(name) {
-    const toolClass = toolPolicy(name).class;
-    return { readOnlyHint: toolClass === "read", destructiveHint: toolClass === "sensitive" };
-}
-/** Tool names in a category, in table order. */
-export function toolsInCategory(category) {
-    return Object.keys(TOOL_POLICY).filter((name) => TOOL_POLICY[name].category === category);
-}
+export const toolPolicy = (name) => toolPolicyFor(TOOL_POLICY, name);
+export const isToolEnabled = (name, profile) => isToolEnabledIn(TOOL_POLICY, name, profile);
+export const toolAnnotations = (name) => toolAnnotationsFor(TOOL_POLICY, name);
+export const toolsInCategory = (category) => toolsInCategoryOf(TOOL_POLICY, category);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/dropspace",
-	"version": "2.24.0",
+	"version": "2.24.1",
 	"description": "MCP server and CLI for the Dropspace API",
 	"repository": {
 		"type": "git",
@@ -19,6 +19,10 @@
 			"types": "./dist/hosted.d.ts",
 			"default": "./dist/hosted.js"
 		},
+		"./policy": {
+			"types": "./dist/policy.d.ts",
+			"default": "./dist/policy.js"
+		},
 		"./tool-policy": {
 			"types": "./dist/tool-policy.d.ts",
 			"default": "./dist/tool-policy.js"