mcp-creatio 0.3.6

package/src/creatio/engines/sys-settings/sys-settings-engine.ts

@@ -0,0 +1,41 @@
+import {
+	CreateSysSettingRequest,
+	CreateSysSettingResult,
+	QuerySysSettingsResponse,
+	SysSettingDefinitionUpdate,
+	SysSettingUpdateResponse,
+	SysSettingsProvider,
+} from '../../providers';
+import { CreatioEngine } from '../engine';
+
+export class SysSettingsEngine implements CreatioEngine {
+	private readonly _provider: SysSettingsProvider;
+
+	public readonly name = 'sys-settings';
+
+	constructor(provider: SysSettingsProvider) {
+		this._provider = provider;
+	}
+
+	public get kind(): string {
+		return this._provider.kind;
+	}
+
+	public setValues(values: Record<string, any>): Promise<any> {
+		return this._provider.setValues(values);
+	}
+
+	public queryValues(codes: string[]): Promise<QuerySysSettingsResponse> {
+		return this._provider.queryValues(codes);
+	}
+
+	public createSetting(request: CreateSysSettingRequest): Promise<CreateSysSettingResult> {
+		return this._provider.createSetting(request);
+	}
+
+	public updateDefinition(
+		definition: SysSettingDefinitionUpdate,
+	): Promise<SysSettingUpdateResponse> {
+		return this._provider.updateDefinition(definition);
+	}
+}

package/src/creatio/engines/user/user-engine.ts

@@ -0,0 +1,20 @@
+import { CurrentUserInfo, UserProvider } from '../../providers';
+import { CreatioEngine } from '../engine';
+
+export class UserEngine implements CreatioEngine {
+	private readonly _provider: UserProvider;
+
+	public readonly name = 'user';
+
+	constructor(provider: UserProvider) {
+		this._provider = provider;
+	}
+
+	public get kind(): string {
+		return this._provider.kind;
+	}
+
+	public getCurrentUserInfo(): Promise<CurrentUserInfo> {
+		return this._provider.getCurrentUserInfo();
+	}
+}

package/src/creatio/index.ts

@@ -0,0 +1,6 @@
+export * from './client-config';
+export * from './provider-context';
+export * from './providers';
+export * from './engines';
+export * from './services';
+export * from './auth';

package/src/creatio/provider-context.ts

@@ -0,0 +1,10 @@
+import { ICreatioAuthProvider } from './auth';
+import { CrudProvider, ProcessProvider, SysSettingsProvider, UserProvider } from './providers';
+
+export interface CreatioProviderContext {
+	authProvider: ICreatioAuthProvider;
+	crud: CrudProvider;
+	process: ProcessProvider;
+	sysSettings: SysSettingsProvider;
+	user: UserProvider;
+}

package/src/creatio/providers/crud-provider.ts

@@ -0,0 +1,45 @@
+export interface EntitySchemaProperty {
+	name: string;
+	type: string;
+	nullable?: boolean;
+}
+
+export interface EntitySchemaDescription {
+	entitySet: string;
+	entityType: string;
+	key: string[];
+	properties: EntitySchemaProperty[];
+}
+
+export interface CrudReadParams {
+	entity: string;
+	filter?: string | undefined;
+	select?: string[] | undefined;
+	top?: number | undefined;
+	expand?: string[] | undefined;
+	orderBy?: string | undefined;
+}
+
+export interface CrudWriteParams {
+	entity: string;
+	data: any;
+}
+
+export interface CrudUpdateParams extends CrudWriteParams {
+	id: string;
+}
+
+export interface CrudDeleteParams {
+	entity: string;
+	id: string;
+}
+
+export interface CrudProvider {
+	readonly kind: string;
+	listEntitySets(): Promise<string[]>;
+	describeEntity(entitySet: string): Promise<EntitySchemaDescription>;
+	read(params: CrudReadParams): Promise<any>;
+	create(params: CrudWriteParams): Promise<any>;
+	update(params: CrudUpdateParams): Promise<any>;
+	delete(params: CrudDeleteParams): Promise<any>;
+}

package/src/creatio/providers/index.ts

@@ -0,0 +1,4 @@
+export * from './crud-provider';
+export * from './process-provider';
+export * from './sys-settings-provider';
+export * from './user-provider';

package/src/creatio/providers/process-provider.ts

@@ -0,0 +1,15 @@
+export interface ExecuteProcessParams {
+	processName: string;
+	parameters?: Record<string, any> | undefined;
+}
+
+export interface ExecuteProcessResult {
+	status?: string;
+	returnValues?: Record<string, any>;
+	[key: string]: any;
+}
+
+export interface ProcessProvider {
+	readonly kind: string;
+	executeProcess(params: ExecuteProcessParams): Promise<ExecuteProcessResult>;
+}

package/src/creatio/providers/sys-settings-provider.ts

@@ -0,0 +1,63 @@
+export interface QuerySysSettingsResponse {
+	success: boolean;
+	values: Record<string, SysSettingDetail>;
+	notFoundSettings?: string[];
+}
+
+export interface SysSettingDetail {
+	code?: string;
+	value?: unknown;
+	displayValue?: string;
+	isCacheable?: boolean;
+	dataValueType?: number | string;
+	dataValueTypeName?: number | string;
+	id?: string;
+	name?: string;
+}
+
+export interface SysSettingDefinition extends Record<string, unknown> {
+	code: string;
+	name: string;
+	valueTypeName: string;
+	id?: string | undefined;
+	description?: string | undefined;
+	isCacheable?: boolean | undefined;
+	isPersonal?: boolean | undefined;
+	isSSPAvailable?: boolean | undefined;
+	referenceSchemaUId?: string | undefined;
+	dataValueType?: number | string | undefined;
+}
+
+export type SysSettingDefinitionUpdate = Partial<SysSettingDefinition> & { id: string };
+
+export interface CreateSysSettingRequest {
+	definition: SysSettingDefinition;
+	initialValue?: unknown;
+	isPersonal?: boolean;
+}
+
+export interface SysSettingInsertResponse extends Record<string, unknown> {
+	id: string;
+	success: boolean;
+	rowsAffected?: number;
+	nextPrcElReady?: boolean;
+}
+
+export interface SysSettingUpdateResponse extends Record<string, unknown> {
+	success?: boolean;
+	rowsAffected?: number;
+	nextPrcElReady?: boolean;
+}
+
+export interface CreateSysSettingResult {
+	insertResult: SysSettingInsertResponse;
+	setValueResult?: any;
+}
+
+export interface SysSettingsProvider {
+	readonly kind: string;
+	setValues(values: Record<string, any>): Promise<any>;
+	queryValues(codes: string[]): Promise<QuerySysSettingsResponse>;
+	createSetting(request: CreateSysSettingRequest): Promise<CreateSysSettingResult>;
+	updateDefinition(definition: SysSettingDefinitionUpdate): Promise<SysSettingUpdateResponse>;
+}

package/src/creatio/providers/user-provider.ts

@@ -0,0 +1,12 @@
+export interface CurrentUserInfo {
+	userId?: string;
+	contactId?: string;
+	userName?: string;
+	cultureName?: string;
+	[key: string]: any;
+}
+
+export interface UserProvider {
+	readonly kind: string;
+	getCurrentUserInfo(): Promise<CurrentUserInfo>;
+}

package/src/creatio/services/creatio-service-context.ts

@@ -0,0 +1,38 @@
+import { CreatioAuthManager, ICreatioAuthProvider } from '../auth';
+import { CreatioClientConfig } from '../client-config';
+import { CreatioProviderContext } from '../provider-context';
+import { CrudProvider, ProcessProvider, SysSettingsProvider, UserProvider } from '../providers';
+
+import { CreatioHttpClient } from './http-client';
+import { ODataMetadataStore } from './metadata-store';
+import { ODataCrudProvider } from './odata-crud-provider';
+import { ProcessServiceProvider } from './process-service-provider';
+import { SysSettingsServiceProvider } from './sys-settings-service-provider';
+import { UserInfoProvider } from './user-info-provider';
+
+export class CreatioServiceContext implements CreatioProviderContext {
+	private readonly _config: CreatioClientConfig;
+	private readonly _authManager: CreatioAuthManager;
+	private readonly _httpClient: CreatioHttpClient;
+
+	public readonly kind = 'creatio-services';
+	public readonly crud: CrudProvider;
+	public readonly process: ProcessProvider;
+	public readonly sysSettings: SysSettingsProvider;
+	public readonly user: UserProvider;
+
+	public get authProvider(): ICreatioAuthProvider {
+		return this._authManager.getProvider();
+	}
+
+	constructor(config: CreatioClientConfig) {
+		this._config = config;
+		this._authManager = new CreatioAuthManager(this._config);
+		this._httpClient = new CreatioHttpClient(this._config, this._authManager);
+		const metadataStore = new ODataMetadataStore(this._httpClient);
+		this.crud = new ODataCrudProvider(this._httpClient, metadataStore);
+		this.process = new ProcessServiceProvider(this._httpClient);
+		this.sysSettings = new SysSettingsServiceProvider(this._httpClient);
+		this.user = new UserInfoProvider(this._httpClient);
+	}
+}

package/src/creatio/services/http-client.ts

@@ -0,0 +1,174 @@
+import log from '../../log';
+import { JSON_ACCEPT, XML_ACCEPT } from '../../types';
+import { CreatioAuthManager, ICreatioAuthProvider } from '../auth';
+import { CreatioClientConfig } from '../client-config';
+
+type RequestFactory = () => Promise<RequestInit>;
+type SuccessHandler<T> = (response: Response, duration: number) => Promise<T>;
+type ErrorHandler<T> = (response: Response, duration: number) => Promise<T>;
+
+type LogContext = Record<string, any>;
+
+export class CreatioHttpClient {
+	private readonly _config: CreatioClientConfig;
+	private readonly _authManager: CreatioAuthManager;
+	private readonly _normalizedBaseUrl: string;
+
+	public get authProvider(): ICreatioAuthProvider {
+		return this._authManager.getProvider();
+	}
+
+	public get normalizedBaseUrl(): string {
+		return this._normalizedBaseUrl;
+	}
+
+	public get odataRoot(): string {
+		return `${this._normalizedBaseUrl}/0/odata`;
+	}
+
+	constructor(config: CreatioClientConfig, authManager: CreatioAuthManager) {
+		this._config = config;
+		this._authManager = authManager;
+		this._normalizedBaseUrl = this._config.baseUrl.replace(/\/$/, '');
+	}
+
+	private _logRequest(url: string, requestInit: RequestInit): void {
+		log.info('creatio.http.request', {
+			url,
+			method: requestInit.method || 'GET',
+			hasAuth: Boolean(requestInit.headers && (requestInit.headers as any)['Authorization']),
+		});
+	}
+
+	private _logUnauthorizedResponse(
+		url: string,
+		response: Response,
+		hasTriedRefresh: boolean,
+	): void {
+		log.warn('creatio.http.401_response', {
+			url,
+			status: response.status,
+			triedRefresh: hasTriedRefresh,
+			responseHeaders: Object.fromEntries(response.headers.entries()),
+		});
+	}
+
+	public async getJsonHeaders(): Promise<Record<string, string>> {
+		return this.authProvider.getHeaders(JSON_ACCEPT, true);
+	}
+
+	public async getXmlHeaders(): Promise<Record<string, string>> {
+		return this.authProvider.getHeaders(XML_ACCEPT, false);
+	}
+
+	public async getPostHeaders(): Promise<Record<string, string>> {
+		const headers = await this.getJsonHeaders();
+		return {
+			...headers,
+			'Content-Type': 'application/json',
+		};
+	}
+
+	public async createPostRequest(body?: any): Promise<RequestInit> {
+		const headers = await this.getPostHeaders();
+		return {
+			method: 'POST',
+			headers,
+			body: body ? JSON.stringify(body) : JSON.stringify({}),
+		};
+	}
+
+	public async fetchJson(url: string, initFactory: RequestFactory) {
+		const response = await this.fetchWithAuth(url, initFactory);
+		if (!response.ok) {
+			const errorText = await response.text().catch(() => '');
+			throw new Error(`creatio_http_error:${response.status} ${errorText}`);
+		}
+		return response.json();
+	}
+
+	public async fetchText(url: string, initFactory: RequestFactory) {
+		const response = await this.fetchWithAuth(url, initFactory);
+		if (!response.ok) {
+			const errorText = await response.text().catch(() => '');
+			throw new Error(`creatio_http_error:${response.status} ${errorText}`);
+		}
+		return response.text();
+	}
+
+	public async fetchWithAuth(url: string, initFactory: RequestFactory): Promise<Response> {
+		let hasTriedRefresh = false;
+		while (true) {
+			const requestInit = await initFactory();
+			this._logRequest(url, requestInit);
+			const response = await fetch(url, requestInit);
+			if (response.status !== 401) {
+				return response;
+			}
+			this._logUnauthorizedResponse(url, response, hasTriedRefresh);
+			if (hasTriedRefresh) {
+				return response;
+			}
+			hasTriedRefresh = true;
+			await this.authProvider.refresh();
+		}
+	}
+
+	public async executeWithTiming<T>(
+		operation: string,
+		url: string,
+		request: () => Promise<Response>,
+		successHandler: SuccessHandler<T>,
+		errorHandler: ErrorHandler<T>,
+		logContext: LogContext = {},
+	): Promise<T> {
+		const startTime = Date.now();
+		try {
+			const response = await request();
+			const duration = Date.now() - startTime;
+			if (!response.ok) {
+				return await errorHandler(response, duration);
+			}
+			return await successHandler(response, duration);
+		} catch (error: any) {
+			const duration = Date.now() - startTime;
+			log.error(`creatio.http.${operation}.error`, {
+				...logContext,
+				url,
+				error: String(error?.message ?? error),
+				duration,
+			});
+			throw error;
+		}
+	}
+
+	public async handleErrorResponse(
+		operation: string,
+		response: Response,
+		duration: number,
+		errorPrefix: string,
+		logContext: LogContext = {},
+	): Promise<never> {
+		const errorText = await response.text().catch(() => '');
+		log.error(`creatio.http.${operation}.error`, {
+			...logContext,
+			status: response.status,
+			error: errorText,
+			duration,
+		});
+		throw new Error(`${errorPrefix}:${response.status} ${errorText}`);
+	}
+
+	public logSuccess(
+		operation: string,
+		status: number,
+		duration: number,
+		logContext: LogContext = {},
+	) {
+		log.info(`creatio.http.${operation}.success`, {
+			...logContext,
+			status,
+			duration,
+		});
+	}
+}

package/src/creatio/services/index.ts

@@ -0,0 +1,7 @@
+export * from './creatio-service-context';
+export * from './http-client';
+export * from './metadata-store';
+export * from './odata-crud-provider';
+export * from './process-service-provider';
+export * from './sys-settings-service-provider';
+export * from './user-info-provider';

package/src/creatio/services/metadata-store.ts

@@ -0,0 +1,181 @@
+import { XMLParser } from 'fast-xml-parser';
+
+import log from '../../log';
+import { EntitySchemaDescription } from '../providers';
+
+import { CreatioHttpClient } from './http-client';
+
+export class ODataMetadataStore {
+	private readonly _client: CreatioHttpClient;
+	private _metadataXml?: string;
+	private _metadataParsed?: any;
+
+	constructor(client: CreatioHttpClient) {
+		this._client = client;
+	}
+
+	private _arrayify<T>(value: T | T[] | undefined | null): T[] {
+		if (value == null) {
+			return [];
+		}
+		return Array.isArray(value) ? value : [value];
+	}
+
+	private async _getMetadataXml(): Promise<string> {
+		if (this._metadataXml) {
+			return this._metadataXml;
+		}
+		const headers = await this._client.getXmlHeaders();
+		const metadataUrl = `${this._client.odataRoot}/$metadata`;
+		const xmlContent = await this._client.fetchText(metadataUrl, async () => ({ headers }));
+		this._metadataXml = xmlContent;
+		return this._metadataXml;
+	}
+
+	private async _getParsedMetadata(): Promise<any> {
+		if (this._metadataParsed) {
+			return this._metadataParsed;
+		}
+		const xmlContent = await this._getMetadataXml();
+		const parser = new XMLParser({
+			ignoreAttributes: false,
+			attributeNamePrefix: '@_',
+		});
+		this._metadataParsed = parser.parse(xmlContent);
+		return this._metadataParsed;
+	}
+
+	private _extractSchemas(metadata: any): any[] {
+		const dataServices = metadata['edmx:Edmx']?.['edmx:DataServices'];
+		return this._arrayify<any>(dataServices?.Schema);
+	}
+
+	private async _tryGetEntitySetsFromService(): Promise<string[] | null> {
+		try {
+			const serviceUrl = `${this._client.odataRoot}/`;
+			const headers = await this._client.getJsonHeaders();
+			const response = await this._client.fetchWithAuth(serviceUrl, async () => ({
+				headers,
+			}));
+			if (response.ok) {
+				const body: any = await response.json().catch(() => null);
+				if (body && Array.isArray(body.value)) {
+					return body.value.map((item: any) => String(item.name));
+				}
+			}
+			if (!response.ok) {
+				log.error('creatio.metadata.list_entity_sets.error', {
+					url: serviceUrl,
+					status: response.status,
+				});
+			}
+		} catch (error: any) {
+			log.error('creatio.metadata.list_entity_sets.error', {
+				url: `${this._client.odataRoot}/`,
+				error: String(error?.message ?? error),
+			});
+		}
+		return null;
+	}
+
+	private async _getEntitySetsFromMetadata(): Promise<string[]> {
+		const metadata = await this._getParsedMetadata();
+		const schemas = this._extractSchemas(metadata);
+		const entitySets: string[] = [];
+		for (const schema of schemas) {
+			const containers = this._arrayify<any>(schema.EntityContainer);
+			for (const container of containers) {
+				const sets = this._arrayify<any>(container.EntitySet);
+				for (const set of sets) {
+					const name = set?.['@_Name'];
+					if (name) {
+						entitySets.push(String(name));
+					}
+				}
+			}
+		}
+		return Array.from(new Set(entitySets));
+	}
+
+	private _findEntityType(schemas: any[], entitySet: string): string {
+		for (const schema of schemas) {
+			const containers = this._arrayify<any>(schema.EntityContainer);
+			for (const container of containers) {
+				const sets = this._arrayify<any>(container.EntitySet);
+				for (const set of sets) {
+					if (set?.['@_Name'] === entitySet) {
+						return String(set?.['@_EntityType'] ?? '');
+					}
+				}
+			}
+		}
+		return '';
+	}
+
+	private _findEntityTypeNode(schemas: any[], typeName: string): any {
+		for (const schema of schemas) {
+			const types = this._arrayify<any>(schema.EntityType);
+			for (const type of types) {
+				if (type?.['@_Name'] === typeName) {
+					return type;
+				}
+			}
+		}
+		return undefined;
+	}
+
+	private _parseEntityProperties(entityTypeNode: any): {
+		key: string[];
+		properties: Array<{
+			name: string;
+			type: string;
+			nullable?: boolean;
+		}>;
+	} {
+		const keyRefs = this._arrayify<any>(entityTypeNode.Key?.PropertyRef);
+		const key = keyRefs.map((ref) => String(ref?.['@_Name'] ?? '')).filter(Boolean) as string[];
+		const propertyNodes = this._arrayify<any>(entityTypeNode.Property);
+		const properties = propertyNodes.map((prop) => {
+			const name = String(prop?.['@_Name'] ?? '');
+			const type = String(prop?.['@_Type'] ?? '');
+			const result: {
+				name: string;
+				type: string;
+				nullable?: boolean;
+			} = { name, type };
+			if (Object.prototype.hasOwnProperty.call(prop, '@_Nullable')) {
+				result.nullable = String(prop['@_Nullable']) === 'true';
+			}
+			return result;
+		});
+		return { key, properties };
+	}
+
+	public async listEntitySets(): Promise<string[]> {
+		const serviceSets = await this._tryGetEntitySetsFromService();
+		if (serviceSets) {
+			return serviceSets;
+		}
+		return this._getEntitySetsFromMetadata();
+	}
+
+	public async describeEntity(entitySet: string): Promise<EntitySchemaDescription> {
+		const metadata = await this._getParsedMetadata();
+		const schemas = this._extractSchemas(metadata);
+		const fullType = this._findEntityType(schemas, entitySet);
+		if (!fullType) {
+			const error = `entity_not_found:${entitySet}`;
+			log.error('creatio.metadata.describe_entity.error', { entitySet, error });
+			throw new Error(error);
+		}
+		const typeName = fullType.split('.').pop()!;
+		const entityTypeNode = this._findEntityTypeNode(schemas, typeName);
+		if (!entityTypeNode) {
+			const error = `entity_type_not_found:${typeName}`;
+			log.error('creatio.metadata.describe_entity.error', { entitySet, error });
+			throw new Error(error);
+		}
+		const { key, properties } = this._parseEntityProperties(entityTypeNode);
+		return { entitySet, entityType: typeName, key, properties };
+	}
+}