@microsoft/teams-js 2.50.0 → 2.51.0-beta.0

package/dist/esm/packages/teams-js/dts/internal/responseHandler.d.ts

@@ -20,7 +20,9 @@ export declare abstract class ResponseHandler<SerializedReturnValueFromHost, Des
      */
     abstract deserialize(response: SerializedReturnValueFromHost): DeserializedReturnValueFromHost;
 }
-export type SimpleType = string | number | boolean | null | undefined | SimpleType[];
+export type SimpleType = string | number | boolean | null | undefined | SimpleType[] | {
+    [key: string]: SimpleType;
+};
 /**
  * This class is used for validating and deserializing boolean responses from the host.
  */

package/dist/esm/packages/teams-js/dts/internal/telemetry.d.ts

@@ -47,6 +47,7 @@ export declare const enum ApiName {
     App_NotifySuccess = "app.notifySuccess",
     App_OpenLink = "app.openLink",
     App_RegisterOnThemeChangeHandler = "app.registerOnThemeChangeHandler",
+    App_RegisterOnPromptHandler = "app.registerOnPromptHandler",
     App_RegisterOnContextChangeHandler = "app.registerOnContextChangeHandler",
     AppInitialization_NotifyAppLoaded = "appInitialization.notifyAppLoaded",
     AppInitialization_NotifyExpectedFailure = "appInitialization.notifyExpectedFailure",
@@ -264,6 +265,8 @@ export declare const enum ApiName {
     PrivateAPIs_RegisterUserSettingsChangeHandler = "registerUserSettingsChangeHandler",
     PrivateAPIs_SendCustomMessage = "sendCustomMessage",
     PrivateAPIs_UploadCustomApp = "uploadCustomApp",
+    Plugins_ReceiveMessage = "plugins.receiveMessage",
+    Plugins_SendMessage = "plugins.sendMessage",
     Profile_ShowProfile = "profile.showProfile",
     PublicAPIs_ExecuteDeepLink = "executeDeepLink",
     PublicAPIs_GetContext = "getContext",

package/dist/esm/packages/teams-js/dts/private/index.d.ts

@@ -18,6 +18,7 @@ export * as messageChannels from './messageChannels/messageChannels';
 export * as nestedAppAuthBridge from './nestedAppAuth/nestedAppAuthBridge';
 export * as notifications from './notifications';
 export * as otherAppStateChange from './otherAppStateChange';
+export * as plugins from './plugins';
 export * as remoteCamera from './remoteCamera';
 export * as appEntity from './appEntity';
 export * as teams from './teams/teams';

package/dist/esm/packages/teams-js/dts/private/plugins.d.ts

@@ -0,0 +1,94 @@
+import { SimpleType } from '../internal/responseHandler';
+/**
+ * The type of arguments that can be passed in a {@link PluginMessage}.
+ *
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ * @beta
+ */
+export type PluginMessageArg = SimpleType;
+/**
+ * Indicates whether the plugin capability is available in the current host.
+ *
+ * @remarks
+ * This API validates SDK initialization and then checks runtime capability flags
+ * for `supports.plugins`.
+ *
+ * @returns `true` if the host reports plugin support; otherwise `false`.
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed.
+ *
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ * @beta
+ */
+export declare function isSupported(): boolean;
+/**
+ * Canonical message envelope used for plugin send/receive operations.
+ *
+ * @remarks
+ * Messages are used to communicate between plugin and host.
+ *
+ * @property func - Function/event name for the message.
+ * @property args - Optional JSON payload.
+ * @property correlationId - Optional ID for request/response correlation.
+ *
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ * @beta
+ */
+export type PluginMessage = {
+    func: string;
+    args?: PluginMessageArg;
+    correlationId?: string;
+};
+/**
+ * Sends a plugin message to the host.
+ *
+ * @remarks
+ * The message payload is serialized before transmission to the host.
+ * All payload data must be JSON-safe (see {@link JsonValue}).
+ *
+ * @returns A promise that resolves when the host acknowledges the message.
+ *
+ * @throws Error if SDK initialization has not completed, if the host returns
+ * an error response, or if `func` is missing.
+ *
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ * @beta
+ */
+export declare function sendPluginMessage(message: PluginMessage): Promise<void>;
+/**
+ * Handler signature for incoming plugin messages.
+ *
+ * @param message - Normalized plugin message envelope.
+ *
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ * @beta
+ */
+export type ReceiveMessageHandler = (message: PluginMessage) => void;
+/**
+ * Registers a handler to receive plugin messages from the host.
+ *
+ * @remarks
+ * This API registers the callback under the `plugin.receiveMessage` handler name.
+ * When the host dispatches a plugin message, the supplied handler is invoked with
+ * the received JSON payload.
+ *
+ * @param handler - Callback invoked for each incoming plugin message payload.
+ *
+ * @throws Error if plugin messaging is not supported by the current host.
+ *
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ * @beta
+ */
+export declare function registerPluginMessage(handler: ReceiveMessageHandler): void;

package/dist/esm/packages/teams-js/dts/private/privateAPIs.d.ts

@@ -1,6 +1,8 @@
 import { FilePreviewParameters, UserSettingTypes } from './interfaces';
 export declare function uploadCustomApp(manifestBlob: Blob, onComplete?: (status: boolean, reason?: string) => void): void;
 /**
+ * @deprecated Use {@link plugins.sendPluginMessage} with {@link plugins.registerPluginMessage} and a correlationId-based response pattern.
+ *
  * @hidden
  * Sends a custom action MessageRequest to host or parent window
  *
@@ -9,6 +11,39 @@ export declare function uploadCustomApp(manifestBlob: Blob, onComplete?: (status
  * @param callback - Optionally specify a callback to receive response parameters from the parent
  * @returns id of sent message
  *
+ * @remarks
+ * Prefer the plugin event model for new development. In that model, send a request message
+ * with a unique `correlationId` and listen for a response event with the same `correlationId`.
+ *
+ * Example:
+ * ```ts
+ * // Request side
+ * const correlationId = crypto.randomUUID();
+ *
+ * plugins.registerPluginMessage((message) => {
+ *   if (message.func !== 'example.customAction.response') {
+ *     return;
+ *   }
+ *   if (message.correlationId !== correlationId) {
+ *     return;
+ *   }
+ *
+ *   // This is the response for the request above.
+ *   const response = message.args;
+ *   console.log('Received response', response);
+ * });
+ *
+ * await plugins.sendPluginMessage({
+ *   func: 'example.customAction.request',
+ *   args: { itemId: '12345' },
+ *   correlationId,
+ * });
+ *
+ * // Host side contract example (conceptual):
+ * // On receiving example.customAction.request, send back
+ * // example.customAction.response with the same correlationId.
+ * ```
+ *
  * @internal
  * Limited to Microsoft-internal use
  */

package/dist/esm/packages/teams-js/dts/public/index.d.ts

@@ -1,6 +1,6 @@
 export * as authentication from './authentication';
 export { ChannelType, DialogDimension, FrameContexts, HostClientType, HostName, RenderingSurfaces, TaskModuleDimension, TeamType, UserTeamRole, } from './constants';
-export { ActionInfo, ActionObjectType, AdaptiveCardVersion, AdaptiveCardDialogInfo, BaseActionObject, BotAdaptiveCardDialogInfo, BotUrlDialogInfo, Context, DeepLinkParameters, DialogInfo, DialogSize, EduType, ErrorCode, FileOpenPreference, FrameContext, FrameInfo, HostMemoryMetrics, HostToAppFrameMemoryMetrics, HostToAppPerformanceMetrics, LoadContext, LocaleInfo, M365ContentAction, ResumeContext, SdkError, SecondaryId, SecondaryM365ContentIdName, ShareDeepLinkParameters, TabInformation, TabInstance, TabInstanceParameters, TaskInfo, TeamInformation, UrlDialogInfo, } from './interfaces';
+export { ActionInfo, ActionObjectType, AdaptiveCardVersion, AdaptiveCardDialogInfo, AppState, BaseActionObject, BotAdaptiveCardDialogInfo, BotUrlDialogInfo, Context, DeepLinkParameters, DialogInfo, DialogSize, EduType, ErrorCode, FileOpenPreference, FrameContext, FrameInfo, HostMemoryMetrics, HostToAppFrameMemoryMetrics, HostToAppPerformanceMetrics, LoadContext, LocaleInfo, M365ContentAction, ResumeContext, SdkError, SecondaryId, SecondaryM365ContentIdName, ShareDeepLinkParameters, TabInformation, TabInstance, TabInstanceParameters, TaskInfo, TeamInformation, UrlDialogInfo, } from './interfaces';
 export * as app from './app/app';
 export { AppId } from './appId';
 export * as appPerformanceMetrics from './appPerformanceMetrics';

package/dist/esm/packages/teams-js/dts/public/interfaces.d.ts

@@ -1271,15 +1271,27 @@ export type HostToAppFrameMemoryMetrics = {
      */
     treeLevel: number;
 };
+/**
+ * The state of the app in terms of its lifecycle and caching status, which can impact its performance characteristics and memory usage.
+ */
+export type AppState = 'cached' | 'precached' | 'active';
 /**
  * Memory metrics provided by the host for the app.
  */
 export type HostMemoryMetrics = {
     /**
+     * The current state of the app, which can be 'cached', 'precached', or 'active'. This provides insight into the app's lifecycle stage and can help developers understand the performance characteristics and memory usage of their app in different states.
+     */
+    appState: AppState;
+    /**
+     * @deprecated - Use `appState` instead.
+     *
      * Indicates if the app is in a hidden state to accelerate future launches.
      */
     isCached: boolean;
     /**
+     * @deprecated - Use `appState` instead.
+     *
      * Indicates if the app is in a preloaded state to accelerate its first launch in the session.
      */
     isPrecached: boolean;

package/dist/esm/packages/teams-js/dts/public/runtime.d.ts

@@ -86,6 +86,7 @@ interface IRuntimeV4 extends IBaseRuntime {
             readonly tabs?: {};
         };
         readonly people?: {};
+        readonly plugins?: {};
         readonly permissions?: {};
         readonly profile?: {};
         readonly remoteCamera?: {};

package/dist/esm/packages/teams-js/src/index.js

@@ -1 +1 @@
-export{NotificationTypes,UserSettingTypes,ViewerActionTypes}from"./private/interfaces.js";export{openFilePreview,registerCustomHandler,registerUserSettingsChangeHandler,sendCustomEvent,sendCustomMessage,uploadCustomApp}from"./private/privateAPIs.js";import*as e from"./private/externalAppAuthentication.js";export{e as externalAppAuthentication};export{UserAuthenticationState}from"./private/externalAppAuthentication.js";import*as r from"./private/logs.js";export{r as logs};import*as t from"./private/conversations.js";export{t as conversations};import*as o from"./private/copilot/copilot.js";export{o as copilot};import*as p from"./private/copilot/sidePanelInterfaces.js";export{p as sidePanelInterfaces};import*as i from"./private/externalAppAuthenticationForCEA.js";export{i as externalAppAuthenticationForCEA};import*as a from"./private/externalAppCardActions.js";export{a as externalAppCardActions};import*as s from"./private/externalAppCardActionsForCEA.js";export{s as externalAppCardActionsForCEA};import*as m from"./private/externalAppCardActionsForDA.js";export{m as externalAppCardActionsForDA};import*as n from"./private/externalAppCommands.js";export{n as externalAppCommands};import*as l from"./private/files.js";export{l as files};import*as c from"./private/meetingRoom.js";export{c as meetingRoom};import*as f from"./private/messageChannels/messageChannels.js";export{f as messageChannels};import*as u from"./private/nestedAppAuth/nestedAppAuthBridge.js";export{u as nestedAppAuthBridge};import*as x from"./private/notifications.js";export{x as notifications};import*as j from"./private/otherAppStateChange.js";export{j as otherAppStateChange};import*as d from"./private/remoteCamera.js";export{d as remoteCamera};import*as g from"./private/appEntity.js";export{g as appEntity};import*as b from"./private/teams/teams.js";export{b as teams};import*as v from"./private/videoEffectsEx.js";export{v as videoEffectsEx};import*as A from"./private/hostEntity/hostEntity.js";export{A as hostEntity};import*as C from"./private/store.js";export{C as store};import*as h from"./private/widgetHosting/widgetHosting.js";export{h as widgetHosting};export{ChannelType,DialogDimension,FrameContexts,HostClientType,HostName,RenderingSurfaces,DialogDimension as TaskModuleDimension,TeamType,UserTeamRole}from"./public/constants.js";export{ActionObjectType,EduType,ErrorCode,FileOpenPreference,SecondaryM365ContentIdName}from"./public/interfaces.js";export{AppId}from"./public/appId.js";export{EmailAddress}from"./public/emailAddress.js";export{activateChildProxyingCommunication,getCurrentFeatureFlagsState,overwriteFeatureFlagsState,setFeatureFlagsState}from"./public/featureFlags.js";export{getAdaptiveCardSchemaVersion}from"./public/adaptiveCards.js";export{ChildAppWindow,ParentAppWindow}from"./public/appWindow.js";export{ValidatedSafeString}from"./public/validatedSafeString.js";export{version}from"./public/version.js";export{enablePrintCapability,executeDeepLink,getContext,getMruTabInstances,getTabInstances,initialize,initializeWithFrameContext,print,registerAppButtonClickHandler,registerAppButtonHoverEnterHandler,registerAppButtonHoverLeaveHandler,registerBackButtonHandler,registerBeforeUnloadHandler,registerChangeSettingsHandler,registerFocusEnterHandler,registerFullScreenHandler,registerOnLoadHandler,registerOnThemeChangeHandler,setFrameContext,shareDeepLink}from"./public/publicAPIs.js";export{navigateBack,navigateCrossDomain,navigateToTab,returnFocus}from"./public/navigation.js";export{UUID}from"./public/uuidObject.js";import*as S from"./public/liveShareHost.js";export{S as liveShare};export{LiveShareHost}from"./public/liveShareHost.js";import*as H from"./public/authentication.js";export{H as authentication};import*as F from"./public/app/app.js";export{F as app};import*as y from"./public/appPerformanceMetrics.js";export{y as appPerformanceMetrics};import*as T from"./public/appInstallDialog.js";export{T as appInstallDialog};import*as E from"./public/barCode.js";export{E as barCode};import*as w from"./public/chat.js";export{w as chat};import*as I from"./public/clipboard.js";export{I as clipboard};import*as D from"./public/dialog/dialog.js";export{D as dialog};import*as P from"./public/nestedAppAuth.js";export{P as nestedAppAuth};import*as B from"./public/geoLocation/geoLocation.js";export{B as geoLocation};import*as k from"./public/pages/pages.js";export{k as pages};import*as L from"./public/menus.js";export{L as menus};import*as M from"./public/media.js";export{M as media};import*as U from"./public/secondaryBrowser.js";export{U as secondaryBrowser};import*as O from"./public/location.js";export{O as location};import*as V from"./public/meeting/meeting.js";export{V as meeting};import*as z from"./public/monetization.js";export{z as monetization};import*as R from"./public/calendar.js";export{R as calendar};import*as W from"./public/mail/mail.js";export{W as mail};import*as N from"./public/teamsAPIs.js";export{N as teamsCore};import*as q from"./public/people.js";export{q as people};import*as G from"./public/profile.js";export{G as profile};import*as J from"./public/videoEffects.js";export{J as videoEffects};import*as K from"./public/search.js";export{K as search};import*as Q from"./public/sharing/sharing.js";export{Q as sharing};import*as X from"./public/stageView/stageView.js";export{X as stageView};import*as Y from"./public/visualMedia/visualMedia.js";export{Y as visualMedia};import*as Z from"./public/webStorage.js";export{Z as webStorage};import*as $ from"./public/call.js";export{$ as call};import*as _ from"./public/appInitialization.js";export{_ as appInitialization};import*as ee from"./public/thirdPartyCloudStorage.js";export{ee as thirdPartyCloudStorage};import*as re from"./public/settings.js";export{re as settings};import*as te from"./public/tasks.js";export{te as tasks};import*as oe from"./public/marketplace.js";export{oe as marketplace};import*as pe from"./public/shortcutRelay.js";export{pe as shortcutRelay};
+export{NotificationTypes,UserSettingTypes,ViewerActionTypes}from"./private/interfaces.js";export{openFilePreview,registerCustomHandler,registerUserSettingsChangeHandler,sendCustomEvent,sendCustomMessage,uploadCustomApp}from"./private/privateAPIs.js";import*as e from"./private/externalAppAuthentication.js";export{e as externalAppAuthentication};export{UserAuthenticationState}from"./private/externalAppAuthentication.js";import*as r from"./private/logs.js";export{r as logs};import*as t from"./private/conversations.js";export{t as conversations};import*as o from"./private/copilot/copilot.js";export{o as copilot};import*as p from"./private/copilot/sidePanelInterfaces.js";export{p as sidePanelInterfaces};import*as i from"./private/externalAppAuthenticationForCEA.js";export{i as externalAppAuthenticationForCEA};import*as a from"./private/externalAppCardActions.js";export{a as externalAppCardActions};import*as s from"./private/externalAppCardActionsForCEA.js";export{s as externalAppCardActionsForCEA};import*as m from"./private/externalAppCardActionsForDA.js";export{m as externalAppCardActionsForDA};import*as n from"./private/externalAppCommands.js";export{n as externalAppCommands};import*as l from"./private/files.js";export{l as files};import*as c from"./private/meetingRoom.js";export{c as meetingRoom};import*as f from"./private/messageChannels/messageChannels.js";export{f as messageChannels};import*as u from"./private/nestedAppAuth/nestedAppAuthBridge.js";export{u as nestedAppAuthBridge};import*as x from"./private/notifications.js";export{x as notifications};import*as j from"./private/otherAppStateChange.js";export{j as otherAppStateChange};import*as d from"./private/plugins.js";export{d as plugins};import*as g from"./private/remoteCamera.js";export{g as remoteCamera};import*as b from"./private/appEntity.js";export{b as appEntity};import*as v from"./private/teams/teams.js";export{v as teams};import*as A from"./private/videoEffectsEx.js";export{A as videoEffectsEx};import*as C from"./private/hostEntity/hostEntity.js";export{C as hostEntity};import*as h from"./private/store.js";export{h as store};import*as S from"./private/widgetHosting/widgetHosting.js";export{S as widgetHosting};export{ChannelType,DialogDimension,FrameContexts,HostClientType,HostName,RenderingSurfaces,DialogDimension as TaskModuleDimension,TeamType,UserTeamRole}from"./public/constants.js";export{ActionObjectType,EduType,ErrorCode,FileOpenPreference,SecondaryM365ContentIdName}from"./public/interfaces.js";export{AppId}from"./public/appId.js";export{EmailAddress}from"./public/emailAddress.js";export{activateChildProxyingCommunication,getCurrentFeatureFlagsState,overwriteFeatureFlagsState,setFeatureFlagsState}from"./public/featureFlags.js";export{getAdaptiveCardSchemaVersion}from"./public/adaptiveCards.js";export{ChildAppWindow,ParentAppWindow}from"./public/appWindow.js";export{ValidatedSafeString}from"./public/validatedSafeString.js";export{version}from"./public/version.js";export{enablePrintCapability,executeDeepLink,getContext,getMruTabInstances,getTabInstances,initialize,initializeWithFrameContext,print,registerAppButtonClickHandler,registerAppButtonHoverEnterHandler,registerAppButtonHoverLeaveHandler,registerBackButtonHandler,registerBeforeUnloadHandler,registerChangeSettingsHandler,registerFocusEnterHandler,registerFullScreenHandler,registerOnLoadHandler,registerOnThemeChangeHandler,setFrameContext,shareDeepLink}from"./public/publicAPIs.js";export{navigateBack,navigateCrossDomain,navigateToTab,returnFocus}from"./public/navigation.js";export{UUID}from"./public/uuidObject.js";import*as H from"./public/liveShareHost.js";export{H as liveShare};export{LiveShareHost}from"./public/liveShareHost.js";import*as F from"./public/authentication.js";export{F as authentication};import*as y from"./public/app/app.js";export{y as app};import*as T from"./public/appPerformanceMetrics.js";export{T as appPerformanceMetrics};import*as E from"./public/appInstallDialog.js";export{E as appInstallDialog};import*as w from"./public/barCode.js";export{w as barCode};import*as I from"./public/chat.js";export{I as chat};import*as D from"./public/clipboard.js";export{D as clipboard};import*as P from"./public/dialog/dialog.js";export{P as dialog};import*as B from"./public/nestedAppAuth.js";export{B as nestedAppAuth};import*as k from"./public/geoLocation/geoLocation.js";export{k as geoLocation};import*as L from"./public/pages/pages.js";export{L as pages};import*as M from"./public/menus.js";export{M as menus};import*as U from"./public/media.js";export{U as media};import*as O from"./public/secondaryBrowser.js";export{O as secondaryBrowser};import*as V from"./public/location.js";export{V as location};import*as z from"./public/meeting/meeting.js";export{z as meeting};import*as R from"./public/monetization.js";export{R as monetization};import*as W from"./public/calendar.js";export{W as calendar};import*as N from"./public/mail/mail.js";export{N as mail};import*as q from"./public/teamsAPIs.js";export{q as teamsCore};import*as G from"./public/people.js";export{G as people};import*as J from"./public/profile.js";export{J as profile};import*as K from"./public/videoEffects.js";export{K as videoEffects};import*as Q from"./public/search.js";export{Q as search};import*as X from"./public/sharing/sharing.js";export{X as sharing};import*as Y from"./public/stageView/stageView.js";export{Y as stageView};import*as Z from"./public/visualMedia/visualMedia.js";export{Z as visualMedia};import*as $ from"./public/webStorage.js";export{$ as webStorage};import*as _ from"./public/call.js";export{_ as call};import*as ee from"./public/appInitialization.js";export{ee as appInitialization};import*as re from"./public/thirdPartyCloudStorage.js";export{re as thirdPartyCloudStorage};import*as te from"./public/settings.js";export{te as settings};import*as oe from"./public/tasks.js";export{oe as tasks};import*as pe from"./public/marketplace.js";export{pe as marketplace};import*as ie from"./public/shortcutRelay.js";export{ie as shortcutRelay};

package/dist/esm/packages/teams-js/src/internal/internalAPIs.js

@@ -1 +1 @@
-import{HostClientType as i}from"../public/constants.js";import{ErrorCode as t}from"../public/interfaces.js";import{isRuntimeInitialized as r}from"../public/runtime.js";import{defaultSDKVersionForCompatCheck as e,errorLibraryNotInitialized as n}from"./constants.js";import{GlobalVars as o}from"./globalVars.js";import{getLogger as l}from"./telemetry.js";import{isValidPatternUrl as s}from"./urlPattern.js";import{compareSDKVersions as a}from"./utils.js";const f=l("internal"),c=f.extend("ensureInitializeCalled"),d=f.extend("ensureInitialized");function m(){if(!o.initializeCalled)throw c(n),new Error(n)}function p(i,...t){if(!o.initializeCompleted)throw d("%s. initializeCalled: %s",n,o.initializeCalled.toString()),new Error(n);if(t&&t.length>0){let i=!1;for(let r=0;r<t.length;r++)if(t[r]===o.frameContext){i=!0;break}if(!i)throw new Error(`This call is only allowed in following contexts: ${JSON.stringify(t)}. Current context: "${o.frameContext}".`)}return r(i)}function u(i=e){const t=a(o.clientSupportedSDKVersion,i);return!isNaN(t)&&t>=0}function C(){return o.hostClientType==i.android||o.hostClientType==i.ios||o.hostClientType==i.ipados||o.hostClientType==i.visionOS}function h(i=e){if(!C()){throw{errorCode:t.NOT_SUPPORTED_ON_PLATFORM}}if(!u(i)){throw{errorCode:t.OLD_PLATFORM}}}function w(i){let t=o.additionalValidOrigins.concat(i.filter(i=>"string"==typeof i&&s(i)));const r={};t=t.filter(i=>!r[i]&&(r[i]=!0,!0)),o.additionalValidOrigins=t}export{m as ensureInitializeCalled,p as ensureInitialized,u as isCurrentSDKVersionAtLeast,C as isHostClientMobile,w as processAdditionalValidOrigins,h as throwExceptionIfMobileApiIsNotSupported};
+import{HostClientType as i}from"../public/constants.js";import{ErrorCode as t}from"../public/interfaces.js";import{isRuntimeInitialized as r}from"../public/runtime.js";import{defaultSDKVersionForCompatCheck as e,errorLibraryNotInitialized as n}from"./constants.js";import{GlobalVars as o}from"./globalVars.js";import{getLogger as l}from"./telemetry.js";import{isValidPatternUrl as s}from"./urlPattern.js";import{compareSDKVersions as a}from"./utils.js";const f=l("internal"),c=f.extend("ensureInitializeCalled"),d=f.extend("ensureInitialized");function m(){if(!o.initializeCalled)throw c(n),new Error(n)}function p(i,...t){if(!o.initializeCompleted)throw d("%s. initializeCalled: %s",n,o.initializeCalled.toString()),new Error(n);if(t&&t.length>0){let i=!1;for(let r=0;r<t.length;r++)if(t[r]===o.frameContext){i=!0;break}if(!i){const i=`This call is only allowed in following contexts: ${JSON.stringify(t)}. Current context: "${o.frameContext}".`;throw d(i),new Error(i)}}return r(i)}function u(i=e){const t=a(o.clientSupportedSDKVersion,i);return!isNaN(t)&&t>=0}function C(){return o.hostClientType==i.android||o.hostClientType==i.ios||o.hostClientType==i.ipados||o.hostClientType==i.visionOS}function h(i=e){if(!C()){throw{errorCode:t.NOT_SUPPORTED_ON_PLATFORM}}if(!u(i)){throw{errorCode:t.OLD_PLATFORM}}}function w(i){let t=o.additionalValidOrigins.concat(i.filter(i=>"string"==typeof i&&s(i)));const r={};t=t.filter(i=>!r[i]&&(r[i]=!0,!0)),o.additionalValidOrigins=t}export{m as ensureInitializeCalled,p as ensureInitialized,u as isCurrentSDKVersionAtLeast,C as isHostClientMobile,w as processAdditionalValidOrigins,h as throwExceptionIfMobileApiIsNotSupported};

package/dist/esm/packages/teams-js/src/private/plugins.js

@@ -0,0 +1 @@
+import{__awaiter as e}from"../../../../node_modules/.pnpm/@rollup_plugin-typescript@11.1.6_rollup@4.55.1_tslib@2.8.1_typescript@4.9.5/node_modules/tslib/tslib.es6.js";import{callFunctionInHost as n}from"../internal/communication.js";import{registerHandlerHelper as r}from"../internal/handlers.js";import{ensureInitialized as t}from"../internal/internalAPIs.js";import{getApiVersionTag as i}from"../internal/telemetry.js";import{FrameContexts as s}from"../public/constants.js";import{runtime as o}from"../public/runtime.js";function u(){return t(o)&&!!o.supports.plugins}function l(r){return e(this,void 0,void 0,function*(){if(t(o),!r.func)throw new Error("func is required in PluginMessage.");return n("plugins.sendMessage",[new c(r)],i("v2","plugins.sendMessage"))})}function p(e){r(i("v2","plugins.receiveMessage"),"plugins.receiveMessage",(...n)=>{e(function(e){if(1===e.length&&function(e){if(!e||"object"!=typeof e)return!1;return"string"==typeof e.func}(e[0]))return e[0];const[n,r,t]=e;return{func:"string"==typeof n?n:String(null!=n?n:""),args:r,correlationId:"string"==typeof t?t:void 0}}(n))},Object.values(s),()=>{if(!u())throw new Error("Receiving plugin messages is not supported in the current host.")})}class c{constructor(e){this.message=e}serialize(){return this.message}}export{u as isSupported,p as registerPluginMessage,l as sendPluginMessage};

package/dist/esm/packages/teams-js/src/public/version.js

@@ -1 +1 @@
-const o="2.50.0";export{o as version};
+const t="2.51.0-beta.0";export{t as version};

package/dist/umd/MicrosoftTeams.js

@@ -1070,6 +1070,7 @@ __webpack_require__.d(__webpack_exports__, {
   overwriteFeatureFlagsState: () => (/* reexport */ overwriteFeatureFlagsState),
   pages: () => (/* reexport */ pages_namespaceObject),
   people: () => (/* reexport */ people_namespaceObject),
+  plugins: () => (/* reexport */ plugins_namespaceObject),
   print: () => (/* reexport */ publicAPIs_print),
   profile: () => (/* reexport */ profile_namespaceObject),
   registerAppButtonClickHandler: () => (/* reexport */ registerAppButtonClickHandler),
@@ -1562,6 +1563,15 @@ __webpack_require__.d(otherAppStateChange_namespaceObject, {
   unregisterAppInstallationHandler: () => (unregisterAppInstallationHandler)
 });
 
+// NAMESPACE OBJECT: ./src/private/plugins.ts
+var plugins_namespaceObject = {};
+__webpack_require__.r(plugins_namespaceObject);
+__webpack_require__.d(plugins_namespaceObject, {
+  isSupported: () => (plugins_isSupported),
+  registerPluginMessage: () => (registerPluginMessage),
+  sendPluginMessage: () => (sendPluginMessage)
+});
+
 // NAMESPACE OBJECT: ./src/private/remoteCamera.ts
 var remoteCamera_namespaceObject = {};
 __webpack_require__.r(remoteCamera_namespaceObject);
@@ -4669,7 +4679,7 @@ function isSerializable(arg) {
  * @hidden
  *  Package version.
  */
-const version = "2.50.0";
+const version = "2.51.0-beta.0";
 
 ;// ./src/public/featureFlags.ts
 // All build feature flags are defined inside this object. Any build feature flag must have its own unique getter and setter function. This pattern allows for client apps to treeshake unused code and avoid including code guarded by this feature flags in the final bundle. If this property isn't desired, use the below runtime feature flags object.
@@ -4959,8 +4969,10 @@ function ensureInitialized(runtime, ...expectedFrameContexts) {
             }
         }
         if (!found) {
-            throw new Error(`This call is only allowed in following contexts: ${JSON.stringify(expectedFrameContexts)}. ` +
-                `Current context: "${GlobalVars.frameContext}".`);
+            const errorMessage = `This call is only allowed in following contexts: ${JSON.stringify(expectedFrameContexts)}. ` +
+                `Current context: "${GlobalVars.frameContext}".`;
+            ensureInitializedLogger(errorMessage);
+            throw new Error(errorMessage);
         }
     }
     return isRuntimeInitialized(runtime);
@@ -9301,6 +9313,8 @@ function uploadCustomApp(manifestBlob, onComplete) {
     sendMessageToParent(getApiVersionTag(privateAPIsTelemetryVersionNumber, "uploadCustomApp" /* ApiName.PrivateAPIs_UploadCustomApp */), 'uploadCustomApp', [manifestBlob], onComplete ? onComplete : getGenericOnCompleteHandler());
 }
 /**
+ * @deprecated Use {@link plugins.sendPluginMessage} with {@link plugins.registerPluginMessage} and a correlationId-based response pattern.
+ *
  * @hidden
  * Sends a custom action MessageRequest to host or parent window
  *
@@ -9309,6 +9323,39 @@ function uploadCustomApp(manifestBlob, onComplete) {
  * @param callback - Optionally specify a callback to receive response parameters from the parent
  * @returns id of sent message
  *
+ * @remarks
+ * Prefer the plugin event model for new development. In that model, send a request message
+ * with a unique `correlationId` and listen for a response event with the same `correlationId`.
+ *
+ * Example:
+ * ```ts
+ * // Request side
+ * const correlationId = crypto.randomUUID();
+ *
+ * plugins.registerPluginMessage((message) => {
+ *   if (message.func !== 'example.customAction.response') {
+ *     return;
+ *   }
+ *   if (message.correlationId !== correlationId) {
+ *     return;
+ *   }
+ *
+ *   // This is the response for the request above.
+ *   const response = message.args;
+ *   console.log('Received response', response);
+ * });
+ *
+ * await plugins.sendPluginMessage({
+ *   func: 'example.customAction.request',
+ *   args: { itemId: '12345' },
+ *   correlationId,
+ * });
+ *
+ * // Host side contract example (conceptual):
+ * // On receiving example.customAction.request, send back
+ * // example.customAction.response with the same correlationId.
+ * ```
+ *
  * @internal
  * Limited to Microsoft-internal use
  */
@@ -12185,6 +12232,122 @@ function otherAppStateChange_isSupported() {
     return ensureInitialized(runtime) && runtime.supports.otherAppStateChange ? true : false;
 }
 
+;// ./src/private/plugins.ts
+var plugins_awaiter = (undefined && undefined.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+
+
+
+
+
+
+const pluginTelemetryVersionNumber = "v2" /* ApiVersionNumber.V_2 */;
+/**
+ * Indicates whether the plugin capability is available in the current host.
+ *
+ * @remarks
+ * This API validates SDK initialization and then checks runtime capability flags
+ * for `supports.plugins`.
+ *
+ * @returns `true` if the host reports plugin support; otherwise `false`.
+ *
+ * @throws Error if {@linkcode app.initialize} has not successfully completed.
+ *
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ * @beta
+ */
+function plugins_isSupported() {
+    return ensureInitialized(runtime) && !!runtime.supports.plugins;
+}
+/**
+ * Sends a plugin message to the host.
+ *
+ * @remarks
+ * The message payload is serialized before transmission to the host.
+ * All payload data must be JSON-safe (see {@link JsonValue}).
+ *
+ * @returns A promise that resolves when the host acknowledges the message.
+ *
+ * @throws Error if SDK initialization has not completed, if the host returns
+ * an error response, or if `func` is missing.
+ *
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ * @beta
+ */
+function sendPluginMessage(message) {
+    return plugins_awaiter(this, void 0, void 0, function* () {
+        ensureInitialized(runtime);
+        if (!message.func) {
+            throw new Error('func is required in PluginMessage.');
+        }
+        return callFunctionInHost("plugins.sendMessage" /* ApiName.Plugins_SendMessage */, [new SerializablePluginMessage(message)], getApiVersionTag(pluginTelemetryVersionNumber, "plugins.sendMessage" /* ApiName.Plugins_SendMessage */));
+    });
+}
+/**
+ * Registers a handler to receive plugin messages from the host.
+ *
+ * @remarks
+ * This API registers the callback under the `plugin.receiveMessage` handler name.
+ * When the host dispatches a plugin message, the supplied handler is invoked with
+ * the received JSON payload.
+ *
+ * @param handler - Callback invoked for each incoming plugin message payload.
+ *
+ * @throws Error if plugin messaging is not supported by the current host.
+ *
+ * @hidden
+ * @internal
+ * Limited to Microsoft-internal use
+ * @beta
+ */
+function registerPluginMessage(handler) {
+    registerHandlerHelper(getApiVersionTag(pluginTelemetryVersionNumber, "plugins.receiveMessage" /* ApiName.Plugins_ReceiveMessage */), "plugins.receiveMessage" /* ApiName.Plugins_ReceiveMessage */, (...incoming) => {
+        handler(normalizePluginInboundMessage(incoming));
+    }, Object.values(FrameContexts), () => {
+        if (!plugins_isSupported()) {
+            throw new Error('Receiving plugin messages is not supported in the current host.');
+        }
+    });
+}
+class SerializablePluginMessage {
+    constructor(message) {
+        this.message = message;
+    }
+    serialize() {
+        return this.message;
+    }
+}
+function normalizePluginInboundMessage(incoming) {
+    // New envelope format: { func, args, correlationId?, schemaVersion? }
+    if (incoming.length === 1 && isPluginInboundMessage(incoming[0])) {
+        return incoming[0];
+    }
+    const [func, args, correlationId] = incoming;
+    return {
+        func: typeof func === 'string' ? func : String(func !== null && func !== void 0 ? func : ''),
+        args: args,
+        correlationId: typeof correlationId === 'string' ? correlationId : undefined,
+    };
+}
+function isPluginInboundMessage(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const message = value;
+    return typeof message.func === 'string';
+}
+
 ;// ./src/private/remoteCamera.ts
 /**
  * @hidden
@@ -14649,6 +14812,8 @@ class SerializableContentSizeArgs {
 
 
 
+
+