posterly-mcp-server 0.44.0 → 0.45.0

package/src/tools/manage-google-business-review.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdKeyValue, mdQuote, mdSection } from '../lib/format.js';
+import { omitKeys, previewThenConfirm, validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+const LOCATION_ID_DESCRIPTION = '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.';
+const LEGACY_LOCATION = {
+  workspace_id: z.string().optional(),
+  account_id: z.number().int().positive().optional(),
+  location_id: z.string().optional(),
+};
+
+type ManageReviewInput = {
+  action: 'suggest_reply' | 'reply' | 'delete_reply';
+  workspace_id?: string;
+  account_id?: number;
+  location_id?: string;
+  review_name?: string;
+  comment?: string;
+  review_text?: string;
+  star_rating?: number;
+  reviewer_name?: string;
+  business_name?: string;
+  tone?: 'professional' | 'friendly' | 'apologetic';
+  count?: number;
+  confirm?: boolean;
+  preview_id?: string;
+};
+
+/** Everything the review endpoints accept, without the selector and confirm fields. */
+function payloadOf(input: ManageReviewInput): Record<string, any> {
+  return omitKeys(input, ['action', 'confirm', 'preview_id']);
+}
+
+function locationRows(input: ManageReviewInput): Array<[string, string | undefined]> {
+  return [
+    ['Account ID', input.account_id !== undefined ? code(input.account_id) : undefined],
+    ['Location ID', input.location_id ? code(input.location_id) : undefined],
+    ['Workspace', input.workspace_id ? code(input.workspace_id) : undefined],
+  ];
+}
+
+export const manageGoogleBusinessReviewTool = {
+  name: 'manage_google_business_review',
+  description:
+    'Act on Google Business Profile reviews. action=suggest_reply (star_rating, optional review_text): short, brand-aware AI reply suggestions; uses the AI Caption Assist allowance and never posts. action=reply (review_name, comment): post or update the owner reply. action=delete_reply (review_name): delete the owner reply. reply and delete_reply use preview then confirm: call without confirm to get a preview and preview_id (it repeats the review name, location, and exact reply text; show the reviewer, rating, and review text from list_google_business_reviews alongside it), then call again with confirm=true and that preview_id.',
+  inputSchema: z.object({
+    action: z.enum(['suggest_reply', 'reply', 'delete_reply']).describe('suggest_reply, reply, or delete_reply.'),
+    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 (optional brand voice context for suggest_reply).'),
+    location_id: z.string().optional().describe(LOCATION_ID_DESCRIPTION),
+    review_name: z.string().min(1).optional().describe('reply and delete_reply: full Google review resource name.'),
+    comment: z.string().min(1).max(4096).optional().describe('reply: exact owner reply text to post.'),
+    review_text: z.string().optional().describe('suggest_reply: review text. Leave empty for rating-only reviews.'),
+    star_rating: z.number().min(1).max(5).optional().describe('suggest_reply: review rating from 1 to 5.'),
+    reviewer_name: z.string().optional(),
+    business_name: z.string().optional(),
+    tone: z.enum(['professional', 'friendly', 'apologetic']).optional(),
+    count: z.number().int().min(1).max(5).optional(),
+    confirm: z.boolean().optional().describe('reply and delete_reply: leave out to get a preview; true only with the preview_id after the user approved it.'),
+    preview_id: z.string().optional().describe('reply and delete_reply: the preview_id from the preview call. Required with confirm: true.'),
+  }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    suggest_google_business_review_reply: z.object({
+      ...LEGACY_LOCATION,
+      review_text: z.string().optional(),
+      star_rating: z.number().min(1).max(5),
+      reviewer_name: z.string().optional(),
+      business_name: z.string().optional(),
+      tone: z.enum(['professional', 'friendly', 'apologetic']).optional(),
+      count: z.number().int().min(1).max(5).optional(),
+    }),
+    reply_google_business_review: z.object({
+      ...LEGACY_LOCATION,
+      review_name: z.string().min(1),
+      comment: z.string().min(1).max(4096),
+      confirm: z.literal(true),
+    }),
+    delete_google_business_review_reply: z.object({
+      ...LEGACY_LOCATION,
+      review_name: z.string().min(1),
+      confirm: z.literal(true),
+    }),
+  },
+
+  async execute(client: PosterlyClient, input: ManageReviewInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'manage_google_business_review', input);
+    const call = args as ManageReviewInput;
+    if (mode === 'suggest_reply') return suggestReply(client, call as ManageReviewInput & { star_rating: number });
+    if (mode === 'delete_reply') {
+      return previewThenConfirm({
+        tool: 'manage_google_business_review',
+        action: 'delete_reply',
+        args,
+        nonce: false,
+        legacyRefusal: 'Refusing to delete a Google review reply without confirm=true after explicit user confirmation.',
+        ctx,
+        describe: async () => [
+          mdSection('Review', mdKeyValue([['Review', code(String(call.review_name))], ...locationRows(call)])),
+          'This deletes the owner reply from this review on Google. The review itself stays.',
+        ].join('\n\n'),
+        run: async () => {
+          const result = await client.deleteGoogleBusinessReviewReply(payloadOf(call) as { review_name: string });
+          return result.message || 'Google Business review reply deleted successfully.';
+        },
+      });
+    }
+    return previewThenConfirm({
+      tool: 'manage_google_business_review',
+      action: 'reply',
+      args,
+      nonce: true,
+      legacyRefusal: 'Refusing to post a Google review reply without confirm=true after explicit user confirmation.',
+      ctx,
+      describe: async () => [
+        mdSection('Review', mdKeyValue([['Review', code(String(call.review_name))], ...locationRows(call)])),
+        mdSection('Owner reply to post', mdQuote(String(call.comment ?? ''))),
+        'This posts publicly on Google as the business owner and replaces any existing owner reply on this review.',
+      ].join('\n\n'),
+      run: async () => {
+        const result = await client.replyGoogleBusinessReview(payloadOf(call) as { review_name: string; comment: string });
+        return result.message || 'Google Business review reply posted successfully.';
+      },
+    });
+  },
+};
+
+async function suggestReply(client: PosterlyClient, input: ManageReviewInput & { star_rating: number }): Promise<string> {
+  const result = await client.suggestGoogleBusinessReviewReply(payloadOf(input) as { star_rating: number });
+  const suggestions = Array.isArray(result.suggestions) ? result.suggestions : [];
+  if (suggestions.length === 0) {
+    return 'No reply suggestions were generated.';
+  }
+  return [
+    `Suggested replies (${result.tone || 'professional'}, ${result.rating || input.star_rating} stars):`,
+    ...suggestions.map((text: string, index: number) => `${index + 1}. ${text}`),
+  ].join('\n');
+}

package/src/tools/manage-oauth-client.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdKeyValue, mdSection } from '../lib/format.js';
+import { omitKeys, previewThenConfirm, readFailedNote, readForPreview, validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+const scopeSchema = z.enum(['accounts:read', 'accounts:write', 'posts:read', 'posts:write', 'media:write', 'analytics:read']);
+
+type ManageOAuthClientInput = {
+  action: 'create' | 'update' | 'delete';
+  client_id?: string;
+  client_name?: string;
+  description?: string;
+  homepage?: string;
+  allowed_redirect_uris?: string[];
+  default_scopes?: string[];
+  is_active?: boolean;
+  confirm?: boolean;
+  preview_id?: string;
+};
+
+export const manageOAuthClientTool = {
+  name: 'manage_oauth_client',
+  description:
+    'Manage self-serve OAuth 2.1 + PKCE developer clients (public clients with no client secret; list them with list_oauth_clients). action=create: client_name, allowed_redirect_uris, and default_scopes; confirm=true only after the user confirms the name, redirect URIs, and scopes. action=update: client_id plus the changed fields; confirm=true after the user confirms the changes. action=delete: client_id; prevents new authorizations (existing access tokens stay revocable as API keys); 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.',
+  inputSchema: z.object({
+    action: z.enum(['create', 'update', 'delete']).describe('create, update, or delete.'),
+    client_id: z.string().min(1).optional().describe('update and delete: the client_id from list_oauth_clients.'),
+    client_name: z.string().min(1).max(120).optional().describe('create (required) or update.'),
+    description: z.string().max(500).optional(),
+    homepage: z.string().url().optional(),
+    allowed_redirect_uris: z.array(z.string().url()).min(1).max(10).optional().describe('create (required) or update.'),
+    default_scopes: z.array(scopeSchema).min(1).optional().describe('create (required) or update.'),
+    is_active: z.boolean().optional(),
+    confirm: z
+      .boolean()
+      .optional()
+      .describe('create and update: true after explicit user confirmation. delete: leave out to get a preview; true only with the preview_id after the user approved it.'),
+    preview_id: z.string().optional().describe('delete: the preview_id from the preview call. Required with confirm: true.'),
+  }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    create_oauth_client: z.object({
+      client_name: z.string().min(1).max(120),
+      description: z.string().max(500).optional(),
+      homepage: z.string().url().optional(),
+      allowed_redirect_uris: z.array(z.string().url()).min(1).max(10),
+      default_scopes: z.array(scopeSchema).min(1),
+      is_active: z.boolean().optional(),
+      confirm: z.literal(true),
+    }),
+    update_oauth_client: z.object({
+      client_id: z.string().min(1),
+      client_name: z.string().min(1).max(120).optional(),
+      description: z.string().max(500).optional(),
+      homepage: z.string().url().optional(),
+      allowed_redirect_uris: z.array(z.string().url()).min(1).max(10).optional(),
+      default_scopes: z.array(scopeSchema).min(1).optional(),
+      is_active: z.boolean().optional(),
+      confirm: z.literal(true),
+    }),
+    delete_oauth_client: z.object({ client_id: z.string().min(1), confirm: z.literal(true) }),
+  },
+
+  async execute(client: PosterlyClient, input: ManageOAuthClientInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'manage_oauth_client', input);
+    const call = args as ManageOAuthClientInput;
+    if (mode === 'create') {
+      if (call.confirm !== true) {
+        throw new Error('Refusing to create OAuth client without confirm=true after explicit user confirmation.');
+      }
+      const payload = omitKeys(call, ['action', 'confirm', 'preview_id']) as {
+        client_name: string;
+        allowed_redirect_uris: string[];
+        default_scopes: string[];
+      };
+      const result = await client.createOAuthClient(payload);
+      return `OAuth client created: ${result.client.client_name}\nclient_id: ${result.client.client_id}\nRedirect URIs: ${result.client.allowed_redirect_uris.join(', ')}`;
+    }
+    if (mode === 'update') {
+      if (call.confirm !== true) {
+        throw new Error('Refusing to update OAuth client without confirm=true after explicit user confirmation.');
+      }
+      const payload = omitKeys(call, ['action', 'confirm', 'preview_id', 'client_id']);
+      const result = await client.updateOAuthClient(String(call.client_id), payload);
+      return `OAuth client updated: ${result.client.client_name} (${result.client.client_id}) active=${result.client.is_active}`;
+    }
+    return previewThenConfirm({
+      tool: 'manage_oauth_client',
+      action: 'delete',
+      args,
+      nonce: false,
+      legacyRefusal: 'Refusing to delete OAuth client without confirm=true after explicit user confirmation.',
+      ctx,
+      describe: async () => {
+        const read = await readForPreview(() => client.listOAuthClients());
+        const found = read.ok ? read.data.clients.find((item) => String(item.client_id) === String(call.client_id)) : null;
+        const details = found
+          ? mdSection('OAuth client', mdKeyValue([
+              ['Name', found.client_name],
+              ['Client ID', code(found.client_id)],
+              ['Redirect URIs', found.allowed_redirect_uris.join(', ')],
+              ['Active', found.is_active],
+            ]))
+          : [
+              read.ok ? '_This client was not found in your OAuth client list, so the preview shows the request as given._' : readFailedNote(read.error),
+              mdKeyValue([['Client ID', code(String(call.client_id))]]),
+            ].join('\n\n');
+        return [details, 'This deletes the OAuth client: nobody can authorize it again. Existing access tokens stay revocable as API keys.'].join('\n\n');
+      },
+      run: async () => {
+        const result = await client.deleteOAuthClient(String(call.client_id));
+        return `OAuth client deleted: ${result.client_id}`;
+      },
+    });
+  },
+};

package/src/tools/manage-webhook.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdKeyValue, mdSection } from '../lib/format.js';
+import { omitKeys, previewThenConfirm, readFailedNote, readForPreview, validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+import { webhookEventSchema } from './webhook-events.js';
+
+type ManageWebhookInput = {
+  action: 'update' | 'delete' | 'test';
+  webhook_id: string;
+  url?: string;
+  events?: string[];
+  workspace_id?: string | null;
+  description?: string | null;
+  is_active?: boolean;
+  confirm?: boolean;
+  preview_id?: string;
+};
+
+export const manageWebhookTool = {
+  name: 'manage_webhook',
+  description:
+    'Change a webhook subscription (list them first with list_webhooks). action=update (webhook_id): change URL, events, workspace, description, or active state; outbound side effects, so pass confirm=true only after explicit confirmation. action=delete (webhook_id): remove the subscription; preview then confirm: call without confirm to get a preview and preview_id, show the URL, events, and workspace, then call again with confirm=true and that preview_id. action=test (webhook_id): send a signed webhook.test delivery; confirm=true after explicit confirmation.',
+  inputSchema: z.object({
+    action: z.enum(['update', 'delete', 'test']).describe('update, delete, or test.'),
+    webhook_id: z.string().describe('Webhook ID from list_webhooks.'),
+    url: z.string().url().optional().describe('update only.'),
+    events: z.array(webhookEventSchema).optional().describe('update only.'),
+    workspace_id: z.union([z.string(), z.null()]).optional().describe('update only. null clears the workspace.'),
+    description: z.union([z.string().max(240), z.null()]).optional().describe('update only.'),
+    is_active: z.boolean().optional().describe('update only.'),
+    confirm: z
+      .boolean()
+      .optional()
+      .describe('update and test: true after the user explicitly confirms. delete: leave out to get a preview; true only with the preview_id after the user approved it.'),
+    preview_id: z.string().optional().describe('delete: the preview_id from the preview call. Required with confirm: true.'),
+  }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    update_webhook: z.object({
+      webhook_id: z.string(),
+      url: z.string().url().optional(),
+      events: z.array(webhookEventSchema).optional(),
+      workspace_id: z.union([z.string(), z.null()]).optional(),
+      description: z.union([z.string().max(240), z.null()]).optional(),
+      is_active: z.boolean().optional(),
+      confirm: z.literal(true),
+    }),
+    delete_webhook: z.object({ webhook_id: z.string(), confirm: z.literal(true) }),
+    test_webhook: z.object({ webhook_id: z.string(), confirm: z.literal(true) }),
+  },
+
+  async execute(client: PosterlyClient, input: ManageWebhookInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'manage_webhook', input);
+    const call = args as ManageWebhookInput;
+    if (mode === 'update') {
+      if (call.confirm !== true) {
+        throw new Error('Refusing to update webhook without confirm=true after explicit user confirmation.');
+      }
+      const payload = omitKeys(call, ['action', 'confirm', 'preview_id', 'webhook_id']);
+      const result = await client.updateWebhook(call.webhook_id, payload);
+      const active = result.webhook.is_active ? 'active' : 'inactive';
+      return `Webhook updated: ${result.webhook.id}\nURL: ${result.webhook.url}\nState: ${active}\nEvents: ${result.webhook.events.join(', ')}`;
+    }
+    if (mode === 'test') {
+      if (call.confirm !== true) {
+        throw new Error('Refusing to test webhook without confirm=true after explicit user confirmation.');
+      }
+      const result = await client.testWebhook(call.webhook_id);
+      const delivery = result.delivery || {};
+      return `Webhook test sent.\nDelivery: ${JSON.stringify(delivery, null, 2)}`;
+    }
+    return previewThenConfirm({
+      tool: 'manage_webhook',
+      action: 'delete',
+      args,
+      nonce: false,
+      legacyRefusal: 'Refusing to delete webhook without confirm=true after explicit user confirmation.',
+      ctx,
+      describe: async () => {
+        // There is no GET /webhooks/:id, so the preview finds it in the list.
+        const read = await readForPreview(() => client.listWebhooks({}));
+        const webhook = read.ok ? read.data.webhooks.find((item) => String(item.id) === String(call.webhook_id)) : null;
+        const details = webhook
+          ? mdSection('Webhook', mdKeyValue([
+              ['Webhook ID', code(webhook.id)],
+              ['URL', webhook.url],
+              ['Events', webhook.events?.length ? webhook.events.join(', ') : 'default events'],
+              ['State', webhook.is_active ? 'active' : 'inactive'],
+              ['Workspace', webhook.workspace_id ? code(webhook.workspace_id) : 'all workspaces'],
+            ]))
+          : [
+              read.ok ? '_This webhook was not found in your webhook list, so the preview shows the request as given._' : readFailedNote(read.error),
+              mdKeyValue([['Webhook ID', code(call.webhook_id)]]),
+            ].join('\n\n');
+        return [details, 'This deletes the webhook subscription. posterly stops sending events to its URL.'].join('\n\n');
+      },
+      run: async () => {
+        const result = await client.deleteWebhook(call.webhook_id);
+        return `Webhook deleted: ${result.id}`;
+      },
+    });
+  },
+};

package/src/tools/update-post.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { code, formatDateTime, mdKeyValue, mdQuote, mdSection, mdTitle, statusLabel } from '../lib/format.js';
+import { validateArgs, type ToolContext } from '../lib/tool-runtime.js';
 
 const mediaAccessibilitySchema = z.array(z.object({
   index: z.number().int().nonnegative(),
@@ -110,11 +111,29 @@ const platformSettingsSchema = z.object({
   ai_generated: z.boolean().optional(),
 }).passthrough();
 
+type EditInput = {
+  post_id: number;
+  caption?: string;
+  scheduled_at?: string;
+  media_url?: string;
+  media_urls?: string[];
+  post_type?: string;
+  instagram_settings?: z.infer<typeof instagramSettingsSchema>;
+  platform_settings?: z.infer<typeof platformSettingsSchema>;
+  confirm: true;
+};
+
+type UpdatePostInput = EditInput & {
+  status?: 'scheduled' | 'paused' | 'draft';
+  release_id?: string;
+  group_id?: string;
+};
+
 export const updatePostTool = {
   name: 'update_post',
   description:
-    'Update a scheduled or draft post. DESTRUCTIVE WRITE - overwrites the existing post\'s caption/media/schedule. Cannot edit published or currently publishing posts. If a client has already approved the post, a caption edit reopens caption approval and a media or thumbnail edit reopens asset approval. A reschedule, account change or settings change cannot be attributed to one axis and reopens both.\n\n' +
-    'REQUIRED BEFORE CALLING: Show the user a side-by-side of the CURRENT post (caption, scheduled time, media) and the PROPOSED changes, and get explicit confirmation ("yes update it", "apply those changes") before calling. Do not auto-edit posts based on a general instruction - each edit needs its own confirmation.',
+    'Change a scheduled or draft post. DESTRUCTIVE WRITE. Edit (default): caption, media, schedule, post_type, or settings; overwrites the existing post; cannot edit published or currently publishing posts; if a client has already approved the post, a caption edit reopens caption approval, a media or thumbnail edit reopens asset approval, and a reschedule, account change or settings change reopens both. status (scheduled, paused, or draft, with scheduled_at when scheduling a draft): pause, resume, or move back to draft; send it on its own. release_id (with optional group_id): set or repair external release/group IDs; send it on its own.\n\n' +
+    'REQUIRED BEFORE CALLING: Show the user a side-by-side of the CURRENT post (caption, scheduled time, media, status) and the PROPOSED change, and get explicit confirmation ("yes update it", "apply those changes") before calling. Do not auto-edit posts based on a general instruction - each change needs its own confirmation.',
   inputSchema: z.object({
     post_id: z.number().describe('The post ID to update'),
     caption: z.string().optional().describe('New caption/text content'),
@@ -136,48 +155,96 @@ export const updatePostTool = {
     reel_thumb_offset: z.number().nonnegative().optional().describe('Frame offset in milliseconds to use as the reel cover.'),
     instagram_settings: instagramSettingsSchema
       .optional()
-      .describe('Instagram-specific updates. Distinguish caption @mentions, native media user_tags, and 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 updates. Distinguish caption @mentions, native media user_tags, and 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 to merge into the post. Prefer this over raw metadata.'),
-    confirm: z.literal(true).describe('Must be true after explicit user confirmation of the proposed post update.'),
+    status: z
+      .enum(['scheduled', 'paused', 'draft'])
+      .optional()
+      .describe('Change the post status instead of editing it. Send with post_id (and scheduled_at when scheduling a draft) only.'),
+    release_id: z
+      .string()
+      .min(1)
+      .max(160)
+      .optional()
+      .describe('Set an external release ID instead of editing the post. Send with post_id and optional group_id only.'),
+    group_id: z.string().min(1).max(160).optional().describe('With release_id only: an external group/campaign ID.'),
+    confirm: z.literal(true).describe('Must be true after explicit user confirmation of the proposed change.'),
   }),
 
-  async execute(
-    client: PosterlyClient,
-    input: {
-      post_id: number;
-      caption?: string;
-      scheduled_at?: string;
-      media_url?: string;
-      media_urls?: string[];
-      post_type?: string;
-      instagram_settings?: z.infer<typeof instagramSettingsSchema>;
-      platform_settings?: z.infer<typeof platformSettingsSchema>;
-      confirm: true;
-    },
-  ) {
-    if (input.confirm !== true) {
-      throw new Error('Refusing to update post without confirm=true after explicit user confirmation.');
-    }
-    const { post_id, confirm: _confirm, instagram_settings, platform_settings, ...updates } = input;
-    const payload = {
-      ...updates,
-      ...(platform_settings || instagram_settings
-        ? { settings: { ...(instagram_settings ? { __type: 'instagram', ...instagram_settings } : {}), ...(platform_settings || {}) } }
-        : {}),
-    };
-    const result = await client.updatePost(post_id, payload);
-    const p = result.post as Record<string, any>;
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    update_post_status: z.object({
+      post_id: z.number(),
+      status: z.enum(['scheduled', 'paused', 'draft']),
+      scheduled_at: z.string().optional(),
+      confirm: z.boolean(),
+    }),
+    update_post_release_id: z.object({
+      post_id: z.number().int().positive(),
+      release_id: z.string().min(1).max(160),
+      group_id: z.string().min(1).max(160).optional(),
+      confirm: z.literal(true),
+    }),
+  },
 
-    return [
-      mdTitle(`✅ Post ${code(p.id)} updated`),
-      mdKeyValue([
-        ['Status', statusLabel(p.status)],
-        ['Scheduled', formatDateTime(p.scheduled_at)],
-        ['Type', p.post_type || 'unknown'],
-      ]),
-      mdSection('Caption', p.content ? mdQuote(p.content) : '_(empty)_'),
-    ].join('\n\n');
+  async execute(client: PosterlyClient, input: UpdatePostInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'update_post', input);
+    if (mode === 'status') return updateStatus(client, args as { post_id: number; status: 'scheduled' | 'paused' | 'draft'; scheduled_at?: string; confirm: boolean });
+    if (mode === 'release_id') return updateReleaseId(client, args as { post_id: number; release_id: string; group_id?: string; confirm: true });
+    return editPost(client, args as EditInput);
   },
 };
+
+async function editPost(client: PosterlyClient, input: EditInput): Promise<string> {
+  if (input.confirm !== true) {
+    throw new Error('Refusing to update post without confirm=true after explicit user confirmation.');
+  }
+  const { post_id, confirm: _confirm, preview_id: _previewId, instagram_settings, platform_settings, ...updates } = input as EditInput & { preview_id?: string };
+  const payload = {
+    ...updates,
+    ...(platform_settings || instagram_settings
+      ? { settings: { ...(instagram_settings ? { __type: 'instagram', ...instagram_settings } : {}), ...(platform_settings || {}) } }
+      : {}),
+  };
+  const result = await client.updatePost(post_id, payload);
+  const p = result.post as Record<string, any>;
+
+  return [
+    mdTitle(`✅ Post ${code(p.id)} updated`),
+    mdKeyValue([
+      ['Status', statusLabel(p.status)],
+      ['Scheduled', formatDateTime(p.scheduled_at)],
+      ['Type', p.post_type || 'unknown'],
+    ]),
+    mdSection('Caption', p.content ? mdQuote(p.content) : '_(empty)_'),
+  ].join('\n\n');
+}
+
+async function updateStatus(
+  client: PosterlyClient,
+  input: { post_id: number; status: 'scheduled' | 'paused' | 'draft'; scheduled_at?: string; confirm: boolean },
+): Promise<string> {
+  if (input.confirm !== true) {
+    throw new Error('Refusing to update post status without confirm=true after explicit user confirmation.');
+  }
+
+  const result = await client.updatePostStatus(input.post_id, {
+    status: input.status,
+    scheduled_at: input.scheduled_at,
+  });
+  const transition = result.transition || {};
+  return `Post #${input.post_id} status changed from ${transition.old_status || 'unknown'} to ${transition.new_status || input.status}.`;
+}
+
+async function updateReleaseId(
+  client: PosterlyClient,
+  input: { post_id: number; release_id: string; group_id?: string; confirm: true },
+): Promise<string> {
+  const result = await client.updatePostReleaseId(input.post_id, {
+    release_id: input.release_id,
+    group_id: input.group_id,
+  });
+  return JSON.stringify(result, null, 2);
+}

package/src/tools/upload-media.ts

@@ -1,13 +1,21 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { mdError, mdSuccess } from '../lib/format.js';
+import { validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+type UploadMediaInput = {
+  file_path?: string;
+  base64_data?: string;
+  url?: string;
+  filename?: string;
+  content_type?: string;
+};
 
 export const uploadMediaTool = {
   name: 'upload_media',
   description:
-    'Upload an image or video file to posterly storage. Returns a URL that can be used with create_post. Supports JPEG, PNG, GIF, WebP, MP4, MOV, WebM. Images up to 10MB, videos up to 50MB.\n\n' +
-    'This writes to the user\'s media storage (counts against quota) but does NOT publish the file anywhere. Uploading is safe - it\'s the subsequent `create_post` call that publishes content, and that tool has its own confirmation requirements.\n\n' +
-    'IMPORTANT: If the user shares an image in the chat, use base64_data (not file_path) since chat-uploaded images are not on the local filesystem. Only use file_path when the user provides an actual local filesystem path - never guess paths.',
+    'Upload an image or video to posterly storage and get a URL for create_post. Supports JPEG, PNG, GIF, WebP, MP4, MOV, WebM. Images up to 10MB, videos up to 50MB. Three ways in: file_path (an explicit local path the user gave you), base64_data with filename (PREFERRED for images shared in chat, which are not on the local filesystem), or url (a public HTTPS image or video; local/private network URLs are blocked).\n\n' +
+    'This writes to the user\'s media storage (counts against quota) but does NOT publish the file anywhere. Uploading is safe - it\'s the subsequent `create_post` call that publishes content, and that tool has its own confirmation requirements. Never guess file paths. You can also pass public HTTP(S) media URLs directly to create_post/update_post; use url here when you want to upload once and reuse the returned posterly URL.',
   inputSchema: z.object({
     file_path: z
       .string()
@@ -17,38 +25,78 @@ export const uploadMediaTool = {
       .string()
       .optional()
       .describe('Base64-encoded file data. PREFERRED for images shared directly in chat - extract the image data as base64 and pass it here.'),
+    url: z
+      .string()
+      .url()
+      .optional()
+      .describe('Public HTTPS URL for the image or video to copy into posterly storage. Local/private network URLs are blocked.'),
     filename: z
       .string()
-      .describe('Filename with extension (e.g. photo.jpg, video.mp4)'),
+      .optional()
+      .describe('Filename with extension (e.g. photo.jpg, video.mp4). Required with file_path or base64_data; optional override with url.'),
     content_type: z
       .string()
       .optional()
       .describe('MIME type (auto-detected from filename if omitted)'),
   }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    upload_media_from_url: z.object({
+      url: z.string().url(),
+      filename: z.string().optional(),
+      content_type: z.string().optional(),
+    }),
+  },
 
-  async execute(
-    client: PosterlyClient,
-    input: {
-      file_path?: string;
-      base64_data?: string;
-      filename: string;
-      content_type?: string;
-    }
-  ) {
-    if (!input.file_path && !input.base64_data) {
-      return mdError('Provide either `file_path` or `base64_data`.');
-    }
-
-    const result = await client.uploadMedia({
-      filePath: input.file_path,
-      base64Data: input.base64_data,
-      filename: input.filename,
-      contentType: input.content_type,
-    });
-
-    return mdSuccess('Media uploaded', [
-      ['URL', result.url],
-      ['Storage path', result.path],
-    ], 'Use this URL as `media_url` when creating a post.');
+  async execute(client: PosterlyClient, input: UploadMediaInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'upload_media', input);
+    if (mode === 'url') return uploadFromUrl(client, args as { url: string; filename?: string; content_type?: string });
+    return uploadFile(client, args as UploadMediaInput & { filename: string });
   },
 };
+
+async function uploadFile(
+  client: PosterlyClient,
+  input: {
+    file_path?: string;
+    base64_data?: string;
+    filename: string;
+    content_type?: string;
+  },
+): Promise<string> {
+  if (!input.file_path && !input.base64_data) {
+    return mdError('Provide either `file_path` or `base64_data`.');
+  }
+
+  const result = await client.uploadMedia({
+    filePath: input.file_path,
+    base64Data: input.base64_data,
+    filename: input.filename,
+    contentType: input.content_type,
+  });
+
+  return mdSuccess('Media uploaded', [
+    ['URL', result.url],
+    ['Storage path', result.path],
+  ], 'Use this URL as `media_url` when creating a post.');
+}
+
+async function uploadFromUrl(
+  client: PosterlyClient,
+  input: { url: string; filename?: string; content_type?: string },
+): Promise<string> {
+  const result = await client.uploadMediaFromUrl({
+    url: input.url,
+    filename: input.filename,
+    contentType: input.content_type,
+  });
+  return [
+    'Remote media uploaded successfully.',
+    `• URL: ${result.url}`,
+    `• Source URL: ${result.source_url}`,
+    `• Content type: ${result.content_type}`,
+    `• Size: ${result.size} bytes`,
+    '',
+    'Use this URL as media_url when creating a post.',
+  ].join('\n');
+}