WordPress Client

🚀 Features

• 📦 API discovery support.
• ⏲️ Measures request completion time.
• 📝 Supports all CRUD operations.
• 🌐 Supports all common REST endpoints.
• 🧩 GraphQL (WPGraphQL) support: client.graphql.query/mutate/raw() with auth.
• 🎨 Custom Requests & Authorization systems.
• 🔐 3 Popular authorization methods.
• 🗄️ Third‑party Database integration.
• 🔧 Middlewares for request & response operations.
• 🎣 Events for preprocessing response.
• 🚀 Execute requests in Parallel (with configurable error handling).
• 🧠 Optional in‑memory caching for GET requests.
• 🌊 Polling-based streaming for single-resource retrieve endpoints (works great with Riverpod's StreamProvider).

📦 Install

Add wordpress_client to your pubspec.yaml:

dependencies:
  wordpress_client: ^9.2.0

Then run flutter pub get or dart pub get.

🔧 Quick start

Import and initialize:

import 'package:wordpress_client/wordpress_client.dart';

final client = WordpressClient.forSite(
  siteUrl: Uri.parse('https://example.com'),
  // or: baseUrl via WordpressClient(baseUrl: Uri.parse('.../wp-json/wp/v2'))
);

🧩 GraphQL (WPGraphQL)

If your site uses the WPGraphQL plugin (canonical), you can send GraphQL operations using the same client and auth.

final client = WordpressClient.forSite(
  siteUrl: Uri.parse('https://example.com'),
  bootstrapper: (b) => b
    .withDefaultAuthorization(
      WordpressAuth.appPassword(user: 'user', appPassword: 'xxxx-xxxx'),
    )
    .build(),
);

// Auto-resolves https://example.com/graphql from the REST base.
final result = await client.graphql.query<List<Map<String, dynamic>>>(
  document: '''
    query Posts($limit: Int!) {
      posts(first: $limit) {
        nodes { id title }
      }
    }
  ''',
  variables: { 'limit': 5 },
  parseData: (data) {
    final nodes = (data['posts']?['nodes'] as List<dynamic>? ?? const [])
        .cast<Map<String, dynamic>>();
    return nodes;
  },
  requireAuth: false, // set true for restricted queries/mutations
);

switch (result) {
  case WordpressSuccessResponse():
    print(result.data);
  case WordpressFailureResponse():
    print('GraphQL error: ${result.error}');
}

// Custom endpoint path if your site exposes a different GraphQL path
client.graphql.setEndpointPath('/custom-graphql');

Add an auth quickly (helpers available):

final client = WordpressClient.forSite(
  siteUrl: Uri.parse('https://example.com'),
  bootstrapper: (b) => b
    .withDefaultAuthorization(
      // Built-in helpers
      WordpressAuth.appPassword(user: 'user', appPassword: 'xxxx-xxxx'),
      // or: WordpressAuth.usefulJwt(user: 'user', password: 'pass', device: 'device-id')
      // or: WordpressAuth.basicJwt(user: 'user', password: 'pass')
    )
    .build(),
);

Enable caching via middleware (optional):

final client = WordpressClient(
  baseUrl: Uri.parse('https://example.com/wp-json/wp/v2'),
  bootstrapper: (b) => b
    .withCache(
      ttl: const Duration(minutes: 5),               // optional, default 1 minute
      // cache: MyCustomCacheManager(),              // optional custom store
      // clearOnWrite: false,                        // keep cache after POST/PUT/PATCH/DELETE
    )
    .build(),
);

📝 Notes: applies to GET requests; default store is in-memory (custom stores supported); cache clears by default on writes.

📩 Send a request

Retrieve 20 recent posts in ascending order:

final request = ListPostRequest(
  page: 1,
  perPage: 20,
  order: Order.asc,
);

final response = await client.posts.list(request);

// Dart 3 pattern matching
switch (response) {
  case WordpressSuccessResponse():
    final data = response.data; // List<Post>
    break;
  case WordpressFailureResponse():
    final error = response.error; // WordpressError
    break;
}

// Or use helpers
final posts = (await client.posts.list(ListPostRequest(perPage: 20))).map(
  onSuccess: (s) => s.data,
  onFailure: (f) => <Post>[],
);

final justPosts = (await client.posts.list(ListPostRequest(perPage: 20))).dataOrThrow();

Convenience extensions are available under client.<interface>.extensions for quick lookups and pagination:

final post = await client.posts.extensions.getById(123);
final allMedia = await client.media.extensions.listAll(perPage: 100);

📚 Advanced docs (Wiki)

Deep-dives and more examples live in the Wiki:

• 🧭 Getting Started: Usage
• 📩 Sending Requests
• 🛡 Authorization
• ⚡ Parallel Requests
• 🧠 Caching
• 🧩 GraphQL
• 🔗 Supported REST Methods
• 🧩 Pattern Directory Items
• 🧰 Using Custom Requests
• 🧪 Raw Requests
• 🔄 Middlewares
• 📜 API Changelog
• 🌊 Fluent Queries
• 🔄 Streaming and Polling

🤝 Feedback & Contributing

• 🐛 For bugs or feature requests, use the issue tracker.
• 💡 Contributions are always appreciated. PRs are welcome!

Contributor tips (scripts, release process, consistency guards) are documented in the Wiki.

📄 License

This project is MIT licensed.