Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
98.53% covered (success)
98.53%
67 / 68
88.89% covered (warning)
88.89%
8 / 9
CRAP
0.00% covered (danger)
0.00%
0 / 1
Connection_Abilities
98.53% covered (success)
98.53%
67 / 68
88.89% covered (warning)
88.89%
8 / 9
17
0.00% covered (danger)
0.00%
0 / 1
 enabled_by_default
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 get_category_slug
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 get_category_definition
100.00% covered (success)
100.00%
4 / 4
100.00% covered (success)
100.00%
1 / 1
1
 get_abilities
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
1
 spec_get_connection_status
100.00% covered (success)
100.00%
37 / 37
100.00% covered (success)
100.00%
1 / 1
1
 can_view_connection
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
1
 get_connection_status
100.00% covered (success)
100.00%
16 / 16
100.00% covered (success)
100.00%
1 / 1
6
 get_manager
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
2
 registration_url
66.67% covered (warning)
66.67%
2 / 3
0.00% covered (danger)
0.00%
0 / 1
3.33
1<?php
2/**
3 * Jetpack Connection Abilities Registration.
4 *
5 * Registers Jetpack Connection abilities with the WordPress Abilities API so
6 * AI agents can inspect the site's connection state through the standard
7 * `wp-abilities/v1` REST surface.
8 *
9 * @package automattic/jetpack-connection
10 */
11
12namespace Automattic\Jetpack\Connection\Abilities;
13
14use Automattic\Jetpack\Connection\Manager as Connection_Manager;
15use Automattic\Jetpack\Connection\Package_Version;
16use Automattic\Jetpack\WP_Abilities\Registrar;
17use Jetpack_Options;
18
19/**
20 * Registers Jetpack Connection abilities with the WordPress Abilities API.
21 *
22 * Exposes a single read-only ability for site-level connection state so AI
23 * agents can answer "is this site registered?" without having to
24 * reverse-engineer Jetpack_Options keys.
25 *
26 * Writes (registering a new site, disconnecting a user, transferring
27 * ownership) are deliberately deferred to a follow-up PR.
28 */
29class Connection_Abilities extends Registrar {
30
31    const CATEGORY_SLUG = 'jetpack';
32
33    /**
34     * {@inheritDoc}
35     */
36    protected static function enabled_by_default(): bool {
37        return true;
38    }
39
40    /**
41     * {@inheritDoc}
42     */
43    public static function get_category_slug(): string {
44        return self::CATEGORY_SLUG;
45    }
46
47    /**
48     * {@inheritDoc}
49     *
50     * The `jetpack` ability-category is shared with other Jetpack registrars
51     * (e.g. the Modules_Abilities class in the Jetpack plugin). Only the first
52     * registration wins, so the English source string is kept byte-identical
53     * across registrars to keep the visible category text consistent
54     * regardless of load order.
55     */
56    public static function get_category_definition(): array {
57        return array(
58            // "Jetpack" is a product name and should not be translated.
59            'label'       => 'Jetpack',
60            'description' => __( 'Abilities provided by Jetpack.', 'jetpack-connection' ),
61        );
62    }
63
64    /**
65     * {@inheritDoc}
66     */
67    public static function get_abilities(): array {
68        return array(
69            'jetpack/get-connection-status' => self::spec_get_connection_status(),
70        );
71    }
72
73    /*
74    ---------------------------------------------------------------------
75     * Ability specs
76     * ---------------------------------------------------------------------
77     */
78
79    /**
80     * Spec: jetpack/get-connection-status.
81     */
82    private static function spec_get_connection_status(): array {
83        return array(
84            'label'               => __( 'Get Jetpack connection status', 'jetpack-connection' ),
85            'description'         => __(
86                'Return the site-level Jetpack connection state in one call. Shape: { site_registered, user_connected, master_user, blog_id, registration_url, connection_version }. `site_registered` is true when the site has a blog id and a blog token. `user_connected` is true when at least one user has linked their WordPress.com account. `master_user` is the local user id of the connection owner (the user who registered the site), or null if there is no owner. `blog_id` is the WordPress.com site id, or null when the site has not been registered. `registration_url` is the wp-admin URL the site owner should visit to register the site when `site_registered` is false; null once the site is registered. `connection_version` is the running Jetpack Connection package version. Read-only and idempotent — safe to poll.',
87                'jetpack-connection'
88            ),
89            'input_schema'        => array(
90                'type'                 => 'object',
91                'additionalProperties' => false,
92            ),
93            'output_schema'       => array(
94                'type'       => 'object',
95                'properties' => array(
96                    'site_registered'    => array( 'type' => 'boolean' ),
97                    'user_connected'     => array( 'type' => 'boolean' ),
98                    'master_user'        => array( 'type' => array( 'integer', 'null' ) ),
99                    'blog_id'            => array( 'type' => array( 'integer', 'null' ) ),
100                    'registration_url'   => array( 'type' => array( 'string', 'null' ) ),
101                    'connection_version' => array( 'type' => 'string' ),
102                ),
103            ),
104            'execute_callback'    => array( __CLASS__, 'get_connection_status' ),
105            'permission_callback' => array( __CLASS__, 'can_view_connection' ),
106            'meta'                => array(
107                'annotations'  => array(
108                    'readonly'    => true,
109                    'destructive' => false,
110                    'idempotent'  => true,
111                ),
112                'public'       => true,
113                'show_in_rest' => true,
114                'mcp'          => array(
115                    'public' => true,
116                    'type'   => 'tool', // default is already "tool", but can be explicit.
117                ),
118            ),
119        );
120    }
121
122    /*
123    ---------------------------------------------------------------------
124     * Permission callbacks
125     * ---------------------------------------------------------------------
126     */
127
128    /**
129     * Permission check: mirrors the capability used by the Jetpack admin page.
130     *
131     * Connection state is not sensitive in itself (the same data is exposed
132     * on the Jetpack admin page and through several existing REST endpoints),
133     * but subscribers and contributors have no legitimate need to inspect it.
134     * Gating on `jetpack_admin_page` aligns with how {@see Modules_Abilities}
135     * scopes its read.
136     *
137     * @return bool
138     */
139    public static function can_view_connection(): bool {
140        return current_user_can( 'jetpack_admin_page' );
141    }
142
143    /*
144    ---------------------------------------------------------------------
145     * Execute callbacks
146     * ---------------------------------------------------------------------
147     */
148
149    /**
150     * Execute: get-connection-status.
151     *
152     * @param array|null $input Ignored — zero-arg ability.
153     * @return array
154     */
155    public static function get_connection_status( $input = null ) {
156        unset( $input );
157
158        $manager         = self::get_manager();
159        $site_registered = (bool) $manager->is_connected();
160        $user_connected  = (bool) $manager->has_connected_user();
161
162        $master_user_raw = Jetpack_Options::get_option( 'master_user' );
163        $master_user     = is_numeric( $master_user_raw ) && (int) $master_user_raw > 0 ? (int) $master_user_raw : null;
164
165        $blog_id_raw = Jetpack_Options::get_option( 'id' );
166        $blog_id     = is_numeric( $blog_id_raw ) && (int) $blog_id_raw > 0 ? (int) $blog_id_raw : null;
167
168        return array(
169            'site_registered'    => $site_registered,
170            'user_connected'     => $user_connected,
171            'master_user'        => $master_user,
172            'blog_id'            => $blog_id,
173            'registration_url'   => $site_registered ? null : self::registration_url(),
174            'connection_version' => Package_Version::PACKAGE_VERSION,
175        );
176    }
177
178    /*
179    ---------------------------------------------------------------------
180     * Helpers
181     * ---------------------------------------------------------------------
182     */
183
184    /**
185     * Return a Connection_Manager instance. Filterable for tests so they can
186     * inject a partial mock without having to seed Jetpack_Options + tokens.
187     *
188     * @return Connection_Manager
189     */
190    protected static function get_manager(): Connection_Manager {
191        /**
192         * Filters the Connection_Manager instance used by the Connection abilities.
193         *
194         * Tests inject a partial mock here; production callers should leave
195         * the default. The filter callback receives the package-default
196         * instance and must return a Connection_Manager — non-Manager
197         * returns are discarded.
198         *
199         * @since 8.4.0
200         *
201         * @param Connection_Manager $manager The default instance.
202         */
203        $instance = apply_filters( 'jetpack_connection_abilities_manager', new Connection_Manager() );
204        return $instance instanceof Connection_Manager ? $instance : new Connection_Manager();
205    }
206
207    /**
208     * Build the wp-admin URL the site owner should visit to register the
209     * site to WordPress.com. We deliberately return a stable admin URL (no
210     * secret generation, no XML-RPC roundtrip) so this read stays side-effect
211     * free and cheap to poll. The destination page handles the actual
212     * registration handshake from there.
213     *
214     * WP 7.0+ ships a core "Connectors" screen at `wp-admin/options-connectors.php`
215     * with a Jetpack card registered by {@see Jetpack_Connector}. We probe
216     * for the file directly (rather than a `class_exists()` on the registry)
217     * because the file is what actually serves the URL — if it isn't on
218     * disk, the redirect 404s regardless of which classes have loaded.
219     *
220     * @return string
221     */
222    private static function registration_url(): string {
223        if ( defined( 'ABSPATH' ) && file_exists( ABSPATH . 'wp-admin/options-connectors.php' ) ) {
224            return admin_url( 'options-connectors.php' );
225        }
226        return admin_url( 'admin.php?page=jetpack' );
227    }
228}