wp-native-client 0.0.1 → 0.0.2

package/README.md

@@ -1,41 +1,94 @@
 # wp-native-client
 
-Universal WordPress client built on the Abilities API.
+Universal WordPress client built on the [Abilities API](https://make.wordpress.org/core/). Discovery + execution. Works in React Native apps, Gutenberg blocks, and Node scripts — one client, three transports, one ability surface.
 
-**Status:** scaffold only. Implementation lands in M3 (see [ROADMAP](../../docs/ROADMAP.md)).
+## Install
 
-## What this package will provide
+```bash
+# React Native or Node
+npm install wp-native-client
 
-- `WPNativeClient` — single universal client, no subclasses
-- `discoverAbilities()` — fetches the site's ability catalog
-- `execute(abilityName, args)` — invokes any ability by name
-- `AuthTransport` — token lifecycle (load / save / refresh / clear)
-- `WpApiFetchTransport` — adapter for `@wordpress/api-fetch` (Gutenberg blocks)
-- *(post-v0.1)* `generateTypes()` — CLI tool to codegen TypeScript types from ability JSON schemas
+# Gutenberg blocks — also import the /wordpress subpath (see below)
+npm install wp-native-client
+```
 
-## The mental model
+No peer dependencies. The main entry point uses plain `fetch`. The `/wordpress` subpath entry wraps `@wordpress/api-fetch` for block contexts.
 
-The client doesn't know what abilities exist on a given WordPress site. **It asks.** The site is the source of truth, always current, self-describing.
+## Quick start
 
 ```ts
-import { WPNativeClient, AuthTransport } from 'wp-native-client';
+import { WPNativeClient, AuthFetchTransport } from 'wp-native-client';
 
-const client = new WPNativeClient({
-  baseUrl: 'https://extrachill.com/wp-json',
-  transport: new AuthTransport({ /* ... */ }),
+const transport = new AuthFetchTransport({
+  baseUrl: 'https://example.com/wp-json',
+  getDeviceId: () => 'your-uuid-v4',
+  loadTokens: async () => null,
+  saveTokens: async () => {},
+  clearTokens: async () => {},
+  onAuthFailure: () => console.log('session expired'),
 });
 
-// Discovery happens once at startup
-await client.discoverAbilities();
+await transport.initialize();
+
+const client = new WPNativeClient(transport);
+
+// Discovery — fetches the site's ability catalog
+await client.discover();
+
+// Execution — call any ability by name
+const me = await client.execute('wp-native/auth-me');
+const posts = await client.execute('wp/post.list', { per_page: 20 });
+```
+
+### Three transports
+
+| Transport | Use when | Import |
+|---|---|---|
+| **`AuthFetchTransport`** | React Native apps, Node scripts — manages token lifecycle (load, save, refresh, clear) | `wp-native-client` |
+| **`FetchTransport`** | Unauthenticated or externally-managed auth | `wp-native-client` |
+| **`WpApiFetchTransport`** | Gutenberg blocks — wraps `@wordpress/api-fetch`, nonce handling by WP core | `wp-native-client/wordpress` |
 
-// From there, anything any plugin registered is callable
-const posts    = await client.execute('wp/post.list', { per_page: 20 });
-const artist   = await client.execute('extrachill/artist.get', { id: 42 });
-const calendar = await client.execute('extrachill/event.calendar', { venue: 'continental-club' });
+```ts
+// Gutenberg block example
+import { WPNativeClient } from 'wp-native-client';
+import { WpApiFetchTransport } from 'wp-native-client/wordpress';
+import apiFetch from '@wordpress/api-fetch';
+
+const client = new WPNativeClient(new WpApiFetchTransport(apiFetch));
+await client.discover();
+const posts = await client.execute('wp/post.list', { per_page: 10 });
 ```
 
-No hand-typed wrappers. No per-site subclasses. No drift between client and server.
+## Public API summary
+
+### Client
+
+- **`WPNativeClient`** — the universal client. Wraps a transport, exposes `discover()`, `execute()`, `executeUnchecked()`, `describe()`, `catalog`.
+- **`WPNativeClientConfig`** — optional config (`validateAbilityNames`).
+
+### Transports
+
+- **`AuthFetchTransport`** — authenticated fetch with automatic token refresh and 401 retry.
+- **`FetchTransport`** — plain fetch, no auth.
+- **`WpApiFetchTransport`** — wraps `@wordpress/api-fetch` for block contexts. Separate entry point: `wp-native-client/wordpress`.
+- **`ApiError`** — structured error with `code`, `message`, `status`.
+
+### Abilities
+
+- **`discoverAbilities(transport, filter?)`** — walk the Abilities API, return an `AbilityCatalog`.
+- **`AbilityCatalog`** — in-memory lookup of ability descriptors by name.
+- **`AbilityDescriptor`** — metadata for a single ability (name, category, input/output schemas).
+
+### Types
+
+- **`StoredTokens`** — `{ accessToken, refreshToken, accessExpiresAt }` (expiry is a Unix timestamp in seconds).
+- **`Transport`**, **`TransportRequest`**, **`TransportResponse`** — transport interface contracts.
+- **`AuthFetchTransportConfig`**, **`FetchTransportConfig`** — transport configuration shapes.
+
+## Broader project
+
+wp-native-client is the abilities client layer of [wp-native](https://github.com/chubes4/wp-native) — an open-source framework for turning WordPress sites into real native apps. See the [main repo](https://github.com/chubes4/wp-native) for the shell, the auth plugin, and the full documentation.
 
-## Why not a typed client per site?
+## License
 
-See the [ROADMAP](../../docs/ROADMAP.md#the-principle). Per-site typed clients defeat the purpose of a generic framework — they'd require every consumer of every WordPress site to ship their own `@whatever/api-client`. Abilities discovery is the only pattern that delivers on "any WordPress site."
+GPL-2.0-or-later — [github.com/chubes4/wp-native](https://github.com/chubes4/wp-native)

package/dist/abilities/discovery.d.ts

@@ -22,6 +22,10 @@ export declare function fetchAbilitiesPage(transport: Transport, params?: Abilit
  * the whole catalog.
  */
 export declare function fetchAbility(transport: Transport, name: string): Promise<AbilityDescriptor>;
+/**
+ * Encode an ability name without escaping its namespace separator.
+ */
+export declare function encodeAbilityName(name: string): string;
 /**
  * Fetch all available ability categories.
  */

package/dist/abilities/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/abilities/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EAChB,MAAM,SAAS,CAAC;AAMjB;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,SAAS,EACpB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAY9B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,CAAC,CAK5B;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,eAAe,EAAE,CAAC,CAK5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,OAAO,CAAC,cAAc,CAAC,CA0BzB"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/abilities/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EAChB,MAAM,SAAS,CAAC;AAMjB;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,SAAS,EACpB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAY9B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,CAAC,CAK5B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,eAAe,EAAE,CAAC,CAK5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,OAAO,CAAC,cAAc,CAAC,CA0BzB"}

package/dist/abilities/discovery.js

@@ -35,10 +35,16 @@ export async function fetchAbilitiesPage(transport, params = {}) {
  */
 export async function fetchAbility(transport, name) {
     return transport.request({
-        path: `${ABILITIES_PATH}/${encodeURIComponent(name)}`,
+        path: `${ABILITIES_PATH}/${encodeAbilityName(name)}`,
         method: 'GET',
     });
 }
+/**
+ * Encode an ability name without escaping its namespace separator.
+ */
+export function encodeAbilityName(name) {
+    return name.split('/').map(encodeURIComponent).join('/');
+}
 /**
  * Fetch all available ability categories.
  */

package/dist/abilities/discovery.js.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/abilities/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAO3C,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,cAAc,GAAG,2BAA2B,CAAC;AACnD,MAAM,eAAe,GAAG,4BAA4B,CAAC;AAErD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAoB,EACpB,SAA4B,EAAE;IAE9B,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,CAAC;IAClE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5C,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,SAAS,CAAC,OAAO,CAAsB;QAC5C,IAAI,EAAE,GAAG,cAAc,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE;QAC7C,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAAoB,EACpB,IAAY;IAEZ,OAAO,SAAS,CAAC,OAAO,CAAoB;QAC1C,IAAI,EAAE,GAAG,cAAc,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE;QACrD,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,SAAoB;IAEpB,OAAO,SAAS,CAAC,OAAO,CAAoB;QAC1C,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAoB,EACpB,UAAmD,EAAE;IAErD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACpD,MAAM,GAAG,GAAwB,EAAE,CAAC;IACpC,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,MAAM,GAAsB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACnC,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACrC,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAE1D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM;QACR,CAAC;QAED,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;QAEnB,IAAI,KAAK,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;YAC3B,MAAM;QACR,CAAC;QAED,IAAI,IAAI,CAAC,CAAC;IACZ,CAAC;IAED,OAAO,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/abilities/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAO3C,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,cAAc,GAAG,2BAA2B,CAAC;AACnD,MAAM,eAAe,GAAG,4BAA4B,CAAC;AAErD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAoB,EACpB,SAA4B,EAAE;IAE9B,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,CAAC;IAClE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5C,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,SAAS,CAAC,OAAO,CAAsB;QAC5C,IAAI,EAAE,GAAG,cAAc,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE;QAC7C,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,SAAoB,EACpB,IAAY;IAEZ,OAAO,SAAS,CAAC,OAAO,CAAoB;QAC1C,IAAI,EAAE,GAAG,cAAc,IAAI,iBAAiB,CAAC,IAAI,CAAC,EAAE;QACpD,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,SAAoB;IAEpB,OAAO,SAAS,CAAC,OAAO,CAAoB;QAC1C,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,KAAK;KACd,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAoB,EACpB,UAAmD,EAAE;IAErD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IACpD,MAAM,GAAG,GAAwB,EAAE,CAAC;IACpC,IAAI,IAAI,GAAG,CAAC,CAAC;IAEb,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,MAAM,GAAsB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACnC,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACrC,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAE1D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM;QACR,CAAC;QAED,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;QAEnB,IAAI,KAAK,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;YAC3B,MAAM;QACR,CAAC;QAED,IAAI,IAAI,CAAC,CAAC;IACZ,CAAC;IAED,OAAO,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC"}

package/dist/abilities/types.d.ts

@@ -4,7 +4,7 @@
  * Mirrors the response shapes documented at:
  *   GET /wp-abilities/v1/abilities
  *   GET /wp-abilities/v1/abilities/{name}
- *   POST /wp-abilities/v1/abilities/{name}/run
+ *   GET|POST|DELETE /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
@@ -33,7 +33,7 @@ export interface AbilityDescriptor {
     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.
+     * /abilities/{name}/run. May be an empty object for nullary abilities.
      */
     input_schema: Record<string, unknown>;
     /**
@@ -57,10 +57,10 @@ export interface AbilityCategory {
     description: string;
 }
 /**
- * Successful response from POST /wp-abilities/v1/abilities/{name}/run.
+ * Legacy wrapped execution response type retained for source compatibility.
+ * WordPress currently returns the ability result directly from `/run`.
  *
- * The actual `result` shape is ability-specific; consumers narrow with
- * a type parameter at the `client.execute<TResult>()` call site.
+ * @deprecated Use the result type passed to `client.execute<TResult>()`.
  */
 export interface AbilityExecutionResponse<TResult = unknown> {
     result: TResult;

package/dist/abilities/types.js

@@ -4,7 +4,7 @@
  * Mirrors the response shapes documented at:
  *   GET /wp-abilities/v1/abilities
  *   GET /wp-abilities/v1/abilities/{name}
- *   POST /wp-abilities/v1/abilities/{name}/run
+ *   GET|POST|DELETE /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

package/dist/client.d.ts

@@ -48,6 +48,7 @@ export declare class WPNativeClient {
     private readonly transport;
     private readonly config;
     private _catalog;
+    private readonly descriptors;
     constructor(transport: Transport, config?: WPNativeClientConfig);
     /**
      * Walk the Abilities API and populate the in-memory catalog.
@@ -81,11 +82,8 @@ export declare class WPNativeClient {
      * 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.
+     * enabled), then sent to /wp-abilities/v1/abilities/{name}/run using the
+     * HTTP method required by the ability annotations.
      *
      * Throws:
      *   - Error    if the ability is not in the catalog (and validation enabled)
@@ -101,6 +99,7 @@ export declare class WPNativeClient {
      * the call site.
      */
     executeUnchecked<TResult = unknown, TInput = unknown>(name: string, input?: TInput): Promise<TResult>;
+    private executeDescriptor;
     /**
      * Get a single ability descriptor from the catalog.
      * Returns undefined if not registered or catalog not loaded.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,mBAAmB,CAAC;AAI3B,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAA+B;gBAEnC,SAAS,EAAE,SAAS,EAAE,MAAM,GAAE,oBAAyB;IAOnE;;;;;;;;;OASG;IACG,QAAQ,CAAC,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAU5E;;;;OAIG;IACH,IAAI,OAAO,IAAI,cAAc,CAO5B;IAED;;;OAGG;IACH,aAAa,IAAI,cAAc,GAAG,IAAI;IAItC;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EAC/C,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IAcnB;;;;;;;OAOG;IACG,gBAAgB,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EACxD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IAwBnB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;CAGtD"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EACV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAI3B,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwC;gBAExD,SAAS,EAAE,SAAS,EAAE,MAAM,GAAE,oBAAyB;IAOnE;;;;;;;;;OASG;IACG,QAAQ,CAAC,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAa5E;;;;OAIG;IACH,IAAI,OAAO,IAAI,cAAc,CAO5B;IAED;;;OAGG;IACH,aAAa,IAAI,cAAc,GAAG,IAAI;IAItC;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;;;;;;;;;OAUG;IACG,OAAO,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EAC/C,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IAoBnB;;;;;;;OAOG;IACG,gBAAgB,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,EACxD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;YAML,iBAAiB;IAgC/B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;CAGtD"}

package/dist/client.js

@@ -27,13 +27,13 @@
  *   const posts = await client.execute<Post[]>('wp/post.list', { per_page: 20 });
  *   const me    = await client.execute<User>('wp-native/user.me');
  */
-import { ApiError } from './transports/fetch';
-import { discoverAbilities } from './abilities/discovery';
+import { discoverAbilities, encodeAbilityName, fetchAbility } from './abilities/discovery';
 const RUN_PATH_PREFIX = 'wp-abilities/v1/abilities';
 export class WPNativeClient {
     transport;
     config;
     _catalog = null;
+    descriptors = new Map();
     constructor(transport, config = {}) {
         this.transport = transport;
         this.config = {
@@ -57,6 +57,9 @@ export class WPNativeClient {
         }
         const catalog = await discoverAbilities(this.transport, filter);
         this._catalog = catalog;
+        for (const ability of catalog.all()) {
+            this.descriptors.set(ability.name, ability);
+        }
         return catalog;
     }
     /**
@@ -87,11 +90,8 @@ export class WPNativeClient {
      * 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.
+     * enabled), then sent to /wp-abilities/v1/abilities/{name}/run using the
+     * HTTP method required by the ability annotations.
      *
      * Throws:
      *   - Error    if the ability is not in the catalog (and validation enabled)
@@ -105,7 +105,12 @@ export class WPNativeClient {
                     `to bypass validation.`);
             }
         }
-        return this.executeUnchecked(name, input);
+        let descriptor = this._catalog?.get(name) ?? this.descriptors.get(name);
+        if (!descriptor) {
+            descriptor = await fetchAbility(this.transport, name);
+            this.descriptors.set(name, descriptor);
+        }
+        return this.executeDescriptor(descriptor, input);
     }
     /**
      * Execute an ability without checking the catalog.
@@ -116,20 +121,35 @@ export class WPNativeClient {
      * the call site.
      */
     async executeUnchecked(name, input) {
-        const path = `${RUN_PATH_PREFIX}/${encodeURIComponent(name)}/run`;
+        const descriptor = await fetchAbility(this.transport, name);
+        this.descriptors.set(name, descriptor);
+        return this.executeDescriptor(descriptor, input);
+    }
+    async executeDescriptor(descriptor, input) {
+        const annotations = descriptor.meta?.annotations;
+        const annotationMap = annotations && typeof annotations === 'object' ? annotations : {};
+        const method = annotationMap.readonly
+            ? 'GET'
+            : annotationMap.destructive && annotationMap.idempotent
+                ? 'DELETE'
+                : 'POST';
+        let path = `${RUN_PATH_PREFIX}/${encodeAbilityName(descriptor.name)}/run`;
         const body = {
             input: input === undefined ? null : input,
         };
-        const response = await this.transport.request({
+        if (method !== 'POST') {
+            const query = new URLSearchParams();
+            appendQueryValue(query, 'input', body.input);
+            const queryString = query.toString();
+            if (queryString) {
+                path += `?${queryString}`;
+            }
+        }
+        return this.transport.request({
             path,
-            method: 'POST',
-            body: body,
+            method,
+            ...(method === 'POST' ? { body: body } : {}),
         });
-        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.
@@ -139,4 +159,20 @@ export class WPNativeClient {
         return this._catalog?.get(name);
     }
 }
+function appendQueryValue(query, key, value) {
+    if (value === null || value === undefined) {
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => appendQueryValue(query, `${key}[${index}]`, item));
+        return;
+    }
+    if (typeof value === 'object') {
+        Object.entries(value).forEach(([childKey, childValue]) => {
+            appendQueryValue(query, `${key}[${childKey}]`, childValue);
+        });
+        return;
+    }
+    query.append(key, String(value));
+}
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wp-native-client",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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",

package/src/abilities/discovery.ts

@@ -52,11 +52,18 @@ export async function fetchAbility(
   name: string,
 ): Promise<AbilityDescriptor> {
   return transport.request<AbilityDescriptor>({
-    path: `${ABILITIES_PATH}/${encodeURIComponent(name)}`,
+    path: `${ABILITIES_PATH}/${encodeAbilityName(name)}`,
     method: 'GET',
   });
 }
 
+/**
+ * Encode an ability name without escaping its namespace separator.
+ */
+export function encodeAbilityName(name: string): string {
+  return name.split('/').map(encodeURIComponent).join('/');
+}
+
 /**
  * Fetch all available ability categories.
  */

package/src/abilities/types.ts

@@ -4,7 +4,7 @@
  * Mirrors the response shapes documented at:
  *   GET /wp-abilities/v1/abilities
  *   GET /wp-abilities/v1/abilities/{name}
- *   POST /wp-abilities/v1/abilities/{name}/run
+ *   GET|POST|DELETE /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
@@ -38,7 +38,7 @@ export interface AbilityDescriptor {
 
   /**
    * JSON Schema describing the shape of the `input` argument expected by
-   * POST /abilities/{name}/run. May be an empty object for nullary abilities.
+   * /abilities/{name}/run. May be an empty object for nullary abilities.
    */
   input_schema: Record<string, unknown>;
 
@@ -66,10 +66,10 @@ export interface AbilityCategory {
 }
 
 /**
- * Successful response from POST /wp-abilities/v1/abilities/{name}/run.
+ * Legacy wrapped execution response type retained for source compatibility.
+ * WordPress currently returns the ability result directly from `/run`.
  *
- * The actual `result` shape is ability-specific; consumers narrow with
- * a type parameter at the `client.execute<TResult>()` call site.
+ * @deprecated Use the result type passed to `client.execute<TResult>()`.
  */
 export interface AbilityExecutionResponse<TResult = unknown> {
   result: TResult;

package/src/client.ts

@@ -29,12 +29,10 @@
  */
 
 import type { Transport } from './transports/types';
-import { ApiError } from './transports/fetch';
 import { AbilityCatalog } from './abilities/catalog';
-import { discoverAbilities } from './abilities/discovery';
+import { discoverAbilities, encodeAbilityName, fetchAbility } from './abilities/discovery';
 import type {
   AbilityDescriptor,
-  AbilityExecutionResponse,
 } from './abilities/types';
 
 const RUN_PATH_PREFIX = 'wp-abilities/v1/abilities';
@@ -58,6 +56,7 @@ export class WPNativeClient {
   private readonly transport: Transport;
   private readonly config: Required<WPNativeClientConfig>;
   private _catalog: AbilityCatalog | null = null;
+  private readonly descriptors = new Map<string, AbilityDescriptor>();
 
   constructor(transport: Transport, config: WPNativeClientConfig = {}) {
     this.transport = transport;
@@ -83,6 +82,9 @@ export class WPNativeClient {
     }
     const catalog = await discoverAbilities(this.transport, filter);
     this._catalog = catalog;
+    for (const ability of catalog.all()) {
+      this.descriptors.set(ability.name, ability);
+    }
     return catalog;
   }
 
@@ -119,11 +121,8 @@ export class WPNativeClient {
    * 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.
+   * enabled), then sent to /wp-abilities/v1/abilities/{name}/run using the
+   * HTTP method required by the ability annotations.
    *
    * Throws:
    *   - Error    if the ability is not in the catalog (and validation enabled)
@@ -143,7 +142,13 @@ export class WPNativeClient {
       }
     }
 
-    return this.executeUnchecked<TResult, TInput>(name, input);
+    let descriptor = this._catalog?.get(name) ?? this.descriptors.get(name);
+    if (!descriptor) {
+      descriptor = await fetchAbility(this.transport, name);
+      this.descriptors.set(name, descriptor);
+    }
+
+    return this.executeDescriptor<TResult, TInput>(descriptor, input);
   }
 
   /**
@@ -158,27 +163,41 @@ export class WPNativeClient {
     name: string,
     input?: TInput,
   ): Promise<TResult> {
-    const path = `${RUN_PATH_PREFIX}/${encodeURIComponent(name)}/run`;
+    const descriptor = await fetchAbility(this.transport, name);
+    this.descriptors.set(name, descriptor);
+    return this.executeDescriptor<TResult, TInput>(descriptor, input);
+  }
+
+  private async executeDescriptor<TResult, TInput>(
+    descriptor: AbilityDescriptor,
+    input?: TInput,
+  ): Promise<TResult> {
+    const annotations = descriptor.meta?.annotations;
+    const annotationMap = annotations && typeof annotations === 'object' ? annotations : {};
+    const method = annotationMap.readonly
+      ? 'GET'
+      : annotationMap.destructive && annotationMap.idempotent
+        ? 'DELETE'
+        : 'POST';
+    let path = `${RUN_PATH_PREFIX}/${encodeAbilityName(descriptor.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,
-      );
+    if (method !== 'POST') {
+      const query = new URLSearchParams();
+      appendQueryValue(query, 'input', body.input);
+      const queryString = query.toString();
+      if (queryString) {
+        path += `?${queryString}`;
+      }
     }
 
-    return response.result;
+    return this.transport.request<TResult>({
+      path,
+      method,
+      ...(method === 'POST' ? { body: body as Record<string, unknown> } : {}),
+    });
   }
 
   /**
@@ -189,3 +208,27 @@ export class WPNativeClient {
     return this._catalog?.get(name);
   }
 }
+
+function appendQueryValue(
+  query: URLSearchParams,
+  key: string,
+  value: unknown,
+): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => appendQueryValue(query, `${key}[${index}]`, item));
+    return;
+  }
+
+  if (typeof value === 'object') {
+    Object.entries(value).forEach(([childKey, childValue]) => {
+      appendQueryValue(query, `${key}[${childKey}]`, childValue);
+    });
+    return;
+  }
+
+  query.append(key, String(value));
+}