Abilities – fluent-wp-client

Overview

fluent-wp-client supports the WordPress Abilities API exposed at /wp-json/wp-abilities/v1.

Use it to inspect registered abilities, list categories, execute ability run endpoints, and fetch the live input/output schemas exposed by WordPress.

Metadata

Ability metadata

const abilities = await wp.getAbilities();
const ability = await wp.getAbility('test/get-site-title');
const categories = await wp.getAbilityCategories();
const category = await wp.getAbilityCategory('test');

Direct execution helpers

Choose the helper that matches the ability annotations:

• executeGetAbility() for readonly: true
• executeRunAbility() for regular POST abilities
• executeDeleteAbility() for destructive: true

Direct execution helpers

const siteTitle = await wp.executeGetAbility<{ title: string }>('test/get-site-title');

const updated = await wp.executeRunAbility<{ previous: string; current: string }>(
  'test/update-option',
  { value: 'hello' },
);

const deleted = await wp.executeDeleteAbility<{ deleted: boolean }>('test/delete-option');

Fluent execution

Use client.ability(name) when you want a reusable ability handle.

Fluent ability execution

const processComplex = wp
  .ability<
    { name: string; settings: { theme: string } },
    { processed: boolean; echo: { name: string } }
  >('test/process-complex')
;

const result = await processComplex.run({
  name: 'demo',
  settings: { theme: 'dark' },
});

Builder methods:

• getDefinition()
• get(input?)
• run(input?)
• delete(input?)
• describe()

Custom validation with describe()

Ability execution does not run local validation. WordPress remains the source of truth.

When you want app-level validation, fetch the live schema and validate the payload yourself before calling the ability:

Validate one ability input with the live schema

import { z } from 'zod';

const desc = await wp.ability('test/process-complex').describe();
const inputSchema = z.fromJSONSchema(desc.schemas.input!);
const outputSchema = z.fromJSONSchema(desc.schemas.output!);

const validatedInput = inputSchema.parse({
  name: 'demo',
  settings: { theme: 'dark' },
});

const result = await wp.ability('test/process-complex').run(validatedInput);
const validatedResult = outputSchema.parse(result);

Schemas

The root package exports these ability schemas as Standard Schema validators:

• abilityAnnotationsSchema
• abilitySchema
• abilityCategorySchema
• getAbilityInputSchema
• runAbilityInputSchema
• deleteAbilityInputSchema

Need native Zod APIs?

Import from fluent-wp-client/zod when you need .parse(), .shape, or .extend():

import {
  abilitySchema,
  getAbilityInputSchema,
} from 'fluent-wp-client/zod';

const parsed = abilitySchema.parse(unknownAbility);
const input = getAbilityInputSchema.parse({ name: 'test/get-site-title' });

All ability schemas use .passthrough() so plugin-added fields stay available.

Validation model

• Ability metadata helpers validate payloads with built-in ability schemas
• Ability execution defers request validation to WordPress
• Use describe() or explore() when you want local validation in your application
• Failed REST responses throw WordPressHttpError (subclass of WordPressClientError)