@wootsup/yt-builder-mcp 0.2.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WootsUp / getimo productions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# @wootsup/yt-builder-mcp — YT Builder MCP for YOOtheme Pro (unofficial)
+
+> Drive your page builder via MCP. Built for YOOtheme Pro 4.0+ — connect **Claude Desktop**, **Cursor**, **Continue**, **Zed**, **Cline**, or **Roo Code** in one command.
+
+> Independent third-party project. YOOtheme® is a registered trademark of YOOtheme GmbH
+> ([yootheme.com](https://yootheme.com)). YT Builder MCP is built by WootsUp (getimo
+> productions) and is not affiliated with, endorsed by, or sponsored by YOOtheme.
+> The integration uses YOOtheme Pro's public extension points.
+
+**License:** MIT
+**Status:** Pre-alpha — under active development.
+
+---
+
+## Quick start
+
+```bash
+# 1. Install the WordPress plugin (yt-builder-mcp).
+#    See https://wootsup.com/products/yt-builder-mcp
+
+# 2. Generate a Bearer key in
+#    wp-admin → Tools → "YT Builder MCP" → Bearer Keys → Generate New Key.
+#    Key format: ytb_(live|test)_<payloadB64Url>.<sigB64Url>
+#    The key is shown ONCE — copy it now; it cannot be recovered later.
+
+# 3. Run the wizard to configure your AI client(s):
+npx -y @wootsup/yt-builder-mcp setup
+
+# 4. (Optional) Install the bundled agent skill:
+npx -y @wootsup/yt-builder-mcp install-skill
+
+# 5. Restart your AI client.
+```
+
+The wizard prompts for:
+
+1. Your WordPress site URL.
+2. The Bearer key you just generated.
+3. Which AI client(s) to configure (multi-select).
+
+It probes `/wp-json/yt-builder-mcp/v1/health` to confirm the
+plugin is reachable, `/etag` to validate the Bearer key, then writes
+the MCP server entry into each selected client's config file. After
+restart you should see the new tools prefixed with `yootheme_builder_*`.
+
+## Supported AI clients (6)
+
+The wizard auto-detects and configures the following clients:
+
+| Client | Config path | Notes |
+|--------|-------------|-------|
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) | DXT bundle also supported (see below) |
+| Cursor | `~/.cursor/mcp.json` | |
+| Continue | `~/.continue/config.json` | |
+| Zed | `~/.config/zed/settings.json` | |
+| Cline | `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | VS Code extension |
+| Roo Code | same VS Code globalStorage path under `rooveterinaryinc.roo-cline` | VS Code extension |
+
+## Tool surface — gateway model
+
+The server registers **22 tools total**, but only **10 entries appear
+in `tools/list`** (well under Cursor's ~40-tool cap):
+
+- **2 direct top-level tools** (always in `tools/list`):
+  `yootheme_builder_health`, `yootheme_builder_diagnose` — the
+  "the gateway itself might be broken" escape hatch.
+- **7 essential forwarded tools** (always in `tools/list`): the most-
+  used reads and writes — `pages_list`, `get_etag`, `element_list`,
+  `element_add`, `element_update_settings`, `sources_list`,
+  `element_types_list`.
+- **1 gateway tool** (`yootheme_builder_advanced`): exposes the
+  remaining **12 advanced tools** behind a single entry. Call
+  `yootheme_builder_advanced({ tool: "<name>" })` for discovery
+  (returns the schema) or `({ tool, arguments })` to execute.
+- **12 advanced tools** dispatched via the gateway (page_get_layout,
+  page_get_schema, page_save, page_publish, element_get,
+  element_move, element_clone, element_delete,
+  element_get_binding, element_bind_source, element_unbind_source,
+  element_type_get_schema).
+
+Total: **21 domain tools + 1 gateway = 22**. Surface: **10 entries
+in tools/list**. See `skills/yootheme-builder/SKILL.md` for the
+full catalog and the 5 canonical workflows.
+
+## Tool catalogue — 21 domain tools
+
+| Domain     | Count | Tools                                                                                                                                                                |
+|------------|------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Health     |     2 | `health`, `diagnose`                                                                                                                                                |
+| Pages      |     6 | `pages_list`, `page_get_layout`, `page_get_schema`, `get_etag`, `page_save`, `page_publish`                                                                          |
+| Elements   |     7 | `element_list`, `element_get`, `element_add`, `element_update_settings`, `element_move`, `element_clone`, `element_delete`                                          |
+| Sources    |     4 | `sources_list`, `element_get_binding`, `element_bind_source`, `element_unbind_source`                                                                                |
+| Inspection |     2 | `element_types_list`, `element_type_get_schema`                                                                                                                      |
+
+All tool names are prefixed with `yootheme_builder_` at the MCP
+server boundary.
+
+## Subcommands
+
+```
+yt-builder-mcp setup            Interactive first-run wizard (default).
+yt-builder-mcp install-skill    Install the bundled agent skill.
+yt-builder-mcp --version, -v    Print package version.
+yt-builder-mcp --help, -h       Show usage.
+```
+
+### `install-skill` — bundled agent skill
+
+Copies the bundled `skills/yootheme-builder/` folder into
+`~/.claude/skills/` and appends a marker block to `~/AGENTS.md` so
+other AI clients pick it up automatically.
+
+`~/.claude/skills/` is the **universal marker path** recognised by
+Claude Desktop and (per the same convention as `@wootsup/mcp`) other
+AI clients that follow the `~/AGENTS.md` discovery protocol. The
+single location keeps the skill discoverable across every supported
+client without per-client write logic.
+
+The skill ships with the 5 canonical workflows (build hero, bind
+source, clone section, diagnose 401, add custom element) plus a
+21-tool auto-generated catalog appendix.
+
+## DXT bundle — Claude Desktop one-click install
+
+The repo includes a `manifest.json` and `scripts/build-dxt.js` that
+produces a `yt-builder-mcp.dxt` archive — the
+[Desktop Extension](https://github.com/anthropics/dxt) format used
+by Claude Desktop for one-click MCP installs. Build it from a
+source checkout:
+
+```bash
+npm run build:dxt
+# → ./yt-builder-mcp.dxt
+```
+
+Drop the `.dxt` file onto Claude Desktop's Extensions screen to
+install. The bundle includes the compiled `dist/`, the bundled
+skill, and `manifest.json`.
+
+## Environment variables
+
+When launched by an AI client (or directly):
+
+| Variable | Required? | Purpose |
+|----------|-----------|---------|
+| `YTB_MCP_WP_URL` | Yes | WordPress base URL (e.g. `https://example.com`). Trailing slash is stripped. |
+| `YTB_MCP_BEARER_TOKEN` | Yes | Bearer key from wp-admin. Format-checked client-side: must match `ytb_(live\|test)_<payload>.<sig>`. Do **not** prepend `Bearer ` — the MCP server adds it. |
+| `YTB_MCP_TIMEOUT_MS` | No | REST timeout (default 15000). |
+| `YTB_MCP_TEST_MODE` | No | `1` skips the stdio loop (smoke tests). |
+
+## Manual MCP config (no wizard)
+
+For users who don't want to run the wizard, paste this into your AI
+client's MCP config file:
+
+```json
+{
+  "mcpServers": {
+    "yootheme-builder": {
+      "command": "npx",
+      "args": ["-y", "@wootsup/yt-builder-mcp"],
+      "env": {
+        "YTB_MCP_WP_URL": "https://example.com",
+        "YTB_MCP_BEARER_TOKEN": "ytb_live_…"
+      }
+    }
+  }
+}
+```
+
+## Non-interactive CI usage
+
+For scripted / CI installs, pass the answers as flags and add
+`--non-interactive` to skip every prompt. Missing required flags
+exit with code `2` and a clear error to stderr:
+
+```bash
+npx -y @wootsup/yt-builder-mcp setup \
+  --non-interactive \
+  --client cursor --client claude-desktop \
+  --url https://dev.wootsup.com/wordpress \
+  --token "$YTB_TOKEN"
+```
+
+Supported flags:
+
+| Flag | Required? | Description |
+|------|-----------|-------------|
+| `--non-interactive` | Yes | Opt-in to non-interactive mode (no prompts). |
+| `--url <wp-url>` | Yes | WordPress base URL; trailing slash is stripped. |
+| `--token <bearer>` | Yes | Bearer key from wp-admin (do not prepend `Bearer `). |
+| `--client <id>` | Yes (≥1) | Client id; repeatable. Valid ids: `claude-desktop`, `cursor`, `zed`, `continue`, `cline`, `roo-code`. |
+
+The wizard still runs its plugin-health + auth probes and uses the
+exit codes documented in the table below — so CI can branch on the
+exit code to detect whether the install actually succeeded.
+
+## Exit codes (CLI)
+
+The CLI returns POSIX-style exit codes for scripting / CI:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Invalid input / unknown subcommand |
+| 2 | Health probe failed and user declined to continue (or install-skill failure) |
+| 3 | Auth probe failed and user declined to continue |
+| 4 | Write failed; configs rolled back |
+| 5 | Handshake failed; configs rolled back |
+| 99 | Unhandled fatal in dispatcher |
+| 130 | User cancelled (SIGINT) |
+
+## Documentation
+
+- [SKILL.md (bundled agent skill)](./skills/yootheme-builder/SKILL.md) — 5 canonical workflows, gateway model, tool catalog
+- [REST API Reference](https://github.com/wootsup/yt-builder-mcp/blob/main/docs/rest-api-reference.md)
+- [MCP Tool Reference](https://github.com/wootsup/yt-builder-mcp/blob/main/docs/mcp-tool-reference.md)
+
+## Repository
+
+https://github.com/wootsup/yt-builder-mcp

package/bin/yt-builder-mcp.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Entry point for `npx -y @wootsup/yt-builder-mcp`.
+ *
+ * Dispatch tree:
+ *   - `setup` / `install-skill` / `install` / `--version` / `-v` /
+ *     `--help` / `-h` / `help` → forward to `runCli()` in
+ *     `dist/setup-cli.js` (Wave G.7).
+ *   - no subcommand + interactive TTY → print a discoverability hint
+ *     (don't accidentally start MCP server).
+ *   - no subcommand + piped stdin/stdout → start the MCP stdio server
+ *     (this is what AI clients invoke).
+ *
+ * The `runCli` / MCP-server split keeps the interactive ergonomics nice
+ * while letting AI clients launch the server with zero arguments.
+ *
+ * @license MIT
+ */
+import { argv, stdout, stderr, exit } from 'node:process';
+
+const args = argv.slice(2);
+const subcommand = args[0];
+
+const CLI_SUBCOMMANDS = new Set([
+    'setup',
+    'install-skill',
+    'install',
+    'help',
+    '--help',
+    '-h',
+    '--version',
+    '-v',
+]);
+
+if (subcommand !== undefined && CLI_SUBCOMMANDS.has(subcommand)) {
+    try {
+        const { runCli } = await import('../dist/setup-cli.js');
+        const code = await runCli(args);
+        exit(code);
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        stderr.write(`yt-builder-mcp: fatal: ${msg}\n`);
+        exit(99);
+    }
+} else if (
+    subcommand === undefined &&
+    stdout.isTTY === true &&
+    process.env.YTB_MCP_TEST_MODE !== '1'
+) {
+    stdout.write(
+        'Run `npx -y @wootsup/yt-builder-mcp setup` to configure your AI client.\n',
+    );
+    stdout.write(
+        'Run `npx -y @wootsup/yt-builder-mcp help` for usage.\n',
+    );
+} else {
+    // Stdin/stdout piped (or YTB_MCP_TEST_MODE=1): MCP stdio mode.
+    await import('../dist/index.js');
+}

package/dist/auth.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Auth / configuration loading for the MCP server.
+ *
+ * The MCP server reads two environment variables on startup:
+ *
+ *   YTB_MCP_WP_URL        — base URL of the WordPress install, e.g.
+ *                           `https://example.com`. The REST namespace
+ *                           `/wp-json/yt-builder-mcp/v1` is
+ *                           appended internally.
+ *   YTB_MCP_BEARER_TOKEN  — the Bearer key generated by the plugin
+ *                           Settings page (`wp-admin → YT Builder MCP`).
+ *
+ * `loadConfig()` throws `ConfigError` if either is missing, so the
+ * server fails fast with a useful message rather than emitting cryptic
+ * 401/Network errors deep in the request stack.
+ *
+ * @license MIT
+ */
+export interface ServerConfig {
+    /** Base URL of the WordPress install (no trailing slash). */
+    readonly baseUrl: string;
+    /** Bearer key. */
+    readonly bearerToken: string;
+    /** Network timeout (ms) for REST calls. */
+    readonly timeoutMs: number;
+}
+export interface LoadConfigOptions {
+    /** Allow the bearer-token to be empty (for health-only smoke tests). */
+    readonly allowMissingToken?: boolean;
+    /** Source of env vars (defaults to process.env). */
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare const ENV_WP_URL = "YTB_MCP_WP_URL";
+export declare const ENV_BEARER = "YTB_MCP_BEARER_TOKEN";
+export declare const ENV_TIMEOUT = "YTB_MCP_TIMEOUT_MS";
+export declare const ENV_TEST_MODE = "YTB_MCP_TEST_MODE";
+export declare function loadConfig(options?: LoadConfigOptions): ServerConfig;
+export declare function isTestMode(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,MAAM,WAAW,YAAY;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kBAAkB;IAClB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,oDAAoD;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACpC;AAED,eAAO,MAAM,UAAU,mBAAmB,CAAC;AAC3C,eAAO,MAAM,UAAU,yBAAyB,CAAC;AACjD,eAAO,MAAM,WAAW,uBAAuB,CAAC;AAChD,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAkCjD,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,YAAY,CAiDxE;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAExE"}

package/dist/auth.js

@@ -0,0 +1,93 @@
+/**
+ * Auth / configuration loading for the MCP server.
+ *
+ * The MCP server reads two environment variables on startup:
+ *
+ *   YTB_MCP_WP_URL        — base URL of the WordPress install, e.g.
+ *                           `https://example.com`. The REST namespace
+ *                           `/wp-json/yt-builder-mcp/v1` is
+ *                           appended internally.
+ *   YTB_MCP_BEARER_TOKEN  — the Bearer key generated by the plugin
+ *                           Settings page (`wp-admin → YT Builder MCP`).
+ *
+ * `loadConfig()` throws `ConfigError` if either is missing, so the
+ * server fails fast with a useful message rather than emitting cryptic
+ * 401/Network errors deep in the request stack.
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+import { ConfigError } from './errors.js';
+export const ENV_WP_URL = 'YTB_MCP_WP_URL';
+export const ENV_BEARER = 'YTB_MCP_BEARER_TOKEN';
+export const ENV_TIMEOUT = 'YTB_MCP_TIMEOUT_MS';
+export const ENV_TEST_MODE = 'YTB_MCP_TEST_MODE';
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * Maximum accepted length for a Bearer token (defense-in-depth bound;
+ * the real plugin keys are ~150-300 bytes, the 512 ceiling protects
+ * against accidental file-pastes / log dumps / memory abuse).
+ */
+const BEARER_MAX_LEN = 512;
+/**
+ * Bearer-token format check — matches the plugin's `KeyService.php`
+ * `PREFIX = ytb_live_` (and the planned `ytb_test_` future variant).
+ * Token shape: `ytb_(live|test)_<payloadB64Url>.<sigB64Url>` where
+ * base64url uses `[A-Za-z0-9_-]` (no dots inside the payload or sig).
+ *
+ * Round-1 audit I7 fix (2026-05-22): the earlier `.trim()` + empty-check
+ * was not enough to catch the most common config mistakes — the leading
+ * `Bearer ` prefix accidentally pasted into the env var, copy-paste
+ * truncation (no `.` separator), or a totally wrong token style. We
+ * fail-fast here so the client never sends a known-bad value upstream.
+ */
+const BEARER_FORMAT_SCHEMA = z
+    .string()
+    .max(BEARER_MAX_LEN, `Bearer too long (max ${String(BEARER_MAX_LEN)} chars). The env var YTB_MCP_BEARER_TOKEN seems to contain something other than a plain key — strip leading "Bearer " or paste only the key copied from wp-admin → "YT Builder MCP" → Settings.`)
+    .regex(/^ytb_(live|test)_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/, 'Bearer must match ytb_(live|test)_<payloadB64Url>.<sigB64Url> format (copy the key as shown in wp-admin → "YT Builder MCP" → Settings; do NOT prepend "Bearer ").');
+export function loadConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const rawUrl = (env[ENV_WP_URL] ?? '').trim();
+    const rawToken = (env[ENV_BEARER] ?? '').trim();
+    const rawTimeout = (env[ENV_TIMEOUT] ?? '').trim();
+    if (rawUrl === '') {
+        throw new ConfigError(`Missing ${ENV_WP_URL}. Set it to your WordPress base URL ` +
+            '(e.g. https://example.com). Run `yt-builder-mcp setup` to configure.');
+    }
+    if (!options.allowMissingToken && rawToken === '') {
+        throw new ConfigError(`Missing ${ENV_BEARER}. Generate a Bearer key in wp-admin → "YT Builder MCP" → ` +
+            'Settings, then run `yt-builder-mcp setup`.');
+    }
+    // I7-fix: enforce the Bearer-format contract before the client
+    // makes any request. Empty token is allowed only via
+    // `allowMissingToken` (the health-only smoke path); any other
+    // non-empty value MUST match the plugin's KeyService format.
+    if (rawToken !== '') {
+        const parsed = BEARER_FORMAT_SCHEMA.safeParse(rawToken);
+        if (!parsed.success) {
+            const issueMsg = parsed.error.issues
+                .map((iss) => iss.message)
+                .join(' ');
+            throw new ConfigError(`Invalid ${ENV_BEARER}: ${issueMsg}`);
+        }
+    }
+    let timeoutMs = DEFAULT_TIMEOUT_MS;
+    if (rawTimeout !== '') {
+        const parsed = Number.parseInt(rawTimeout, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            timeoutMs = parsed;
+        }
+    }
+    return {
+        baseUrl: stripTrailingSlash(rawUrl),
+        bearerToken: rawToken,
+        timeoutMs,
+    };
+}
+export function isTestMode(env = process.env) {
+    return (env[ENV_TEST_MODE] ?? '') === '1';
+}
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, '');
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `RestClient` — thin wrapper around `fetch` that targets the
+ * `yt-builder-mcp/v1` REST namespace.
+ *
+ * Responsibilities:
+ *   - Compose final URLs (`{baseUrl}/wp-json/yt-builder-mcp/v1{path}`)
+ *   - Attach `Authorization: Bearer …`
+ *   - Encode JSON bodies + propagate `If-Match` etag headers
+ *   - Map non-2xx into `RestError` with status / `code` / message
+ *   - Map network failures into `NetworkError`
+ *
+ * The client deliberately keeps zero state beyond constructor config
+ * so each tool can hold a reference and call `.get/.post/.put/.delete`
+ * without coordinating sessions.
+ *
+ * @license MIT
+ */
+import type { Platform } from './platform/index.js';
+/**
+ * Canonical WordPress REST-namespace path. Re-exported for backward
+ * compat — new code should reach for `Platform.restNamespacePath`.
+ */
+export declare const REST_NAMESPACE_PATH = "/wp-json/yt-builder-mcp/v1";
+/**
+ * Legacy single-platform options shape. Kept so existing call-sites
+ * continue working without touching every entry point.
+ */
+export interface LegacyRestClientOptions {
+    readonly baseUrl: string;
+    readonly bearerToken: string;
+    readonly timeoutMs?: number;
+    /** Injected for tests. Defaults to `globalThis.fetch`. */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Platform-aware options shape (Wave G.0+).
+ * Pass an instance of `WordPressPlatform` (or any future `Platform`)
+ * instead of a bare `baseUrl`.
+ */
+export interface PlatformRestClientOptions {
+    readonly platform: Platform;
+    readonly bearerToken: string;
+    readonly timeoutMs?: number;
+    /** Injected for tests. Defaults to `globalThis.fetch`. */
+    readonly fetch?: typeof fetch;
+}
+/** Discriminated union: callers pick whichever shape suits them. */
+export type RestClientOptions = LegacyRestClientOptions | PlatformRestClientOptions;
+export interface RequestOptions {
+    /** Optional ETag for optimistic-lock (`If-Match` header). */
+    readonly etag?: string;
+    /** JSON body. */
+    readonly body?: unknown;
+    /** Extra headers. */
+    readonly headers?: Record<string, string>;
+    /** Optional AbortSignal. */
+    readonly signal?: AbortSignal;
+}
+export declare class RestClient {
+    private readonly platform;
+    private readonly baseUrl;
+    private readonly bearerToken;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: RestClientOptions);
+    /** Expose the underlying platform (used by tools that need restNamespacePath/kind). */
+    getPlatform(): Platform;
+    get<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    post<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    put<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    request<T = unknown>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    private buildUrl;
+}
+/**
+ * URL-encode a JSON-Pointer-style element path for use in the route.
+ *
+ * The plugin's regex captures everything after `/elements/`, so the
+ * raw `/grid/1/columns/0` path can be passed as-is — but each segment
+ * must be percent-encoded so reserved chars like `~` (used in
+ * JSON-Pointer escapes) don't collide with WordPress' router.
+ */
+export declare function encodeElementPath(pointer: string): string;
+//# 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;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,+BAAgC,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACtC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED,oEAAoE;AACpE,MAAM,MAAM,iBAAiB,GAAG,uBAAuB,GAAG,yBAAyB,CAAC;AAEpF,MAAM,WAAW,cAAc;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB;IACjB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CACjC;AAED,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,iBAAiB;IAYtC,uFAAuF;IACvF,WAAW,IAAI,QAAQ;IAIvB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIxE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIzE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIxE,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrE,OAAO,CAAC,CAAC,GAAG,OAAO,EACrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,CAAC,CAAC;IAgDb,OAAO,CAAC,QAAQ;CAInB;AAgCD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKzD"}