posterly-mcp-server 0.24.0 → 0.25.0

package/README.md

@@ -108,7 +108,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.23.0` exposes 63 tools.
+`posterly-mcp-server@0.25.0` exposes 72 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
@@ -127,6 +127,11 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `get_connect_session` (poll connection progress while the user approves OAuth or enters credentials)
 - `create_api_key` (create a new API key after explicit confirmation; scopes cannot exceed the calling dashboard key)
 - `delete_api_key` (revoke a user-created API key after explicit confirmation)
+- `get_subscription` (read subscription status, tier, and cancel/pause state; requires `billing:read`)
+- `cancel_subscription` (cancel after explicit confirmation; the agent must ask for a `reason` first; requires `billing:write`)
+- `pause_subscription` (pause 30 days, one per 90-day cooldown, after confirmation; requires `billing:write`)
+- `resume_subscription` (resume a paused subscription; requires `billing:write`)
+- `downgrade_subscription` (downgrade one tier at next renewal after confirmation; requires `billing:write`)
 - `list_oauth_clients`
 - `create_oauth_client` (create a public PKCE client after explicit confirmation)
 - `update_oauth_client` (update redirect URIs/scopes after explicit confirmation)

package/dist/index.js

@@ -66,6 +66,11 @@ import { createConnectSessionTool } from './tools/create-connect-session.js';
 import { getConnectSessionTool } from './tools/get-connect-session.js';
 import { createApiKeyTool } from './tools/create-api-key.js';
 import { deleteApiKeyTool } from './tools/delete-api-key.js';
+import { getSubscriptionTool } from './tools/get-subscription.js';
+import { cancelSubscriptionTool } from './tools/cancel-subscription.js';
+import { pauseSubscriptionTool } from './tools/pause-subscription.js';
+import { resumeSubscriptionTool } from './tools/resume-subscription.js';
+import { downgradeSubscriptionTool } from './tools/downgrade-subscription.js';
 import { listOAuthClientsTool } from './tools/list-oauth-clients.js';
 import { createOAuthClientTool } from './tools/create-oauth-client.js';
 import { updateOAuthClientTool } from './tools/update-oauth-client.js';
@@ -184,6 +189,51 @@ server.tool(deleteApiKeyTool.name, deleteApiKeyTool.description, deleteApiKeyToo
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(getSubscriptionTool.name, getSubscriptionTool.description, getSubscriptionTool.inputSchema.shape, async () => {
+    try {
+        const text = await getSubscriptionTool.execute(client);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(cancelSubscriptionTool.name, cancelSubscriptionTool.description, cancelSubscriptionTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await cancelSubscriptionTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(pauseSubscriptionTool.name, pauseSubscriptionTool.description, pauseSubscriptionTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await pauseSubscriptionTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(resumeSubscriptionTool.name, resumeSubscriptionTool.description, resumeSubscriptionTool.inputSchema.shape, async () => {
+    try {
+        const text = await resumeSubscriptionTool.execute(client);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(downgradeSubscriptionTool.name, downgradeSubscriptionTool.description, downgradeSubscriptionTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await downgradeSubscriptionTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(listOAuthClientsTool.name, listOAuthClientsTool.description, listOAuthClientsTool.inputSchema.shape, async () => {
     try {
         const text = await listOAuthClientsTool.execute(client);

package/dist/lib/api-client.d.ts

@@ -237,7 +237,7 @@ export type AskSupportPayload = {
     request_human?: boolean;
     confirm_escalation?: boolean;
 };
-export type ApiKeyScope = 'accounts:read' | 'accounts:write' | 'posts:read' | 'posts:write' | 'media:write' | 'analytics:read';
+export type ApiKeyScope = 'accounts:read' | 'accounts:write' | 'posts:read' | 'posts:write' | 'media:write' | 'analytics:read' | 'billing:read' | 'billing:write';
 export type CreateApiKeyPayload = {
     name?: string;
     scopes?: ApiKeyScope[];
@@ -279,6 +279,43 @@ export type DeleteApiKeyResponse = {
         is_revoked?: boolean;
     };
 };
+export type SubscriptionTierName = 'starter' | 'pro' | 'power_user' | 'agency';
+export type SubscriptionSummary = {
+    id: string | null;
+    status: string | null;
+    tier: string | null;
+    cancel_at_period_end: boolean | null;
+    current_period_end: string | null;
+    trial_ends_at: string | null;
+    paused_at: string | null;
+    pause_resumes_at: string | null;
+    stripe_subscription_id: string | null;
+};
+export type SubscriptionSummaryResponse = {
+    subscription: SubscriptionSummary;
+};
+export type CancelSubscriptionPayload = {
+    reason: string;
+    feedback?: string;
+    immediate?: boolean;
+};
+export type CancelSubscriptionResponse = {
+    success: true;
+    immediate: boolean;
+    canceled_at: string | null;
+    cancel_at_period_end: boolean;
+};
+export type PauseSubscriptionResponse = {
+    success: true;
+    pause_resumes_at: string;
+};
+export type ResumeSubscriptionResponse = {
+    success: true;
+};
+export type DowngradeSubscriptionResponse = {
+    success: true;
+    tier: SubscriptionTierName;
+};
 export type AskSupportResponse = {
     success: boolean;
     workspace_id: string;
@@ -698,6 +735,13 @@ export declare class PosterlyClient {
     deleteApiKey(keyId: string, data: {
         confirm: true;
     }): Promise<DeleteApiKeyResponse>;
+    getSubscription(): Promise<SubscriptionSummaryResponse>;
+    cancelSubscription(data: CancelSubscriptionPayload): Promise<CancelSubscriptionResponse>;
+    pauseSubscription(): Promise<PauseSubscriptionResponse>;
+    resumeSubscription(): Promise<ResumeSubscriptionResponse>;
+    downgradeSubscription(data: {
+        tier?: SubscriptionTierName;
+    }): Promise<DowngradeSubscriptionResponse>;
     listAccounts(params?: {
         workspace_id?: string;
     }): Promise<Account[]>;

package/dist/lib/api-client.js

@@ -122,6 +122,21 @@ export class PosterlyClient {
     async deleteApiKey(keyId, data) {
         return this.request('DELETE', `/api-keys/${encodeURIComponent(keyId)}`, data);
     }
+    async getSubscription() {
+        return this.request('GET', '/subscription');
+    }
+    async cancelSubscription(data) {
+        return this.request('POST', '/subscription/cancel', data);
+    }
+    async pauseSubscription() {
+        return this.request('POST', '/subscription/pause', {});
+    }
+    async resumeSubscription() {
+        return this.request('POST', '/subscription/resume', {});
+    }
+    async downgradeSubscription(data) {
+        return this.request('POST', '/subscription/downgrade', data);
+    }
     async listAccounts(params) {
         const searchParams = new URLSearchParams();
         if (params?.workspace_id)

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.24.0";
+export declare const POSTERLY_MCP_VERSION = "0.25.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.24.0';
+export const POSTERLY_MCP_VERSION = '0.25.0';

package/dist/tools/cancel-subscription.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+declare const CANCELLATION_REASONS: readonly ["too_expensive", "not_using", "missing_features", "technical_issues", "switching_service", "temporary_break", "other"];
+export declare const cancelSubscriptionTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        reason: z.ZodEnum<["too_expensive", "not_using", "missing_features", "technical_issues", "switching_service", "temporary_break", "other"]>;
+        feedback: z.ZodOptional<z.ZodString>;
+        immediate: z.ZodOptional<z.ZodBoolean>;
+        confirm: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        confirm: true;
+        reason: "too_expensive" | "not_using" | "missing_features" | "technical_issues" | "switching_service" | "temporary_break" | "other";
+        feedback?: string | undefined;
+        immediate?: boolean | undefined;
+    }, {
+        confirm: true;
+        reason: "too_expensive" | "not_using" | "missing_features" | "technical_issues" | "switching_service" | "temporary_break" | "other";
+        feedback?: string | undefined;
+        immediate?: boolean | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        reason: (typeof CANCELLATION_REASONS)[number];
+        feedback?: string;
+        immediate?: boolean;
+        confirm: true;
+    }): Promise<string>;
+};
+export {};

package/dist/tools/cancel-subscription.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+// Mirrors CANCELLATION_REASONS in the main app (lib/subscription-reasons.ts).
+// Kept in sync manually because the npm package cannot import from the app.
+const CANCELLATION_REASONS = [
+    'too_expensive',
+    'not_using',
+    'missing_features',
+    'technical_issues',
+    'switching_service',
+    'temporary_break',
+    'other',
+];
+function formatCanceled(result) {
+    return [
+        mdTitle(result.immediate ? 'Subscription cancelled immediately' : 'Subscription set to cancel at period end'),
+        mdSection('Details', mdKeyValue([
+            ['Immediate', result.immediate ? 'yes' : 'no'],
+            ['Cancel at period end', result.cancel_at_period_end ? 'yes' : 'no'],
+            ['Canceled at', result.canceled_at || 'at end of current period'],
+        ])),
+    ].join('\n\n');
+}
+export const cancelSubscriptionTool = {
+    name: 'cancel_subscription',
+    description: "Cancel the authenticated user's posterly subscription. DESTRUCTIVE billing action; requires the billing:write scope. ALWAYS ask the user why they are cancelling FIRST and pass their answer as `reason` (one of the allowed values). By default the subscription is set to cancel at the end of the current period; pass immediate=true only if the user explicitly wants it cancelled right now. Only call after the user explicitly confirms.",
+    inputSchema: z.object({
+        reason: z.enum(CANCELLATION_REASONS).describe('Why the user is cancelling. Ask the user before calling; do not guess.'),
+        feedback: z.string().max(2000).optional().describe('Optional free-text detail the user gave about why they are cancelling.'),
+        immediate: z.boolean().optional().describe('Cancel immediately instead of at period end. Defaults to false (cancel at period end).'),
+        confirm: z.literal(true).describe('Must be true after the user explicitly confirms the cancellation.'),
+    }),
+    async execute(client, input) {
+        const result = await client.cancelSubscription({
+            reason: input.reason,
+            feedback: input.feedback,
+            immediate: input.immediate === true,
+        });
+        return formatCanceled(result);
+    },
+};

package/dist/tools/create-api-key.d.ts

@@ -5,7 +5,7 @@ export declare const createApiKeyTool: {
     description: string;
     inputSchema: z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
-        scopes: z.ZodOptional<z.ZodArray<z.ZodEnum<["accounts:read", "accounts:write", "posts:read", "posts:write", "media:write", "analytics:read"]>, "many">>;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodEnum<["accounts:read", "accounts:write", "posts:read", "posts:write", "media:write", "analytics:read", "billing:read", "billing:write"]>, "many">>;
         workspace_id: z.ZodOptional<z.ZodString>;
         expires_in_days: z.ZodOptional<z.ZodNumber>;
         confirm: z.ZodLiteral<true>;
@@ -13,13 +13,13 @@ export declare const createApiKeyTool: {
         confirm: true;
         workspace_id?: string | undefined;
         name?: string | undefined;
-        scopes?: ("accounts:read" | "accounts:write" | "posts:read" | "posts:write" | "media:write" | "analytics:read")[] | undefined;
+        scopes?: ("accounts:read" | "accounts:write" | "posts:read" | "posts:write" | "media:write" | "analytics:read" | "billing:read" | "billing:write")[] | undefined;
         expires_in_days?: number | undefined;
     }, {
         confirm: true;
         workspace_id?: string | undefined;
         name?: string | undefined;
-        scopes?: ("accounts:read" | "accounts:write" | "posts:read" | "posts:write" | "media:write" | "analytics:read")[] | undefined;
+        scopes?: ("accounts:read" | "accounts:write" | "posts:read" | "posts:write" | "media:write" | "analytics:read" | "billing:read" | "billing:write")[] | undefined;
         expires_in_days?: number | undefined;
     }>;
     execute(client: PosterlyClient, input: CreateApiKeyPayload): Promise<string>;

package/dist/tools/create-api-key.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { code, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
-const scopeSchema = z.enum(['accounts:read', 'accounts:write', 'posts:read', 'posts:write', 'media:write', 'analytics:read']);
+const scopeSchema = z.enum(['accounts:read', 'accounts:write', 'posts:read', 'posts:write', 'media:write', 'analytics:read', 'billing:read', 'billing:write']);
 function formatCreatedApiKey(result) {
     const key = result.api_key;
     return [
@@ -23,7 +23,7 @@ export const createApiKeyTool = {
     description: 'Create a new Posterly API key for the authenticated user. SECRET-CREATING WRITE: only use after explicit user confirmation. The new key can only request scopes already present on the calling dashboard-created API key; OAuth and managed assistant tokens cannot mint keys.',
     inputSchema: z.object({
         name: z.string().trim().min(1).max(120).optional().describe('Human-readable key name.'),
-        scopes: z.array(scopeSchema).min(1).max(6).optional().describe('Scopes for the new key. Omit to copy the calling key scopes. Cannot exceed the calling key scopes.'),
+        scopes: z.array(scopeSchema).min(1).max(8).optional().describe('Scopes for the new key. Omit to copy the calling key scopes. Cannot exceed the calling key scopes. billing:read and billing:write allow managing the posterly subscription (cancel/pause/resume/downgrade).'),
         workspace_id: z.string().trim().min(1).optional().describe('Optional workspace restriction. Workspace-scoped calling keys cannot create keys outside their workspace.'),
         expires_in_days: z.number().int().min(1).max(365).optional().describe('Optional expiry from now, up to 365 days. Omit for no expiry.'),
         confirm: z.literal(true).describe('Must be true after the user explicitly confirms that a new secret API key should be created.'),

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

@@ -117,6 +117,7 @@ export declare const platformSettingsSchema: z.ZodObject<{
     allow_stitch: z.ZodOptional<z.ZodBoolean>;
     title: z.ZodOptional<z.ZodString>;
     media_type: z.ZodOptional<z.ZodString>;
+    video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
     is_commercial_content: z.ZodOptional<z.ZodBoolean>;
     is_your_brand: z.ZodOptional<z.ZodBoolean>;
     is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -193,6 +194,7 @@ export declare const platformSettingsSchema: z.ZodObject<{
     allow_stitch: z.ZodOptional<z.ZodBoolean>;
     title: z.ZodOptional<z.ZodString>;
     media_type: z.ZodOptional<z.ZodString>;
+    video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
     is_commercial_content: z.ZodOptional<z.ZodBoolean>;
     is_your_brand: z.ZodOptional<z.ZodBoolean>;
     is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -269,6 +271,7 @@ export declare const platformSettingsSchema: z.ZodObject<{
     allow_stitch: z.ZodOptional<z.ZodBoolean>;
     title: z.ZodOptional<z.ZodString>;
     media_type: z.ZodOptional<z.ZodString>;
+    video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
     is_commercial_content: z.ZodOptional<z.ZodBoolean>;
     is_your_brand: z.ZodOptional<z.ZodBoolean>;
     is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -430,6 +433,7 @@ export declare const createPostPayloadInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -506,6 +510,7 @@ export declare const createPostPayloadInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -582,6 +587,7 @@ export declare const createPostPayloadInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -691,6 +697,7 @@ export declare const createPostPayloadInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -799,6 +806,7 @@ export declare const createPostPayloadInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -961,6 +969,7 @@ export declare const createPostInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -1037,6 +1046,7 @@ export declare const createPostInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -1113,6 +1123,7 @@ export declare const createPostInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -1225,6 +1236,7 @@ export declare const createPostInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -1334,6 +1346,7 @@ export declare const createPostInputSchema: z.ZodObject<{
         allow_stitch: z.ZodOptional<z.ZodBoolean>;
         title: z.ZodOptional<z.ZodString>;
         media_type: z.ZodOptional<z.ZodString>;
+        video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
         is_commercial_content: z.ZodOptional<z.ZodBoolean>;
         is_your_brand: z.ZodOptional<z.ZodBoolean>;
         is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -1502,6 +1515,7 @@ export declare const createPostTool: {
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
             media_type: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -1578,6 +1592,7 @@ export declare const createPostTool: {
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
             media_type: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -1654,6 +1669,7 @@ export declare const createPostTool: {
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
             media_type: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -1766,6 +1782,7 @@ export declare const createPostTool: {
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
             media_type: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -1875,6 +1892,7 @@ export declare const createPostTool: {
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
             media_type: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;

package/dist/tools/create-post.js

@@ -53,6 +53,7 @@ export const platformSettingsSchema = z.object({
     allow_stitch: z.boolean().optional(),
     title: z.string().optional(),
     media_type: z.string().optional(), // TikTok: 'PHOTO' forces a photo slideshow; image media is auto-detected when omitted
+    video_cover_timestamp_ms: z.number().nonnegative().optional(), // TikTok: millisecond timestamp of the video frame to use as the cover (direct post only)
     is_commercial_content: z.boolean().optional(),
     is_your_brand: z.boolean().optional(),
     is_branded_content: z.boolean().optional(),
@@ -106,7 +107,7 @@ export const createPostPayloadInputSchema = z.object({
     post_type: z
         .string()
         .optional()
-        .describe('Post type: text, image, video, carousel, reel, story. Auto-set to x_thread/threads_thread when `thread_posts` is provided. For TikTok you can omit it: image media auto-detects as a photo slideshow (use "carousel" for 2 or more images, or "image" for one), while a single video posts as a video.'),
+        .describe('Optional post type: text, image, video, carousel, reel, story, story_series, document, photo, cover_photo, x_thread, or threads_thread. Omit it for auto-detection from media. For TikTok photo posts, use photo/image/carousel or omit it; for Facebook cover photos, use cover_photo or platform_settings.post_type.'),
     thread_posts: z
         .array(z.string())
         .optional()

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

@@ -132,6 +132,7 @@ export declare const createPostsBatchTool: {
                 allow_stitch: z.ZodOptional<z.ZodBoolean>;
                 title: z.ZodOptional<z.ZodString>;
                 media_type: z.ZodOptional<z.ZodString>;
+                video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
                 is_commercial_content: z.ZodOptional<z.ZodBoolean>;
                 is_your_brand: z.ZodOptional<z.ZodBoolean>;
                 is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -208,6 +209,7 @@ export declare const createPostsBatchTool: {
                 allow_stitch: z.ZodOptional<z.ZodBoolean>;
                 title: z.ZodOptional<z.ZodString>;
                 media_type: z.ZodOptional<z.ZodString>;
+                video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
                 is_commercial_content: z.ZodOptional<z.ZodBoolean>;
                 is_your_brand: z.ZodOptional<z.ZodBoolean>;
                 is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -284,6 +286,7 @@ export declare const createPostsBatchTool: {
                 allow_stitch: z.ZodOptional<z.ZodBoolean>;
                 title: z.ZodOptional<z.ZodString>;
                 media_type: z.ZodOptional<z.ZodString>;
+                video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
                 is_commercial_content: z.ZodOptional<z.ZodBoolean>;
                 is_your_brand: z.ZodOptional<z.ZodBoolean>;
                 is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -393,6 +396,7 @@ export declare const createPostsBatchTool: {
                 allow_stitch: z.ZodOptional<z.ZodBoolean>;
                 title: z.ZodOptional<z.ZodString>;
                 media_type: z.ZodOptional<z.ZodString>;
+                video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
                 is_commercial_content: z.ZodOptional<z.ZodBoolean>;
                 is_your_brand: z.ZodOptional<z.ZodBoolean>;
                 is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -501,6 +505,7 @@ export declare const createPostsBatchTool: {
                 allow_stitch: z.ZodOptional<z.ZodBoolean>;
                 title: z.ZodOptional<z.ZodString>;
                 media_type: z.ZodOptional<z.ZodString>;
+                video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
                 is_commercial_content: z.ZodOptional<z.ZodBoolean>;
                 is_your_brand: z.ZodOptional<z.ZodBoolean>;
                 is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -613,6 +618,7 @@ export declare const createPostsBatchTool: {
                 allow_stitch: z.ZodOptional<z.ZodBoolean>;
                 title: z.ZodOptional<z.ZodString>;
                 media_type: z.ZodOptional<z.ZodString>;
+                video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
                 is_commercial_content: z.ZodOptional<z.ZodBoolean>;
                 is_your_brand: z.ZodOptional<z.ZodBoolean>;
                 is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -724,6 +730,7 @@ export declare const createPostsBatchTool: {
                 allow_stitch: z.ZodOptional<z.ZodBoolean>;
                 title: z.ZodOptional<z.ZodString>;
                 media_type: z.ZodOptional<z.ZodString>;
+                video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
                 is_commercial_content: z.ZodOptional<z.ZodBoolean>;
                 is_your_brand: z.ZodOptional<z.ZodBoolean>;
                 is_branded_content: z.ZodOptional<z.ZodBoolean>;

package/dist/tools/downgrade-subscription.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { PosterlyClient, SubscriptionTierName } from '../lib/api-client.js';
+export declare const downgradeSubscriptionTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        tier: z.ZodOptional<z.ZodEnum<["starter", "pro", "power_user", "agency"]>>;
+        confirm: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        confirm: true;
+        tier?: "starter" | "pro" | "power_user" | "agency" | undefined;
+    }, {
+        confirm: true;
+        tier?: "starter" | "pro" | "power_user" | "agency" | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        tier?: SubscriptionTierName;
+        confirm: true;
+    }): Promise<string>;
+};

package/dist/tools/downgrade-subscription.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+const TIER_VALUES = ['starter', 'pro', 'power_user', 'agency'];
+function formatDowngraded(result) {
+    return [
+        mdTitle('Subscription downgrade scheduled'),
+        mdSection('Details', mdKeyValue([
+            ['New tier at next renewal', result.tier],
+        ])),
+    ].join('\n\n');
+}
+export const downgradeSubscriptionTool = {
+    name: 'downgrade_subscription',
+    description: "Downgrade the authenticated user's posterly subscription one tier (or to an explicit lower `tier`) at the next renewal with no proration. Billing action; requires the billing:write scope. Only call after the user explicitly confirms.",
+    inputSchema: z.object({
+        tier: z.enum(TIER_VALUES).optional().describe('Optional explicit target tier. Omit to drop one tier automatically.'),
+        confirm: z.literal(true).describe('Must be true after the user explicitly confirms the downgrade.'),
+    }),
+    async execute(client, input) {
+        const result = await client.downgradeSubscription({ tier: input.tier });
+        return formatDowngraded(result);
+    },
+};

package/dist/tools/get-subscription.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getSubscriptionTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    execute(client: PosterlyClient): Promise<string>;
+};

package/dist/tools/get-subscription.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { formatDateTime, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+function formatSubscription(result) {
+    const sub = result.subscription;
+    return [
+        mdTitle('posterly subscription'),
+        mdSection('Details', mdKeyValue([
+            ['Status', sub.status || 'unknown'],
+            ['Tier', sub.tier || 'unknown'],
+            ['Cancel at period end', sub.cancel_at_period_end ? 'yes' : 'no'],
+            ['Current period end', sub.current_period_end ? formatDateTime(sub.current_period_end) : 'n/a'],
+            ['Trial ends', sub.trial_ends_at ? formatDateTime(sub.trial_ends_at) : 'n/a'],
+            ['Paused at', sub.paused_at ? formatDateTime(sub.paused_at) : 'n/a'],
+            ['Pause resumes at', sub.pause_resumes_at ? formatDateTime(sub.pause_resumes_at) : 'n/a'],
+        ])),
+    ].join('\n\n');
+}
+export const getSubscriptionTool = {
+    name: 'get_subscription',
+    description: "Get the authenticated user's posterly subscription: status, tier, cancel-at-period-end, current period end, trial end, and pause state. Read-only. Requires the billing:read scope.",
+    inputSchema: z.object({}),
+    async execute(client) {
+        const result = await client.getSubscription();
+        return formatSubscription(result);
+    },
+};

package/dist/tools/pause-subscription.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const pauseSubscriptionTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        confirm: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        confirm: true;
+    }, {
+        confirm: true;
+    }>;
+    execute(client: PosterlyClient, _input: {
+        confirm: true;
+    }): Promise<string>;
+};

package/dist/tools/pause-subscription.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { formatDateTime, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+function formatPaused(result) {
+    return [
+        mdTitle('Subscription paused'),
+        mdSection('Details', mdKeyValue([
+            ['Resumes at', result.pause_resumes_at ? formatDateTime(result.pause_resumes_at) : 'n/a'],
+        ])),
+    ].join('\n\n');
+}
+export const pauseSubscriptionTool = {
+    name: 'pause_subscription',
+    description: "Pause the authenticated user's posterly subscription for 30 days (one pause allowed per 90-day cooldown). Billing action; requires the billing:write scope. Only call after the user explicitly confirms.",
+    inputSchema: z.object({
+        confirm: z.literal(true).describe('Must be true after the user explicitly confirms pausing the subscription.'),
+    }),
+    async execute(client, _input) {
+        const result = await client.pauseSubscription();
+        return formatPaused(result);
+    },
+};

package/dist/tools/resume-subscription.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const resumeSubscriptionTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    execute(client: PosterlyClient): Promise<string>;
+};

package/dist/tools/resume-subscription.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { mdTitle } from '../lib/format.js';
+export const resumeSubscriptionTool = {
+    name: 'resume_subscription',
+    description: "Resume the authenticated user's paused posterly subscription, restoring active billing. Requires the billing:write scope.",
+    inputSchema: z.object({}),
+    async execute(client) {
+        await client.resumeSubscription();
+        return mdTitle('Subscription resumed', 'Billing has been restored to active.');
+    },
+};

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

@@ -116,6 +116,7 @@ declare const platformSettingsSchema: z.ZodObject<{
     allow_duet: z.ZodOptional<z.ZodBoolean>;
     allow_stitch: z.ZodOptional<z.ZodBoolean>;
     title: z.ZodOptional<z.ZodString>;
+    video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
     is_commercial_content: z.ZodOptional<z.ZodBoolean>;
     is_your_brand: z.ZodOptional<z.ZodBoolean>;
     is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -191,6 +192,7 @@ declare const platformSettingsSchema: z.ZodObject<{
     allow_duet: z.ZodOptional<z.ZodBoolean>;
     allow_stitch: z.ZodOptional<z.ZodBoolean>;
     title: z.ZodOptional<z.ZodString>;
+    video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
     is_commercial_content: z.ZodOptional<z.ZodBoolean>;
     is_your_brand: z.ZodOptional<z.ZodBoolean>;
     is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -266,6 +268,7 @@ declare const platformSettingsSchema: z.ZodObject<{
     allow_duet: z.ZodOptional<z.ZodBoolean>;
     allow_stitch: z.ZodOptional<z.ZodBoolean>;
     title: z.ZodOptional<z.ZodString>;
+    video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
     is_commercial_content: z.ZodOptional<z.ZodBoolean>;
     is_your_brand: z.ZodOptional<z.ZodBoolean>;
     is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -426,6 +429,7 @@ export declare const updatePostTool: {
             allow_duet: z.ZodOptional<z.ZodBoolean>;
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -501,6 +505,7 @@ export declare const updatePostTool: {
             allow_duet: z.ZodOptional<z.ZodBoolean>;
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -576,6 +581,7 @@ export declare const updatePostTool: {
             allow_duet: z.ZodOptional<z.ZodBoolean>;
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -681,6 +687,7 @@ export declare const updatePostTool: {
             allow_duet: z.ZodOptional<z.ZodBoolean>;
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;
@@ -785,6 +792,7 @@ export declare const updatePostTool: {
             allow_duet: z.ZodOptional<z.ZodBoolean>;
             allow_stitch: z.ZodOptional<z.ZodBoolean>;
             title: z.ZodOptional<z.ZodString>;
+            video_cover_timestamp_ms: z.ZodOptional<z.ZodNumber>;
             is_commercial_content: z.ZodOptional<z.ZodBoolean>;
             is_your_brand: z.ZodOptional<z.ZodBoolean>;
             is_branded_content: z.ZodOptional<z.ZodBoolean>;

package/dist/tools/update-post.js

@@ -40,6 +40,7 @@ const platformSettingsSchema = z.object({
     allow_duet: z.boolean().optional(),
     allow_stitch: z.boolean().optional(),
     title: z.string().optional(),
+    video_cover_timestamp_ms: z.number().nonnegative().optional(), // TikTok: millisecond timestamp of the video frame to use as the cover (direct post only)
     is_commercial_content: z.boolean().optional(),
     is_your_brand: z.boolean().optional(),
     is_branded_content: z.boolean().optional(),
@@ -81,7 +82,7 @@ export const updatePostTool = {
         post_type: z
             .string()
             .optional()
-            .describe('New post type: text, image, video, carousel, reel, story'),
+            .describe('New post type: text, image, video, carousel, reel, story, story_series, document, photo, or cover_photo'),
         instagram_settings: instagramSettingsSchema
             .optional()
             .describe('Instagram-specific updates: post_type, collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_thumb_offset.'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "MCP server for posterly: schedule and publish social media posts across 11 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",
   "homepage": "https://www.poster.ly/mcp",

package/src/index.ts

@@ -67,6 +67,11 @@ import { createConnectSessionTool } from './tools/create-connect-session.js';
 import { getConnectSessionTool } from './tools/get-connect-session.js';
 import { createApiKeyTool } from './tools/create-api-key.js';
 import { deleteApiKeyTool } from './tools/delete-api-key.js';
+import { getSubscriptionTool } from './tools/get-subscription.js';
+import { cancelSubscriptionTool } from './tools/cancel-subscription.js';
+import { pauseSubscriptionTool } from './tools/pause-subscription.js';
+import { resumeSubscriptionTool } from './tools/resume-subscription.js';
+import { downgradeSubscriptionTool } from './tools/downgrade-subscription.js';
 import { listOAuthClientsTool } from './tools/list-oauth-clients.js';
 import { createOAuthClientTool } from './tools/create-oauth-client.js';
 import { updateOAuthClientTool } from './tools/update-oauth-client.js';
@@ -248,6 +253,76 @@ server.tool(
   }
 );
 
+server.tool(
+  getSubscriptionTool.name,
+  getSubscriptionTool.description,
+  getSubscriptionTool.inputSchema.shape,
+  async () => {
+    try {
+      const text = await getSubscriptionTool.execute(client);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  cancelSubscriptionTool.name,
+  cancelSubscriptionTool.description,
+  cancelSubscriptionTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await cancelSubscriptionTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  pauseSubscriptionTool.name,
+  pauseSubscriptionTool.description,
+  pauseSubscriptionTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await pauseSubscriptionTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  resumeSubscriptionTool.name,
+  resumeSubscriptionTool.description,
+  resumeSubscriptionTool.inputSchema.shape,
+  async () => {
+    try {
+      const text = await resumeSubscriptionTool.execute(client);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  downgradeSubscriptionTool.name,
+  downgradeSubscriptionTool.description,
+  downgradeSubscriptionTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await downgradeSubscriptionTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 server.tool(
   listOAuthClientsTool.name,
   listOAuthClientsTool.description,

package/src/lib/api-client.ts

@@ -255,7 +255,9 @@ export type ApiKeyScope =
   | 'posts:read'
   | 'posts:write'
   | 'media:write'
-  | 'analytics:read';
+  | 'analytics:read'
+  | 'billing:read'
+  | 'billing:write';
 
 export type CreateApiKeyPayload = {
   name?: string;
@@ -301,6 +303,51 @@ export type DeleteApiKeyResponse = {
   };
 };
 
+export type SubscriptionTierName = 'starter' | 'pro' | 'power_user' | 'agency';
+
+export type SubscriptionSummary = {
+  id: string | null;
+  status: string | null;
+  tier: string | null;
+  cancel_at_period_end: boolean | null;
+  current_period_end: string | null;
+  trial_ends_at: string | null;
+  paused_at: string | null;
+  pause_resumes_at: string | null;
+  stripe_subscription_id: string | null;
+};
+
+export type SubscriptionSummaryResponse = {
+  subscription: SubscriptionSummary;
+};
+
+export type CancelSubscriptionPayload = {
+  reason: string;
+  feedback?: string;
+  immediate?: boolean;
+};
+
+export type CancelSubscriptionResponse = {
+  success: true;
+  immediate: boolean;
+  canceled_at: string | null;
+  cancel_at_period_end: boolean;
+};
+
+export type PauseSubscriptionResponse = {
+  success: true;
+  pause_resumes_at: string;
+};
+
+export type ResumeSubscriptionResponse = {
+  success: true;
+};
+
+export type DowngradeSubscriptionResponse = {
+  success: true;
+  tier: SubscriptionTierName;
+};
+
 export type AskSupportResponse = {
   success: boolean;
   workspace_id: string;
@@ -862,6 +909,26 @@ export class PosterlyClient {
     return this.request('DELETE', `/api-keys/${encodeURIComponent(keyId)}`, data);
   }
 
+  async getSubscription(): Promise<SubscriptionSummaryResponse> {
+    return this.request('GET', '/subscription');
+  }
+
+  async cancelSubscription(data: CancelSubscriptionPayload): Promise<CancelSubscriptionResponse> {
+    return this.request('POST', '/subscription/cancel', data);
+  }
+
+  async pauseSubscription(): Promise<PauseSubscriptionResponse> {
+    return this.request('POST', '/subscription/pause', {});
+  }
+
+  async resumeSubscription(): Promise<ResumeSubscriptionResponse> {
+    return this.request('POST', '/subscription/resume', {});
+  }
+
+  async downgradeSubscription(data: { tier?: SubscriptionTierName }): Promise<DowngradeSubscriptionResponse> {
+    return this.request('POST', '/subscription/downgrade', data);
+  }
+
   async listAccounts(params?: { workspace_id?: string }): Promise<Account[]> {
     const searchParams = new URLSearchParams();
     if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);

package/src/lib/version.ts

@@ -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.24.0';
+export const POSTERLY_MCP_VERSION = '0.25.0';

package/src/tools/cancel-subscription.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import type { CancelSubscriptionResponse, PosterlyClient } from '../lib/api-client.js';
+import { mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+
+// Mirrors CANCELLATION_REASONS in the main app (lib/subscription-reasons.ts).
+// Kept in sync manually because the npm package cannot import from the app.
+const CANCELLATION_REASONS = [
+  'too_expensive',
+  'not_using',
+  'missing_features',
+  'technical_issues',
+  'switching_service',
+  'temporary_break',
+  'other',
+] as const;
+
+function formatCanceled(result: CancelSubscriptionResponse): string {
+  return [
+    mdTitle(result.immediate ? 'Subscription cancelled immediately' : 'Subscription set to cancel at period end'),
+    mdSection('Details', mdKeyValue([
+      ['Immediate', result.immediate ? 'yes' : 'no'],
+      ['Cancel at period end', result.cancel_at_period_end ? 'yes' : 'no'],
+      ['Canceled at', result.canceled_at || 'at end of current period'],
+    ])),
+  ].join('\n\n');
+}
+
+export const cancelSubscriptionTool = {
+  name: 'cancel_subscription',
+  description:
+    "Cancel the authenticated user's posterly subscription. DESTRUCTIVE billing action; requires the billing:write scope. ALWAYS ask the user why they are cancelling FIRST and pass their answer as `reason` (one of the allowed values). By default the subscription is set to cancel at the end of the current period; pass immediate=true only if the user explicitly wants it cancelled right now. Only call after the user explicitly confirms.",
+  inputSchema: z.object({
+    reason: z.enum(CANCELLATION_REASONS).describe('Why the user is cancelling. Ask the user before calling; do not guess.'),
+    feedback: z.string().max(2000).optional().describe('Optional free-text detail the user gave about why they are cancelling.'),
+    immediate: z.boolean().optional().describe('Cancel immediately instead of at period end. Defaults to false (cancel at period end).'),
+    confirm: z.literal(true).describe('Must be true after the user explicitly confirms the cancellation.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { reason: (typeof CANCELLATION_REASONS)[number]; feedback?: string; immediate?: boolean; confirm: true },
+  ) {
+    const result = await client.cancelSubscription({
+      reason: input.reason,
+      feedback: input.feedback,
+      immediate: input.immediate === true,
+    });
+    return formatCanceled(result);
+  },
+};

package/src/tools/create-api-key.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import type { CreateApiKeyPayload, CreateApiKeyResponse, PosterlyClient } from '../lib/api-client.js';
 import { code, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
 
-const scopeSchema = z.enum(['accounts:read', 'accounts:write', 'posts:read', 'posts:write', 'media:write', 'analytics:read']);
+const scopeSchema = z.enum(['accounts:read', 'accounts:write', 'posts:read', 'posts:write', 'media:write', 'analytics:read', 'billing:read', 'billing:write']);
 
 function formatCreatedApiKey(result: CreateApiKeyResponse): string {
   const key = result.api_key;
@@ -28,7 +28,7 @@ export const createApiKeyTool = {
     'Create a new Posterly API key for the authenticated user. SECRET-CREATING WRITE: only use after explicit user confirmation. The new key can only request scopes already present on the calling dashboard-created API key; OAuth and managed assistant tokens cannot mint keys.',
   inputSchema: z.object({
     name: z.string().trim().min(1).max(120).optional().describe('Human-readable key name.'),
-    scopes: z.array(scopeSchema).min(1).max(6).optional().describe('Scopes for the new key. Omit to copy the calling key scopes. Cannot exceed the calling key scopes.'),
+    scopes: z.array(scopeSchema).min(1).max(8).optional().describe('Scopes for the new key. Omit to copy the calling key scopes. Cannot exceed the calling key scopes. billing:read and billing:write allow managing the posterly subscription (cancel/pause/resume/downgrade).'),
     workspace_id: z.string().trim().min(1).optional().describe('Optional workspace restriction. Workspace-scoped calling keys cannot create keys outside their workspace.'),
     expires_in_days: z.number().int().min(1).max(365).optional().describe('Optional expiry from now, up to 365 days. Omit for no expiry.'),
     confirm: z.literal(true).describe('Must be true after the user explicitly confirms that a new secret API key should be created.'),

package/src/tools/create-post.ts

@@ -56,6 +56,7 @@ export const platformSettingsSchema = z.object({
   allow_stitch: z.boolean().optional(),
   title: z.string().optional(),
   media_type: z.string().optional(), // TikTok: 'PHOTO' forces a photo slideshow; image media is auto-detected when omitted
+  video_cover_timestamp_ms: z.number().nonnegative().optional(), // TikTok: millisecond timestamp of the video frame to use as the cover (direct post only)
   is_commercial_content: z.boolean().optional(),
   is_your_brand: z.boolean().optional(),
   is_branded_content: z.boolean().optional(),
@@ -110,7 +111,7 @@ export const createPostPayloadInputSchema = z.object({
   post_type: z
     .string()
     .optional()
-    .describe('Post type: text, image, video, carousel, reel, story. Auto-set to x_thread/threads_thread when `thread_posts` is provided. For TikTok you can omit it: image media auto-detects as a photo slideshow (use "carousel" for 2 or more images, or "image" for one), while a single video posts as a video.'),
+    .describe('Optional post type: text, image, video, carousel, reel, story, story_series, document, photo, cover_photo, x_thread, or threads_thread. Omit it for auto-detection from media. For TikTok photo posts, use photo/image/carousel or omit it; for Facebook cover photos, use cover_photo or platform_settings.post_type.'),
   thread_posts: z
     .array(z.string())
     .optional()

package/src/tools/downgrade-subscription.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import type { DowngradeSubscriptionResponse, PosterlyClient, SubscriptionTierName } from '../lib/api-client.js';
+import { mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+
+const TIER_VALUES = ['starter', 'pro', 'power_user', 'agency'] as const;
+
+function formatDowngraded(result: DowngradeSubscriptionResponse): string {
+  return [
+    mdTitle('Subscription downgrade scheduled'),
+    mdSection('Details', mdKeyValue([
+      ['New tier at next renewal', result.tier],
+    ])),
+  ].join('\n\n');
+}
+
+export const downgradeSubscriptionTool = {
+  name: 'downgrade_subscription',
+  description:
+    "Downgrade the authenticated user's posterly subscription one tier (or to an explicit lower `tier`) at the next renewal with no proration. Billing action; requires the billing:write scope. Only call after the user explicitly confirms.",
+  inputSchema: z.object({
+    tier: z.enum(TIER_VALUES).optional().describe('Optional explicit target tier. Omit to drop one tier automatically.'),
+    confirm: z.literal(true).describe('Must be true after the user explicitly confirms the downgrade.'),
+  }),
+
+  async execute(client: PosterlyClient, input: { tier?: SubscriptionTierName; confirm: true }) {
+    const result = await client.downgradeSubscription({ tier: input.tier });
+    return formatDowngraded(result);
+  },
+};

package/src/tools/get-subscription.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { PosterlyClient, SubscriptionSummaryResponse } from '../lib/api-client.js';
+import { formatDateTime, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+
+function formatSubscription(result: SubscriptionSummaryResponse): string {
+  const sub = result.subscription;
+  return [
+    mdTitle('posterly subscription'),
+    mdSection('Details', mdKeyValue([
+      ['Status', sub.status || 'unknown'],
+      ['Tier', sub.tier || 'unknown'],
+      ['Cancel at period end', sub.cancel_at_period_end ? 'yes' : 'no'],
+      ['Current period end', sub.current_period_end ? formatDateTime(sub.current_period_end) : 'n/a'],
+      ['Trial ends', sub.trial_ends_at ? formatDateTime(sub.trial_ends_at) : 'n/a'],
+      ['Paused at', sub.paused_at ? formatDateTime(sub.paused_at) : 'n/a'],
+      ['Pause resumes at', sub.pause_resumes_at ? formatDateTime(sub.pause_resumes_at) : 'n/a'],
+    ])),
+  ].join('\n\n');
+}
+
+export const getSubscriptionTool = {
+  name: 'get_subscription',
+  description:
+    "Get the authenticated user's posterly subscription: status, tier, cancel-at-period-end, current period end, trial end, and pause state. Read-only. Requires the billing:read scope.",
+  inputSchema: z.object({}),
+
+  async execute(client: PosterlyClient) {
+    const result = await client.getSubscription();
+    return formatSubscription(result);
+  },
+};

package/src/tools/pause-subscription.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import type { PauseSubscriptionResponse, PosterlyClient } from '../lib/api-client.js';
+import { formatDateTime, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+
+function formatPaused(result: PauseSubscriptionResponse): string {
+  return [
+    mdTitle('Subscription paused'),
+    mdSection('Details', mdKeyValue([
+      ['Resumes at', result.pause_resumes_at ? formatDateTime(result.pause_resumes_at) : 'n/a'],
+    ])),
+  ].join('\n\n');
+}
+
+export const pauseSubscriptionTool = {
+  name: 'pause_subscription',
+  description:
+    "Pause the authenticated user's posterly subscription for 30 days (one pause allowed per 90-day cooldown). Billing action; requires the billing:write scope. Only call after the user explicitly confirms.",
+  inputSchema: z.object({
+    confirm: z.literal(true).describe('Must be true after the user explicitly confirms pausing the subscription.'),
+  }),
+
+  async execute(client: PosterlyClient, _input: { confirm: true }) {
+    const result = await client.pauseSubscription();
+    return formatPaused(result);
+  },
+};

package/src/tools/resume-subscription.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { mdTitle } from '../lib/format.js';
+
+export const resumeSubscriptionTool = {
+  name: 'resume_subscription',
+  description:
+    "Resume the authenticated user's paused posterly subscription, restoring active billing. Requires the billing:write scope.",
+  inputSchema: z.object({}),
+
+  async execute(client: PosterlyClient) {
+    await client.resumeSubscription();
+    return mdTitle('Subscription resumed', 'Billing has been restored to active.');
+  },
+};

package/src/tools/update-post.ts

@@ -43,6 +43,7 @@ const platformSettingsSchema = z.object({
   allow_duet: z.boolean().optional(),
   allow_stitch: z.boolean().optional(),
   title: z.string().optional(),
+  video_cover_timestamp_ms: z.number().nonnegative().optional(), // TikTok: millisecond timestamp of the video frame to use as the cover (direct post only)
   is_commercial_content: z.boolean().optional(),
   is_your_brand: z.boolean().optional(),
   is_branded_content: z.boolean().optional(),
@@ -86,7 +87,7 @@ export const updatePostTool = {
     post_type: z
       .string()
       .optional()
-      .describe('New post type: text, image, video, carousel, reel, story'),
+      .describe('New post type: text, image, video, carousel, reel, story, story_series, document, photo, or cover_photo'),
     instagram_settings: instagramSettingsSchema
       .optional()
       .describe('Instagram-specific updates: post_type, collaborators, user_tags, first_comment, media_alt_texts, is_trial_reel, graduation_strategy (defaults to MANUAL), reel_cover_url, reel_thumb_offset.'),