@relvehq/agent-ready 0.2.1 → 0.3.0

package/dist/wp/relve-agent-ready/includes/class-relve-ar-settings.php

@@ -6,6 +6,14 @@
  *   post_types      string[]  default post, page
  *   excluded_paths  string    one path prefix per line
  *   llms_mode       string    auto|on|off, default auto
+ *   openai_key      string    the site's own OpenAI key (stored here only, never
+ *                             shown in full; sent only to the Relve refine endpoint)
+ *   refine_model    string    gpt-4o-mini (default), gpt-4o, gpt-4.1, gpt-4.1-mini
+ *   refine_on_save  bool      default true (only acts once a key is saved)
+ *
+ * The settings form never posts `openai_key`; it posts `openai_key_new` (a
+ * replacement, empty = keep) and `openai_key_remove`. A submission without
+ * either keeps the saved key.
  *
  * @package Relve_Agent_Ready
  */
@@ -24,6 +32,12 @@ class Relve_AR_Settings {
 	/** Paths never worth serving as Markdown (segment-aware prefixes). */
 	const DEFAULT_EXCLUDED = "/wp-admin\n/wp-login.php\n/wp-json\n/wp-content\n/wp-includes\n/feed\n/cart\n/checkout\n/my-account\n/account";
 
+	/** Models the Relve refine endpoint accepts (contract.md). */
+	const MODELS = array( 'gpt-4o-mini', 'gpt-4o', 'gpt-4.1', 'gpt-4.1-mini' );
+
+	/** Default model: fast enough for the endpoint's ~30 s request limit. */
+	const DEFAULT_MODEL = 'gpt-4o-mini';
+
 	/**
 	 * Defaults.
 	 *
@@ -35,9 +49,43 @@ class Relve_AR_Settings {
 			'post_types'     => array( 'post', 'page' ),
 			'excluded_paths' => self::DEFAULT_EXCLUDED,
 			'llms_mode'      => 'auto',
+			'openai_key'     => '',
+			'refine_model'   => self::DEFAULT_MODEL,
+			'refine_on_save' => true,
 		);
 	}
 
+	/**
+	 * Masked key for display: "sk-...abcd". Never the full key.
+	 *
+	 * @param string $key Key.
+	 * @return string
+	 */
+	public static function mask_key( $key ) {
+		$key = (string) $key;
+		if ( '' === $key ) {
+			return '';
+		}
+		if ( strlen( $key ) < 12 ) {
+			return '****';
+		}
+		return substr( $key, 0, 3 ) . '...' . substr( $key, -4 );
+	}
+
+	/**
+	 * A cleaned key, or null when it does not look like an OpenAI key.
+	 *
+	 * @param string $raw Raw input.
+	 * @return string|null
+	 */
+	public static function clean_key( $raw ) {
+		$key = preg_replace( '/\s+/', '', (string) $raw );
+		if ( null === $key || ! preg_match( '/^[A-Za-z0-9_\-]{20,300}$/', $key ) ) {
+			return null;
+		}
+		return $key;
+	}
+
 	/**
 	 * Current settings merged over the defaults, plus "excluded" as a list.
 	 *
@@ -46,9 +94,12 @@ class Relve_AR_Settings {
 	public static function get() {
 		$stored = get_option( self::OPTION, array() );
 		$s      = array_merge( self::defaults(), is_array( $stored ) ? $stored : array() );
-		$s['enabled']    = (bool) $s['enabled'];
-		$s['post_types'] = array_values( array_filter( (array) $s['post_types'], 'is_string' ) );
-		$s['excluded']   = self::lines( $s['excluded_paths'] );
+		$s['enabled']        = (bool) $s['enabled'];
+		$s['post_types']     = array_values( array_filter( (array) $s['post_types'], 'is_string' ) );
+		$s['excluded']       = self::lines( $s['excluded_paths'] );
+		$s['openai_key']     = is_string( $s['openai_key'] ) ? $s['openai_key'] : '';
+		$s['refine_model']   = in_array( $s['refine_model'], self::MODELS, true ) ? $s['refine_model'] : self::DEFAULT_MODEL;
+		$s['refine_on_save'] = (bool) $s['refine_on_save'];
 		return $s;
 	}
 
@@ -110,6 +161,41 @@ class Relve_AR_Settings {
 
 		$mode             = isset( $input['llms_mode'] ) ? (string) $input['llms_mode'] : 'auto';
 		$out['llms_mode'] = in_array( $mode, array( 'auto', 'on', 'off' ), true ) ? $mode : 'auto';
+
+		// OpenAI key: replace, remove, or keep. WordPress may run this callback
+		// a second time on its own output (first save), which carries
+		// `openai_key` itself; that value is re-validated and kept.
+		$stored  = get_option( self::OPTION, array() );
+		$current = ( is_array( $stored ) && isset( $stored['openai_key'] ) && is_string( $stored['openai_key'] ) ) ? $stored['openai_key'] : '';
+		$new     = isset( $input['openai_key_new'] ) ? trim( (string) $input['openai_key_new'] ) : '';
+		$changed = false;
+		if ( '' !== $new ) {
+			$clean = self::clean_key( $new );
+			if ( null === $clean ) {
+				$out['openai_key'] = $current;
+				if ( function_exists( 'add_settings_error' ) ) {
+					add_settings_error( self::OPTION, 'relve_ar_bad_key', __( 'That does not look like an OpenAI API key. The saved key was kept.', 'relve-agent-ready' ) );
+				}
+			} else {
+				$out['openai_key'] = $clean;
+				$changed           = $clean !== $current;
+			}
+		} elseif ( ! empty( $input['openai_key_remove'] ) ) {
+			$out['openai_key'] = '';
+			$changed           = '' !== $current;
+		} elseif ( isset( $input['openai_key'] ) ) {
+			$clean             = self::clean_key( (string) $input['openai_key'] );
+			$out['openai_key'] = null === $clean ? $current : $clean;
+		} else {
+			$out['openai_key'] = $current;
+		}
+		if ( $changed && class_exists( 'Relve_AR_Refiner' ) ) {
+			Relve_AR_Refiner::key_changed( '' !== $out['openai_key'] );
+		}
+
+		$model               = isset( $input['refine_model'] ) ? (string) $input['refine_model'] : self::DEFAULT_MODEL;
+		$out['refine_model'] = in_array( $model, self::MODELS, true ) ? $model : self::DEFAULT_MODEL;
+		$out['refine_on_save'] = ! empty( $input['refine_on_save'] );
 		return $out;
 	}
 }

package/dist/wp/relve-agent-ready/includes/class-relve-ar-store.php

@@ -288,6 +288,46 @@ class Relve_AR_Store {
 		return false !== file_put_contents( $file, $content ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents
 	}
 
+	/**
+	 * Is there a stored file at this relative path?
+	 *
+	 * @param string $rel Relative path ("blog/my-post.md").
+	 * @return bool
+	 */
+	public function exists( $rel ) {
+		$check = self::validate_entry( 'md/' . $rel );
+		if ( 'store' !== $check['status'] ) {
+			return false;
+		}
+		$file = $this->md_dir() . '/' . $check['path'];
+		return is_file( $file ) && $this->inside( $file );
+	}
+
+	/**
+	 * Delete one stored file.
+	 *
+	 * @param string $rel Relative path.
+	 * @return bool Whether a file was deleted.
+	 */
+	public function delete( $rel ) {
+		if ( ! $this->exists( $rel ) ) {
+			return false;
+		}
+		return unlink( $this->md_dir() . '/' . $rel ); // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink
+	}
+
+	/**
+	 * Relative file the router looks up first for a URL path (the full path,
+	 * as uploads and the npm refine name them), or null for a bad path.
+	 *
+	 * @param string $path URL path ("/blog/my-post/").
+	 * @return string|null
+	 */
+	public static function rel_for_path( $path ) {
+		$list = self::candidates( $path );
+		return $list ? $list[0] : null;
+	}
+
 	/**
 	 * Delete every stored file (keeps the folder and its protection files).
 	 *

package/dist/wp/relve-agent-ready/readme.txt

@@ -4,7 +4,7 @@ Tags: markdown, llms.txt, ai, agents, seo
 Requires at least: 6.0
 Tested up to: 6.7
 Requires PHP: 7.4
-Stable tag: 0.1.0
+Stable tag: 0.2.0
 License: MIT
 License URI: https://opensource.org/licenses/MIT
 
@@ -25,18 +25,33 @@ What it serves:
 * Posts and pages (published, public, not password-protected, of the post types you enable): YAML front matter (title, canonical, author, published, modified, categories, tags, description, source), one `# Title` heading, the featured image and the content converted to Markdown (headings, lists, links, images, tables, code blocks).
 * The posts front page and category, tag and author archives: a heading and a list of their latest 50 posts.
 * `llms.txt` under your home path: your site name, tagline and links to the `.md` version of up to 200 recent posts and pages.
-* Refined files: upload the zip Relve produces for your site and those hand-checked Markdown files are served first.
+* Rewritten files: with your own OpenAI key, each post is rewritten into clean Markdown with Relve's prompt (see below) and served first.
+* Refined files: upload a zip of Markdown files (a top-level `md/` folder) and those files are served first.
 
 Response headers: `Content-Type: text/markdown; charset=utf-8`, `Vary: Accept`, `Link: <permalink>; rel="canonical"`, `X-Robots-Tag: noindex` (search engines keep indexing your HTML page), `x-markdown-tokens`, `ETag` (304 on `If-None-Match`), `x-agent-ready-source: native | stored | llms`. Markdown asked for by `Accept` is sent with `Cache-Control: private, max-age=300`; `.md`, `?format=md` and llms.txt with `Cache-Control: public, s-maxage=300, stale-while-revalidate=86400`.
 
 The plugin is installed switched off. Nothing changes until you tick "Enabled" in Settings -> Agent Ready.
 
+= Better Markdown with your own OpenAI key =
+
+The Markdown built from WordPress is faithful but plain. For agent-ready pages that read well (a clear summary, clean headings, tables kept, theme clutter gone), save your OpenAI API key in Settings -> Agent Ready:
+
+* When a post of an enabled type is published or updated, WP-Cron sends it about 30 seconds later (never while you wait on the editor) to Relve's refine service at `https://relvehq.com/api/agent-ready/v1/refine`: the permalink, and a small HTML page with the title, description, canonical link, structured data and the rendered content.
+* Relve rewrites it with its own prompt, using your key for that single OpenAI call, checks the result and sends back the Markdown. The plugin stores it as that post's file in `wp-content/uploads/relve-agent-ready/md/`; it is served first (`x-agent-ready-source: stored`).
+* A post that has not changed since its last rewrite is answered "unchanged" without a model call, so it costs nothing.
+* "Rewrite all now" queues every published post of the enabled types; WP-Cron works through them 5 at a time. The settings page shows progress, posts rewritten, the last run and the last error code.
+* If OpenAI rejects the key or the account is out of quota, rewriting pauses and an admin notice says so. Saving a new key resumes it.
+* Unpublishing or deleting a post deletes its rewritten file. If a rewrite fails, the previous file (or the Markdown built from WordPress) keeps being served.
+* Models: `gpt-4o-mini` (default, the fastest), `gpt-4o`, `gpt-4.1`, `gpt-4.1-mini`. Every call spends your own OpenAI key; no Relve account is needed.
+
+The key is stored in your site's own options, shown masked (`sk-...abcd`) and only ever sent to the Relve endpoint over https, with redirects disabled. A developer can point the plugin at another endpoint with the `RELVE_AR_REFINE_ENDPOINT` constant or the `relve_ar_refine_endpoint` filter; anything other than https (or http on localhost, for testing) is refused and the key is not sent.
+
 == Installation ==
 
 1. Upload the `relve-agent-ready` zip in Plugins -> Add New -> Upload Plugin, then activate it.
 2. Go to Settings -> Agent Ready, tick "Enabled" and save.
 3. Optional: choose post types, add excluded paths, pick the llms.txt mode.
-4. Optional: upload the refined-files zip Relve sent you.
+4. Optional: paste your OpenAI API key, save, then click "Rewrite all now".
 5. Run the three test commands shown in the Status panel.
 
 == Frequently Asked Questions ==
@@ -57,6 +72,18 @@ The plugin sets `DONOTCACHEPAGE` on every Markdown response and tells WP Rocket
 
 The description in the front matter uses your Yoast meta description when there is one. If Yoast's own llms.txt feature is on, the "auto" mode leaves llms.txt to Yoast; choose "On" to serve this plugin's version instead.
 
+= Does Relve see my OpenAI key? =
+
+It passes through Relve's server for the single call that rewrites a post: the plugin sends it in a request header over https, Relve uses it for that one OpenAI call, and does not store or log it. It is never returned and never written to a database, file or cache on Relve's side. On your site it is kept in the plugin's option in your own database, like other plugin API keys, and is never shown in full on the settings page. Relve also receives the post's public permalink and content, which are public anyway. Remove the key at any time with "Remove the saved key"; deleting the plugin deletes it too.
+
+= What does rewriting cost? =
+
+Your OpenAI usage for each rewrite (one model call per changed post, typically a few thousand tokens). Unchanged posts cost nothing.
+
+= Why does the status say "rejected" or "too_little_text" for a post? =
+
+`rejected` means the rewrite did not pass Relve's quality check twice; `too_little_text` means the post is too short to be worth rewriting. Nothing is stored for that post and the Markdown built from WordPress keeps being served.
+
 = What is in the refined-files zip? =
 
 A top-level `md/` folder with one `.md` file per URL path (`/` is `md/index.md`, `/blog/my-post/` is `md/blog/my-post.md`). Other files (such as `.json` sidecars) are skipped. Entries outside `md/`, absolute paths and paths containing `..` are rejected. Uploading replaces the stored set. Files are kept in `wp-content/uploads/relve-agent-ready/md/`, behind a deny-all `.htaccess`, and are only ever sent as text.
@@ -67,9 +94,15 @@ Drafts, private and password-protected posts, post types you did not enable, sea
 
 = What happens when I uninstall? =
 
-Deactivating flushes rewrite rules and removes the WP Rocket rules. Deleting the plugin also removes its settings and the refined-files folder.
+Deactivating flushes rewrite rules, removes the WP Rocket rules and cancels scheduled rewrites. Deleting the plugin also removes its settings (including the OpenAI key), its rewrite status and post meta, and the refined-files folder.
 
 == Changelog ==
 
+= 0.2.0 =
+* Better Markdown with your own OpenAI key: posts are rewritten with Relve's prompt through Relve's refine API, in WP-Cron, on publish and update.
+* "Rewrite all now" works through all posts 5 at a time, with progress on the settings page.
+* Status: key saved, posts rewritten, last run, last error code. Rewriting pauses with an admin notice when OpenAI rejects the key or the quota runs out.
+* Unpublished and deleted posts lose their rewritten file. "Clear refined files" also resets the rewrite fingerprints.
+
 = 0.1.0 =
 * First release: Markdown for posts, pages, the front page and archives via Accept, `.md` and `?format=md`; llms.txt; refined-files upload; WP Rocket and Yoast awareness; settings page with status and test commands.

package/dist/wp/relve-agent-ready/relve-agent-ready.php

@@ -2,8 +2,8 @@
 /**
  * Plugin Name:       Relve Agent Ready
  * Plugin URI:        https://relvehq.com/agent-md
- * Description:       Serves a Markdown version of posts, pages and archives to AI agents (Accept: text/markdown, .md URLs, ?format=md) plus an llms.txt. Browsers are never affected. Off until enabled in Settings -> Agent Ready.
- * Version:           0.1.0
+ * Description:       Serves a Markdown version of posts, pages and archives to AI agents (Accept: text/markdown, .md URLs, ?format=md) plus an llms.txt. Optionally rewrites posts into better Markdown with Relve's prompt and your own OpenAI key. Browsers are never affected. Off until enabled in Settings -> Agent Ready.
+ * Version:           0.2.0
  * Requires at least: 6.0
  * Requires PHP:      7.4
  * Author:            Relve
@@ -19,10 +19,17 @@ if ( ! defined( 'ABSPATH' ) ) {
 	exit;
 }
 
-define( 'RELVE_AR_VERSION', '0.1.0' );
+define( 'RELVE_AR_VERSION', '0.2.0' );
 define( 'RELVE_AR_FILE', __FILE__ );
 define( 'RELVE_AR_DIR', plugin_dir_path( __FILE__ ) );
 
+// The Relve refine endpoint. Define it in wp-config.php to override (https
+// only; http is accepted for localhost). Also filterable:
+// relve_ar_refine_endpoint.
+if ( ! defined( 'RELVE_AR_REFINE_ENDPOINT' ) ) {
+	define( 'RELVE_AR_REFINE_ENDPOINT', 'https://relvehq.com/api/agent-ready/v1/refine' );
+}
+
 require_once RELVE_AR_DIR . 'includes/class-relve-ar-settings.php';
 require_once RELVE_AR_DIR . 'includes/class-relve-ar-negotiation.php';
 require_once RELVE_AR_DIR . 'includes/class-relve-ar-converter.php';
@@ -31,6 +38,7 @@ require_once RELVE_AR_DIR . 'includes/class-relve-ar-response.php';
 require_once RELVE_AR_DIR . 'includes/class-relve-ar-llms.php';
 require_once RELVE_AR_DIR . 'includes/class-relve-ar-store.php';
 require_once RELVE_AR_DIR . 'includes/class-relve-ar-router.php';
+require_once RELVE_AR_DIR . 'includes/class-relve-ar-refiner.php';
 
 /**
  * Activation: default settings (disabled), the refined-files folder with its
@@ -48,12 +56,14 @@ function relve_ar_activate() {
 }
 
 /**
- * Deactivation: flush rewrite rules and drop our WP Rocket reject rules.
- * Settings and refined files are kept (uninstall removes them).
+ * Deactivation: flush rewrite rules, drop our WP Rocket reject rules and
+ * every scheduled rewrite. Settings and refined files are kept (uninstall
+ * removes them).
  *
  * @return void
  */
 function relve_ar_deactivate() {
+	Relve_AR_Refiner::unschedule_all();
 	flush_rewrite_rules();
 	remove_filter( 'rocket_cache_reject_uri', array( 'Relve_AR_Router', 'rocket_reject_uri' ) );
 	Relve_AR_Router::refresh_rocket();
@@ -63,6 +73,7 @@ register_activation_hook( __FILE__, 'relve_ar_activate' );
 register_deactivation_hook( __FILE__, 'relve_ar_deactivate' );
 
 Relve_AR_Router::init();
+Relve_AR_Refiner::init();
 
 if ( is_admin() ) {
 	require_once RELVE_AR_DIR . 'includes/class-relve-ar-admin.php';

package/dist/wp/relve-agent-ready/uninstall.php

@@ -1,6 +1,8 @@
 <?php
 /**
- * Uninstall: remove the option and the refined-files folder.
+ * Uninstall: remove the options (settings, including the OpenAI key; refine
+ * state; refine queue), the refine post meta, any scheduled rewrites and the
+ * refined-files folder.
  *
  * @package Relve_Agent_Ready
  */
@@ -12,12 +14,21 @@ if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
 require_once __DIR__ . '/includes/class-relve-ar-negotiation.php';
 require_once __DIR__ . '/includes/class-relve-ar-store.php';
 
-delete_option( 'relve_agent_ready' );
+foreach ( array( 'relve_agent_ready', 'relve_agent_ready_refine', 'relve_agent_ready_refine_queue' ) as $relve_ar_option ) {
+	delete_option( $relve_ar_option );
+	if ( is_multisite() ) {
+		delete_site_option( $relve_ar_option );
+	}
+}
+delete_transient( 'relve_ar_refine_lock' );
 
-if ( is_multisite() ) {
-	delete_site_option( 'relve_agent_ready' );
+foreach ( array( '_relve_ar_fingerprint', '_relve_ar_refined_at', '_relve_ar_refined_path' ) as $relve_ar_meta_key ) {
+	delete_post_meta_by_key( $relve_ar_meta_key );
 }
 
+wp_unschedule_hook( 'relve_ar_refine_post' );
+wp_unschedule_hook( 'relve_ar_refine_batch' );
+
 $relve_ar_store = new Relve_AR_Store();
 $relve_ar_store->delete_all();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relvehq/agent-ready",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "Make your site agent-ready: serve every page as clean Markdown to AI agents (Accept: text/markdown, .md URLs, llms.txt), refine it with AI ahead of time, and prove it with a free checker and a visits dashboard. Next.js adapter included.",
   "keywords": [