@gxp-dev/tools 2.0.72 → 2.0.74

package/mcp/gxp-api-server.js

@@ -63,12 +63,40 @@ function searchEndpoints(spec, query) {
 }
 
 /**
- * Search AsyncAPI spec for channels/events matching a query
+ * Search AsyncAPI spec for channels/events matching a query.
+ *
+ * Matches across:
+ *   - components.messages (event name, summary, description, x-triggered-by)
+ *   - channels            (channel name, description)
+ *
+ * For messages, the returned `eventName` is what you pass to
+ * store.listen(eventName, permissionIdentifier, callback) on the client.
  */
 function searchEvents(spec, query) {
 	const results = []
 	const queryLower = query.toLowerCase()
 
+	const messages = spec?.components?.messages || {}
+	for (const [eventName, message] of Object.entries(messages)) {
+		if (typeof message !== "object" || message === null) continue
+		const trigger = message["x-triggered-by"] || ""
+		if (
+			eventName.toLowerCase().includes(queryLower) ||
+			message.summary?.toLowerCase().includes(queryLower) ||
+			message.description?.toLowerCase().includes(queryLower) ||
+			trigger.toLowerCase().includes(queryLower)
+		) {
+			results.push({
+				kind: "event",
+				eventName,
+				summary: message.summary || "",
+				description: message.description || "",
+				triggeredBy: trigger || null,
+				payloadRef: message.payload?.$ref || null,
+			})
+		}
+	}
+
 	if (spec.channels) {
 		for (const [channel, details] of Object.entries(spec.channels)) {
 			if (
@@ -92,6 +120,7 @@ function searchEvents(spec, query) {
 				}
 
 				results.push({
+					kind: "channel",
 					channel,
 					description: details.description || "",
 					operations,
@@ -200,7 +229,7 @@ const API_TOOLS = [
 	{
 		name: "search_websocket_events",
 		description:
-			"Search for WebSocket channels/events matching a query. Searches channel names and descriptions.",
+			"Search AsyncAPI events matching a query. Searches components.messages (event name, summary, description, x-triggered-by) and channel definitions. The returned eventName is what you pass to store.listen(eventName, permissionIdentifier, callback).",
 		inputSchema: {
 			type: "object",
 			properties: {

package/mcp/lib/api-tools.js

@@ -158,6 +158,38 @@ const EXT_API_TOOLS = [
 			required: [],
 		},
 	},
+	{
+		name: "api_find_events_for_operation",
+		description:
+			"Given an OpenAPI operationId, return every AsyncAPI message whose x-triggered-by matches. Use this after adding a callApi(operationId, ...) call to discover whether a socket event is fired server-side — subscribe to it with store.listen(eventName, permissionIdentifier, cb) instead of polling.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				operationId: {
+					type: "string",
+					description:
+						"OpenAPI operationId (e.g. 'posts.store'). Bare ids and 'portal.v1.project.<id>' are both accepted.",
+				},
+			},
+			required: ["operationId"],
+		},
+	},
+	{
+		name: "api_list_events",
+		description:
+			"List all AsyncAPI events from components.messages. Each entry includes the event name, summary/description, and x-triggered-by (if declared). Optionally filter by triggeredBy operationId.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				triggeredBy: {
+					type: "string",
+					description:
+						"Only return events whose x-triggered-by equals this operationId. Omit for all events.",
+				},
+			},
+			required: [],
+		},
+	},
 	{
 		name: "api_generate_dependency",
 		description:
@@ -312,6 +344,50 @@ async function findEndpointsBySchema(filters) {
 	return out
 }
 
+function normalizeOperationId(id) {
+	if (!id) return id
+	return id.replace(/^portal\.v1\.project\./, "")
+}
+
+async function listAsyncApiEvents(triggeredBy) {
+	const spec = await fetchSpec("asyncapi")
+	const messages = spec?.components?.messages || {}
+	const targetTrigger = triggeredBy ? normalizeOperationId(triggeredBy) : null
+
+	const out = []
+	for (const [eventName, message] of Object.entries(messages)) {
+		if (typeof message !== "object" || message === null) continue
+		const trigger = message["x-triggered-by"] || null
+		if (targetTrigger && normalizeOperationId(trigger) !== targetTrigger) {
+			continue
+		}
+		out.push({
+			eventName,
+			summary: message.summary || "",
+			description: message.description || "",
+			triggeredBy: trigger,
+			payloadRef: message.payload?.$ref || null,
+		})
+	}
+	return out
+}
+
+async function findEventsForOperation(operationId) {
+	if (!operationId) {
+		return { ok: false, error: "operationId is required" }
+	}
+	const events = await listAsyncApiEvents(operationId)
+	return {
+		ok: true,
+		operationId: normalizeOperationId(operationId),
+		events,
+		note:
+			events.length === 0
+				? "No AsyncAPI messages declare x-triggered-by for this operationId. Either the operation does not fire a platform event, or the spec has not declared the trigger yet."
+				: "Subscribe with store.listen(eventName, permissionIdentifier, callback) to receive these events live.",
+	}
+}
+
 async function generateDependency({
 	identifier,
 	tag,
@@ -429,6 +505,14 @@ async function handleExtApiToolCall(name, args = {}) {
 				results: await findEndpointsBySchema(args || {}),
 			})
 
+		case "api_find_events_for_operation":
+			return contentResult(await findEventsForOperation(args.operationId))
+
+		case "api_list_events":
+			return contentResult({
+				events: await listAsyncApiEvents(args.triggeredBy),
+			})
+
 		case "api_generate_dependency":
 			return contentResult(await generateDependency(args))
 
@@ -453,4 +537,7 @@ module.exports = {
 	getOperationParameters,
 	findEndpointsBySchema,
 	generateDependency,
+	listAsyncApiEvents,
+	findEventsForOperation,
+	normalizeOperationId,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gxp-dev/tools",
-	"version": "2.0.72",
+	"version": "2.0.74",
 	"description": "Dev tools to create platform plugins",
 	"type": "commonjs",
 	"publishConfig": {

package/runtime/stores/gxpPortalConfigStore.js

@@ -244,8 +244,8 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 
 		if (manifest.dependencies && Array.isArray(manifest.dependencies)) {
 			dependencies.value = manifest.dependencies // Store full dependency objects
-			dependencyList.value = manifest.dependencies.reduce((acc, dependency) => {
-				acc[dependency.identifier] = "1"
+			dependencyList.value = manifest.dependencies.reduce((acc, permission) => {
+				acc[permission.identifier] = "1"
 				return acc
 			}, {})
 			console.log("[GxP Store] Dependency List:", dependencyList.value)
@@ -379,58 +379,16 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 
 		// Initialize dependency-based sockets based on the new structure
 		if (Array.isArray(dependencies.value)) {
-			dependencies.value.forEach((dependency) => {
-				if (
-					dependency.operations &&
-					Object.keys(dependency.operations).length > 0
-				) {
-					// Object.keys(dependency.operations).forEach((operation) => {
-					// 	if (
-					// 		Object.keys(apiOperations.value[dependency.identifier]).every(
-					// 			(key) =>
-					// 				[
-					// 					"identifier",
-					// 					"model",
-					// 					"permissionKey",
-					// 					"operations",
-					// 				].includes(key)
-					// 		)
-					// 	) {
-					// 		let method = "get";
-					// 		let path = dependency.operations[operation];
-					// 		if (path.includes(":")) {
-					// 			let pathSplit = path.split(":");
-					// 			method = pathSplit[0];
-					// 			path = pathSplit[1];
-					// 		}
-					// 		path = path.replace(
-					// 			"{teamSlug}/{projectSlug}",
-					// 			pluginVars.value.projectId
-					// 		);
-					// 		path = path.replace(
-					// 			`{${dependency.permissionKey}}`,
-					// 			dependencyList.value[dependency.identifier]
-					// 		);
-					// 		if (!apiOperations.value[dependency.identifier]) {
-					// 			apiOperations.value[dependency.identifier] = {};
-					// 		}
-					// 		apiOperations.value[dependency.identifier][operation] = {
-					// 			method: method,
-					// 			path: path,
-					// 			model_key: dependency.permissionKey,
-					// 		};
-					// 	}
-					// });
-				}
-				if (dependency.events && Object.keys(dependency.events).length > 0) {
+			dependencies.value.forEach((permission) => {
+				if (permission.events && Object.keys(permission.events).length > 0) {
 					// Create socket listeners for each event type
-					sockets[dependency.identifier] = {}
+					sockets[permission.identifier] = {}
 
-					Object.keys(dependency.events).forEach((eventType) => {
-						const eventName = dependency.events[eventType]
-						const channel = `private.${dependency.model}.${dependency.identifier}`
+					Object.keys(permission.events).forEach((eventType) => {
+						const eventName = permission.events[eventType]
+						const channel = `private.${permission.model}.${permission.identifier}`
 
-						sockets[dependency.identifier][eventType] = {
+						sockets[permission.identifier][eventType] = {
 							listen: function (callback) {
 								// Listen for the specific event on the primary socket
 								return primarySocket.on(eventName, (data) => {
@@ -445,7 +403,7 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 					})
 				} else {
 					// For dependencies without events, create empty listeners
-					sockets[dependency.identifier] = {
+					sockets[permission.identifier] = {
 						created: { listen: () => () => {} },
 						updated: { listen: () => () => {} },
 						deleted: { listen: () => () => {} },
@@ -500,7 +458,7 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 			throw new Error(`DELETE ${endpoint}: ${error.message}`)
 		}
 	}
-	async function callApi(operationId, identifier, data = {}) {
+	async function callApi(operationId, permissionIdentifier, data = {}) {
 		// Initialize operations if not done
 		if (Object.keys(apiOperations.value).length === 0) {
 			await initializeApiOperations()
@@ -520,7 +478,7 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 
 		// Build context parameters from multiple sources:
 		// 1. Auto-inject teamSlug and projectSlug from portal context
-		// 2. Look up identifier value from dependencyList (if identifier provided)
+		// 2. Look up permissionIdentifier value from dependencyList (if permissionIdentifier provided)
 		// 3. Merge in additional data parameters
 
 		let projectTeamId = pluginVars.value?.projectId?.split("/")
@@ -537,14 +495,19 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 		if (parameters.includes("form") && pluginVars.value?.formId) {
 			contextParams["form"] = pluginVars.value?.formId
 		}
-		// If identifier is provided, look up its value from dependencyList
-		// dependencyList stores parent object IDs as { 'identifier': idValue }
-		if (identifier !== null && identifier !== undefined) {
-			const identifierValue = dependencyList.value?.[identifier]
-			if (identifierValue !== undefined) {
-				// Add the identifier value using the identifier key as the param name
-				// e.g., identifier='form' with dependencyList.form='quiz-123' adds { form: 'quiz-123' }
-				contextParams[identifier] = identifierValue
+		// If permissionIdentifier is provided, look up its value from dependencyList
+		// dependencyList stores parent object IDs as { 'permissionIdentifier': idValue }
+		if (
+			permissionIdentifier !== null &&
+			permissionIdentifier !== undefined &&
+			permissionIdentifier !== "project"
+		) {
+			const permissionIdentifierValue =
+				dependencyList.value?.[permissionIdentifier]
+			if (permissionIdentifierValue !== undefined) {
+				// Add the permissionIdentifier value using the permissionIdentifier key as the param name
+				// e.g., permissionIdentifier='form' with dependencyList.form='quiz-123' adds { form: 'quiz-123' }
+				contextParams[permissionIdentifier] = permissionIdentifierValue
 			}
 		}
 		const parsedData = {}
@@ -582,9 +545,9 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 		for (const param of parameters) {
 			delete bodyData[param]
 		}
-		// Also remove identifier from body if it was in data
-		if (identifier && bodyData[identifier] !== undefined) {
-			delete bodyData[identifier]
+		// Also remove permissionIdentifier from body if it was in data
+		if (permissionIdentifier && bodyData[permissionIdentifier] !== undefined) {
+			delete bodyData[permissionIdentifier]
 		}
 
 		try {
@@ -611,20 +574,6 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 			)
 			throw new Error(`${method.toUpperCase()} ${resolvedPath}: ${message}`)
 		}
-
-		// try {
-		// 	const operationConfig = apiOperations.value[identifier][operation];
-		// 	if (!operationConfig) {
-		// 		throw new Error(`Operation not found: ${operation}`);
-		// 	}
-		// 	const response = await apiClient[operationConfig.method](
-		// 		operationConfig.path,
-		// 		data
-		// 	);
-		// 	return response.data;
-		// } catch (error) {
-		// 	throw new Error(`${method} ${endpoint}: ${error.message}`);
-		// }
 	}
 
 	// Utility methods
@@ -643,8 +592,8 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 	function getState(key, fallback = null) {
 		return triggerState.value[key] || fallback
 	}
-	function findDependency(identifier) {
-		return dependencyList.value[identifier]
+	function findDependency(permissionIdentifier) {
+		return dependencyList.value[permissionIdentifier]
 	}
 	function hasPermission(flag) {
 		return permissionFlags.value.includes(flag)
@@ -661,13 +610,65 @@ export const useGxpStore = defineStore("gxp-portal-app", () => {
 	}
 
 	// Standard Socket helper methods
-	function listen(socketName, event, callback) {
-		if (sockets[socketName] && sockets[socketName].listen) {
-			return sockets[socketName].listen(event, callback)
-		} else {
-			console.warn(`Socket not found: ${socketName}`)
-			return () => {}
+	//
+	// Polymorphic — supports two forms:
+	//
+	//   1. listen(socketName, event, callback)
+	//      Subscribes to `event` on the named socket (e.g. 'primary' or a
+	//      dependency identifier whose socket was initialized via
+	//      initializeDependencySockets). This matches the legacy shape.
+	//
+	//   2. listen(eventName, permissionIdentifier, callback)
+	//      Subscribes to an AsyncAPI-defined platform event on the primary
+	//      socket, scoped to a permission identifier from dependencyList
+	//      (or the reserved "project" identifier). Use this for events whose
+	//      `x-triggered-by` matches a callApi operationId.
+	//
+	// Disambiguation: if arg1 names a registered socket we take form 1,
+	// otherwise we fall through to form 2.
+	function listen(arg1, arg2, arg3) {
+		const hasRegisteredSocket =
+			sockets[arg1] && typeof sockets[arg1].listen === "function"
+
+		if (hasRegisteredSocket && typeof arg3 === "function") {
+			return sockets[arg1].listen(arg2, arg3)
+		}
+
+		if (typeof arg3 === "function") {
+			const eventName = arg1
+			const permissionIdentifier = arg2
+			const callback = arg3
+			const primary = socketConnections.primary
+			if (!primary) {
+				console.warn(
+					"[GxP Store] listen(): primary socket not initialized",
+				)
+				return () => {}
+			}
+			if (
+				permissionIdentifier !== "project" &&
+				dependencyList.value?.[permissionIdentifier] === undefined
+			) {
+				console.warn(
+					`[GxP Store] listen("${eventName}", "${permissionIdentifier}"): permission identifier not bound in dependencyList`,
+				)
+			}
+			const handler = (data) => {
+				try {
+					callback(data)
+				} catch (err) {
+					console.error(
+						`[GxP Store] listen callback error for ${eventName}:`,
+						err,
+					)
+				}
+			}
+			primary.on(eventName, handler)
+			return () => primary.off(eventName, handler)
 		}
+
+		console.warn(`Socket not found: ${arg1}`)
+		return () => {}
 	}
 
 	function broadcast(socketName, event, data) {