diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/_index.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/_index.md index f737de2e4d9..b8da9068ae0 100644 --- a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/_index.md +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/_index.md @@ -55,3 +55,5 @@ The following how-tos help you get started: * [How to Listen for Connection Changes](/apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-controller-api/) * [How to Access Runtime Constants](/apidocs-mxsdk/apidocs/web-extensibility-api-11/runtime-configuration-api/) * [How to Use Extension Permissions in Overview Pane](/apidocs-mxsdk/apidocs/web-extensibility-api-11/extension-permissions/) +* [How to Query User Authentication](/apidocs-mxsdk/apidocs/web-extensibility-api-11/user-authentication-api/) +* [How to Set the Maia Chat Prompt](/apidocs-mxsdk/apidocs/web-extensibility-api-11/maia-chat-api/) diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/maia-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/maia-api.md new file mode 100644 index 00000000000..009b1b3dff8 --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/maia-api.md @@ -0,0 +1,76 @@ +--- +title: "Set the Maia Chat Prompt Using Web API" +linktitle: "Maia Chat" +url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/maia-chat-api/ +description: "Describes how to populate the Maia Agent chat prompt from an extension in Studio Pro using the Web Extensibility API." +--- + +## Introduction + +This document describes how to use an extension in Studio Pro to populate the Maia Agent chat prompt for the user to review and send. For example, an extension can add text selected by the user and send it to Maia as a prompt. + +The Maia chat API is available to extensions through `studioPro.ai.chat`. + +## Prerequisites + +Before starting this how-to, complete the following prerequisites: + +* This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). Complete that how-to before starting this one. +* Make sure you are familiar with creating menus as described in [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu-api/). + +## Setting the Maia Chat Prompt + +With the Maia Chat API, you can set a prompt text in the Maia Agent chat. + +To do this, replace your `src/main/index.ts` file with the following text: + +```typescript +import { IComponent, getStudioProApi } from "@mendix/extensions-api"; + +export const component: IComponent = { + async loaded(componentContext) { + const studioPro = getStudioProApi(componentContext); + + const maiaChatApi = studioPro.ai.chat; + const menuId = "set-maia-prompt-menu"; + + await studioPro.ui.extensionsMenu.add({ + menuId, + caption: "Ask Maia about my app", + action: async () => { + await maiaChatApi.setChatPrompt("Explain what this app does and suggest improvements.", true); + } + }); + } +}; +``` + +This code: + +* Uses `maiaChatApi` from `studioPro.ai.chat` to access the Maia Chat API +* Adds a menu item named *Ask Maia about my app* that calls `setChatPrompt` to populate the Maia Agent chat input and sends the prompt to Maia without user review + +You can also populate the prompt with text the user selects in your own editor UI, for example, from a context-menu action on a text area: + +```typescript +const sendToMaiaHandler = async (textarea: HTMLTextAreaElement | null) => { + if (textarea) { + await studioPro.ai.chat.setChatPrompt(textarea.value, false); + } +}; +``` +The value `false` allows the user to review the text and send it themselves in the Maia chat window. + +## Maia Chat API + +The `setChatPrompt` API provides a method that allows users to interact with the Maia Agent chat. + +### Setting the Chat Prompt + +The `setChatPrompt` method takes a `prompt` string to populate the Maia Agent chat input and an `autoSend` to control whether the prompt is automatically send to the Maia chat. Set `autoSend` to `true` to send the prompt automatically, or `false` to let the user review, edit, and send it. If the Maia tab is not open, the method opens it and makes it active. + +## Extensibility Feedback + +If you would like to provide additional feedback, you can complete a short [survey](https://survey.alchemer.eu/s3/90801191/Extensibility-Feedback). + +Any feedback is appreciated. diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/user-authentication-api.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/user-authentication-api.md new file mode 100644 index 00000000000..de0431edc99 --- /dev/null +++ b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/extensibility-api/web/web-extensions-howtos/user-authentication-api.md @@ -0,0 +1,145 @@ +--- +title: "Query User Authentication Using Web API" +linktitle: "User Authentication" +url: /apidocs-mxsdk/apidocs/web-extensibility-api-11/user-authentication-api/ +description: "Describes how to query the signed-in user's authentication state and profile in Studio Pro using the Web Extensibility API." +--- + +## Introduction + +This document describes how to query the signed-in user's authentication state and profile in Studio Pro, and how to react to the user signing in or out. + +The user authentication API is available to extensions through `studioPro.ui.userAuthentication`. It lets you check whether a user is signed in, retrieve the user's profile information, and subscribe to `signedIn` and `signedOut` events. + +## Prerequisites + +Before starting this how-to, complete the following prerequisites: + +* This how-to uses the results of [Get Started with the Web Extensibility API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/getting-started/). Complete that how-to before starting this one. +* Make sure you are familiar with creating menus as described in [Create a Menu Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/menu-api/), message boxes as described in [Show a Message Box Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/messagebox-api/), and notifications as described in [Show a Pop-up Notification Using Web API](/apidocs-mxsdk/apidocs/web-extensibility-api-11/notification-api/). + +## Showing the User's Authentication State + +With the user authentication API, you can create a menu item that shows whether a user is currently signed in and, when signed in, displays the user's profile details. You also subscribe to the `signedIn` and `signedOut` events to show a notification whenever the authentication state changes. + +Replace your `src/main/index.ts` file with the following text: + +```typescript +import { IComponent, Menu, getStudioProApi } from "@mendix/extensions-api"; + +export const component: IComponent = { + async loaded(componentContext) { + const studioPro = getStudioProApi(componentContext); + + const userAuthenticationApi = studioPro.ui.userAuthentication; + const menuApi = studioPro.ui.extensionsMenu; + const messageBoxApi = studioPro.ui.messageBoxes; + const notificationsApi = studioPro.ui.notifications; + + const menuId = "user-authentication-menu"; + + // React to the user signing in. + userAuthenticationApi.addEventListener("signedIn", async () => { + const profileResult = await userAuthenticationApi.getUserProfile(); + const displayName = profileResult.result === "success" ? profileResult.profile.displayName : "unknown user"; + + await notificationsApi.show({ + title: "Signed in", + message: `User ${displayName} signed in`, + displayDurationInSeconds: 4 + }); + }); + + // React to the user signing out. + userAuthenticationApi.addEventListener("signedOut", async () => { + await notificationsApi.show({ + title: "Signed out", + message: "User signed out", + displayDurationInSeconds: 4 + }); + }); + + const menu: Menu = { + caption: "Current user authentication", + menuId, + action: async () => { + const isSignedIn = await userAuthenticationApi.isSignedIn(); + + if (!isSignedIn) { + await messageBoxApi.show("info", "Not signed in"); + return; + } + + const profileResult = await userAuthenticationApi.getUserProfile(); + + if (profileResult.result === "success") { + await messageBoxApi.show( + "info", + `Display name: ${profileResult.profile.displayName}\nUsername: ${profileResult.profile.userName}` + ); + } + } + }; + + await menuApi.add(menu); + } +}; +``` + +This code: + +* Uses `userAuthenticationApi` from `studioPro.ui.userAuthentication` to access the user authentication API +* Subscribes to the `signedIn` event to show a notification with the user's display name whenever a user signs in +* Subscribes to the `signedOut` event to show a notification whenever a user signs out +* Adds a menu item named **Current user authentication** that checks `isSignedIn()` and, when a user is signed in, shows the user's display name and username in a message box + +## User Authentication API + +This API provides events and methods that relate to the signed-in user's authentication state and profile: + +* `signedIn` +* `signedOut` +* `isSignedIn` +* `getUserProfile` + +| Event | Description | Payload | +|--------------|-------------------------------|----------------| +| `signedIn` | Triggers when a user signs in. | Empty object | +| `signedOut` | Triggers when a user signs out. | Empty object | + +### `UserProfile` Properties + +| Property | Type | Description | +|---------------|--------|--------------------------------------------| +| `userName` | string | The user's username. | +| `displayName` | string | The user's display name. | +| `avatarUrl` | string | A URL pointing to the user's avatar image. | + +### How to Listen to an Event + +```typescript +studioPro.ui.userAuthentication.addEventListener("signedIn", async () => { + ... +} +studioPro.ui.userAuthentication.addEventListener("signedOut", async () => { + ... +} +``` + +### Checking Whether a User Is Signed In + +This API provides a `isSignedIn` method that returns a `Promise` that resolves to `true` when a user is currently signed in to Studio Pro, and `false` if they are not. + +### Getting the User Profile + +This API provides a `getUserProfile` method that returns a `Promise` describing the signed-in user's profile. The result is a discriminated union on the `result` property: + +* `{ result: "error" }` – the profile could not be retrieved +* `{ result: "userNotSignedIn" }` – no user is currently signed in +* `{ result: "success"; profile: UserProfile }` – the profile was retrieved successfully, where `UserProfile` contains the properties listed above + +## Extensibility Feedback + +If you would like to provide additional feedback, you can complete a short [survey](https://survey.alchemer.eu/s3/90801191/Extensibility-Feedback). + +Any feedback is appreciated. diff --git a/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md b/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md index d59cbe285ef..3ff16a7189e 100644 --- a/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md +++ b/content/en/docs/releasenotes/studio-pro/web-extensibility-api.md @@ -8,6 +8,17 @@ numberless_headings: true These release notes cover changes to the [Extensibility API for Web Developers](/apidocs-mxsdk/apidocs/extensibility-api/). +## Version 11.16.0 + +### New Features + +* We added a new user authentication API (`studioPro.ui.userAuthentication`) to check the signed-in state (`isSignedIn`), retrieve the user's profile information (`getUserProfile`), and subscribe to `signedIn`/`signedOut` events. +* We added a new API for interacting with the Maia agent chat (`studioPro.ai.chat`) to prefill the Maia chat window with input text and either let the user review it before sending it or automatically send it. + +### Fixes + +* We fixed a bug that caused permissions to be missing from the Extensions Overview tab when using an extension created with an older version of Studio Pro. + ## Version 11.15.0 ### New Features