@elementor/elementor-mcp-common 4.1.0-754

package/src/elements.ts

@@ -0,0 +1,158 @@
+import { ensureElementorFrontend, isGutenbergEditor } from './editor-detection';
+import { get$e, getElementor, getElementorFrontend, getWp } from './utils';
+
+interface GutenbergBlockEditorDispatch {
+	updateBlockAttributes: ( clientId: string, attributes: Record< string, unknown > ) => void;
+}
+
+interface GutenbergBlockEditorSelect {
+	getBlock: ( clientId: string ) => { name: string } | null;
+}
+
+interface GutenbergBlock {
+	name: string;
+}
+
+export function injectElementCSS( elementId: string, css: string ): void {
+	const style = document.createElement( 'style' );
+	style.id = elementId;
+	style.appendChild( document.createTextNode( css ) );
+
+	ensureElementorFrontend();
+	const frontend = getElementorFrontend() as { elements: { $body: HTMLElement[] } } | undefined;
+	if ( frontend ) {
+		frontend.elements.$body[ 0 ].appendChild( style );
+	}
+}
+
+export function removeElementCSS( elementId: string ): void {
+	ensureElementorFrontend();
+	const frontend = getElementorFrontend() as { elements: { $body: HTMLElement[] } } | undefined;
+	if ( ! frontend ) {
+		return;
+	}
+
+	const bodyElement = frontend.elements.$body[ 0 ];
+	const styleTags = bodyElement.querySelectorAll( `#${ CSS.escape( elementId ) }` );
+
+	if ( styleTags?.length > 0 ) {
+		styleTags.forEach( ( tag: Element ) => {
+			bodyElement.removeChild( tag );
+		} );
+	}
+}
+
+export async function updateElementSettings( {
+	id,
+	settings,
+}: {
+	id: string;
+	settings: Record< string, unknown >;
+} ): Promise< unknown > {
+	const containerToUpdateSettings = getElementor()?.getContainer( id );
+	if ( ! containerToUpdateSettings ) {
+		throw new Error( `Element with ID "${ id }" not found.` );
+	}
+
+	const updateResult = await get$e()?.run( 'document/elements/settings', {
+		container: containerToUpdateSettings,
+		settings,
+		options: {
+			external: true,
+			render: true,
+		},
+	} );
+
+	const frontend = getElementorFrontend() as { elements: { $body: { resize: () => void } } } | undefined;
+	frontend?.elements.$body.resize();
+
+	return updateResult;
+}
+
+export function getElementSettings( id: string ): unknown {
+	const container = getElementor()?.getContainer( id );
+	if ( ! container ) {
+		throw new Error( `Element with ID "${ id }" not found.` );
+	}
+	return container.settings;
+}
+
+export function getGutenbergBlockEditorApis(): {
+	blockEditorDispatch: GutenbergBlockEditorDispatch;
+	blockEditorSelect: GutenbergBlockEditorSelect;
+} {
+	const wp = getWp();
+	if ( ! isGutenbergEditor() || ! wp ) {
+		throw new Error( 'WordPress editor API is not available' );
+	}
+
+	const blockEditorDispatch = wp.data.dispatch( 'core/block-editor' ) as unknown as GutenbergBlockEditorDispatch;
+	const blockEditorSelect = wp.data.select( 'core/block-editor' ) as unknown as GutenbergBlockEditorSelect;
+
+	if ( ! blockEditorDispatch || ! blockEditorSelect ) {
+		throw new Error( 'Block editor API is not available' );
+	}
+
+	return { blockEditorDispatch, blockEditorSelect };
+}
+
+export function validateAndGetGutenbergBlock(
+	blockEditorSelect: GutenbergBlockEditorSelect,
+	blockId: string
+): GutenbergBlock {
+	const block = blockEditorSelect.getBlock( blockId );
+	if ( ! block ) {
+		throw new Error( `Block with ID "${ blockId }" not found` );
+	}
+	return block;
+}
+
+export function updateGutenbergBlockAttributes(
+	blockId: string,
+	attributes: Record< string, unknown >
+): { blockId: string; blockName: string; updatedAttributes: string[] } {
+	const { blockEditorDispatch, blockEditorSelect } = getGutenbergBlockEditorApis();
+	const block = validateAndGetGutenbergBlock( blockEditorSelect, blockId );
+
+	blockEditorDispatch.updateBlockAttributes( blockId, attributes );
+
+	return {
+		blockId,
+		blockName: block.name,
+		updatedAttributes: Object.keys( attributes ),
+	};
+}
+
+export function extractElementImageData(
+	targetElementId: string,
+	fallbackImageId = '',
+	fallbackImageUrl = ''
+): { imageId: string; imageUrl: string } {
+	let extractedImageId = fallbackImageId;
+	let extractedImageUrl = fallbackImageUrl;
+
+	if ( targetElementId && ( ! extractedImageId || ! extractedImageUrl ) ) {
+		const targetContainer = getElementor()?.getContainer?.( targetElementId );
+		if ( targetContainer ) {
+			const imageData = targetContainer.settings.get( 'image' );
+			if ( imageData && typeof imageData === 'object' ) {
+				const imageObj = imageData as { id?: string | number; url?: string };
+				extractedImageId = extractedImageId || imageObj.id?.toString() || '';
+				extractedImageUrl = extractedImageUrl || imageObj.url || '';
+			}
+		}
+	}
+
+	return {
+		imageId: extractedImageId,
+		imageUrl: extractedImageUrl,
+	};
+}
+
+export function isSelectAllCheckbox( input: HTMLInputElement ): boolean {
+	if ( ( input.id && input.id.includes( 'select-all' ) ) || ( input.name && input.name.includes( 'select-all' ) ) ) {
+		return true;
+	}
+
+	return false;
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+export {
+	isGutenbergEditor,
+	isElementorEditor,
+	isElementorAIActive,
+	hasGutenbergUI,
+	ensureElementorFrontend,
+	isElementorEditorReady,
+	waitForElementorEditor,
+	waitForElementor,
+	whenElementorReady,
+} from './editor-detection';
+
+export {
+	injectElementCSS,
+	removeElementCSS,
+	updateElementSettings,
+	getElementSettings,
+	getGutenbergBlockEditorApis,
+	validateAndGetGutenbergBlock,
+	updateGutenbergBlockAttributes,
+	extractElementImageData,
+	isSelectAllCheckbox,
+} from './elements';
+
+export { callWpApi, extractJSONFromResponse } from './rest-client';
+
+export { initNonceRefresh, refreshNonce, isNonceError } from './nonce-refresh';
+
+export type {
+	ElementorChannels,
+	ElementorCommandsInstance,
+	ElementorCommonInstance,
+	ElementorContainer,
+	ElementorDocument,
+	ElementorFrontendInstance,
+	ElementorInstance,
+	JQuery,
+	WpApiSettings,
+	WpDataInstance,
+} from './types';
+
+export {
+	get$e,
+	getAjaxUrl,
+	getElementor,
+	getElementorAiConfig,
+	getElementorCommon,
+	getElementorFrontend,
+	getJQuery,
+	getWp,
+	getWpApiSettings,
+} from './utils';

package/src/nonce-refresh.ts

@@ -0,0 +1,76 @@
+import type { WpApiSettings } from './types';
+import { getAjaxUrl, getJQuery, getWpApiSettings } from './utils';
+
+type HeartbeatTickData = {
+	angie_nonce?: string;
+};
+
+let isNonceRefreshInitialized = false;
+let nonceRefreshPromise: Promise< string > | null = null;
+
+export function initNonceRefresh(): void {
+	const jQuery = getJQuery();
+	const wpApiSettings = getWpApiSettings();
+	if ( isNonceRefreshInitialized || typeof jQuery === 'undefined' || ! wpApiSettings ) {
+		return;
+	}
+
+	isNonceRefreshInitialized = true;
+
+	jQuery?.( document ).on( 'heartbeat-tick.angieNonceRefresh', ( _event: unknown, data: unknown ) => {
+		try {
+			const tickData = data as HeartbeatTickData;
+			const currentSettings = getWpApiSettings() as WpApiSettings | undefined;
+			if ( tickData.angie_nonce && currentSettings && currentSettings.nonce !== tickData.angie_nonce ) {
+				currentSettings.nonce = tickData.angie_nonce;
+			}
+		} catch ( error ) {
+			// eslint-disable-next-line no-console
+			console.error( 'Failed to refresh nonce:', error );
+		}
+	} );
+}
+
+export async function refreshNonce(): Promise< string > {
+	if ( nonceRefreshPromise ) {
+		return nonceRefreshPromise;
+	}
+
+	nonceRefreshPromise = fetchFreshNonce();
+
+	try {
+		return await nonceRefreshPromise;
+	} finally {
+		nonceRefreshPromise = null;
+	}
+}
+
+async function fetchFreshNonce(): Promise< string > {
+	const ajaxUrl = new URL( getAjaxUrl() || '/wp-admin/admin-ajax.php', window.location.origin );
+	ajaxUrl.searchParams.set( 'action', 'rest-nonce' );
+	const response = await fetch( ajaxUrl.toString(), {
+		credentials: 'same-origin',
+	} );
+
+	if ( ! response.ok ) {
+		throw new Error( `Failed to refresh nonce: HTTP ${ response.status }` );
+	}
+
+	const nonce = await response.text();
+
+	if ( ! nonce || nonce === '0' ) {
+		throw new Error( 'Session expired — received invalid nonce' );
+	}
+
+	const wpApiSettings = getWpApiSettings() as WpApiSettings | undefined;
+	if ( ! wpApiSettings ) {
+		throw new Error( 'wpApiSettings not available — cannot refresh nonce' );
+	}
+
+	wpApiSettings.nonce = nonce;
+	return nonce;
+}
+
+export function isNonceError( status: number, responseText: string ): boolean {
+	return status === 403 && responseText.includes( 'rest_cookie_invalid_nonce' );
+}

package/src/rest-client.ts

@@ -0,0 +1,163 @@
+import { isNonceError, refreshNonce } from './nonce-refresh';
+import { getWpApiSettings } from './utils';
+
+type WpApiResponse = unknown;
+
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+
+type CallWpApiOptions = {
+	binaryData?: ArrayBufferLike;
+	customHeaders?: Record< string, string >;
+};
+
+type CallWpApiResult< T > = {
+	data: T;
+	totalItems?: number;
+	totalPages?: number;
+};
+
+export async function callWpApi< T = WpApiResponse >(
+	endpoint: string,
+	method: HttpMethod,
+	data?: Record< string, unknown >,
+	options?: CallWpApiOptions
+): Promise< CallWpApiResult< T > > {
+	return executeWpApiCall< T >( endpoint, method, data, options, true );
+}
+
+async function executeWpApiCall< T = WpApiResponse >(
+	endpoint: string,
+	method: HttpMethod,
+	data?: Record< string, unknown >,
+	options?: CallWpApiOptions,
+	allowNonceRetry = false
+): Promise< CallWpApiResult< T > > {
+	const wpApiSettings = getWpApiSettings();
+	if ( ! wpApiSettings?.nonce || ! wpApiSettings.root ) {
+		throw new Error( 'wpApiSettings not available' );
+	}
+
+	const baseUrl = wpApiSettings.root;
+	const urlObject = new URL( baseUrl );
+	const endpointUrl = new URL( endpoint, baseUrl );
+
+	urlObject.searchParams.set( 'rest_route', endpointUrl.pathname );
+
+	for ( const [ key, value ] of endpointUrl.searchParams.entries() ) {
+		urlObject.searchParams.append( key, value );
+	}
+
+	const url = urlObject.toString();
+
+	const headers: Record< string, string > = {
+		'X-WP-Nonce': wpApiSettings.nonce,
+		...( options?.customHeaders || {} ),
+	};
+
+	if ( ! options?.binaryData && ! options?.customHeaders?.[ 'Content-Type' ] ) {
+		headers[ 'Content-Type' ] = 'application/json';
+	}
+
+	const requestOptions: RequestInit = {
+		method,
+		headers,
+		credentials: 'same-origin',
+	};
+
+	if ( options?.binaryData ) {
+		requestOptions.body = options.binaryData as ArrayBuffer;
+	} else if ( data && ( method === 'POST' || method === 'PUT' || method === 'PATCH' ) ) {
+		requestOptions.body = JSON.stringify( data );
+	}
+
+	const response = await fetch( url, requestOptions );
+
+	if ( ! response.ok ) {
+		const responseText = await response.text();
+
+		if ( allowNonceRetry && isNonceError( response.status, responseText ) ) {
+			await refreshNonce();
+			return executeWpApiCall< T >( endpoint, method, data, options, false );
+		}
+
+		throw new Error( `HTTP error ${ response.status }: ${ responseText }` );
+	}
+
+	const responseText = await response.text();
+	const json = extractJSONFromResponse( responseText );
+
+	if ( json === null ) {
+		throw new Error( `Invalid response: no JSON found in: ${ responseText.substring( 0, 200 ) }` );
+	}
+
+	const jsonObj = json as { success?: boolean };
+	if ( jsonObj?.success !== undefined && ! jsonObj.success ) {
+		throw new Error( `API errors: ${ JSON.stringify( json ) }` );
+	}
+
+	const totalItemsHeader = response.headers.get( 'X-WP-Total' );
+	const totalPagesHeader = response.headers.get( 'X-WP-TotalPages' );
+	const totalItems: number | undefined = totalItemsHeader ? parseInt( totalItemsHeader, 10 ) : undefined;
+	const totalPages: number | undefined = totalPagesHeader ? parseInt( totalPagesHeader, 10 ) : undefined;
+
+	return {
+		data: json as T,
+		totalItems,
+		totalPages,
+	};
+}
+
+export function extractJSONFromResponse( responseText: string ): unknown {
+	const objectStart = responseText.indexOf( '{' );
+	const arrayStart = responseText.indexOf( '[' );
+
+	let startIndex = -1;
+	let isArray = false;
+
+	if ( objectStart === -1 && arrayStart === -1 ) {
+		return null;
+	}
+
+	if ( objectStart === -1 ) {
+		startIndex = arrayStart;
+		isArray = true;
+	} else if ( arrayStart === -1 ) {
+		startIndex = objectStart;
+		isArray = false;
+	} else if ( arrayStart < objectStart ) {
+		startIndex = arrayStart;
+		isArray = true;
+	} else {
+		startIndex = objectStart;
+		isArray = false;
+	}
+
+	let delimiterCount = 0;
+	let endIndex = -1;
+	const openChar = isArray ? '[' : '{';
+	const closeChar = isArray ? ']' : '}';
+
+	for ( let i = startIndex; i < responseText.length; i++ ) {
+		if ( responseText[ i ] === openChar ) {
+			delimiterCount++;
+		} else if ( responseText[ i ] === closeChar ) {
+			delimiterCount--;
+			if ( delimiterCount === 0 ) {
+				endIndex = i;
+				break;
+			}
+		}
+	}
+
+	if ( endIndex === -1 ) {
+		return null;
+	}
+
+	const jsonString = responseText.substring( startIndex, endIndex + 1 );
+
+	try {
+		return JSON.parse( jsonString );
+	} catch {
+		return null;
+	}
+}

package/src/types.ts

@@ -0,0 +1,186 @@
+export interface WpApiSettings {
+	nonce: string;
+	root: string;
+}
+
+export interface ElementorContainer {
+	id: string;
+	model: {
+		id: string;
+		get: ( key: string ) => unknown;
+		attributes?: Record< string, unknown >;
+		editor_settings?: { title?: string };
+	};
+	settings: {
+		get: ( key: string ) => unknown;
+		attributes?: Record< string, unknown >;
+		controls?: Record< string, unknown >;
+	};
+	children?: ElementorContainer[];
+	view?: {
+		el: HTMLElement;
+	};
+	parent?: ElementorContainer;
+}
+
+export interface ElementorDocument {
+	id: string;
+	container: ElementorContainer;
+	config?: {
+		type?: string;
+		settings?: Record< string, unknown >;
+	};
+	editor?: {
+		status?: string;
+		isChanged?: boolean;
+	};
+	history?: {
+		active?: boolean;
+		setActive?: ( active: boolean ) => void;
+	};
+}
+
+export interface ElementorChannels {
+	deviceMode?: {
+		request: ( key?: string ) => unknown;
+	};
+	dataEditMode?: {
+		request: ( key?: string ) => unknown;
+	};
+}
+
+export interface ElementorInstance {
+	documents: {
+		getCurrent: () => ElementorDocument | null;
+		get?: ( id: string | number ) => ElementorDocument | null;
+	};
+	getContainer: ( id: string ) => ElementorContainer | null;
+	getCurrentElement: () => { model: { id: string } } | null;
+	on: ( event: string, callback: () => void ) => void;
+	config?: {
+		responsive?: {
+			breakpoints?: Record< string, unknown >;
+		};
+		controls?: Record< string, unknown >;
+		v4Promotions?: Record< string, unknown >;
+		default_schemes?: Record< string, unknown >;
+		atomicDynamicTags?: {
+			tags?: Record< string, unknown >;
+			groups?: Record< string, unknown >;
+		};
+	};
+	helpers?: {
+		hasPro?: () => boolean;
+		enqueueFont?: ( font: string ) => void;
+	};
+	$preview?: [ HTMLIFrameElement ];
+	selection?: {
+		elements?: Record< string, unknown >;
+		getElements?: () => unknown[];
+	};
+	hooks?: {
+		addFilter: ( name: string, callback: ( ...args: unknown[] ) => unknown ) => void;
+	};
+	dynamicTags?: {
+		getConfig: ( key: string ) => Record< string, unknown >;
+		tagDataToTagText: ( id: string, name: string, settings: Record< string, unknown > ) => string;
+		createTag?: ( options: Record< string, unknown > ) => unknown;
+		loadTagDataFromCache?: ( tag: unknown, key: string ) => unknown;
+		refreshCacheFromServer?: ( tag: unknown, callback: () => void ) => void;
+	};
+	widgetsCache?: Record<
+		string,
+		{
+			controls?: Record< string, unknown >;
+			title?: string;
+			atomic_controls?: unknown[];
+		}
+	>;
+	channels?: ElementorChannels;
+	getPanelView?: () => {
+		getHeaderView?: () => {
+			setTitle?: ( title: string ) => void;
+		};
+		getCurrentPageView?: () => unknown;
+	};
+	getPreferences?: ( key: string ) => unknown;
+	changeEditMode?: ( mode: string ) => void;
+	modules?: Record< string, unknown >;
+}
+
+export interface ElementorFrontendInstance {
+	elements: {
+		$body: JQuery & HTMLElement[];
+	};
+	on: ( event: string, callback: () => void ) => void;
+	config?: {
+		responsive?: {
+			activeBreakpoints?: Record< string, unknown >;
+		};
+		kit?: {
+			active_breakpoints?: string[];
+		};
+		experimentalFeatures?: Record< string, boolean >;
+		is_rtl?: boolean;
+	};
+}
+
+export interface ElementorCommandsInstance {
+	run: ( command: string, args?: Record< string, unknown > ) => Promise< unknown >;
+	components: {
+		get: ( name: string ) => {
+			getCommands?: () => {
+				open?: { registerConfig: { command: string } };
+				close?: { registerConfig: { command: string } };
+			};
+			getNamespace?: () => string;
+		} | null;
+		getAll?: () => string[];
+	};
+	routes?: {
+		getAll?: () => string[];
+		isPartOf?: ( route: string ) => boolean;
+		to?: ( route: string, args?: Record< string, unknown > ) => void;
+		register?: ( route: string, callback: () => void ) => void;
+		saveState?: ( namespace: string ) => void;
+		back?: ( namespace: string ) => void;
+		getComponent?: ( route: string ) => { getNamespace: () => string };
+	};
+	data?: {
+		get?: ( key: string ) => Promise< unknown >;
+	};
+	modules?: {
+		hookData?: Record< string, unknown >;
+	};
+}
+
+export interface WpDataInstance {
+	select: ( store: string ) => Record< string, unknown > | undefined;
+	dispatch: ( store: string ) => Record< string, unknown >;
+}
+
+export interface JQuery {
+	resize: () => void;
+	[ index: number ]: HTMLElement;
+}
+
+export interface ElementorCommonInstance {
+	eventsManager?: {
+		dispatchEvent?: ( name: string, data: unknown, options?: Record< string, unknown > ) => void;
+		canSendEvents?: () => boolean;
+		initializeMixpanel?: ( onLoaded: ( mpInstance?: unknown ) => void ) => void;
+		config?: Record< string, unknown >;
+	};
+	config?: {
+		isRTL?: boolean;
+		version?: string;
+		experimentalFeatures?: Record< string, boolean >;
+		urls?: Record< string, string >;
+	};
+	helpers?: {
+		getUniqueId?: () => number | string;
+	};
+	ajax?: {
+		addRequest?: ( endpoint: string, options: { success?: ( data: unknown ) => void } ) => Promise< void >;
+	};
+}

package/src/utils.ts

@@ -0,0 +1,46 @@
+import type {
+	ElementorCommandsInstance,
+	ElementorCommonInstance,
+	ElementorFrontendInstance,
+	ElementorInstance,
+	WpApiSettings,
+	WpDataInstance,
+} from './types';
+
+interface McpWindow {
+	elementor?: ElementorInstance;
+	elementorFrontend?: ElementorFrontendInstance;
+	$e?: ElementorCommandsInstance;
+	elementorCommon?: ElementorCommonInstance;
+	wpApiSettings?: WpApiSettings;
+	ajaxurl?: string;
+	wp?: {
+		data: WpDataInstance;
+	};
+	jQuery?: ( selector: unknown ) => {
+		on: ( event: string, callback: ( event: unknown, data: unknown ) => void ) => void;
+		get?: ( index: number ) => HTMLElement;
+	};
+	ElementorAiConfig?: Record< string, unknown >;
+}
+
+export const getElementor = (): ElementorInstance | undefined => ( window as unknown as McpWindow ).elementor;
+
+export const getElementorFrontend = (): ElementorFrontendInstance | undefined =>
+	( window as unknown as McpWindow ).elementorFrontend;
+
+export const get$e = (): ElementorCommandsInstance | undefined => ( window as unknown as McpWindow ).$e;
+
+export const getElementorCommon = (): ElementorCommonInstance | undefined =>
+	( window as unknown as McpWindow ).elementorCommon;
+
+export const getWpApiSettings = (): WpApiSettings | undefined => ( window as unknown as McpWindow ).wpApiSettings;
+
+export const getAjaxUrl = (): string | undefined => ( window as unknown as McpWindow ).ajaxurl;
+
+export const getWp = (): { data: WpDataInstance } | undefined => ( window as unknown as McpWindow ).wp;
+
+export const getJQuery = (): McpWindow[ 'jQuery' ] => ( window as unknown as McpWindow ).jQuery;
+
+export const getElementorAiConfig = (): Record< string, unknown > | undefined =>
+	( window as unknown as McpWindow ).ElementorAiConfig;