posterly-mcp-server 0.8.2 → 0.19.0

package/src/lib/api-client.ts

@@ -80,6 +80,37 @@ export interface InstagramPostSettings {
 
 export type PlatformPostSettings = Record<string, unknown>;
 
+export type CreatePostPayload = {
+  account_id?: string;
+  username?: string;
+  platform?: string;
+  caption: string;
+  scheduled_at?: string;
+  post_type?: string;
+  media_url?: string;
+  media_urls?: string[];
+  metadata?: Record<string, unknown>;
+  settings?: PlatformPostSettings;
+  reel_cover_url?: string;
+  reel_cover_method?: string;
+  reel_thumb_offset?: number;
+  workspace_id?: string;
+};
+
+export type CreatePostResponse = {
+  post: Post;
+  workspace: { id: string; name: string; is_personal: boolean; resolved_from: 'explicit' | 'account' | 'personal' };
+};
+
+export type BatchCreatePostsResponse = {
+  posts: Array<CreatePostResponse & { index: number; replayed: boolean }>;
+  errors: Array<{ index: number; status: number; error: string; validation_errors?: unknown }>;
+  total: number;
+  created: number;
+  replayed: number;
+  failed: number;
+};
+
 export interface Slot {
   time: string;
   local_time: string;
@@ -180,6 +211,172 @@ export interface PostAnalyticsResponse {
   offset: number;
 }
 
+export interface GoogleBusinessReview {
+  name?: string;
+  reviewId?: string;
+  reviewer?: { displayName?: string; profilePhotoUrl?: string };
+  starRating: number;
+  comment?: string;
+  createTime?: string;
+  updateTime?: string;
+  reviewReply?: Record<string, unknown>;
+  locationId?: string | null;
+  locationName?: string | null;
+  businessName?: string | null;
+  socialAccountId?: number;
+  account_id?: number;
+}
+
+export interface GoogleBusinessReviewsResponse {
+  reviews: GoogleBusinessReview[];
+  total: number;
+  locations: Array<Record<string, unknown>>;
+}
+
+export interface GoogleBusinessReviewLinkResponse {
+  reviewLink: string;
+  placeId: string;
+  businessName: string;
+  locationId: string | null;
+  account_id: number;
+}
+
+export interface ActivityItem {
+  id: string;
+  type: 'activity' | 'publish';
+  post_id: number | null;
+  action?: string | null;
+  description?: string | null;
+  platform?: string | null;
+  outcome?: string | null;
+  error_code?: string | null;
+  error_message?: string | null;
+  http_status?: number | null;
+  retry_number?: number | null;
+  duration_ms?: number | null;
+  pipeline_step?: string | null;
+  metadata?: Record<string, unknown> | null;
+  context?: Record<string, unknown> | null;
+  created_at: string;
+}
+
+export interface ActivityResponse {
+  items: ActivityItem[];
+  total: number;
+  limit: number;
+}
+
+export interface ApiWebhook {
+  id: string;
+  workspace_id: string | null;
+  url: string;
+  description: string | null;
+  events: string[];
+  is_active: boolean;
+  created_at: string;
+  updated_at: string | null;
+  last_delivery_at: string | null;
+  last_delivery_status: number | null;
+  last_error: string | null;
+}
+
+export interface WebhookResponse {
+  webhook: ApiWebhook;
+  secret?: string;
+}
+
+export interface PlatformSchema {
+  id: string;
+  aliases: string[];
+  label: string;
+  status: 'supported' | 'planned';
+  summary: string;
+  content_limit: number | null;
+  media: Record<string, unknown>;
+  post_types: string[];
+  analytics_supported: boolean;
+  settings_schema: {
+    fields: Array<Record<string, unknown>>;
+    example: Record<string, unknown>;
+  };
+  helper_tools: Array<Record<string, unknown>>;
+  native_features: string[];
+}
+
+export interface ConnectOption {
+  platform: string;
+  aliases: string[];
+  label: string;
+  status: 'supported' | 'planned';
+  method: 'dashboard_oauth' | 'manual_credentials' | 'planned';
+  provider_platforms: string[];
+  dashboard_url: string;
+  connection_url: string | null;
+  oauth_url: string | null;
+  supports_direct_oauth_url: boolean;
+  requires_browser_session: boolean;
+  configured: boolean | null;
+  env_requirements: Array<Record<string, unknown>>;
+  missing_env: string[][];
+  scopes: string[];
+  credential_fields: Array<Record<string, unknown>>;
+  notes: string[];
+  connected_count?: number;
+  connected_accounts?: Account[];
+}
+
+export interface OAuthDeveloperClient {
+  id: string;
+  client_id: string;
+  client_name: string;
+  description?: string | null;
+  homepage?: string | null;
+  allowed_redirect_uris: string[];
+  default_scopes: string[];
+  is_active: boolean;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface VideoJob {
+  id: string;
+  status: string;
+  prompt: string;
+  model: string;
+  duration_seconds: number;
+  aspect_ratio?: string;
+  resolution?: string;
+  generation_mode?: string | null;
+  credit_cost: number;
+  included_credit_cost?: number;
+  purchased_credit_cost?: number;
+  source_image_url?: string | null;
+  end_image_url?: string | null;
+  source_video_url?: string | null;
+  reference_images?: unknown;
+  generate_audio?: boolean | null;
+  video_url?: string | null;
+  error_message?: string | null;
+  created_at: string;
+  started_at?: string | null;
+  completed_at?: string | null;
+}
+
+export interface XPostingQuotaResponse {
+  workspace_id: string | null;
+  tier: string | null;
+  base_posts: number;
+  addon_posts: number;
+  total_posts: number;
+  used_posts: number;
+  remaining_posts: number;
+  current_period_start: string;
+  current_period_end: string;
+  urls_blocked: boolean;
+  addon?: Record<string, unknown>;
+  plans?: Array<Record<string, unknown>>;
+}
+
 export class PosterlyClient {
   private baseUrl: string;
   private apiKey: string;
@@ -234,6 +431,58 @@ export class PosterlyClient {
     return data.accounts;
   }
 
+  async disconnectAccount(accountId: string): Promise<Record<string, any>> {
+    return this.request('DELETE', `/accounts/${encodeURIComponent(accountId)}`);
+  }
+
+  async getConnectLink(params?: {
+    platform?: string;
+    workspace_id?: string;
+    include_planned?: boolean;
+  }): Promise<{ connect?: ConnectOption; connect_options?: ConnectOption[] }> {
+    const searchParams = new URLSearchParams();
+    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    if (params?.include_planned) searchParams.set('include_planned', 'true');
+    const qs = searchParams.toString();
+    const path = params?.platform
+      ? `/connect/${encodeURIComponent(params.platform)}`
+      : '/connect';
+    return this.request('GET', `${path}${qs ? `?${qs}` : ''}`);
+  }
+
+  async listOAuthClients(): Promise<{ clients: OAuthDeveloperClient[] }> {
+    return this.request('GET', '/oauth/clients');
+  }
+
+  async createOAuthClient(data: {
+    client_name: string;
+    description?: string;
+    homepage?: string;
+    allowed_redirect_uris: string[];
+    default_scopes: string[];
+    is_active?: boolean;
+  }): Promise<{ client: OAuthDeveloperClient }> {
+    return this.request('POST', '/oauth/clients', data);
+  }
+
+  async updateOAuthClient(
+    clientId: string,
+    data: {
+      client_name?: string;
+      description?: string;
+      homepage?: string | null;
+      allowed_redirect_uris?: string[];
+      default_scopes?: string[];
+      is_active?: boolean;
+    },
+  ): Promise<{ client: OAuthDeveloperClient }> {
+    return this.request('PATCH', `/oauth/clients/${encodeURIComponent(clientId)}`, data);
+  }
+
+  async deleteOAuthClient(clientId: string): Promise<{ deleted: boolean; client_id: string }> {
+    return this.request('DELETE', `/oauth/clients/${encodeURIComponent(clientId)}`);
+  }
+
   async listBrands(params?: { workspace_id?: string }): Promise<Brand[]> {
     const searchParams = new URLSearchParams();
     if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
@@ -275,32 +524,22 @@ export class PosterlyClient {
     return this.request('GET', `/posts${qs ? `?${qs}` : ''}`);
   }
 
-  async createPost(data: {
-    account_id?: string;
-    username?: string;
-    platform?: string;
-    caption: string;
-    scheduled_at?: string;
-    post_type?: string;
-    media_url?: string;
-    media_urls?: string[];
-    metadata?: Record<string, unknown>;
-    settings?: PlatformPostSettings;
-    reel_cover_url?: string;
-    reel_cover_method?: string;
-    reel_thumb_offset?: number;
-    workspace_id?: string;
-  }): Promise<{
-    post: Post;
-    workspace: { id: string; name: string; is_personal: boolean; resolved_from: 'explicit' | 'account' | 'personal' };
-  }> {
+  async createPost(data: CreatePostPayload): Promise<CreatePostResponse> {
     return this.request('POST', '/posts', data);
   }
 
+  async createPostsBatch(data: { posts: CreatePostPayload[] }): Promise<BatchCreatePostsResponse> {
+    return this.request('POST', '/posts/batch', data);
+  }
+
   async getPost(id: number): Promise<{ post: Post }> {
     return this.request('GET', `/posts/${id}`);
   }
 
+  async getPostMissing(id: number): Promise<Record<string, any>> {
+    return this.request('GET', `/posts/${id}/missing`);
+  }
+
   async updatePost(
     id: number,
     data: {
@@ -323,6 +562,24 @@ export class PosterlyClient {
     return this.request('DELETE', `/posts/${id}`);
   }
 
+  async updatePostStatus(
+    id: number,
+    data: { status: 'scheduled' | 'paused' | 'draft'; scheduled_at?: string },
+  ): Promise<Record<string, any>> {
+    return this.request('PUT', `/posts/${id}/status`, data);
+  }
+
+  async updatePostReleaseId(
+    id: number,
+    data: { release_id: string; group_id?: string },
+  ): Promise<Record<string, any>> {
+    return this.request('PUT', `/posts/${id}/release-id`, data);
+  }
+
+  async deletePostGroup(groupId: string): Promise<Record<string, any>> {
+    return this.request('DELETE', `/posts/group/${encodeURIComponent(groupId)}?confirm=true`);
+  }
+
   async generateImage(data: {
     prompt: string;
     aspect_ratio?: string;
@@ -347,6 +604,49 @@ export class PosterlyClient {
     return this.request('POST', '/ai/generate-image', data);
   }
 
+  async getVideoOptions(): Promise<Record<string, any>> {
+    return this.request('GET', '/ai/video-options');
+  }
+
+  async runVideoFunction(data: {
+    identifier: string;
+    functionName: string;
+    params?: Record<string, unknown>;
+  }): Promise<Record<string, any>> {
+    return this.request('POST', '/ai/video-function', data);
+  }
+
+  async generateVideo(data: {
+    prompt: string;
+    negative_prompt?: string;
+    aspect_ratio?: '16:9' | '9:16';
+    duration_seconds?: 4 | 6 | 8;
+    resolution?: '720p' | '1080p';
+    model?: 'fast' | 'standard';
+    image_url?: string;
+    end_image_url?: string;
+    reference_images?: Array<{ url: string; type: 'character' | 'object' | 'scene' }>;
+    generate_audio?: boolean;
+    source_video_url?: string;
+  }): Promise<Record<string, any>> {
+    return this.request('POST', '/ai/generate-video', data);
+  }
+
+  async getVideoJob(params?: {
+    job_id?: string;
+    status?: string;
+    limit?: number;
+  }): Promise<{ job?: VideoJob; jobs?: VideoJob[] }> {
+    if (params?.job_id) {
+      return this.request('GET', `/ai/video-jobs/${encodeURIComponent(params.job_id)}`);
+    }
+    const searchParams = new URLSearchParams();
+    if (params?.status) searchParams.set('status', params.status);
+    if (params?.limit) searchParams.set('limit', String(params.limit));
+    const qs = searchParams.toString();
+    return this.request('GET', `/ai/video-jobs${qs ? `?${qs}` : ''}`);
+  }
+
   async findAvailableSlots(params?: {
     account_ids?: string[];
     timezone?: string;
@@ -392,6 +692,172 @@ export class PosterlyClient {
     return this.request('GET', `/analytics/posts?${searchParams.toString()}`);
   }
 
+  async listGoogleBusinessReviews(params?: {
+    workspace_id?: string;
+    account_id?: number;
+    location_id?: string;
+    rating?: number;
+    unanswered?: boolean;
+  }): Promise<GoogleBusinessReviewsResponse> {
+    const searchParams = new URLSearchParams();
+    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    if (params?.account_id) searchParams.set('account_id', String(params.account_id));
+    if (params?.location_id) searchParams.set('location_id', params.location_id);
+    if (params?.rating) searchParams.set('rating', String(params.rating));
+    if (params?.unanswered) searchParams.set('unanswered', 'true');
+    const qs = searchParams.toString();
+    return this.request('GET', `/google-business/reviews${qs ? `?${qs}` : ''}`);
+  }
+
+  async getGoogleBusinessReviewLink(params: {
+    workspace_id?: string;
+    account_id?: number;
+    location_id?: string;
+  }): Promise<GoogleBusinessReviewLinkResponse> {
+    const searchParams = new URLSearchParams();
+    if (params.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    if (params.account_id) searchParams.set('account_id', String(params.account_id));
+    if (params.location_id) searchParams.set('location_id', params.location_id);
+    return this.request('GET', `/google-business/review-link?${searchParams.toString()}`);
+  }
+
+  async auditGoogleBusinessProfile(params: {
+    workspace_id?: string;
+    account_id?: number;
+    location_id?: string;
+  }): Promise<Record<string, any>> {
+    const searchParams = new URLSearchParams();
+    if (params.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    if (params.account_id) searchParams.set('account_id', String(params.account_id));
+    if (params.location_id) searchParams.set('location_id', params.location_id);
+    return this.request('GET', `/google-business/audit?${searchParams.toString()}`);
+  }
+
+  async suggestGoogleBusinessReviewReply(data: {
+    workspace_id?: string;
+    account_id?: number;
+    location_id?: string;
+    review_text?: string;
+    star_rating: number;
+    reviewer_name?: string;
+    business_name?: string;
+    tone?: 'professional' | 'friendly' | 'apologetic';
+    count?: number;
+  }): Promise<Record<string, any>> {
+    return this.request('POST', '/google-business/reviews/suggest-reply', data);
+  }
+
+  async replyGoogleBusinessReview(data: {
+    workspace_id?: string;
+    account_id?: number;
+    location_id?: string;
+    review_name: string;
+    comment: string;
+  }): Promise<Record<string, any>> {
+    return this.request('POST', '/google-business/reviews/reply', data);
+  }
+
+  async deleteGoogleBusinessReviewReply(data: {
+    workspace_id?: string;
+    account_id?: number;
+    location_id?: string;
+    review_name: string;
+  }): Promise<Record<string, any>> {
+    return this.request('DELETE', '/google-business/reviews/reply', data);
+  }
+
+  async listActivity(params?: {
+    workspace_id?: string;
+    post_id?: number;
+    since?: string;
+    type?: 'all' | 'activity' | 'publish';
+    limit?: number;
+  }): Promise<ActivityResponse> {
+    const searchParams = new URLSearchParams();
+    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    if (params?.post_id) searchParams.set('post_id', String(params.post_id));
+    if (params?.since) searchParams.set('since', params.since);
+    if (params?.type) searchParams.set('type', params.type);
+    if (params?.limit) searchParams.set('limit', String(params.limit));
+    const qs = searchParams.toString();
+    return this.request('GET', `/activity${qs ? `?${qs}` : ''}`);
+  }
+
+  async listWebhooks(params?: { workspace_id?: string }): Promise<{ webhooks: ApiWebhook[] }> {
+    const searchParams = new URLSearchParams();
+    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    const qs = searchParams.toString();
+    return this.request('GET', `/webhooks${qs ? `?${qs}` : ''}`);
+  }
+
+  async createWebhook(data: {
+    url: string;
+    events?: string[];
+    workspace_id?: string;
+    description?: string;
+    is_active?: boolean;
+  }): Promise<WebhookResponse> {
+    return this.request('POST', '/webhooks', data);
+  }
+
+  async updateWebhook(
+    id: string,
+    data: {
+      url?: string;
+      events?: string[];
+      workspace_id?: string | null;
+      description?: string | null;
+      is_active?: boolean;
+    },
+  ): Promise<WebhookResponse> {
+    return this.request('PATCH', `/webhooks/${encodeURIComponent(id)}`, data);
+  }
+
+  async deleteWebhook(id: string): Promise<{ deleted: boolean; id: string }> {
+    return this.request('DELETE', `/webhooks/${encodeURIComponent(id)}`);
+  }
+
+  async testWebhook(id: string): Promise<{ delivery: Record<string, unknown> }> {
+    return this.request('POST', `/webhooks/${encodeURIComponent(id)}/test`, {});
+  }
+
+  async listPlatforms(params?: { include_planned?: boolean }): Promise<{ platforms: PlatformSchema[] }> {
+    const searchParams = new URLSearchParams();
+    if (params?.include_planned) searchParams.set('include_planned', 'true');
+    const qs = searchParams.toString();
+    return this.request('GET', `/platforms${qs ? `?${qs}` : ''}`);
+  }
+
+  async getPlatformSchema(params: {
+    account_id?: string;
+    platform?: string;
+    include_planned?: boolean;
+  }): Promise<{ account?: Record<string, unknown>; schema?: PlatformSchema; platform?: PlatformSchema; platforms?: PlatformSchema[] }> {
+    if (params.account_id) {
+      return this.request('GET', `/accounts/${encodeURIComponent(params.account_id)}/schema`);
+    }
+    const searchParams = new URLSearchParams();
+    if (params.platform) searchParams.set('platform', params.platform);
+    if (params.include_planned) searchParams.set('include_planned', 'true');
+    return this.request('GET', `/platforms?${searchParams.toString()}`);
+  }
+
+  async triggerPlatformHelper(data: {
+    helper: string;
+    account_id?: string;
+    platform?: string;
+    params?: Record<string, unknown>;
+  }): Promise<{ helper: string; account: Record<string, unknown> | null; result: unknown }> {
+    return this.request('POST', '/platforms/trigger', data);
+  }
+
+  async getXPostingQuota(params?: { workspace_id?: string }): Promise<XPostingQuotaResponse> {
+    const searchParams = new URLSearchParams();
+    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    const qs = searchParams.toString();
+    return this.request('GET', `/x-posting/quota${qs ? `?${qs}` : ''}`);
+  }
+
   async getSignedUploadUrl(
     filename: string,
     contentType: string,
@@ -459,6 +925,18 @@ export class PosterlyClient {
       content_type: contentType,
     });
   }
+
+  async uploadMediaFromUrl(input: {
+    url: string;
+    filename?: string;
+    contentType?: string;
+  }): Promise<{ url: string; path: string; source_url: string; content_type: string; size: number }> {
+    return this.request('POST', '/media/upload-from-url', {
+      url: input.url,
+      filename: input.filename,
+      content_type: input.contentType,
+    });
+  }
 }
 
 function guessContentType(filename: string): string {

package/src/tools/audit-google-business-profile.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const auditGoogleBusinessProfileTool = {
+  name: 'audit_google_business_profile',
+  description:
+    'Run a live local-profile audit for a connected Google Business Profile location, including completeness, categories, media, attributes, reviews, and recommendations.',
+  inputSchema: z.object({
+    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
+    account_id: z.number().int().positive().optional().describe('Google Business account ID from list_accounts.'),
+    location_id: z.string().optional().describe('Google Business location/platform_user_id.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      workspace_id?: string;
+      account_id?: number;
+      location_id?: string;
+    },
+  ) {
+    const result = await client.auditGoogleBusinessProfile(input);
+    const audit = result.audit || {};
+    const recommendations = Array.isArray(audit.recommendations) ? audit.recommendations : [];
+    const lines = [
+      `Google Business audit: ${audit.businessName || 'Unknown business'}`,
+      `Score: ${audit.overallScore ?? 'n/a'} (${audit.overallGrade || 'n/a'})`,
+      `Fetched: ${result.fetchedAt || 'unknown'}`,
+    ];
+    if (recommendations.length > 0) {
+      lines.push('Top recommendations:');
+      for (const rec of recommendations.slice(0, 5)) {
+        lines.push(`- ${rec.priority || 'medium'}: ${rec.description || rec.title || 'Recommendation'}`);
+      }
+    }
+    return lines.join('\n');
+  },
+};

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

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+const scopeSchema = z.enum(['accounts:read', 'accounts:write', 'posts:read', 'posts:write', 'media:write', 'analytics:read']);
+
+export const createOAuthClientTool = {
+  name: 'create_oauth_client',
+  description:
+    'Create a public OAuth 2.1 + PKCE developer client. WRITE: confirm app name, redirect URIs, and scopes with the user before calling.',
+  inputSchema: 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).describe('Must be true after explicit user confirmation.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      client_name: string;
+      description?: string;
+      homepage?: string;
+      allowed_redirect_uris: string[];
+      default_scopes: string[];
+      is_active?: boolean;
+      confirm: true;
+    },
+  ) {
+    const { confirm: _confirm, ...payload } = input;
+    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(', ')}`;
+  },
+};