wp-native-client 0.0.1

package/dist/transports/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/transports/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/transports/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/C"}

package/dist/transports/types.js

@@ -0,0 +1,9 @@
+/**
+ * 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 {};
+//# sourceMappingURL=types.js.map

package/dist/transports/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/transports/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/transports/wp-api-fetch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * WordPress api-fetch transport.
+ *
+ * Wraps @wordpress/api-fetch for use inside WordPress blocks.
+ * Nonce handling, root URL, and middleware are all managed by WP core.
+ *
+ * This transport is in a separate entry point (wordpress.ts) so the main
+ * bundle has zero WordPress dependencies. Only import this in WP blocks.
+ */
+import type { Transport, TransportRequest } from './types';
+type ApiFetchOptions = {
+    path: string;
+    method: string;
+    data?: Record<string, unknown>;
+    body?: FormData;
+    headers?: Record<string, string>;
+};
+type ApiFetchFn = <T>(options: ApiFetchOptions) => Promise<T>;
+export declare class WpApiFetchTransport implements Transport {
+    private apiFetch;
+    constructor(apiFetch: ApiFetchFn);
+    request<T>(req: TransportRequest): Promise<T>;
+}
+export {};
+//# sourceMappingURL=wp-api-fetch.d.ts.map

package/dist/transports/wp-api-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wp-api-fetch.d.ts","sourceRoot":"","sources":["../../src/transports/wp-api-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAG3D,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,KAAK,UAAU,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAE9D,qBAAa,mBAAoB,YAAW,SAAS;IACnD,OAAO,CAAC,QAAQ,CAAa;gBAEjB,QAAQ,EAAE,UAAU;IAI1B,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;CA2BpD"}

package/dist/transports/wp-api-fetch.js

@@ -0,0 +1,40 @@
+/**
+ * WordPress api-fetch transport.
+ *
+ * Wraps @wordpress/api-fetch for use inside WordPress blocks.
+ * Nonce handling, root URL, and middleware are all managed by WP core.
+ *
+ * This transport is in a separate entry point (wordpress.ts) so the main
+ * bundle has zero WordPress dependencies. Only import this in WP blocks.
+ */
+import { ApiError } from './fetch';
+export class WpApiFetchTransport {
+    apiFetch;
+    constructor(apiFetch) {
+        this.apiFetch = apiFetch;
+    }
+    async request(req) {
+        const isFormData = typeof FormData !== 'undefined' && req.body instanceof FormData;
+        try {
+            const result = await this.apiFetch({
+                path: req.path,
+                method: req.method,
+                ...(isFormData
+                    ? { body: req.body }
+                    : req.body
+                        ? { data: req.body }
+                        : {}),
+                ...(req.headers ? { headers: req.headers } : {}),
+            });
+            return result;
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'code' in error) {
+                const wpError = error;
+                throw new ApiError(wpError.message, wpError.code, wpError.data?.status || 500);
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=wp-api-fetch.js.map

package/dist/transports/wp-api-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wp-api-fetch.js","sourceRoot":"","sources":["../../src/transports/wp-api-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAYnC,MAAM,OAAO,mBAAmB;IACtB,QAAQ,CAAa;IAE7B,YAAY,QAAoB;QAC9B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,OAAO,CAAI,GAAqB;QACpC,MAAM,UAAU,GAAG,OAAO,QAAQ,KAAK,WAAW,IAAI,GAAG,CAAC,IAAI,YAAY,QAAQ,CAAC;QAEnF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAI;gBACpC,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,GAAG,CAAC,UAAU;oBACZ,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAgB,EAAE;oBAChC,CAAC,CAAC,GAAG,CAAC,IAAI;wBACR,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAA+B,EAAE;wBAC/C,CAAC,CAAC,EAAE,CAAC;gBACT,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACjD,CAAC,CAAC;YACH,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;gBAC1D,MAAM,OAAO,GAAG,KAAqE,CAAC;gBACtF,MAAM,IAAI,QAAQ,CAChB,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,IAAI,EACZ,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,GAAG,CAC5B,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/wordpress.d.ts

@@ -0,0 +1,8 @@
+/**
+ * WordPress entry point — only import from inside Gutenberg blocks.
+ *
+ * Keeps @wordpress/api-fetch out of the main bundle so React Native /
+ * Node consumers don't pull in WP-specific deps.
+ */
+export { WpApiFetchTransport } from './transports/wp-api-fetch';
+//# sourceMappingURL=wordpress.d.ts.map

package/dist/wordpress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wordpress.d.ts","sourceRoot":"","sources":["../src/wordpress.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/wordpress.js

@@ -0,0 +1,8 @@
+/**
+ * WordPress entry point — only import from inside Gutenberg blocks.
+ *
+ * Keeps @wordpress/api-fetch out of the main bundle so React Native /
+ * Node consumers don't pull in WP-specific deps.
+ */
+export { WpApiFetchTransport } from './transports/wp-api-fetch';
+//# sourceMappingURL=wordpress.js.map

package/dist/wordpress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wordpress.js","sourceRoot":"","sources":["../src/wordpress.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "wp-native-client",
+  "version": "0.0.1",
+  "description": "Universal WordPress client built on the Abilities API. Discovery + execution. Works in WordPress blocks, React Native, and Node — one client, three transports, one ability surface.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "source": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./wordpress": {
+      "types": "./dist/wordpress.d.ts",
+      "default": "./dist/wordpress.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "GPL-2.0-or-later",
+  "author": "Chris Huber <chubes@extrachill.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chubes4/wp-native.git",
+    "directory": "packages/api-client"
+  },
+  "homepage": "https://github.com/chubes4/wp-native/tree/main/packages/api-client",
+  "bugs": "https://github.com/chubes4/wp-native/issues",
+  "keywords": [
+    "wordpress",
+    "abilities-api",
+    "headless",
+    "client",
+    "react-native",
+    "gutenberg"
+  ],
+  "scripts": {
+    "typecheck": "tsc -b",
+    "prepublishOnly": "tsc -b"
+  }
+}

package/src/__smoke__/discovery.smoke.ts

@@ -0,0 +1,66 @@
+/**
+ * Smoke test for ability discovery against a live WordPress site.
+ *
+ * Not a unit test — this hits the network. Run manually with:
+ *
+ *   WP_BASE_URL=https://your-site.com/wp-json \
+ *   WP_BEARER=eyJhbG... \
+ *   npx tsx packages/api-client/src/__smoke__/discovery.smoke.ts
+ *
+ * Verifies:
+ *   1. Discovery walks pages and produces a non-empty catalog
+ *   2. The catalog can be queried by name, category, namespace
+ *   3. The shape returned by the server matches AbilityDescriptor
+ *
+ * If the server requires no auth for /abilities, omit WP_BEARER.
+ */
+
+import { FetchTransport } from '../transports/fetch';
+import { WPNativeClient } from '../client';
+
+async function main(): Promise<void> {
+  const baseUrl = process.env['WP_BASE_URL'];
+  if (!baseUrl) {
+    throw new Error('WP_BASE_URL env var is required');
+  }
+
+  const bearer = process.env['WP_BEARER'];
+
+  const transport = new FetchTransport({
+    baseUrl,
+    ...(bearer
+      ? { getAuthHeaders: () => ({ Authorization: `Bearer ${bearer}` }) }
+      : {}),
+  });
+
+  const client = new WPNativeClient(transport);
+
+  console.log(`Discovering abilities at ${baseUrl}...`);
+  const catalog = await client.discover();
+
+  console.log(`Discovered ${catalog.size()} abilities.`);
+  console.log('First 10 names:');
+  for (const name of catalog.names().slice(0, 10)) {
+    console.log(`  - ${name}`);
+  }
+
+  const namespaces = new Set<string>();
+  for (const ability of catalog.all()) {
+    const slash = ability.name.indexOf('/');
+    if (slash > 0) {
+      namespaces.add(ability.name.slice(0, slash));
+    }
+  }
+  console.log(`\nNamespaces found: ${Array.from(namespaces).sort().join(', ')}`);
+
+  const categories = new Set<string>();
+  for (const ability of catalog.all()) {
+    categories.add(ability.category);
+  }
+  console.log(`Categories found: ${Array.from(categories).sort().join(', ')}`);
+}
+
+main().catch((err: unknown) => {
+  console.error('Smoke test failed:', err);
+  process.exitCode = 1;
+});

package/src/abilities/catalog.ts

@@ -0,0 +1,75 @@
+/**
+ * AbilityCatalog — in-memory index of a WordPress site's ability registry.
+ *
+ * Built once at app startup via WPNativeClient.discover(). Provides O(1)
+ * lookup by ability name plus convenience accessors for filtering by
+ * category / namespace.
+ *
+ * The catalog is the source of truth for "what can this site do?" —
+ * shell screens consult it to decide which ability to call for which
+ * UI slot, consumers query it to feature-detect, and the client uses
+ * it to fail fast when execute() is called with an unknown ability.
+ */
+
+import type { AbilityDescriptor } from './types';
+
+export class AbilityCatalog {
+  private readonly byName: Map<string, AbilityDescriptor>;
+
+  constructor(abilities: readonly AbilityDescriptor[]) {
+    this.byName = new Map(abilities.map((a) => [a.name, a]));
+  }
+
+  /**
+   * Get a single ability descriptor by name.
+   * Returns undefined if the ability is not registered on this site.
+   */
+  get(name: string): AbilityDescriptor | undefined {
+    return this.byName.get(name);
+  }
+
+  /**
+   * Whether the given ability is registered on this site.
+   */
+  has(name: string): boolean {
+    return this.byName.has(name);
+  }
+
+  /**
+   * All registered ability names, in catalog order.
+   */
+  names(): string[] {
+    return Array.from(this.byName.keys());
+  }
+
+  /**
+   * All registered abilities.
+   */
+  all(): AbilityDescriptor[] {
+    return Array.from(this.byName.values());
+  }
+
+  /**
+   * Abilities filtered by category slug.
+   */
+  byCategory(category: string): AbilityDescriptor[] {
+    return this.all().filter((a) => a.category === category);
+  }
+
+  /**
+   * Abilities whose name starts with the given namespace prefix.
+   *
+   * Example: catalog.byNamespace('wp-native') returns all wp-native/* abilities.
+   */
+  byNamespace(namespace: string): AbilityDescriptor[] {
+    const prefix = `${namespace}/`;
+    return this.all().filter((a) => a.name.startsWith(prefix));
+  }
+
+  /**
+   * Total number of abilities in the catalog.
+   */
+  size(): number {
+    return this.byName.size;
+  }
+}

package/src/abilities/discovery.ts

@@ -0,0 +1,111 @@
+/**
+ * Abilities discovery — walks /wp-abilities/v1/abilities and builds a catalog.
+ *
+ * The Abilities REST API is paginated. discoverAbilities() loops through
+ * all pages and returns a fully-populated AbilityCatalog. For sites with
+ * hundreds of abilities this is a few sequential requests at startup;
+ * the catalog is then cached in memory for the app session.
+ */
+
+import type { Transport } from '../transports/types';
+import { AbilityCatalog } from './catalog';
+import type {
+  AbilityDescriptor,
+  AbilityListParams,
+  AbilityCategory,
+} from './types';
+
+const DEFAULT_PER_PAGE = 100;
+const ABILITIES_PATH = 'wp-abilities/v1/abilities';
+const CATEGORIES_PATH = 'wp-abilities/v1/categories';
+
+/**
+ * Fetch a single page of abilities.
+ *
+ * Returns the items only — pagination is driven by the discovery loop.
+ */
+export async function fetchAbilitiesPage(
+  transport: Transport,
+  params: AbilityListParams = {},
+): Promise<AbilityDescriptor[]> {
+  const query = new URLSearchParams();
+  query.set('per_page', String(params.perPage ?? DEFAULT_PER_PAGE));
+  query.set('page', String(params.page ?? 1));
+  if (params.category) {
+    query.set('category', params.category);
+  }
+
+  return transport.request<AbilityDescriptor[]>({
+    path: `${ABILITIES_PATH}?${query.toString()}`,
+    method: 'GET',
+  });
+}
+
+/**
+ * Fetch one ability descriptor by name.
+ *
+ * Useful for refreshing a single ability's schema without re-discovering
+ * the whole catalog.
+ */
+export async function fetchAbility(
+  transport: Transport,
+  name: string,
+): Promise<AbilityDescriptor> {
+  return transport.request<AbilityDescriptor>({
+    path: `${ABILITIES_PATH}/${encodeURIComponent(name)}`,
+    method: 'GET',
+  });
+}
+
+/**
+ * Fetch all available ability categories.
+ */
+export async function fetchAbilityCategories(
+  transport: Transport,
+): Promise<AbilityCategory[]> {
+  return transport.request<AbilityCategory[]>({
+    path: CATEGORIES_PATH,
+    method: 'GET',
+  });
+}
+
+/**
+ * Discover all abilities on a WordPress site and return a populated catalog.
+ *
+ * Walks pages until an empty page is returned. The Abilities API caps
+ * `per_page` at 100, so a site with N abilities resolves in ⌈N / 100⌉ requests.
+ *
+ * Optionally filter by category — useful when an app only cares about a
+ * subset of the surface (e.g. only `wp-native/*` abilities for the auth
+ * bootstrap flow).
+ */
+export async function discoverAbilities(
+  transport: Transport,
+  options: { category?: string; perPage?: number } = {},
+): Promise<AbilityCatalog> {
+  const perPage = options.perPage ?? DEFAULT_PER_PAGE;
+  const all: AbilityDescriptor[] = [];
+  let page = 1;
+
+  while (true) {
+    const params: AbilityListParams = { page, perPage };
+    if (options.category !== undefined) {
+      params.category = options.category;
+    }
+    const items = await fetchAbilitiesPage(transport, params);
+
+    if (items.length === 0) {
+      break;
+    }
+
+    all.push(...items);
+
+    if (items.length < perPage) {
+      break;
+    }
+
+    page += 1;
+  }
+
+  return new AbilityCatalog(all);
+}

package/src/abilities/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Public surface for the abilities subsystem.
+ */
+
+export { AbilityCatalog } from './catalog';
+export {
+  discoverAbilities,
+  fetchAbilitiesPage,
+  fetchAbility,
+  fetchAbilityCategories,
+} from './discovery';
+export type {
+  AbilityDescriptor,
+  AbilityCategory,
+  AbilityExecutionResponse,
+  AbilityListPage,
+  AbilityListParams,
+} from './types';

package/src/abilities/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Type definitions for the WordPress Abilities API REST surface.
+ *
+ * Mirrors the response shapes documented at:
+ *   GET /wp-abilities/v1/abilities
+ *   GET /wp-abilities/v1/abilities/{name}
+ *   POST /wp-abilities/v1/abilities/{name}/run
+ *
+ * These types describe the wire format. They are intentionally permissive
+ * about ability-specific input/output (modeled as `unknown`) because the
+ * universal client can't know each ability's schema at compile time —
+ * codegen from `input_schema` / `output_schema` is a post-v0.1 concern.
+ */
+
+/**
+ * A single ability as returned by the catalog endpoints.
+ */
+export interface AbilityDescriptor {
+  /**
+   * Unique identifier, namespaced. Examples:
+   *   wp/post.list
+   *   wp-native/auth-login
+   *   extrachill/artist.get
+   */
+  name: string;
+
+  /** Human-readable display label. */
+  label: string;
+
+  /** Longer description of what the ability does. */
+  description: string;
+
+  /**
+   * Category slug. Categories group related abilities for UI / discovery.
+   * Validated server-side against /^[a-z0-9]+(?:-[a-z0-9]+)*$/ — no slashes.
+   */
+  category: string;
+
+  /**
+   * JSON Schema describing the shape of the `input` argument expected by
+   * POST /abilities/{name}/run. May be an empty object for nullary abilities.
+   */
+  input_schema: Record<string, unknown>;
+
+  /**
+   * JSON Schema describing the shape of `result` returned by /run.
+   */
+  output_schema: Record<string, unknown>;
+
+  /**
+   * Meta information attached to the ability registration.
+   */
+  meta?: {
+    annotations?: Record<string, unknown> | boolean | null;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * An ability category as returned by GET /wp-abilities/v1/categories.
+ */
+export interface AbilityCategory {
+  slug: string;
+  label: string;
+  description: string;
+}
+
+/**
+ * Successful response from POST /wp-abilities/v1/abilities/{name}/run.
+ *
+ * The actual `result` shape is ability-specific; consumers narrow with
+ * a type parameter at the `client.execute<TResult>()` call site.
+ */
+export interface AbilityExecutionResponse<TResult = unknown> {
+  result: TResult;
+}
+
+/**
+ * Pagination wrapper. The Abilities REST API uses standard WP REST
+ * paginated lists — total count comes in the `X-WP-Total` header.
+ */
+export interface AbilityListPage {
+  items: AbilityDescriptor[];
+  totalItems: number;
+  totalPages: number;
+}
+
+/**
+ * Optional filters for catalog listing.
+ */
+export interface AbilityListParams {
+  /** Filter by category slug. */
+  category?: string;
+  /** Page number (1-indexed). Default: 1. */
+  page?: number;
+  /** Items per page. Server max is typically 100. Default: 50. */
+  perPage?: number;
+}