=== HarperFlow ===
Contributors: thefamoushesham
Tags: seo, faq, content, automation, geo
Requires at least: 5.6
Tested up to: 7.1
Requires PHP: 7.2
Stable tag: 1.5.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Exposes HarperFlow article metadata (SEO, FAQ, TL;DR, GEO) to the REST API and
optionally styles HarperFlow posts. Thin by design.

== Description ==

HarperFlow (https://harperflow.io) auto-publishes AI-written, GEO-optimized articles
to your WordPress site. Your posts publish and render natively in your theme **without
this plugin** — it is entirely optional. Installing it adds the extras WordPress core
has no home for:

* **SEO title & description** — written into Yoast or Rank Math when present, or
  emitted by the plugin itself when no SEO plugin is active.
* **Self-contained HarperFlow article components** — preserves the renderer's
  inline-styled feature header, table of contents, comparison cards, promotional
  CTAs, and author cards on REST writes for HarperFlow-authored posts only.
* **Styled TL;DR box** and **FAQ accordion** — rendered from HarperFlow's structured
  metadata, scoped only to HarperFlow-authored posts so the rest of your site is
  untouched.
* **FAQPage structured data (JSON-LD)** — improves visibility in Google and AI answer
  engines.

How it works:

1. Registers HarperFlow post meta (`_hf_*`) with `show_in_rest` so HarperFlow can
   write SEO/FAQ/TL;DR data over the REST API.
2. Re-exposes Yoast / Rank Math SEO meta over REST when those plugins are active
   (they hide those keys from REST by default).
3. Serves `GET /wp-json/harperflow/v1/health` so HarperFlow can detect the plugin and
   which SEO engine is live.
4. Preserves HarperFlow-rendered article HTML with a narrow KSES allowlist. Scripts,
   iframes, event handlers, and unsafe URL schemes are still stripped.
5. Adds a **HarperFlow** menu in wp-admin: connection status, the HarperFlow articles
   published to this site (with their content type + topic cluster), and a link into
   the full HarperFlow dashboard (autopilot, scheduling, veto inbox, GEO reports).

== Installation ==

1. Download `harperflow.zip`.
2. In your WordPress admin, go to **Plugins → Add New → Upload Plugin**.
3. Choose `harperflow.zip` and click **Install Now**, then **Activate**.
4. Go to **HarperFlow** in your wp-admin menu.
5. In your HarperFlow dashboard, add this WordPress site and copy the **pairing code**.
6. Paste the code into **Connect to HarperFlow** and click **Connect**.

That's it. One click links this site to your HarperFlow account — you never create or
copy a password. The plugin mints a WordPress Application Password for HarperFlow
automatically, registers the site, and enables one-click sign-in back to your dashboard.

== Frequently Asked Questions ==

= How do I connect my site to HarperFlow? =

Install and activate the plugin, open **HarperFlow** in your wp-admin menu, then paste the
**pairing code** from your HarperFlow dashboard into **Connect to HarperFlow** and click
Connect. The plugin does the rest.

= Do I need to create an Application Password myself? =

No. The plugin creates a WordPress Application Password named "HarperFlow" for you, using
WordPress core, and sends it securely to HarperFlow during the one-click connect. You never
create or copy a password. Application Passwords require WordPress 5.6+ and HTTPS; if they
are disabled on your site, the plugin tells you and you can connect from the HarperFlow
dashboard instead. Use **Disconnect** to revoke that password at any time.

= Do my articles still publish without this plugin? =

Yes. Posts publish and render in your theme either way. Without the plugin, the SEO
title/description and the dedicated styled FAQ/TL;DR sections are not added — but the
FAQ and TL;DR text is inlined into the post body, so no information is lost.

= Does it touch the rest of my site? =

No. The styling and the content additions only run on single posts that HarperFlow
authored (gated on a meta flag).

= Which SEO plugins are supported? =

Yoast SEO and Rank Math. HarperFlow writes the matching SEO meta when either is
active; otherwise the plugin emits a basic title and meta description itself.

== External services ==

This plugin connects your site to HarperFlow, a third-party Software-as-a-Service
platform (https://harperflow.io) that writes and publishes articles to your site.
The plugin communicates with two HarperFlow hosts:

* **api.harperflow.io** — the HarperFlow API.
* **app.harperflow.io** — the HarperFlow web dashboard (opened in your browser).

**What is sent, and when:**

* **On Connect** (you paste a pairing code and click Connect): your site URL, your
  WordPress username, and a WordPress Application Password the plugin mints for
  HarperFlow are sent to `api.harperflow.io` so HarperFlow can publish to your site.
  Nothing is sent until you initiate the connection.
* **On "Open HarperFlow Dashboard (SSO)"** (you click the button): your site host
  (used as your HarperFlow account identifier) and an HMAC-signed timestamp are sent
  to `api.harperflow.io` to mint a one-click sign-in link, then your browser opens
  `app.harperflow.io`.
* **On HarperFlow article writes**: HarperFlow calls this site's REST API (authenticated
  with the Application Password above) to publish or update its own articles. This
  plugin sends nothing outbound here; it only receives and stores the article data.

No data is transmitted for visitors of your site, and nothing is sent in the
background without an action you took. Use **Disconnect** at any time to revoke the
Application Password and clear the stored credentials.

By connecting, you agree to HarperFlow's Terms of Service
(https://www.harperflow.io/terms-of-service) and Privacy Policy
(https://www.harperflow.io/privacy-policy).

== Screenshots ==

1. The HarperFlow panel inside wp-admin — plugin status, one-click sign-in to your dashboard, and every published article tracked with its content type and topic cluster.
2. Connecting takes one step — paste the pairing code from your HarperFlow dashboard; no passwords or API keys to manage.
3. What a published HarperFlow article looks like on your site — a featured image, a styled comparison table, a TL;DR summary, an FAQ, and JSON-LD schema, engineered to be cited by AI search.

== Changelog ==

= 1.5.0 =
* Docs: added an External Services disclosure (the third-party HarperFlow hosts this
  plugin talks to, exactly what data is sent, and when) and bumped Tested up to 7.0.
* i18n: user-facing admin and front-end strings are now translatable under the
  `harperflow` text domain.
* Hardening: escapers are applied inline at every output site, and the FAQPage JSON-LD
  now encodes with JSON_HEX_TAG so a `</script>` in a question can never break out.
  No behavior change — lint/robustness only.

= 1.4.2 =
* Security: the "Open dashboard (SSO)" handshake now also refuses a non-https API URL, so
  the signed request is only ever sent over https. Completes the https enforcement started
  in 1.4.1 (which covered the connect handshake and the Advanced override) by applying the
  same guard to the third and last outbound call.

= 1.4.1 =
* Security: the Advanced API URL override now requires https:// — a non-secure override
  is rejected at save time with a clear error, and the one-click connect refuses to send
  your Application Password to a non-https API URL even if an old/injected setting has
  one (checked before minting the password, so nothing is created needlessly).
* Clarity: "Treat this code like a password — don't share it" warning next to the pairing
  code field. Whoever redeems the code first links your site to their HarperFlow account.

= 1.4.0 =
* New: true one-click connect. Enter the pairing code from your HarperFlow dashboard and
  click Connect — the plugin mints a WordPress Application Password via core
  (WP_Application_Passwords) and registers this site automatically. You never create or
  copy a password. Replaces the previous "paste your SSO key" step; the returned SSO
  secret is stored in the same option, so the existing HMAC style-preservation, one-click
  SSO, and SEO features work unchanged.
* New: Disconnect button — revokes the HarperFlow Application Password and clears the
  stored SSO secret. Reconnect anytime with a fresh pairing code.
* Clear errors for the WordPress < 5.6 / Application-Passwords-disabled cases (with a
  fallback to connecting from the HarperFlow dashboard).

= 1.3.1 =
* Security: bind style-preservation to a per-site HMAC signature (sso_secret)
  instead of the forgeable _hf_authored meta flag. Authors cannot inject inline
  CSS without a valid HarperFlow integration signature.
* Enhancement: allow color-mix(), clamp(), min(), max() CSS function values
  emitted by the adaptive renderer via the safecss_filter_attr_allow_css filter,
  with a tight security guard blocking url(), expression(), and javascript:.
* Hardening: wrap wp_kses in try/finally so an unexpected throw cannot leak the
  expanded CSS allowlist into other filters in the same request.

= 1.3.0 =
* New: preserve HarperFlow's inline-styled article components on REST writes for
  HarperFlow-authored posts only, while keeping scripts, iframes, event handlers,
  and unsafe URL schemes stripped.

= 1.2.0 =
* New: one-click SSO from wp-admin — “Open HarperFlow Dashboard (SSO)” signs you straight into your HarperFlow dashboard (no password). Paste the SSO key shown in the dashboard after connecting this site. Single-use, short-lived login tokens; minted server-to-server.

= 1.1.0 =
* New: HarperFlow admin dashboard page (wp-admin → HarperFlow) — connection status,
  recent HarperFlow articles with their GEO metadata, and a link into the web
  dashboard. Read-only; never mutates site data. Purely additive over 1.0.0.

= 1.0.0 =
* Initial release: REST-exposed HarperFlow meta, Yoast/Rank Math interop, health
  route, scoped TL;DR + FAQ rendering, FAQPage JSON-LD.
