@relvehq/agent-ready 0.3.0 → 0.4.0

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

@@ -1,201 +1,210 @@
-<?php
-/**
- * Settings: one option array, `relve_agent_ready`.
- *
- *   enabled         bool      default false (installing changes nothing)
- *   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
- */
-
-if ( ! defined( 'ABSPATH' ) ) {
-	exit;
-}
-
-/**
- * Settings access and sanitising.
- */
-class Relve_AR_Settings {
-
-	const OPTION = 'relve_agent_ready';
-
-	/** 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.
-	 *
-	 * @return array
-	 */
-	public static function defaults() {
-		return array(
-			'enabled'        => false,
-			'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.
-	 *
-	 * @return array
-	 */
-	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['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;
-	}
-
-	/**
-	 * Split the excluded-paths text into prefixes.
-	 *
-	 * @param string $text Text.
-	 * @return string[]
-	 */
-	public static function lines( $text ) {
-		$out = array();
-		foreach ( preg_split( '/\r\n|\r|\n/', (string) $text ) as $line ) {
-			$line = trim( $line );
-			if ( '' !== $line ) {
-				$out[] = $line;
-			}
-		}
-		return $out;
-	}
-
-	/**
-	 * Sanitise a submitted settings array (register_setting callback).
-	 *
-	 * @param mixed $input Raw input.
-	 * @return array
-	 */
-	public static function sanitize( $input ) {
-		$input = is_array( $input ) ? $input : array();
-		$out   = self::defaults();
-
-		$out['enabled'] = ! empty( $input['enabled'] );
-
-		$public = function_exists( 'get_post_types' ) ? get_post_types( array( 'public' => true ) ) : array( 'post' => 'post', 'page' => 'page' );
-		$types  = array();
-		foreach ( (array) ( isset( $input['post_types'] ) ? $input['post_types'] : array() ) as $t ) {
-			$t = sanitize_key( (string) $t );
-			if ( 'attachment' !== $t && isset( $public[ $t ] ) ) {
-				$types[] = $t;
-			}
-		}
-		$out['post_types'] = array_values( array_unique( $types ) );
-
-		$paths = array();
-		foreach ( self::lines( isset( $input['excluded_paths'] ) ? (string) $input['excluded_paths'] : '' ) as $line ) {
-			$line = sanitize_text_field( $line );
-			$line = preg_replace( '#[^A-Za-z0-9/_.~%@!$&\'()*+,;=:-]#', '', $line );
-			if ( '' === $line ) {
-				continue;
-			}
-			if ( '/' !== $line[0] ) {
-				$line = '/' . $line;
-			}
-			$paths[] = $line;
-			if ( count( $paths ) >= 200 ) {
-				break;
-			}
-		}
-		$out['excluded_paths'] = implode( "\n", array_unique( $paths ) );
-
-		$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;
-	}
-}
+<?php
+/**
+ * Settings: one option array, `relve_agent_ready`.
+ *
+ *   enabled         bool      default false (installing changes nothing)
+ *   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 (default), gpt-4.1, gpt-4.1-mini, gpt-4o-mini
+ *   refine_on_save  bool      default true (only acts once a key is saved)
+ *   share_stats     bool      default false: send each agent visit's stats
+ *                             (path, bot, tokens, bytes; never the Markdown or
+ *                             the visitor's IP) to Relve (Relve_AR_Reporter)
+ *
+ * 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
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Settings access and sanitising.
+ */
+class Relve_AR_Settings {
+
+	const OPTION = 'relve_agent_ready';
+
+	/** 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', 'gpt-4.1', 'gpt-4.1-mini', 'gpt-4o-mini' );
+
+	/**
+	 * Default model. Was gpt-4o-mini; on 2026-10-29 it gave example cards'
+	 * prices to the page itself, gpt-4o did not and was as fast.
+	 */
+	const DEFAULT_MODEL = 'gpt-4o';
+
+	/**
+	 * Defaults.
+	 *
+	 * @return array
+	 */
+	public static function defaults() {
+		return array(
+			'enabled'        => false,
+			'post_types'     => array( 'post', 'page' ),
+			'excluded_paths' => self::DEFAULT_EXCLUDED,
+			'llms_mode'      => 'auto',
+			'openai_key'     => '',
+			'refine_model'   => self::DEFAULT_MODEL,
+			'refine_on_save' => true,
+			'share_stats'    => false,
+		);
+	}
+
+	/**
+	 * 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.
+	 *
+	 * @return array
+	 */
+	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['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'];
+		$s['share_stats']    = (bool) $s['share_stats'];
+		return $s;
+	}
+
+	/**
+	 * Split the excluded-paths text into prefixes.
+	 *
+	 * @param string $text Text.
+	 * @return string[]
+	 */
+	public static function lines( $text ) {
+		$out = array();
+		foreach ( preg_split( '/\r\n|\r|\n/', (string) $text ) as $line ) {
+			$line = trim( $line );
+			if ( '' !== $line ) {
+				$out[] = $line;
+			}
+		}
+		return $out;
+	}
+
+	/**
+	 * Sanitise a submitted settings array (register_setting callback).
+	 *
+	 * @param mixed $input Raw input.
+	 * @return array
+	 */
+	public static function sanitize( $input ) {
+		$input = is_array( $input ) ? $input : array();
+		$out   = self::defaults();
+
+		$out['enabled'] = ! empty( $input['enabled'] );
+
+		$public = function_exists( 'get_post_types' ) ? get_post_types( array( 'public' => true ) ) : array( 'post' => 'post', 'page' => 'page' );
+		$types  = array();
+		foreach ( (array) ( isset( $input['post_types'] ) ? $input['post_types'] : array() ) as $t ) {
+			$t = sanitize_key( (string) $t );
+			if ( 'attachment' !== $t && isset( $public[ $t ] ) ) {
+				$types[] = $t;
+			}
+		}
+		$out['post_types'] = array_values( array_unique( $types ) );
+
+		$paths = array();
+		foreach ( self::lines( isset( $input['excluded_paths'] ) ? (string) $input['excluded_paths'] : '' ) as $line ) {
+			$line = sanitize_text_field( $line );
+			$line = preg_replace( '#[^A-Za-z0-9/_.~%@!$&\'()*+,;=:-]#', '', $line );
+			if ( '' === $line ) {
+				continue;
+			}
+			if ( '/' !== $line[0] ) {
+				$line = '/' . $line;
+			}
+			$paths[] = $line;
+			if ( count( $paths ) >= 200 ) {
+				break;
+			}
+		}
+		$out['excluded_paths'] = implode( "\n", array_unique( $paths ) );
+
+		$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'] );
+		$out['share_stats']    = ! empty( $input['share_stats'] );
+		return $out;
+	}
+}