@wootsup/mcp 0.1.0 → 0.4.0

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

@@ -1,5 +1,6 @@
 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.
  *
@@ -45,7 +46,7 @@ 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" | "credential_expired" | "tier_limit_reached" | "unknown";
 export interface ExtApiResponse<T = unknown> extends ApiResponse<T> {
     status?: number;
     errorCode?: ApiErrorCode;
@@ -105,6 +106,66 @@ export interface PlatformClient {
  */
 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.
  *
@@ -120,11 +181,61 @@ export declare const PLATFORM_KIND: "wordpress" | "joomla";
  */
 export declare function request<T = unknown>(path: string, init?: RequestInit, opts?: RequestOpts): Promise<ExtApiResponse<T>>;
 /**
- * Map an `errorCode` to a focused hint string for the caller.
- * Falls back to the generic health-tool hint.
+ * Optional second argument to {@link hintFor}, used to route a hint more
+ * precisely than the coarse `ApiErrorCode` alone allows. Both fields are
+ * optional and every legacy `hintFor(code)` call keeps its exact prior
+ * output (back-compat), so the ~12 call sites need not change.
+ *
+ * Welle 2 (F112 + F113, 2026-06-11):
+ *   - `message`: the upstream error string. Lets the `unknown` branch route
+ *      a config/validation/argument error to a "fix the field / fix the flow
+ *      shape / detect schema" hint instead of the catch-all HEALTH_HINT
+ *      (which sends the agent on a connectivity probe that always passes).
+ *      It is also the channel for the F83 JMESPath depth-limit detection
+ *      (see {@link DEPTH_SPLIT_HINT}).
+ *   - `origin`: WHERE a 401/403 came from. `classify()` maps every 401/403
+ *      to `'auth'`, but a 401/403 raised by a *connection* / *credential*
+ *      fetch is an EXPIRED UPSTREAM token, not a broken MCP key. With
+ *      `origin: 'connection' | 'credential'` the auth branch steers to
+ *      re-authorising the upstream credential (`oauth_authorize_begin`)
+ *      rather than rotating the still-valid MCP bearer key.
  */
-export declare function hintFor(code?: ApiErrorCode): string;
+export interface HintContext {
+    /** The upstream error message, used for message-pattern routing of `unknown`. */
+    message?: string;
+    /**
+     * The origin of an auth (401/403) failure. `connection` / `credential`
+     * mean an expired upstream token; `mcp_transport` (or omitted) means the
+     * MCP bearer key itself.
+     */
+    origin?: "connection" | "credential" | "mcp_transport";
+}
+export declare const DEPTH_SPLIT_HINT: string;
+/**
+ * Map an `errorCode` (and optional {@link HintContext}) to a focused hint
+ * string for the caller. Falls back to the generic health-tool hint only for
+ * genuinely connectivity-shaped failures.
+ *
+ * The second argument is a UNION: a bare `string` is treated as
+ * `{ message }` so the ~12 legacy call sites that pass the upstream error
+ * string verbatim (`hintFor(code, r.error)`) keep working unchanged, while
+ * the richer `{ message, origin }` form drives F112/F113 routing. Omit it to
+ * keep the legacy code-only behaviour byte-for-byte.
+ */
+export declare function hintFor(code?: ApiErrorCode, context?: string | HintContext): string;
 export declare const HEALTH_HINT = "Use apimapper_health to check connectivity and auth.";
+/**
+ * Recovery hint for an auth failure on the MCP transport itself (the bearer
+ * key is wrong/revoked/expired). Kept verbatim for the legacy `hintFor('auth')`
+ * contract.
+ */
+export declare const MCP_KEY_AUTH_HINT: string;
+/**
+ * F113 — recovery hint for an EXPIRED UPSTREAM credential surfaced as a
+ * connection/credential 401/403. The fix is to re-authorise the credential in
+ * place (preserving the refresh_token), NOT to rotate the MCP key.
+ */
+export declare const CREDENTIAL_EXPIRED_HINT: string;
 export declare function authConfigured(): boolean;
 export declare const api: {
     request: <T>(path: string, init?: RequestInit, _retryCount?: number, responseSchema?: import("zod").ZodType<T>) => Promise<ApiResponse<T>>;