@jclvsh/dropspace 2.36.1 → 2.42.0

package/README.md

@@ -269,8 +269,10 @@ Other agents that read skill files can use the same file from `node_modules/@jcl
 | `reply_to_comment`     | Reply as the publishing account: youtube and instagram (send scope, stdio only)                   |
 | `hide_comment`         | Hide or unhide a comment: instagram (send scope, stdio only)                                      |
 | `delete_comment`       | Permanently delete a comment: instagram, media owner only (send scope, stdio only)                |
+| `list_comment_queue` | Every comment still waiting for you across your recent instagram and youtube posts, with claude's suggested action (stdio only) |
+| `act_on_comments` | Hide (instagram, send scope) or dismiss up to 50 queue comments (stdio only) |
 
-CLI: `dropspace launches comments list|reply|hide|delete`.
+CLI: `dropspace launches comments list|reply|hide|delete` and `dropspace comment-queue list|hide|dismiss <platform:post_id:comment_id...>`.
 
 ### Reddit
 
@@ -370,14 +372,22 @@ Reddit engagement (drafted comments in other communities) is paused: its tools a
 | Tool           | Description                                                                                            |
 | -------------- | ------------------------------------------------------------------------------------------------------ |
 | `get_audience` | Follower counts and growth per connected account (Instagram, YouTube, TikTok, Twitter, Facebook Pages) |
+| `get_trial_reel_analytics` | Instagram trial reel results: totals, one entry per reel, and net followers since the first trial reel (local package only, not the hosted endpoint) |
+| `get_best_posting_hours` | When your Instagram followers are online (last 30 days): per hour, per weekday and hour, and the busiest hours (local package only, not the hosted endpoint) |
+| `get_audience_demographics` | Age, gender, country, and city of your Instagram followers and engaged audience (local package only, not the hosted endpoint) |
+| `get_reels_read` | Each Instagram account's latest reels read (local package only, not the hosted endpoint) |
+| `generate_reels_read` | Claude compares your top, middle, and bottom reels of the last 90 days; pro and premium, one a day per account (local package only, not the hosted endpoint) |
 
 #### `get_audience` Parameters
 
 | Parameter     | Type   | Required | Description                               |
 | ------------- | ------ | -------- | ----------------------------------------- |
 | `window_days` | number | No       | Growth window in days (1-365, default 30) |
+| `include_instagram_insights` | boolean | No | Add Instagram growth analytics to each Instagram entry (default false) |
 
-CLI: `dropspace audience [-w, --window-days <n>]`.
+CLI: `dropspace audience [-w, --window-days <n>] [--instagram-insights]`, `dropspace trial-reels`, `dropspace best-hours [--timezone <zone>]`, `dropspace demographics [--timeframe <this_week|this_month|last_90_days>]`, and `dropspace reels-read [--generate] [--connection-id <id>]`.
+
+With `include_instagram_insights`, each Instagram entry carries `instagram_insights`: follows, unfollows, net, and reach split into followers and non-followers per Pacific-time day, an estimated followers-over-time series rebuilt back from the current count, weekly growth velocity, the share of reach from non-followers, and contact-button taps. Instagram revises the last 7 days (`settled: false`). Each call reads up to 31 days, newest first, so a 90-day window fills over a few calls (`days_pending`). Instagram reports none of this for accounts under 100 followers (`available: false`).
 
 Counts come from each platform's official API and are cached for 15 minutes. YouTube works differently: each read spends a shared daily quota, so a connected account's YouTube count is refreshed in the background about once an hour, and an on-demand read re-fetches at most every 6 hours if that background refresh is delayed; if the daily quota is exhausted, a YouTube read returns the most recent successful count instead of null. `current.captured_at` is always when that count was actually read from the platform, not when it was served from cache - use it to judge freshness, not the response time. YouTube history points are kept for 30 days (YouTube's API storage limit), so YouTube growth reaches back about 30 days even for a longer `window_days`; other platforms keep their full history. LinkedIn is not covered (its API exposes no personal-profile follower count).
 

package/dist/commands/audience.js

@@ -4,11 +4,14 @@ export function registerAudienceCommands(program, client) {
         .command("audience")
         .description("follower counts + growth per connected account (instagram, youtube, tiktok, twitter, facebook pages); counts cache for 15 min, youtube refreshes about hourly in the background, and captured_at is always the actual read time, not the serve time")
         .option("-w, --window-days <n>", "growth window in days (max 365)", "30")
+        .option("--instagram-insights", "add instagram growth analytics: follows/unfollows per day, followers over time, velocity, reach split, contact taps")
         .action(async (opts) => {
         try {
             const params = {};
             if (opts.windowDays)
                 params.window_days = opts.windowDays;
+            if (opts.instagramInsights)
+                params.include = "instagram_insights";
             const result = await client.get("/audience", params);
             formatOutput(result, getFormat(program.opts()));
         }
@@ -16,4 +19,93 @@ export function registerAudienceCommands(program, client) {
             handleError(error);
         }
     });
+    program
+        .command("trial-reels")
+        .description("instagram trial reel results: totals, one entry per reel, and net followers since the first trial reel (stored numbers, no instagram request)")
+        .action(async () => {
+        try {
+            const result = await client.get("/analytics/trial-reels");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("best-hours")
+        .description("when your instagram followers are online (last 30 days): average per hour and per weekday-hour, and the busiest hours at least two hours apart; accounts with 100+ followers")
+        .option("--timezone <zone>", "IANA timezone for the hours (default: autopilot timezone, else UTC)")
+        .action(async (opts) => {
+        try {
+            const result = await client.get("/audience/best-hours", opts.timezone ? { timezone: opts.timezone } : undefined);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("demographics")
+        .description("who your instagram audience is: age, gender, country, and city of followers and of accounts that engaged in a timeframe; accounts with 100+ followers")
+        .option("--timeframe <period>", "engaged-audience period: this_week, this_month (default), last_90_days")
+        .action(async (opts) => {
+        try {
+            const result = await client.get("/audience/demographics", opts.timeframe ? { timeframe: opts.timeframe } : undefined);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    program
+        .command("reels-read")
+        .description("claude's read of your recent instagram reels (top, middle, and bottom by views over the last 90 days); shows the latest stored read, or makes a new one with --generate (pro and premium, one a day per account, 30-60 seconds)")
+        .option("--generate", "make a new read instead of showing the stored ones")
+        .option("--connection-id <id>", "instagram connection to read with --generate (default: the first instagram account)")
+        .action(async (opts) => {
+        try {
+            const result = opts.generate
+                ? await client.post("/analytics/reels-read", opts.connectionId ? { connection_id: opts.connectionId } : {})
+                : await client.get("/analytics/reels-read");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    const queue = program
+        .command("comment-queue")
+        .description("comments still waiting for you across your recent instagram and youtube posts");
+    queue
+        .command("list")
+        .description("waiting comments, newest first, with claude's suggested action and reply draft")
+        .action(async () => {
+        try {
+            const result = await client.get("/comments/queue");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    for (const action of ["hide", "dismiss"]) {
+        queue
+            .command(`${action} <refs...>`)
+            .description(action === "hide"
+            ? "hide comments on instagram (send scope); refs are platform:post_id:comment_id"
+            : "dismiss comments from the queue (nothing changes on the platform); refs are platform:post_id:comment_id")
+            .action(async (refs) => {
+            try {
+                const comments = refs.map((ref) => {
+                    const [platform, post_id, ...rest] = ref.split(":");
+                    return { platform, post_id, comment_id: rest.join(":") };
+                });
+                const result = await client.post("/comments/actions", { action, comments });
+                formatOutput(result, getFormat(program.opts()));
+            }
+            catch (error) {
+                handleError(error);
+            }
+        });
+    }
 }

package/dist/tool-policy.d.ts

@@ -29,7 +29,7 @@ export declare const REDDIT_ENGAGEMENT_PAUSED = true;
 export declare const PAUSED_TOOLS: ReadonlySet<string>;
 /** The tools the package serves - every docs count and category list reads this. */
 export declare const TOOL_POLICY: PolicyTable<ToolCategory>;
-export declare const toolPolicy: (name: string) => ToolPolicy<"audience" | "launches" | "comments" | "personas" | "connections" | "webhooks" | "usage" | "credits" | "media" | "boosts" | "posts" | "API keys" | "dropspace" | "account" | "autopilot" | "recommendations" | "reddit engagement">;
+export declare const toolPolicy: (name: string) => ToolPolicy<"audience" | "comments" | "launches" | "personas" | "connections" | "webhooks" | "usage" | "credits" | "media" | "boosts" | "posts" | "API keys" | "dropspace" | "account" | "autopilot" | "recommendations" | "reddit engagement">;
 export declare const isToolEnabled: (name: string, profile: ToolProfile) => boolean;
 export declare const toolAnnotations: (name: string) => {
     readOnlyHint: boolean;

package/dist/tool-policy.js

@@ -74,6 +74,9 @@ const FULL_TOOL_POLICY = {
     hide_comment: localOnly("comments", "sensitive"),
     // deletes on the platform with no restore
     delete_comment: localOnly("comments", "sensitive"),
+    list_comment_queue: localOnly("comments", "read"),
+    // hide changes the post on Instagram; dismiss only leaves the queue
+    act_on_comments: localOnly("comments", "sensitive"),
     // personas
     list_personas: hosted("personas", "read"),
     get_persona: hosted("personas", "read"),
@@ -118,6 +121,13 @@ const FULL_TOOL_POLICY = {
     dismiss_recommendation: hosted("recommendations", "write"),
     // audience, usage, status
     get_audience: hosted("audience", "read"),
+    // Local-only while the hosted set submitted to Meta on 10/13/2026 is in review (server.test.ts pins it).
+    get_trial_reel_analytics: localOnly("audience", "read"),
+    get_best_posting_hours: localOnly("audience", "read"),
+    get_audience_demographics: localOnly("audience", "read"),
+    get_reels_read: localOnly("audience", "read"),
+    // spends a Claude call and up to 60 Instagram requests; changes nothing the user posted
+    generate_reels_read: localOnly("audience", "write"),
     get_usage: hosted("usage", "read"),
     get_changelog: hosted("usage", "read"),
     get_dropspace_status: hosted("dropspace", "read"),

package/dist/tools/audience.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export function registerAudienceTools(server, client) {
-    server.tool("get_audience", 'follower counts + growth for every connected instagram / youtube / tiktok / twitter account and facebook page. one entry per ACCOUNT, not per platform: "entity_id" is null for your primary account on a platform and set for each additional one, so a user with two instagram accounts returns two instagram entries. counts come from each platform\'s official API and are cached for 15 minutes. youtube works differently: each youtube read spends a shared daily quota, so while you keep reading a creator\'s audience, their youtube count is refreshed in the background about once an hour, and an on-demand read re-fetches at most every 6 hours if that refresh is delayed; if the daily quota is exhausted, a youtube read returns the most recent successful count instead of null. "current.captured_at" is always when that count was actually read from the platform, never when it was served: use it to judge freshness. "series" is the stored history; youtube history is kept for 30 days (youtube\'s API storage limit), so youtube growth reaches back about 30 days whatever window_days says, while other platforms keep full history. growth is measured from the OLDEST stored point inside the window, which — because history points are recorded when you read, at most one per account per day — can be much younger than window_days: read "effective_window_days" (the span the delta actually covers) and "baseline_captured_at" before comparing growth across accounts. linkedin is not covered (its API exposes no personal-profile follower count).', {
+    server.tool("get_audience", 'follower counts + growth for every connected instagram / youtube / tiktok / twitter account and facebook page. one entry per ACCOUNT, not per platform: "entity_id" is null for your primary account on a platform and set for each additional one, so a user with two instagram accounts returns two instagram entries. counts come from each platform\'s official API and are cached for 15 minutes. youtube works differently: each youtube read spends a shared daily quota, so while you keep reading a creator\'s audience, their youtube count is refreshed in the background about once an hour, and an on-demand read re-fetches at most every 6 hours if that refresh is delayed; if the daily quota is exhausted, a youtube read returns the most recent successful count instead of null. "current.captured_at" is always when that count was actually read from the platform, never when it was served: use it to judge freshness. "series" is the stored history; youtube history is kept for 30 days (youtube\'s API storage limit), so youtube growth reaches back about 30 days whatever window_days says, while other platforms keep full history. growth is measured from the OLDEST stored point inside the window, which — because history points are recorded when you read, at most one per account per day — can be much younger than window_days: read "effective_window_days" (the span the delta actually covers) and "baseline_captured_at" before comparing growth across accounts. linkedin is not covered (its API exposes no personal-profile follower count). set include_instagram_insights to add instagram growth analytics to each instagram entry: follows, unfollows, net, and reach split into followers and non-followers per pacific-time day (the last 7 days are settled: false because instagram still revises them), followers_over_time (an estimate rebuilt back from the current count), weekly velocity with a trend, non_follower_reach_share, and contact-button taps. it reads up to 31 days per call, newest first, so a longer window fills over a few calls (days_pending says how many are left); instagram reports none of it for accounts under 100 followers (available: false).', {
         window_days: z
             .number()
             .int()
@@ -8,9 +8,18 @@ export function registerAudienceTools(server, client) {
             .max(365)
             .optional()
             .describe("growth window in days (default: 30, max: 365)"),
-    }, async ({ window_days }) => {
+        include_instagram_insights: z
+            .boolean()
+            .optional()
+            .describe("add instagram growth analytics to each instagram entry (default: false)"),
+    }, async ({ window_days, include_instagram_insights }) => {
         try {
-            const result = await client.get("/audience", window_days ? { window_days: String(window_days) } : undefined);
+            const params = {};
+            if (window_days)
+                params.window_days = String(window_days);
+            if (include_instagram_insights)
+                params.include = "instagram_insights";
+            const result = await client.get("/audience", Object.keys(params).length ? params : undefined);
             return {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             };
@@ -27,4 +36,105 @@ export function registerAudienceTools(server, client) {
             };
         }
     });
+    server.tool("get_trial_reel_analytics", "instagram trial reel results: totals across every trial reel posted through dropspace (views, reach summed per reel, likes, comments, shares, saves, plus views-weighted avg_watch_time_ms and skip_rate, the percent of plays that skipped in the first 3 seconds), one entry per reel newest first (up to 100, with the numbers last read from instagram and when), and followers_since_first: net follows minus unfollows on your instagram accounts since the pacific day of the first trial reel, from the daily counts get_audience with include_instagram_insights stores (days_counted of days_in_span says how complete it is; it counts every new follower, not only ones the trial reels brought). reads stored numbers only, so it makes no instagram request.", {}, async () => {
+        try {
+            const result = await client.get("/analytics/trial-reels");
+            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_best_posting_hours", "when your instagram followers are online, from instagram's online_followers insight over the last 30 days. per connected instagram account: hourly (average followers online in each hour of the day, index = hour 0-23), grid (average by weekday, index 0 = sunday, then hour), days_counted, and best_hours, the busiest hours at least two hours apart (up to 5, busiest first); the top-level best_hours combines every instagram account. every hour is in timezone (default: your autopilot timezone, else UTC). cached about 12 hours per account. instagram reports this only for accounts with 100 or more followers (available: false with unavailable_reason otherwise). to post at these hours, set autopilot posting_times to them with configure_autopilot.", {
+        timezone: z
+            .string()
+            .optional()
+            .describe("IANA timezone for every hour in the answer, e.g. America/New_York (default: autopilot timezone, else UTC)"),
+    }, async ({ timezone }) => {
+        try {
+            const result = await client.get("/audience/best-hours", timezone ? { timezone } : undefined);
+            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_audience_demographics", "who your instagram audience is: per connected instagram account, the age, gender (F, M, U = unknown), country (ISO code), and city of its current followers (followers) and of the accounts that engaged with it in timeframe (engaged), each split largest first with total = people instagram has demographic data for. instagram reports the top 45 rows per split and nothing for accounts under 100 followers (available: false with unavailable_reason). cached about 12 hours per account.", {
+        timeframe: z
+            .enum(["this_week", "this_month", "last_90_days"])
+            .optional()
+            .describe("period for the engaged audience (default this_month); followers are always current"),
+    }, async ({ timeframe }) => {
+        try {
+            const result = await client.get("/audience/demographics", timeframe ? { timeframe } : undefined);
+            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_reels_read", "each connected instagram account with its latest reels read (claude's comparison of the top, middle, and bottom reels by views over the last 90 days), read is absent when none was made in the last 30 days; oldest_posted_at says how far back a read reaches (up to 60 reels within 90 days). next_refresh_at is when generate_reels_read can make a new one. makes no instagram or claude request. pro and premium.", {}, async () => {
+        try {
+            const result = await client.get("/analytics/reels-read");
+            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("generate_reels_read", "make a reels read for one instagram account: the latest reels (up to 60) from the last 90 days are ranked by views, and claude compares the top, middle, and bottom ten from their captions and numbers (it never sees the videos). returns status ok with read (summary, working and not_working findings with evidence, three next steps), not_enough_reels (needs 8), or unavailable with reason. one new read per account a day: inside that day it returns the existing read with refreshed: false. takes 30-60 seconds. pro and premium.", {
+        connection_id: z
+            .string()
+            .uuid()
+            .optional()
+            .describe("instagram connection to read (from get_reels_read); default: the first instagram account"),
+    }, async ({ connection_id }) => {
+        try {
+            const result = await client.post("/analytics/reels-read", connection_id ? { connection_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/comments.js

@@ -76,4 +76,31 @@ export function registerCommentTools(server, client) {
             return fail(error);
         }
     });
+    server.tool("list_comment_queue", "every comment still waiting for you across your instagram and youtube posts made through dropspace in the last 30 days (newest 30 posts, newest 50 comments each), newest first, up to 200. waiting: not hidden, not written or answered by your account, and not replied to, hidden, deleted, or dismissed through dropspace. each comment carries its post (platform, post_id, launch_id, launch_name) and claude's read: kind (question, feedback, praise, spam, attack, other; null until sorted), suggested_action (reply, hide, dismiss), and reply_draft for questions and feedback; may_be_answered is true when youtube returned only some replies and none was yours. counts per kind; post_issues lists posts that could not be read. reply with reply_to_comment, delete with delete_comment (launch_id + post_id + comment id); hide or dismiss several with act_on_comments.", {}, async () => {
+        try {
+            return text(await client.get("/comments/queue"));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("act_on_comments", "hide (instagram only, changes the post, needs the send scope) or dismiss (seen, nothing to do; nothing changes on the platform, needs the write scope) up to 50 comments from list_comment_queue. hides are sent one a second. returns a result per comment (ok, detail); comments not on your own dropspace posts fail with the reason.", {
+        action: z.enum(["hide", "dismiss"]).describe("hide on instagram, or dismiss from the queue"),
+        comments: z
+            .array(z.object({
+            platform: z.enum(["instagram", "youtube"]),
+            post_id: z.string().min(1).max(200),
+            comment_id: z.string().min(1).max(200),
+        }))
+            .min(1)
+            .max(50)
+            .describe("comments from list_comment_queue: platform, post_id, and the comment's id"),
+    }, async ({ action, comments }) => {
+        try {
+            return text(await client.post("/comments/actions", { action, comments }));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/dropspace",
-	"version": "2.36.1",
+	"version": "2.42.0",
 	"description": "MCP server and CLI for the Dropspace API",
 	"repository": {
 		"type": "git",

package/skills/dropspace/SKILL.md

@@ -41,7 +41,7 @@ Dropspace turns one brief into per-platform posts and publishes them on the user
   - `media_source`: `ai` (generated slides and video), `library` (only the user's own media), or `mixed` (library first). `product_image_url` makes AI slides show the real product.
   - Media library (stdio server and CLI only): `list_media_library`, `add_to_media_library`, `update_media_library_item`, `delete_media_library_item`. Autopilot chooses items by their description, so describe each one. Items without one are captioned on autopilot's next run (images from the image, videos from their `thumbnail_url`), so a video needs a description or a thumbnail.
   - Brand kit: `update_persona` with `brand_kit` (text and outline colors, a corner logo) styles the image slides autopilot posts as that persona.
-- Audience: `get_audience` for follower counts on Instagram, TikTok, and YouTube.
+- Audience: `get_audience` for follower counts on Instagram, TikTok, and YouTube; its instagram insights option adds Instagram follows and unfollows per day, followers over time, growth velocity, and the non-follower reach share.
 - Webhooks: `create_webhook` with a Slack incoming webhook URL (`https://hooks.slack.com/services/...`) posts events to that channel as readable messages.
 
 ## Spending money - confirm first