@wix/mcp 1.0.74 → 1.0.76

package/build/dts/toolkit-entry.d.cts

@@ -0,0 +1,410 @@
+import { z } from 'zod';
+
+/**
+ * Local structural types for the toolkit's public surface.
+ *
+ * The MCP SDK's `CallToolResult`/`ToolAnnotations` are z.infer projections of
+ * large zod schemas; exporting them from the toolkit forces every TS consumer
+ * to resolve the SDK's (zod-v4-flavored) declarations. These structural
+ * equivalents keep the published `./toolkit` types self-contained — the SDK's
+ * actual result objects are assignable to them, so implementations keep
+ * returning SDK results unchanged.
+ */
+/** One content block of a tool result (text blocks carry `text`). */
+export type WixToolContentBlock = {
+	type: string;
+	text?: string;
+} & Record<string, unknown>;
+/** Structural equivalent of the MCP SDK's CallToolResult. */
+export type WixToolCallResult = {
+	content: WixToolContentBlock[];
+	isError?: boolean;
+	structuredContent?: Record<string, unknown>;
+	_meta?: Record<string, unknown>;
+} & Record<string, unknown>;
+/** Structural equivalent of the MCP SDK's ToolAnnotations. */
+export type WixToolAnnotations = {
+	title?: string;
+	readOnlyHint?: boolean;
+	destructiveHint?: boolean;
+	idempotentHint?: boolean;
+	openWorldHint?: boolean;
+} & Record<string, unknown>;
+export interface Logger {
+	log(...data: unknown[]): void;
+	error(...data: unknown[]): void;
+}
+export declare const attachConsoleLogger: () => void;
+export declare const UNAUTHORIZED_ERROR_NAME = "UnauthorizedError";
+export type McpHeaders = Record<string, string>;
+/**
+ * Material the execute runtime needs to obtain a site-scoped token for any site
+ * on demand (multi-site ExecuteWixAPI). `oauth` is exchanged for a per-site
+ * token via the oauth2/token refresh-grant; `apiKey` works for any site as-is.
+ * The oauth refresh token is sensitive: never log it, never expose to sandbox JS.
+ */
+export type SiteAuthContext = {
+	type: "oauth";
+	clientId: string;
+	refreshToken: string;
+} | {
+	type: "apiKey";
+	accessToken: string;
+};
+export type McpAuthenticationStrategy = {
+	/**
+	 * Call inside the tool callback so it resolves against the session's
+	 * current handler — the handler can swap mid-session (e.g. anonymous
+	 * → authenticated after OAuth), so anything resolved at registration
+	 * time goes stale.
+	 */
+	isAnonymous?: () => boolean;
+	/**
+	 * Call inside the tool callback so it resolves against the session's
+	 * current handler — the handler can swap mid-session, so anything
+	 * resolved at registration time goes stale.
+	 */
+	getSiteAuthHeaders: (siteId: string) => Promise<McpHeaders> | McpHeaders;
+	/**
+	 * Call inside the tool callback so it resolves against the session's
+	 * current handler — the handler can swap mid-session, so anything
+	 * resolved at registration time goes stale.
+	 */
+	getAccountAuthHeaders: (accountId?: string) => Promise<McpHeaders> | McpHeaders;
+	/**
+	 * Material for the runtime to obtain per-site tokens (multi-site ExecuteWixAPI).
+	 * Optional: strategies without it fall back to the single-site path. Call
+	 * before any try/catch so an UnauthorizedError propagates to wrapToolCallback.
+	 */
+	getSiteAuthContext?: () => Promise<SiteAuthContext> | SiteAuthContext;
+	/**
+	 * Call from a tool's catch block on a Wix API failure. Throws
+	 * `UnauthorizedError` when the error indicates a revoked upstream session
+	 * so `wrapToolCallback` surfaces the re-auth signal; returns silently
+	 * otherwise so the tool's own error handling continues.
+	 */
+	enforceValidWixToken?: (error: unknown) => Promise<void>;
+};
+/**
+ * Re-throws the error if it is an UnauthorizedError.
+ *
+ * IMPORTANT FOR TOOL AUTHORS: When your tool calls getSiteAuthHeaders() or
+ * getAccountAuthHeaders(), prefer making that call BEFORE any try/catch block.
+ * This lets UnauthorizedError propagate naturally to wrapToolCallback, which
+ * attaches the OAuth metadata needed for anonymous-to-authenticated flow.
+ *
+ * If the auth call MUST be inside a try/catch (e.g. it's interleaved with
+ * other logic), add rethrowIfUnauthorized(error) as the first line of your
+ * catch block to ensure the error still propagates.
+ */
+export declare function rethrowIfUnauthorized(error: unknown): void;
+declare const VALID_DOCS_TOOLS: readonly [
+	"WDS",
+	"REST",
+	"SDK",
+	"BUILD_APPS",
+	"WIX_HEADLESS",
+	"VELO",
+	"BUSINESS_SOLUTIONS",
+	"CLI",
+	"OVERVIEW"
+];
+export type DocsTool = (typeof VALID_DOCS_TOOLS)[number];
+/**
+ * Configuration for a README doc entry
+ */
+export interface ReadmeDocConfig {
+	url?: string;
+	action: "include" | "index" | "text" | "api";
+	title?: string;
+	description?: string;
+	content?: string;
+	/** HTTP method for API calls (only used when action is 'api'). Defaults to 'GET' */
+	method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+	/** Request body for API calls (only used when action is 'api' with POST/PUT/PATCH) */
+	body?: Record<string, unknown>;
+}
+export interface DocsToolsOptions {
+	getToKnowWixEnabled?: boolean;
+	createWixBusinessGuideEnabled?: boolean;
+	disableTools?: string[];
+	/** Custom descriptions for tools, keyed by tool name */
+	toolDescriptions?: Record<string, string>;
+	/** Custom list of docs that compose the WixREADME tool output */
+	readmeDocs?: ReadmeDocConfig[];
+	/** Authentication strategy for API calls (required if using 'api' action in readmeDocs) */
+	authStrategy?: McpAuthenticationStrategy;
+	/** Override base URL for skills docs (e.g., "http://localhost:4000" for local dev) */
+	skillsPortalUrl?: string;
+	/** GitHub repo (e.g. "wix-private/docs") to fetch skill overrides from a PR */
+	skillsRepo?: string;
+	/** GitHub repo (e.g. "wix-private/docs") to fetch skill overrides from. Preferred alias for `skillsRepo`; takes precedence when both are supplied. */
+	repo?: string;
+	/** PR number to fetch skill content overrides from */
+	skillsPr?: string;
+	/** Commit hash to fetch content overrides from. Preferred alias for `skillsPr`; takes precedence when both are supplied. */
+	commitHash?: string;
+	/** Tags to filter skills by (e.g. ['velo', 'cms']) */
+	skillsTags?: string[];
+	/** Enable dynamic context fetch */
+	dynamicContextEnabled?: boolean;
+	/** Enable partner context section in dynamic context output */
+	partnerContextEnabled?: boolean;
+	/** Whether the client is a CLI environment (e.g. Claude Code) where users can run terminal commands.
+	 *  Accepts a boolean or a function for lazy evaluation (useful when client name is only known after MCP init). */
+	cliEnabled?: boolean | (() => boolean);
+	/** Use the new platformized semantic search API (POST /v1/docs/search) instead of the legacy GET endpoint */
+	usePlatformizedSearch?: boolean;
+	/** Use the platformized menu browse API (POST /v1/docs/menu/browse) instead of scraping the legacy get-menu-content markdown. Falls back to legacy on transport errors. */
+	usePlatformizedBrowse?: boolean;
+}
+export interface ToolHintsConfig {
+	readOnlyHint?: boolean;
+	destructiveHint?: boolean;
+	openWorldHint?: boolean;
+}
+/**
+ * Safely extract all text content from a WixToolCallResult.
+ * Filters out non-text content blocks (images, audio, resources)
+ * and concatenates text blocks with newlines.
+ */
+export declare function extractText(result: WixToolCallResult): string;
+export declare function formatToolResultAdditionalFields(result: WixToolCallResult): string | undefined;
+/** A single tool extracted from @wix/mcp, ready to execute. */
+export interface WixTool {
+	/** Tool name (e.g. 'CallWixSiteAPI', 'SearchWixRESTDocumentation') */
+	name: string;
+	/** Tool description for the LLM */
+	description: string;
+	/** Zod schema for tool input parameters */
+	inputSchema: z.ZodObject<any>;
+	/**
+	 * JSON Schema for tool input parameters — for consumers that speak JSON
+	 * Schema rather than Zod (WebMCP's `document.modelContext`, OpenAI tool
+	 * definitions, etc.). Computed lazily from `inputSchema` on first access;
+	 * `$ref`s are inlined so the object is self-contained.
+	 */
+	readonly inputJsonSchema: Record<string, unknown>;
+	/** MCP tool annotations (readOnlyHint, destructiveHint, etc.) */
+	annotations?: WixToolAnnotations;
+	/** Execute the tool with the given arguments. Returns native MCP WixToolCallResult. */
+	execute(args: Record<string, any>): Promise<WixToolCallResult>;
+}
+/** The toolkit object returned by createWixToolkit. */
+export interface WixToolkit {
+	/** All registered tools as plain objects */
+	getTools(): WixTool[];
+	/** Get a single tool by name */
+	getTool(name: string): WixTool | undefined;
+	/** Just the tool names */
+	getToolNames(): string[];
+	/** Pre-load WixREADME content (calls the WixREADME tool internally).
+	 *  Site context is resolved from `defaults` passed to createWixToolkit. */
+	preloadReadme(): Promise<string | null>;
+	/** Pre-load dynamic context (site info, installed apps, etc.).
+	 *  Site context is resolved from `defaults` passed to createWixToolkit. */
+	preloadDynamicContext(): Promise<string | null>;
+}
+/** Lifecycle hooks for consumer-side observability. */
+export interface WixToolkitHooks {
+	/** Called before a tool callback is invoked */
+	beforeExecute?: (toolName: string, args: Record<string, any>) => void;
+	/** Called after a tool callback returns (success or isError) */
+	afterExecute?: (toolName: string, result: WixToolCallResult, durationMs: number) => void;
+	/** Called when a tool callback throws an exception */
+	onError?: (toolName: string, error: Error, durationMs: number) => void;
+}
+/** Auth configuration -- either a full McpAuthenticationStrategy or token functions. */
+export type WixToolkitAuth = McpAuthenticationStrategy | {
+	siteToken: (siteId: string) => Promise<McpHeaders> | McpHeaders;
+	accountToken: () => Promise<McpHeaders> | McpHeaders;
+};
+/**
+ * Docs tools configuration.
+ *
+ * Note: `WixREADME` and `GetSiteContext` register only when
+ * `getToKnowWixEnabled: true` is set here — it defaults to false and is
+ * independent of `readmeDocs` and of which API tools are requested.
+ */
+export interface WixToolkitDocsConfig extends DocsToolsOptions {
+	/** Which doc sources to register (default: all) */
+	tools?: DocsTool[];
+}
+/** API tools configuration. */
+export interface WixToolkitApiConfig {
+	/** Which API tools to register (default: all three) */
+	tools?: string[];
+	/** Disable specific tools by name */
+	disableTools?: string[];
+	/** Enable additional tools */
+	enableTools?: string[];
+	/** Custom descriptions per tool */
+	toolDescriptions?: Record<string, string>;
+	/** Tool hint overrides */
+	toolHints?: Record<string, ToolHintsConfig>;
+	/**
+	 * Max response size in chars before truncation. Applies to CallWixSiteAPI/
+	 * ListWixSites/ManageWixSite (default: 50,000) and to ExecuteWixAPI/
+	 * SearchWixAPISpec (default: 24,000). Always clamped to a hard ceiling
+	 * regardless of what's requested here — see MAX_ALLOWED_RESPONSE_CHARS.
+	 */
+	maxResponseSize?: number;
+	/** Base URL for code-mode tools such as ExecuteWixAPI */
+	codeModeBaseUrl?: string;
+}
+/** Options for createWixToolkit. */
+export interface WixToolkitOptions {
+	/** Authentication -- required for API call tools */
+	auth: WixToolkitAuth;
+	/** Docs tools configuration */
+	docs?: WixToolkitDocsConfig;
+	/** API tools configuration */
+	api?: WixToolkitApiConfig;
+	/**
+	 * Default values to inject at execute time.
+	 * Fields listed here are removed from the tool's inputSchema and
+	 * automatically merged into args when execute() is called.
+	 *
+	 * Common use: `defaults: { siteId: 'my-site-id' }` to hide siteId from
+	 * the LLM's schema and auto-inject it on every tool execution.
+	 */
+	defaults?: Record<string, any>;
+	/** Tool names to exclude after registration */
+	exclude?: string[];
+	/** Consumer name -- shows up in BI events for tracking usage per consumer */
+	clientName?: string;
+	/**
+	 * Environment name (DEV/TEST/LOCAL/REMOTE/PICASSO/VISITOR_MCP). Defaults to
+	 * `process.env.NODE_ENV` where a `process` global exists; pass explicitly in
+	 * browsers. Unknown/absent values resolve to LOCAL (telemetry on).
+	 */
+	nodeEnv?: string;
+	/** Consumer-side observability hooks (separate from library Panorama/BI telemetry) */
+	hooks?: WixToolkitHooks;
+	/** Conversation ID — passed to BI events for tracking */
+	conversationId?: string;
+	/**
+	 * Keep WixREADME mentions in tool descriptions. Defaults to `false` (mentions
+	 * scrubbed, for consumers that don't expose WixREADME); set `true` for the live
+	 * MCP server's text. Only affects description text — never the tool set itself.
+	 */
+	includeReadmeMentions?: boolean;
+}
+/**
+ * Create a WixToolkit that provides pre-wired tool objects for in-process use.
+ *
+ * This is the recommended way to use @wix/mcp tools outside of a full MCP server.
+ * It handles tool registration, context building, Panorama/BI telemetry, and
+ * schema manipulation (defaults) internally.
+ */
+export declare function createWixToolkit(options: WixToolkitOptions): WixToolkit;
+export declare class WixFetchError extends Error {
+	readonly status: number;
+	readonly response: {
+		status: number;
+		data: string;
+	};
+	constructor(status: number, statusText: string, body: string);
+}
+export declare const EXECUTE_FUNCTION_EXPRESSION_HINT: string;
+export interface CodeValidationResult {
+	isValid: boolean;
+	error?: string;
+}
+export declare function validateExecuteCode(code: string): CodeValidationResult;
+/** URL for the management recipes index article */
+export declare const RECIPES_INDEX_URL = "https://dev.wix.com/docs/api-reference/articles/ai-tools/wix-mcp/skills/wix-management-recipes-index";
+/**
+ * Fetch the management recipes index content from the public rawdocs API.
+ * Returns the recipes index as a string (markdown).
+ *
+ * No authentication required -- creates its own HttpClient.
+ *
+ * @example
+ * ```typescript
+ * import { fetchRecipesIndex } from '@wix/mcp';
+ *
+ * const recipes = await fetchRecipesIndex();
+ * console.log(recipes);
+ * ```
+ */
+export declare function fetchRecipesIndex(): Promise<string>;
+/**
+ * Fetch any Wix documentation article by its URL.
+ * Returns the article content as a string (markdown).
+ *
+ * No authentication required -- creates its own HttpClient.
+ *
+ * @param articleUrl - Full URL to a dev.wix.com docs article
+ *
+ * @example
+ * ```typescript
+ * import { fetchArticle } from '@wix/mcp';
+ *
+ * const article = await fetchArticle(
+ *   'https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/products/query-products'
+ * );
+ * console.log(article);
+ * ```
+ */
+export declare function fetchArticle(articleUrl: string): Promise<string>;
+interface ReadmeDocConfig$1 {
+	url?: string;
+	action: "include" | "index" | "text" | "api";
+	title?: string;
+	description?: string;
+	content?: string;
+	/** HTTP method for API calls (only used when action is 'api'). Defaults to 'GET' */
+	method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+	/** Request body for API calls (only used when action is 'api' with POST/PUT/PATCH) */
+	body?: Record<string, unknown>;
+}
+/**
+ * Configuration structure for MCP modes
+ */
+export interface ModeDefaultConfig {
+	toolDescriptions: Record<string, string>;
+	disableTools: string[];
+	enableTools: string[];
+	readmeDocs: ReadmeDocConfig$1[];
+	toolHints?: Record<string, ToolHintsConfig>;
+	docsTools?: DocsTool[];
+	getToKnowWixEnabled?: boolean;
+	createWixBusinessGuideEnabled?: boolean;
+	codeModeEnabled?: boolean;
+	maxResponseSize?: number;
+	dynamicContextEnabled?: boolean;
+	partnerContextEnabled?: boolean;
+	usePlatformizedSearch?: boolean;
+	skillsPrOverrideEnabled?: boolean;
+}
+export declare const SYSTEM_REMINDER_GUIDELINES: string;
+export declare const SYSTEM_REMINDER: string;
+/**
+ * Canonical (README-inclusive) tool descriptions used by the live MCP server and
+ * all existing importers.
+ */
+export declare const defaultToolDescriptions: Record<string, string>;
+export declare const executeCodeModeToolDescriptions: Record<string, string>;
+/**
+ * Default readme docs - content for WixREADME tool response.
+ * Assumes both ExecuteWixAPI and SearchWixAPISpec are available (execute-and-search mode).
+ *
+ * Joined rather than interpolated into one `dedent` — `dedent` reads indentation from the literal
+ * parts only, so a multi-line interpolation gets flattened.
+ */
+export declare const defaultReadmeDocs: ReadmeDocConfig$1[];
+/**
+ * Merge base config with overrides
+ * @param base - Base configuration
+ * @param overrides - Partial overrides to apply
+ * @returns Merged configuration
+ */
+export declare function mergeConfig(base: ModeDefaultConfig, overrides: Partial<ModeDefaultConfig>): ModeDefaultConfig;
+/**
+ * Default config - used by both /mcp and /v2 endpoints
+ * All tools enabled, all descriptions, good readmeDocs
+ */
+export declare const defaultConfig: ModeDefaultConfig;
+
+export {};