fluent-wp-client – README

fluent-wp-client is a runtime-agnostic TypeScript client for the WordPress REST API. It works on Node.js, Deno, Bun, and in the browser using only web-standard APIs (fetch, URL, Blob).

Quick start

1. Install the package

   npm install fluent-wp-client

2. Create a client

   import { WordPressClient } from 'fluent-wp-client';
   
   const wp = new WordPressClient({
     baseUrl: 'https://your-wordpress-site.com',
   });

3. Use it

   import { getEmbeddedAuthor, getEmbeddedTerms } from 'fluent-wp-client';
   
   // List posts
   const posts = await wp.content('posts').list({ perPage: 10 });
   
   // Get a single item with embedded relations
   const book = await wp.content('books').item('my-book', { embed: true });
   const author = getEmbeddedAuthor(book);
   const genres = getEmbeddedTerms(book, 'genre');
   
   // Create (requires auth)
   const draft = await wp.content('posts').create({ title: 'Hello', status: 'draft' });
   
   // First-class resources
   const comments = await wp.comments().list({ post: 42 });
   const me = await wp.users().me();

What is a Resource Client?

wp.content('posts'), wp.terms('categories'), wp.media(), etc. each return a resource client — a dedicated helper for one type of content. The data returned is always a plain serializable DTO, safe for structuredClone(), JSON.stringify(), and cross-boundary transport.

Features

• Unified content builders — content('posts'), content('books'), terms('genre') share one API shape
• First-class resource clients — media(), comments(), users(), settings()
• Cross-resource search — searchContent() across posts, pages, and CPTs
• Embed and extraction helpers — embed: true or selective embed: ['author', 'wp:term'] plus typed extraction functions
• Lean payloads — no _embed overhead by default
• Flexible CPT defaults — tolerates post types that omit title, content, or excerpt
• Gutenberg block add-on — fluent-wp-client/blocks for block discovery, parsing, validation, and writes
• Framework-neutral agent helpers — root package helpers for selectors, JSON Schemas, fields, and query arguments
• AI SDK tools — fluent-wp-client/ai-sdk for manually composed Vercel AI SDK tools
• Auth flexibility — Basic, JWT, cookie+nonce, prebuilt headers, per-request signing
• Abilities API — discover and execute registered WordPress abilities
• Schema discovery — fetch live JSON Schemas, convert to Zod with z.fromJSONSchema()
• CLI code generation — generate TypeScript, JSON Schema, and Zod-ready artifacts from live REST schemas
• Standard Schema validation — validator-agnostic root exports; native Zod via fluent-wp-client/zod
• ACF extraction helpers — getAcfFieldPosts(), getAcfFieldPost(), getAcfFieldTerms() for ACF relation fields

Guides

Usage guide API styles, method reference, embed extraction, CRUD, pagination, and errors.

Authentication Choose the right auth strategy for your runtime.

Gutenberg content Block type discovery, parsing, validation, and writes.

Custom endpoints Custom post types, taxonomies, and plugin REST namespaces.

AI SDK Compose WordPress tools for the Vercel AI SDK.

Agent tools Build framework-native tools with catalog-backed selectors, schemas, fields, and query arguments.

AI tool design Design a minimal AI, MCP, or agent tool surface around WordPress schemas and policy.

Abilities Discover and execute WordPress abilities.

Schema discovery Fetch live JSON Schemas for runtime validation.

Validation Standard Schema, Zod, Valibot, or ArkType.

Embed extraction Embed parameters, extraction helpers, and ACF relation extraction.

Plugin support: ACF Expose ACF field descriptions and choice labels through a minimal PHP snippet.

Development notes

Contributor-facing transport, mutation helpers, query primitives, and base resource classes live in src/core/. Query builders live in src/builders/. The public API is re-exported from src/index.ts.