wp-native-client 0.0.1

package/src/client.ts

@@ -0,0 +1,191 @@
+/**
+ * WPNativeClient — universal WordPress client built on the Abilities API.
+ *
+ * One client. No subclasses. No per-site wrappers.
+ *
+ * The client wraps a Transport (FetchTransport, AuthFetchTransport, or
+ * WpApiFetchTransport) and exposes two surfaces:
+ *
+ *   1. Discovery — fetch the site's ability catalog at startup
+ *   2. Execution — call abilities by name with typed input/output
+ *
+ * Site-specific concerns (extrachill/* abilities, woocommerce/* abilities,
+ * etc.) are addressed via ability namespacing on the server side. The
+ * client itself never knows the difference between a core WP ability and
+ * a plugin-registered one — they're all just strings + JSON Schemas.
+ *
+ * Example:
+ *
+ *   import { WPNativeClient, AuthFetchTransport } from 'wp-native-client';
+ *
+ *   const client = new WPNativeClient(
+ *     new AuthFetchTransport({ baseUrl: 'https://example.com/wp-json', ... })
+ *   );
+ *
+ *   await client.discover();
+ *
+ *   const posts = await client.execute<Post[]>('wp/post.list', { per_page: 20 });
+ *   const me    = await client.execute<User>('wp-native/user.me');
+ */
+
+import type { Transport } from './transports/types';
+import { ApiError } from './transports/fetch';
+import { AbilityCatalog } from './abilities/catalog';
+import { discoverAbilities } from './abilities/discovery';
+import type {
+  AbilityDescriptor,
+  AbilityExecutionResponse,
+} from './abilities/types';
+
+const RUN_PATH_PREFIX = 'wp-abilities/v1/abilities';
+
+export interface WPNativeClientConfig {
+  /**
+   * Auto-fail execute() calls for abilities not present in the catalog.
+   *
+   * When true (default), execute() throws synchronously if the ability
+   * name is not registered on the site, before making the HTTP request.
+   * This catches typos and missing-plugin scenarios at the call site.
+   *
+   * Set to false if you want to call abilities before discover() has
+   * run (auth bootstrap, for example) — but prefer executeUnchecked()
+   * for that case so the intent is explicit.
+   */
+  validateAbilityNames?: boolean;
+}
+
+export class WPNativeClient {
+  private readonly transport: Transport;
+  private readonly config: Required<WPNativeClientConfig>;
+  private _catalog: AbilityCatalog | null = null;
+
+  constructor(transport: Transport, config: WPNativeClientConfig = {}) {
+    this.transport = transport;
+    this.config = {
+      validateAbilityNames: config.validateAbilityNames ?? true,
+    };
+  }
+
+  /**
+   * Walk the Abilities API and populate the in-memory catalog.
+   *
+   * Call once at app startup, after auth is established. Subsequent
+   * calls replace the catalog (cheap to re-run if the server registers
+   * new abilities at runtime).
+   *
+   * Optionally filter to a subset by category — useful when bootstrapping
+   * a minimal client that only needs auth abilities.
+   */
+  async discover(options: { category?: string } = {}): Promise<AbilityCatalog> {
+    const filter: { category?: string } = {};
+    if (options.category !== undefined) {
+      filter.category = options.category;
+    }
+    const catalog = await discoverAbilities(this.transport, filter);
+    this._catalog = catalog;
+    return catalog;
+  }
+
+  /**
+   * The current catalog. Throws if discover() has not been called.
+   *
+   * Use catalogOrNull() if you want to feature-detect without throwing.
+   */
+  get catalog(): AbilityCatalog {
+    if (!this._catalog) {
+      throw new Error(
+        'WPNativeClient: catalog not loaded. Call discover() before accessing catalog.',
+      );
+    }
+    return this._catalog;
+  }
+
+  /**
+   * Non-throwing accessor for the catalog. Returns null if discover()
+   * has not been called.
+   */
+  catalogOrNull(): AbilityCatalog | null {
+    return this._catalog;
+  }
+
+  /**
+   * Whether discover() has populated the catalog.
+   */
+  hasCatalog(): boolean {
+    return this._catalog !== null;
+  }
+
+  /**
+   * Execute an ability by name.
+   *
+   * The ability is looked up in the catalog (when validateAbilityNames is
+   * enabled), then POSTed to /wp-abilities/v1/abilities/{name}/run with
+   * the given input as the request body's `input` field.
+   *
+   * The response shape `{ result: TResult }` is unwrapped — callers receive
+   * the result value directly.
+   *
+   * Throws:
+   *   - Error    if the ability is not in the catalog (and validation enabled)
+   *   - ApiError if the server returns a non-2xx response
+   */
+  async execute<TResult = unknown, TInput = unknown>(
+    name: string,
+    input?: TInput,
+  ): Promise<TResult> {
+    if (this.config.validateAbilityNames && this._catalog) {
+      if (!this._catalog.has(name)) {
+        throw new Error(
+          `WPNativeClient: ability "${name}" is not registered on this site. ` +
+            `Run discover() to refresh the catalog, or use executeUnchecked() ` +
+            `to bypass validation.`,
+        );
+      }
+    }
+
+    return this.executeUnchecked<TResult, TInput>(name, input);
+  }
+
+  /**
+   * Execute an ability without checking the catalog.
+   *
+   * Use this for the auth bootstrap path (login → discover) where the
+   * client must call abilities before the catalog exists. For all other
+   * call sites, prefer execute() so missing abilities fail loudly at
+   * the call site.
+   */
+  async executeUnchecked<TResult = unknown, TInput = unknown>(
+    name: string,
+    input?: TInput,
+  ): Promise<TResult> {
+    const path = `${RUN_PATH_PREFIX}/${encodeURIComponent(name)}/run`;
+    const body: { input: TInput | null } = {
+      input: input === undefined ? null : input,
+    };
+
+    const response = await this.transport.request<AbilityExecutionResponse<TResult>>({
+      path,
+      method: 'POST',
+      body: body as Record<string, unknown>,
+    });
+
+    if (!response || typeof response !== 'object' || !('result' in response)) {
+      throw new ApiError(
+        `WPNativeClient: malformed ability response for "${name}". ` +
+          `Expected { result: ... }.`,
+        'malformed_ability_response',
+        500,
+      );
+    }
+
+    return response.result;
+  }
+
+  /**
+   * Get a single ability descriptor from the catalog.
+   * Returns undefined if not registered or catalog not loaded.
+   */
+  describe(name: string): AbilityDescriptor | undefined {
+    return this._catalog?.get(name);
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * wp-native-client — universal WordPress client built on the Abilities API.
+ *
+ * One client. Discovery + execution. No per-site wrappers.
+ */
+
+// Client
+export { WPNativeClient } from './client';
+export type { WPNativeClientConfig } from './client';
+
+// Abilities subsystem
+export { AbilityCatalog } from './abilities/catalog';
+export {
+  discoverAbilities,
+  fetchAbilitiesPage,
+  fetchAbility,
+  fetchAbilityCategories,
+} from './abilities/discovery';
+export type {
+  AbilityDescriptor,
+  AbilityCategory,
+  AbilityExecutionResponse,
+  AbilityListPage,
+  AbilityListParams,
+} from './abilities/types';
+
+// Transports
+export type { Transport, TransportRequest, TransportResponse } from './transports/types';
+export { FetchTransport, ApiError } from './transports/fetch';
+export type { FetchTransportConfig } from './transports/fetch';
+export { AuthFetchTransport } from './transports/auth-fetch';
+export type { AuthFetchTransportConfig, StoredTokens } from './transports/auth-fetch';

package/src/transports/auth-fetch.ts

@@ -0,0 +1,310 @@
+/**
+ * Authenticated fetch transport with token lifecycle.
+ *
+ * Wraps FetchTransport and adds:
+ * - Bearer token injection via getAuthHeaders
+ * - Proactive token refresh before expiry
+ * - 401 retry with refresh lock (prevents thundering herd)
+ * - Auth failure callback for logout/navigation
+ *
+ * Platform-specific storage is injected via callbacks:
+ *   - loadTokens: read persisted tokens on init
+ *   - saveTokens: persist after login/refresh
+ *   - clearTokens: wipe on logout/auth failure
+ *
+ * Usage:
+ *
+ *   const transport = new AuthFetchTransport({
+ *     baseUrl: 'https://wordpress.test/wp-json',
+ *     refreshPath: 'wp-native/v1/auth/refresh',
+ *     getDeviceId: () => getSecureItem('device_id'),
+ *     loadTokens: () => getSecureItem('tokens').then(JSON.parse),
+ *     saveTokens: (t) => setSecureItem('tokens', JSON.stringify(t)),
+ *     clearTokens: () => deleteSecureItem('tokens'),
+ *     onAuthFailure: () => router.replace('/login'),
+ *   });
+ *
+ *   // Inject your platform's secure storage via the callbacks above.
+ *   await transport.initialize(); // loads stored tokens
+ */
+
+import type { Transport, TransportRequest } from './types';
+import { ApiError } from './fetch';
+
+/** Token data stored by consumers. */
+export interface StoredTokens {
+  accessToken: string;
+  refreshToken: string;
+  /** Unix timestamp (seconds) when the access token expires. */
+  accessExpiresAt: number;
+}
+
+export interface AuthFetchTransportConfig {
+  /** Base URL for the REST API, e.g. "https://example.com/wp-json" */
+  baseUrl: string;
+
+  /**
+   * REST path for the token refresh endpoint.
+   * @default 'wp-native/v1/auth/refresh'
+   */
+  refreshPath?: string;
+
+  /**
+   * How many milliseconds before expiry to proactively refresh.
+   * @default 60000 (1 minute)
+   */
+  refreshBufferMs?: number;
+
+  /**
+   * Return a device ID for refresh requests.
+   * Mobile apps generate a UUID and persist it; Node scripts can return a fixed string.
+   */
+  getDeviceId: () => string | Promise<string>;
+
+  /**
+   * Load persisted tokens on initialize().
+   * Return null if no tokens are stored.
+   */
+  loadTokens: () => StoredTokens | null | Promise<StoredTokens | null>;
+
+  /**
+   * Persist tokens after login, register, or refresh.
+   */
+  saveTokens: (tokens: StoredTokens) => void | Promise<void>;
+
+  /**
+   * Clear persisted tokens on logout or auth failure.
+   */
+  clearTokens: () => void | Promise<void>;
+
+  /**
+   * Called when authentication cannot be recovered (refresh failed, no tokens).
+   * Use this to navigate to a login screen or reset app state.
+   */
+  onAuthFailure?: () => void;
+
+  /**
+   * Extra headers to include on every request.
+   * Useful for custom client identification headers.
+   */
+  defaultHeaders?: Record<string, string>;
+}
+
+export class AuthFetchTransport implements Transport {
+  private config: AuthFetchTransportConfig;
+  private accessToken: string | null = null;
+  private refreshToken: string | null = null;
+  private accessExpiresAt: number | null = null;
+  private refreshPromise: Promise<boolean> | null = null;
+  private initialized = false;
+
+  constructor(config: AuthFetchTransportConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Load stored tokens into memory. Call once at app startup.
+   */
+  async initialize(): Promise<void> {
+    const tokens = await this.config.loadTokens();
+    if (tokens) {
+      this.accessToken = tokens.accessToken;
+      this.refreshToken = tokens.refreshToken;
+      this.accessExpiresAt = tokens.accessExpiresAt;
+    }
+    this.initialized = true;
+  }
+
+  /**
+   * Whether initialize() has been called.
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Whether tokens are currently loaded in memory.
+   */
+  hasTokens(): boolean {
+    return this.accessToken !== null && this.refreshToken !== null;
+  }
+
+  /**
+   * Store new tokens in memory and persist via saveTokens callback.
+   * Call after login, register, or any auth flow that returns tokens.
+   */
+  async setTokens(tokens: StoredTokens): Promise<void> {
+    this.accessToken = tokens.accessToken;
+    this.refreshToken = tokens.refreshToken;
+    this.accessExpiresAt = tokens.accessExpiresAt;
+    await this.config.saveTokens(tokens);
+  }
+
+  /**
+   * Set or replace the auth failure callback.
+   * Useful when the callback depends on framework state or navigation
+   * and must be wired after transport construction.
+   */
+  setOnAuthFailure(callback: () => void): void {
+    this.config.onAuthFailure = callback;
+  }
+
+  /**
+   * Clear tokens from memory and storage. Call on logout.
+   */
+  async clearAuth(): Promise<void> {
+    this.accessToken = null;
+    this.refreshToken = null;
+    this.accessExpiresAt = null;
+    await this.config.clearTokens();
+  }
+
+  /**
+   * Execute an HTTP request with automatic auth handling.
+   *
+   * - Injects Bearer token if available
+   * - Proactively refreshes before expiry
+   * - Retries once on 401 after refreshing
+   */
+  async request<T>(req: TransportRequest): Promise<T> {
+    // Proactive refresh before the request
+    if (this.hasTokens() && this.isAccessExpiringSoon()) {
+      const refreshed = await this.refreshAccessToken();
+      if (!refreshed) {
+        await this.handleAuthFailure();
+        throw new ApiError('Session expired', 'session_expired', 401);
+      }
+    }
+
+    try {
+      return await this.executeRequest<T>(req);
+    } catch (error) {
+      // Retry once on 401 after refresh
+      if (error instanceof ApiError && error.status === 401 && this.refreshToken) {
+        const refreshed = await this.refreshAccessToken();
+        if (!refreshed) {
+          await this.handleAuthFailure();
+          throw new ApiError('Session expired', 'session_expired', 401);
+        }
+        return await this.executeRequest<T>(req);
+      }
+      throw error;
+    }
+  }
+
+  // ─── Private ───────────────────────────────────────────────────────────
+
+  private async executeRequest<T>(req: TransportRequest): Promise<T> {
+    const url = `${this.config.baseUrl}/${req.path}`;
+
+    const isFormData = typeof FormData !== 'undefined' && req.body instanceof FormData;
+
+    const headers: Record<string, string> = {
+      ...(!isFormData ? { 'Content-Type': 'application/json' } : {}),
+      ...(this.config.defaultHeaders ?? {}),
+      ...(this.accessToken ? { Authorization: `Bearer ${this.accessToken}` } : {}),
+      ...req.headers,
+    };
+
+    const response = await fetch(url, {
+      method: req.method,
+      headers,
+      body: req.body
+        ? isFormData
+          ? (req.body as BodyInit)
+          : JSON.stringify(req.body)
+        : null,
+    });
+
+    if (response.status === 401) {
+      throw new ApiError('Unauthorized', 'unauthorized', 401);
+    }
+
+    if (!response.ok) {
+      let errorData: { code?: string; message?: string } = {};
+      try {
+        errorData = await response.json();
+      } catch {
+        // Response wasn't JSON
+      }
+      throw new ApiError(
+        errorData.message || `Request failed with status ${response.status}`,
+        errorData.code || 'request_failed',
+        response.status,
+      );
+    }
+
+    if (response.status === 204) {
+      return undefined as T;
+    }
+
+    return (await response.json()) as T;
+  }
+
+  private isAccessExpiringSoon(): boolean {
+    if (!this.accessExpiresAt) return true;
+    const bufferMs = this.config.refreshBufferMs ?? 60_000;
+    return Date.now() >= this.accessExpiresAt * 1000 - bufferMs;
+  }
+
+  /**
+   * Refresh the access token. Uses a lock to deduplicate concurrent refreshes.
+   */
+  private async refreshAccessToken(): Promise<boolean> {
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
+
+    this.refreshPromise = this.executeRefresh();
+
+    try {
+      return await this.refreshPromise;
+    } finally {
+      this.refreshPromise = null;
+    }
+  }
+
+  private async executeRefresh(): Promise<boolean> {
+    if (!this.refreshToken) return false;
+
+    try {
+      const deviceId = await this.config.getDeviceId();
+      const refreshPath = this.config.refreshPath ?? 'wp-native/v1/auth/refresh';
+      const url = `${this.config.baseUrl}/${refreshPath}`;
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          refresh_token: this.refreshToken,
+          device_id: deviceId,
+        }),
+      });
+
+      if (!response.ok) return false;
+
+      const data = (await response.json()) as {
+        access_token: string;
+        access_expires_at: string;
+        refresh_token: string;
+      };
+
+      const expiresAt = Math.floor(new Date(data.access_expires_at).getTime() / 1000);
+
+      await this.setTokens({
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        accessExpiresAt: expiresAt,
+      });
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async handleAuthFailure(): Promise<void> {
+    await this.clearAuth();
+    this.config.onAuthFailure?.();
+  }
+}

package/src/transports/fetch.ts

@@ -0,0 +1,107 @@
+/**
+ * Native fetch transport.
+ *
+ * Works in:
+ * - React Native (built-in fetch)
+ * - Modern browsers (without @wordpress/api-fetch)
+ * - Node 18+ (built-in fetch)
+ *
+ * Auth is handled via a configurable header function.
+ * Mobile apps pass Bearer tokens, Node scripts pass Basic auth, etc.
+ */
+
+import type { Transport, TransportRequest } from './types';
+
+export interface FetchTransportConfig {
+  /** Base URL for the REST API, e.g. "https://example.com/wp-json" */
+  baseUrl: string;
+
+  /**
+   * Return auth headers for each request.
+   * Return empty object for public endpoints.
+   *
+   * Examples:
+   *   Bearer:  () => ({ Authorization: `Bearer ${token}` })
+   *   Basic:   () => ({ Authorization: `Basic ${btoa('user:pass')}` })
+   *   Nonce:   () => ({ 'X-WP-Nonce': nonce })
+   */
+  getAuthHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+
+  /**
+   * Called when a request returns 401.
+   * Use this to trigger token refresh or logout.
+   */
+  onUnauthorized?: () => void | Promise<void>;
+}
+
+export class FetchTransport implements Transport {
+  private config: FetchTransportConfig;
+
+  constructor(config: FetchTransportConfig) {
+    this.config = config;
+  }
+
+  async request<T>(req: TransportRequest): Promise<T> {
+    const url = `${this.config.baseUrl}/${req.path}`;
+
+    const authHeaders = this.config.getAuthHeaders
+      ? await this.config.getAuthHeaders()
+      : {};
+
+    const isFormData = typeof FormData !== 'undefined' && req.body instanceof FormData;
+
+    const headers: Record<string, string> = {
+      ...(!isFormData ? { 'Content-Type': 'application/json' } : {}),
+      ...authHeaders,
+      ...req.headers,
+    };
+
+    const response = await fetch(url, {
+      method: req.method,
+      headers,
+      body: req.body
+        ? isFormData
+          ? (req.body as BodyInit)
+          : JSON.stringify(req.body)
+        : null,
+    });
+
+    if (response.status === 401) {
+      await this.config.onUnauthorized?.();
+      throw new ApiError('Unauthorized', 'unauthorized', 401);
+    }
+
+    if (!response.ok) {
+      let errorData: { code?: string; message?: string } = {};
+      try {
+        errorData = await response.json();
+      } catch {
+        // Response wasn't JSON
+      }
+      throw new ApiError(
+        errorData.message || `Request failed with status ${response.status}`,
+        errorData.code || 'request_failed',
+        response.status,
+      );
+    }
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return undefined as T;
+    }
+
+    return (await response.json()) as T;
+  }
+}
+
+export class ApiError extends Error {
+  code: string;
+  status: number;
+
+  constructor(message: string, code: string, status: number) {
+    super(message);
+    this.name = 'ApiError';
+    this.code = code;
+    this.status = status;
+  }
+}

package/src/transports/types.ts

@@ -0,0 +1,24 @@
+/**
+ * Transport layer abstraction.
+ *
+ * A Transport is the only platform-specific piece in the client.
+ * It knows how to send HTTP requests and handle auth headers.
+ * Everything above it is pure TypeScript — platform agnostic.
+ */
+
+export interface TransportRequest {
+  path: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  body?: Record<string, unknown> | FormData;
+  headers?: Record<string, string>;
+}
+
+export interface TransportResponse<T = unknown> {
+  data: T;
+  status: number;
+  headers: Record<string, string>;
+}
+
+export interface Transport {
+  request<T>(req: TransportRequest): Promise<T>;
+}