@wordpress/abilities 0.1.1-next.dc3f6d3c1.0

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@wordpress/abilities",
+	"version": "0.1.1-next.dc3f6d3c1.0",
+	"description": "JavaScript client for WordPress Abilities API.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"abilities",
+		"api",
+		"ai"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/abilities/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/abilities"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=18.12.0",
+		"npm": ">=8.19.2"
+	},
+	"files": [
+		"build",
+		"build-module",
+		"build-types",
+		"src",
+		"*.md"
+	],
+	"main": "build/index.js",
+	"module": "build-module/index.js",
+	"react-native": "src/index",
+	"wpScript": true,
+	"types": "build-types",
+	"dependencies": {
+		"@wordpress/api-fetch": "^7.35.1-next.dc3f6d3c1.0",
+		"@wordpress/core-data": "^7.35.1-next.dc3f6d3c1.0",
+		"@wordpress/data": "^10.35.1-next.dc3f6d3c1.0",
+		"@wordpress/i18n": "^6.8.1-next.dc3f6d3c1.0",
+		"@wordpress/url": "^4.35.1-next.dc3f6d3c1.0",
+		"ajv": "^8.17.1",
+		"ajv-draft-04": "^1.0.0",
+		"ajv-formats": "^3.0.1"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "f73b5e69b34fbaccfb8c47783f4f993059ff1a41"
+}

package/src/api.ts

@@ -0,0 +1,339 @@
+/**
+ * WordPress dependencies
+ */
+import { dispatch, resolveSelect } from '@wordpress/data';
+import apiFetch from '@wordpress/api-fetch';
+import { addQueryArgs } from '@wordpress/url';
+import { sprintf } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { store } from './store';
+import type {
+	Ability,
+	AbilityCategory,
+	AbilityCategoryArgs,
+	AbilitiesQueryArgs,
+	AbilityInput,
+	AbilityOutput,
+} from './types';
+import { validateValueFromSchema } from './validation';
+
+/**
+ * Get all available abilities with optional filtering.
+ *
+ * @param args Optional query arguments to filter. Defaults to empty object.
+ * @return Promise resolving to array of abilities.
+ */
+export async function getAbilities(
+	args: AbilitiesQueryArgs = {}
+): Promise< Ability[] > {
+	return await resolveSelect( store ).getAbilities( args );
+}
+
+/**
+ * Get a specific ability by name.
+ *
+ * @param name The ability name.
+ * @return Promise resolving to the ability or null if not found.
+ */
+export async function getAbility( name: string ): Promise< Ability | null > {
+	return await resolveSelect( store ).getAbility( name );
+}
+
+/**
+ * Get all available ability categories.
+ *
+ * @return Promise resolving to array of categories.
+ */
+export async function getAbilityCategories(): Promise< AbilityCategory[] > {
+	return await resolveSelect( store ).getAbilityCategories();
+}
+
+/**
+ * Get a specific ability category by slug.
+ *
+ * @param slug The category slug.
+ * @return Promise resolving to the category or null if not found.
+ */
+export async function getAbilityCategory(
+	slug: string
+): Promise< AbilityCategory | null > {
+	return await resolveSelect( store ).getAbilityCategory( slug );
+}
+
+/**
+ * Register a client-side ability.
+ *
+ * Client abilities are executed locally in the browser and must include
+ * a callback function. The ability will be validated by the store action,
+ * and an error will be thrown if validation fails.
+ *
+ * Categories will be automatically fetched from the REST API if they
+ * haven't been loaded yet, so you don't need to call getAbilityCategories()
+ * before registering abilities.
+ *
+ * @param  ability The ability definition including callback.
+ * @return Promise that resolves when registration is complete.
+ * @throws {Error} If the ability fails validation.
+ *
+ * @example
+ * ```js
+ * await registerAbility({
+ *   name: 'my-plugin/navigate',
+ *   label: 'Navigate to URL',
+ *   description: 'Navigates to a URL within WordPress admin',
+ *   category: 'navigation',
+ *   input_schema: {
+ *     type: 'object',
+ *     properties: {
+ *       url: { type: 'string' }
+ *     },
+ *     required: ['url']
+ *   },
+ *   callback: async ({ url }) => {
+ *     window.location.href = url;
+ *     return { success: true };
+ *   }
+ * });
+ * ```
+ */
+export async function registerAbility( ability: Ability ): Promise< void > {
+	await dispatch( store ).registerAbility( ability );
+}
+
+/**
+ * Unregister an ability from the store.
+ *
+ * Remove a client-side ability from the store.
+ * Note: This will return an error for server-side abilities.
+ *
+ * @param name The ability name to unregister.
+ */
+export function unregisterAbility( name: string ): void {
+	dispatch( store ).unregisterAbility( name );
+}
+
+/**
+ * Register a client-side ability category.
+ *
+ * Categories registered on the client are stored alongside server-side categories
+ * in the same store and can be used when registering client side abilities.
+ * This is useful when registering client-side abilities that introduce new
+ * categories not defined by the server.
+ *
+ * Categories will be automatically fetched from the REST API if they haven't been
+ * loaded yet to check for duplicates against server-side categories.
+ *
+ * @param  slug Category slug (lowercase alphanumeric with dashes only).
+ * @param  args Category arguments (label, description, optional meta).
+ * @return Promise that resolves when registration is complete.
+ * @throws {Error} If the category fails validation.
+ *
+ * @example
+ * ```js
+ * // Register a new category for block editor abilities
+ * await registerAbilityCategory('block-editor', {
+ *   label: 'Block Editor',
+ *   description: 'Abilities for interacting with the WordPress block editor'
+ * });
+ *
+ * // Then register abilities using this category
+ * await registerAbility({
+ *   name: 'my-plugin/insert-block',
+ *   label: 'Insert Block',
+ *   description: 'Inserts a block into the editor',
+ *   category: 'block-editor',
+ *   callback: async ({ blockType }) => {
+ *     // Implementation
+ *     return { success: true };
+ *   }
+ * });
+ * ```
+ */
+export async function registerAbilityCategory(
+	slug: string,
+	args: AbilityCategoryArgs
+): Promise< void > {
+	await dispatch( store ).registerAbilityCategory( slug, args );
+}
+
+/**
+ * Unregister an ability category.
+ *
+ * Removes a category from the store.
+ *
+ * @param slug The category slug to unregister.
+ *
+ * @example
+ * ```js
+ * unregisterAbilityCategory('block-editor');
+ * ```
+ */
+export function unregisterAbilityCategory( slug: string ): void {
+	dispatch( store ).unregisterAbilityCategory( slug );
+}
+
+/**
+ * Execute a client-side ability.
+ *
+ * @param ability The ability to execute.
+ * @param input   Input parameters for the ability.
+ * @return Promise resolving to the ability execution result.
+ * @throws Error if validation fails or execution errors.
+ */
+async function executeClientAbility(
+	ability: Ability,
+	input: AbilityInput
+): Promise< AbilityOutput > {
+	if ( ! ability.callback ) {
+		throw new Error(
+			sprintf(
+				'Client ability %s is missing callback function',
+				ability.name
+			)
+		);
+	}
+
+	// Check permission callback if defined
+	if ( ability.permissionCallback ) {
+		const hasPermission = await ability.permissionCallback( input );
+		if ( ! hasPermission ) {
+			const error = new Error(
+				sprintf( 'Permission denied for ability: %s', ability.name )
+			);
+			( error as any ).code = 'ability_permission_denied';
+			throw error;
+		}
+	}
+
+	if ( ability.input_schema ) {
+		const inputValidation = validateValueFromSchema(
+			input,
+			ability.input_schema,
+			'input'
+		);
+		if ( inputValidation !== true ) {
+			const error = new Error(
+				sprintf(
+					'Ability "%1$s" has invalid input. Reason: %2$s',
+					ability.name,
+					inputValidation
+				)
+			);
+			( error as any ).code = 'ability_invalid_input';
+			throw error;
+		}
+	}
+
+	let result: AbilityOutput;
+	try {
+		result = await ability.callback( input );
+	} catch ( error ) {
+		// eslint-disable-next-line no-console
+		console.error(
+			`Error executing client ability ${ ability.name }:`,
+			error
+		);
+		throw error;
+	}
+
+	if ( ability.output_schema ) {
+		const outputValidation = validateValueFromSchema(
+			result,
+			ability.output_schema,
+			'output'
+		);
+		if ( outputValidation !== true ) {
+			const error = new Error(
+				sprintf(
+					'Ability "%1$s" has invalid output. Reason: %2$s',
+					ability.name,
+					outputValidation
+				)
+			);
+			( error as any ).code = 'ability_invalid_output';
+			throw error;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Execute a server-side ability.
+ *
+ * @param ability The ability to execute.
+ * @param input   Input parameters for the ability.
+ * @return Promise resolving to the ability execution result.
+ * @throws Error if the API call fails.
+ */
+async function executeServerAbility(
+	ability: Ability,
+	input: AbilityInput
+): Promise< AbilityOutput > {
+	let method = 'POST';
+	if ( !! ability.meta?.annotations?.readonly ) {
+		method = 'GET';
+	} else if (
+		!! ability.meta?.annotations?.destructive &&
+		!! ability.meta?.annotations?.idempotent
+	) {
+		method = 'DELETE';
+	}
+
+	let path = `/wp-abilities/v1/abilities/${ ability.name }/run`;
+	const options: {
+		method: string;
+		data?: { input: AbilityInput };
+	} = {
+		method,
+	};
+
+	if ( [ 'GET', 'DELETE' ].includes( method ) && input !== null ) {
+		// For GET and DELETE requests, pass the input directly.
+		path = addQueryArgs( path, { input } );
+	} else if ( method === 'POST' && input !== null ) {
+		options.data = { input };
+	}
+
+	// Note: Input and output validation happens on the server side for these abilities.
+	try {
+		return await apiFetch< AbilityOutput >( {
+			path,
+			...options,
+		} );
+	} catch ( error ) {
+		// eslint-disable-next-line no-console
+		console.error( `Error executing ability ${ ability.name }:`, error );
+		throw error;
+	}
+}
+
+/**
+ * Execute an ability.
+ *
+ * Determines whether to execute locally (client abilities) or remotely (server abilities)
+ * based on whether the ability has a callback function.
+ *
+ * @param name  The ability name.
+ * @param input Optional input parameters for the ability.
+ * @return Promise resolving to the ability execution result.
+ * @throws Error if the ability is not found or execution fails.
+ */
+export async function executeAbility(
+	name: string,
+	input?: AbilityInput
+): Promise< AbilityOutput > {
+	const ability = await getAbility( name );
+	if ( ! ability ) {
+		throw new Error( sprintf( 'Ability not found: %s', name ) );
+	}
+
+	if ( ability.callback ) {
+		return executeClientAbility( ability, input );
+	}
+
+	return executeServerAbility( ability, input );
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * WordPress Abilities API Client
+ *
+ * This package provides a client for interacting with the
+ * WordPress Abilities API, allowing you to list, retrieve, and execute
+ * abilities from client-side code.
+ *
+ * @package
+ */
+
+/**
+ * Public API functions
+ */
+export {
+	getAbilities,
+	getAbility,
+	getAbilityCategories,
+	getAbilityCategory,
+	executeAbility,
+	registerAbility,
+	unregisterAbility,
+	registerAbilityCategory,
+	unregisterAbilityCategory,
+} from './api';
+
+/**
+ * The store can be used directly with @wordpress/data via selectors
+ * in React components with useSelect.
+ *
+ * @example
+ * ```js
+ * import { useSelect } from '@wordpress/data';
+ * import { store as abilitiesStore } from '@wordpress/abilities';
+ *
+ * function MyComponent() {
+ *   const abilities = useSelect(
+ *     (select) => select(abilitiesStore).getAbilities(),
+ *     []
+ *   );
+ *   // Use abilities...
+ * }
+ * ```
+ */
+export { store } from './store';
+
+/**
+ * Type definitions
+ */
+export type {
+	Ability,
+	AbilityCategory,
+	AbilityCategoryArgs,
+	AbilitiesState,
+	AbilitiesQueryArgs,
+	AbilityCallback,
+	PermissionCallback,
+	AbilityInput,
+	AbilityOutput,
+	ValidationError,
+} from './types';
+
+/**
+ * Validation utilities
+ */
+export { validateValueFromSchema } from './validation';

package/src/store/actions.ts

@@ -0,0 +1,247 @@
+/**
+ * WordPress dependencies
+ */
+import { sprintf } from '@wordpress/i18n';
+import { resolveSelect } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import type { Ability, AbilityCategory, AbilityCategoryArgs } from '../types';
+import {
+	RECEIVE_ABILITIES,
+	REGISTER_ABILITY,
+	UNREGISTER_ABILITY,
+	RECEIVE_CATEGORIES,
+	REGISTER_ABILITY_CATEGORY,
+	UNREGISTER_ABILITY_CATEGORY,
+	STORE_NAME,
+} from './constants';
+
+/**
+ * Returns an action object used to receive abilities into the store.
+ *
+ * @param abilities Array of abilities to store.
+ * @return Action object.
+ */
+export function receiveAbilities( abilities: Ability[] ) {
+	return {
+		type: RECEIVE_ABILITIES,
+		abilities,
+	};
+}
+
+/**
+ * Returns an action object used to receive categories into the store.
+ *
+ * @param categories Array of categories to store.
+ * @return Action object.
+ */
+export function receiveCategories( categories: AbilityCategory[] ) {
+	return {
+		type: RECEIVE_CATEGORIES,
+		categories,
+	};
+}
+
+/**
+ * Registers an ability in the store.
+ *
+ * This action validates the ability before registration. If validation fails,
+ * an error will be thrown. Categories will be automatically fetched from the
+ * REST API if they haven't been loaded yet.
+ *
+ * @param  ability The ability to register.
+ * @return Action object or function.
+ * @throws {Error} If validation fails.
+ */
+export function registerAbility( ability: Ability ) {
+	// @ts-expect-error - registry types are not yet available
+	return async ( { select, dispatch } ) => {
+		if ( ! ability.name ) {
+			throw new Error( 'Ability name is required' );
+		}
+
+		// Validate name format matches server implementation
+		if ( ! /^[a-z0-9-]+\/[a-z0-9-]+$/.test( ability.name ) ) {
+			throw new Error(
+				'Ability name must be a string containing a namespace prefix, i.e. "my-plugin/my-ability". It can only contain lowercase alphanumeric characters, dashes and the forward slash.'
+			);
+		}
+
+		if ( ! ability.label ) {
+			throw new Error(
+				sprintf( 'Ability "%s" must have a label', ability.name )
+			);
+		}
+
+		if ( ! ability.description ) {
+			throw new Error(
+				sprintf( 'Ability "%s" must have a description', ability.name )
+			);
+		}
+
+		if ( ! ability.category ) {
+			throw new Error(
+				sprintf( 'Ability "%s" must have a category', ability.name )
+			);
+		}
+
+		// Validate category format
+		if ( ! /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test( ability.category ) ) {
+			throw new Error(
+				sprintf(
+					'Ability "%1$s" has an invalid category. Category must be lowercase alphanumeric with dashes only Got: "%2$s"',
+					ability.name,
+					ability.category
+				)
+			);
+		}
+
+		// Ensure categories are loaded before validating
+		const categories =
+			await resolveSelect( STORE_NAME ).getAbilityCategories();
+		const existingCategory = categories.find(
+			( cat: AbilityCategory ) => cat.slug === ability.category
+		);
+		if ( ! existingCategory ) {
+			throw new Error(
+				sprintf(
+					'Ability "%1$s" references non-existent category "%2$s". Please register the category first.',
+					ability.name,
+					ability.category
+				)
+			);
+		}
+
+		// Client-side abilities must have a callback
+		if ( ability.callback && typeof ability.callback !== 'function' ) {
+			throw new Error(
+				sprintf(
+					'Ability "%s" has an invalid callback. Callback must be a function',
+					ability.name
+				)
+			);
+		}
+
+		// Check if ability is already registered
+		const existingAbility = select.getAbility( ability.name );
+		if ( existingAbility ) {
+			throw new Error(
+				sprintf( 'Ability "%s" is already registered', ability.name )
+			);
+		}
+
+		// All validation passed, dispatch the registration action
+		dispatch( {
+			type: REGISTER_ABILITY,
+			ability,
+		} );
+	};
+}
+
+/**
+ * Returns an action object used to unregister a client-side ability.
+ *
+ * @param name The name of the ability to unregister.
+ * @return Action object.
+ */
+export function unregisterAbility( name: string ) {
+	return {
+		type: UNREGISTER_ABILITY,
+		name,
+	};
+}
+
+/**
+ * Registers a client-side ability category in the store.
+ *
+ * This action validates the category before registration. If validation fails,
+ * an error will be thrown. Categories will be automatically fetched from the
+ * REST API if they haven't been loaded yet to check for duplicates.
+ *
+ * @param  slug The unique category slug identifier.
+ * @param  args Category arguments (label, description, optional meta).
+ * @return Action object or function.
+ * @throws {Error} If validation fails.
+ */
+export function registerAbilityCategory(
+	slug: string,
+	args: AbilityCategoryArgs
+) {
+	// @ts-expect-error - registry types are not yet available
+	return async ( { select, dispatch } ) => {
+		if ( ! slug ) {
+			throw new Error( 'Category slug is required' );
+		}
+
+		// Validate slug format matches server implementation
+		if ( ! /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test( slug ) ) {
+			throw new Error(
+				'Category slug must contain only lowercase alphanumeric characters and dashes.'
+			);
+		}
+
+		// Ensure categories are loaded before checking for duplicates
+		await resolveSelect( STORE_NAME ).getAbilityCategories();
+		const existingCategory = select.getAbilityCategory( slug );
+		if ( existingCategory ) {
+			throw new Error(
+				sprintf( 'Category "%s" is already registered.', slug )
+			);
+		}
+
+		// Validate label presence and type (matches PHP empty() + is_string())
+		if ( ! args.label || typeof args.label !== 'string' ) {
+			throw new Error(
+				'The category properties must contain a `label` string.'
+			);
+		}
+
+		// Validate description presence and type (matches PHP empty() + is_string())
+		if ( ! args.description || typeof args.description !== 'string' ) {
+			throw new Error(
+				'The category properties must contain a `description` string.'
+			);
+		}
+
+		if (
+			args.meta !== undefined &&
+			( typeof args.meta !== 'object' || Array.isArray( args.meta ) )
+		) {
+			throw new Error(
+				'The category properties should provide a valid `meta` object.'
+			);
+		}
+
+		const category: AbilityCategory = {
+			slug,
+			label: args.label,
+			description: args.description,
+			meta: {
+				...( args.meta || {} ),
+				// Internal implementation note: Client-registered categories will have `meta._clientRegistered` set to `true` to differentiate them from server-fetched categories.
+				// This is used internally by the resolver to determine whether to fetch categories from the server.
+				_clientRegistered: true,
+			},
+		};
+
+		dispatch( {
+			type: REGISTER_ABILITY_CATEGORY,
+			category,
+		} );
+	};
+}
+
+/**
+ * Returns an action object used to unregister a client-side ability category.
+ *
+ * @param slug The slug of the category to unregister.
+ * @return Action object.
+ */
+export function unregisterAbilityCategory( slug: string ) {
+	return {
+		type: UNREGISTER_ABILITY_CATEGORY,
+		slug,
+	};
+}

package/src/store/constants.ts

@@ -0,0 +1,15 @@
+/**
+ * Store constants
+ */
+export const STORE_NAME = 'core/abilities';
+export const ENTITY_KIND = 'root';
+export const ENTITY_NAME = 'abilities';
+export const ENTITY_NAME_CATEGORIES = 'ability-categories';
+
+// Action types
+export const RECEIVE_ABILITIES = 'RECEIVE_ABILITIES';
+export const REGISTER_ABILITY = 'REGISTER_ABILITY';
+export const UNREGISTER_ABILITY = 'UNREGISTER_ABILITY';
+export const RECEIVE_CATEGORIES = 'RECEIVE_CATEGORIES';
+export const REGISTER_ABILITY_CATEGORY = 'REGISTER_ABILITY_CATEGORY';
+export const UNREGISTER_ABILITY_CATEGORY = 'UNREGISTER_ABILITY_CATEGORY';