posterly-mcp-server 0.44.0 → 0.45.0

package/dist/lib/tool-runtime.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Per-call context and shared helpers for the npm stdio tools that merge
+ * several old tools (MCP tool consolidation, 0.45.0).
+ *
+ *   - validateArgs(): the registry's per-mode rules (mcp-server/tool-registry.json)
+ *     run before any request, same as the hosted endpoint
+ *   - previewThenConfirm(): preview then confirm for public or destructive
+ *     actions; alias calls (ctx.legacyConfirm) keep their old one-step confirm
+ *     until the alias sunset date
+ *
+ * The context is built per call in index.ts from the transport's request map,
+ * never stored in the arguments or on shared state.
+ */
+import { type ToolRegistry } from './tool-registry.js';
+import type { StdioPreviewTokens } from './preview-token.js';
+export interface ToolContext {
+    /** The name the client called: an alias or the canonical tool. */
+    calledName: string;
+    /** True for alias calls: confirm: true alone still runs preview actions until the sunset date. */
+    legacyConfirm: boolean;
+    registry: ToolRegistry;
+    previews: StdioPreviewTokens;
+    /** The tool sets listed in this process (POSTERLY_TOOLSETS); every set when all is true. */
+    toolsets?: {
+        enabled: string[];
+        all: boolean;
+    };
+}
+/**
+ * Validates a merged tool's args against the registry's per-mode rules and
+ * returns the normalised args and mode. Throws a plain error before any request.
+ */
+export declare function validateArgs(ctx: ToolContext, tool: string, input: unknown): {
+    mode: string | null;
+    args: Record<string, any>;
+};
+/** A shallow copy of args without the given keys. */
+export declare function omitKeys(args: Record<string, any>, keys: string[]): Record<string, any>;
+export interface PreviewStep {
+    tool: string;
+    action: string;
+    /** Validated (normalised) args: the preview and the confirm call must hash identically. */
+    args: Record<string, any>;
+    /** Public writes: a preview_id can be confirmed once only. */
+    nonce: boolean;
+    /** The old tool's refusal when confirm is missing, for alias calls. */
+    legacyRefusal: string;
+    ctx: ToolContext;
+    /** What will change (may make one read request; must not throw). */
+    describe: () => Promise<string>;
+    run: () => Promise<string>;
+}
+/**
+ * Preview then confirm (docs/mcp-tool-design.md section 4). Canonical calls:
+ * no confirm returns a preview and a preview_id bound to this tool, action,
+ * and exact args; confirm needs that preview_id. Alias calls keep the old
+ * contract until the sunset: confirm: true alone runs the action.
+ */
+export declare function previewThenConfirm(step: PreviewStep): Promise<string>;
+/** Runs one read for a preview; a failed read (for example a 403 on a narrower key) falls back to echoing the request. */
+export declare function readForPreview<T>(read: () => Promise<T>): Promise<{
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function readFailedNote(error: string): string;

package/dist/lib/tool-runtime.js

@@ -0,0 +1,85 @@
+/**
+ * Per-call context and shared helpers for the npm stdio tools that merge
+ * several old tools (MCP tool consolidation, 0.45.0).
+ *
+ *   - validateArgs(): the registry's per-mode rules (mcp-server/tool-registry.json)
+ *     run before any request, same as the hosted endpoint
+ *   - previewThenConfirm(): preview then confirm for public or destructive
+ *     actions; alias calls (ctx.legacyConfirm) keep their old one-step confirm
+ *     until the alias sunset date
+ *
+ * The context is built per call in index.ts from the transport's request map,
+ * never stored in the arguments or on shared state.
+ */
+import { canonicalArgs, validateMode } from './tool-registry.js';
+import { previewFailureMessage } from './preview-token-core.js';
+import { code, mdSection, mdTitle } from './format.js';
+/** The local process serves one user; preview tokens are bound to this process's key anyway. */
+const STDIO_PREVIEW_USER = 'stdio-local';
+/**
+ * Validates a merged tool's args against the registry's per-mode rules and
+ * returns the normalised args and mode. Throws a plain error before any request.
+ */
+export function validateArgs(ctx, tool, input) {
+    const validated = validateMode(ctx.registry, tool, input);
+    if (!validated.ok)
+        throw new Error(validated.error);
+    return { mode: validated.mode, args: validated.args };
+}
+/** A shallow copy of args without the given keys. */
+export function omitKeys(args, keys) {
+    const out = {};
+    for (const [key, value] of Object.entries(args || {})) {
+        if (!keys.includes(key))
+            out[key] = value;
+    }
+    return out;
+}
+function formatPreview(body, previewId, tool) {
+    return [
+        mdTitle('Preview only: nothing has changed yet'),
+        body,
+        mdSection('Preview ID', `${code(previewId)} (expires in 10 minutes)`),
+        mdSection('Next step', `Show this preview to the user. Only after they explicitly approve, call ${tool} again with the same fields plus confirm: true and this preview_id.`),
+    ].filter(Boolean).join('\n\n');
+}
+/**
+ * Preview then confirm (docs/mcp-tool-design.md section 4). Canonical calls:
+ * no confirm returns a preview and a preview_id bound to this tool, action,
+ * and exact args; confirm needs that preview_id. Alias calls keep the old
+ * contract until the sunset: confirm: true alone runs the action.
+ */
+export async function previewThenConfirm(step) {
+    const { ctx, args } = step;
+    if (ctx.legacyConfirm) {
+        if (args.confirm !== true)
+            throw new Error(step.legacyRefusal);
+        return step.run();
+    }
+    const binding = { userId: STDIO_PREVIEW_USER, tool: step.tool, action: step.action, args: canonicalArgs(args) };
+    if (args.confirm !== true) {
+        const previewId = ctx.previews.create(binding);
+        return formatPreview(await step.describe(), previewId, step.tool);
+    }
+    const token = args.preview_id;
+    if (typeof token !== 'string' || !token)
+        throw new Error(previewFailureMessage('missing'));
+    const verified = ctx.previews.verify(token, binding);
+    if (!verified.ok)
+        throw new Error(previewFailureMessage(verified.reason));
+    if (step.nonce && !ctx.previews.claimOnce(token, verified.exp))
+        throw new Error(previewFailureMessage('used'));
+    return step.run();
+}
+/** Runs one read for a preview; a failed read (for example a 403 on a narrower key) falls back to echoing the request. */
+export async function readForPreview(read) {
+    try {
+        return { ok: true, data: await read() };
+    }
+    catch (error) {
+        return { ok: false, error: error?.message || String(error) };
+    }
+}
+export function readFailedNote(error) {
+    return `_posterly could not read the current item (${error}), so the preview shows the request as given._`;
+}

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.44.0";
+export declare const POSTERLY_MCP_VERSION = "0.45.0";

package/dist/lib/version.js

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.44.0';
+export const POSTERLY_MCP_VERSION = '0.45.0';

package/dist/tools/audit-google-business-profile.js

@@ -5,7 +5,7 @@ export const auditGoogleBusinessProfileTool = {
     inputSchema: z.object({
         workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
         account_id: z.number().int().positive().optional().describe('Google Business account ID from list_accounts.'),
-        location_id: z.string().optional().describe('Google Business numeric location id (the location_id/platform_user_id from list_accounts, e.g. "197940849675145390"). NOT the ChIJ... Place ID returned by get_google_business_review_link. Prefer account_id.'),
+        location_id: z.string().optional().describe('Google Business numeric location id (the location_id/platform_user_id from list_accounts, e.g. "197940849675145390"). NOT the ChIJ... Place ID from list_google_business_reviews view=review_link. Prefer account_id.'),
     }),
     async execute(client, input) {
         const result = await client.auditGoogleBusinessProfile(input);

package/dist/tools/connect-account.d.ts

@@ -20,13 +20,13 @@ export declare const connectAccountTool: {
         workspace_id: z.ZodOptional<z.ZodString>;
         connect_session_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        platform: "telegram" | "bluesky" | "discord" | "devto" | "hashnode" | "wordpress" | "lemmy";
+        platform: "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy";
         username?: string | undefined;
         workspace_id?: string | undefined;
         connect_session_id?: string | undefined;
-        handle?: string | undefined;
         bot_token?: string | undefined;
         chat_id?: string | undefined;
+        handle?: string | undefined;
         app_password?: string | undefined;
         webhook_url?: string | undefined;
         site_url?: string | undefined;
@@ -35,13 +35,13 @@ export declare const connectAccountTool: {
         instance?: string | undefined;
         password?: string | undefined;
     }, {
-        platform: "telegram" | "bluesky" | "discord" | "devto" | "hashnode" | "wordpress" | "lemmy";
+        platform: "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy";
         username?: string | undefined;
         workspace_id?: string | undefined;
         connect_session_id?: string | undefined;
-        handle?: string | undefined;
         bot_token?: string | undefined;
         chat_id?: string | undefined;
+        handle?: string | undefined;
         app_password?: string | undefined;
         webhook_url?: string | undefined;
         site_url?: string | undefined;

package/dist/tools/connect-account.js

@@ -26,7 +26,7 @@ const PLATFORM_CREDENTIAL_FIELDS = {
 };
 export const connectAccountTool = {
     name: 'connect_account',
-    description: 'Connect a credential-based social account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, without a browser session. Call get_connect_link first to discover the exact credential fields the platform needs. Prefer scoped secrets: app passwords (Bluesky, WordPress), bot tokens (Telegram), webhook URLs (Discord), and API tokens (Dev.to, Hashnode) over primary passwords. Warn the user that any credential they share passes through this conversation. For OAuth platforms (Instagram, X, LinkedIn, ...) use create_connect_session instead.',
+    description: 'Connect a credential-based social account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, without a browser session. Call list_platforms with view=connect_link first to discover the exact credential fields the platform needs. Prefer scoped secrets: app passwords (Bluesky, WordPress), bot tokens (Telegram), webhook URLs (Discord), and API tokens (Dev.to, Hashnode) over primary passwords. Warn the user that any credential they share passes through this conversation. For OAuth platforms (Instagram, X, LinkedIn, ...) use create_connect_session instead.',
     inputSchema: z.object({
         platform: z
             .enum(CREDENTIAL_PLATFORMS)
@@ -56,7 +56,7 @@ export const connectAccountTool = {
         }
         const missing = allowedFields.filter((field) => !(field in credentials));
         if (missing.length > 0) {
-            return `Missing credential field(s) for ${input.platform}: ${missing.join(', ')}. Call get_connect_link with platform=${input.platform} to see field descriptions.`;
+            return `Missing credential field(s) for ${input.platform}: ${missing.join(', ')}. Call list_platforms with view=connect_link and target=${input.platform} to see field descriptions.`;
         }
         const result = await client.connectAccountCredentials({
             platform: input.platform,

package/dist/tools/create-connect-session.d.ts

@@ -9,12 +9,12 @@ export declare const createConnectSessionTool: {
         auto_start: z.ZodOptional<z.ZodBoolean>;
         debug: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "medium" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
+        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "medium" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "reddit" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
         workspace_id?: string | undefined;
         auto_start?: boolean | undefined;
         debug?: boolean | undefined;
     }, {
-        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "medium" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "reddit" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
+        platform: "meta" | "instagram_direct" | "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "medium" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "reddit" | "skool" | "whop" | "gmb" | "google-business" | "google_business_profile" | "linkedin_page" | "facebook_instagram" | "facebook_pages" | "linkedin-company" | "linkedin-page" | "linkedin_company" | "linkedin_personal" | "meta_business" | "x_twitter";
         workspace_id?: string | undefined;
         auto_start?: boolean | undefined;
         debug?: boolean | undefined;

package/dist/tools/create-connect-session.js

@@ -3,7 +3,7 @@ import { DASHBOARD_CONNECT_URL, formatConnectedAccounts, formatLocalDateTime } f
 import { CONNECT_INPUTS } from '../generated/platform-manifest.js';
 export const createConnectSessionTool = {
     name: 'create_connect_session',
-    description: 'Create a short-lived posterly dashboard handoff session for connecting a social account. Send the secure connection URL to the user, then poll get_connect_session to narrate progress. Do not ask for social media passwords or OAuth codes; posterly handles those browser steps.',
+    description: 'Create a short-lived posterly dashboard handoff session for connecting a social account. Send the secure connection URL to the user, then poll list_accounts with view=connect_session to narrate progress. Do not ask for social media passwords or OAuth codes; posterly handles those browser steps.',
     inputSchema: z.object({
         platform: z
             .enum(CONNECT_INPUTS)
@@ -41,7 +41,7 @@ function formatConnectSession(session, includeRaw) {
         `Expires: ${formatLocalDateTime(session.expires_at)}`,
         `Dashboard connect page: ${DASHBOARD_CONNECT_URL}`,
         '',
-        'Next step for the AI agent: send the secure connection URL to the user, explain that posterly will handle the browser OAuth step, then poll get_connect_session until the account is connected or the session ends.',
+        'Next step for the AI agent: send the secure connection URL to the user, explain that posterly will handle the browser OAuth step, then poll list_accounts with view=connect_session until the account is connected or the session ends.',
         includeRaw ? `\nRaw connect session:\n${JSON.stringify(session, null, 2)}` : '',
     ].filter(Boolean).join('\n');
 }

package/dist/tools/create-post.d.ts

@@ -968,7 +968,7 @@ export declare const createPostPayloadInputSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">>>;
     workspace_id: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+    platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
     username?: string | undefined;
     workspace_id?: string | undefined;
     account_id?: string | undefined;
@@ -1131,7 +1131,7 @@ export declare const createPostPayloadInputSchema: z.ZodObject<{
         ai_generated: z.ZodOptional<z.ZodBoolean>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
 }, {
-    platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+    platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
     username?: string | undefined;
     workspace_id?: string | undefined;
     account_id?: string | undefined;
@@ -1787,7 +1787,7 @@ export declare const createPostInputSchema: z.ZodObject<{
     confirm: z.ZodLiteral<true>;
 }, "strip", z.ZodTypeAny, {
     confirm: true;
-    platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+    platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
     username?: string | undefined;
     workspace_id?: string | undefined;
     account_id?: string | undefined;
@@ -1951,7 +1951,7 @@ export declare const createPostInputSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough"> | undefined;
 }, {
     confirm: true;
-    platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+    platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
     username?: string | undefined;
     workspace_id?: string | undefined;
     account_id?: string | undefined;
@@ -2613,7 +2613,7 @@ export declare const createPostTool: {
         confirm: z.ZodLiteral<true>;
     }, "strip", z.ZodTypeAny, {
         confirm: true;
-        platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+        platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
         username?: string | undefined;
         workspace_id?: string | undefined;
         account_id?: string | undefined;
@@ -2777,7 +2777,7 @@ export declare const createPostTool: {
         }, z.ZodTypeAny, "passthrough"> | undefined;
     }, {
         confirm: true;
-        platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+        platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
         username?: string | undefined;
         workspace_id?: string | undefined;
         account_id?: string | undefined;

package/dist/tools/create-post.js

@@ -151,7 +151,7 @@ export const createPostPayloadInputSchema = z.object({
         .describe('For X or Threads only: array of 2+ strings, one per post in the thread. The first entry leads, the rest reply in order. When set, the platform must be twitter or threads.'),
     instagram_settings: instagramSettingsSchema
         .optional()
-        .describe('Instagram-specific settings. If “tag” is ambiguous, distinguish caption @mentions (put @username in caption), native media tags (user_tags), and co-author invitations (collaborators). Native media tags work with eligible direct or Meta-linked accounts; collaborators require an eligible Meta-linked account. Call get_platform_schema(account_id) first.'),
+        .describe('Instagram-specific settings. If “tag” is ambiguous, distinguish caption @mentions (put @username in caption), native media tags (user_tags), and co-author invitations (collaborators). Native media tags work with eligible direct or Meta-linked accounts; collaborators require an eligible Meta-linked account. Call list_platforms with view=schema and account_id first.'),
     platform_settings: platformSettingsSchema
         .optional()
         .describe('Platform-specific settings for the selected account. Use this for non-Instagram settings and prefer it over raw metadata.'),
@@ -218,9 +218,9 @@ export const createPostTool = {
         '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole, then prefer `create_posts_batch` so they are created in one API request.\n\n' +
         'AFTER CALLING: Tell the user the post was created, include the posterly dashboard link returned by the tool, and offer the next natural action. Do not narrate raw HTTP, curl, or API plumbing.\n\n' +
         'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace - pass workspace_id explicitly if the user has more than one workspace.\n\n' +
-        'MEDIA URLS: Posterly storage URLs are used as-is. Third-party HTTP(S) media URLs are copied into posterly storage before the post is saved, so API-created posts do not later fail on expired signed URLs. Short-lived signed URLs must still be live when this tool runs. You can also call `upload_media_from_url` first if you want to upload once and reuse the returned posterly URL across posts.\n\n' +
+        'MEDIA URLS: Posterly storage URLs are used as-is. Third-party HTTP(S) media URLs are copied into posterly storage before the post is saved, so API-created posts do not later fail on expired signed URLs. Short-lived signed URLs must still be live when this tool runs. You can also call `upload_media` with `url` first if you want to upload once and reuse the returned posterly URL across posts.\n\n' +
         'THREADS: Pass `thread_posts` (an array of 2+ strings) to schedule a multi-post thread on X (Twitter) or Threads (Meta). The first entry is the lead post; the rest are published as replies in the same chain. X entries are capped at 280 characters each (4000 for verified, 25000 for organization accounts); Threads entries are capped at 500 characters each. When `thread_posts` is set, `caption` is ignored.\n\n' +
-        'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/brandPartner, LinkedIn document titles/mentions/polls/content_call_to_action_label (including BUY_NOW and SHOP_NOW), TikTok direct-post privacy/toggles/commercial disclosure, Pinterest board/title/link/product_tags, GBP event/offer/CTA/recurrence, X reply settings/polls/paid_partnership, Threads reply controls/text attachments/ghost posts/spoilers/reply approvals/GIPHY, Telegram polls/buttons/video cover/live photo, Slack markdown/blocks, Mastodon visibility/quote/poll (media+poll allowed), and Instagram feed/story/reel/carousel/native media tags/collaborators/first comments/trial Reels/is_ai_generated/audio_id. For Instagram, @username in caption is only a caption mention; `user_tags` creates native media tags and `collaborators` sends co-author invitations only when the selected Meta-linked account reports those capabilities. Call `get_platform_schema` with the account ID first. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
+        'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/brandPartner, LinkedIn document titles/mentions/polls/content_call_to_action_label (including BUY_NOW and SHOP_NOW), TikTok direct-post privacy/toggles/commercial disclosure, Pinterest board/title/link/product_tags, GBP event/offer/CTA/recurrence, X reply settings/polls/paid_partnership, Threads reply controls/text attachments/ghost posts/spoilers/reply approvals/GIPHY, Telegram polls/buttons/video cover/live photo, Slack markdown/blocks, Mastodon visibility/quote/poll (media+poll allowed), and Instagram feed/story/reel/carousel/native media tags/collaborators/first comments/trial Reels/is_ai_generated/audio_id. For Instagram, @username in caption is only a caption mention; `user_tags` creates native media tags and `collaborators` sends co-author invitations only when the selected Meta-linked account reports those capabilities. Call `list_platforms` with `view: "schema"` and the account ID first. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
         'TIKTOK MEDIA: TikTok supports a single video or a photo slideshow of 1 to 35 images, never multiple videos. Image media auto-detects as a slideshow, so you usually do not set post_type or media_type for photos and every image is posted. Pass `platform_settings.media_type: "PHOTO"` to force a slideshow explicitly.',
     inputSchema: createPostInputSchema,
     async execute(client, input) {

package/dist/tools/create-posts-batch.d.ts

@@ -495,7 +495,7 @@ export declare const createPostsBatchTool: {
             }, z.ZodTypeAny, "passthrough">>>;
             workspace_id: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
-            platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+            platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
             username?: string | undefined;
             workspace_id?: string | undefined;
             account_id?: string | undefined;
@@ -658,7 +658,7 @@ export declare const createPostsBatchTool: {
                 ai_generated: z.ZodOptional<z.ZodBoolean>;
             }, z.ZodTypeAny, "passthrough"> | undefined;
         }, {
-            platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+            platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
             username?: string | undefined;
             workspace_id?: string | undefined;
             account_id?: string | undefined;
@@ -825,7 +825,7 @@ export declare const createPostsBatchTool: {
     }, "strip", z.ZodTypeAny, {
         confirm: true;
         posts: {
-            platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+            platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
             username?: string | undefined;
             workspace_id?: string | undefined;
             account_id?: string | undefined;
@@ -991,7 +991,7 @@ export declare const createPostsBatchTool: {
     }, {
         confirm: true;
         posts: {
-            platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "slack" | "mastodon" | "devto" | "hashnode" | "wordpress" | "lemmy" | "gmb" | "google-business" | "google_business_profile" | undefined;
+            platform?: "instagram" | "instagram-standalone" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | "x" | "telegram" | "bluesky" | "discord" | "wordpress" | "devto" | "hashnode" | "lemmy" | "slack" | "mastodon" | "gmb" | "google-business" | "google_business_profile" | undefined;
             username?: string | undefined;
             workspace_id?: string | undefined;
             account_id?: string | undefined;

package/dist/tools/create-webhook.d.ts

@@ -15,15 +15,15 @@ export declare const createWebhookTool: {
         url: string;
         description?: string | undefined;
         workspace_id?: string | undefined;
-        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
         is_active?: boolean | undefined;
+        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
     }, {
         confirm: true;
         url: string;
         description?: string | undefined;
         workspace_id?: string | undefined;
-        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
         is_active?: boolean | undefined;
+        events?: ("webhook.test" | "post.created" | "post.updated" | "post.deleted" | "post.publishing" | "post.published" | "post.failed" | "account.disconnected" | "analytics.synced" | "approval.requested" | "approval.approved" | "approval.changes_requested" | "approval.rejected" | "approval.commented")[] | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         url: string;

package/dist/tools/delete-post.d.ts

@@ -1,20 +1,44 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { type ToolContext } from '../lib/tool-runtime.js';
+type DeletePostInput = {
+    post_id?: number;
+    group_id?: string;
+    confirm?: boolean;
+    preview_id?: string;
+};
 export declare const deletePostTool: {
     name: string;
     description: string;
     inputSchema: z.ZodObject<{
-        post_id: z.ZodNumber;
-        confirm: z.ZodLiteral<true>;
+        post_id: z.ZodOptional<z.ZodNumber>;
+        group_id: z.ZodOptional<z.ZodString>;
+        confirm: z.ZodOptional<z.ZodBoolean>;
+        preview_id: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        confirm: true;
-        post_id: number;
+        confirm?: boolean | undefined;
+        preview_id?: string | undefined;
+        post_id?: number | undefined;
+        group_id?: string | undefined;
     }, {
-        confirm: true;
-        post_id: number;
+        confirm?: boolean | undefined;
+        preview_id?: string | undefined;
+        post_id?: number | undefined;
+        group_id?: string | undefined;
     }>;
-    execute(client: PosterlyClient, input: {
-        post_id: number;
-        confirm: true;
-    }): Promise<string>;
+    /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+    legacySchemas: {
+        delete_post_group: z.ZodObject<{
+            group_id: z.ZodString;
+            confirm: z.ZodLiteral<true>;
+        }, "strip", z.ZodTypeAny, {
+            confirm: true;
+            group_id: string;
+        }, {
+            confirm: true;
+            group_id: string;
+        }>;
+    };
+    execute(client: PosterlyClient, input: DeletePostInput, ctx: ToolContext): Promise<string>;
 };
+export {};

package/dist/tools/delete-post.js

@@ -1,24 +1,60 @@
 import { z } from 'zod';
-import { dashboardUrlForPosts } from '../lib/format.js';
+import { code, dashboardUrlForPosts } from '../lib/format.js';
+import { previewThenConfirm, validateArgs } from '../lib/tool-runtime.js';
 export const deletePostTool = {
     name: 'delete_post',
-    description: 'Delete a scheduled or draft post. DESTRUCTIVE and IRREVERSIBLE - the post and its caption cannot be recovered. Cannot delete published or currently publishing posts.\n\n' +
-        'REQUIRED BEFORE CALLING: Fetch the post with `get_post` first and show the user what will be deleted (caption, account, scheduled time). Get explicit confirmation ("yes delete it", "remove it") before calling. Never delete multiple posts in a single batch without listing each one and confirming the full list.',
+    description: 'Delete posts. DESTRUCTIVE and IRREVERSIBLE: deleted posts and captions cannot be recovered, and published or currently publishing posts are never deleted. post_id: delete one scheduled or draft post; fetch it with `get_post` first, show the user what will be deleted (caption, account, scheduled time), and pass confirm=true only after explicit confirmation ("yes delete it", "remove it"). group_id: delete every draft, scheduled, failed, or paused post matching a caller-defined group_id, post_group_id, api_group_id, or release_id; preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id. Never delete several posts one by one without listing each and confirming the full list.',
     inputSchema: z.object({
-        post_id: z.number().describe('The post ID to delete'),
-        confirm: z.literal(true).describe('Must be true after explicit user confirmation of the post deletion.'),
+        post_id: z.number().optional().describe('Delete this one post.'),
+        group_id: z.string().min(1).max(160).optional().describe('Delete every unpublished post in this group or release instead.'),
+        confirm: z
+            .boolean()
+            .optional()
+            .describe('post_id: true after explicit user confirmation of the deletion. group_id: leave out to get a preview; true only with the preview_id after the user approved it.'),
+        preview_id: z.string().optional().describe('group_id: the preview_id from the preview call. Required with confirm: true.'),
     }),
-    async execute(client, input) {
-        if (input.confirm !== true) {
-            throw new Error('Refusing to delete post without confirm=true after explicit user confirmation.');
+    /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+    legacySchemas: {
+        delete_post_group: z.object({
+            group_id: z.string().min(1).max(160),
+            confirm: z.literal(true),
+        }),
+    },
+    async execute(client, input, ctx) {
+        const { mode, args } = validateArgs(ctx, 'delete_post', input);
+        if (mode === 'group') {
+            return previewThenConfirm({
+                tool: 'delete_post',
+                action: 'group',
+                args,
+                nonce: false,
+                legacyRefusal: 'Refusing to delete post group without confirm=true after explicit user confirmation.',
+                ctx,
+                // GET /api/v1/posts has no group filter, so the preview says in plain
+                // words which posts match instead of listing them.
+                describe: async () => [
+                    `Deletes every draft, scheduled, failed, or paused post whose group_id, post_group_id, api_group_id, or release_id is ${code(args.group_id)}. Published posts are never deleted. This cannot be undone.`,
+                    'To see the posts first, call list_posts and check each post\'s group or release ID.',
+                ].join('\n\n'),
+                run: async () => {
+                    const result = await client.deletePostGroup(args.group_id);
+                    return JSON.stringify(result, null, 2);
+                },
+            });
         }
-        const result = await client.deletePost(input.post_id);
-        return [
-            `Post #${result.id} deleted successfully.`,
-            'It has been removed from the posterly queue.',
-            `View queue in posterly: ${dashboardUrlForPosts()}`,
-            '',
-            'Next step for the AI agent: tell the user the post is gone and offer to create, reschedule, or review the next post.',
-        ].join('\n');
+        return deleteOne(client, args);
     },
 };
+async function deleteOne(client, input) {
+    if (input.confirm !== true) {
+        throw new Error('Refusing to delete post without confirm=true after explicit user confirmation.');
+    }
+    const result = await client.deletePost(input.post_id);
+    return [
+        `Post #${result.id} deleted successfully.`,
+        'It has been removed from the posterly queue.',
+        `View queue in posterly: ${dashboardUrlForPosts()}`,
+        '',
+        'Next step for the AI agent: tell the user the post is gone and offer to create, reschedule, or review the next post.',
+    ].join('\n');
+}

package/dist/tools/generate-captions.d.ts

@@ -35,12 +35,12 @@ export declare const generateCaptionsTool: {
         platforms: ("instagram" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business")[];
         workspace_id?: string | undefined;
         count?: number | undefined;
+        mode?: "generate" | "adapt" | undefined;
         social_account_id?: string | undefined;
         brief?: string | undefined;
         tone?: string | undefined;
         allow_emojis?: boolean | undefined;
         hashtag_strategy?: "none" | "smart" | "minimal" | "aggressive" | undefined;
-        mode?: "generate" | "adapt" | undefined;
         source_caption?: string | undefined;
         source_platform?: "instagram" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | undefined;
         preserve_links?: boolean | undefined;
@@ -55,12 +55,12 @@ export declare const generateCaptionsTool: {
         platforms: ("instagram" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business")[];
         workspace_id?: string | undefined;
         count?: number | undefined;
+        mode?: "generate" | "adapt" | undefined;
         social_account_id?: string | undefined;
         brief?: string | undefined;
         tone?: string | undefined;
         allow_emojis?: boolean | undefined;
         hashtag_strategy?: "none" | "smart" | "minimal" | "aggressive" | undefined;
-        mode?: "generate" | "adapt" | undefined;
         source_caption?: string | undefined;
         source_platform?: "instagram" | "facebook" | "tiktok" | "twitter" | "threads" | "linkedin" | "youtube" | "pinterest" | "google_business" | undefined;
         preserve_links?: boolean | undefined;

package/dist/tools/generate-image.d.ts

@@ -20,10 +20,10 @@ export declare const generateImageTool: {
         prompt: string;
         provider?: "google" | "xai" | undefined;
         aspect_ratio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "4:5" | "1:4" | "1:8" | "21:9" | "4:1" | "8:1" | "5:4" | undefined;
+        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
+        model?: "pro" | "lite" | "flash" | undefined;
         style?: "minimal" | "professional" | "photographic" | "illustration" | "vibrant" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
         variations?: number | undefined;
-        model?: "pro" | "lite" | "flash" | undefined;
-        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
         quality?: "low" | "medium" | "high" | undefined;
         thinking_level?: "minimal" | "high" | undefined;
         reference_image_urls?: string[] | undefined;
@@ -32,10 +32,10 @@ export declare const generateImageTool: {
         prompt: string;
         provider?: "google" | "xai" | undefined;
         aspect_ratio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "4:5" | "1:4" | "1:8" | "21:9" | "4:1" | "8:1" | "5:4" | undefined;
+        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
+        model?: "pro" | "lite" | "flash" | undefined;
         style?: "minimal" | "professional" | "photographic" | "illustration" | "vibrant" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
         variations?: number | undefined;
-        model?: "pro" | "lite" | "flash" | undefined;
-        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
         quality?: "low" | "medium" | "high" | undefined;
         thinking_level?: "minimal" | "high" | undefined;
         reference_image_urls?: string[] | undefined;