'rest-api', 'title' => 'REST API (auto-discovery)', 'available' => self::is_available(), ); } /** * Emit the baseline discovery derived from the site's own registries. * * @param Registry $registry The collector. */ public function provide( Registry $registry ) { if ( ! self::is_available() ) { return; } /** * Toggle REST auto-discovery off entirely. * * @param bool $enabled Default true. */ if ( ! apply_filters( 'agentimus_rest_discovery', true ) ) { return; } $namespaces = (array) rest_get_server()->get_namespaces(); // Whatever explicit providers already registered (we run late, priority 99). // A namespace any of these already describe is left to them — we only fill // gaps, so the auto-stub never shadows or duplicates a first-class entry. $existing = $registry->resources(); // 1. WordPress core content, with capabilities derived from the public, // REST-enabled post types and taxonomies actually registered here. // Root, not prefix: another provider owning a route INSIDE wp/v2 (any // CPT with show_in_rest does) must not silence core's own content. if ( in_array( 'wp/v2', $namespaces, true ) && ! isset( $existing['wordpress-core'] ) && ! self::is_root_described( 'wp/v2', $existing ) ) { $registry->register( array( 'id' => 'wordpress-core', 'title' => __( 'Your site’s content', 'agentimus' ), 'type' => 'content', 'description' => __( 'Your posts, pages and everything else you publish, in a form an AI assistant can read.', 'agentimus' ), 'capabilities' => self::content_capabilities(), 'endpoints' => array( array( 'url' => '/wp-json/wp/v2', 'type' => 'rest', 'methods' => array( 'GET' ), 'auth' => 'none', 'description' => __( 'Public WordPress REST API (read).', 'agentimus' ), ), ), ) ); } $skip = (array) apply_filters( 'agentimus_rest_skip_namespaces', self::SKIP ); /** * Allow-list of third-party REST namespaces to PUBLISH. Default is the * owner's "Detected REST APIs" checklist (a setting) — nothing third-party * is published unless explicitly opted in, so the document stays clean * (no automatic rule reliably tells an agent-useful API from internal * plumbing, so the owner decides). * * @param string[] $allowed Namespace names to publish. */ $allowed = (array) apply_filters( 'agentimus_rest_namespaces', self::allowed() ); // 2. Only the third-party namespaces the owner opted in (or a filter added) // AND that no explicit provider has already described. foreach ( $namespaces as $namespace ) { if ( ! self::is_third_party( $namespace, $skip ) || ! self::is_allowed( $namespace, $allowed ) ) { continue; } if ( self::is_described( $namespace, $existing ) ) { continue; } $registry->register( array( 'id' => self::slug( $namespace ), 'title' => (string) $namespace, 'type' => 'x-rest-api', 'description' => __( 'A plugin’s own data door. You chose to list it; the plugin says nothing more about it.', 'agentimus' ), 'endpoints' => array( array( 'url' => '/wp-json/' . $namespace, 'type' => 'rest', 'auth' => 'none' ), ), ) ); } } /** * Third-party namespaces detected on this site — the candidates the owner can * opt into publishing (the full detected set, not the published subset). * * @return string[] */ public static function detected() { if ( ! self::is_available() ) { return array(); } $skip = (array) apply_filters( 'agentimus_rest_skip_namespaces', self::SKIP ); $out = array(); foreach ( (array) rest_get_server()->get_namespaces() as $namespace ) { if ( self::is_third_party( $namespace, $skip ) ) { $out[] = (string) $namespace; } } sort( $out ); return $out; } /** * The owner's opted-in namespace allow-list, from settings. * * @return string[] */ private static function allowed() { if ( ! class_exists( '\Agentimus\Settings' ) ) { return array(); } return array_values( (array) ( new \Agentimus\Settings() )->get( 'rest_namespaces', array() ) ); } /** * Content capabilities for `wordpress-core`, derived ONLY from the post types * the owner enabled in Content types (settings.post_types) and the taxonomies * attached to them — so unchecking "Products" really does drop * content.product.read from discovery. Consistent with what feeds llms.txt / * markdown / schema. * * @return string[] */ private static function content_capabilities() { $selected = array(); if ( class_exists( '\Agentimus\Settings' ) ) { $selected = (array) ( new \Agentimus\Settings() )->get( 'post_types', array() ); } $post_objects = array(); foreach ( (array) get_post_types( array( 'public' => true, 'show_in_rest' => true ), 'objects' ) as $obj ) { if ( in_array( $obj->name, $selected, true ) ) { $post_objects[] = $obj; } } // Taxonomies attached to the selected post types (public, REST-enabled). $tax_names = array(); foreach ( $post_objects as $obj ) { foreach ( (array) get_object_taxonomies( $obj->name, 'names' ) as $tax_name ) { $tax_names[ $tax_name ] = true; } } $tax_objects = array(); foreach ( array_keys( $tax_names ) as $tax_name ) { $tax = get_taxonomy( $tax_name ); if ( $tax && ! empty( $tax->public ) && ! empty( $tax->show_in_rest ) ) { $tax_objects[] = $tax; } } return self::core_capabilities( self::rest_bases( $post_objects ), self::rest_bases( $tax_objects ) ); } /* ---------------------------------------------------------------------- * * Pure helpers (no WordPress dependency — unit-tested) * ---------------------------------------------------------------------- */ /** * Map REST bases of post types + taxonomies to dot-notation read capabilities. * * @param string[] $post_bases Post-type REST bases (e.g. posts, pages). * @param string[] $tax_bases Taxonomy REST bases (e.g. categories, tags). * @return string[] Deduplicated `content..read` tokens. */ public static function core_capabilities( array $post_bases, array $tax_bases ) { $caps = array(); foreach ( array_merge( $post_bases, $tax_bases ) as $base ) { $base = sanitize_key( (string) $base ); if ( '' !== $base ) { $caps[] = 'content.' . $base . '.read'; } } return array_values( array_unique( $caps ) ); } /** * Whether a namespace belongs to a third-party plugin (not core / us / a * dedicated adapter), and therefore worth surfacing as a discovered API. * * @param string $namespace REST namespace, e.g. "acme/v1". * @param string[] $skip Prefixes to exclude. * @return bool */ public static function is_third_party( $namespace, array $skip ) { $namespace = (string) $namespace; if ( '' === $namespace ) { return false; } foreach ( $skip as $prefix ) { if ( '' !== $prefix && 0 === strpos( $namespace, (string) $prefix ) ) { return false; } } return true; } /** * A valid resource-id slug for a namespace. Any run of non-alphanumeric * characters (slashes, underscores, dots) becomes a single hyphen, so the * result always satisfies the Resource id pattern: "wc/v3/wc_paypal" → * "wc-v3-wc-paypal", "acme/v1" → "acme-v1". * * @param string $namespace REST namespace. * @return string */ public static function slug( $namespace ) { $slug = preg_replace( '/[^a-z0-9]+/', '-', strtolower( (string) $namespace ) ); return trim( (string) $slug, '-' ); } /** * Whether a namespace is on the owner's publish allow-list. * * @param string $namespace Namespace. * @param string[] $allowed Allow-list (opted-in namespaces). * @return bool */ public static function is_allowed( $namespace, array $allowed ) { return in_array( (string) $namespace, $allowed, true ); } /** * Whether an explicit provider has already described this namespace, in which * case the auto-stub is skipped. True when either: * - a resource already exists under the id this adapter would mint for the * namespace (an intentional override), or * - any existing resource has an endpoint pointing into `/wp-json/`. * * Pure: takes the resources map (id => resource) so it is unit-testable. * * @param string $namespace REST namespace, e.g. "acme/v1". * @param array $resources Already-registered resources, keyed by id. * @return bool */ /** * Whether a resource describes a namespace's ROOT — the namespace itself, * rather than merely a route that happens to live inside it. * * `wp/v2` is core's shared namespace, not any one plugin's: every custom * post type registered with `show_in_rest` and no `rest_namespace` of its * own lands a route inside it. Judged by {@see is_described()}, a single * provider naming one product endpoint was enough to answer "already * covered" for the whole of core — so a site's posts, pages, media and * taxonomies vanished from discovery.json while still answering 200 to * anyone who asked for them. A plugin describing its OWN namespace is the * opposite case and keeps the prefix match. * * @param string $namespace REST namespace. * @param array $resources Already-registered resources. * @return bool */ public static function is_root_described( $namespace, array $resources ) { if ( isset( $resources[ self::slug( $namespace ) ] ) ) { return true; } $namespace = strtolower( trim( (string) $namespace, '/' ) ); if ( '' === $namespace ) { return false; } $token = '/' . $namespace; foreach ( $resources as $resource ) { $endpoints = isset( $resource['endpoints'] ) ? (array) $resource['endpoints'] : array(); foreach ( $endpoints as $endpoint ) { $url = isset( $endpoint['url'] ) ? $endpoint['url'] : ''; $url = rtrim( strtolower( (string) preg_replace( '/[?#].*$/', '', (string) $url ) ), '/' ); if ( '' !== $url && strlen( $url ) >= strlen( $token ) && substr( $url, -strlen( $token ) ) === $token ) { return true; } } } return false; } public static function is_described( $namespace, array $resources ) { if ( isset( $resources[ self::slug( $namespace ) ] ) ) { return true; } foreach ( $resources as $resource ) { $endpoints = isset( $resource['endpoints'] ) ? (array) $resource['endpoints'] : array(); foreach ( $endpoints as $endpoint ) { $url = isset( $endpoint['url'] ) ? $endpoint['url'] : ''; if ( self::endpoint_covers( $url, $namespace ) ) { return true; } } } return false; } /** * Whether an endpoint URL addresses a given REST namespace — i.e. its path * contains `/` as a whole segment run (so "acme/v1" matches * "/wp-json/acme/v1" and "…/acme/v1/products" but never "…/acme/v10"). * Query/fragment and a trailing slash are ignored. * * @param string $url Endpoint URL (relative or absolute). * @param string $namespace REST namespace. * @return bool */ public static function endpoint_covers( $url, $namespace ) { $url = strtolower( (string) preg_replace( '/[?#].*$/', '', (string) $url ) ); $url = rtrim( $url, '/' ); $namespace = strtolower( (string) $namespace ); if ( '' === $url || '' === $namespace ) { return false; } $token = '/' . $namespace; $pos = strpos( $url, $token ); if ( false === $pos ) { return false; } $after = substr( $url, $pos + strlen( $token ) ); return '' === $after || '/' === $after[0]; } /** * Extract REST bases from post-type / taxonomy objects (WP-coupled glue). * * @param array $objects WP_Post_Type[] | WP_Taxonomy[]. * @return string[] */ private static function rest_bases( $objects ) { $bases = array(); foreach ( (array) $objects as $obj ) { if ( ! is_object( $obj ) ) { continue; } $base = ! empty( $obj->rest_base ) ? $obj->rest_base : ( ! empty( $obj->name ) ? $obj->name : '' ); if ( '' !== $base ) { $bases[] = $base; } } return $bases; } }