@omnisocials/mcp-server 1.20.0 → 1.20.1

package/build/tools/webhooks.js

@@ -8,7 +8,7 @@ export function registerWebhookTools(server, getClient) {
                 content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
             };
         }
-        const webhooks = Array.isArray(result.data) ? result.data : result.data?.webhooks || [];
+        const webhooks = Array.isArray(result.data) ? result.data : [];
         if (!webhooks.length) {
             return {
                 content: [{ type: "text", text: "No webhooks configured." }],
@@ -39,6 +39,11 @@ export function registerWebhookTools(server, getClient) {
             };
         }
         const w = result.data;
+        if (!w) {
+            return {
+                content: [{ type: "text", text: "Webhook created, but the API returned no details. Verify with list_webhooks." }],
+            };
+        }
         let md = `## Webhook Created\n\n`;
         md += `| Field | Value |\n`;
         md += `|-------|-------|\n`;
@@ -64,6 +69,11 @@ export function registerWebhookTools(server, getClient) {
             };
         }
         const w = result.data;
+        if (!w) {
+            return {
+                content: [{ type: "text", text: "Webhook not found." }],
+            };
+        }
         let md = `## Webhook Details\n\n`;
         md += `| Field | Value |\n`;
         md += `|-------|-------|\n`;
@@ -95,6 +105,11 @@ export function registerWebhookTools(server, getClient) {
             };
         }
         const w = result.data;
+        if (!w) {
+            return {
+                content: [{ type: "text", text: "Webhook updated, but the API returned no details. Verify with list_webhooks." }],
+            };
+        }
         let md = `## Webhook Updated\n\n`;
         md += `| Field | Value |\n`;
         md += `|-------|-------|\n`;
@@ -124,6 +139,11 @@ export function registerWebhookTools(server, getClient) {
             };
         }
         const w = result.data;
+        if (!w) {
+            return {
+                content: [{ type: "text", text: "Secret rotated, but the API returned no details." }],
+            };
+        }
         let md = `## Webhook Secret Rotated\n\n`;
         md += `| Field | Value |\n`;
         md += `|-------|-------|\n`;

package/build/types.d.ts

@@ -4,6 +4,14 @@ export interface ApiResponse<T = unknown> {
         code: string;
         message: string;
     };
+    warnings?: Array<{
+        code: string;
+        message: string;
+        credits_required?: number;
+        credits_balance?: number | null;
+        enforced?: boolean;
+        enforce_from?: string;
+    }>;
     pagination?: {
         next_cursor: string | null;
         has_more: boolean;
@@ -56,39 +64,183 @@ export interface InboxMessage {
         thumbnail: string | null;
     } | null;
 }
-export interface Post {
+/** One media entry on a post — a plain URL string, or an object carrying the
+ * url plus an optional accessibility description (alt text). */
+export type ApiPostMediaEntry = string | {
+    id?: string | number;
+    url?: string;
+    alt?: string;
+    [k: string]: unknown;
+};
+/** A thread part as echoed back by the API (X / Bluesky / Mastodon). */
+export interface ApiThreadPartOut {
+    id?: string;
+    text?: string;
+    media_urls?: Array<string | {
+        url?: string;
+        alt?: string;
+    }>;
+    [k: string]: unknown;
+}
+/** Per-platform option block echoed on a post. First comments (input +
+ * post-publish outcome), thread parts, and platform-specific settings all
+ * ride here under their platform key, mirroring the request shape. */
+export interface ApiPlatformOptionsOut {
+    first_comment?: string;
+    first_comment_result?: {
+        status?: string;
+        error?: string;
+        [k: string]: unknown;
+    } | null;
+    thread_parts?: ApiThreadPartOut[];
+    [k: string]: unknown;
+}
+/** Instagram option block — adds the Reel-cover and Trial-Reel read-backs. */
+export interface ApiInstagramOptionsOut extends ApiPlatformOptionsOut {
+    is_trial_reel?: boolean;
+    trial_graduation_strategy?: string;
+    thumbnail_type?: string;
+    thumb_offset?: number | string;
+    cover_url?: string;
+}
+export interface ApiPost {
     id: string;
-    content: string;
+    /** DB "posted" is mapped to "published" by the serializer. */
     status: string;
-    scheduled_at: string | null;
-    published_at: string | null;
-    channels: string[];
-    media: string[];
-    created_at: string;
-    /**
-     * Per-platform user-friendly error messages, keyed by platform identifier
-     * (facebook, instagram, linkedin, linkedin_page, youtube, tiktok, pinterest,
-     * x, threads, bluesky, mastodon, google_business). Populated when `status`
-     * is `failed` or `warning`. Only failed platforms appear. `null` while the
-     * post is still draft/scheduled/processing or every platform succeeded.
-     */
+    /** "post" | "story" | "reel" */
+    type?: string;
+    /** Per-platform captions keyed by platform id plus "default". Legacy
+     * servers returned a plain string. */
+    content?: Record<string, string> | string;
+    /** Selected platforms — an array of platform ids on current servers;
+     * legacy servers returned a {platform: boolean} map. */
+    accounts?: string[] | Record<string, boolean>;
+    /** legacy servers (older key for `accounts`) */
+    channels?: string[] | Record<string, boolean>;
+    /** Flat array (same set everywhere) or per-platform map keyed
+     * "default"/platform. */
+    media?: ApiPostMediaEntry[] | Record<string, ApiPostMediaEntry[]>;
+    schedule_at?: string | null;
+    /** legacy servers */
+    scheduled_at?: string | null;
+    /** legacy servers */
+    published_at?: string | null;
+    approval_status?: string | null;
+    /** Deep link into the OmniSocials dashboard for this post. */
+    app_url?: string;
+    /** platform → live URL for each platform that successfully published. */
+    published_urls?: Record<string, string>;
+    /** Set on a retry post: the original failed post's id. */
+    retry_of?: string;
+    /** Set on the original post: ids of its retry posts. */
+    retries?: string[];
+    location_id?: string;
+    collaborators?: string[];
+    user_tags?: Array<string | {
+        username?: string;
+        x?: number;
+        y?: number;
+        image_index?: number;
+    }>;
+    link_url?: string;
+    link_title?: string;
+    link_description?: string;
+    link_thumbnail_url?: string;
+    youtube?: ApiPlatformOptionsOut;
+    pinterest?: ApiPlatformOptionsOut;
+    instagram?: ApiInstagramOptionsOut;
+    facebook?: ApiPlatformOptionsOut;
+    linkedin?: ApiPlatformOptionsOut;
+    linkedin_page?: ApiPlatformOptionsOut;
+    tiktok?: ApiPlatformOptionsOut;
+    google_business?: ApiPlatformOptionsOut;
+    x?: ApiPlatformOptionsOut;
+    bluesky?: ApiPlatformOptionsOut;
+    mastodon?: ApiPlatformOptionsOut;
+    /** platform → user-friendly error message; only failed platforms appear.
+     * null while draft/scheduled/processing or when every platform succeeded. */
     errors?: Record<string, string> | null;
-    x?: {
-        reply_settings?: string;
-        paid_partnership?: boolean;
-        made_with_ai?: boolean;
-        thread_parts?: Array<{
-            id?: string;
-            text: string;
-            /** Entries are plain URLs, or { url, alt } when the media carries an
-             * accessibility description (alt text). */
-            media_urls?: Array<string | {
-                url: string;
-                alt?: string;
-            }>;
-        }>;
-        [key: string]: unknown;
+    source?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+/** `data` of POST /posts/:id/publish — a small ack, not a full post
+ * (backend/routes/api/v1/posts.js publish route). */
+export interface PublishPostResult {
+    id: string;
+    status: string;
+    message?: string;
+}
+/** `data` of POST /posts/:id/retry (backend/routes/api/v1/posts.js:4194). */
+export interface RetryPostResult {
+    id: string;
+    status: string;
+    /** The failed platforms being re-published. */
+    platforms?: string[];
+    message?: string;
+}
+/** One place from GET /locations/search
+ * (@openapi block in backend/routes/api/v1/locations.js). */
+export interface LocationPlace {
+    /** Facebook Place ID — use as `location_id`. */
+    id: string;
+    name: string;
+    address?: string | null;
+    city?: string | null;
+    country?: string | null;
+}
+/** GET /locations/search envelope — NOT the standard data/error envelope:
+ * on the documented degraded path (no Facebook account / missing permission)
+ * `error` is a human-readable STRING next to an empty `data`; the standard
+ * { code, message } object appears only on transport/HTTP failures. */
+export interface LocationSearchResult {
+    data?: LocationPlace[];
+    error?: string | {
+        code: string;
+        message: string;
     };
+    needsPermission?: boolean;
+}
+/** One track from GET /audio/search
+ * (@openapi block in backend/routes/api/v1/audio.js). */
+export interface InstagramAudioTrack {
+    /** Use as `instagram.audio_id` on a reel. */
+    audio_id: string;
+    title?: string | null;
+    artist?: string | null;
+    duration_ms?: number | null;
+    /** Creator handle (original sounds only). */
+    ig_username?: string | null;
+    [k: string]: unknown;
+}
+/** GET /audio/search envelope — same nonstandard string-`error` convention
+ * as LocationSearchResult. */
+export interface AudioSearchResult {
+    data?: InstagramAudioTrack[];
+    error?: string | {
+        code: string;
+        message: string;
+    };
+}
+/** One record from GET /posts/recent-platform — normalized in
+ * backend/services/voice-fetcher/recentPlatformPostsService.js (:125-149). */
+export interface RecentPlatformPost {
+    platform: string;
+    /** The platform's own post id — the stable dedupe key. */
+    id: string | null;
+    permalink: string | null;
+    /** Always a string; "" when the post has no caption. */
+    text: string;
+    format?: string;
+    media_count?: number;
+    timestamp?: string | null;
+    image_url?: string | null;
+    /** Video length in whole seconds; null for images / platforms without it. */
+    duration_seconds?: number | null;
+    metrics?: Record<string, unknown>;
+    engagement?: number | null;
+    impressions?: number | null;
+    engagement_rate?: number | null;
 }
 export interface MediaItem {
     id: string;
@@ -170,11 +322,123 @@ export interface HashtagSet {
     created_at: string;
     updated_at: string;
 }
+/** Per-platform stats block inside AnalyticsOverview.platform_breakdown.
+ * Shape from backend/routes/api/v1/analytics.js (overview route). */
+export interface AnalyticsPlatformBreakdown {
+    posts: number;
+    total_engagement: number;
+    total_impressions: number;
+    average_engagement: number;
+    /** 0 when total_impressions is below the shared minimum-impressions floor. */
+    engagement_rate: number;
+}
+/** `data` payload of GET /analytics/overview. The resolved range
+ * (`period`/`start_date`/`end_date`/`current_date`) rides top-level on the
+ * response envelope, not inside `data` — see getAnalyticsOverview(). */
 export interface AnalyticsOverview {
     total_posts: number;
+    total_platforms: number;
+    total_engagement: number;
     total_impressions: number;
-    total_engagements: number;
-    period: string;
+    average_engagement_rate: number;
+    top_performing_platform: string | null;
+    platform_breakdown: Record<string, AnalyticsPlatformBreakdown>;
+}
+/** One connected platform that would reject the file
+ * (backend/services/media/mediaCompatibility.js getMediaWarnings). */
+export interface MediaCompatWarning {
+    platform: string;
+    display_name: string;
+    reasons: string[];
+}
+/** Advisory compatibility block on /media/upload* and /media/check responses.
+ * Built by buildCompatibility() in backend/routes/api/v1/media.js:
+ * empty warnings = the file posts to every connected platform. */
+export interface MediaCompatibility {
+    compatible: boolean;
+    warnings: MediaCompatWarning[];
+    /** One-line human summary, or null when fully compatible. */
+    summary: string | null;
+}
+/** POST /media/check response — the compatibility block is spread top-level
+ * next to `file` and `connected_platforms`; there is no `data` key
+ * (backend/routes/api/v1/media.js check route). */
+export interface MediaCheckResult {
+    error?: {
+        code: string;
+        message: string;
+    };
+    file?: {
+        size_bytes: number | null;
+        mime: string | null;
+        size_known: boolean;
+    };
+    connected_platforms?: string[];
+    compatible?: boolean;
+    warnings?: MediaCompatWarning[];
+    summary?: string | null;
+}
+/** One folder from GET /folders — formatFolder in
+ * backend/routes/api/v1/folders.js (:15-23). */
+export interface MediaFolder {
+    id: string;
+    name: string;
+    parent_id: string | null;
+    item_count?: number;
+    created_at?: string;
+}
+/** One row of GET /analytics/accounts `data`. `metrics` is the platform's
+ * account-level snapshot JSONB — counters are numbers; `note` (when present)
+ * explains non-obvious metric scope and must be relayed to the user. */
+export interface AccountAnalyticsEntry {
+    platform: string;
+    platform_account_id?: string | null;
+    date?: string;
+    metrics?: {
+        followers?: number;
+        subscribers?: number;
+        posts?: number;
+        following?: number;
+        impressions?: number;
+        engagement?: number;
+        total_views?: number;
+        total_videos?: number;
+        note?: string;
+        [k: string]: number | string | undefined;
+    };
+}
+/** GET /analytics/best-times response — top-level, not the data/error
+ * envelope (backend/services/analytics/bestTimeService.js getBestTimes). */
+export interface BestTimeRecommendation {
+    day: string;
+    /** "HH:00" in the resolved timezone. */
+    time: string;
+    score: number;
+    /** Number of posts behind the slot (own-data basis only). */
+    n?: number;
+    typical_engagement?: number;
+}
+export interface BestTimeGridCell {
+    day: string;
+    hour: number;
+    score: number;
+    [k: string]: unknown;
+}
+export interface BestTimesResult {
+    error?: {
+        code: string;
+        message: string;
+    };
+    platform?: string;
+    timezone?: string;
+    metric?: string;
+    window_days?: number;
+    sample_size?: number;
+    basis?: "own_data" | "defaults";
+    posts_needed?: number;
+    /** Absent on the defaults basis. */
+    grid?: BestTimeGridCell[];
+    recommendations?: BestTimeRecommendation[];
 }
 export interface PostAnalyticsPlatformEntry {
     platform: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnisocials/mcp-server",
-  "version": "1.20.0",
+  "version": "1.20.1",
   "description": "MCP server for OmniSocials API - manage social media posts, media, accounts, analytics, and webhooks",
   "type": "module",
   "main": "build/index.js",