@microsoft/teams-js 2.28.1-beta.0 → 2.29.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -275,6 +275,72 @@ export interface UserJoinedTeamsInformation {
275
275
  */
276
276
  userJoinedTeams: TeamInformation[];
277
277
  }
278
+ /**
279
+ * @beta
280
+ * @hidden
281
+ * The types for ActionOpenUrl
282
+ *
283
+ * @internal
284
+ * Limited to Microsoft-internal use
285
+ */
286
+ export enum ActionOpenUrlType {
287
+ DeepLinkDialog = "DeepLinkDialog",
288
+ DeepLinkOther = "DeepLinkOther",
289
+ DeepLinkStageView = "DeepLinkStageView",
290
+ GenericUrl = "GenericUrl"
291
+ }
292
+ /**
293
+ * @beta
294
+ * @hidden
295
+ * Error that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
296
+ * and IExternalAppCardActionForCEAService.handleActionOpenUrl
297
+ *
298
+ * @internal
299
+ * Limited to Microsoft-internal use
300
+ */
301
+ export interface ActionOpenUrlError {
302
+ errorCode: ActionOpenUrlErrorCode;
303
+ message?: string;
304
+ }
305
+ /**
306
+ * @beta
307
+ * @hidden
308
+ * Error codes that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
309
+ * and IExternalAppCardActionForCEAService.handleActionOpenUrl
310
+ *
311
+ * @internal
312
+ * Limited to Microsoft-internal use
313
+ */
314
+ export enum ActionOpenUrlErrorCode {
315
+ INTERNAL_ERROR = "INTERNAL_ERROR",
316
+ INVALID_LINK = "INVALID_LINK",
317
+ NOT_SUPPORTED = "NOT_SUPPORTED"
318
+ }
319
+ /**
320
+ * @beta
321
+ * @hidden
322
+ * The payload that is used when executing an Adaptive Card Action.Submit
323
+ *
324
+ * @internal
325
+ * Limited to Microsoft-internal use
326
+ */
327
+ export interface IAdaptiveCardActionSubmit {
328
+ id: string;
329
+ data: string | Record<string, unknown>;
330
+ }
331
+ /**
332
+ * @beta
333
+ * @hidden
334
+ * Error that can be thrown from IExternalAppCardActionService.handleActionSubmit
335
+ * and IExternalAppCardActionForCEAService.handleActionSubmit
336
+ *
337
+ * @internal
338
+ * Limited to Microsoft-internal use
339
+ */
340
+ export interface ActionSubmitError {
341
+ errorCode: ExternalAppErrorCode;
342
+ message?: string;
343
+ }
278
344
 
279
345
  export function uploadCustomApp(manifestBlob: Blob, onComplete?: (status: boolean, reason?: string) => void): void;
280
346
  /**
@@ -867,80 +933,84 @@ export namespace externalAppCardActions {
867
933
  GenericUrl = "GenericUrl"
868
934
  }
869
935
  /**
936
+ * @beta
870
937
  * @hidden
871
- * Error that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
872
- *
938
+ * Delegates an Adaptive Card Action.Submit request to the host for the application with the provided app ID
873
939
  * @internal
874
940
  * Limited to Microsoft-internal use
941
+ * @param appId ID of the application the request is intended for. This must be a UUID
942
+ * @param actionSubmitPayload The Adaptive Card Action.Submit payload
943
+ * @param cardActionsConfig The card actions configuration. This indicates which subtypes should be handled by this API
944
+ * @returns Promise that resolves when the request is completed and rejects with ActionSubmitError if the request fails
875
945
  */
876
- interface ActionOpenUrlError {
877
- errorCode: ActionOpenUrlErrorCode;
878
- message?: string;
879
- }
946
+ function processActionSubmit(appId: string, actionSubmitPayload: IAdaptiveCardActionSubmit): Promise<void>;
880
947
  /**
948
+ * @beta
881
949
  * @hidden
882
- * Error codes that can be thrown from IExternalAppCardActionService.handleActionOpenUrl
950
+ * Delegates an Adaptive Card Action.OpenUrl request to the host for the application with the provided app ID.
951
+ * If `fromElement` is not provided, the information from the manifest is used to determine whether the URL can
952
+ * be processed by the host. Deep link URLs for plugins are not supported and will result in an error.
883
953
  * @internal
884
954
  * Limited to Microsoft-internal use
955
+ * @param appId ID of the application the request is intended for. This must be a UUID
956
+ * @param url The URL to open
957
+ * @param fromElement The element on behalf of which the M365 app is making the request.
958
+ * @returns Promise that resolves to ActionOpenUrlType indicating the type of URL that was opened on success and rejects with ActionOpenUrlError if the request fails
885
959
  */
886
- enum ActionOpenUrlErrorCode {
887
- INTERNAL_ERROR = "INTERNAL_ERROR",
888
- INVALID_LINK = "INVALID_LINK",
889
- NOT_SUPPORTED = "NOT_SUPPORTED"
890
- }
960
+ function processActionOpenUrl(appId: string, url: URL, fromElement?: {
961
+ name: 'composeExtensions' | 'plugins';
962
+ }): Promise<ActionOpenUrlType>;
891
963
  /**
892
964
  * @hidden
893
- * The payload that is used when executing an Adaptive Card Action.Submit
894
- * @internal
895
- * Limited to Microsoft-internal use
896
- */
897
- interface IAdaptiveCardActionSubmit {
898
- id: string;
899
- data: string | Record<string, unknown>;
900
- }
901
- /**
965
+ * Checks if the externalAppCardActions capability is supported by the host
966
+ * @returns boolean to represent whether externalAppCardActions capability is supported
902
967
  *
903
- * @hidden
904
- * Error that can be thrown from IExternalAppCardActionService.handleActionSubmit
968
+ * @throws Error if {@linkcode app.initialize} has not successfully completed
905
969
  *
906
970
  * @internal
907
971
  * Limited to Microsoft-internal use
908
972
  */
909
- interface ActionSubmitError {
910
- errorCode: ExternalAppErrorCode;
911
- message?: string;
912
- }
973
+ function isSupported(): boolean;
974
+ }
975
+
976
+ /**
977
+ * @beta
978
+ * @hidden
979
+ * Namespace to delegate adaptive card action for Custom Engine Agent execution to the host
980
+ * @internal
981
+ * Limited to Microsoft-internal use
982
+ */
983
+ export namespace externalAppCardActionsForCEA {
913
984
  /**
914
985
  * @beta
915
986
  * @hidden
916
- * Delegates an Adaptive Card Action.Submit request to the host for the application with the provided app ID
987
+ * Delegates an Adaptive Card Action.OpenUrl request to the host for the application with the provided app ID.
917
988
  * @internal
918
989
  * Limited to Microsoft-internal use
919
990
  * @param appId ID of the application the request is intended for. This must be a UUID
920
- * @param actionSubmitPayload The Adaptive Card Action.Submit payload
921
- * @param cardActionsConfig The card actions configuration. This indicates which subtypes should be handled by this API
922
- * @returns Promise that resolves when the request is completed and rejects with ActionSubmitError if the request fails
991
+ * @param conversationId To tell the bot what conversation the calls are coming from
992
+ * @param url The URL to open
993
+ * @throws Error if the response has not successfully completed
994
+ * @returns Promise that resolves to ActionOpenUrlType indicating the type of URL that was opened on success and rejects with ActionOpenUrlError if the request fails
923
995
  */
924
- function processActionSubmit(appId: string, actionSubmitPayload: IAdaptiveCardActionSubmit): Promise<void>;
996
+ function processActionOpenUrl(appId: AppId, conversationId: string, url: URL): Promise<ActionOpenUrlType>;
925
997
  /**
926
998
  * @beta
927
999
  * @hidden
928
- * Delegates an Adaptive Card Action.OpenUrl request to the host for the application with the provided app ID.
929
- * If `fromElement` is not provided, the information from the manifest is used to determine whether the URL can
930
- * be processed by the host. Deep link URLs for plugins are not supported and will result in an error.
1000
+ * Delegates an Adaptive Card Action.Submit request to the host for the application with the provided app ID
931
1001
  * @internal
932
1002
  * Limited to Microsoft-internal use
933
1003
  * @param appId ID of the application the request is intended for. This must be a UUID
934
- * @param url The URL to open
935
- * @param fromElement The element on behalf of which the M365 app is making the request.
936
- * @returns Promise that resolves to ActionOpenUrlType indicating the type of URL that was opened on success and rejects with ActionOpenUrlError if the request fails
1004
+ * @param conversationId To tell the bot what conversation the calls are coming from
1005
+ * @param actionSubmitPayload The Adaptive Card Action.Submit payload
1006
+ * @throws Error if host notifies of an error
1007
+ * @returns Promise that resolves when the request is completed and rejects with ActionSubmitError if the request fails
937
1008
  */
938
- function processActionOpenUrl(appId: string, url: URL, fromElement?: {
939
- name: 'composeExtensions' | 'plugins';
940
- }): Promise<ActionOpenUrlType>;
1009
+ function processActionSubmit(appId: AppId, conversationId: string, actionSubmitPayload: IAdaptiveCardActionSubmit): Promise<void>;
941
1010
  /**
1011
+ * @beta
942
1012
  * @hidden
943
- * Checks if the externalAppCardActions capability is supported by the host
1013
+ * Checks if the externalAppCardActionsForCEA capability is supported by the host
944
1014
  * @returns boolean to represent whether externalAppCardActions capability is supported
945
1015
  *
946
1016
  * @throws Error if {@linkcode app.initialize} has not successfully completed
@@ -5503,7 +5573,8 @@ export namespace app {
5503
5573
  * However, there are some older internal/hard-coded apps which violate this schema and use names like
5504
5574
  * com.microsoft.teamspace.tab.youtube. For compatibility with these legacy apps, we unfortunately cannot
5505
5575
  * securely and completely validate app ids as UUIDs. Based on this, the validation is limited to checking
5506
- * for script tags, length, and non-printable characters.
5576
+ * for script tags, length, and non-printable characters. Validation will be updated in the future to ensure
5577
+ * the app id is a valid UUID as legacy apps update.
5507
5578
  */
5508
5579
  export class AppId {
5509
5580
  /**
@@ -6276,8 +6347,9 @@ export namespace pages {
6276
6347
  *
6277
6348
  * @param params Parameters for the navigation
6278
6349
  * @returns a `Promise` that will resolve if the navigation was successful or reject if it was not
6350
+ * @throws `Error` if the app ID is not valid or `params.webUrl` is defined but not a valid URL
6279
6351
  */
6280
- function navigateToApp(params: NavigateToAppParams): Promise<void>;
6352
+ function navigateToApp(params: AppNavigationParameters | NavigateToAppParams): Promise<void>;
6281
6353
  /**
6282
6354
  * Shares a deep link that a user can use to navigate back to a specific state in this page.
6283
6355
  * Please note that this method does not yet work on mobile hosts.
@@ -6301,7 +6373,10 @@ export namespace pages {
6301
6373
  */
6302
6374
  function isSupported(): boolean;
6303
6375
  /**
6304
- * Parameters for the NavigateToApp API
6376
+ * @deprecated
6377
+ * This interface has been deprecated in favor of a more type-safe interface using {@link pages.AppNavigationParameters}
6378
+ *
6379
+ * Parameters for the {@link pages.navigateToApp} function
6305
6380
  */
6306
6381
  interface NavigateToAppParams {
6307
6382
  /**
@@ -6331,6 +6406,38 @@ export namespace pages {
6331
6406
  */
6332
6407
  chatId?: string;
6333
6408
  }
6409
+ /**
6410
+ * Type-safer version of parameters for the {@link pages.navigateToApp} function
6411
+ */
6412
+ interface AppNavigationParameters {
6413
+ /**
6414
+ * ID of the app to navigate to
6415
+ */
6416
+ appId: AppId;
6417
+ /**
6418
+ * Developer-defined ID of the page to navigate to within the app (formerly called `entityId`)
6419
+ */
6420
+ pageId: string;
6421
+ /**
6422
+ * Fallback URL to open if the navigation cannot be completed within the host (e.g., if the target app is not installed)
6423
+ */
6424
+ webUrl?: URL;
6425
+ /**
6426
+ * Developer-defined ID describing the content to navigate to within the page. This ID is passed to the application
6427
+ * via the {@link app.PageInfo.subPageId} property on the {@link app.Context} object (retrieved by calling {@link app.getContext})
6428
+ */
6429
+ subPageId?: string;
6430
+ /**
6431
+ * For apps installed as a channel tab, this ID can be supplied to indicate in which Teams channel the app should be opened
6432
+ * This property has no effect in hosts where apps cannot be opened in channels
6433
+ */
6434
+ channelId?: string;
6435
+ /**
6436
+ * Optional ID of the chat or meeting where the app should be opened
6437
+ * This property has no effect in hosts where apps cannot be opened in chats or meetings
6438
+ */
6439
+ chatId?: string;
6440
+ }
6334
6441
  /**
6335
6442
  * Provides APIs for querying and navigating between contextual tabs of an application. Unlike personal tabs,
6336
6443
  * contextual tabs are pages associated with a specific context, such as channel or chat.
@@ -6642,6 +6749,9 @@ export namespace pages {
6642
6749
  function isSupported(): boolean;
6643
6750
  }
6644
6751
  }
6752
+ export function isAppNavigationParametersObject(obj: pages.AppNavigationParameters | pages.NavigateToAppParams): obj is pages.AppNavigationParameters;
6753
+ export function convertNavigateToAppParamsToAppNavigationParameters(params: pages.NavigateToAppParams): pages.AppNavigationParameters;
6754
+ export function convertAppNavigationParametersToNavigateToAppParams(params: pages.AppNavigationParameters): pages.NavigateToAppParams;
6645
6755
 
6646
6756
  /** onComplete function type */
6647
6757
  export type onCompleteFunctionType = (status: boolean, reason?: string) => void;