@wordpress/abilities 0.2.0 → 0.2.1-next.738bb1424.0

package/src/tests/api.test.ts

@@ -5,8 +5,7 @@
 /**
  * WordPress dependencies
  */
-import { dispatch, select, resolveSelect } from '@wordpress/data';
-import apiFetch from '@wordpress/api-fetch';
+import { dispatch, select } from '@wordpress/data';
 
 /**
  * Internal dependencies
@@ -23,15 +22,11 @@ import {
 import { store } from '../store';
 import type { Ability, AbilityCategory } from '../types';
 
-// Mock WordPress dependencies
 jest.mock( '@wordpress/data', () => ( {
-	dispatch: jest.fn(),
 	select: jest.fn(),
-	resolveSelect: jest.fn(),
+	dispatch: jest.fn(),
 } ) );
 
-jest.mock( '@wordpress/api-fetch' );
-
 jest.mock( '../store', () => ( {
 	store: 'abilities-api/store',
 } ) );
@@ -42,7 +37,7 @@ describe( 'API functions', () => {
 	} );
 
 	describe( 'getAbilities', () => {
-		it( 'should resolve and return all abilities from the store', async () => {
+		it( 'should return all abilities from the store', () => {
 			const mockAbilities: Ability[] = [
 				{
 					name: 'test/ability1',
@@ -62,21 +57,19 @@ describe( 'API functions', () => {
 				},
 			];
 
-			const mockGetAbilities = jest
-				.fn()
-				.mockResolvedValue( mockAbilities );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbilities = jest.fn().mockReturnValue( mockAbilities );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbilities: mockGetAbilities,
 			} );
 
-			const result = await getAbilities();
+			const result = getAbilities();
 
-			expect( resolveSelect ).toHaveBeenCalledWith( store );
+			expect( select ).toHaveBeenCalledWith( store );
 			expect( mockGetAbilities ).toHaveBeenCalled();
 			expect( result ).toEqual( mockAbilities );
 		} );
 
-		it( 'should pass category parameter to store when filtering', async () => {
+		it( 'should pass category parameter to store when filtering', () => {
 			const mockAbilities: Ability[] = [
 				{
 					name: 'test/ability1',
@@ -96,16 +89,14 @@ describe( 'API functions', () => {
 				},
 			];
 
-			const mockGetAbilities = jest
-				.fn()
-				.mockResolvedValue( mockAbilities );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbilities = jest.fn().mockReturnValue( mockAbilities );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbilities: mockGetAbilities,
 			} );
 
-			const result = await getAbilities( { category: 'data-retrieval' } );
+			const result = getAbilities( { category: 'data-retrieval' } );
 
-			expect( resolveSelect ).toHaveBeenCalledWith( store );
+			expect( select ).toHaveBeenCalledWith( store );
 			expect( mockGetAbilities ).toHaveBeenCalledWith( {
 				category: 'data-retrieval',
 			} );
@@ -114,7 +105,7 @@ describe( 'API functions', () => {
 	} );
 
 	describe( 'getAbility', () => {
-		it( 'should return a specific ability by name', async () => {
+		it( 'should return a specific ability by name', () => {
 			const mockAbility: Ability = {
 				name: 'test/ability',
 				label: 'Test Ability',
@@ -124,29 +115,17 @@ describe( 'API functions', () => {
 				output_schema: { type: 'object' },
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
-			const result = await getAbility( 'test/ability' );
+			const result = getAbility( 'test/ability' );
 
-			expect( resolveSelect ).toHaveBeenCalledWith( store );
+			expect( select ).toHaveBeenCalledWith( store );
 			expect( mockGetAbility ).toHaveBeenCalledWith( 'test/ability' );
 			expect( result ).toEqual( mockAbility );
 		} );
-
-		it( 'should return null if ability not found', async () => {
-			const mockGetAbility = jest.fn().mockResolvedValue( null );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
-				getAbility: mockGetAbility,
-			} );
-
-			const result = await getAbility( 'non-existent' );
-
-			expect( mockGetAbility ).toHaveBeenCalledWith( 'non-existent' );
-			expect( result ).toBeNull();
-		} );
 	} );
 
 	describe( 'registerAbility', () => {
@@ -195,7 +174,10 @@ describe( 'API functions', () => {
 	} );
 
 	describe( 'executeAbility', () => {
-		it( 'should execute a server-side ability via API', async () => {
+		it( 'should execute a server-side ability via callback', async () => {
+			const mockServerCallback = jest
+				.fn()
+				.mockResolvedValue( { success: true, result: 'test' } );
 			const mockAbility: Ability = {
 				name: 'test/server-ability',
 				label: 'Server Ability',
@@ -209,30 +191,23 @@ describe( 'API functions', () => {
 					required: [ 'message' ],
 				},
 				output_schema: { type: 'object' },
+				callback: mockServerCallback,
+				meta: { annotations: { serverRegistered: true } },
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
-			const mockResponse = { success: true, result: 'test' };
-			( apiFetch as unknown as jest.Mock ).mockResolvedValue(
-				mockResponse
-			);
-
 			const input = { message: 'Hello' };
 			const result = await executeAbility( 'test/server-ability', input );
 
 			expect( mockGetAbility ).toHaveBeenCalledWith(
 				'test/server-ability'
 			);
-			expect( apiFetch ).toHaveBeenCalledWith( {
-				path: '/wp-abilities/v1/abilities/test/server-ability/run',
-				method: 'POST',
-				data: { input },
-			} );
-			expect( result ).toEqual( mockResponse );
+			expect( mockServerCallback ).toHaveBeenCalledWith( input );
+			expect( result ).toEqual( { success: true, result: 'test' } );
 		} );
 
 		it( 'should execute a client-side ability locally', async () => {
@@ -247,10 +222,11 @@ describe( 'API functions', () => {
 				input_schema: { type: 'object' },
 				output_schema: { type: 'object' },
 				callback: mockCallback,
+				meta: { annotations: { clientRegistered: true } },
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
@@ -261,13 +237,12 @@ describe( 'API functions', () => {
 				'test/client-ability'
 			);
 			expect( mockCallback ).toHaveBeenCalledWith( input );
-			expect( apiFetch ).not.toHaveBeenCalled();
 			expect( result ).toEqual( { success: true } );
 		} );
 
 		it( 'should throw error if ability not found', async () => {
-			const mockGetAbility = jest.fn().mockResolvedValue( null );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( null );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
@@ -292,10 +267,11 @@ describe( 'API functions', () => {
 				},
 				output_schema: { type: 'object' },
 				callback: mockCallback,
+				meta: { annotations: { clientRegistered: true } },
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
@@ -304,7 +280,10 @@ describe( 'API functions', () => {
 			).rejects.toThrow( 'invalid input' );
 		} );
 
-		it( 'should execute a read-only ability via GET', async () => {
+		it( 'should execute a read-only server ability', async () => {
+			const mockServerCallback = jest
+				.fn()
+				.mockResolvedValue( { data: 'read-only data' } );
 			const mockAbility: Ability = {
 				name: 'test/read-only',
 				label: 'Read-only Ability',
@@ -319,31 +298,27 @@ describe( 'API functions', () => {
 				},
 				output_schema: { type: 'object' },
 				meta: {
-					annotations: { readonly: true },
+					annotations: { serverRegistered: true, readonly: true },
 				},
+				callback: mockServerCallback,
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
-			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/read-only', input );
 
-			expect( apiFetch ).toHaveBeenCalledWith( {
-				path: '/wp-abilities/v1/abilities/test/read-only/run?input%5Bid%5D=123&input%5Bformat%5D=json',
-				method: 'GET',
-			} );
-			expect( result ).toEqual( mockResponse );
+			expect( mockServerCallback ).toHaveBeenCalledWith( input );
+			expect( result ).toEqual( { data: 'read-only data' } );
 		} );
 
 		it( 'should execute a read-only ability with empty input', async () => {
+			const mockServerCallback = jest
+				.fn()
+				.mockResolvedValue( { data: 'read-only data' } );
 			const mockAbility: Ability = {
 				name: 'test/read-only',
 				label: 'Read-only Ability',
@@ -352,30 +327,26 @@ describe( 'API functions', () => {
 				input_schema: { type: 'object' },
 				output_schema: { type: 'object' },
 				meta: {
-					annotations: { readonly: true },
+					annotations: { serverRegistered: true, readonly: true },
 				},
+				callback: mockServerCallback,
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
-			const mockResponse = { data: 'read-only data' };
-			( apiFetch as unknown as jest.Mock ).mockResolvedValue(
-				mockResponse
-			);
-
 			const result = await executeAbility( 'test/read-only', {} );
 
-			expect( apiFetch ).toHaveBeenCalledWith( {
-				path: '/wp-abilities/v1/abilities/test/read-only/run?',
-				method: 'GET',
-			} );
-			expect( result ).toEqual( mockResponse );
+			expect( mockServerCallback ).toHaveBeenCalledWith( {} );
+			expect( result ).toEqual( { data: 'read-only data' } );
 		} );
 
-		it( 'should execute a destructive idempotent ability via DELETE', async () => {
+		it( 'should execute a destructive idempotent server ability', async () => {
+			const mockServerCallback = jest
+				.fn()
+				.mockResolvedValue( 'Item deleted successfully.' );
 			const mockAbility: Ability = {
 				name: 'test/destructive',
 				label: 'Destructive Ability',
@@ -391,30 +362,24 @@ describe( 'API functions', () => {
 				output_schema: { type: 'string' },
 				meta: {
 					annotations: {
+						serverRegistered: true,
 						destructive: true,
 						idempotent: true,
 					},
 				},
+				callback: mockServerCallback,
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
-			const mockResponse = 'Item deleted successfully.';
-			( apiFetch as unknown as jest.Mock ).mockResolvedValue(
-				mockResponse
-			);
-
 			const input = { id: '123', format: 'json' };
 			const result = await executeAbility( 'test/destructive', input );
 
-			expect( apiFetch ).toHaveBeenCalledWith( {
-				path: '/wp-abilities/v1/abilities/test/destructive/run?input%5Bid%5D=123&input%5Bformat%5D=json',
-				method: 'DELETE',
-			} );
-			expect( result ).toEqual( mockResponse );
+			expect( mockServerCallback ).toHaveBeenCalledWith( input );
+			expect( result ).toEqual( 'Item deleted successfully.' );
 		} );
 
 		it( 'should handle errors in client ability execution', async () => {
@@ -432,10 +397,11 @@ describe( 'API functions', () => {
 				input_schema: { type: 'object' },
 				output_schema: { type: 'object' },
 				callback: mockCallback,
+				meta: { annotations: { clientRegistered: true } },
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
@@ -444,7 +410,7 @@ describe( 'API functions', () => {
 			).rejects.toThrow( 'Execution failed' );
 
 			expect( consoleErrorSpy ).toHaveBeenCalledWith(
-				'Error executing client ability test/client-ability:',
+				'Error executing ability test/client-ability:',
 				executionError
 			);
 
@@ -455,7 +421,10 @@ describe( 'API functions', () => {
 			const consoleErrorSpy = jest
 				.spyOn( console, 'error' )
 				.mockImplementation();
-			const apiError = new Error( 'API request failed' );
+			const serverError = new Error( 'Server execution failed' );
+			const mockServerCallback = jest
+				.fn()
+				.mockRejectedValue( serverError );
 
 			const mockAbility: Ability = {
 				name: 'test/server-ability',
@@ -464,28 +433,31 @@ describe( 'API functions', () => {
 				category: 'test-category',
 				input_schema: { type: 'object' },
 				output_schema: { type: 'object' },
+				callback: mockServerCallback,
+				meta: { annotations: { serverRegistered: true } },
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
-			( apiFetch as unknown as jest.Mock ).mockRejectedValue( apiError );
-
 			await expect(
 				executeAbility( 'test/server-ability', {} )
-			).rejects.toThrow( 'API request failed' );
+			).rejects.toThrow( 'Server execution failed' );
 
 			expect( consoleErrorSpy ).toHaveBeenCalledWith(
 				'Error executing ability test/server-ability:',
-				apiError
+				serverError
 			);
 
 			consoleErrorSpy.mockRestore();
 		} );
 
 		it( 'should execute ability without callback as server ability', async () => {
+			const mockServerCallback = jest
+				.fn()
+				.mockResolvedValue( { success: true } );
 			const mockAbility: Ability = {
 				name: 'test/ability',
 				label: 'Test Ability',
@@ -493,29 +465,24 @@ describe( 'API functions', () => {
 				category: 'test-category',
 				input_schema: { type: 'object' },
 				output_schema: { type: 'object' },
-				// No callback - should execute as server ability
+				// Server ability - should execute without client validation
+				callback: mockServerCallback,
+				meta: { annotations: { serverRegistered: true } },
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
-			const mockResponse = { success: true };
-			( apiFetch as unknown as jest.Mock ).mockResolvedValue(
-				mockResponse
-			);
-
 			const result = await executeAbility( 'test/ability', {
 				data: 'test',
 			} );
 
-			expect( apiFetch ).toHaveBeenCalledWith( {
-				path: '/wp-abilities/v1/abilities/test/ability/run',
-				method: 'POST',
-				data: { input: { data: 'test' } },
+			expect( mockServerCallback ).toHaveBeenCalledWith( {
+				data: 'test',
 			} );
-			expect( result ).toEqual( mockResponse );
+			expect( result ).toEqual( { success: true } );
 		} );
 
 		it( 'should validate output for client abilities', async () => {
@@ -536,10 +503,11 @@ describe( 'API functions', () => {
 					required: [ 'result' ],
 				},
 				callback: mockCallback,
+				meta: { annotations: { clientRegistered: true } },
 			};
 
-			const mockGetAbility = jest.fn().mockResolvedValue( mockAbility );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+			const mockGetAbility = jest.fn().mockReturnValue( mockAbility );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbility: mockGetAbility,
 			} );
 
@@ -550,7 +518,7 @@ describe( 'API functions', () => {
 	} );
 
 	describe( 'getAbilityCategories', () => {
-		it( 'should resolve and return all categories from the store', async () => {
+		it( 'should return all categories from the store', () => {
 			const mockCategories: AbilityCategory[] = [
 				{
 					slug: 'data-retrieval',
@@ -566,32 +534,32 @@ describe( 'API functions', () => {
 
 			const mockGetAbilityCategories = jest
 				.fn()
-				.mockResolvedValue( mockCategories );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+				.mockReturnValue( mockCategories );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbilityCategories: mockGetAbilityCategories,
 			} );
 
-			const result = await getAbilityCategories();
+			const result = getAbilityCategories();
 
-			expect( resolveSelect ).toHaveBeenCalledWith( store );
+			expect( select ).toHaveBeenCalledWith( store );
 			expect( mockGetAbilityCategories ).toHaveBeenCalled();
 			expect( result ).toEqual( mockCategories );
 		} );
 
-		it( 'should return empty array when no categories exist', async () => {
-			const mockGetAbilityCategories = jest.fn().mockResolvedValue( [] );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+		it( 'should return empty array when no categories exist', () => {
+			const mockGetAbilityCategories = jest.fn().mockReturnValue( [] );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbilityCategories: mockGetAbilityCategories,
 			} );
 
-			const result = await getAbilityCategories();
+			const result = getAbilityCategories();
 
 			expect( result ).toEqual( [] );
 		} );
 	} );
 
 	describe( 'getAbilityCategory', () => {
-		it( 'should return a specific category by slug', async () => {
+		it( 'should return a specific category by slug', () => {
 			const mockCategory: AbilityCategory = {
 				slug: 'data-retrieval',
 				label: 'Data Retrieval',
@@ -600,56 +568,42 @@ describe( 'API functions', () => {
 
 			const mockGetAbilityCategory = jest
 				.fn()
-				.mockResolvedValue( mockCategory );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+				.mockReturnValue( mockCategory );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbilityCategory: mockGetAbilityCategory,
 			} );
 
-			const result = await getAbilityCategory( 'data-retrieval' );
+			const result = getAbilityCategory( 'data-retrieval' );
 
-			expect( resolveSelect ).toHaveBeenCalledWith( store );
+			expect( select ).toHaveBeenCalledWith( store );
 			expect( mockGetAbilityCategory ).toHaveBeenCalledWith(
 				'data-retrieval'
 			);
 			expect( result ).toEqual( mockCategory );
 		} );
 
-		it( 'should return null if category not found', async () => {
-			const mockGetAbilityCategory = jest.fn().mockResolvedValue( null );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
-				getAbilityCategory: mockGetAbilityCategory,
-			} );
-
-			const result = await getAbilityCategory( 'non-existent' );
-
-			expect( mockGetAbilityCategory ).toHaveBeenCalledWith(
-				'non-existent'
-			);
-			expect( result ).toBeNull();
-		} );
-
-		it( 'should handle categories with meta', async () => {
+		it( 'should handle categories with meta', () => {
 			const mockCategory: AbilityCategory = {
 				slug: 'user-management',
 				label: 'User Management',
 				description: 'Abilities for managing users',
 				meta: {
-					priority: 'high',
+					annotations: { clientRegistered: true },
 				},
 			};
 
 			const mockGetAbilityCategory = jest
 				.fn()
-				.mockResolvedValue( mockCategory );
-			( resolveSelect as jest.Mock ).mockReturnValue( {
+				.mockReturnValue( mockCategory );
+			( select as jest.Mock ).mockReturnValue( {
 				getAbilityCategory: mockGetAbilityCategory,
 			} );
 
-			const result = await getAbilityCategory( 'user-management' );
+			const result = getAbilityCategory( 'user-management' );
 
 			expect( result ).toEqual( mockCategory );
 			expect( result?.meta ).toBeDefined();
-			expect( result?.meta?.priority ).toBe( 'high' );
+			expect( result?.meta?.annotations?.clientRegistered ).toBe( true );
 		} );
 	} );
 } );

package/src/types.ts

@@ -63,14 +63,13 @@ export interface Ability {
 	output_schema?: Record< string, any >;
 
 	/**
-	 * Callback function for client-side abilities.
-	 * If present, the ability will be executed locally in the browser.
-	 * If not present, the ability will be executed via REST API on the server.
+	 * Callback function for ability execution.
+	 * This property is required for all abilities.
 	 */
 	callback?: AbilityCallback;
 
 	/**
-	 * Client Permission callback for abilities.
+	 * Permission callback for abilities.
 	 * Called before executing the ability to check if it's allowed.
 	 * If it returns false, the ability execution will be denied.
 	 */
@@ -78,15 +77,15 @@ export interface Ability {
 
 	/**
 	 * Metadata about the ability.
-	 * @see WP_Ability::get_meta()
 	 */
 	meta?: {
 		annotations?: {
-			readonly?: boolean | null;
-			destructive?: boolean | null;
-			idempotent?: boolean | null;
+			clientRegistered?: boolean;
+			serverRegistered?: boolean;
+			readonly?: boolean;
+			destructive?: boolean;
+			idempotent?: boolean;
 		};
-		[ key: string ]: any;
 	};
 }
 
@@ -128,9 +127,13 @@ export interface AbilityCategory {
 
 	/**
 	 * Metadata about the category.
-	 * @see WP_Ability_Category::get_meta()
 	 */
-	meta?: Record< string, any >;
+	meta?: {
+		annotations?: {
+			clientRegistered?: boolean;
+			serverRegistered?: boolean;
+		};
+	};
 }
 
 /**
@@ -156,21 +159,6 @@ export interface AbilityCategoryArgs {
 	meta?: Record< string, any >;
 }
 
-/**
- * The state shape for the abilities store.
- */
-export interface AbilitiesState {
-	/**
-	 * Map of ability names to ability objects.
-	 */
-	abilitiesByName: Record< string, Ability >;
-
-	/**
-	 * Map of category slugs to category objects.
-	 */
-	categoriesBySlug: Record< string, AbilityCategory >;
-}
-
 /**
  * Input parameters for ability execution.
  * Can be any JSON-serializable value: primitive, array, object, or null.