@omnisocials/mcp-server 1.34.1 → 1.39.0

package/README.md

@@ -9,7 +9,7 @@ MCP (Model Context Protocol) server for the [OmniSocials](https://omnisocials.co
 
 ## Remote MCP URL (no install)
 
-For clients that support remote MCP over HTTP (claude.ai, ChatGPT, Notion, OpenClaw):
+For clients that support remote MCP over HTTP (claude.ai, ChatGPT, Notion, Muse, OpenClaw):
 
 ```
 https://mcp.omnisocials.com?API_KEY=omsk_live_your_key_here
@@ -115,7 +115,7 @@ OmniSocials accepts the following channel IDs in `create_post`, `create_and_publ
 
 ## Available Tools
 
-### Posts (13 tools)
+### Posts (15 tools)
 
 | Tool | Description |
 |------|-------------|
@@ -130,7 +130,9 @@ OmniSocials accepts the following channel IDs in `create_post`, `create_and_publ
 | `list_approval_workflows` | List the workspace's approval workflows (steps + approvers); pass an id as `approval_workflow_id` on `create_post` to hold the post for review |
 | `approve_post` | Approve the current step of a post's approval workflow (the connected user must be a listed approver for that step) |
 | `reject_post` | Reject a post's approval workflow, stopping it immediately |
+| `get_post_approval` | Read the approval review of a post: steps, approvers and their decisions, the rejection reason and the comment thread |
 | `search_locations` | Find an Instagram or Threads location to tag (Instagram place IDs for `location_id`, Threads location ids for `threads.location_id`; Threads also searches by latitude/longitude) |
+| `list_pinterest_products` | List the product Pins of the connected Pinterest account (catalog or own Pins), or check one Pin, to tag products with `pinterest.product_tags` |
 | `search_instagram_audio` | Search Instagram's licensed music catalog for a track to attach to a Reel |
 
 ### Media & folders (6 tools)
@@ -178,12 +180,12 @@ Apply a set when creating a post: `create_post` / `create_and_publish_post` acce
 | `list_workspaces` | List all workspaces available in this session |
 | `switch_workspace` | Switch the active workspace **by name** (id or list number also accepted) |
 
-### Webhooks (5 tools)
+### Webhooks (6 tools)
 
 | Tool | Description |
 |------|-------------|
 | `list_webhooks` | List all webhooks |
-| `create_webhook` | Create a webhook for event notifications |
+| `create_webhook` | Create a webhook for event notifications (`post.scheduled`, `post.published`, `post.failed`, `post.approved`, `post.rejected`) |
 | `get_webhook` | Get webhook details |
 | `update_webhook` | Update a webhook |
 | `delete_webhook` | Delete a webhook |
@@ -194,10 +196,10 @@ Apply a set when creating a post: `create_post` / `create_and_publish_post` acce
 | Tool | Description |
 |------|-------------|
 | `list_inbox_conversations` | List conversations: Instagram/Facebook DMs, comments, mentions, LinkedIn company-page comments/mentions, TikTok video comments, YouTube video comments, X DMs (opt-in), and Threads replies on your posts plus mentions; filter by platform, type, unread, or `unanswered` |
-| `get_next_unanswered` | The next item that still needs an answer (longest-waiting first) with the whole thread and the post it is on; filter by platform or type, `include_read`, `exclude` |
+| `get_next_unanswered` | The next item that still needs an answer (DMs that can still be answered first, then expired Instagram/Facebook DMs, then comments and mentions oldest first) with the whole thread, the post it is on and its `reply_window`; filter by platform or type, `include_read`, `exclude` |
 | `get_inbox_conversation` | Get a conversation's full message history with the post it belongs to; every message shows its `#id` |
 | `mark_inbox_read` | Mark all incoming messages in a conversation as read (also the durable skip for `get_next_unanswered`) |
-| `reply_to_inbox` | Reply to a DM, comment, or mention (existing conversations only); `include_next` returns the next unanswered item in the same call |
+| `reply_to_inbox` | Reply to a DM, comment, or mention (existing conversations only); `message_id` picks the comment being answered; `include_next` returns the next unanswered item in the same call |
 | `hide_inbox_comment` | Hide or unhide a comment on one of your posts (Facebook, Instagram, TikTok, YouTube, Threads) |
 | `delete_inbox_comment` | Permanently delete a comment on one of your posts, with the replies under it (Facebook, Instagram, TikTok) |
 | `hide_inbox_reply` | Older name for `hide_inbox_comment`, kept for compatibility |
@@ -227,6 +229,49 @@ Full API docs: [docs.omnisocials.com](https://docs.omnisocials.com)
 
 ## Changelog
 
+### 1.39.0 (2026-10-05)
+
+- **Added: tag products on a Pinterest Pin.** `pinterest.product_tags` on `create_post`, `create_and_publish_post` and `update_post` takes up to 24 product Pins of the connected Pinterest account (Pin IDs or Pin links), so people can shop the items in the image. Pinterest accepts a product only when its Pin is public, belongs to the same account and links to a website that account claimed; products of other merchants cannot be tagged. The tags are added right after the Pin is published. A product that Pinterest refuses never fails the post: the other products are still tagged, and `get_post` shows the outcome (`product_tags_result`, with Pinterest's reason for each product that was not tagged).
+- **Added: `list_pinterest_products`.** New tool that lists the product Pins of the connected Pinterest account, with the `pin_id` to use in `pinterest.product_tags`. `source` `catalog` reads the Pinterest catalog (price and stock included) and needs catalog access, which the user gives one time in the OmniSocials composer (Pinterest options, Add products, Connect catalog). `source` `pins` reads the account's own Pins and works on every connection. `check_pin` checks one Pin ID or Pin link instead of listing.
+
+### 1.38.0 (2026-10-02)
+
+- **Added: read the approval review of a post.** New tool `get_post_approval` returns the review of a post that went through an approval workflow: every step with its approvers and their decisions, the rejection (who, when and the reason) and the comment thread, oldest first. Until now the tools only gave the status, so an assistant saw `rejected` and not who rejected the post or why. Use it on a rejected post to learn what to change before sending it again, or on a post that waits for approval to see who it waits for and what the reviewers wrote. Read-only. A post without an approval workflow returns status `none`. Backed by `GET /posts/{id}/approval` (scope `posts:read`). Same on the companion server (`mcp.omnisocials.com`).
+- **Added: webhook events `post.approved` and `post.rejected`.** `create_webhook` and `update_webhook` take them next to `post.scheduled`, `post.published` and `post.failed`. `post.approved` fires when the last step of a post's approval workflow is approved (the post moves to `scheduled`, or `posting` when its publish time already passed). `post.rejected` fires when an approver rejects the post (it will not publish). Both carry one more object, `data.approval`: `{ status, decided_by, reason }` (`reason` is `null` on an approval and when the approver gave none), and their `targets` array is empty. Same on the companion server.
+- **Changed: more approval emails.** A rejection, a reviewer comment, a reviewer edit and the final approval now email the person who requested the approval, and the requester's reply in the review thread emails the reviewers. A post that still waits for approval gets automatic emails near its publish time: the reviewers 24 hours before, and the reviewers plus the requester when the time passes (the post did not publish; a late approval publishes it at once). No tool input or output changed for this.
+- **Changed: X link-post credits count only `http://` and `https://` links.** A post that names a website without a scheme (`brand.com`, `www.brand.com`) no longer uses credits and no longer returns the `x_url_post_credits` warning, because X does not bill it as a link post. A post with a full link still uses 20 credits. The descriptions of `create_post` and `create_and_publish_post` say which links count. Same on the companion server.
+
+### 1.37.1 (2026-09-30)
+
+- **Changed: Facebook Reels longer than 90 seconds are accepted.** The API no longer refuses a Facebook Reel over 90 seconds at submit: a Reel now follows the 240 minute ceiling of a Facebook feed video. Meta removed the Reel length limit in June 2025 (every Facebook video is a reel now), while its Reels Publishing API guide still lists 3 to 90 seconds. A 3 minute Reel published through the API on 2026-09-30, and Reels of 91 to 117 seconds published before the cap existed. The `create_post` and `create_and_publish_post` descriptions no longer tell the assistant to keep a Facebook Reel under 90 seconds. If Facebook refuses a length at publish time, the Facebook target fails with "Facebook did not accept the length of this video..." and the video can go out as a regular Facebook post (`type: "post"`). Same on the companion server.
+- **Changed: `video_cover` on YouTube Shorts is described as channel-dependent.** YouTube shows the cover on Shorts only on channels where it has enabled custom Shorts thumbnails (rolling out since July 2026, Partner Program channels first); on other channels it stores the cover as the default thumbnail but shows a frame from the video (checked on 15 published Shorts from 5 channels: 3 channels show it, 1 does not). The `video_cover` and `youtube` descriptions now say so, so the assistant says it depends on the channel instead of promising it. The image is now sent at up to 1080 x 1920, YouTube's Shorts thumbnail size. Same on the companion server.
+- **Companion server: `video_cover` added.** The hosted server now accepts `video_cover` on `create_post`, `create_and_publish_post` and `update_post` (`null` removes it), takes `facebook.thumbnail_type` / `thumb_offset` / `cover_url`, and lists the cover under Platform Options in `get_post`. This package has had them since 1.35.0.
+
+### 1.37.0 (2026-09-28)
+
+- **Added: the original PDF is kept, and LinkedIn receives it.** `upload_media` (url, base64 and the `upload_url` snippet) still splits a PDF into one image slide per page (max 20) and now also keeps the original file. When a LinkedIn post's `media_ids` are exactly that PDF's slides, in order and unchanged, LinkedIn receives the original file as the document: text stays sharp, in-document links work, viewers download the real file, and every page is included even past the 20-slide cap. The upload result names the kept file (`pdf.id`, `pdf.name`, `pdf.url`, `pdf.size_bytes`), the tool output says so, and every slide returned by `list_media` / `get_media` carries `pdf: { id, name, url, page, total_pages, rendered_pages }`. Same on the companion server (`mcp.omnisocials.com`).
+- **Added: `pdf_mode` on `upload_media`.** `"slides"` (default) keeps one image media item per page, one Media ID each. `"document"` keeps the PDF as ONE media item (`type: "document"`, its page images in `pdf.pages`); pass its single Media ID in `media_ids` and the post gets every page, in order. The tool output explains which shape came back, and `list_media` shows document items as "Document (PDF, N pages)". Same on the companion server (`mcp.omnisocials.com`), where the `upload_url` snippet takes it as a form field (`-F pdf_mode=document`).
+- **Added: `document_source` on the `linkedin` / `linkedin_page` options** of `create_post`, `create_and_publish_post` and `update_post`. `"original_pdf"` (default) sends the kept original when the images are its unchanged pages; `"slides"` rebuilds the document from the slide images instead (a flattened copy). On `update_post`: `"slides"` sets it, `"original_pdf"`/`null` reverts, omitted keeps the current value. `get_post` prints "document source: rebuilt from the slide images" when a channel opted out. Ignored when the images are not a PDF's pages, when `carousel_as_images` is true, and for 0-1 images, videos and polls. Same on the companion server.
+
+### 1.36.0 (2026-09-24)
+
+- **Added: `reply_to_inbox` takes `message_id`.** Every comment on a post shares one inbox conversation, and the reply endpoint always answered the newest incoming comment on that post, so a reply drafted for one person could land under a different person's comment. Pass `message_id` (the "Message to answer" `#id` from `get_next_unanswered`, or a `#id` from `get_inbox_conversation`) and the reply goes under exactly that comment. Without it the old behaviour is kept for compatibility (newest comment). Ignored for DMs. A `404 not_found` means the id is not an incoming message of that conversation. The tool description and the `get_next_unanswered` output tell the assistant to always pass it for comments. Same on the companion server (`mcp.omnisocials.com`).
+- **Changed: `get_next_unanswered` serves DMs first and no longer drops expired ones.** A customer's Facebook DM ("How do I buy and where please") was never served: DMs older than 24 hours were filtered out and the queue was oldest-first across everything, so a fresh DM sat behind a three-week comment backlog until Meta's reply window closed. The order is now: Instagram/Facebook DMs inside Meta's 24-hour window (the one closing soonest first) and X DMs, then Instagram/Facebook DMs whose window has closed, then comments and mentions oldest first (`order: "newest"` reverses within each group). Each item carries `reply_window: { open, closes_at }` (only Instagram/Facebook DMs have a window; everything else is `open: true, closes_at: null`). When `open` is false the tool prints a warning that OmniSocials cannot reply and that the user must answer from the Instagram or Facebook app (mirrored into the inbox) or skip with `mark_inbox_read`. `list_inbox_conversations` with `unanswered: true` now includes those expired DM conversations too. Same on the companion server.
+- **Changed: `reply_to_inbox` checks the 24-hour window before sending.** A `422 outside_messaging_window` on an Instagram/Facebook DM is now raised before the platform call (it was only mapped from Meta's error afterwards). Nothing is sent, the message names when the window closed, and the tool description tells the assistant not to retry. Same on the companion server.
+- **Changed: `hide_inbox_comment` explains a 502 `hide_not_applied`.** After an Instagram hide or unhide the API reads the comment back and reports Instagram's own `hidden` state. When Instagram accepted the call but the comment is still in the old state, the API answers 502 `hide_not_applied` and the inbox row is left unchanged (a hide had been reported as done while the comment stayed public). This happens with comments Instagram shows under "Comments from Facebook" on a reel that is also shared to Facebook: they live on Facebook and Instagram's hide does not reach them. The tool description tells the assistant to have the user hide it in the Instagram or Facebook app and not retry. Same on the companion server.
+- **Changed: Facebook `reach` is absent, never 0, in `get_post_analytics` and `get_bulk_post_analytics`.** Meta retired Facebook post reach on 2026-06-15 and the replacement metric it documents (`post_total_media_view_unique`) returns 0 for every Page post while views and clicks keep counting, so the API had stored and returned a false 0 for every Facebook post. The key is now left out, and a row collected before 2026-09-27 that still carries `reach: 0` is dropped by the API. The tool description tells the assistant to treat a missing `reach` as "not reported" and to sum reach only over the platforms that carry it (Instagram, LinkedIn, TikTok with the Business API). Same on the companion server (`mcp.omnisocials.com`).
+
+### 1.35.1 (2026-09-22)
+
+- **Changed: `reply_to_inbox` explains a 422 `reply_not_allowed`.** The API answers 422 instead of 502 when the platform refuses replies to an item for good (Facebook `#1705`: comment on a share or boosted copy of the post, or the commenter restricts replies; YouTube: the thread's `canReply` is false). The item is dropped from `get_next_unanswered` automatically; relay it, do not retry.
+- **Changed: `hide_inbox_comment` explains a 422 `cannot_hide`.** Facebook does not let the Page hide some comments (the commenter blocked the Page, their account is deactivated or restricted, or the comment sits on a shared copy of the post); the API now reads the comment back and answers 422 when Facebook's `can_hide` is false, instead of a 502 on every attempt. Retrying never changes it; use `mark_inbox_read` if the item should stop coming up.
+
+### 1.35.0 (2026-09-17)
+
+- **Added: video covers.** `create_post`, `create_and_publish_post` and `update_post` accept `video_cover` for a post whose media is one video: `type: "frame"` with `thumb_offset` (milliseconds into the video) or `type: "custom"` with `cover_url` (JPEG/PNG), plus per-platform `overrides` keyed by platform id (instagram, facebook, linkedin, linkedin_page, tiktok, pinterest, youtube). On `update_post`, `video_cover: null` removes the stored cover. `get_post` shows the cover in use.
+- **Changed: analytics say "not reported" instead of 0.** Metrics a platform never reports at post level (reach on X, saves on Facebook, link clicks on Instagram feed posts, and so on) render as N/A with the reason, and `reach` is null when the platform did not report it, so a zero is never invented.
+- **Changed: `reply_to_inbox` explains a 409 `duplicate_reply`.** The API now refuses the same reply (same text and attachment) sent twice to one comment, or to one DM conversation, within 10 minutes; the tool description tells the assistant that nothing was sent again and to continue with `get_next_unanswered` rather than resend. Guards against a re-invoked tool call after a slow response (a customer's Instagram comment got the identical reply twice, 21 seconds apart).
+
 ### 1.34.1 (2026-09-14)
 
 - **Changed: Threads threads and the Threads inbox are no longer "rolling out".** Meta approved the reply, read-replies and mentions permissions, so `threads.thread_parts` and the Threads inbox work for every Threads connection; accounts connected before 2026-09-14 need a one-time reconnect under Settings -> Organisation -> Workspaces (`400`/`401` errors name the reconnect). Threads location tagging stays rolling out (not approved yet). Same on the companion server.

package/build/client.d.ts

@@ -1,4 +1,4 @@
-import type { Account, AnalyticsOverview, AccountAnalyticsEntry, ApiPost, ApiResponse, AudioSearchResult, BestTimesResult, HashtagSet, LocationSearchResult, MediaCheckResult, MediaCompatibility, MediaFolder, MediaItem, PdfUploadResult, PostAnalytics, PublishPostResult, RecentPlatformPost, RetryPostResult, ApprovePostResult, RejectPostResult, InboxConversation, InboxDeleteResult, InboxMessage, InboxNextUnanswered, Webhook } from "./types.js";
+import type { Account, AnalyticsOverview, AccountAnalyticsEntry, ApiPost, ApiResponse, ApiVideoCover, AudioSearchResult, BestTimesResult, HashtagSet, LocationSearchResult, PinterestProductCheck, PinterestProductsResult, MediaCheckResult, MediaCompatibility, MediaFolder, MediaItem, PdfUploadResult, PostAnalytics, PublishPostResult, RecentPlatformPost, RetryPostResult, ApprovePostResult, RejectPostResult, PostApproval, InboxConversation, InboxDeleteResult, InboxMessage, InboxNextUnanswered, Webhook } from "./types.js";
 export declare function fetchImageAsBase64(url: string): Promise<{
     data: string;
     mimeType: string;
@@ -168,6 +168,8 @@ export interface CreatePostInput {
         y: number;
         image_index?: number;
     }>;
+    /** Video thumbnail: { type: "frame"|"custom", thumb_offset?, cover_url?, overrides? }. */
+    video_cover?: ApiVideoCover;
     pinterest?: Record<string, unknown>;
     youtube?: Record<string, unknown>;
     instagram?: Record<string, unknown>;
@@ -248,6 +250,7 @@ export declare class OmniSocialsClient {
             y: number;
             image_index?: number;
         }>;
+        video_cover?: ApiVideoCover | null;
         pinterest?: Record<string, unknown>;
         youtube?: Record<string, unknown>;
         instagram?: Record<string, unknown>;
@@ -267,11 +270,19 @@ export declare class OmniSocialsClient {
     retryPost(id: string): Promise<ApiResponse<RetryPostResult>>;
     approvePost(id: string): Promise<ApiResponse<ApprovePostResult>>;
     rejectPost(id: string, comment?: string): Promise<ApiResponse<RejectPostResult>>;
+    getPostApproval(id: string): Promise<ApiResponse<PostApproval>>;
     searchLocations(query?: string, platform?: "instagram" | "threads", coords?: {
         latitude?: number;
         longitude?: number;
     }): Promise<LocationSearchResult>;
     validateLocation(id: string): Promise<ApiResponse<unknown>>;
+    listPinterestProducts(params?: {
+        source?: "catalog" | "pins";
+        product_group_id?: string;
+        bookmark?: string;
+        page_size?: string;
+    }): Promise<PinterestProductsResult>;
+    validatePinterestProduct(id: string): Promise<PinterestProductCheck>;
     searchInstagramAudio(query?: string, type?: "music" | "original_sound"): Promise<AudioSearchResult>;
     listMedia(params?: {
         limit?: string;
@@ -284,6 +295,7 @@ export declare class OmniSocialsClient {
         filename?: string;
         name?: string;
         folder?: string;
+        pdf_mode?: "slides" | "document";
     }): Promise<ApiResponse<MediaItem> & Partial<PdfUploadResult> & {
         compatibility?: MediaCompatibility;
         message?: string;
@@ -294,6 +306,7 @@ export declare class OmniSocialsClient {
         filename?: string;
         name?: string;
         folder?: string;
+        pdf_mode?: "slides" | "document";
     }): Promise<ApiResponse<MediaItem> & Partial<PdfUploadResult> & {
         compatibility?: MediaCompatibility;
         message?: string;
@@ -391,6 +404,7 @@ export declare class OmniSocialsClient {
     markInboxRead(conversationId: string): Promise<ApiResponse<unknown>>;
     replyToInboxConversation(conversationId: string, data: {
         text: string;
+        message_id?: string;
         attachment_url?: string;
         attachment_type?: string;
         include_next?: boolean;

package/build/client.js

@@ -285,6 +285,12 @@ export class OmniSocialsClient {
             ...(comment ? { comment } : {}),
         });
     }
+    // Reads the review of the post's approval workflow: every step with its
+    // approvers and their decisions, the rejection with its reason, and the
+    // comment thread. A post without a workflow answers 200 with status "none".
+    async getPostApproval(id) {
+        return this.request("GET", `/posts/${id}/approval`);
+    }
     // Locations (Instagram or Threads place tagging). NOT the standard
     // envelope; see LocationSearchResult: Instagram's degraded-path `error` is
     // a plain string next to `data`; Threads answers with `locations` and a
@@ -303,6 +309,24 @@ export class OmniSocialsClient {
     async validateLocation(id) {
         return this.request("GET", "/locations/validate", undefined, { id });
     }
+    // Pinterest product Pins (for `pinterest.product_tags`). NOT the standard
+    // envelope; see PinterestProductsResult: `products` on success, a
+    // { code, message } `error` object when the list could not be read.
+    async listPinterestProducts(params) {
+        const query = {};
+        if (params?.source)
+            query.source = params.source;
+        if (params?.product_group_id)
+            query.product_group_id = params.product_group_id;
+        if (params?.bookmark)
+            query.bookmark = params.bookmark;
+        if (params?.page_size)
+            query.page_size = params.page_size;
+        return this.request("GET", "/pinterest/products", undefined, query);
+    }
+    async validatePinterestProduct(id) {
+        return this.request("GET", "/pinterest/products/validate", undefined, { id });
+    }
     // Audio (Instagram Reel music). Same nonstandard string-`error` envelope.
     async searchInstagramAudio(query, type) {
         const params = {};

package/build/index.js

@@ -29,7 +29,7 @@ const sessionState = { activeIndex: 0 };
 const getActiveClient = () => workspaceClients[sessionState.activeIndex].client;
 const server = new McpServer({
     name: "OmniSocials",
-    version: "1.34.1",
+    version: "1.39.0",
 });
 // Register all tools - pass getter function so tools always use the active workspace's client
 registerPostTools(server, getActiveClient);

package/build/metrics.d.ts

@@ -16,8 +16,16 @@ type Metrics = Record<string, unknown> | null | undefined;
 export declare function getEngagement(platform: string, metrics: Metrics): number;
 /** Best-available impressions ("how many times seen") for a post's metrics. */
 export declare function getImpressions(platform: string, metrics: Metrics): number;
-/** Unique accounts reached, when the platform reports it (0 otherwise). */
-export declare function getReach(platform: string, metrics: Metrics): number;
+/** Unique accounts reached; null when the platform did not report it. */
+export declare function getReach(platform: string, metrics: Metrics): number | null;
+/** Post-level metrics a platform can never report: platform -> metric key -> reason. */
+export declare const UNSUPPORTED_POST_METRICS: Record<string, Record<string, string>>;
+/** Metrics unavailable for some post types only: platform -> content_type -> metric key -> reason. Empty since Facebook reach moved to the platform-wide map. */
+export declare const UNSUPPORTED_POST_METRICS_BY_CONTENT_TYPE: Record<string, Record<string, Record<string, string>>>;
+/** Reason `metricKey` is unavailable on `platform` (refined by `contentType`), or null when it is available. */
+export declare function unsupportedMetricReason(platform: string, metricKey: string, contentType?: string): string | null;
+/** True when the platform can never report `metricKey` for this post; a finite stored value overrides the map. */
+export declare function isMetricUnsupported(platform: string, metricKey: string, metrics?: Metrics): boolean;
 /**
  * Engagement rate as a percentage (0-100), suppressed below the impression
  * floor and capped at 100%.

package/build/metrics.js

@@ -106,10 +106,108 @@ export function getImpressions(platform, metrics) {
             return num(m.views) || num(m.impressions) || num(m.reach);
     }
 }
-/** Unique accounts reached, when the platform reports it (0 otherwise). */
+// Finite number or null: a missing key stays "no data", never 0.
+const finiteOrNull = (v) => {
+    if (v === null || v === undefined || v === "")
+        return null;
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) ? n : null;
+};
+/** Unique accounts reached; null when the platform did not report it. */
 export function getReach(platform, metrics) {
     const m = metrics || {};
-    return num(m.reach) || num(m.unique_impressions) || num(m.members_reached);
+    for (const key of ["reach", "unique_impressions", "members_reached"]) {
+        const v = finiteOrNull(m[key]);
+        if (v !== null)
+            return v;
+    }
+    return null;
+}
+/** Post-level metrics a platform can never report: platform -> metric key -> reason. */
+export const UNSUPPORTED_POST_METRICS = {
+    x: {
+        reach: "X does not report reach, only impressions.",
+    },
+    facebook: {
+        reach: "Facebook stopped reporting post reach in June 2026: Meta retired the metric and its replacement returns no data.",
+        saves: "Facebook does not report saves.",
+    },
+    instagram: {
+        clicks: "Instagram reports link clicks for stories only (link sticker taps).",
+        link_clicks: "Instagram reports link clicks for stories only (link sticker taps).",
+    },
+    linkedin_page: {
+        link_clicks: "LinkedIn Pages report total clicks only, not link clicks separately.",
+        saves: "LinkedIn Pages do not report saves.",
+    },
+    threads: {
+        reach: "Threads does not report reach for posts.",
+        clicks: "Threads reports link clicks at account level only, not per post.",
+        link_clicks: "Threads reports link clicks at account level only, not per post.",
+        saves: "Threads does not report saves.",
+    },
+    youtube: {
+        reach: "YouTube does not report reach, only views.",
+        clicks: "YouTube does not report clicks.",
+        link_clicks: "YouTube does not report clicks.",
+        saves: "YouTube does not report saves.",
+    },
+    tiktok: {
+        clicks: "TikTok reports bio link clicks at account level only, not per video.",
+        link_clicks: "TikTok reports bio link clicks at account level only, not per video.",
+    },
+    pinterest: {
+        reach: "Pinterest does not report reach, only impressions.",
+        shares: "Pinterest does not report shares.",
+    },
+    bluesky: {
+        impressions: "Bluesky does not report impressions or views.",
+        reach: "Bluesky does not report reach.",
+        clicks: "Bluesky does not report clicks.",
+        link_clicks: "Bluesky does not report clicks.",
+        video_views: "Bluesky does not report video views.",
+        engagement_rate: "Engagement rate needs impressions, which Bluesky does not report.",
+    },
+    mastodon: {
+        impressions: "Mastodon does not report impressions or views.",
+        reach: "Mastodon does not report reach.",
+        clicks: "Mastodon does not report clicks.",
+        link_clicks: "Mastodon does not report clicks.",
+        saves: "Mastodon does not report saves.",
+        video_views: "Mastodon does not report video views.",
+        engagement_rate: "Engagement rate needs impressions, which Mastodon does not report.",
+    },
+    google_business: {
+        impressions: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        reach: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        likes: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        comments: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        shares: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        saves: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        clicks: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        link_clicks: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        video_views: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        engagement: "Google discontinued per-post metrics for Business Profiles in 2023.",
+        engagement_rate: "Google discontinued per-post metrics for Business Profiles in 2023.",
+    },
+};
+/** Metrics unavailable for some post types only: platform -> content_type -> metric key -> reason. Empty since Facebook reach moved to the platform-wide map. */
+export const UNSUPPORTED_POST_METRICS_BY_CONTENT_TYPE = {};
+/** Reason `metricKey` is unavailable on `platform` (refined by `contentType`), or null when it is available. */
+export function unsupportedMetricReason(platform, metricKey, contentType) {
+    const typed = contentType ? UNSUPPORTED_POST_METRICS_BY_CONTENT_TYPE[platform]?.[contentType]?.[metricKey] : undefined;
+    if (typed)
+        return typed;
+    return UNSUPPORTED_POST_METRICS[platform]?.[metricKey] ?? null;
+}
+/** True when the platform can never report `metricKey` for this post; a finite stored value overrides the map. */
+export function isMetricUnsupported(platform, metricKey, metrics) {
+    const contentType = typeof metrics?.content_type === "string" ? metrics.content_type : undefined;
+    if (!unsupportedMetricReason(platform, metricKey, contentType))
+        return false;
+    if (metrics && finiteOrNull(metrics[metricKey]) !== null)
+        return false;
+    return true;
 }
 /**
  * Engagement rate as a percentage (0-100), suppressed below the impression

package/build/tools/analytics.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { formatNumber, capitalize, metricRows, metricBreakdownRows, sortMetricLabels } from "../client.js";
 import { getEngagement, getImpressions, getEngagementRate, MIN_IMPRESSIONS_FOR_ENGAGEMENT_RATE, } from "../metrics.js";
 export function registerAnalyticsTools(server, getClient) {
-    server.tool("get_post_analytics", "Get analytics/statistics for a specific published post. Renders every metric the platform reported — impressions, reach, views, saves, likes, comments, shares, clicks, engagements, and more — per platform. TikTok videos also carry average_time_watched, full_video_watched_rate, total_time_watched, favorites and reach when the workspace enabled TikTok comments (Business API authorization).", {
+    server.tool("get_post_analytics", "Get analytics/statistics for a specific published post. Renders every metric the platform reported per platform: impressions, reach, views, saves, likes, comments, shares, clicks, link_clicks, engagements, and more. A missing key means the platform does not report it: reach is absent (not 0) on X, Pinterest, YouTube, Threads, Bluesky, Mastodon and Facebook (Meta retired Facebook post reach in June 2026 and its replacement metric returns no data; a Facebook row collected before 2026-09-27 may still carry reach: 0, treat it as absent); link_clicks (clicks on links in the post) exists for X posts under 30 days, LinkedIn profile, Facebook feed posts, Pinterest and Instagram stories, while clicks is the platform's broadest click count. TikTok videos also carry average_time_watched, full_video_watched_rate, total_time_watched, favorites and reach when the workspace enabled TikTok comments (Business API authorization).", {
         post_id: z.string().describe("The numeric OmniSocials post id (the `id` field from list_posts). NOT a platform post id such as a YouTube video id or tweet id."),
     }, { title: "Get Post Analytics", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ post_id }) => {
         const result = await getClient().getPostAnalytics(post_id);

package/build/tools/inbox.js

@@ -80,11 +80,15 @@ function renderNextUnanswered(result) {
     const c = item.conversation;
     const who = c.participant?.name || c.participant?.username || "Unknown";
     let md = `## Next: ${PLATFORM_EMOJI[c.platform] || ""} ${c.platform} ${c.type} from ${who}\n\n`;
-    md += `Conversation ID: \`${c.conversation_id}\`\nMessage to answer: \`#${item.message.id}\`\n\n`;
+    md += `Conversation ID: \`${c.conversation_id}\`\nMessage to answer: \`#${item.message.id}\` (pass it as message_id when replying)\n\n`;
+    if (item.reply_window?.open === false) {
+        const app = c.platform === "instagram" ? "Instagram" : "Facebook";
+        md += `⚠️ **Meta's 24-hour reply window for this DM closed ${formatDateTime(item.reply_window.closes_at)}.** OmniSocials cannot send a reply here (reply_to_inbox answers 422 outside_messaging_window). Tell the user to answer it from the ${app} app; that reply is mirrored into the inbox and clears this item. Or mark_inbox_read to skip it.\n\n`;
+    }
     md += renderInboxPost(item.message.post || c.post);
     md += renderInboxMessages(item.messages, item.message.id);
     md += `_${result.remaining || 0} more waiting._\n\n`;
-    md += `_Reply: reply_to_inbox with the conversation ID (add include_next: true to get the next one in the same call). Skip for good: mark_inbox_read. Comments: hide_inbox_comment / delete_inbox_comment with the message id._`;
+    md += `_Reply: reply_to_inbox with the conversation ID and message_id: "${item.message.id}" (add include_next: true to get the next one in the same call). Skip for good: mark_inbox_read. Comments: hide_inbox_comment / delete_inbox_comment with the message id._`;
     return md;
 }
 export function registerInboxTools(server, getClient) {
@@ -104,7 +108,7 @@ export function registerInboxTools(server, getClient) {
         unanswered: z
             .boolean()
             .optional()
-            .describe("Only conversations that still need an answer: the customer's latest DM has no reply after it (Instagram/Facebook DMs within the 24-hour reply window), or a comment/mention nobody replied to and that is not hidden. Replies typed in the native apps count as answers."),
+            .describe("Only conversations that still need an answer: the customer's latest DM has no reply after it (Instagram/Facebook DMs past the 24-hour reply window included; they cannot be answered through the API but the customer is still waiting), or a comment/mention nobody replied to and that is not hidden. Replies typed in the native apps count as answers."),
         limit: z
             .number()
             .optional()
@@ -201,8 +205,12 @@ export function registerInboxTools(server, getClient) {
             ],
         };
     });
-    server.tool("reply_to_inbox", "Reply to an existing inbox conversation (DM, comment, or mention) on Instagram, Facebook, LinkedIn, TikTok, YouTube, X, or Threads. You can only reply to conversations that already exist. Meta direct-message replies must be within the platform's 24-hour messaging window. TikTok replies are comments only, text-only, and capped at 150 characters; they can take a few minutes to appear on TikTok while they pass spam review. YouTube replies are comments only. Threads replies are on the workspace's posts and mentions; a 401 reauth_required means the Threads connection must be reconnected to grant the reply permission. X replies are DM-only and use 2 prepaid credits per send (X's API fee passed through at cost); a 402 insufficient_credits error means the organisation needs to top up at https://app.omnisocials.com/credits; relay that link to the user rather than retrying. Each workspace can send up to 1,000 replies per day. attachment_url/attachment_type let you send media on a Facebook or Instagram DM (text is optional when an attachment is set); other platforms are text-only. Set include_next: true to get the next conversation that needs an answer back in the same call (same as get_next_unanswered), so the inbox can be worked through as: get_next_unanswered → draft → reply_to_inbox(include_next) → draft → repeat.", {
+    server.tool("reply_to_inbox", "Reply to an existing inbox conversation (DM, comment, or mention) on Instagram, Facebook, LinkedIn, TikTok, YouTube, X, or Threads. You can only reply to conversations that already exist. For a comment or mention, pass message_id (the #id of the comment being answered): comments on one post share a conversation and without it the reply goes under the newest comment on the post. Meta direct-message replies must be within the platform's 24-hour messaging window: a 422 outside_messaging_window means the window has closed, nothing was sent, and the user must answer that DM from the Instagram or Facebook app (mirrored into the inbox) or skip it with mark_inbox_read; do not retry. TikTok replies are comments only, text-only, and capped at 150 characters; they can take a few minutes to appear on TikTok while they pass spam review. YouTube replies are comments only. Threads replies are on the workspace's posts and mentions; a 401 reauth_required means the Threads connection must be reconnected to grant the reply permission. X replies are DM-only and use 2 prepaid credits per send (X's API fee passed through at cost); a 402 insufficient_credits error means the organisation needs to top up at https://app.omnisocials.com/credits; relay that link to the user rather than retrying. Each workspace can send up to 1,000 replies per day. attachment_url/attachment_type let you send media on a Facebook or Instagram DM (text is optional when an attachment is set); other platforms are text-only. Set include_next: true to get the next conversation that needs an answer back in the same call (same as get_next_unanswered), so the inbox can be worked through as: get_next_unanswered → draft → reply_to_inbox(include_next) → draft → repeat. A 409 duplicate_reply means this exact reply already went out to this conversation in the last 10 minutes (an earlier call that looked slow or failed did succeed) or is being sent right now: nothing was sent again, do NOT retry it — continue with get_next_unanswered. A 422 reply_not_allowed means the platform refuses replies to this item for good (Facebook #1705: the comment sits on a share or boosted copy of the post, or the commenter restricts replies; YouTube: the thread's canReply is false because comments are off on the video or the comment was removed or held for review): the item is dropped from get_next_unanswered automatically, tell the user, and do NOT retry.", {
         conversation_id: z.string().describe("The conversation ID to reply to"),
+        message_id: z
+            .string()
+            .optional()
+            .describe("For comment/mention threads: the inbox id of the comment you are answering (the 'Message to answer' #id from get_next_unanswered, or a #id from get_inbox_conversation). Every comment on a post shares one conversation, so without it the reply is posted under the newest comment on the post, which can be a different person than the one you drafted for. Always pass it for comments. Ignored for DMs."),
         text: z
             .string()
             .optional()
@@ -219,9 +227,10 @@ export function registerInboxTools(server, getClient) {
             .boolean()
             .optional()
             .describe("After sending, also return the next conversation that needs an answer (full thread + post context), or 'nothing waiting'"),
-    }, { title: "Reply to Inbox Message", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ conversation_id, text, attachment_url, attachment_type, include_next }) => {
+    }, { title: "Reply to Inbox Message", readOnlyHint: false, destructiveHint: true, openWorldHint: true }, async ({ conversation_id, message_id, text, attachment_url, attachment_type, include_next }) => {
         const result = await getClient().replyToInboxConversation(conversation_id, {
             text: text ?? "",
+            ...(message_id ? { message_id } : {}),
             attachment_url,
             attachment_type,
             ...(include_next ? { include_next: true } : {}),
@@ -240,7 +249,7 @@ export function registerInboxTools(server, getClient) {
         }
         return { content: [{ type: "text", text: md }] };
     });
-    server.tool("get_next_unanswered", "Get the next inbox item that needs an answer, with the whole conversation and the post it is on, in one call. Serves the longest-waiting item first: the customer's latest DM with no reply after it (Instagram/Facebook DMs within the 24-hour reply window only, since Meta refuses later replies), or a comment/mention nobody replied to and that is not hidden. Replies typed in the native apps count as answered (they are mirrored into the inbox), so a thread a colleague answered on their phone is not served again. Instagram mentions are skipped (no reply path). Only unread items are served by default: to skip one for good, mark_inbox_read it; pass include_read to also see read-but-unanswered items. Looks back 30 days. Loop: get_next_unanswered → draft a reply → reply_to_inbox with include_next: true → repeat until nothing is waiting.", {
+    server.tool("get_next_unanswered", "Get the next inbox item that needs an answer, with the whole conversation and the post it is on, in one call. An item needs an answer when it is the customer's latest DM with no reply after it, or a comment/mention nobody replied to and that is not hidden. Order: DMs that can still be answered first (Instagram/Facebook DMs inside Meta's 24-hour window, the one closing soonest first, plus X DMs), then Instagram/Facebook DMs whose window has closed (reply_window.open = false: OmniSocials cannot reply, tell the user to answer from the native app or skip with mark_inbox_read), then comments and mentions, oldest first. Replies typed in the native apps count as answered (they are mirrored into the inbox), so a thread a colleague answered on their phone is not served again. Instagram mentions are skipped (no reply path). Only unread items are served by default: to skip one for good, mark_inbox_read it; pass include_read to also see read-but-unanswered items. Looks back 30 days. Loop: get_next_unanswered → draft a reply → reply_to_inbox with the conversation id, message_id = the served message's #id, and include_next: true → repeat until nothing is waiting.", {
         platform: z
             .enum(INBOX_PLATFORMS)
             .optional()
@@ -252,7 +261,7 @@ export function registerInboxTools(server, getClient) {
         order: z
             .enum(["oldest", "newest"])
             .optional()
-            .describe("oldest (default): the item that has waited longest first; newest: the most recent first"),
+            .describe("oldest (default): the item that has waited longest first; newest: the most recent first. Applies within each group (answerable DMs, then expired Instagram/Facebook DMs, then comments); the groups keep their order"),
         include_read: z
             .boolean()
             .optional()
@@ -307,7 +316,7 @@ export function registerInboxTools(server, getClient) {
             ],
         };
     };
-    server.tool("hide_inbox_comment", "Hide (or unhide) a comment someone left on one of the workspace's posts, on the platform, as the post owner. Facebook, Instagram, TikTok, YouTube and Threads comments. On YouTube, hide sets the comment to 'rejected' (removed from public view together with its replies) and unhide publishes it again. Takes the message id (the #id shown by get_inbox_conversation and get_next_unanswered), not the conversation id. A hidden comment no longer counts as unanswered. If the comment was already deleted on the platform (its author removed it, etc.), this still succeeds — the response says so — and the item is marked handled; do not retry it. A 403 reconnect_required means the account was connected without the comment-moderation permission and must be reconnected in the dashboard; relay that to the user rather than retrying.", hideCommentSchema, { title: "Hide Inbox Comment", readOnlyHint: false, destructiveHint: false, openWorldHint: true }, hideComment);
+    server.tool("hide_inbox_comment", "Hide (or unhide) a comment someone left on one of the workspace's posts, on the platform, as the post owner. Facebook, Instagram, TikTok, YouTube and Threads comments. On YouTube, hide sets the comment to 'rejected' (removed from public view together with its replies) and unhide publishes it again. Takes the message id (the #id shown by get_inbox_conversation and get_next_unanswered), not the conversation id. A hidden comment no longer counts as unanswered. If the comment was already deleted on the platform (its author removed it, etc.), this still succeeds — the response says so — and the item is marked handled; do not retry it. A 403 reconnect_required means the account was connected without the comment-moderation permission and must be reconnected in the dashboard; relay that to the user rather than retrying. A 422 cannot_hide means Facebook does not let the Page hide this particular comment (the commenter blocked the Page, their account is deactivated or restricted, or the comment sits on a shared copy of the post): retrying never changes it — tell the user, and use mark_inbox_read on the conversation if it should stop coming up. A 502 hide_not_applied means Instagram accepted the call but still reports the comment as visible (this happens with comments shown under 'Comments from Facebook' on a reel shared to Facebook; they live on Facebook and Instagram's hide does not reach them): nothing changed in the inbox, tell the user to hide it in the Instagram or Facebook app, do not retry.", hideCommentSchema, { title: "Hide Inbox Comment", readOnlyHint: false, destructiveHint: false, openWorldHint: true }, hideComment);
     // Older name from 1.28.0 (when hiding was Threads-only). Kept so existing
     // setups keep working; same call, same platforms as hide_inbox_comment.
     server.tool("hide_inbox_reply", "Older name for hide_inbox_comment, kept so existing setups keep working; prefer hide_inbox_comment. Same behaviour: hide (or unhide with hide: false) a comment someone left on one of the workspace's posts, as the post owner, on Facebook, Instagram, TikTok, YouTube or Threads. Takes the message id (the #id in the thread), not the conversation id. A 403 reconnect_required means the account must be reconnected in the dashboard to grant the comment-moderation permission.", hideCommentSchema, { title: "Hide Inbox Comment (older name)", readOnlyHint: false, destructiveHint: false, openWorldHint: true }, hideComment);

package/build/tools/media.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { fetchImageAsBase64, formatBytes } from "../client.js";
 export function registerMediaTools(server, getClient) {
-    server.tool("list_media", "List media files in the workspace. Returns each file's ID, name, folder, type (image/video), and size. To reuse an existing graphic, SEARCH for it by name here FIRST instead of re-uploading — re-uploading the same image creates duplicates. Media IDs from this list can be passed to create_post. Organize assets into folders with create_folder / list_folders.", {
+    server.tool("list_media", "List media files in the workspace. Returns each file's ID, name, folder, type (image/video/document — a document is a PDF kept as one item; its ID in media_ids expands into every page), and size. To reuse an existing graphic, SEARCH for it by name here FIRST instead of re-uploading — re-uploading the same image creates duplicates. Media IDs from this list can be passed to create_post. Organize assets into folders with create_folder / list_folders.", {
         limit: z.string().optional().describe("Max results to return"),
         offset: z.string().optional().describe("Offset for pagination"),
         search: z.string().optional().describe('Find a file by name or filename, e.g. "play5get50". Use this before uploading to check if the graphic already exists.'),
@@ -30,7 +30,16 @@ export function registerMediaTools(server, getClient) {
             // `type` may be "video"/"image" (normalized) or a raw MIME like "video/mp4".
             const rawType = typeof m.type === "string" ? m.type : "";
             const isVideo = rawType === "video" || rawType.startsWith("video/");
-            const type = isVideo ? "Video" : "Image";
+            const isDocument = rawType === "document";
+            // A PDF document item names its page count (pass its ONE id and the
+            // post gets every page); a slide rendered from a PDF names its file
+            // and page, so the assistant can pass the whole deck in order.
+            const pdfTag = m.pdf
+                ? isDocument
+                    ? ` (PDF, ${Array.isArray(m.pdf.pages) ? m.pdf.pages.length : m.pdf.rendered_pages} pages)`
+                    : ` (PDF ${m.pdf.name ? `"${m.pdf.name}" ` : ""}page ${m.pdf.page}/${m.pdf.total_pages})`
+                : "";
+            const type = (isVideo ? "Video" : isDocument ? "Document" : "Image") + pdfTag;
             const folder = m.folder_id ? `\`${m.folder_id}\`` : "—";
             md += `| ${i + 1} | ${type} | ${m.name || m.filename || "—"} | ${folder} | ${(m.size || "—")} | \`${m.id}\` |\n`;
         }
@@ -57,7 +66,7 @@ export function registerMediaTools(server, getClient) {
     });
     server.tool("upload_media", `Upload media to the library. Accepts EITHER a public URL OR base64-encoded image data (e.g. when the user pastes an image directly in chat). Supported: JPEG, PNG, GIF, WebP, MP4, MOV, AVI, and PDF.
 
-PDF = carousel: upload a PDF (as a 'url' or as base64_data with mime_type "application/pdf") and it is split into one image slide per page (max 20 pages). The response lists a Media ID for every slide — pass ALL of them, in order, as media_ids to create_post to post the deck as a carousel. On LinkedIn the slides post as a native swipeable DOCUMENT; on Instagram, TikTok, Threads and Pinterest as an image carousel. This is the way to let a user post an existing slide deck (Canva/PowerPoint/Figma exported to PDF) as a carousel.
+PDF = carousel: upload a PDF (as a 'url' or as base64_data with mime_type "application/pdf") and it is split into one image slide per page (max 20 pages). The response lists a Media ID for every slide — pass ALL of them, in order, as media_ids to create_post to post the deck as a carousel. Prefer pdf_mode "document" when the user wants ONE library item for the deck: the response then has a single Media ID whose media_ids entry expands into every page at post time. On LinkedIn the slides post as a native swipeable DOCUMENT made from the ORIGINAL PDF file (the file is kept: text stays sharp, in-document links work, viewers download the real file, and every page is included even past the 20-slide cap) as long as the slides are posted unchanged and in order; on Instagram, TikTok, Threads and Pinterest as an image carousel. Set linkedin.document_source to 'slides' on the post to send a document rebuilt from the slide images instead. This is the way to let a user post an existing slide deck (Canva/PowerPoint/Figma exported to PDF) as a carousel.
 
 Size limits: base64 and direct uploads are capped at 100 MB (and base64 inflates the request body, so the practical ceiling is ~75 MB). For anything larger — up to 1 GB — use ONE of: (a) pass a public 'url' and the server fetches it (handles up to 1 GB), or (b) have the user upload the file in the OmniSocials Library UI at https://app.omnisocials.com/library . IMPORTANT: if the user has a large LOCAL file (over ~100 MB) with no public URL, do NOT tell them to compress or shrink it — instead point them to the Library UI link above, which uploads files up to 1 GB directly.
 
@@ -72,6 +81,7 @@ When the user provides an image in the conversation (not a URL), use base64_data
         filename: z.string().optional().describe("Optional filename for the uploaded media"),
         name: z.string().optional().describe('Human-readable label so you can find this asset by name later instead of re-uploading it, e.g. "pp-play5get50". Strongly recommended on every upload.'),
         folder: z.string().optional().describe('Optional folder name to file this asset under (created at the top level if it does not exist), e.g. "win-graphics". See list_folders.'),
+        pdf_mode: z.enum(["slides", "document"]).optional().describe('PDF uploads only. "slides" (default): one image media item per page, one Media ID each (pass ALL of media_ids to create_post). "document": ONE media item for the whole PDF (type "document"); pass its single Media ID in media_ids and the post gets every page in order. Both keep the original file, which LinkedIn receives. Prefer "document" when the user wants one library item for the deck.'),
     }, { title: "Upload Media", readOnlyHint: false, destructiveHint: false, openWorldHint: true }, async (params) => {
         let result;
         if (params.base64_data && params.mime_type) {
@@ -81,10 +91,17 @@ When the user provides an image in the conversation (not a URL), use base64_data
                 filename: params.filename,
                 name: params.name || params.filename,
                 folder: params.folder,
+                ...(params.pdf_mode ? { pdf_mode: params.pdf_mode } : {}),
             });
         }
         else if (params.url) {
-            result = await getClient().uploadMedia({ url: params.url, filename: params.filename, name: params.name || params.filename, folder: params.folder });
+            result = await getClient().uploadMedia({
+                url: params.url,
+                filename: params.filename,
+                name: params.name || params.filename,
+                folder: params.folder,
+                ...(params.pdf_mode ? { pdf_mode: params.pdf_mode } : {}),
+            });
         }
         else {
             return {
@@ -97,6 +114,23 @@ When the user provides an image in the conversation (not a URL), use base64_data
             };
         }
         const compatibility = result.compatibility;
+        // PDF kept as ONE document item (pdf_mode "document").
+        if (result.data?.type === "document" && result.pdf) {
+            const d = result.data;
+            const pdfInfo = result.pdf;
+            const pageCount = Array.isArray(d.pdf?.pages) ? d.pdf.pages.length : pdfInfo.rendered_pages;
+            let md = `## PDF Uploaded as One Document\n\n`;
+            md += `**${d.name || pdfInfo.name || "document.pdf"}**, ${pageCount} ${pageCount === 1 ? "page" : "pages"}`;
+            if (pdfInfo.truncated)
+                md += ` (${pdfInfo.total_pages} in the file; the first ${pdfInfo.rendered_pages} became page images)`;
+            md += `.\n\n**Media ID:** \`${d.id}\`\n\n`;
+            md += `Pass this ONE id in \`create_post\` as \`media_ids: ["${d.id}"]\`; the post gets every page, in order. `;
+            md += `On LinkedIn it posts as a swipeable **document** made from the **original PDF file** (sharp text, working links, the real download); on Instagram, TikTok, Threads and Pinterest as an **image** carousel. Platforms that do not support carousels use the first page.`;
+            if (compatibility && compatibility.compatible === false && compatibility.summary) {
+                md += `\n\n⚠️ **${compatibility.summary}** It will still post to your other connected platforms. Ask the user whether to continue before posting.`;
+            }
+            return { content: [{ type: "text", text: md }] };
+        }
         // PDF upload: the server split it into image slides. Surface every slide
         // id and tell the model to pass them ALL to create_post as one carousel.
         const mediaIds = result.media_ids;
@@ -115,7 +149,7 @@ When the user provides an image in the conversation (not a URL), use base64_data
             });
             md += `\n**Pass ALL of these to \`create_post\` as \`media_ids\`, in this order**, to post the deck as a carousel:\n\n`;
             md += `\`\`\`\nmedia_ids: [${mediaIds.map((id) => `"${id}"`).join(", ")}]\n\`\`\`\n\n`;
-            md += `On LinkedIn this posts as a swipeable **document** carousel; on Instagram, TikTok, Threads and Pinterest as an **image** carousel. Platforms that do not support carousels use the first slide.`;
+            md += `On LinkedIn this posts as a swipeable **document** carousel made from the **original PDF file** (kept in storage: sharp text, working links, the real download${pdf?.truncated ? `, all ${pdf.total_pages} pages` : ""}) as long as the slides are posted unchanged and in order; on Instagram, TikTok, Threads and Pinterest as an **image** carousel. Platforms that do not support carousels use the first slide. To send a document rebuilt from the slide images instead, set linkedin.document_source to "slides" on the post.`;
             if (compatibility && compatibility.compatible === false && compatibility.summary) {
                 md += `\n\n⚠️ **${compatibility.summary}** It will still post to your other connected platforms. Ask the user whether to continue before posting.`;
             }