Update docs and tests

Author: gziolo

includes/abilities-api/class-wp-ability.php

@@ -27,20 +27,20 @@ class WP_Ability {
 	 * @var array<string,(bool|string)>
 	 */
 	protected static $default_annotations = array(
-		// An instruction on how to use the ability.
-		'instruction' => '',
+		// Instructions on how to use the ability.
+		'instructions' => '',
 		// If true, the ability does not modify its environment.
-		'read_only'   => false,
+		'read_only'    => false,
 		/*
 		 * If true, the ability may perform destructive updates to its environment.
 		 * If false, the ability performs only additive updates.
 		 */
-		'destructive' => true,
+		'destructive'  => true,
 		/*
 		 * If true, calling the ability repeatedly with the same arguments will have no additional effect
 		 * on its environment.
 		 */
-		'idempotent'  => false,
+		'idempotent'   => false,
 	);
 
 	/**

packages/client/README.md

@@ -28,13 +28,13 @@ const { getAbilities, getAbility, executeAbility } = wp.abilities;
 const abilities = await getAbilities();
 
 // Get a specific ability
-const ability = await getAbility('my-plugin/my-ability');
+const ability = await getAbility( 'my-plugin/my-ability' );
 
 // Execute an ability
-const result = await executeAbility('my-plugin/my-ability', {
+const result = await executeAbility( 'my-plugin/my-ability', {
   param1: 'value1',
   param2: 'value2',
-});
+} );
 ```
 
 ### Using with React and WordPress Data
@@ -47,24 +47,24 @@ import { store as abilitiesStore } from '@wordpress/abilities';
 
 function MyComponent() {
   const abilities = useSelect(
-    (select) => select(abilitiesStore).getAbilities(),
+    ( select ) => select( abilitiesStore ).getAbilities(),
     []
   );
 
   const specificAbility = useSelect(
-    (select) => select(abilitiesStore).getAbility('my-plugin/my-ability'),
+    ( select ) => select( abilitiesStore ).getAbility( 'my-plugin/my-ability' ),
     []
   );
 
   return (
     <div>
       <h2>All Abilities</h2>
       <ul>
-        {abilities.map((ability) => (
-          <li key={ability.name}>
-            <strong>{ability.label}</strong>: {ability.description}
+        { abilities.map( ( ability ) => (
+          <li key={ ability.name }>
+            <strong>{ ability.label }</strong>: { ability.description }
           </li>
-        ))}
+        ) ) }
       </ul>
     </div>
   );
@@ -81,38 +81,38 @@ Returns all registered abilities. Automatically handles pagination to fetch all
 
 ```javascript
 const abilities = await getAbilities();
-console.log(`Found ${abilities.length} abilities`);
+console.log( `Found ${ abilities.length } abilities` );
 ```
 
 #### `getAbility(name: string): Promise<Ability | null>`
 
 Returns a specific ability by name, or null if not found.
 
 ```javascript
-const ability = await getAbility('my-plugin/create-post');
-if (ability) {
-  console.log(`Found ability: ${ability.label}`);
+const ability = await getAbility( 'my-plugin/create-post' );
+if ( ability ) {
+  console.log( `Found ability: ${ ability.label }` );
 }
 ```
 
 #### `executeAbility(name: string, input?: Record<string, any>): Promise<any>`
 
-Executes an ability with optional input parameters. The HTTP method is automatically determined based on the ability's type:
+Executes an ability with optional input parameters. The HTTP method is automatically determined based on the ability's annotations:
 
-- `resource` type abilities use GET (read-only operations)
-- `tool` type abilities use POST (write operations)
+- `read_only` abilities use GET (read-only operations)
+- regular abilities use POST (write operations)
 
 ```javascript
-// Execute a resource ability (GET)
-const data = await executeAbility('my-plugin/get-data', {
+// Execute a read only ability (GET)
+const data = await executeAbility( 'my-plugin/get-data', {
   id: 123,
-});
+} );
 
-// Execute a tool ability (POST)
-const result = await executeAbility('my-plugin/create-item', {
+// Execute a regular ability (POST)
+const result = await executeAbility( 'my-plugin/create-item', {
   title: 'New Item',
   content: 'Item content',
-});
+} );
 ```
 
 ### Store Selectors

packages/client/src/__tests__/api.test.ts

@@ -259,12 +259,12 @@ describe( 'API functions', () => {
 			).rejects.toThrow( 'invalid input' );
 		} );
 
-		it( 'should execute a resource-type ability via GET', async () => {
+		it( 'should execute a read only ability via GET', async () => {
 			const mockAbility: Ability = {
-				name: 'test/resource',
-				label: 'Resource Ability',
-				description: 'Test resource ability',
-				meta: { type: 'resource' },
+				name: 'test/read-only',
+				label: 'Read only Ability',
+				description: 'Test read only ability.',
+				annotations: { read_only: true },
 				input_schema: {
 					type: 'object',
 					properties: {
@@ -280,27 +280,27 @@ describe( 'API functions', () => {
 				getAbility: mockGetAbility,
 			} );
 
-			const mockResponse = { data: 'resource data' };
+			const mockResponse = { data: 'read only data' };
 			( apiFetch as unknown as jest.Mock ).mockResolvedValue(
 				mockResponse
 			);
 
 			const input = { id: '123', format: 'json' };
-			const result = await executeAbility( 'test/resource', input );
+			const result = await executeAbility( 'test/read-only', input );
 
 			expect( apiFetch ).toHaveBeenCalledWith( {
-				path: '/wp/v2/abilities/test/resource/run?input%5Bid%5D=123&input%5Bformat%5D=json',
+				path: '/wp/v2/abilities/test/read-only/run?input%5Bid%5D=123&input%5Bformat%5D=json',
 				method: 'GET',
 			} );
 			expect( result ).toEqual( mockResponse );
 		} );
 
-		it( 'should execute a resource-type ability with empty input', async () => {
+		it( 'should execute a read only ability with empty input', async () => {
 			const mockAbility: Ability = {
-				name: 'test/resource',
-				label: 'Resource Ability',
-				description: 'Test resource ability',
-				meta: { type: 'resource' },
+				name: 'test/read-only',
+				label: 'Read only Ability',
+				description: 'Test read only ability.',
+				annotations: { read_only: true },
 				input_schema: { type: 'object' },
 				output_schema: { type: 'object' },
 			};
@@ -310,15 +310,15 @@ describe( 'API functions', () => {
 				getAbility: mockGetAbility,
 			} );
 
-			const mockResponse = { data: 'all resources' };
+			const mockResponse = { data: 'read only data' };
 			( apiFetch as unknown as jest.Mock ).mockResolvedValue(
 				mockResponse
 			);
 
-			const result = await executeAbility( 'test/resource', {} );
+			const result = await executeAbility( 'test/read-only', {} );
 
 			expect( apiFetch ).toHaveBeenCalledWith( {
-				path: '/wp/v2/abilities/test/resource/run?',
+				path: '/wp/v2/abilities/test/read-only/run?',
 				method: 'GET',
 			} );
 			expect( result ).toEqual( mockResponse );

packages/client/src/store/__tests__/reducer.test.ts

@@ -118,46 +118,21 @@ describe( 'Store Reducer', () => {
 				).not.toHaveProperty( '_embedded' );
 			} );
 
-			it( 'should filter out location property', () => {
-				const abilities = [
-					{
-						name: 'test/ability',
-						label: 'Test Ability',
-						description: 'Test ability with location',
-						location: 'client',
-					},
-				];
-
-				const action = {
-					type: RECEIVE_ABILITIES,
-					abilities,
-				};
-
-				const state = reducer(
-					{ abilitiesByName: defaultState },
-					action
-				);
-
-				expect(
-					state.abilitiesByName[ 'test/ability' ]
-				).not.toHaveProperty( 'location' );
-			} );
-
 			it( 'should preserve all valid ability properties', () => {
 				const abilities = [
 					{
 						name: 'test/ability',
 						label: 'Test Ability',
-						description: 'Full test ability',
+						description: 'Full test ability.',
 						input_schema: { type: 'object' },
 						output_schema: { type: 'object' },
-						meta: { type: 'resource' as const },
+						annotations: { read_only: true },
+						meta: { category: 'test' },
 						callback: () => Promise.resolve( {} ),
 						permissionCallback: () => true,
 						// Extra properties that should be filtered out
 						_links: { self: { href: '/test' } },
 						_embedded: { test: 'value' },
-						location: 'client',
 						extra_field: 'should be removed',
 					},
 				];
@@ -176,17 +151,17 @@ describe( 'Store Reducer', () => {
 				// Should have valid properties
 				expect( ability.name ).toBe( 'test/ability' );
 				expect( ability.label ).toBe( 'Test Ability' );
-				expect( ability.description ).toBe( 'Full test ability' );
+				expect( ability.description ).toBe( 'Full test ability.' );
 				expect( ability.input_schema ).toEqual( { type: 'object' } );
 				expect( ability.output_schema ).toEqual( { type: 'object' } );
-				expect( ability.meta ).toEqual( { type: 'resource' } );
+				expect( ability.annotations ).toEqual( { read_only: true } );
+				expect( ability.meta ).toEqual( { category: 'test' } );
 				expect( ability.callback ).toBeDefined();
 				expect( ability.permissionCallback ).toBeDefined();
 
 				// Should NOT have invalid properties
 				expect( ability ).not.toHaveProperty( '_links' );
 				expect( ability ).not.toHaveProperty( '_embedded' );
-				expect( ability ).not.toHaveProperty( 'location' );
 				expect( ability ).not.toHaveProperty( 'extra_field' );
 			} );
 		} );
@@ -225,7 +200,6 @@ describe( 'Store Reducer', () => {
 					description: 'Test ability',
 					callback: () => Promise.resolve( {} ),
 					// Extra properties that should be filtered out
-					location: 'client',
 					_links: { self: { href: '/test' } },
 					extra_field: 'should be removed',
 				};
@@ -249,7 +223,6 @@ describe( 'Store Reducer', () => {
 				expect( registeredAbility.callback ).toBeDefined();
 
 				// Should NOT have invalid properties
-				expect( registeredAbility ).not.toHaveProperty( 'location' );
 				expect( registeredAbility ).not.toHaveProperty( '_links' );
 				expect( registeredAbility ).not.toHaveProperty( 'extra_field' );
 			} );

packages/client/src/store/reducer.ts

@@ -23,6 +23,7 @@ const ABILITY_KEYS = [
 	'description',
 	'input_schema',
 	'output_schema',
+	'annotations',
 	'meta',
 	'callback',
 	'permissionCallback',

packages/client/src/types.ts

@@ -69,7 +69,7 @@ export interface Ability {
 	permissionCallback?: PermissionCallback;
 
 	/**
-	 * Annotation for the ability.
+	 * Annotations for the ability.
 	 * @see WP_Ability::get_annotations()
 	 */
 	annotations?: {

tests/unit/abilities-api/wpAbilitiesRegistry.php

@@ -59,6 +59,9 @@ public function set_up(): void {
 			'permission_callback' => static function (): bool {
 				return true;
 			},
+			'annotations'         => array(
+				'read_only' => true,
+			),
 			'meta'                => array(
 				'category' => 'math',
 			),

tests/unit/abilities-api/wpAbility.php

@@ -29,6 +29,9 @@ public function set_up(): void {
 			'permission_callback' => static function (): bool {
 				return true;
 			},
+			'annotations'         => array(
+				'read_only' => true,
+			),
 			'meta'                => array(
 				'category' => 'math',
 			),

tests/unit/abilities-api/wpRegisterAbility.php

@@ -60,6 +60,9 @@ public function set_up(): void {
 			'permission_callback' => static function (): bool {
 				return true;
 			},
+			'annotations'         => array(
+				'read_only' => true,
+			),
 			'meta'                => array(
 				'category' => 'math',
 			),
@@ -132,6 +135,7 @@ public function test_register_valid_ability(): void {
 		$this->assertSame( self::$test_ability_args['description'], $result->get_description() );
 		$this->assertSame( self::$test_ability_args['input_schema'], $result->get_input_schema() );
 		$this->assertSame( self::$test_ability_args['output_schema'], $result->get_output_schema() );
+		$this->assertSame( self::$test_ability_args['annotations'], $result->get_annotations() );
 		$this->assertSame( self::$test_ability_args['meta'], $result->get_meta() );
 		$this->assertTrue(
 			$result->check_permissions(

tests/unit/rest-api/wpRestAbilitiesListController.php

@@ -84,7 +84,7 @@ public function tear_down(): void {
 	 * Register test abilities for testing.
 	 */
 	private function register_test_abilities(): void {
-		// Register a tool ability
+		// Register a regular ability.
 		wp_register_ability(
 			'test/calculator',
 			array(
@@ -127,7 +127,7 @@ private function register_test_abilities(): void {
 			)
 		);
 
-		// Register a resource ability
+		// Register a read only ability.
 		wp_register_ability(
 			'test/system-info',
 			array(
@@ -163,6 +163,9 @@ private function register_test_abilities(): void {
 				'permission_callback' => static function () {
 					return current_user_can( 'read' );
 				},
+				'annotations'         => array(
+					'read_only' => true,
+				),
 				'meta'                => array(
 					'category' => 'system',
 				),