=== 5th Social Bot ===
Contributors: arcmediasoft
Donate link: https://plugin.5th.ro
Tags: mastodon, fediverse, social, autopost, social.5th.ro
Requires at least: 5.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.7.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Automatically post WordPress content to your Mastodon account (any instance) with a customizable template and safe queue.

== Description ==

5th Social Bot (Mastodon All-In-One Wordpress Plugin) connects your WordPress site to any Mastodon instance. By default, it works with **https://social.5th.ro**, but you can configure it to use any Mastodon instance.

When you publish posts or pages, the plugin can automatically send a status to Mastodon that contains:

* a clean excerpt of your content,
* a link back to the original post or page,
* WordPress tags converted into Mastodon hashtags (with spaces and unsafe characters removed).

You can customize the structure of the Mastodon message using placeholders and emojis.

To avoid spam and rate-limit issues, bulk posting uses an internal queue (drip feed) and sends only 1 post every 5 minutes via WP-Cron.

> Important:  
> By default, this plugin works with the instance **social.5th.ro**, but you can configure it to use any Mastodon instance.  
> You need a personal access token from your Mastodon account with the required permissions.

This plugin does not send data to any third-party service other than the configured Mastodon instance when posting statuses. You remain responsible for ensuring that your use of the plugin complies with applicable laws (for example, privacy and data protection regulations).

"Mastodon" and "WordPress" are separate projects and registered trademarks of their respective owners. This plugin is an independent integration and is not officially endorsed by them.

### Main features

* Auto-post to any Mastodon instance when publishing posts and/or pages (default: social.5th.ro, configurable to any instance).
* Per-post control: exclude individual posts/pages from auto-posting via meta box checkbox.
* Customizable message template with placeholders:
  * `{text}` – excerpt / preview of the content.
  * `{tags}` – hashtags generated from WordPress tags.
  * `{readmore_text}` – short call-to-action text.
  * `{url}` – permalink to the post or page.
* Newlines support in the template:
  * write on multiple lines in the textarea, or
  * use `\n` in the template (converted to real newlines).
* Multiple `{readmore_text}` variants:
  * one per line; a random line is chosen for each post.
  * examples: `Read more at:`, `More details at:`.
* Extended emoji picker with over 2000 Unicode emojis:
  * categorized emojis for various domains (business, IT/SEO, medical, construction, news, etc.),
  * lazy-loading mechanism for better performance,
  * quick access toolbar in the template editor.
* Post language setting:
  * configure the language code (ISO 639-1/639-2) for your Mastodon posts,
  * default: Romanian (ro).
* Automatic trimming to a maximum of 500 characters:
  * tries to shorten only the `{text}` part first,
  * falls back to a minimal `…. {readmore_text} {url}` variant if needed.
* WordPress tags → Mastodon hashtags:
  * spaces and characters like `-`, `_`, `;`, `:` are removed,
  * only letters and digits remain, then a `#` prefix is added.
* Profile verification:
  * automatically adds Mastodon profile verification code to your site header and footer,
  * includes `<meta name="fediverse:creator">` tag and `<a rel="me">` link,
  * helps verify your Mastodon account ownership.
* Mastodon Button shortcode:
  * `[mastodon_button]` – display a Mastodon button or link on your site,
  * compatible with Gutenberg, Elementor, and other page builders,
  * multiple button styles (button, link, icon, modern, minimal, rounded, outline, gradient, pill, white, black, etc.),
  * customizable sizes (small, medium, large),
  * icon color options (default, black, gray, red, white, green, purple),
  * mobile-friendly and responsive design.
* Mastodon Feed shortcode:
  * `[mastodon_feed]` – display the latest Mastodon posts in sidebars, widgets, posts, or pages,
  * supports personal feeds and tag feeds,
  * automatically uses your Mastodon username from settings if not specified,
  * configurable post count (maximum 10 posts),
  * multiple layouts (default, compact, grid),
  * caching support for better performance,
  * optional filters (exclude replies, exclude reblogs, only media posts).
* Auto-Boost functionality:
  * automatically boost posts from your primary Mastodon instance to a second Mastodon instance,
  * cross-instance boost support using Mastodon API v2 search with `resolve=true` parameter,
  * configurable rate limits (1-10 boosts per day, 30 minutes to 2 hours interval),
  * automatic queue management for rate-limited boosts,
  * boost queue management: reorder posts (move up/down) and remove posts from boost queue,
  * boost queue statistics: shows queue size, daily boost count, and rate limit status,
  * rate limit warnings: visual indicators when approaching or reaching daily limits,
  * automatic retry mechanism: failed boosts (e.g., post not federated yet) are retried after 5 minutes,
  * displays both Mastodon post link and boost link in the Bulk & queue tab,
  * "Boost now" button for manual boost of individual posts,
  * connection test button for second instance to verify configuration.
* Bulk & queue tab:
  * "Post last article".
  * "Post last 20 / 40 / 60 / 80".
  * bulk actions only **queue** posts for sending, they are not fired all at once.
  * queue reordering: move posts up/down in the main queue,
  * boost queue management: dedicated "Boost Queue & Statistics" section with:
    * visual statistics (queue size, daily boost count, minimum interval),
    * rate limit warnings (yellow for <=2 remaining, red for 0 remaining),
    * boost queue table with reorder (up/down) and remove buttons,
    * empty state messages when queues are empty,
  * "Boost now" button for individual posts (appears when boost is enabled and configured),
  * displays both Mastodon post link and boost link (if available),
  * status indicators: "Posted to Mastodon", "Boosted", "Boost queued", "Boost pending".
* Safe drip-feed queue via WP-Cron:
  * the queue is processed in small batches per run (1 post every 5 minutes),
  * if there are more posts, the next batch is scheduled later.
* Per-post Mastodon status in the Bulk tab:
  * "Posted to Mastodon" / "Queued" / "Not posted",
  * "Boosted" / "Boost queued" / "Boost pending" status indicators,
  * direct links to view posts and boosts on Mastodon.
* Manual "Post now" and "Boost now" buttons for each post/page.
* Analytics tab:
  * aggregated statistics (total posts, replies, boosts, favorites, views),
  * average statistics per post,
  * individual post statistics with detailed metrics,
  * boost statistics (separate metrics for boosted posts),
  * data cached for 5 minutes to reduce API calls,
  * direct links to view posts and boosts on Mastodon,
  * "Import Stats from Mastodon" button to import missing post URLs from your Mastodon account.
* Log & debug tab:
  * internal log of successful sends and errors,
  * only the most recent 200 entries are stored,
  * the latest 20 are shown by default, with "Load 20 more",
  * optional debug mode for detailed logging of shortcode execution and API interactions.
* User experience improvements:
  * connection status indicator (green/yellow/red) in settings page header for both primary and boost accounts,
  * "Send test post to Mastodon" button to verify configuration,
  * empty state messages for empty queues,
  * loading states (spinners) for all asynchronous actions,
  * help tooltips for complex fields (access token, template, visibility, language),
  * modern CSS styling with cards, info boxes, status indicators, and stats grids across all tabs.
* Security features:
  * password-type input field for access tokens with show/hide toggle,
  * all user inputs are sanitized and validated,
  * all outputs are properly escaped to prevent XSS attacks,
  * no SQL injection vulnerabilities (uses WordPress APIs only),
  * no remote command execution risks.
* Support & Contact and Terms & Conditions tabs in the settings screen.
* Updated URLs: plugin official website is now **https://plugin.5th.ro**.
* Support link: dynamically includes site domain for better support tracking.
* Plugin menu:
  * moved to main WordPress admin menu (not under Settings),
  * custom "5th" icon for easy identification.

### Data and privacy

* The Mastodon access token you provide is stored only in your WordPress database.
* The plugin uses this token exclusively to communicate with your configured Mastodon instance through its official API.
* Logs are stored locally in your database and can be cleared at any time from the Log & debug tab.
* The plugin does not send analytics, tracking data or logs to the plugin author or any third-party service.

You remain responsible for:

* informing your users about how content is published and processed,
* configuring and using the plugin in accordance with applicable data protection and privacy laws,
* securing your WordPress installation and access credentials.

== Installation ==

1. Upload the plugin folder `5th-social-bot` to the `/wp-content/plugins/` directory,  
   or install the `5th Social Bot` zip through the WordPress “Plugins → Add New → Upload” screen.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Go to **5th Social Bot** in the main admin menu.
4. Configure your Mastodon instance:
   * By default, the plugin uses **https://social.5th.ro**.
   * If you want to use a different instance, check "I'm not Romanian, I will use other instance" and enter your Mastodon instance URL.
5. In your Mastodon account:
   * create or log into your Mastodon account on your chosen instance,
   * generate a personal access token with at least the required scopes.
6. Paste the access token into the plugin settings.
7. Choose:
   * which post types should be auto-posted (posts, pages),
   * the message template and readmore texts,
   * the default Mastodon visibility (public / unlisted / private / direct).
8. Click **Save settings**.
9. Click **Check connection with Mastodon** to verify the token.
10. Optionally use the **Bulk & queue** tab to add existing posts into the queue.

== Frequently Asked Questions ==

= Does this plugin support instances other than social.5th.ro? =

Yes! Starting from version 1.7.1, the plugin supports any Mastodon instance.  
By default, it uses **https://social.5th.ro**, but you can configure it to use any Mastodon instance by checking "I'm not Romanian, I will use other instance" in the settings and entering your instance URL.

= What permissions does the Mastodon access token need? =

You need a personal access token from your Mastodon account (on any instance).  
The token should have at least the `write:statuses` permission.  
For the connection test to show the account name, read access to the account (`read:accounts`) is also recommended.

= How is the 500-character limit enforced? =

Mastodon enforces a 500-character limit for statuses.

The plugin:

1. Builds the full message using `{text}`, `{tags}`, `{readmore_text}` and `{url}`.
2. If the result is longer than 500 characters, it shortens the `{text}` part.
3. If it is still too long, it falls back to a minimal variant such as:  
   `…. {readmore_text} {url}`.

= Can I prevent specific posts from being auto-posted? =

Automatic posting is controlled globally per post type (posts/pages).  
If you want to exclude certain posts, you can temporarily disable auto-posting for that post type, publish your content, and then use the Bulk & queue tools to choose exactly which posts should be sent.

= How does the Bulk & queue system work? =

The **Bulk & queue** tab lets you add the last 1 / 20 / 40 / 60 / 80 published posts/pages to an internal queue.

* Posts that are already marked as “posted” or “queued” are skipped.
* WP-Cron processes the queue in small batches to avoid aggressive posting.
* If there are many items, multiple cron runs are scheduled, resulting in a drip-feed effect.

= Where are logs stored and how can I clear them? =

Logs are stored in a single WordPress option in your database.  
You can see them and clear them from the **Log & debug** tab.

= Does this plugin make my site legally compliant? =

No. The plugin provides technical integration with Mastodon but does not ensure legal compliance by itself. You are responsible for configuring and using the plugin in line with applicable laws (for example, privacy, data protection, online communications, or local regulations).

If you are unsure, consider consulting a legal professional familiar with your jurisdiction.

== Screenshots ==

1. Main settings page with connection details, template and readmore texts.
2. Bulk & queue page with “Post last 20 / 40 / 60 / 80”.
3. Log & debug page listing recent Mastodon operations.
4. Example Mastodon status on social.5th.ro (excerpt + hashtags + link).

== Changelog ==

= 1.7.1 =
* New: Plugin menu moved to main admin menu with custom icon.
* New: Custom Mastodon instance support - use any Mastodon instance, not just social.5th.ro.
* New: Connection status displays full username with instance domain (e.g., @username@mastodon.social).
* New: Import Stats feature in Analytics tab to import missing post URLs from Mastodon.
* New: Automatic version check and update notifications from plugin.5th.ro.
* Improved: Dynamic instance handling - all API calls use configured instance.
* Security: Enhanced input sanitization and output escaping.

= 1.7.0 =
* New: Per-post control - meta box to exclude individual posts/pages from auto-posting.
* New: Analytics tab with comprehensive statistics for Mastodon posts.
* New: Auto-Boost functionality - configure a second Mastodon instance to automatically boost your posts.
* New: Cross-instance boost support using Mastodon API v2 search.
* New: Boost queue management with visual statistics and rate limit warnings.
* New: Connection status indicators for both primary and boost accounts.
* New: "Send test post to Mastodon" button for configuration verification.
* Improved: Modern UI with cards, info boxes, and status indicators.
* Improved: Security enhancements and password-protected access tokens.
* Fixed: Cross-instance boost logic improvements.

= 1.6.0 =
* New: Shortcode & Verification tab with profile verification support.
* New: [mastodon_button] and [mastodon_feed] shortcodes for displaying Mastodon content.
* Security: Enhanced input sanitization and output escaping throughout the plugin.
* Improved: Queue processing interval updated to 1 post every 5 minutes.

= 1.5.3 =
* Feature: Mastodon post links displayed in Bulk & queue tab.

= 1.5.2 =
* Fix: Template newline handling improved.

= 1.5.1 =
* Improved WordPress.org Plugin Check compatibility.

= 1.5.0 =
* Complete rewrite using class-based architecture.
* New message template with placeholders and emoji toolbar.
* New Bulk & queue and Log & debug tabs.

== Upgrade Notice ==

= 1.7.1 =
Major update adding custom Mastodon instance support, version check system, and installation tracking. Plugin menu moved to main admin menu. Highly recommended update.

= 1.7.0 =
Major update adding Auto-Boost functionality and Analytics tab. Highly recommended update for better cross-instance visibility and statistics.

= 1.6.0 =
Major update adding shortcodes and profile verification. Highly recommended update for better Mastodon integration.
