=== MentionFetch ===
Contributors: serkanemir, freemius
Tags: press, mentions, media coverage, cards, import
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 0.2.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn your media coverage into beautiful WordPress cards in seconds.

== Description ==

MentionFetch helps agencies, consultants, founders, and personal brand sites showcase earned media professionally.

Paste a URL from any publication. MentionFetch attempts to fetch the metadata automatically. When the publisher allows it, fields are populated instantly. When a site blocks server-side fetch (common on major publishers), MentionFetch opens a manual editing form automatically with best-effort prefills from the URL — no extra click needed. Either way, you review the fields and save structured WordPress content in under a minute.

**Core flow:** Paste URL → Review → Publish

= What MentionFetch Does =

* Import media coverage from any URL using Open Graph, Twitter Card, and standard HTML metadata
* Save imported items as dedicated Mention entries or as regular WordPress posts
* Preview and edit all imported fields before saving
* Live card preview on the import screen shows how the card will look
* Render mention cards on the frontend with a shortcode or Gutenberg block
* Display existing WordPress posts as mention cards without re-importing
* Automatic featured image sideload from imported article images
* Duplicate import prevention based on normalized source URL
* Source published date ordering so coverage timelines stay correct
* Clean source name resolution using page metadata and a curated publisher brand map
* MentionFetch Details meta box for editing mention fields after import
* WordPress-native import screen with Featured Image workflow, card preview sidebar, and combined Categories & Tags panel
* Optional AI excerpt enhancement with BYOK OpenAI-compatible provider; model selection via provider-backed discovery ("Load Models" fetches available models) or manual entry as fallback

= Shortcode =

`[mentionfetch]`

Shows published mentions using the active destination setting.

Optional attributes:

* `limit` — number of items (default: 6)
* `source` — `mention_item`, `post`, or `existing_posts`
* `category` — category slug or ID
* `post_type` — post type slug (existing_posts mode, default: post)
* `taxonomy` — taxonomy slug
* `term` — term slug or ID within the taxonomy
* `layout` — `grid` (default)
* `show_image` — `true` (default) or `false`
* `show_excerpt` — `true` (default) or `false`
* `show_date` — `true` (default) or `false`
* `show_source` — `true` (default) or `false`
* `orderby` — `source_date` (default for imported content), `post_date` (default for existing posts), `title`, or `random`
* `order` — `DESC` (default; title defaults to `ASC`) or `ASC`
* `offset` — number of items to skip (default: 0, max: 50)
* `preset` — display preset slug (created in MentionFetch > Presets); explicit attributes override preset values

= Shortcode Examples =

Show imported mentions:

`[mentionfetch limit="6"]`

Show imported posts only:

`[mentionfetch source="post"]`

Show existing posts from a category:

`[mentionfetch source="existing_posts" category="news" limit="4"]`

Show a custom post type filtered by taxonomy:

`[mentionfetch source="existing_posts" post_type="case_study" taxonomy="industry" term="saas"]`

Grid without images or dates:

`[mentionfetch layout="grid" show_image="false" show_date="false"]`

= Gutenberg Block =

Insert the **MentionFetch** block from the block inserter. Use the inspector panel to set source, limit, taxonomy filters, and display toggles. The block shows a live server-rendered grid preview in the editor.

= Layouts =

* **Grid** — visual card grid with image, excerpt, meta, and "Read more" link (default)

= Elementor Widget =

If Elementor is installed and active, a **MentionFetch** widget is available in the Elementor editor under General. It supports the same source, filter, and display options as the shortcode and block. Display controls use a three-state Inherit/Show/Hide pattern so preset values flow through to untouched widgets. The plugin remains fully functional without Elementor.

= Save Destinations =

In MentionFetch Settings, choose where imported items are saved:

* **Mention Item** — a dedicated custom post type managed under the MentionFetch menu
* **WordPress Post** — a standard post with optional default category assignment

Both destinations store the same normalized mention metadata and support the same shortcode and block rendering.

= Import Features =

* Metadata parsing: Open Graph, Twitter/X Card, meta description, JSON-LD dates, HTML paragraph fallback
* Canonical URL resolution: prefers og:url, then link rel=canonical, then the pasted URL
* URL normalization: strips tracking parameters (utm_*, fbclid, gclid, etc.), lowercases, normalizes trailing slashes
* Relative URL resolution for protocol-relative, root-relative, and path-relative metadata values
* Browser-like fetch headers for better publisher compatibility
* Featured image sideload into the WordPress media library
* Generated post content with excerpt summary and source attribution link (post destination only)
* Duplicate detection across both mention items and imported posts
* Draft or Publish status choice at import time
* Automatic manual fallback: when a publisher blocks server-side fetch, the edit form opens automatically with URL-derived prefills — no extra click needed

== Installation ==

1. Upload the `mentionfetch` folder to `/wp-content/plugins/` or create a symlink from your development directory.
2. Activate the plugin through the Plugins menu in WordPress.
3. Go to **MentionFetch > Settings** and choose your save destination.
4. Go to **MentionFetch > Add Mention** and paste an article URL.
5. Review the preview, edit fields if needed, and save.
6. Use the `[mentionfetch]` shortcode or MentionFetch Gutenberg block to display cards on a page.

== Screenshots ==

1. Paste a URL and fetch metadata automatically — title, image, source, date, and live card preview.
2. Display your press coverage beautifully with the built-in grid layout.
3. Add the MentionFetch block anywhere on your site with the Gutenberg editor.
4. Customize import settings, save destination, and optional AI excerpt enhancement.
5. Elementor widget with source, filter, and display controls.

== Frequently Asked Questions ==

= Does MentionFetch copy the full article? =

No. MentionFetch primarily imports page metadata: title, description, image, source URL, and publication date. When a page has no usable description in its metadata, the importer may extract a short lead paragraph from the page HTML as a fallback excerpt. It does not reproduce or store the full article. Cards always link back to the original source.

= Can I use MentionFetch with Elementor? =

Yes. MentionFetch includes a dedicated Elementor widget with the same source, filter, layout, and display controls available in the shortcode and block. The widget appears under General in the Elementor editor when Elementor is installed and active. Imported content also works with Elementor's native Loop Grid since it uses standard WordPress post structure.

= What happens if an article has no image? =

The card renders cleanly without the image section. No broken image placeholders appear.

= Can I import the same URL twice? =

No. MentionFetch detects duplicates by normalized source URL and blocks the second import with a link to the existing item.

== External Services ==

= OpenAI-Compatible API (Optional) =

MentionFetch can optionally connect to an OpenAI-compatible API to enhance article excerpts using AI. This feature is disabled by default and requires you to:

1. Enable the AI option in MentionFetch > Settings
2. Provide your own API key (BYOK — Bring Your Own Key)
3. Configure your provider API base URL

When enabled, MentionFetch sends the extracted article excerpt text to the configured API endpoint for improvement. No other user data is transmitted.

MentionFetch does not enable or contact an AI provider until an administrator enables the feature, enters an API key, and saves a provider API base URL. You may use any OpenAI-compatible provider (OpenAI, OpenRouter, Groq, Anthropic, etc.). Please consult the configured provider's own terms of service and privacy policy before enabling this feature.

When the OpenAI default endpoint is used (api.openai.com):

* OpenAI Terms of Use: [https://openai.com/policies/terms-of-use/](https://openai.com/policies/terms-of-use/)
* OpenAI Privacy Policy: [https://openai.com/policies/privacy-policy/](https://openai.com/policies/privacy-policy/)

= Freemius Licensing and Updates =

MentionFetch uses the Freemius SDK for optional account connection, licensing, plan status, software updates, and support/contact screens. The plugin can be used without connecting a Freemius account. License management and account-based update screens use Freemius only when you choose to connect through the Freemius screen.

When you choose to connect through the Freemius opt-in screen, the SDK may send the site URL, plugin version, WordPress version, PHP version, and administrator email to Freemius for licensing and support purposes. MentionFetch does not send this data to Freemius unless you opt in through the Freemius screen.

* Freemius Terms of Service: [https://freemius.com/terms/](https://freemius.com/terms/)
* Freemius Privacy Policy: [https://freemius.com/privacy/](https://freemius.com/privacy/)

= Public Article Pages (Metadata Fetch) =

When you paste a URL into the URL Import screen, MentionFetch fetches the public HTML of that page (one-time, server-side via wp_safe_remote_get) to extract Open Graph / Twitter Card / schema.org metadata so the card preview can populate Title, Excerpt, Source Name, Image, and Published Date. No data about your site, user, or visitors is sent to those services — only an unauthenticated GET request to the URL the admin pasted, exactly as a browser would.

The URL is fetched once at import time. There is no background polling or analytics.

Some public pages also include schema.org `AggregateRating` metadata inside `<script type="application/ld+json">` blocks. When that metadata is present in the pasted page's HTML, MentionFetch may parse and store it as part of the imported mention metadata. Common services that publish this markup include Apple Podcasts, Rotten Tomatoes, and Goodreads. Their respective terms and privacy policies:

* Apple Podcasts (podcasts.apple.com): Apple Media Services Terms ([https://www.apple.com/legal/internet-services/itunes/](https://www.apple.com/legal/internet-services/itunes/)), Apple Privacy Policy ([https://www.apple.com/legal/privacy/](https://www.apple.com/legal/privacy/))
* Rotten Tomatoes (rottentomatoes.com): Terms of Service ([https://www.rottentomatoes.com/policies/terms-and-policies](https://www.rottentomatoes.com/policies/terms-and-policies)), Privacy Policy ([https://www.versantprivacy.com/privacy](https://www.versantprivacy.com/privacy) — Rotten Tomatoes is part of the Versant family of brands, which hosts the consolidated privacy policy linked from rottentomatoes.com)
* Goodreads (goodreads.com): Terms of Service ([https://www.goodreads.com/about/terms](https://www.goodreads.com/about/terms)), Privacy Policy ([https://www.goodreads.com/about/privacy](https://www.goodreads.com/about/privacy))

If you paste a URL from a different publisher or rating service, the same one-time HTML fetch happens against that URL only — please consult that site's own terms and privacy policy.

== Changelog ==

= 0.2.4 =
* Settings page now shows WordPress's standard "Settings saved." notice after a successful save.
* WordPress.org package documentation now describes only the features available in the submitted package.

= 0.2.3 =
* WordPress.org review follow-up: removed production-shipped local workspace plugin-row labeling and the review-risky plugin-root constant usage behind it.
* Hardened frontend escaping by replacing remaining output-ignore comments with explicit escaping helpers.
* Cleaned remaining short-prefix local variables and comments. Public shortcode and block APIs now use the mentionfetch slug only.

= 0.2.1 =
* WordPress.org compliance hardening: the distributed package now shows only controls and templates that are physically present in the package.
* Saved display presets are fully usable without a preset cap.
* Removed unavailable-feature notices from package templates.
* Legacy query parameter leftovers renamed for prefix consistency.
* External Services readme section extended to document the public-page metadata fetch path used at URL import.

= 0.2.0 =
* Renamed plugin from MentionPress to MentionFetch for WordPress.org trademark compliance.
* New plugin slug and shortcode: mentionfetch.
* Internal identifiers updated to the mentionfetch prefix family for WordPress.org guidelines.
* Inline scripts moved to wp_add_inline_script() / external JS files per WordPress.org enqueue requirements.
* Output escaping hardened across frontend and widget output.
* API key sanitization improved: uses character-class regex instead of sanitize_text_field() to preserve valid key characters.
* Added External Services section to readme documenting optional OpenAI API usage with terms and privacy links.

= 0.1.2 =
* Improved metadata parsing for public article pages.
* Redesign the MentionFetch Details meta box as a compact two-column grid.
* Add inline help icons next to MentionFetch Details fields with instant tooltips explaining ambiguous fields (Source Logo vs. Image, rating scale semantics, etc.).

= 0.1.1 =
* Fix Freemius opt-in flow: "Complete MentionFetch Activation Now" link is no longer swallowed by the top-level admin redirect, so submenus appear after opt-in or skip.

= 0.1.0 =
* Initial MVP release.
* URL import with metadata parsing and preview.
* Mention item and post save destinations.
* Shortcode and Gutenberg block frontend output.
* Existing posts rendering mode.
* Featured image sideload.
* Duplicate import guard.
* Source published date ordering.
* MentionFetch Details meta box.
* Live card preview on import screen.
