← All changes | modules/shortlinks/abilities/class-shortlinks-abilities.php +207 -0 16.2-beta → 16.3 View file →

		@@ -1,0 +1,207 @@
	1	+<?php
	2	+/**
	3	+ * Jetpack Shortlinks Abilities Registration
	4	+ *
	5	+ * Registers Jetpack WP.me Shortlinks abilities with the WordPress Abilities API.
	6	+ *
	7	+ * @package automattic/jetpack
	8	+ */
	9	+
	10	+namespace Automattic\Jetpack\Plugin\Abilities;
	11	+
	12	+use Automattic\Jetpack\Connection\Manager as Connection_Manager;
	13	+use Automattic\Jetpack\WP_Abilities\Registrar;
	14	+
	15	+/**
	16	+ * Registers Jetpack WP.me Shortlinks abilities with the WordPress Abilities API.
	17	+ *
	18	+ * Exposes a single read ability that returns wp.me shortlinks for the
	19	+ * requested posts and (optionally) the site homepage so AI agents can fetch
	20	+ * shareable URLs in bulk through the standard `wp-abilities/v1` REST surface.
	21	+ */
	22	+class Shortlinks_Abilities extends Registrar {
	23	+
	24	+ /**
	25	+ * Maximum number of post IDs accepted per call.
	26	+ */
	27	+ const MAX_POST_IDS = 100;
	28	+
	29	+ /**
	30	+ * Returns the category slug this registrar owns.
	31	+ *
	32	+ * @return string
	33	+ */
	34	+ public static function get_category_slug(): string {
	35	+ return 'jetpack-shortlinks';
	36	+ }
	37	+
	38	+ /**
	39	+ * Returns the category definition passed to wp_register_ability_category().
	40	+ *
	41	+ * @return array
	42	+ */
	43	+ public static function get_category_definition(): array {
	44	+ return array(
	45	+ // "Jetpack" is a product name and should not be translated.
	46	+ 'label' => 'Jetpack WP.me Shortlinks',
	47	+ 'description' => __( 'Abilities for retrieving wp.me shortlinks for posts, pages, attachments, and the site homepage.', 'jetpack' ),
	48	+ );
	49	+ }
	50	+
	51	+ /**
	52	+ * Returns the ability specs this registrar owns as a [ slug => spec ] map.
	53	+ *
	54	+ * @return array<string, array>
	55	+ */
	56	+ public static function get_abilities(): array {
	57	+ $item_schema = array(
	58	+ 'type' => 'object',
	59	+ 'properties' => array(
	60	+ 'post_id' => array(
	61	+ 'type' => 'integer',
	62	+ 'description' => __( '0 for the site homepage entry; otherwise the WordPress post ID.', 'jetpack' ),
	63	+ ),
	64	+ 'post_title' => array( 'type' => 'string' ),
	65	+ 'post_type' => array(
	66	+ 'type' => 'string',
	67	+ 'description' => __( '"blog" for the homepage entry; otherwise the WordPress post type slug (post, page, attachment, or a CPT that supports shortlinks).', 'jetpack' ),
	68	+ ),
	69	+ 'shortlink' => array(
	70	+ 'type' => 'string',
	71	+ 'description' => __( 'The wp.me URL.', 'jetpack' ),
	72	+ ),
	73	+ 'target_url' => array(
	74	+ 'type' => 'string',
	75	+ 'description' => __( 'The canonical permalink the shortlink resolves to.', 'jetpack' ),
	76	+ ),
	77	+ ),
	78	+ );
	79	+
	80	+ return array(
	81	+ 'jetpack-shortlinks/get-shortlinks' => array(
	82	+ 'label' => __( 'Get wp.me shortlinks', 'jetpack' ),
	83	+ 'description' => __( 'Return wp.me shortlinks for the given posts and (optionally) the site homepage. Each result is a { post_id, post_title, post_type, shortlink, target_url } object — post_id is 0 for the homepage entry, post_type is "blog". IDs that do not exist, are unreadable to the current user, or belong to a post type without shortlinks support are silently omitted (returns a shorter array, not WP_Error). Caps post_ids at 100 per call. Requires the WP.me Shortlinks Jetpack module (slug: shortlinks) to be active and the site to be connected; an unconnected site returns jetpack_shortlinks_blog_id_unavailable. Use jetpack/get-modules to verify the module is on, jetpack/set-module-status to activate it.', 'jetpack' ),
	84	+ 'input_schema' => array(
	85	+ 'type' => 'object',
	86	+ 'default' => array(),
	87	+ 'properties' => array(
	88	+ 'post_ids' => array(
	89	+ 'type' => 'array',
	90	+ 'description' => __( 'Up to 100 post IDs to fetch shortlinks for. Order is preserved in the response. Defaults to an empty list.', 'jetpack' ),
	91	+ 'maxItems' => self::MAX_POST_IDS,
	92	+ 'items' => array(
	93	+ 'type' => 'integer',
	94	+ 'minimum' => 1,
	95	+ ),
	96	+ ),
	97	+ 'include_blog' => array(
	98	+ 'type' => 'boolean',
	99	+ 'description' => __( 'When true, prepend a single entry for the site homepage (post_id 0, post_type "blog") to the response.', 'jetpack' ),
	100	+ 'default' => false,
	101	+ ),
	102	+ ),
	103	+ 'additionalProperties' => false,
	104	+ ),
	105	+ 'output_schema' => array(
	106	+ 'type' => 'array',
	107	+ 'items' => $item_schema,
	108	+ ),
	109	+ 'execute_callback' => array( __CLASS__, 'get_shortlinks' ),
	110	+ 'permission_callback' => array( __CLASS__, 'can_view_shortlinks' ),
	111	+ 'meta' => array(
	112	+ 'annotations' => array(
	113	+ 'readonly' => true,
	114	+ 'destructive' => false,
	115	+ 'idempotent' => true,
	116	+ ),
	117	+ 'show_in_rest' => true,
	118	+ 'mcp' => array(
	119	+ 'public' => true,
	120	+ 'type' => 'tool', // default is already "tool", but can be explicit.
	121	+ ),
	122	+ ),
	123	+ ),
	124	+ );
	125	+ }
	126	+
	127	+ /**
	128	+ * Permission check: require edit_posts so only users with content-management
	129	+ * rights may enumerate shortlinks. Per-post read capability is still
	130	+ * enforced inside the execute callback so unreadable IDs are silently
	131	+ * omitted rather than failing the whole call.
	132	+ */
	133	+ public static function can_view_shortlinks(): bool {
	134	+ return current_user_can( 'edit_posts' );
	135	+ }
	136	+
	137	+ /**
	138	+ * Execute: return wp.me shortlinks for the requested posts and (optionally) the homepage.
	139	+ *
	140	+ * @param array|null $input Input matching the ability's input_schema.
	141	+ * @return array|\WP_Error
	142	+ */
	143	+ public static function get_shortlinks( $input = null ) {
	144	+ $input = is_array( $input ) ? $input : array();
	145	+
	146	+ if ( null === Connection_Manager::get_site_id( true ) ) {
	147	+ return new \WP_Error(
	148	+ 'jetpack_shortlinks_blog_id_unavailable',
	149	+ __( 'No Jetpack/WordPress.com blog ID is available for this site. Connect Jetpack before requesting wp.me shortlinks.', 'jetpack' )
	150	+ );
	151	+ }
	152	+
	153	+ $post_ids = array();
	154	+ if ( isset( $input['post_ids'] ) && is_array( $input['post_ids'] ) ) {
	155	+ foreach ( $input['post_ids'] as $candidate ) {
	156	+ $candidate_id = absint( $candidate );
	157	+ if ( $candidate_id > 0 ) {
	158	+ $post_ids[] = $candidate_id;
	159	+ }
	160	+ }
	161	+ }
	162	+ if ( count( $post_ids ) > self::MAX_POST_IDS ) {
	163	+ $post_ids = array_slice( $post_ids, 0, self::MAX_POST_IDS );
	164	+ }
	165	+
	166	+ $include_blog = ! empty( $input['include_blog'] );
	167	+
	168	+ $out = array();
	169	+
	170	+ if ( $include_blog ) {
	171	+ $blog_shortlink = wp_get_shortlink( 0, 'blog' );
	172	+ if ( is_string( $blog_shortlink ) && '' !== $blog_shortlink ) {
	173	+ $out[] = array(
	174	+ 'post_id' => 0,
	175	+ 'post_title' => (string) get_bloginfo( 'name' ),
	176	+ 'post_type' => 'blog',
	177	+ 'shortlink' => $blog_shortlink,
	178	+ 'target_url' => home_url( '/' ),
	179	+ );
	180	+ }
	181	+ }
	182	+
	183	+ if ( ! empty( $post_ids ) ) {
	184	+ _prime_post_caches( $post_ids, false, false );
	185	+ }
	186	+
	187	+ foreach ( $post_ids as $post_id ) {
	188	+ $post = get_post( $post_id );
	189	+ if ( ! $post || ! current_user_can( 'read_post', $post_id ) ) {
	190	+ continue;
	191	+ }
	192	+ $shortlink = wp_get_shortlink( $post_id, 'post' );
	193	+ if ( ! is_string( $shortlink ) || '' === $shortlink ) {
	194	+ continue;
	195	+ }
	196	+ $out[] = array(
	197	+ 'post_id' => (int) $post->ID,
	198	+ 'post_title' => (string) $post->post_title,
	199	+ 'post_type' => (string) $post->post_type,
	200	+ 'shortlink' => $shortlink,
	201	+ 'target_url' => (string) get_permalink( $post ),
	202	+ );
	203	+ }
	204	+
	205	+ return $out;
	206	+ }
	207	+}