From af1ad61cf3e71d2bbcf51ace9e66195ccde08b6c Mon Sep 17 00:00:00 2001
From: Jonathan Bossenger <jonathanbossenger@gmail.com>
Date: Fri, 26 Sep 2025 13:05:09 +0200
Subject: [PATCH 1/5] AI generated docs

---
 README.md                   |   1 +
 docs/7.javascript-client.md | 503 ++++++++++++++++++++++++++++++++++++
 packages/client/README.md   | 127 ---------
 3 files changed, 504 insertions(+), 127 deletions(-)
 create mode 100644 docs/7.javascript-client.md
 delete mode 100644 packages/client/README.md

diff --git a/README.md b/README.md
index e257e7e..4762b71 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,7 @@
 - [Using Abilities](docs/4.using-abilities.md)
 - [REST API Reference](docs/5.rest-api.md)
 - [Hooks](docs/6.hooks.md)
+- [JavaScript/TypeScript Client](docs/7.javascript-client.md)
 - [Contributing Guidelines](CONTRIBUTING.md)
 
 ## Inspiration
diff --git a/docs/7.javascript-client.md b/docs/7.javascript-client.md
new file mode 100644
index 0000000..7b68b95
--- /dev/null
+++ b/docs/7.javascript-client.md
@@ -0,0 +1,503 @@
+# 7. JavaScript/TypeScript Client
+
+The WordPress Abilities API includes a comprehensive JavaScript client that enables frontend applications, block editor plugins, and external systems to discover and execute abilities both on the server and within the browser.
+
+## Overview
+
+While the previous documentation covered registering and using abilities in PHP, this client extends that functionality to JavaScript environments. It provides:
+
+- **Server-side ability execution** via WordPress REST API
+- **Client-side ability registration** for browser-based capabilities
+- **Automatic discovery** of all registered abilities
+- **Input/output validation** using JSON Schema
+- **WordPress data store integration** for reactive UI development
+- **TypeScript support** with full type definitions
+
+## Installation
+
+### As an NPM Package
+
+For modern JavaScript development workflows:
+
+```bash
+npm install @wordpress/abilities
+```
+
+Then import the functions you need:
+
+```javascript
+import { getAbilities, getAbility, executeAbility, registerAbility } from '@wordpress/abilities';
+```
+
+### WordPress Global (Plugin Users)
+
+When the Abilities API plugin is active, the client is automatically available as a WordPress script:
+
+```javascript
+// Available globally when the plugin is loaded
+const { getAbilities, getAbility, executeAbility } = wp.abilities;
+```
+
+This approach is ideal for WordPress admin pages, block editor plugins, or theme scripts where you don't have a build process.
+
+## Basic Usage Patterns
+
+### Executing Server-Side Abilities
+
+Server-side abilities that you registered in PHP (as shown in [Registering Abilities](3.registering-abilities.md)) can be executed from JavaScript:
+
+```javascript
+// Execute the site info ability we registered in earlier examples
+const siteInfo = await executeAbility('my-plugin/get-site-info');
+console.log('Site Name:', siteInfo.name);
+
+// Execute an ability with input parameters
+const result = await executeAbility('my-plugin/update-option', {
+    option_name: 'blogname',
+    option_value: 'My New Site Title'
+});
+
+if (result.success) {
+    console.log('Option updated successfully');
+}
+```
+
+### Discovering Available Abilities
+
+Get all registered abilities (both server-side and client-side):
+
+```javascript
+// Get all abilities
+const abilities = await getAbilities();
+console.log(`Found ${abilities.length} abilities`);
+
+// Filter by type (tools vs resources)
+const tools = abilities.filter(ability => ability.meta?.type === 'tool');
+const resources = abilities.filter(ability => ability.meta?.type === 'resource');
+
+// List abilities by namespace
+abilities.forEach(ability => {
+    console.log(`${ability.name}: ${ability.description}`);
+});
+```
+
+### Getting a Specific Ability
+
+```javascript
+const ability = await getAbility('my-plugin/get-site-info');
+if (ability) {
+    console.log('Label:', ability.label);
+    console.log('Description:', ability.description);
+    console.log('Input Schema:', ability.input_schema);
+
+    // Check if it's client-side or server-side
+    if (ability.callback) {
+        console.log('This is a client-side ability');
+    } else {
+        console.log('This is a server-side ability');
+    }
+}
+```
+
+## Client-Side Abilities
+
+One of the key features of the JavaScript client is the ability to register capabilities that run entirely in the browser. This is useful for UI interactions, data formatting, and browser-specific functionality.
+
+### Registering Client-Side Abilities
+
+```javascript
+// Register a simple notification ability
+registerAbility({
+    name: 'my-plugin/show-notification',
+    label: 'Show Notification',
+    description: 'Display a notification message to the user',
+    input_schema: {
+        type: 'object',
+        properties: {
+            message: { type: 'string' },
+            type: { type: 'string', enum: ['success', 'error', 'warning', 'info'] }
+        },
+        required: ['message']
+    },
+    callback: async ({ message, type = 'info' }) => {
+        // Use WordPress notices API
+        wp.data.dispatch('core/notices').createNotice(type, message);
+        return { success: true, displayed: message };
+    },
+    permissionCallback: () => {
+        // Allow any logged-in user
+        return !!wp.data.select('core').getCurrentUser();
+    }
+});
+```
+
+### Complex Client-Side Example
+
+Here's a more comprehensive example that demonstrates validation and error handling:
+
+```javascript
+registerAbility({
+    name: 'my-plugin/format-post-data',
+    label: 'Format Post Data',
+    description: 'Format and validate post data for display',
+    input_schema: {
+        type: 'object',
+        properties: {
+            title: { type: 'string', minLength: 1, maxLength: 100 },
+            content: { type: 'string', minLength: 10 },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                maxItems: 10
+            },
+            publishDate: { type: 'string', format: 'date-time' }
+        },
+        required: ['title', 'content']
+    },
+    output_schema: {
+        type: 'object',
+        properties: {
+            formattedTitle: { type: 'string' },
+            wordCount: { type: 'number' },
+            excerpt: { type: 'string' },
+            tagList: { type: 'string' }
+        }
+    },
+    callback: async ({ title, content, tags = [], publishDate }) => {
+        // Format title
+        const formattedTitle = title.trim().replace(/\s+/g, ' ');
+
+        // Calculate word count
+        const wordCount = content.split(/\s+/).length;
+
+        // Generate excerpt
+        const excerpt = content.substring(0, 150) + (content.length > 150 ? '...' : '');
+
+        // Format tags
+        const tagList = tags.length > 0 ? tags.join(', ') : 'No tags';
+
+        return {
+            formattedTitle,
+            wordCount,
+            excerpt,
+            tagList
+        };
+    },
+    permissionCallback: (input) => {
+        // Only allow users who can edit posts
+        return wp.data.select('core').getCurrentUser()?.capabilities?.edit_posts;
+    }
+});
+
+// Use the ability
+const formatted = await executeAbility('my-plugin/format-post-data', {
+    title: '  My  Blog  Post  Title  ',
+    content: 'This is the content of my blog post. It contains multiple sentences and should be long enough to generate a proper excerpt when processed by the formatting ability.',
+    tags: ['WordPress', 'JavaScript', 'Abilities API']
+});
+
+console.log('Formatted:', formatted.formattedTitle);
+console.log('Word count:', formatted.wordCount);
+```
+
+## Error Handling
+
+The client provides structured error handling with specific error codes:
+
+```javascript
+try {
+    const result = await executeAbility('my-plugin/risky-operation', input);
+    // Success - use result
+} catch (error) {
+    switch (error.code) {
+        case 'ability_permission_denied':
+            console.error('You do not have permission:', error.message);
+            break;
+        case 'ability_invalid_input':
+            console.error('Invalid input data:', error.message);
+            break;
+        case 'ability_invalid_output':
+            console.error('Ability returned invalid output:', error.message);
+            break;
+        case 'rest_ability_not_found':
+            console.error('Ability not found:', error.message);
+            break;
+        default:
+            console.error('Execution failed:', error.message);
+    }
+}
+```
+
+## WordPress Data Store Integration
+
+The client integrates with the WordPress data package for reactive state management in React applications:
+
+### Using Selectors in React Components
+
+```javascript
+import { useSelect } from '@wordpress/data';
+import { store as abilitiesStore } from '@wordpress/abilities';
+
+function AbilitiesList() {
+    const abilities = useSelect(
+        select => select(abilitiesStore).getAbilities(),
+        []
+    );
+
+    return (
+        <div>
+            <h3>Available Abilities ({abilities.length})</h3>
+            <ul>
+                {abilities.map(ability => (
+                    <li key={ability.name}>
+                        <strong>{ability.label}</strong>: {ability.description}
+                        {ability.callback && <span> (Client-side)</span>}
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+}
+```
+
+### Custom React Hook for Ability Execution
+
+```javascript
+import { useState, useCallback } from 'react';
+import { executeAbility } from '@wordpress/abilities';
+
+function useAbility(abilityName) {
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [result, setResult] = useState(null);
+
+    const execute = useCallback(async (input) => {
+        setLoading(true);
+        setError(null);
+
+        try {
+            const output = await executeAbility(abilityName, input);
+            setResult(output);
+            return output;
+        } catch (err) {
+            setError(err.message);
+            throw err;
+        } finally {
+            setLoading(false);
+        }
+    }, [abilityName]);
+
+    return { execute, loading, error, result };
+}
+
+// Usage in a component
+function ContentGenerator() {
+    const { execute, loading, error } = useAbility('ai-plugin/generate-content');
+    const [prompt, setPrompt] = useState('');
+
+    const handleGenerate = async () => {
+        try {
+            const content = await execute({ prompt, maxLength: 500 });
+            console.log('Generated:', content);
+        } catch (error) {
+            console.error('Generation failed:', error);
+        }
+    };
+
+    return (
+        <div>
+            <textarea
+                value={prompt}
+                onChange={(e) => setPrompt(e.target.value)}
+                placeholder="Enter your content prompt..."
+            />
+            <button onClick={handleGenerate} disabled={loading}>
+                {loading ? 'Generating...' : 'Generate Content'}
+            </button>
+            {error && <div className="error">Error: {error}</div>}
+        </div>
+    );
+}
+```
+
+## Server vs Client Execution
+
+The client automatically determines whether to execute an ability locally or remotely:
+
+### Resource Abilities (GET Requests)
+
+For abilities with `meta.type: 'resource'`, input is sent as query parameters:
+
+```javascript
+// This becomes: GET /wp/v2/abilities/blog-plugin/get-posts/run?category=tech&limit=10
+const posts = await executeAbility('blog-plugin/get-posts', {
+    category: 'tech',
+    limit: 10,
+    orderby: 'date'
+});
+```
+
+### Tool Abilities (POST Requests)
+
+For abilities with `meta.type: 'tool'` (the default), input is sent in the request body:
+
+```javascript
+// This becomes: POST /wp/v2/abilities/ai-plugin/generate-content/run
+const content = await executeAbility('ai-plugin/generate-content', {
+    prompt: 'Write about WordPress development',
+    maxTokens: 300
+});
+```
+
+### Client-Side Execution
+
+For client-side abilities (those with a `callback` function), execution happens entirely in the browser:
+
+```javascript
+// Executes locally, no HTTP request
+const formatted = await executeAbility('my-plugin/format-currency', {
+    amount: 99.99,
+    currency: 'USD'
+});
+```
+
+## Integration with Block Editor
+
+The JavaScript client works seamlessly with WordPress block editor development:
+
+```javascript
+import { registerBlockType } from '@wordpress/blocks';
+import { useSelect } from '@wordpress/data';
+import { store as abilitiesStore } from '@wordpress/abilities';
+
+registerBlockType('my-plugin/abilities-block', {
+    title: 'Abilities Integration',
+    category: 'widgets',
+
+    edit: function Edit() {
+        const abilities = useSelect(
+            select => select(abilitiesStore).getAbilities(),
+            []
+        );
+
+        // Filter to show only abilities from your plugin
+        const myAbilities = abilities.filter(ability =>
+            ability.name.startsWith('my-plugin/')
+        );
+
+        return (
+            <div>
+                <h4>Available Abilities</h4>
+                {myAbilities.map(ability => (
+                    <button
+                        key={ability.name}
+                        onClick={() => executeAbility(ability.name)}
+                    >
+                        {ability.label}
+                    </button>
+                ))}
+            </div>
+        );
+    },
+
+    save: () => null // Dynamic block
+});
+```
+
+## Best Practices
+
+### Namespace Your Client Abilities
+
+Always use your plugin's namespace for client-side abilities:
+
+```javascript
+// Good
+registerAbility({
+    name: 'my-plugin/client-function',
+    // ...
+});
+
+// Bad - conflicts possible
+registerAbility({
+    name: 'show-modal',
+    // ...
+});
+```
+
+### Validate Permissions Properly
+
+For client-side abilities, always implement appropriate permission checking:
+
+```javascript
+registerAbility({
+    name: 'my-plugin/admin-function',
+    // ...
+    permissionCallback: (input) => {
+        // Check specific capability
+        return wp.data.select('core').getCurrentUser()?.capabilities?.manage_options;
+    }
+});
+```
+
+### Handle Async Operations
+
+Use async/await patterns for cleaner error handling:
+
+```javascript
+// Good
+try {
+    const result = await executeAbility('my-plugin/async-operation', input);
+    // Handle success
+} catch (error) {
+    // Handle error
+}
+
+// Avoid callback hell
+executeAbility('my-plugin/operation').then().catch();
+```
+
+## TypeScript Support
+
+The client includes full TypeScript definitions. You can import types for better development experience:
+
+```typescript
+import {
+    Ability,
+    AbilityCallback,
+    PermissionCallback
+} from '@wordpress/abilities';
+
+const myCallback: AbilityCallback = async (input: any) => {
+    // Type-safe callback implementation
+    return { success: true };
+};
+
+const myPermissionCallback: PermissionCallback = (input?: any): boolean => {
+    return wp.data.select('core').getCurrentUser()?.capabilities?.edit_posts ?? false;
+};
+```
+
+## Validation
+
+The client uses JSON Schema validation (AJV with Draft-04) to ensure data integrity. This matches the validation used by WordPress REST API, ensuring consistency between client and server validation.
+
+### Supported Schema Features
+
+- All basic types: `string`, `number`, `integer`, `boolean`, `array`, `object`, `null`
+- String constraints: `minLength`, `maxLength`, `pattern`, `format` (email, date-time, etc.)
+- Number constraints: `minimum`, `maximum`, `multipleOf`
+- Array constraints: `minItems`, `maxItems`, `uniqueItems`
+- Object constraints: `required`, `additionalProperties`, `properties`
+
+See the [REST API documentation](5.rest-api.md) for more details on the server-side validation and execution endpoints that the client interacts with.
+
+## Next Steps
+
+Now that you understand how to use the JavaScript client, you can:
+
+- Integrate abilities into your block editor plugins
+- Create reactive admin interfaces using the WordPress data store
+- Build client-side capabilities that complement your server-side abilities
+- Develop external applications that interact with your WordPress site's capabilities
+
+The JavaScript client bridges the gap between your PHP abilities and modern frontend development, enabling rich interactive experiences while maintaining the security and validation standards of the WordPress Abilities API.
\ No newline at end of file
diff --git a/packages/client/README.md b/packages/client/README.md
deleted file mode 100644
index 90d1f5d..0000000
--- a/packages/client/README.md
+++ /dev/null
@@ -1,127 +0,0 @@
-# WordPress Abilities API Client
-
-Client library for the WordPress Abilities API, providing a standardized way to discover and execute WordPress capabilities.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Usage](#usage)
-- [API Reference](#api-reference)
-- [Development and Testing](#development-and-testing)
-
-## Installation
-
-The client is currently available as a part of the Composer package.
-
-### As a WordPress Script
-
-When the Abilities API is installed, the client is automatically registered and enqueue in the admin.
-
-## Usage
-
-```javascript
-// In your WordPress plugin or theme JavaScript
-const { getAbilities, getAbility, executeAbility } = wp.abilities;
-// or import { getAbilities, getAbility, executeAbility } from '@wordpress/abilities'; depending on your setup
-
-// Get all abilities
-const abilities = await getAbilities();
-
-// Get a specific ability
-const ability = await getAbility('my-plugin/my-ability');
-
-// Execute an ability
-const result = await executeAbility('my-plugin/my-ability', {
-  param1: 'value1',
-  param2: 'value2',
-});
-```
-
-### Using with React and WordPress Data
-
-The client includes a data store that integrates with `@wordpress/data` for use in React components:
-
-```javascript
-import { useSelect } from '@wordpress/data';
-import { store as abilitiesStore } from '@wordpress/abilities';
-
-function MyComponent() {
-  const abilities = useSelect(
-    (select) => select(abilitiesStore).getAbilities(),
-    []
-  );
-
-  const specificAbility = useSelect(
-    (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}
-          </li>
-        ))}
-      </ul>
-    </div>
-  );
-}
-```
-
-## API Reference
-
-### Functions
-
-#### `getAbilities(): Promise<Ability[]>`
-
-Returns all registered abilities. Automatically handles pagination to fetch all abilities across multiple pages if needed.
-
-```javascript
-const abilities = await getAbilities();
-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}`);
-}
-```
-
-#### `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:
-
-- `resource` type abilities use GET (read-only operations)
-- `tool` type abilities use POST (write operations)
-
-```javascript
-// Execute a resource 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', {
-  title: 'New Item',
-  content: 'Item content',
-});
-```
-
-### Store Selectors
-
-When using with `@wordpress/data`:
-
-- `getAbilities()` - Returns all abilities from the store
-- `getAbility(name)` - Returns a specific ability from the store
-
-## Development and Testing
-
-For development and contributing guidelines, see [CONTRIBUTING.md](../../CONTRIBUTING.md).

From 775312a8f605239d3507e735238180c4f9ae6ecb Mon Sep 17 00:00:00 2001
From: Jonathan Bossenger <jonathanbossenger@gmail.com>
Date: Fri, 26 Sep 2025 13:12:05 +0200
Subject: [PATCH 2/5] Re-adding the package readme which was incorrectly
 deleted

---
 packages/client/README.md | 127 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 packages/client/README.md

diff --git a/packages/client/README.md b/packages/client/README.md
new file mode 100644
index 0000000..90d1f5d
--- /dev/null
+++ b/packages/client/README.md
@@ -0,0 +1,127 @@
+# WordPress Abilities API Client
+
+Client library for the WordPress Abilities API, providing a standardized way to discover and execute WordPress capabilities.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+- [Development and Testing](#development-and-testing)
+
+## Installation
+
+The client is currently available as a part of the Composer package.
+
+### As a WordPress Script
+
+When the Abilities API is installed, the client is automatically registered and enqueue in the admin.
+
+## Usage
+
+```javascript
+// In your WordPress plugin or theme JavaScript
+const { getAbilities, getAbility, executeAbility } = wp.abilities;
+// or import { getAbilities, getAbility, executeAbility } from '@wordpress/abilities'; depending on your setup
+
+// Get all abilities
+const abilities = await getAbilities();
+
+// Get a specific ability
+const ability = await getAbility('my-plugin/my-ability');
+
+// Execute an ability
+const result = await executeAbility('my-plugin/my-ability', {
+  param1: 'value1',
+  param2: 'value2',
+});
+```
+
+### Using with React and WordPress Data
+
+The client includes a data store that integrates with `@wordpress/data` for use in React components:
+
+```javascript
+import { useSelect } from '@wordpress/data';
+import { store as abilitiesStore } from '@wordpress/abilities';
+
+function MyComponent() {
+  const abilities = useSelect(
+    (select) => select(abilitiesStore).getAbilities(),
+    []
+  );
+
+  const specificAbility = useSelect(
+    (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}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Functions
+
+#### `getAbilities(): Promise<Ability[]>`
+
+Returns all registered abilities. Automatically handles pagination to fetch all abilities across multiple pages if needed.
+
+```javascript
+const abilities = await getAbilities();
+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}`);
+}
+```
+
+#### `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:
+
+- `resource` type abilities use GET (read-only operations)
+- `tool` type abilities use POST (write operations)
+
+```javascript
+// Execute a resource 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', {
+  title: 'New Item',
+  content: 'Item content',
+});
+```
+
+### Store Selectors
+
+When using with `@wordpress/data`:
+
+- `getAbilities()` - Returns all abilities from the store
+- `getAbility(name)` - Returns a specific ability from the store
+
+## Development and Testing
+
+For development and contributing guidelines, see [CONTRIBUTING.md](../../CONTRIBUTING.md).

From f45c9d1de279e321cf00e5c698e66caa96001d14 Mon Sep 17 00:00:00 2001
From: Jonathan Bossenger <jonathanbossenger@gmail.com>
Date: Fri, 26 Sep 2025 13:19:57 +0200
Subject: [PATCH 3/5] Focus on core API and examples

---
 docs/7.javascript-client.md | 509 +++++++-----------------------------
 1 file changed, 94 insertions(+), 415 deletions(-)

diff --git a/docs/7.javascript-client.md b/docs/7.javascript-client.md
index 7b68b95..897a1f7 100644
--- a/docs/7.javascript-client.md
+++ b/docs/7.javascript-client.md
@@ -1,109 +1,104 @@
 # 7. JavaScript/TypeScript Client
 
-The WordPress Abilities API includes a comprehensive JavaScript client that enables frontend applications, block editor plugins, and external systems to discover and execute abilities both on the server and within the browser.
+The JavaScript client provides a simple interface for discovering and executing WordPress Abilities from frontend applications, block editor plugins, and external systems.
 
 ## Overview
 
-While the previous documentation covered registering and using abilities in PHP, this client extends that functionality to JavaScript environments. It provides:
+The JavaScript client enables frontend code to interact with the PHP Abilities API system. It can:
 
-- **Server-side ability execution** via WordPress REST API
-- **Client-side ability registration** for browser-based capabilities
-- **Automatic discovery** of all registered abilities
-- **Input/output validation** using JSON Schema
-- **WordPress data store integration** for reactive UI development
-- **TypeScript support** with full type definitions
+- Discover all registered abilities on your WordPress site
+- Execute server-side PHP abilities via REST API calls
+- Register and execute client-side JavaScript abilities
+- Handle input validation and permission checking
 
-## Installation
+## Core API Functions
 
-### As an NPM Package
+### getAbilities()
 
-For modern JavaScript development workflows:
+Returns an array of all registered abilities (both server-side and client-side).
 
-```bash
-npm install @wordpress/abilities
-```
+**Parameters:** None
 
-Then import the functions you need:
+**Returns:** `Promise<Array>` - Array of ability objects
 
-```javascript
-import { getAbilities, getAbility, executeAbility, registerAbility } from '@wordpress/abilities';
-```
+**Example:**
 
-### WordPress Global (Plugin Users)
+```javascript
+const abilities = await getAbilities();
+console.log(`Found ${abilities.length} abilities`);
 
-When the Abilities API plugin is active, the client is automatically available as a WordPress script:
+// List all abilities
+abilities.forEach(ability => {
+    console.log(`${ability.name}: ${ability.description}`);
+});
 
-```javascript
-// Available globally when the plugin is loaded
-const { getAbilities, getAbility, executeAbility } = wp.abilities;
+// Filter by type
+const tools = abilities.filter(ability => ability.meta?.type === 'tool');
+const resources = abilities.filter(ability => ability.meta?.type === 'resource');
 ```
 
-This approach is ideal for WordPress admin pages, block editor plugins, or theme scripts where you don't have a build process.
+### getAbility(name)
 
-## Basic Usage Patterns
+Retrieves a specific ability by name.
 
-### Executing Server-Side Abilities
+**Parameters:**
+- `name` (string) - The ability name (e.g., 'my-plugin/get-posts')
 
-Server-side abilities that you registered in PHP (as shown in [Registering Abilities](3.registering-abilities.md)) can be executed from JavaScript:
+**Returns:** `Promise<Object|null>` - The ability object or null if not found
 
-```javascript
-// Execute the site info ability we registered in earlier examples
-const siteInfo = await executeAbility('my-plugin/get-site-info');
-console.log('Site Name:', siteInfo.name);
-
-// Execute an ability with input parameters
-const result = await executeAbility('my-plugin/update-option', {
-    option_name: 'blogname',
-    option_value: 'My New Site Title'
-});
+**Example:**
 
-if (result.success) {
-    console.log('Option updated successfully');
+```javascript
+const ability = await getAbility('my-plugin/get-site-info');
+if (ability) {
+    console.log('Label:', ability.label);
+    console.log('Description:', ability.description);
+    console.log('Input Schema:', ability.input_schema);
 }
 ```
 
-### Discovering Available Abilities
+### executeAbility(name, input)
+
+Executes an ability with the provided input data.
 
-Get all registered abilities (both server-side and client-side):
+**Parameters:**
+- `name` (string) - The ability name
+- `input` (object, optional) - Input data for the ability
+
+**Returns:** `Promise<any>` - The ability's output
+
+**Example:**
 
 ```javascript
-// Get all abilities
-const abilities = await getAbilities();
-console.log(`Found ${abilities.length} abilities`);
+// Execute without input
+const siteTitle = await executeAbility('my-plugin/get-site-title');
+console.log('Site:', siteTitle);
 
-// Filter by type (tools vs resources)
-const tools = abilities.filter(ability => ability.meta?.type === 'tool');
-const resources = abilities.filter(ability => ability.meta?.type === 'resource');
+// Execute with input parameters
+const posts = await executeAbility('my-plugin/get-posts', {
+    category: 'news',
+    limit: 5
+});
+posts.forEach(post => console.log(post.title));
 
-// List abilities by namespace
-abilities.forEach(ability => {
-    console.log(`${ability.name}: ${ability.description}`);
+// Execute with complex input
+const result = await executeAbility('my-plugin/update-option', {
+    option_name: 'blogname',
+    option_value: 'My New Site Title'
 });
+console.log('Success:', result.success);
 ```
 
-### Getting a Specific Ability
+### registerAbility(ability)
 
-```javascript
-const ability = await getAbility('my-plugin/get-site-info');
-if (ability) {
-    console.log('Label:', ability.label);
-    console.log('Description:', ability.description);
-    console.log('Input Schema:', ability.input_schema);
-
-    // Check if it's client-side or server-side
-    if (ability.callback) {
-        console.log('This is a client-side ability');
-    } else {
-        console.log('This is a server-side ability');
-    }
-}
-```
+Registers a client-side ability that runs in the browser.
 
-## Client-Side Abilities
+**Parameters:**
+- `ability` (object) - The ability configuration object
 
-One of the key features of the JavaScript client is the ability to register capabilities that run entirely in the browser. This is useful for UI interactions, data formatting, and browser-specific functionality.
+**Returns:** `void`
 
-### Registering Client-Side Abilities
+**Example:**
 
 ```javascript
 // Register a simple notification ability
@@ -120,104 +115,62 @@ registerAbility({
         required: ['message']
     },
     callback: async ({ message, type = 'info' }) => {
-        // Use WordPress notices API
-        wp.data.dispatch('core/notices').createNotice(type, message);
+        // Show browser notification
+        if (Notification.permission === 'granted') {
+            new Notification(message);
+        }
         return { success: true, displayed: message };
     },
     permissionCallback: () => {
-        // Allow any logged-in user
         return !!wp.data.select('core').getCurrentUser();
     }
 });
+
+// Use the registered ability
+const result = await executeAbility('my-plugin/show-notification', {
+    message: 'Hello World!',
+    type: 'success'
+});
 ```
 
-### Complex Client-Side Example
+### unregisterAbility(name)
 
-Here's a more comprehensive example that demonstrates validation and error handling:
+Removes a previously registered client-side ability.
 
-```javascript
-registerAbility({
-    name: 'my-plugin/format-post-data',
-    label: 'Format Post Data',
-    description: 'Format and validate post data for display',
-    input_schema: {
-        type: 'object',
-        properties: {
-            title: { type: 'string', minLength: 1, maxLength: 100 },
-            content: { type: 'string', minLength: 10 },
-            tags: {
-                type: 'array',
-                items: { type: 'string' },
-                maxItems: 10
-            },
-            publishDate: { type: 'string', format: 'date-time' }
-        },
-        required: ['title', 'content']
-    },
-    output_schema: {
-        type: 'object',
-        properties: {
-            formattedTitle: { type: 'string' },
-            wordCount: { type: 'number' },
-            excerpt: { type: 'string' },
-            tagList: { type: 'string' }
-        }
-    },
-    callback: async ({ title, content, tags = [], publishDate }) => {
-        // Format title
-        const formattedTitle = title.trim().replace(/\s+/g, ' ');
-
-        // Calculate word count
-        const wordCount = content.split(/\s+/).length;
-
-        // Generate excerpt
-        const excerpt = content.substring(0, 150) + (content.length > 150 ? '...' : '');
+**Parameters:**
+- `name` (string) - The ability name to unregister
 
-        // Format tags
-        const tagList = tags.length > 0 ? tags.join(', ') : 'No tags';
+**Returns:** `boolean` - True if the ability was found and removed
 
-        return {
-            formattedTitle,
-            wordCount,
-            excerpt,
-            tagList
-        };
-    },
-    permissionCallback: (input) => {
-        // Only allow users who can edit posts
-        return wp.data.select('core').getCurrentUser()?.capabilities?.edit_posts;
-    }
-});
+**Example:**
 
-// Use the ability
-const formatted = await executeAbility('my-plugin/format-post-data', {
-    title: '  My  Blog  Post  Title  ',
-    content: 'This is the content of my blog post. It contains multiple sentences and should be long enough to generate a proper excerpt when processed by the formatting ability.',
-    tags: ['WordPress', 'JavaScript', 'Abilities API']
-});
+```javascript
+// Unregister an ability
+const wasRemoved = unregisterAbility('my-plugin/old-ability');
+if (wasRemoved) {
+    console.log('Ability successfully removed');
+}
 
-console.log('Formatted:', formatted.formattedTitle);
-console.log('Word count:', formatted.wordCount);
+// Check if ability is gone
+const ability = await getAbility('my-plugin/old-ability');
+console.log('Ability exists:', ability !== null);
 ```
 
 ## Error Handling
 
-The client provides structured error handling with specific error codes:
+All functions return promises that may reject with specific error codes:
 
 ```javascript
 try {
-    const result = await executeAbility('my-plugin/risky-operation', input);
-    // Success - use result
+    const result = await executeAbility('my-plugin/restricted-action', input);
+    console.log('Success:', result);
 } catch (error) {
     switch (error.code) {
         case 'ability_permission_denied':
-            console.error('You do not have permission:', error.message);
+            console.error('Permission denied:', error.message);
             break;
         case 'ability_invalid_input':
-            console.error('Invalid input data:', error.message);
-            break;
-        case 'ability_invalid_output':
-            console.error('Ability returned invalid output:', error.message);
+            console.error('Invalid input:', error.message);
             break;
         case 'rest_ability_not_found':
             console.error('Ability not found:', error.message);
@@ -227,277 +180,3 @@ try {
     }
 }
 ```
-
-## WordPress Data Store Integration
-
-The client integrates with the WordPress data package for reactive state management in React applications:
-
-### Using Selectors in React Components
-
-```javascript
-import { useSelect } from '@wordpress/data';
-import { store as abilitiesStore } from '@wordpress/abilities';
-
-function AbilitiesList() {
-    const abilities = useSelect(
-        select => select(abilitiesStore).getAbilities(),
-        []
-    );
-
-    return (
-        <div>
-            <h3>Available Abilities ({abilities.length})</h3>
-            <ul>
-                {abilities.map(ability => (
-                    <li key={ability.name}>
-                        <strong>{ability.label}</strong>: {ability.description}
-                        {ability.callback && <span> (Client-side)</span>}
-                    </li>
-                ))}
-            </ul>
-        </div>
-    );
-}
-```
-
-### Custom React Hook for Ability Execution
-
-```javascript
-import { useState, useCallback } from 'react';
-import { executeAbility } from '@wordpress/abilities';
-
-function useAbility(abilityName) {
-    const [loading, setLoading] = useState(false);
-    const [error, setError] = useState(null);
-    const [result, setResult] = useState(null);
-
-    const execute = useCallback(async (input) => {
-        setLoading(true);
-        setError(null);
-
-        try {
-            const output = await executeAbility(abilityName, input);
-            setResult(output);
-            return output;
-        } catch (err) {
-            setError(err.message);
-            throw err;
-        } finally {
-            setLoading(false);
-        }
-    }, [abilityName]);
-
-    return { execute, loading, error, result };
-}
-
-// Usage in a component
-function ContentGenerator() {
-    const { execute, loading, error } = useAbility('ai-plugin/generate-content');
-    const [prompt, setPrompt] = useState('');
-
-    const handleGenerate = async () => {
-        try {
-            const content = await execute({ prompt, maxLength: 500 });
-            console.log('Generated:', content);
-        } catch (error) {
-            console.error('Generation failed:', error);
-        }
-    };
-
-    return (
-        <div>
-            <textarea
-                value={prompt}
-                onChange={(e) => setPrompt(e.target.value)}
-                placeholder="Enter your content prompt..."
-            />
-            <button onClick={handleGenerate} disabled={loading}>
-                {loading ? 'Generating...' : 'Generate Content'}
-            </button>
-            {error && <div className="error">Error: {error}</div>}
-        </div>
-    );
-}
-```
-
-## Server vs Client Execution
-
-The client automatically determines whether to execute an ability locally or remotely:
-
-### Resource Abilities (GET Requests)
-
-For abilities with `meta.type: 'resource'`, input is sent as query parameters:
-
-```javascript
-// This becomes: GET /wp/v2/abilities/blog-plugin/get-posts/run?category=tech&limit=10
-const posts = await executeAbility('blog-plugin/get-posts', {
-    category: 'tech',
-    limit: 10,
-    orderby: 'date'
-});
-```
-
-### Tool Abilities (POST Requests)
-
-For abilities with `meta.type: 'tool'` (the default), input is sent in the request body:
-
-```javascript
-// This becomes: POST /wp/v2/abilities/ai-plugin/generate-content/run
-const content = await executeAbility('ai-plugin/generate-content', {
-    prompt: 'Write about WordPress development',
-    maxTokens: 300
-});
-```
-
-### Client-Side Execution
-
-For client-side abilities (those with a `callback` function), execution happens entirely in the browser:
-
-```javascript
-// Executes locally, no HTTP request
-const formatted = await executeAbility('my-plugin/format-currency', {
-    amount: 99.99,
-    currency: 'USD'
-});
-```
-
-## Integration with Block Editor
-
-The JavaScript client works seamlessly with WordPress block editor development:
-
-```javascript
-import { registerBlockType } from '@wordpress/blocks';
-import { useSelect } from '@wordpress/data';
-import { store as abilitiesStore } from '@wordpress/abilities';
-
-registerBlockType('my-plugin/abilities-block', {
-    title: 'Abilities Integration',
-    category: 'widgets',
-
-    edit: function Edit() {
-        const abilities = useSelect(
-            select => select(abilitiesStore).getAbilities(),
-            []
-        );
-
-        // Filter to show only abilities from your plugin
-        const myAbilities = abilities.filter(ability =>
-            ability.name.startsWith('my-plugin/')
-        );
-
-        return (
-            <div>
-                <h4>Available Abilities</h4>
-                {myAbilities.map(ability => (
-                    <button
-                        key={ability.name}
-                        onClick={() => executeAbility(ability.name)}
-                    >
-                        {ability.label}
-                    </button>
-                ))}
-            </div>
-        );
-    },
-
-    save: () => null // Dynamic block
-});
-```
-
-## Best Practices
-
-### Namespace Your Client Abilities
-
-Always use your plugin's namespace for client-side abilities:
-
-```javascript
-// Good
-registerAbility({
-    name: 'my-plugin/client-function',
-    // ...
-});
-
-// Bad - conflicts possible
-registerAbility({
-    name: 'show-modal',
-    // ...
-});
-```
-
-### Validate Permissions Properly
-
-For client-side abilities, always implement appropriate permission checking:
-
-```javascript
-registerAbility({
-    name: 'my-plugin/admin-function',
-    // ...
-    permissionCallback: (input) => {
-        // Check specific capability
-        return wp.data.select('core').getCurrentUser()?.capabilities?.manage_options;
-    }
-});
-```
-
-### Handle Async Operations
-
-Use async/await patterns for cleaner error handling:
-
-```javascript
-// Good
-try {
-    const result = await executeAbility('my-plugin/async-operation', input);
-    // Handle success
-} catch (error) {
-    // Handle error
-}
-
-// Avoid callback hell
-executeAbility('my-plugin/operation').then().catch();
-```
-
-## TypeScript Support
-
-The client includes full TypeScript definitions. You can import types for better development experience:
-
-```typescript
-import {
-    Ability,
-    AbilityCallback,
-    PermissionCallback
-} from '@wordpress/abilities';
-
-const myCallback: AbilityCallback = async (input: any) => {
-    // Type-safe callback implementation
-    return { success: true };
-};
-
-const myPermissionCallback: PermissionCallback = (input?: any): boolean => {
-    return wp.data.select('core').getCurrentUser()?.capabilities?.edit_posts ?? false;
-};
-```
-
-## Validation
-
-The client uses JSON Schema validation (AJV with Draft-04) to ensure data integrity. This matches the validation used by WordPress REST API, ensuring consistency between client and server validation.
-
-### Supported Schema Features
-
-- All basic types: `string`, `number`, `integer`, `boolean`, `array`, `object`, `null`
-- String constraints: `minLength`, `maxLength`, `pattern`, `format` (email, date-time, etc.)
-- Number constraints: `minimum`, `maximum`, `multipleOf`
-- Array constraints: `minItems`, `maxItems`, `uniqueItems`
-- Object constraints: `required`, `additionalProperties`, `properties`
-
-See the [REST API documentation](5.rest-api.md) for more details on the server-side validation and execution endpoints that the client interacts with.
-
-## Next Steps
-
-Now that you understand how to use the JavaScript client, you can:
-
-- Integrate abilities into your block editor plugins
-- Create reactive admin interfaces using the WordPress data store
-- Build client-side capabilities that complement your server-side abilities
-- Develop external applications that interact with your WordPress site's capabilities
-
-The JavaScript client bridges the gap between your PHP abilities and modern frontend development, enabling rich interactive experiences while maintaining the security and validation standards of the WordPress Abilities API.
\ No newline at end of file

From 818224dc24dcb3f02e28befeeff5bbe86bd69cd7 Mon Sep 17 00:00:00 2001
From: Jonathan Bossenger <jonathanbossenger@gmail.com>
Date: Tue, 30 Sep 2025 11:26:31 +0200
Subject: [PATCH 4/5] Updates to API examples

---
 docs/7.javascript-client.md | 46 ++++++++++++++++++++-----------------
 1 file changed, 25 insertions(+), 21 deletions(-)

diff --git a/docs/7.javascript-client.md b/docs/7.javascript-client.md
index 897a1f7..7384a0f 100644
--- a/docs/7.javascript-client.md
+++ b/docs/7.javascript-client.md
@@ -1,15 +1,16 @@
 # 7. JavaScript/TypeScript Client
 
-The JavaScript client provides a simple interface for discovering and executing WordPress Abilities from frontend applications, block editor plugins, and external systems.
+The JavaScript client provides an interface for discovering and executing WordPress Abilities from the browser.
 
 ## Overview
 
-The JavaScript client enables frontend code to interact with the PHP Abilities API system. It can:
+The JavaScript client enables frontend code to interact with the Abilities API system. It can:
 
 - Discover all registered abilities on your WordPress site
-- Execute server-side PHP abilities via REST API calls
+- Execute server-side PHP abilities
 - Register and execute client-side JavaScript abilities
-- Handle input validation and permission checking
+
+You can read more about installation and setup in the [package readme](../packages/client/README.md).
 
 ## Core API Functions
 
@@ -31,10 +32,6 @@ console.log(`Found ${abilities.length} abilities`);
 abilities.forEach(ability => {
     console.log(`${ability.name}: ${ability.description}`);
 });
-
-// Filter by type
-const tools = abilities.filter(ability => ability.meta?.type === 'tool');
-const resources = abilities.filter(ability => ability.meta?.type === 'resource');
 ```
 
 ### getAbility(name)
@@ -80,13 +77,6 @@ const posts = await executeAbility('my-plugin/get-posts', {
     limit: 5
 });
 posts.forEach(post => console.log(post.title));
-
-// Execute with complex input
-const result = await executeAbility('my-plugin/update-option', {
-    option_name: 'blogname',
-    option_value: 'My New Site Title'
-});
-console.log('Success:', result.success);
 ```
 
 ### registerAbility(ability)
@@ -101,7 +91,13 @@ Registers a client-side ability that runs in the browser.
 **Example:**
 
 ```javascript
-// Register a simple notification ability
+// showNotification function
+const showNotification = (message) => {
+  new Notification(message);
+  return { success: true, displayed: message };
+}
+
+// Register a notification ability which calls the showNotification function
 registerAbility({
     name: 'my-plugin/show-notification',
     label: 'Show Notification',
@@ -115,11 +111,19 @@ registerAbility({
         required: ['message']
     },
     callback: async ({ message, type = 'info' }) => {
-        // Show browser notification
-        if (Notification.permission === 'granted') {
-            new Notification(message);
-        }
-        return { success: true, displayed: message };
+      // Show browser notification
+      if (!("Notification" in window)) {
+         alert("This browser does not support desktop notification");
+        return { success: false, error: 'Browser does not support notifications' };
+      }
+      if (Notification.permission !== 'granted') {
+        Notification.requestPermission().then((permission) => {
+          if (permission === "granted") {
+            return showNotification(message);
+          }
+        });
+      }
+      return showNotification(message);
     },
     permissionCallback: () => {
         return !!wp.data.select('core').getCurrentUser();

From 54849b9dfdbec612e2264e56d5b0fcfb210d0217 Mon Sep 17 00:00:00 2001
From: Jonathan Bossenger <jonathanbossenger@gmail.com>
Date: Tue, 30 Sep 2025 11:44:28 +0200
Subject: [PATCH 5/5] Fix indenting issue

---
 docs/7.javascript-client.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/7.javascript-client.md b/docs/7.javascript-client.md
index 7384a0f..2b4154c 100644
--- a/docs/7.javascript-client.md
+++ b/docs/7.javascript-client.md
@@ -113,7 +113,7 @@ registerAbility({
     callback: async ({ message, type = 'info' }) => {
       // Show browser notification
       if (!("Notification" in window)) {
-         alert("This browser does not support desktop notification");
+        alert("This browser does not support desktop notification");
         return { success: false, error: 'Browser does not support notifications' };
       }
       if (Notification.permission !== 'granted') {