wp-native-client 0.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+GNU GENERAL PUBLIC LICENSE
+Version 2, June 1991
+
+Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Full license text: https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt

package/README.md

@@ -0,0 +1,41 @@
+# wp-native-client
+
+Universal WordPress client built on the Abilities API.
+
+**Status:** scaffold only. Implementation lands in M3 (see [ROADMAP](../../docs/ROADMAP.md)).
+
+## What this package will provide
+
+- `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
+
+## The mental model
+
+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.
+
+```ts
+import { WPNativeClient, AuthTransport } from 'wp-native-client';
+
+const client = new WPNativeClient({
+  baseUrl: 'https://extrachill.com/wp-json',
+  transport: new AuthTransport({ /* ... */ }),
+});
+
+// Discovery happens once at startup
+await client.discoverAbilities();
+
+// 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' });
+```
+
+No hand-typed wrappers. No per-site subclasses. No drift between client and server.
+
+## Why not a typed client per site?
+
+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."

package/dist/abilities/catalog.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare class AbilityCatalog {
+    private readonly byName;
+    constructor(abilities: readonly AbilityDescriptor[]);
+    /**
+     * Get a single ability descriptor by name.
+     * Returns undefined if the ability is not registered on this site.
+     */
+    get(name: string): AbilityDescriptor | undefined;
+    /**
+     * Whether the given ability is registered on this site.
+     */
+    has(name: string): boolean;
+    /**
+     * All registered ability names, in catalog order.
+     */
+    names(): string[];
+    /**
+     * All registered abilities.
+     */
+    all(): AbilityDescriptor[];
+    /**
+     * Abilities filtered by category slug.
+     */
+    byCategory(category: string): AbilityDescriptor[];
+    /**
+     * Abilities whose name starts with the given namespace prefix.
+     *
+     * Example: catalog.byNamespace('wp-native') returns all wp-native/* abilities.
+     */
+    byNamespace(namespace: string): AbilityDescriptor[];
+    /**
+     * Total number of abilities in the catalog.
+     */
+    size(): number;
+}
+//# sourceMappingURL=catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/abilities/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAE5C,SAAS,EAAE,SAAS,iBAAiB,EAAE;IAInD;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAIhD;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,KAAK,IAAI,MAAM,EAAE;IAIjB;;OAEG;IACH,GAAG,IAAI,iBAAiB,EAAE;IAI1B;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAIjD;;;;OAIG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAKnD;;OAEG;IACH,IAAI,IAAI,MAAM;CAGf"}

package/dist/abilities/catalog.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+export class AbilityCatalog {
+    byName;
+    constructor(abilities) {
+        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) {
+        return this.byName.get(name);
+    }
+    /**
+     * Whether the given ability is registered on this site.
+     */
+    has(name) {
+        return this.byName.has(name);
+    }
+    /**
+     * All registered ability names, in catalog order.
+     */
+    names() {
+        return Array.from(this.byName.keys());
+    }
+    /**
+     * All registered abilities.
+     */
+    all() {
+        return Array.from(this.byName.values());
+    }
+    /**
+     * Abilities filtered by category slug.
+     */
+    byCategory(category) {
+        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) {
+        const prefix = `${namespace}/`;
+        return this.all().filter((a) => a.name.startsWith(prefix));
+    }
+    /**
+     * Total number of abilities in the catalog.
+     */
+    size() {
+        return this.byName.size;
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/dist/abilities/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/abilities/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,OAAO,cAAc;IACR,MAAM,CAAiC;IAExD,YAAY,SAAuC;QACjD,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,GAAG;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,QAAgB;QACzB,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;IAC3D,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,SAAiB;QAC3B,MAAM,MAAM,GAAG,GAAG,SAAS,GAAG,CAAC;QAC/B,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED;;OAEG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;CACF"}

package/dist/abilities/discovery.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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';
+/**
+ * Fetch a single page of abilities.
+ *
+ * Returns the items only — pagination is driven by the discovery loop.
+ */
+export declare function fetchAbilitiesPage(transport: Transport, params?: AbilityListParams): Promise<AbilityDescriptor[]>;
+/**
+ * Fetch one ability descriptor by name.
+ *
+ * Useful for refreshing a single ability's schema without re-discovering
+ * the whole catalog.
+ */
+export declare function fetchAbility(transport: Transport, name: string): Promise<AbilityDescriptor>;
+/**
+ * Fetch all available ability categories.
+ */
+export declare function fetchAbilityCategories(transport: Transport): Promise<AbilityCategory[]>;
+/**
+ * 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 declare function discoverAbilities(transport: Transport, options?: {
+    category?: string;
+    perPage?: number;
+}): Promise<AbilityCatalog>;
+//# sourceMappingURL=discovery.d.ts.map

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

@@ -0,0 +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"}

package/dist/abilities/discovery.js

@@ -0,0 +1,82 @@
+/**
+ * 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 { AbilityCatalog } from './catalog';
+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, params = {}) {
+    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({
+        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, name) {
+    return transport.request({
+        path: `${ABILITIES_PATH}/${encodeURIComponent(name)}`,
+        method: 'GET',
+    });
+}
+/**
+ * Fetch all available ability categories.
+ */
+export async function fetchAbilityCategories(transport) {
+    return transport.request({
+        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, options = {}) {
+    const perPage = options.perPage ?? DEFAULT_PER_PAGE;
+    const all = [];
+    let page = 1;
+    while (true) {
+        const params = { 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);
+}
+//# sourceMappingURL=discovery.js.map

package/dist/abilities/discovery.js.map

@@ -0,0 +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"}

package/dist/abilities/index.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/abilities/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,wBAAwB,EACxB,eAAe,EACf,iBAAiB,GAClB,MAAM,SAAS,CAAC"}

package/dist/abilities/index.js

@@ -0,0 +1,6 @@
+/**
+ * Public surface for the abilities subsystem.
+ */
+export { AbilityCatalog } from './catalog';
+export { discoverAbilities, fetchAbilitiesPage, fetchAbility, fetchAbilityCategories, } from './discovery';
+//# sourceMappingURL=index.js.map

package/dist/abilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/abilities/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,GACvB,MAAM,aAAa,CAAC"}

package/dist/abilities/types.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/abilities/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IAEd,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtC;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEvC;;OAEG;IACH,IAAI,CAAC,EAAE;QACL,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC;QACvD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB,CAAC,OAAO,GAAG,OAAO;IACzD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/abilities/types.js

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

package/dist/abilities/types.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 { AbilityCatalog } from './abilities/catalog';
+import type { AbilityDescriptor } from './abilities/types';
+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 declare class WPNativeClient {
+    private readonly transport;
+    private readonly config;
+    private _catalog;
+    constructor(transport: Transport, config?: WPNativeClientConfig);
+    /**
+     * 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.
+     */
+    discover(options?: {
+        category?: string;
+    }): Promise<AbilityCatalog>;
+    /**
+     * The current catalog. Throws if discover() has not been called.
+     *
+     * Use catalogOrNull() if you want to feature-detect without throwing.
+     */
+    get catalog(): AbilityCatalog;
+    /**
+     * Non-throwing accessor for the catalog. Returns null if discover()
+     * has not been called.
+     */
+    catalogOrNull(): AbilityCatalog | null;
+    /**
+     * Whether discover() has populated the catalog.
+     */
+    hasCatalog(): boolean;
+    /**
+     * 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
+     */
+    execute<TResult = unknown, TInput = unknown>(name: string, input?: TInput): Promise<TResult>;
+    /**
+     * 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.
+     */
+    executeUnchecked<TResult = unknown, TInput = unknown>(name: string, input?: TInput): Promise<TResult>;
+    /**
+     * Get a single ability descriptor from the catalog.
+     * Returns undefined if not registered or catalog not loaded.
+     */
+    describe(name: string): AbilityDescriptor | undefined;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +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"}