Ability Actions – astrojs-wp-integration

Ability Actions

Ability actions let you execute WordPress abilities from Astro server-side code.

Actions overview Shared auth strategies, error mapping, and factory patterns.

User actions User-focused action patterns with typed schemas.

Post actions Content write flows for posts, pages, and custom post types.

WordPress abilities expose executable server-side primitives through the REST API at /wp-json/wp-abilities/v1.

Each ability declares annotations that determine which HTTP method you must use:

Annotation	HTTP method	Action factory	Execute function
readonly: true	GET	createGetAbilityAction	executeGetAbility
readonly: false, destructive: false	POST	createRunAbilityAction	executeRunAbility
destructive: true	DELETE	createDeleteAbilityAction	executeDeleteAbility

Setup

import {
  createDeleteAbilityAction,
  createGetAbilityAction,
  createRunAbilityAction,
} from 'wp-astrojs-integration';
import { wordPressAuthBridge } from '../lib/auth/bridge';

export const server = {
  getAbility: createGetAbilityAction(wordPressAuthBridge.getClient),
  runAbility: createRunAbilityAction(wordPressAuthBridge.getClient),
  deleteAbility: createDeleteAbilityAction(wordPressAuthBridge.getClient),
};

Read-only abilities

Use createGetAbilityAction for abilities annotated with readonly: true.

const { data, error } = await Astro.callAction(actions.getAbility, {
  name: 'my-plugin/get-site-info',
  input: { user_id: 1 },
});

Regular abilities

Use createRunAbilityAction for abilities that execute through POST /run.

const { data, error } = await Astro.callAction(actions.runAbility, {
  name: 'my-plugin/update-option',
  input: { value: 'new-value' },
});

Destructive abilities

Use createDeleteAbilityAction for abilities annotated with destructive: true.

const { data, error } = await Astro.callAction(actions.deleteAbility, {
  name: 'my-plugin/delete-cache',
});

Typed responses

Pass a responseSchema when you want the action result validated in Astro after the WordPress ability runs. Any Standard Schema-compatible validator works, including Zod.

import { WordPressClient } from 'fluent-wp-client';
import { z } from 'astro/zod';

const optionResultSchema = z.object({
  previous: z.string(),
  current: z.string(),
});

export const server = {
  runAbility: createRunAbilityAction(new WordPressClient({
    baseUrl: import.meta.env.WP_URL,
    auth: {
      username: import.meta.env.WP_USERNAME,
      password: import.meta.env.WP_APP_PASSWORD,
    },
  }), {
    responseSchema: optionResultSchema,
  }),
};

Execute helpers

The raw execute* functions are useful in tests or custom wrappers.

import { WordPressClient } from 'fluent-wp-client';
import {
  executeDeleteAbility,
  executeGetAbility,
  executeRunAbility,
} from 'wp-astrojs-integration/actions';

const wp = new WordPressClient({
  baseUrl: 'https://example.com',
  auth: { username: 'admin', password: 'app-password' },
});

await executeGetAbility(wp, { name: 'my-plugin/get-site-info' });
await executeRunAbility(wp, { name: 'my-plugin/update-option', input: { value: 'hello' } });
await executeDeleteAbility(wp, { name: 'my-plugin/delete-cache' });

Client relationship

Astro ability actions are thin wrappers around fluent-wp-client.

They resolve Astro auth per request, call the standalone client, and map WordPress failures into ActionError.

For direct runtime usage outside Astro, use the published fluent-wp-client abilities guide.