@wootsup/mcp 0.1.0-rc.9 → 0.3.0

package/dist/modules/apimapper/client.d.ts

@@ -1,6 +1,37 @@
 import { type ApiResponse } from "@getimo/mcp-toolkit";
 import { type Platform } from "../../platform/index.js";
+import { type SitesRegistry } from "../../sites/loader.js";
+/**
+ * WordPress / Joomla site base URL.
+ *
+ * Env-var precedence: `APIMAPPER_WP_BASE` → `APIMAPPER_SITE_URL` (alias
+ * written by the DXT setup wizard) → empty string.
+ *
+ * The SITE_URL → WP_BASE bridge is handled exactly once, above, via
+ * `process.env.APIMAPPER_WP_BASE = process.env.APIMAPPER_SITE_URL`. This
+ * keeps a single source of truth in `process.env` so any consumer
+ * (including child processes spawned later, R7 verify scripts, and
+ * legacy CustomGraph internal code) sees the same value — not just
+ * this module's exported `WP_BASE` constant.
+ *
+ * Empty default is intentional (F-43, 2026-05-19): a freshly-installed
+ * customer who has not run the setup wizard must NOT silently inherit
+ * the WootsUp dev URL — that leaked the vendor's setup hostname into
+ * customer error logs and confused triage. In production (NODE_ENV
+ * === "production") an empty value causes a fail-fast exit below.
+ *
+ * Trailing slash is normalised away so downstream `${WP_BASE}/...` joins
+ * never produce double-slashes.
+ */
 export declare const WP_BASE: string;
+/**
+ * WordPress username for legacy Application-Password Basic auth.
+ *
+ * Empty default is intentional (F-44, 2026-05-19): the previous "getimo"
+ * default leaked a personal username into customer 401 logs. Customers
+ * using the modern Bearer-token flow (`amk_live_...`) don't need this
+ * value at all; legacy users must set `APIMAPPER_WP_USER` explicitly.
+ */
 export declare const WP_USER: string;
 export declare const WP_APP_PASS: string;
 /**
@@ -15,12 +46,21 @@ export declare function sanitizeErrorString(s: string): string;
  * The underlying toolkit `ApiResponse` only carries `{success, data?, error?}`.
  * We wrap each call so we capture the HTTP code via `fetch` and merge.
  */
-export type ApiErrorCode = "auth" | "not_found" | "rate_limit" | "server" | "network" | "unknown";
+export type ApiErrorCode = "auth" | "not_found" | "conflict" | "rate_limit" | "server" | "network" | "unknown";
 export interface ExtApiResponse<T = unknown> extends ApiResponse<T> {
     status?: number;
     errorCode?: ApiErrorCode;
     /** When true, response was 2xx but payload had `success: false` — semantically failed. */
     payloadFailed?: boolean;
+    /**
+     * W2-3 (H-3, 2026-05-28): the parsed JSON body when the server returned a
+     * non-2xx response. Carries domain-specific fields like
+     * `compiler_error_code` (FlowHandler::compile) that the caller-side autofix
+     * branches on. `undefined` when the error response wasn't JSON, or when the
+     * call succeeded. Do NOT use as a "did the request succeed" check;
+     * `success` is the source of truth for that.
+     */
+    errorBody?: Record<string, unknown>;
 }
 interface RequestOpts {
     /**
@@ -65,6 +105,67 @@ export interface PlatformClient {
  * All errors are sanitised via `sanitizeErrorString()` before being returned.
  */
 export declare function createPlatformClient(platform: Platform): PlatformClient;
+export declare const PLATFORM_KIND: "wordpress" | "joomla";
+/**
+ * Network platform auto-detect. Concurrently probes the WordPress REST identity
+ * endpoint and the Joomla com_ajax getIdentity task with the same auth header,
+ * and decides which CMS is actually running at WP_BASE:
+ *
+ *   - Joomla wins if its probe is HTTP 200 AND the body parses to
+ *     `{success:true, data:[{success:true, …}]}` (or `data[0].platform` set).
+ *   - WordPress wins if its probe is HTTP 200 AND the body is a JSON object
+ *     that is NOT a `{success:false}` error envelope.
+ *   - If both look OK (shouldn't happen on a single CMS), prefer the one whose
+ *     reported identity `.platform` matches its own kind; else WordPress.
+ *   - If neither answers → return "wordpress" (graceful fallback — no worse
+ *     than the pre-Phase-1 silent default).
+ *
+ * All fetch errors are swallowed → fallback. The token is sent on the wire but
+ * never logged. Short timeout so a blocked probe host can't stall startup.
+ *
+ * Phase 3 (2026-06-03): accepts optional `(baseUrl, token)` overrides so a
+ * per-site probe (sites-file path) can target the entry's own URL + token. The
+ * no-arg call preserves the env-path behaviour exactly (module WP_BASE +
+ * probeAuthHeader()).
+ */
+export declare function probePlatform(baseUrl?: string, token?: string): Promise<"wordpress" | "joomla">;
+/**
+ * Lazily load + memoize the sites-file registry from APIMAPPER_SITES_FILE.
+ * Returns `null` when the env var is unset/empty, the file is absent, or it has
+ * zero sites — in all those cases the caller falls through to the env path.
+ * A malformed / schema-invalid file throws `SitesFileError` (loud-fail at first
+ * use rather than silently degrading multi-site to single-site).
+ */
+export declare function getSitesRegistry(): SitesRegistry | null;
+/**
+ * The currently-active site_id, or `null` when none has been explicitly set
+ * (the file's default entry is then used) or when no sites-file is loaded.
+ */
+export declare function getActiveSiteId(): string | null;
+/**
+ * Switch the active site. Validates that `id` exists in the loaded sites-file
+ * registry, updates the in-memory pointer, and resets the resolution memo so
+ * the next `request()` re-resolves (URL + token + platform) against the new
+ * site. Throws when no sites-file is loaded or the id is unknown — the pointer
+ * is NOT changed on error.
+ */
+export declare function setActiveSite(id: string): void;
+/**
+ * Drop the memoized platform resolution (and the cached sites-file registry +
+ * active-site pointer) so the next `request()` re-resolves from scratch —
+ * re-reading APIMAPPER_SITES_FILE, re-running the env-check / network probe.
+ *
+ * Production callers: invoke after deliberately changing the active selection
+ * outside `setActiveSite()` (the tool wiring uses `setActiveSite`, which already
+ * resets the memo). Safe to call any time.
+ */
+export declare function resetPlatformResolution(): void;
+/**
+ * Test-only alias of {@link resetPlatformResolution}, kept for the existing
+ * Phase-1 client tests that reference it by this name. New code should call
+ * `resetPlatformResolution()`.
+ */
+export declare function __resetPlatformResolutionForTests(): void;
 /**
  * Issue a request through the toolkit HTTP client + capture HTTP status.
  *