Package Exports

@atomic-solutions/wordpress-api-client
@atomic-solutions/wordpress-api-client/client
@atomic-solutions/wordpress-api-client/http
@atomic-solutions/wordpress-api-client/package.json
@atomic-solutions/wordpress-api-client/testing
@atomic-solutions/wordpress-api-client/utils

Readme

@atomic-solutions/wordpress-utils

Type-safe WordPress REST API client (platform-agnostic)

⚛️ React users: This is a platform-agnostic client. If you're using React or React Native, use @atomic-solutions/react-wordpress instead for React Query hooks and context providers.

Features

🔒 Type-safe: Full TypeScript support with Zod schema validation
🌐 Platform-agnostic: Works in Node.js, browsers, React, React Native
🔐 JWT Authentication: Support for JWT Authentication plugin
📄 Pagination: Automatic handling of WordPress pagination headers
🎯 Error Handling: Built-in error classes with optional error reporter injection

Installation

pnpm add @atomic-solutions/wordpress-utils

For React/React Native projects, install react-wordpress instead:

pnpm add @atomic-solutions/react-wordpress

Peer Dependencies

pnpm add axios zod

Quick Start

React users: See @atomic-solutions/react-wordpress for React Query hooks and provider.

Basic Usage (Platform-agnostic)

import { createClient } from '@atomic-solutions/wordpress-utils';

// Create a client
const client = createClient({
  baseURL: 'https://example.com/wp-json',
  jwtToken: {
    get: () => AsyncStorage.getItem('wp_jwt_token'),
  },
});

// Use the API directly
const posts = await client.posts.list({ per_page: 10 });
const post = await client.posts.get(123);
const categories = await client.categories.list();

API Reference

Client Configuration

interface WordPressConfig {
  baseURL: string;           // WordPress wp-json URL
  jwtToken?: JwtTokenAdapter; // Optional JWT token provider
  queryKeyPrefix?: string[];  // Query key prefix (default: ['wordpress'])
  timeout?: number;           // Request timeout (default: 30000)
  headers?: Record<string, string>; // Custom headers
  errorReporter?: ErrorReporter; // Optional error reporter for tracking (default: console.error)
  onRequest?: (config) => config;   // Request interceptor
  onResponse?: (response) => response; // Response interceptor
  onError?: (error) => void;  // Error handler
}

Client API Methods

The client provides direct access to all WordPress REST API endpoints:

// Posts
const posts = await client.posts.list({ per_page: 10 });
const post = await client.posts.get(123);
const postBySlug = await client.posts.getBySlug('hello-world');

// Categories
const categories = await client.categories.list();
const category = await client.categories.get(5);

// Media
const media = await client.media.get(456);

// Users (requires authentication)
const currentUser = await client.users.me();

// Auth
const token = await client.auth.login({ username: 'user', password: 'pass' });
const isValid = await client.auth.validateToken();

Error Handling

import { WordPressError } from '@atomic-solutions/wordpress-utils';

try {
  await client.posts.get(999);
} catch (error) {
  if (error instanceof WordPressError) {
    console.log(error.userMessage); // User-friendly message
    console.log(error.wpCode);      // WordPress error code
    console.log(error.retryable);   // Whether to retry
    console.log(error.isAuthError); // Authentication error?
    console.log(error.isNotFoundError); // 404 error?
  }
}

Error Reporter Integration

You can integrate with error tracking services like Sentry:

import * as Sentry from '@sentry/react-native';
import { createClient } from '@atomic-solutions/wordpress-utils';

const client = createClient({
  baseURL: 'https://example.com/wp-json',
  errorReporter: {
    report: (error) => Sentry.captureException(error),
  },
});

Integration Testing

The package provides testing utilities for consumer projects to verify WordPress API connectivity in CI/CD pipelines.

Quick Health Check

import { createClient } from '@atomic-solutions/wordpress-utils';
import { runHealthCheck, assertHealthy } from '@atomic-solutions/wordpress-utils/testing';

test('WordPress API is healthy', async () => {
  const client = createClient({ baseURL: process.env.WP_API_URL! });
  const report = await runHealthCheck(client);

  assertHealthy(report); // Throws if any check fails
  expect(report.overall).toBe(true);
}, 30000);

Health Checker Factory

import { createHealthChecker } from '@atomic-solutions/wordpress-utils/testing';

const checkHealth = createHealthChecker({
  baseURL: process.env.WP_API_URL!,
});

test('WordPress API responds', async () => {
  const report = await checkHealth();
  expect(report.summary.failed).toBe(0);
});

Full Test Suite

For comprehensive integration testing, use the pre-built test suite:

// wordpress-api.integration.test.ts
import { createWordPressTestSuite } from '@atomic-solutions/wordpress-utils/testing';

createWordPressTestSuite({
  config: {
    baseURL: process.env.WP_API_URL || 'https://example.com/wp-json',
  },
  timeout: 30000,
  skipMedia: false, // Set true if site has no media
  skipAuth: true,   // Set false if testing JWT auth
});

This runs tests for:

Health check (connectivity, schema validation)
Posts API (list, single, slug lookup, pagination)
Categories API (list, single)
Media API (featured images)
Auth API (JWT validation, if enabled)

Health Check Report

interface HealthCheckReport {
  baseURL: string;
  timestamp: string;
  overall: boolean;        // true if all checks passed
  results: HealthCheckResult[];
  summary: {
    passed: number;
    failed: number;
    total: number;
  };
}

Tree-shaking Support

Import only what you need for optimal bundle size:

// Import just the client
import { createClient } from '@atomic-solutions/wordpress-utils/client';

// Import just schemas
import { PostSchema, CategorySchema } from '@atomic-solutions/wordpress-utils/schemas';

// Import just HTTP utilities
import { calculatePagination } from '@atomic-solutions/wordpress-utils/http';

// Import just query keys utility
import { createQueryKeys } from '@atomic-solutions/wordpress-utils/utils';

Migration from v1.x

If you were using React hooks from v1.x, follow these steps:

1. Install react-wordpress

pnpm add @atomic-solutions/react-wordpress

2. Update Imports

// Before (v1.x)
import { usePosts, WordPressProvider } from '@atomic-solutions/wordpress-utils';

// After (v2.x)
import { usePosts, WordPressProvider } from '@atomic-solutions/react-wordpress';

3. Update Dependencies

{
  "dependencies": {
    "@atomic-solutions/wordpress-utils": "^2.0.0",
    "@atomic-solutions/react-wordpress": "^1.1.0"
  }
}

That's it! The API is identical - only the package name changed.

What Changed in v2.0.0

❌ Removed: React hooks (usePosts, useCategories, etc.) - now in react-wordpress
❌ Removed: WordPressProvider and WordPressContext - now in react-wordpress
❌ Removed: React and React Query peer dependencies
✅ Added: /schemas export path for tree-shaking
✅ Added: /utils export path for query keys utility
✅ Improved: Test coverage (112+ tests)

If You're NOT Using React

No breaking changes! Just update the version:

{
  "dependencies": {
    "@atomic-solutions/wordpress-utils": "^2.0.0"
  }
}

Architecture

schemas (Zod schemas)
       ↓
wordpress-utils (platform-agnostic API client)
       ↓
react-wordpress (React Query hooks + provider)
       ↓
React / React Native apps

License

MIT

@atomic-solutions/wordpress-api-client