WordPress Buffer Media Normalizer

A high-performance WordPress plugin designed for automated media ingestion and cross-platform social scheduling. It exposes secure endpoints to import remote images directly into the WordPress Media Library, normalizes assets to ideal social dimensions, creates premium high-resolution PNG variants, removes source watermarks dynamically, and integrates with the Buffer API to schedule multi-network posts.

This plugin is especially useful for setting up AI-driven editorial pipelines (e.g., matching with autonomous agents or curation bots) that coordinate blog publication with social media broadcasts.

Key Features

• 📥 Remote Ingestion Endpoint: Sideload external images securely into the WordPress Media Library via REST API.
• 📐 Social Asset Normalization: Registers a custom crop size (buffer-share at 1080×566) optimized for Buffer and modern social networks.
• 🖼️ High-Fidelity PNG Generation: Automatically exports a secondary high-quality PNG variant alongside standard sizes.
• ✂️ Smart Watermark Removal: Detects source domains (e.g., technology blogs) and crops watermarks dynamically (customizable list of domains).
• 📅 Buffer Scheduling Engine: Listens to WordPress post lifecycle hooks (scheduled/future/published transitions) to automatically queue posts onto Buffer channels.
• ⚙️ Custom Configuration Dashboard: Manage all API keys, access tokens, and social profile IDs under WordPress Settings -> Buffer Normalizer.
• 🔑 Flexible API Authentication: Dual support for constants defined in wp-config.php and options stored in the WordPress database.

Architecture Flow

graph TD
    subgraph Clients["📡 Client Applications"]
        Bot["Curation Bot / AI Agent"]
        Cron["External Feeds / Pipelines"]
    end

    subgraph WordPress["🖥️ WordPress instance"]
        REST["REST API Endpoints<br/>/wbmn/v1/..."]
        Admin["Settings Page<br/>Admin GUI Options"]
        Download["Remote Downloader<br/>wp_remote_get()"]
        Watermark["Watermark Cropper<br/>WP Image Editor"]
        MediaLib["Media Library Insertion<br/>wp_insert_attachment()"]
        PNG["PNG Variant Generator<br/>wp_get_image_editor()"]
        BufferHook["Buffer Hook Event<br/>save_post / transition_post_status"]
    end

    subgraph Buffer["🌐 Buffer Platform API"]
        BufferAPI["GraphQL Endpoint<br/>Create/Delete Scheduled Post"]
    end

    Bot -->|"POST /normalize-media<br/>(Secret Authentication)"| REST
    Cron -->|"POST /normalize-media"| REST
    Admin -->|"Saves Token & IDs"| WordPress
    REST -->|"Verifies token"| Download
    Download -->|"Applies Crop Filter"| Watermark
    Watermark --> MediaLib
    MediaLib -->|"Generates size"| PNG
    PNG -->|"Returns URLs & Dimensions"| Bot
    BufferHook -->|"Checks Post Metadata"| BufferAPI

Installation

1. Download the code or clone the repository into your WordPress plugins directory:

   cd wp-content/plugins/
   git clone https://github.com/yourusername/wp-buffer-media-normalizer.git

2. Activate the plugin in the WordPress Dashboard (Plugins -> Installed Plugins).
3. Navigate to Settings -> Buffer Normalizer to complete setup.

Configuration

The plugin can be configured through the admin panel or using PHP constants in wp-config.php.

Admin Dashboard Configuration

Go to Settings -> Buffer Normalizer inside your WordPress Admin Area:

• REST API Shared Secret: A custom token used to validate incoming requests.
• Buffer Access Token: Your personal OAuth token obtained from your Buffer Developer Console.
• Buffer Channel IDs: The platform-specific 24-character hexadecimal IDs for your social channels (LinkedIn, X/Twitter, Instagram, Bluesky, Mastodon, Threads).
• Watermark Crop Domains: A comma-separated list of domains (e.g. 9to5mac.com) to run the dynamic bottom 10% crop on.

wp-config.php Configuration (Optional)

For production environments, you can define credentials in wp-config.php to prevent storing secrets in the database:

define('BUFFER_ACCESS_TOKEN', 'your-oauth-access-token');
define('CRAFT_AGENT_LAB_WP_NORMALIZER_SHARED_SECRET', 'your-custom-shared-api-secret');

API Reference

1. Ingest & Normalize Media

Downloads a remote image, processes it, creates custom sizes, and returns details.

• Endpoint: POST /wp-json/wbmn/v1/normalize-media
• Headers:
  • x-craft-agent-secret: <your-shared-secret>
• Request Body (JSON):

  {
  "source_url": "https://example.com/remote-image.jpg",
  "title": "Featured Image Title",
  "alt_text": "Image alt description",
  "preferred_size": "buffer-share"
  }

• Response (200 OK):

  {
  "ok": true,
  "attachment_id": 4821,
  "source_url": "https://yourdomain.com/wp-content/uploads/2026/06/remote-image.jpg",
  "preferred_size": "buffer-share",
  "preferred_url": "https://yourdomain.com/wp-content/uploads/2026/06/remote-image-1080x566.png",
  "preferred_dimensions": {
    "width": 1080,
    "height": 566
  },
  "preferred_mime_type": "image/png",
  "buffer_url": "https://yourdomain.com/wp-content/uploads/2026/06/remote-image-1080x566.png",
  "sizes": {
    "thumbnail": "https://yourdomain.com/wp-content/uploads/2026/06/remote-image-150x150.jpg",
    "large": "https://yourdomain.com/wp-content/uploads/2026/06/remote-image-1024x538.jpg",
    "buffer-share": "https://yourdomain.com/wp-content/uploads/2026/06/remote-image-1080x566.jpg",
    "buffer-share-png": "https://yourdomain.com/wp-content/uploads/2026/06/remote-image-1080x566.png"
  }
  }

2. Manually Trigger Buffer Schedule

Manually queues the social posts associated with a specific WordPress Post ID.

• Endpoint: POST /wp-json/wbmn/v1/schedule-buffer
• Headers:
  • x-craft-agent-secret: <your-shared-secret>
• Request Body (JSON):

  {
  "post_id": 1245
  }

• Response (200 OK):

  {
  "ok": true,
  "post_id": 1245,
  "post_status": "publish",
  "buffer_posts_count": 3,
  "buffer_posts": [
    { "channel": "x", "post_id": "689c2f16..." },
    { "channel": "linkedin", "post_id": "689c3a6d..." },
    { "channel": "threads", "post_id": "667c3667..." }
  ],
  "scheduled_time": 1782476100
  }

Social Scheduling Workflow Details

When a post is scheduled in WordPress (transition_post_status to future), the plugin reads:

1. _craft_tweet_text custom metadata (used for Twitter, Bluesky, Mastodon, Threads).
2. _craft_facebook_text custom metadata (used for LinkedIn and Instagram).
3. If no custom metadata is present, it defaults to the WordPress post title.

It formats, truncates according to each platform's character limit constraints, appends the post permalink, attaches the buffer-share image, and transmits a GraphQL payload to the Buffer API scheduling queue. If the WordPress post is rescheduled, draft-saved, or deleted, the plugin updates or unschedules the items from Buffer automatically.

License

This project is licensed under the GPLv2 (or later) License - see the LICENSE file for details.