@omnisocials/mcp-server 1.34.1 → 1.39.0

package/build/tools/posts.js

@@ -60,9 +60,35 @@ const FACEBOOK_OPTIONS = z
         .max(8000)
         .optional()
         .describe("Text auto-posted as the first comment on the Facebook post right after it publishes. Page posts only (the API cannot comment on personal-profile posts). Not posted for Stories."),
+    thumbnail_type: z
+        .enum(["from-video", "from-library"])
+        .nullable()
+        .optional()
+        .describe("Video thumbnail for Facebook feed videos and reels: 'from-video' uses the frame at thumb_offset, 'from-library' uploads the image at cover_url. Applied after the video is live; a thumbnail failure never fails the post. On update_post, null removes the Facebook override."),
+    thumb_offset: z
+        .number()
+        .optional()
+        .describe("Frame timestamp in MILLISECONDS from the start of the video (e.g. 3000 = 0:03). Used with thumbnail_type 'from-video'."),
+    cover_url: z
+        .string()
+        .optional()
+        .describe("Custom thumbnail image URL (JPEG/PNG, max 10 MB). Used with thumbnail_type 'from-library'."),
 })
     .optional()
     .describe("Facebook options");
+const VIDEO_COVER_ENTRY = z.object({
+    type: z.enum(["frame", "custom"]).describe("'frame' uses the video frame at thumb_offset; 'custom' uploads the image at cover_url."),
+    thumb_offset: z.number().int().min(0).optional().describe("Milliseconds into the video (type 'frame'). 3000 = 0:03."),
+    cover_url: z.string().optional().describe("Public image URL, JPEG or PNG (type 'custom')."),
+});
+const VIDEO_COVER_OPTIONS = VIDEO_COVER_ENTRY.extend({
+    overrides: z
+        .record(z.string(), VIDEO_COVER_ENTRY.nullable())
+        .optional()
+        .describe("Per-platform overrides keyed by platform id (instagram, facebook, linkedin, linkedin_page, tiktok, pinterest, youtube). An override wins over the base cover for that platform."),
+})
+    .optional()
+    .describe("Video thumbnail for a post whose media is ONE video. Applied on Instagram (feed videos and reels), Facebook (feed videos and reels), LinkedIn Profile and Page, TikTok, Pinterest and YouTube Shorts. YouTube Shorts: the cover shows on Shorts only on channels where YouTube has enabled custom Shorts thumbnails (rolling out since July 2026, Partner Program channels first); on other channels YouTube stores it as the default thumbnail but shows a frame from the video on Shorts. Say that it depends on the channel; do not promise it. TikTok only takes a frame: a 'custom' cover is skipped there, so add a tiktok override with type 'frame' when the user wants a specific TikTok frame. The per-platform reel fields (instagram.thumb_offset / cover_url, tiktok.video_cover_timestamp_ms, pinterest.video_cover) keep working and win over the base cover for their platform. get_post reads it back as `video_cover`.");
 const LINKEDIN_OPTIONS = z
     .object({
     first_comment: z
@@ -75,6 +101,11 @@ const LINKEDIN_OPTIONS = z
         .nullable()
         .optional()
         .describe("Multi-image style for the profile post. By default 2+ images publish as LinkedIn's swipeable PDF document carousel; true publishes them as a plain multi-image gallery instead. Ignored for 0-1 images, videos, and polls. On update_post: true sets it, false/null reverts to the document carousel, omitted keeps the current value."),
+    document_source: z
+        .enum(["original_pdf", "slides"])
+        .nullable()
+        .optional()
+        .describe("Where the profile post's document carousel comes from when its images are exactly the rendered pages of one uploaded PDF (unchanged, in order). 'original_pdf' (default): LinkedIn receives the kept original PDF file: sharp text, working in-document links, the real download, every page even past the 20-slide cap. 'slides': rebuild the document from the slide images (a flattened copy). Ignored when the images are not a PDF's pages, when carousel_as_images is true, for 0-1 images, videos and polls. On update_post: 'slides' sets it, 'original_pdf'/null reverts to the default, omitted keeps the current value."),
 })
     .optional()
     .describe("LinkedIn Profile options");
@@ -90,6 +121,11 @@ const LINKEDIN_PAGE_OPTIONS = z
         .nullable()
         .optional()
         .describe("Multi-image style for the company-page post. By default 2+ images publish as LinkedIn's swipeable PDF document carousel; true publishes them as a plain multi-image gallery instead. Ignored for 0-1 images, videos, and polls. On update_post: true sets it, false/null reverts to the document carousel, omitted keeps the current value."),
+    document_source: z
+        .enum(["original_pdf", "slides"])
+        .nullable()
+        .optional()
+        .describe("Same as linkedin.document_source, for the company-page post: 'original_pdf' (default) sends the kept original PDF when the images are its unchanged pages; 'slides' rebuilds the document from the slide images. On update_post: 'slides' sets it, 'original_pdf'/null reverts, omitted keeps the current value."),
 })
     .optional()
     .describe("LinkedIn Company Page options");
@@ -148,6 +184,7 @@ const PINTEREST_OPTIONS = z.object({
     link: z.string().optional().describe("Destination URL the pin clicks through to"),
     video_cover: z.string().optional().describe("Cover image URL for video pins (JPEG/PNG). Falls back to a video keyframe if omitted."),
     alt_text: z.string().optional().describe("Accessibility alt text for the pin image (max 500 characters)"),
+    product_tags: z.array(z.string()).max(24).optional().describe("Products to tag on the Pin, so people can shop the items in the image. Up to 24 product Pins of the connected Pinterest account, each as a Pin ID string or a Pin link (https://www.pinterest.com/pin/<id>/). Get the IDs with list_pinterest_products. Only the account's own product Pins can be tagged (public, with a link on a website the account claimed on Pinterest); products of other merchants cannot. The tags are added right after the Pin is published; a product Pinterest refuses never fails the post, and get_post shows the outcome (product_tags_result). On update_post the pinterest object replaces the stored one, so leave product_tags out to remove the tags."),
 }).optional().describe("Pinterest-specific options. Attach 2–5 images via media_urls.pinterest (or default) to publish a single carousel pin instead of separate pins. More than 5 images is rejected with a 400 validation_error at create/schedule time — carousels hard-cap at 5. Carousel slides MUST share the same aspect ratio (1% tolerance) — the API returns 400 validation_error with `mismatched_slides: [n, ...]` if you pass mixed-ratio images and try to schedule or publish. Drafts are exempt so you can iterate.");
 // One Instagram photo tag. The wrapping z.array(...).describe(...) stays
 // per-tool because update_post documents replace/clear semantics.
@@ -601,20 +638,67 @@ export function registerPostTools(server, getClient) {
             optionRows.push(["Pinterest title", pin.title]);
         if (typeof pin.link === "string" && pin.link)
             optionRows.push(["Pinterest link", pin.link]);
+        if (Array.isArray(pin.product_tags) && pin.product_tags.length) {
+            optionRows.push(["Pinterest product tags", pin.product_tags.join(", ")]);
+        }
+        // Outcome of the tag step, written after the Pin is live.
+        const tagResult = pin.product_tags_result;
+        if (tagResult && typeof tagResult === "object") {
+            const skipped = (tagResult.skipped || []).map((item) => `${item.pin_id} ${item.reason}`).join(", ");
+            optionRows.push([
+                "Pinterest products tagged",
+                `${(tagResult.tagged || []).length} of ${tagResult.requested ?? 0}${skipped ? ` (not tagged: ${skipped})` : ""}${tagResult.error ? ` (Pinterest: ${tagResult.error})` : ""}`,
+            ]);
+        }
+        // Cross-platform video cover (base + per-platform overrides).
+        const describeCover = (c) => {
+            if (!c || typeof c !== "object")
+                return null;
+            const entry = c;
+            if (entry.type === "frame") {
+                const ms = Number(entry.thumb_offset) || 0;
+                return `video frame at ${ms} ms (${(ms / 1000).toFixed(1)}s into the video)`;
+            }
+            if (entry.type === "custom" && typeof entry.cover_url === "string")
+                return `custom image ${entry.cover_url}`;
+            return null;
+        };
+        const vc = p.video_cover;
+        const baseCover = describeCover(vc);
+        if (baseCover)
+            optionRows.push(["Video cover", baseCover]);
+        const coverOverrides = vc && typeof vc === "object" ? vc.overrides : null;
+        if (coverOverrides && typeof coverOverrides === "object") {
+            for (const [platform, entry] of Object.entries(coverOverrides)) {
+                const text = describeCover(entry);
+                if (text)
+                    optionRows.push([`Video cover (${platform})`, text]);
+            }
+        }
+        const fbCoverMs = Number(p.facebook?.thumb_offset) || 0;
+        const fbCoverUrl = p.facebook?.cover_url;
+        if (!coverOverrides?.facebook && (fbCoverMs > 0 || typeof fbCoverUrl === "string")) {
+            optionRows.push(["Facebook cover", typeof fbCoverUrl === "string" ? `custom image ${fbCoverUrl}` : `video frame at ${fbCoverMs} ms`]);
+        }
         if (optionRows.length) {
             md += `\n\n### Platform Options\n\n| Option | Value |\n|--------|-------|\n`;
             for (const [k, v] of optionRows)
                 md += `| ${k} | ${v.replace(/\|/g, "\\|")} |\n`;
         }
-        // LinkedIn multi-image style: nested under each channel's options
-        // object by the API. Only rendered when the post opts out of the
-        // default PDF document carousel.
+        // LinkedIn multi-image style + document source: nested under each
+        // channel's options object by the API. Only rendered when the post
+        // opts out of a default (document carousel; kept original PDF).
         for (const channel of ["linkedin", "linkedin_page"]) {
             const opts = p[channel];
-            if (opts && typeof opts === "object" && opts.carousel_as_images === true) {
-                const label = channel === "linkedin_page" ? "LinkedIn Page" : "LinkedIn Profile";
+            if (!opts || typeof opts !== "object")
+                continue;
+            const label = channel === "linkedin_page" ? "LinkedIn Page" : "LinkedIn Profile";
+            if (opts.carousel_as_images === true) {
                 md += `\n\n**${label} multi-image style:** plain image gallery (default is the swipeable PDF document carousel)\n`;
             }
+            if (opts.document_source === "slides") {
+                md += `\n\n**${label} document source:** rebuilt from the slide images (default sends the kept original PDF when the images are its unchanged pages)\n`;
+            }
         }
         // Trial Reel state: nested under the instagram options object by the
         // API. Only rendered when enabled, so batch-scheduled Trial Reels can be
@@ -673,7 +757,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
 
    **Per-platform video caps (duration + size, checked via ffprobe at submit; exceeding either returns a 400 validation_error stating the exact cap and the file's value, e.g. "X only allows videos up to 2min 20s; yours is 2min 35s. Trim the video or deselect X."):**
    - X — **140s (2min 20s)** · **512MB** on free/Basic accounts; when the connected X account has **Premium or Premium+** the caps rise to **125min / 16GB** automatically (tier is read from the connection; reconnect X after upgrading). X also can't mix a video with images in one tweet: a tweet is either 1 video OR up to 4 images
-   - Bluesky 180s · Threads 5min · Instagram 15min · TikTok 10min · YouTube Short 3min · LinkedIn 10min · Pinterest 15min · Facebook Reel 90s
+   - Bluesky 180s · Threads 5min · Instagram 15min · TikTok 10min · YouTube Short 3min · LinkedIn 10min · Pinterest 15min · Facebook 240min (Post + Reel; the old 90s Reel cap is gone)
    Pick a file within the cap up front; if the user's video is over, tell them the limit so they can trim it rather than retrying blindly.
 
    When attaching more than these caps to a selected platform, EITHER trim the array OR move to a flat \`media_urls: [...]\` and let the user know which platform will be over the limit so they can split into multiple posts.
@@ -687,7 +771,7 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
    - TikTok: Privacy level?
    - **X threads vs long-form**: A chained "thread" (the user explicitly asks for one) → pass \`x.thread_parts\` as an array of 2–25 \`{ text }\` objects (each ≤ 280 chars on free/Basic, 25,000 on Premium/Premium+); the \`content\` field is then ignored for X. A single **long-form** post on a Premium / Premium+ account → just put the full text (up to 25,000 chars) in \`content\` — no threading needed (check \`platform_details.subscription_type\` via list_accounts). On free / Basic, X caps a single post at 280 chars, so either split into a thread or shorten. Never cram "1/", "2/" prefixes into \`content\` — that posts one tweet, not a thread.
    - **Bluesky, Mastodon and Threads chains**: the same \`thread_parts\` shape works under \`bluesky\`, \`mastodon\` and \`threads\` (each an array of 2 to 25 \`{ text, media_ids?, media_urls? }\` objects); parts after the first publish as replies to the previous part and \`content\` is then ignored for that platform. Threads: 2 to 25 parts, 500 characters per part, up to 10 media per part (images and videos can be mixed). Bluesky: 300 characters per part, 4 media. Mastodon: 500 characters per part (instance-dependent), 4 media.
-   - **X posts containing a link cost credits**: X's API bills posts whose text contains a URL at a premium, and OmniSocials passes that through as prepaid credits at X's exact rate (20 credits ≈ $0.20 per URL-containing tweet; threads are charged per part that contains a link). The create response includes a \`warnings\` entry (\`x_url_post_credits\`) with the cost and current balance — relay it to the user. Credits are only deducted after the post successfully publishes; a failed publish is never charged. If the balance can't cover it at publish time, only the X target fails (message says to top up at https://app.omnisocials.com/credits) and the post can be retried after topping up. Posts without links stay free — never remove a user's link to dodge the fee without asking them. Scheduling is also gated up front: every scheduled X link post reserves its cost, and a create/schedule that would push the reserved total past the balance is refused with a 402 \`x_credits_insufficient\` error (details carry credits_required / credits_balance / credits_reserved) — tell the user to top up or remove the link, don't silently retry.
+   - **X posts containing a link cost credits**: X's API bills posts whose text contains a URL at a premium, and OmniSocials passes that through as prepaid credits at X's exact rate (20 credits ≈ $0.20 per URL-containing tweet; threads are charged per part that contains a link). Only a link written with http:// or https:// counts; a bare domain (brand.com) or a www. link is free. The create response includes a \`warnings\` entry (\`x_url_post_credits\`) with the cost and current balance — relay it to the user. Credits are only deducted after the post successfully publishes; a failed publish is never charged. If the balance can't cover it at publish time, only the X target fails (message says to top up at https://app.omnisocials.com/credits) and the post can be retried after topping up. Posts without links stay free — never remove a user's link to dodge the fee without asking them. Scheduling is also gated up front: every scheduled X link post reserves its cost, and a create/schedule that would push the reserved total past the balance is refused with a 402 \`x_credits_insufficient\` error (details carry credits_required / credits_balance / credits_reserved) — tell the user to top up or remove the link, don't silently retry.
 
 Do NOT call this tool without media when creating stories, reels, Instagram posts, TikTok posts, or Pinterest posts — it will fail.
 
@@ -698,7 +782,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         media_ids: z.union([
             z.array(mediaIdEntry),
             z.record(z.string(), z.array(mediaIdEntry)),
-        ]).optional().describe("Media IDs from upload — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...] }. Each entry is a plain ID string or { id, alt } to attach alt text (accessibility description, max 1500 chars) to that file — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images)."),
+        ]).optional().describe("Media IDs from upload — flat array (same for all platforms) or object with platform keys: { default: [...], instagram: [...] }. Each entry is a plain ID string or { id, alt } to attach alt text (accessibility description, max 1500 chars) to that file — delivered to Mastodon, Bluesky, X, Pinterest, Instagram (images) and LinkedIn (images). A media item of type 'document' (a PDF kept as one item) expands into its page images, in order, so one id attaches the whole deck."),
         media_urls: z.union([
             z.array(mediaUrlEntry),
             z.record(z.string(), z.array(mediaUrlEntry)),
@@ -714,6 +798,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
         hashtag_set: z.string().optional().describe("Name of a saved hashtag set (from list_hashtag_sets, matched case-insensitively) to apply. The set's tags are merged in ONCE at create time — tags already in a caption are skipped, and Instagram's 30-hashtag cap returns a clear hashtag_limit_exceeded error. When the user says 'add my usual hashtags', check list_hashtag_sets first."),
         hashtag_placement: z.enum(["caption_append", "first_comment"]).optional().describe("Where the set's tags land. caption_append (default): appended to each target caption after a blank line. first_comment: posted as the auto first comment on Instagram/Facebook/LinkedIn/LinkedIn Page/YouTube/TikTok (TikTok only when the workspace enabled TikTok comments) (appended after any explicit first_comment); platforms without a comment API fall back to caption_append. Stories always use captions."),
         hashtag_platforms: z.array(z.string()).optional().describe("Optional subset of the post's channels to apply the hashtag set to (e.g. [\"instagram\", \"tiktok\"]). Defaults to all selected channels."),
+        video_cover: VIDEO_COVER_OPTIONS,
         pinterest: PINTEREST_OPTIONS,
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. Falls back to \"YouTube Short\" when omitted."),
@@ -724,7 +809,7 @@ Do NOT call this tool without media when creating stories, reels, Instagram post
             notify_subscribers: z.boolean().optional(),
             contains_synthetic_media: z.boolean().optional(),
             first_comment: z.string().max(10000).optional().describe("Text auto-posted as the first comment on the video right after it publishes. The video must have comments enabled."),
-        }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
+        }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels. A custom Shorts thumbnail is set with the top-level `video_cover` (a `youtube` override for a YouTube-only image); it shows on Shorts only on channels where YouTube has enabled custom Shorts thumbnails (Partner Program channels first, since July 2026), other channels show a frame from the video."),
         instagram: z.object({
             share_to_feed: z.boolean().optional(),
             thumbnail_type: z.enum(["from-video", "from-library"]).optional().describe("How the Reel cover is chosen: 'from-video' picks a frame at thumb_offset; 'from-library' uses the image at cover_url. get_post reads the chosen cover back."),
@@ -844,10 +929,10 @@ IMPORTANT — Before calling this tool, make sure you have all required informat
    - Pinterest: ALWAYS need an image + board_id.
    - Ask the user which media to use. Use list_media to show options.
    - **Max items per platform** (same caps as create_post — exceeding returns 400): Bluesky/X/Mastodon ≤4, Instagram/Threads ≤10, TikTok ≤35 photos, Pinterest carousel 2–5 same-ratio images. Mixing images+video is rejected on Facebook/LinkedIn/X/Bluesky/Mastodon/TikTok; Instagram and Threads mixed carousels are allowed.
-   - **Video duration/size caps** (ffprobe at submit — over either returns 400 validation_error with the exact cap + the file's value): X **140s/512MB** free/Basic, **125min/16GB** when the connected X account has Premium/Premium+ (auto-detected; no video+image mix in one tweet), Bluesky 180s, Threads 5min, Instagram 15min, TikTok 10min, YouTube Short 3min, LinkedIn 10min, Facebook Reel 90s.
+   - **Video duration/size caps** (ffprobe at submit — over either returns 400 validation_error with the exact cap + the file's value): X **140s/512MB** free/Basic, **125min/16GB** when the connected X account has Premium/Premium+ (auto-detected; no video+image mix in one tweet), Bluesky 180s, Threads 5min, Instagram 15min, TikTok 10min, YouTube Short 3min, LinkedIn 10min, Facebook 240min (Post + Reel; the old 90s Reel cap is gone).
 4. **Pinterest board (auto-default to first board)**: If Pinterest is in \`channels\` and \`pinterest.board_id\` is NOT provided, do NOT block on asking — and do NOT skip Pinterest. Call \`get_account\` on the Pinterest account, take the FIRST board from the returned boards list, and pass its \`id\` as \`pinterest.board_id\`. In your reply, mention which board you used (e.g. "Published to your 'Marketing' board on Pinterest — let me know if you'd prefer a different one.") so the user can redirect. If the user named a specific board in the request, match it (case-insensitive) against the list and use that one instead.
 5. **X threads vs long-form**: A chained "thread" → pass \`x.thread_parts\` as a 2–25 entry array of \`{ text }\` objects (each ≤ 280 chars on free/Basic, 25,000 on Premium/Premium+). A single long-form post on a Premium / Premium+ account → put the full text (up to 25,000 chars) in \`content\`; no threading needed. On free / Basic, X caps a single post at 280 chars. Do NOT split into "1/", "2/" inside \`content\` — that produces a single tweet, not a thread. The same \`thread_parts\` shape works under \`bluesky\`, \`mastodon\` and \`threads\` (Threads: 2 to 25 parts, 500 characters per part, up to 10 media per part; parts after the first publish as replies to the previous part).
-6. **X posts containing a link cost credits**: X bills API posts whose text contains a URL at a premium; OmniSocials passes that through as prepaid credits at X's exact rate (20 credits ≈ $0.20 per URL-containing tweet, threads charged per link-containing part). Because this tool publishes IMMEDIATELY, the debit happens right away — if the company's balance can't cover it, the X target fails with a top-up message while other platforms still publish. Relay any \`x_url_post_credits\` warning and X publish failure to the user; never strip their link to avoid the fee without asking. If the balance (minus credits reserved by scheduled X link posts) can't cover this post, the request is refused up front with a 402 \`x_credits_insufficient\` error instead of failing at publish.
+6. **X posts containing a link cost credits**: X bills API posts whose text contains a URL at a premium; OmniSocials passes that through as prepaid credits at X's exact rate (20 credits ≈ $0.20 per URL-containing tweet, threads charged per link-containing part; only a link written with http:// or https:// counts, a bare domain or www. link is free). Because this tool publishes IMMEDIATELY, the debit happens right away — if the company's balance can't cover it, the X target fails with a top-up message while other platforms still publish. Relay any \`x_url_post_credits\` warning and X publish failure to the user; never strip their link to avoid the fee without asking. If the balance (minus credits reserved by scheduled X link posts) can't cover this post, the request is refused up front with a 402 \`x_credits_insufficient\` error instead of failing at publish.
 
 Do NOT call without required media — it will fail.`, {
         content: z.union([z.string(), z.record(z.string(), z.string())]).describe("Post caption. String for same text on all channels, or object with platform keys for per-channel captions: { \"default\": \"fallback\", \"linkedin\": \"long version\", \"threads\": \"short version\" }. The \"default\" key is used for any selected channel without its own key."),
@@ -871,6 +956,7 @@ Do NOT call without required media — it will fail.`, {
         hashtag_set: z.string().optional().describe("Name of a saved hashtag set (from list_hashtag_sets, matched case-insensitively) to apply. Tags are merged in once at create time; tags already in a caption are skipped."),
         hashtag_placement: z.enum(["caption_append", "first_comment"]).optional().describe("caption_append (default) appends tags to the captions; first_comment posts them as the auto first comment on comment-capable platforms (others fall back to caption)."),
         hashtag_platforms: z.array(z.string()).optional().describe("Optional subset of the post's channels to apply the hashtag set to. Defaults to all selected channels."),
+        video_cover: VIDEO_COVER_OPTIONS,
         pinterest: PINTEREST_OPTIONS,
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube."),
@@ -881,7 +967,7 @@ Do NOT call without required media — it will fail.`, {
             notify_subscribers: z.boolean().optional(),
             contains_synthetic_media: z.boolean().optional(),
             first_comment: z.string().max(10000).optional().describe("Text auto-posted as the first comment on the video right after it publishes. The video must have comments enabled."),
-        }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
+        }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels. A custom Shorts thumbnail is set with the top-level `video_cover` (a `youtube` override for a YouTube-only image); it shows on Shorts only on channels where YouTube has enabled custom Shorts thumbnails (Partner Program channels first, since July 2026), other channels show a frame from the video."),
         instagram: z.object({
             share_to_feed: z.boolean().optional(),
             thumbnail_type: z.enum(["from-video", "from-library"]).optional().describe("How the Reel cover is chosen: 'from-video' picks a frame at thumb_offset; 'from-library' uses the image at cover_url. get_post reads the chosen cover back."),
@@ -985,6 +1071,7 @@ Do NOT call without required media — it will fail.`, {
         location_id: z.string().optional().describe("Instagram only. Facebook Place/Page ID to tag the post's location with. Send an empty string to clear an existing location tag. Ignored by other platforms."),
         collaborators: z.array(z.string()).max(3).optional().describe("Instagram only. Up to 3 public Instagram usernames to invite as co-authors. Replaces the existing collaborator list. Send an empty array to clear collaborators. Works on image, carousel, and reel posts — NOT Stories. Ignored by other platforms."),
         user_tags: z.array(USER_TAG_ENTRY).optional().describe("Instagram only. Tag public accounts at x/y positions on a PHOTO (not video/reels/stories). Replaces the existing tag list. Send an empty array to clear. For carousels set image_index per tag. Ignored by other platforms."),
+        video_cover: VIDEO_COVER_OPTIONS.nullable().describe("Replaces the stored video cover wholesale; pass null to remove it; omit to leave it untouched. facebook.thumbnail_type / thumb_offset / cover_url merge into overrides.facebook on their own."),
         youtube: z.object({
             title: z.string().optional().describe("Short title shown on YouTube. To change the Short's title on an existing draft, set this — do NOT use `content` (which is the description)."),
             tags: z.array(z.string()).optional(),
@@ -994,7 +1081,7 @@ Do NOT call without required media — it will fail.`, {
             notify_subscribers: z.boolean().optional(),
             contains_synthetic_media: z.boolean().optional(),
             first_comment: z.string().max(10000).optional().describe("Text auto-posted as the first comment on the video right after it publishes. The video must have comments enabled. Pass an empty string to clear a previously set first comment."),
-        }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels."),
+        }).optional().describe("YouTube Shorts options. Only applies when type is 'reel' and youtube is among the selected channels. A custom Shorts thumbnail is set with the top-level `video_cover` (a `youtube` override for a YouTube-only image); it shows on Shorts only on channels where YouTube has enabled custom Shorts thumbnails (Partner Program channels first, since July 2026), other channels show a frame from the video."),
         pinterest: PINTEREST_OPTIONS,
         instagram: z.object({
             share_to_feed: z.boolean().optional(),
@@ -1213,6 +1300,72 @@ IMPORTANT: this only succeeds if the connected user is a listed approver for the
             content: [{ type: "text", text: md }],
         };
     });
+    server.tool("get_post_approval", `Read the approval review of a post: every workflow step with its approvers and their decisions, the rejection with its reason, and the comment thread.
+
+Use it when \`get_post\` shows the status \`rejected\` (who rejected it and why, what to change before sending it again) or \`in_approval\` (who the post waits for, what the reviewers wrote). Read-only. A post without an approval workflow returns status \`none\`.`, {
+        id: z.string().describe("The post ID"),
+    }, { title: "Get Post Approval", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ id }) => {
+        const result = await getClient().getPostApproval(id);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: `Error (${result.error.code}): ${result.error.message}` }],
+            };
+        }
+        const a = result.data;
+        if (!a) {
+            return {
+                content: [{ type: "text", text: "The API returned no approval review for this post. Check its status with get_post." }],
+            };
+        }
+        let md = `## Approval Review\n\n`;
+        md += `| Field | Value |\n`;
+        md += `|-------|-------|\n`;
+        md += `| **Post** | \`${a.post_id || id}\` |\n`;
+        md += `| **Status** | ${capitalize(a.status || "none")} |\n`;
+        if (a.workflow?.name)
+            md += `| **Workflow** | ${a.workflow.name} |\n`;
+        if (a.requested_by?.name)
+            md += `| **Requested by** | ${a.requested_by.name} |\n`;
+        if (a.status === "none") {
+            md += `\n_This post has no approval workflow._`;
+            return {
+                content: [{ type: "text", text: md }],
+            };
+        }
+        if (a.rejection) {
+            md += `\n### Rejected\n\n`;
+            md += `${a.rejection.by?.name || "A reviewer"} rejected this post${a.rejection.at ? ` on ${formatDateTime(a.rejection.at)}` : ""}.\n`;
+            md += a.rejection.reason ? `\n**Reason:** ${a.rejection.reason}\n` : `\n_No reason was given._\n`;
+        }
+        if (Array.isArray(a.steps) && a.steps.length) {
+            md += `\n### Steps\n\n`;
+            md += `| # | Step | Needs | Status | Approvers |\n`;
+            md += `|---|------|-------|--------|-----------|\n`;
+            for (const s of a.steps) {
+                const who = (s.approvers || [])
+                    .map((p) => `${p.name || p.email || p.id} (${p.status})`)
+                    .join(", ");
+                const active = a.current_step === s.order ? " (waiting now)" : "";
+                md += `| ${s.order} | ${s.name}${active} | ${s.require_mode === "any" ? "one approval" : "all approvers"} | ${capitalize(s.status)} | ${who || "none"} |\n`;
+            }
+        }
+        if (Array.isArray(a.comments) && a.comments.length) {
+            md += `\n### Comments (${a.comments.length}, oldest first)\n\n`;
+            for (const c of a.comments) {
+                const where = c.account ? ` on ${capitalize(c.account.replace(/_/g, " "))}` : "";
+                md += `- **${c.author?.name || "Unknown"}**${where}, ${formatDateTime(c.created_at)}: ${String(c.message).replace(/\n+/g, " / ")}\n`;
+            }
+        }
+        else {
+            md += `\n_No comments in the review thread._`;
+        }
+        if (a.status === "rejected") {
+            md += `\n\n_A rejected post does not publish. To send it again, open it in OmniSocials, edit it and send it for approval there, or create a new post with \`approval_workflow_id\`._`;
+        }
+        return {
+            content: [{ type: "text", text: md }],
+        };
+    });
     server.tool("search_locations", `Search for a location to tag on a post. Use this whenever the user wants to post WITH a place/location (e.g. "post this at my dealership", "tag the café"). It returns matching real venues with their addresses and a location ID.
 
 Pick the platform with \`platform\`: "instagram" (default) or "threads". The two use DIFFERENT ids (a Facebook Place ID is not a Threads location id), so search with the platform you will tag. If the user wants both, search twice.
@@ -1304,6 +1457,91 @@ Notes:
         });
         return { content: [{ type: "text", text: md }] };
     });
+    server.tool("list_pinterest_products", `List the product Pins of the connected Pinterest account, to tag products on a Pin (people can then shop the items in the image). Use this whenever the user wants to tag products on a Pinterest post.
+
+Flow: call it → show the products to the user → pass the chosen \`pin_id\` values (max 24) as \`pinterest.product_tags\` on create_post / create_and_publish_post / update_post. If the user gives a Pin link or Pin ID of a product, pass it as \`check_pin\` to check it first, or put it straight in \`pinterest.product_tags\`.
+
+Notes:
+- Only the account's own product Pins can be tagged: a public product Pin with a link on a website the account claimed on Pinterest. Products of other merchants cannot be tagged through the API.
+- \`source\` "catalog" reads the Pinterest catalog (with price and stock). It needs catalog access, which the user gives one time in OmniSocials: create a post, open the Pinterest options, select Add products, then Connect catalog. \`source\` "pins" reads the account's own Pins and returns the product Pins; one call scans up to 250 Pins, so an empty result with a bookmark means: call again with that bookmark. Without \`source\`, the catalog is used when the connection has catalog access, else the Pins.
+- A product that Pinterest refuses never fails the post; get_post shows which products were tagged.`, {
+        source: z
+            .enum(["catalog", "pins"])
+            .optional()
+            .describe("Where to read product Pins from. Default: catalog when the Pinterest connection has catalog access, else pins."),
+        product_group_id: z
+            .string()
+            .optional()
+            .describe("Catalog source only. A product group ID from an earlier result. Default: the group named All Products."),
+        bookmark: z
+            .string()
+            .optional()
+            .describe("Cursor from an earlier result, to get the next page."),
+        check_pin: z
+            .string()
+            .optional()
+            .describe("A Pin ID or Pin link (https://www.pinterest.com/pin/<id>/) to check instead of listing: answers whether that Pin can be tagged as a product."),
+    }, { title: "List Pinterest Products", readOnlyHint: true, destructiveHint: false, openWorldHint: true }, async ({ source, product_group_id, bookmark, check_pin }) => {
+        const messageOf = (err) => typeof err === "string" ? err : err?.message;
+        if (check_pin) {
+            const check = await getClient().validatePinterestProduct(check_pin);
+            const failed = messageOf(check?.error);
+            if (failed)
+                return { content: [{ type: "text", text: failed }] };
+            const name = check?.title ? ` (${check.title})` : "";
+            let text;
+            if (check?.valid) {
+                text = `Pin \`${check.pin_id}\`${name} is a product Pin of this account. Use it in \`pinterest.product_tags\`.`;
+            }
+            else if (check?.unverified) {
+                text = `Could not check Pin \`${check?.pin_id ?? check_pin}\`: ${check?.reason || "no answer from Pinterest"} You can still pass it in \`pinterest.product_tags\`; Pinterest checks it at publish.`;
+            }
+            else {
+                text = `Pin ${check?.pin_id ? `\`${check.pin_id}\`${name}` : `"${check_pin}"`} cannot be tagged: ${check?.reason || "Pinterest did not accept it."}`;
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        const result = await getClient().listPinterestProducts({ source, product_group_id, bookmark });
+        const failed = messageOf(result?.error);
+        if (failed)
+            return { content: [{ type: "text", text: failed }] };
+        const products = result?.products || [];
+        const fromCatalog = result?.source === "catalog";
+        const groups = result?.product_groups || [];
+        let md = `## Pinterest product Pins (${fromCatalog ? "catalog" : "the account's own Pins"})\n\n`;
+        if (!products.length) {
+            if (result?.bookmark) {
+                md += `No product Pins in this part of the Pin list. Call again with bookmark \`${result.bookmark}\` to scan the next part.\n`;
+            }
+            else if (fromCatalog) {
+                md += groups.length
+                    ? "This product group has no products.\n"
+                    : "The Pinterest account has no catalog. Try source \"pins\", or pass a product Pin link as check_pin.\n";
+            }
+            else {
+                md += "No product Pins found. A product Pin comes from the Pinterest catalog, or links to a product page on a website the account claimed on Pinterest.\n";
+            }
+        }
+        else {
+            md += `Ask the user which products to tag, then pass their IDs (max 24) as \`pinterest.product_tags\`:\n\n`;
+            md += `| # | Product | Price | Stock | pin_id |\n|---|---------|-------|-------|--------|\n`;
+            products.forEach((p, i) => {
+                const price = typeof p.price === "number" ? `${p.price}${p.currency ? ` ${p.currency}` : ""}` : "-";
+                md += `| ${i + 1} | ${p.title || p.link || "-"} | ${price} | ${p.availability || "-"} | \`${p.pin_id}\` |\n`;
+            });
+            if (result?.bookmark)
+                md += `\nMore products: call again with bookmark \`${result.bookmark}\`.\n`;
+        }
+        if (fromCatalog && groups.length > 1) {
+            md += `\nProduct groups (pass one as product_group_id): ${groups
+                .map((g) => `${g.name || "Unnamed"} \`${g.id}\`${g.id === result?.product_group_id ? " (shown)" : ""}`)
+                .join(", ")}\n`;
+        }
+        if (!fromCatalog && result?.catalog_access === false) {
+            md += `\nThe connection has no catalog access, so catalog products are not listed. The user can give it one time in OmniSocials: create a post, open the Pinterest options, select Add products, then Connect catalog.\n`;
+        }
+        return { content: [{ type: "text", text: md }] };
+    });
     server.tool("search_instagram_audio", `Search Instagram's licensed music catalog for a track to attach to a REEL. Use this whenever the user wants to post a reel WITH music/a song/a sound (e.g. "post this reel with trending audio", "add that song to it").
 
 Flow: call with a song/artist/keyword (or NO query for currently trending audio) → present the options → once the user picks, pass that result's \`audio_id\` as \`instagram.audio_id\` on create_post / create_and_publish_post / update_post. Optionally mix with \`instagram.audio_volume\` / \`instagram.video_volume\` (0-100; set video_volume 0 to fully replace the video's own sound). Instagram Reels only — feed posts, carousels, and Stories can't take music via the API (Meta limitation).

package/build/tools/webhooks.js

@@ -28,9 +28,9 @@ export function registerWebhookTools(server, getClient) {
             content: [{ type: "text", text: md }],
         };
     });
-    server.tool("create_webhook", "Create a new webhook to receive event notifications. Available events: post.scheduled, post.published, post.failed", {
+    server.tool("create_webhook", "Create a new webhook to receive event notifications. Available events: post.scheduled, post.published, post.failed, post.approved (the last approval of a post's approval workflow is in), post.rejected (an approver rejected the post)", {
         url: z.string().describe("The HTTPS URL to send webhook events to"),
-        events: z.array(z.string()).describe("Events to subscribe to: post.scheduled, post.published, post.failed"),
+        events: z.array(z.string()).describe("Events to subscribe to: post.scheduled, post.published, post.failed, post.approved, post.rejected"),
     }, { title: "Create Webhook", readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async (params) => {
         const result = await getClient().createWebhook(params);
         if (result.error) {
@@ -95,7 +95,7 @@ export function registerWebhookTools(server, getClient) {
     server.tool("update_webhook", "Update a webhook's URL, events, or active status.", {
         id: z.string().describe("The webhook ID to update"),
         url: z.string().optional().describe("Updated HTTPS URL"),
-        events: z.array(z.string()).optional().describe("Updated event list"),
+        events: z.array(z.string()).optional().describe("Updated event list: post.scheduled, post.published, post.failed, post.approved, post.rejected"),
         is_active: z.boolean().optional().describe("Enable or disable the webhook"),
     }, { title: "Update Webhook", readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ id, ...data }) => {
         const result = await getClient().updateWebhook(id, data);