@microsoft/teamsfx 1.2.1-rc.1 → 2.0.0-alpha.585cd02ba.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.
@@ -116,6 +116,18 @@ export declare class ApiKeyProvider implements AuthProvider {
116
116
  */
117
117
  export declare class AppCredential implements TokenCredential {
118
118
  private readonly msalClient;
119
+ /**
120
+ * Constructor of AppCredential.
121
+ *
122
+ * @remarks
123
+ * Only works in in server side.
124
+ *
125
+ * @param {AppCredentialAuthConfig} authConfig - The authentication configuration.
126
+ *
127
+ * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret or tenant id is not found in config.
128
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
129
+ */
130
+ constructor(authConfig: AppCredentialAuthConfig);
119
131
  /**
120
132
  * Constructor of AppCredential.
121
133
  *
@@ -163,6 +175,11 @@ export declare class AppCredential implements TokenCredential {
163
175
  private loadAndValidateConfig;
164
176
  }
165
177
 
178
+ /**
179
+ * Authentication configuration for AppCredential used in node environment
180
+ */
181
+ export declare type AppCredentialAuthConfig = OnBehalfOfCredentialAuthConfig;
182
+
166
183
  /**
167
184
  * Authentication related configuration.
168
185
  */
@@ -287,7 +304,9 @@ export declare interface BotSsoConfig {
287
304
  * The list of scopes for which the token will have access
288
305
  */
289
306
  scopes: string[];
290
- } & AuthenticationConfiguration;
307
+ } & ((OnBehalfOfCredentialAuthConfig & {
308
+ initiateLoginEndpoint: string;
309
+ }) | AuthenticationConfiguration);
291
310
  dialog?: {
292
311
  /**
293
312
  * Custom sso execution activity handler class which should implement the interface {@link BotSsoExecutionActivityHandler}. If not provided, it will use {@link DefaultBotSsoExecutionActivityHandler} by default
@@ -392,1930 +411,2102 @@ export declare class BotSsoExecutionDialog extends ComponentDialog {
392
411
  private commandMapping;
393
412
  /**
394
413
  * Creates a new instance of the BotSsoExecutionDialog.
395
- * @param dedupStorage Helper storage to remove duplicated messages
396
- * @param settings The list of scopes for which the token will have access
397
- * @param teamsfx {@link TeamsFx} instance for authentication
398
- */
399
- constructor(dedupStorage: Storage_2, ssoPromptSettings: TeamsBotSsoPromptSettings, teamsfx: TeamsFx, dialogName?: string);
400
- /**
401
- * Add TeamsFxBotSsoCommandHandler instance
402
- * @param handler {@link BotSsoExecutionDialogHandler} callback function
403
- * @param triggerPatterns The trigger pattern
404
- */
405
- addCommand(handler: BotSsoExecutionDialogHandler, triggerPatterns: TriggerPatterns): void;
406
- private getCommandHash;
407
- /**
408
- * The run method handles the incoming activity (in the form of a DialogContext) and passes it through the dialog system.
409
- *
410
- * @param context The context object for the current turn.
411
- * @param accessor The instance of StatePropertyAccessor for dialog system.
412
- */
413
- run(context: TurnContext, accessor: StatePropertyAccessor): Promise<void>;
414
- private getActivityText;
415
- private commandRouteStep;
416
- private ssoStep;
417
- private dedupStep;
418
- /**
419
- * Called when the component is ending.
420
- *
421
- * @param context Context for the current turn of conversation.
422
- */
423
- protected onEndDialog(context: TurnContext): Promise<void>;
424
- /**
425
- * If a user is signed into multiple Teams clients, the Bot might receive a "signin/tokenExchange" from each client.
426
- * Each token exchange request for a specific user login will have an identical activity.value.Id.
427
- * Only one of these token exchange requests should be processed by the bot. For a distributed bot in production,
428
- * this requires a distributed storage to ensure only one token exchange is processed.
429
- * @param context Context for the current turn of conversation.
430
- * @returns boolean value indicate whether the message should be removed
431
- */
432
- private shouldDedup;
433
- private getStorageKey;
434
- private matchPattern;
435
- private isPatternMatched;
436
- private getMatchesCommandId;
437
- /**
438
- * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
439
- * @param dc dialog context
440
- * @throws {@link ErrorCode|ChannelNotSupported} if bot channel is not MS Teams
441
- * @internal
442
- */
443
- private ensureMsTeamsChannel;
444
- }
445
-
446
- export declare type BotSsoExecutionDialogHandler = (context: TurnContext, tokenResponse: TeamsBotSsoPromptTokenResponse, message: CommandMessage) => Promise<void>;
447
-
448
- /**
449
- * A card action bot to respond to adaptive card universal actions.
450
- */
451
- export declare class CardActionBot {
452
- private readonly adapter;
453
- private middleware;
454
- /**
455
- * Creates a new instance of the `CardActionBot`.
456
- *
457
- * @param adapter The bound `BotFrameworkAdapter`.
458
- * @param options - initialize options
459
- */
460
- constructor(adapter: BotFrameworkAdapter, options?: CardActionOptions);
461
- /**
462
- * Registers a card action handler to the bot.
463
- * @param actionHandler A card action handler to be registered.
464
- */
465
- registerHandler(actionHandler: TeamsFxAdaptiveCardActionHandler): void;
466
- /**
467
- * Registers card action handlers to the bot.
468
- * @param actionHandlers A set of card action handlers to be registered.
469
- */
470
- registerHandlers(actionHandlers: TeamsFxAdaptiveCardActionHandler[]): void;
471
- }
472
-
473
- /**
474
- * Options to initialize {@link CardActionBot}.
475
- */
476
- export declare interface CardActionOptions {
477
- /**
478
- * The action handlers to registered with the action bot. Each command should implement the interface {@link TeamsFxAdaptiveCardActionHandler} so that it can be correctly handled by this bot.
479
- */
480
- actions?: TeamsFxAdaptiveCardActionHandler[];
481
- }
482
-
483
- /**
484
- * Provider that handles Certificate authentication
485
- */
486
- export declare class CertificateAuthProvider implements AuthProvider {
487
- private certOption;
488
- /**
489
- *
490
- * @param { SecureContextOptions } certOption - information about the cert used in http requests
491
- *
492
- * @throws {@link ErrorCode|InvalidParameter} - when cert option is empty.
493
- */
494
- constructor(certOption: SecureContextOptions);
495
- /**
496
- * Adds authentication info to http requests.
497
- *
498
- * @param { AxiosRequestConfig } config - Contains all the request information and can be updated to include extra authentication info.
499
- * Refer https://axios-http.com/docs/req_config for detailed document.
500
- *
501
- * @returns Updated axios request config.
502
- *
503
- * @throws {@link ErrorCode|InvalidParameter} - when custom httpsAgent in the request has duplicate properties with certOption provided in constructor.
504
- */
505
- AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
506
- }
507
-
508
- /**
509
- * A {@link NotificationTarget} that represents a team channel.
510
- *
511
- * @remarks
512
- * It's recommended to get channels from {@link TeamsBotInstallation.channels()}.
513
- */
514
- export declare class Channel implements NotificationTarget {
515
- /**
516
- * The parent {@link TeamsBotInstallation} where this channel is created from.
517
- */
518
- readonly parent: TeamsBotInstallation;
519
- /**
520
- * Detailed channel information.
521
- */
522
- readonly info: ChannelInfo;
523
- /**
524
- * Notification target type. For channel it's always "Channel".
525
- */
526
- readonly type: NotificationTargetType;
527
- /**
528
- * Constructor.
529
- *
530
- * @remarks
531
- * It's recommended to get channels from {@link TeamsBotInstallation.channels()}, instead of using this constructor.
532
- *
533
- * @param parent - The parent {@link TeamsBotInstallation} where this channel is created from.
534
- * @param info - Detailed channel information.
535
- */
536
- constructor(parent: TeamsBotInstallation, info: ChannelInfo);
537
- /**
538
- * Send a plain text message.
539
- *
540
- * @param text - the plain text message.
541
- * @param onError - an optional error handler that can catch exceptions during message sending.
542
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
543
- * @returns the response of sending message.
544
- */
545
- sendMessage(text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
546
- /**
547
- * Send an adaptive card message.
548
- *
549
- * @param card - the adaptive card raw JSON.
550
- * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
551
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
552
- * @returns the response of sending adaptive card message.
553
- */
554
- sendAdaptiveCard(card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
555
- /**
556
- * @internal
557
- */
558
- private newConversation;
559
- }
560
-
561
- /**
562
- * A command bot for receiving commands and sending responses in Teams.
563
- *
564
- * @remarks
565
- * Ensure each command should ONLY be registered with the command once, otherwise it'll cause unexpected behavior if you register the same command more than once.
566
- */
567
- export declare class CommandBot {
568
- private readonly adapter;
569
- private readonly middleware;
570
- private readonly ssoConfig;
571
- /**
572
- * Creates a new instance of the `CommandBot`.
573
- *
574
- * @param adapter The bound `BotFrameworkAdapter`.
575
- * @param options - initialize options
576
- */
577
- constructor(adapter: BotFrameworkAdapter, options?: CommandOptions, ssoCommandActivityHandler?: BotSsoExecutionActivityHandler, ssoConfig?: BotSsoConfig);
578
- /**
579
- * Registers a command into the command bot.
580
- *
581
- * @param command The command to register.
582
- */
583
- registerCommand(command: TeamsFxBotCommandHandler): void;
584
- /**
585
- * Registers commands into the command bot.
586
- *
587
- * @param commands The commands to register.
588
- */
589
- registerCommands(commands: TeamsFxBotCommandHandler[]): void;
590
- /**
591
- * Registers a sso command into the command bot.
592
- *
593
- * @param command The command to register.
594
- */
595
- registerSsoCommand(ssoCommand: TeamsFxBotSsoCommandHandler): void;
596
- /**
597
- * Registers commands into the command bot.
598
- *
599
- * @param commands The commands to register.
600
- */
601
- registerSsoCommands(ssoCommands: TeamsFxBotSsoCommandHandler[]): void;
602
- private validateSsoActivityHandler;
603
- }
604
-
605
- /**
606
- * Interface for a command message that can handled in a command handler.
607
- */
608
- export declare interface CommandMessage {
609
- /**
610
- * Text of the message sent by the user.
611
- */
612
- text: string;
613
- /**
614
- * The capture groups that matched to the {@link TriggerPatterns} in a {@link TeamsFxBotCommandHandler} instance.
615
- */
616
- matches?: RegExpMatchArray;
617
- }
618
-
619
- /**
620
- * Options to initialize {@link CommandBot}.
621
- */
622
- export declare interface CommandOptions {
623
- /**
624
- * The commands to registered with the command bot. Each command should implement the interface {@link TeamsFxBotCommandHandler} so that it can be correctly handled by this command bot.
625
- */
626
- commands?: TeamsFxBotCommandHandler[];
627
- /**
628
- * The commands to registered with the sso command bot. Each sso command should implement the interface {@link TeamsFxBotSsoCommandHandler} so that it can be correctly handled by this command bot.
629
- */
630
- ssoCommands?: TeamsFxBotSsoCommandHandler[];
631
- }
632
-
633
- /**
634
- * Provide utilities for bot conversation, including:
635
- * - handle command and response.
636
- * - send notification to varies targets (e.g., member, group, channel).
637
- *
638
- * @example
639
- * For command and response, you can register your commands through the constructor, or use the `registerCommand` and `registerCommands` API to add commands later.
640
- *
641
- * ```typescript
642
- * // register through constructor
643
- * const conversationBot = new ConversationBot({
644
- * command: {
645
- * enabled: true,
646
- * commands: [ new HelloWorldCommandHandler() ],
647
- * },
648
- * });
649
- *
650
- * // register through `register*` API
651
- * conversationBot.command.registerCommand(new HelpCommandHandler());
652
- * ```
653
- *
654
- * For notification, you can enable notification at initialization, then send notifications at any time.
655
- *
656
- * ```typescript
657
- * // enable through constructor
658
- * const conversationBot = new ConversationBot({
659
- * notification: {
660
- * enabled: true,
661
- * },
662
- * });
663
- *
664
- * // get all bot installations and send message
665
- * for (const target of await conversationBot.notification.installations()) {
666
- * await target.sendMessage("Hello Notification");
667
- * }
668
- *
669
- * // alternative - send message to all members
670
- * for (const target of await conversationBot.notification.installations()) {
671
- * for (const member of await target.members()) {
672
- * await member.sendMessage("Hello Notification");
673
- * }
674
- * }
675
- * ```
676
- *
677
- * @remarks
678
- * Set `adapter` in {@link ConversationOptions} to use your own bot adapter.
679
- *
680
- * For command and response, ensure each command should ONLY be registered with the command once, otherwise it'll cause unexpected behavior if you register the same command more than once.
681
- *
682
- * For notification, set `notification.storage` in {@link ConversationOptions} to use your own storage implementation.
683
- */
684
- export declare class ConversationBot {
685
- /**
686
- * The bot adapter.
687
- */
688
- readonly adapter: BotFrameworkAdapter;
689
- /**
690
- * The entrypoint of command and response.
691
- */
692
- readonly command?: CommandBot;
693
- /**
694
- * The entrypoint of notification.
695
- */
696
- readonly notification?: NotificationBot;
697
- /**
698
- * The action handler used for adaptive card universal actions.
699
- */
700
- readonly cardAction?: CardActionBot;
701
- /**
702
- * Creates new instance of the `ConversationBot`.
703
- *
704
- * @remarks
705
- * It's recommended to create your own adapter and storage for production environment instead of the default one.
706
- *
707
- * @param options - initialize options
708
- */
709
- constructor(options: ConversationOptions);
710
- private createDefaultAdapter;
711
- /**
712
- * The request handler to integrate with web request.
713
- *
714
- * @param req - an Express or Restify style request object.
715
- * @param res - an Express or Restify style response object.
716
- * @param logic - the additional function to handle bot context.
717
- *
718
- * @example
719
- * For example, to use with Restify:
720
- * ``` typescript
721
- * // The default/empty behavior
722
- * server.post("api/messages", conversationBot.requestHandler);
723
- *
724
- * // Or, add your own logic
725
- * server.post("api/messages", async (req, res) => {
726
- * await conversationBot.requestHandler(req, res, async (context) => {
727
- * // your-own-context-logic
728
- * });
729
- * });
730
- * ```
731
- */
732
- requestHandler(req: WebRequest, res: WebResponse, logic?: (context: TurnContext) => Promise<any>): Promise<void>;
733
- }
734
-
735
- /**
736
- * Options to initialize {@link ConversationBot}
737
- */
738
- export declare interface ConversationOptions {
739
- /**
740
- * The bot adapter. If not provided, a default adapter will be created:
741
- * - with `adapterConfig` as constructor parameter.
742
- * - with a default error handler that logs error to console, sends trace activity, and sends error message to user.
743
- *
744
- * @remarks
745
- * If neither `adapter` nor `adapterConfig` is provided, will use BOT_ID and BOT_PASSWORD from environment variables.
746
- */
747
- adapter?: BotFrameworkAdapter;
748
- /**
749
- * If `adapter` is not provided, this `adapterConfig` will be passed to the new `BotFrameworkAdapter` when created internally.
750
- *
751
- * @remarks
752
- * If neither `adapter` nor `adapterConfig` is provided, will use BOT_ID and BOT_PASSWORD from environment variables.
753
- */
754
- adapterConfig?: {
755
- [key: string]: unknown;
756
- };
757
- /**
758
- * Configurations for sso command bot
759
- */
760
- ssoConfig?: BotSsoConfig;
761
- /**
762
- * The command part.
763
- */
764
- command?: CommandOptions & {
765
- /**
766
- * Whether to enable command or not.
767
- */
768
- enabled?: boolean;
769
- };
770
- /**
771
- * The notification part.
772
- */
773
- notification?: NotificationOptions_2 & {
774
- /**
775
- * Whether to enable notification or not.
776
- */
777
- enabled?: boolean;
778
- };
779
- /**
780
- * The adaptive card action handler part.
781
- */
782
- cardAction?: CardActionOptions & {
783
- /**
784
- * Whether to enable adaptive card actions or not.
785
- */
786
- enabled?: boolean;
787
- };
788
- }
789
-
790
- /**
791
- * Initializes new Axios instance with specific auth provider
792
- *
793
- * @param apiEndpoint - Base url of the API
794
- * @param authProvider - Auth provider that injects authentication info to each request
795
- * @returns axios instance configured with specfic auth provider
796
- *
797
- * @example
798
- * ```typescript
799
- * const client = createApiClient("https://my-api-endpoint-base-url", new BasicAuthProvider("xxx","xxx"));
800
- * ```
801
- */
802
- export declare function createApiClient(apiEndpoint: string, authProvider: AuthProvider): AxiosInstance;
803
-
804
- /**
805
- * Get Microsoft graph client.
806
- *
807
- * @example
808
- * Get Microsoft graph client by TokenCredential
809
- * ```typescript
810
- * // Sso token example (Azure Function)
811
- * const ssoToken = "YOUR_TOKEN_STRING";
812
- * const options = {"AAD_APP_ID", "AAD_APP_SECRET"};
813
- * const credential = new OnBehalfOfAADUserCredential(ssoToken, options);
814
- * const graphClient = await createMicrosoftGraphClient(credential);
815
- * const profile = await graphClient.api("/me").get();
816
- *
817
- * // TeamsBotSsoPrompt example (Bot Application)
818
- * const requiredScopes = ["User.Read"];
819
- * const config: Configuration = {
820
- * loginUrl: loginUrl,
821
- * clientId: clientId,
822
- * clientSecret: clientSecret,
823
- * tenantId: tenantId
824
- * };
825
- * const prompt = new TeamsBotSsoPrompt(dialogId, {
826
- * config: config
827
- * scopes: '["User.Read"],
828
- * });
829
- * this.addDialog(prompt);
830
- *
831
- * const oboCredential = new OnBehalfOfAADUserCredential(
832
- * getUserId(dialogContext),
833
- * {
834
- * clientId: "AAD_APP_ID",
835
- * clientSecret: "AAD_APP_SECRET"
836
- * });
837
- * try {
838
- * const graphClient = await createMicrosoftGraphClient(credential);
839
- * const profile = await graphClient.api("/me").get();
840
- * } catch (e) {
841
- * dialogContext.beginDialog(dialogId);
842
- * return Dialog.endOfTurn();
843
- * }
844
- * ```
845
- *
846
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth.
847
- * @param scopes - The array of Microsoft Token scope of access. Default value is `[.default]`.
848
- *
849
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
850
- *
851
- * @returns Graph client with specified scopes.
852
- */
853
- export declare function createMicrosoftGraphClient(teamsfx: TeamsFxConfiguration, scopes?: string | string[]): Client;
854
-
855
- /**
856
- * Helper to create SecureContextOptions from PEM format cert
857
- *
858
- * @param { string | Buffer } cert - The cert chain in PEM format
859
- * @param { string | Buffer } key - The private key for the cert chain
860
- * @param { {passphrase?: string; ca?: string | Buffer} } options - Optional settings when create the cert options.
861
- *
862
- * @returns Instance of SecureContextOptions
863
- *
864
- * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
865
- *
866
- */
867
- export declare function createPemCertOption(cert: string | Buffer, key: string | Buffer, options?: {
868
- passphrase?: string;
869
- ca?: string | Buffer;
870
- }): SecureContextOptions;
871
-
872
- /**
873
- * Helper to create SecureContextOptions from PFX format cert
874
- *
875
- * @param { string | Buffer } pfx - The content of .pfx file
876
- * @param { {passphrase?: string} } options - Optional settings when create the cert options.
877
- *
878
- * @returns Instance of SecureContextOptions
879
- *
880
- * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
881
- *
882
- */
883
- export declare function createPfxCertOption(pfx: string | Buffer, options?: {
884
- passphrase?: string;
885
- }): SecureContextOptions;
886
-
887
- /**
888
- * Error code to trace the error types.
889
- */
890
- export declare enum ErrorCode {
891
- /**
892
- * Invalid parameter error.
893
- */
894
- InvalidParameter = "InvalidParameter",
895
- /**
896
- * Invalid configuration error.
897
- */
898
- InvalidConfiguration = "InvalidConfiguration",
899
- /**
900
- * Invalid certificate error.
901
- */
902
- InvalidCertificate = "InvalidCertificate",
903
- /**
904
- * Internal error.
905
- */
906
- InternalError = "InternalError",
907
- /**
908
- * Channel is not supported error.
909
- */
910
- ChannelNotSupported = "ChannelNotSupported",
911
- /**
912
- * Failed to retrieve sso token
913
- */
914
- FailedToRetrieveSsoToken = "FailedToRetrieveSsoToken",
915
- /**
916
- * Failed to process sso handler
917
- */
918
- FailedToProcessSsoHandler = "FailedToProcessSsoHandler",
919
- /**
920
- * Cannot find command
921
- */
922
- CannotFindCommand = "CannotFindCommand",
923
- /**
924
- * Failed to run sso step
925
- */
926
- FailedToRunSsoStep = "FailedToRunSsoStep",
927
- /**
928
- * Failed to run dedup step
929
- */
930
- FailedToRunDedupStep = "FailedToRunDedupStep",
931
- /**
932
- * Sso activity handler is undefined
933
- */
934
- SsoActivityHandlerIsUndefined = "SsoActivityHandlerIsUndefined",
935
- /**
936
- * Runtime is not supported error.
937
- */
938
- RuntimeNotSupported = "RuntimeNotSupported",
939
- /**
940
- * User failed to finish the AAD consent flow failed.
941
- */
942
- ConsentFailed = "ConsentFailed",
943
- /**
944
- * The user or administrator has not consented to use the application error.
945
- */
946
- UiRequiredError = "UiRequiredError",
947
- /**
948
- * Token is not within its valid time range error.
949
- */
950
- TokenExpiredError = "TokenExpiredError",
951
- /**
952
- * Call service (AAD or simple authentication server) failed.
953
- */
954
- ServiceError = "ServiceError",
955
- /**
956
- * Operation failed.
957
- */
958
- FailedOperation = "FailedOperation",
959
- /**
960
- * Invalid response error.
961
- */
962
- InvalidResponse = "InvalidResponse",
963
- /**
964
- * Identity type error.
965
- */
966
- IdentityTypeNotSupported = "IdentityTypeNotSupported",
967
- /**
968
- * Authentication info already exists error.
969
- */
970
- AuthorizationInfoAlreadyExists = "AuthorizationInfoAlreadyExists"
971
- }
972
-
973
- /**
974
- * Error class with code and message thrown by the SDK.
975
- */
976
- export declare class ErrorWithCode extends Error {
977
- /**
978
- * Error code
979
- *
980
- * @readonly
981
- */
982
- code: string | undefined;
983
- /**
984
- * Constructor of ErrorWithCode.
985
- *
986
- * @param {string} message - error message.
987
- * @param {ErrorCode} code - error code.
988
- */
989
- constructor(message?: string, code?: ErrorCode);
990
- }
991
-
992
- /**
993
- * Get log level.
994
- *
995
- * @returns Log level
996
- */
997
- export declare function getLogLevel(): LogLevel | undefined;
998
-
999
- export declare interface GetTeamsUserTokenOptions extends GetTokenOptions {
1000
- resources?: string[];
1001
- }
1002
-
1003
- /**
1004
- * Generate connection configuration consumed by tedious.
1005
- *
1006
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth
1007
- * @param { string? } databaseName - specify database name to override default one if there are multiple databases.
1008
- *
1009
- * @returns Connection configuration of tedious for the SQL.
1010
- *
1011
- * @throws {@link ErrorCode|InvalidConfiguration} when SQL config resource configuration is invalid.
1012
- * @throws {@link ErrorCode|InternalError} when get user MSI token failed or MSI token is invalid.
1013
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1014
- */
1015
- export declare function getTediousConnectionConfig(teamsfx: TeamsFx, databaseName?: string): Promise<ConnectionConfig>;
1016
-
1017
- /**
1018
- * Users execute query in message extension with SSO or access token.
1019
- *
1020
- * @param {TurnContext} context - The context object for the current turn.
1021
- * @param {AuthenticationConfiguration} config - User custom the message extension authentication configuration.
1022
- * @param {string| string[]} scopes - The list of scopes for which the token will have access.
1023
- * @param {function} logic - Business logic when executing the query in message extension with SSO or access token.
1024
- *
1025
- * @throws {@link ErrorCode|InternalError} when User invoke not response to message extension query.
1026
- * @throws {@link ErrorCode|InternalError} when failed to get access token with unknown error.
1027
- * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1028
- * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth server.
1029
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1030
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1031
- *
1032
- * @returns A MessageExtension Response for the activity. If the logic not return any, return void instead.
1033
- */
1034
- export declare function handleMessageExtensionQueryWithToken(context: TurnContext, config: AuthenticationConfiguration | null, scopes: string | string[], logic: (token: MessageExtensionTokenResponse) => Promise<any>): Promise<MessagingExtensionResponse | void>;
1035
-
1036
- /**
1037
- * Identity type to use in authentication.
1038
- */
1039
- export declare enum IdentityType {
1040
- /**
1041
- * Represents the current user of Teams.
1042
- */
1043
- User = "User",
1044
- /**
1045
- * Represents the application itself.
1046
- */
1047
- App = "Application"
1048
- }
1049
-
1050
- /**
1051
- * Status code for an `application/vnd.microsoft.error` invoke response.
1052
- */
1053
- export declare enum InvokeResponseErrorCode {
1054
- /**
1055
- * Invalid request.
1056
- */
1057
- BadRequest = 400,
1058
- /**
1059
- * Internal server error.
1060
- */
1061
- InternalServerError = 500
1062
- }
1063
-
1064
- /**
1065
- * Provides methods for formatting various invoke responses a bot can send to respond to an invoke request.
1066
- *
1067
- * @remarks
1068
- * All of these functions return an {@link InvokeResponse} object, which can be
1069
- * passed as input to generate a new `invokeResponse` activity.
1070
- *
1071
- * This example sends an invoke response that contains an adaptive card.
1072
- *
1073
- * ```typescript
1074
- *
1075
- * const myCard = {
1076
- * type: "AdaptiveCard",
1077
- * body: [
1078
- * {
1079
- * "type": "TextBlock",
1080
- * "text": "This is a sample card"
1081
- * }],
1082
- * $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
1083
- * version: "1.4"
1084
- * };
1085
- *
1086
- * const invokeResponse = InvokeResponseFactory.adaptiveCard(myCard);
1087
- * await context.sendActivity({
1088
- * type: ActivityTypes.InvokeResponse,
1089
- * value: invokeResponse,
1090
- * });
1091
- * ```
1092
- */
1093
- export declare class InvokeResponseFactory {
1094
- /**
1095
- * Create an invoke response from a text message.
1096
- * The type of the invoke response is `application/vnd.microsoft.activity.message`
1097
- * indicates the request was successfully processed.
1098
- *
1099
- * @param message A text message included in a invoke response.
1100
- *
1101
- * @returns {InvokeResponse} An InvokeResponse object.
1102
- */
1103
- static textMessage(message: string): InvokeResponse;
1104
- /**
1105
- * Create an invoke response from an adaptive card.
1106
- *
1107
- * The type of the invoke response is `application/vnd.microsoft.card.adaptive` indicates
1108
- * the request was successfully processed, and the response includes an adaptive card
1109
- * that the client should display in place of the current one.
1110
- *
1111
- * @param card The adaptive card JSON payload.
1112
- *
1113
- * @returns {InvokeResponse} An InvokeResponse object.
1114
- */
1115
- static adaptiveCard(card: unknown): InvokeResponse;
1116
- /**
1117
- * Create an invoke response with error code and message.
1118
- *
1119
- * The type of the invoke response is `application/vnd.microsoft.error` indicates
1120
- * the request was failed to processed.
1121
- *
1122
- * @param errorCode The status code indicates error, available values:
1123
- * - 400 (BadRequest): indicate the incoming request was invalid.
1124
- * - 500 (InternalServerError): indicate an unexpected error occurred.
1125
- * @param errorMessage The error message.
1126
- *
1127
- * @returns {InvokeResponse} An InvokeResponse object.
1128
- */
1129
- static errorResponse(errorCode: InvokeResponseErrorCode, errorMessage: string): InvokeResponse;
1130
- /**
1131
- * Create an invoke response with status code and response value.
1132
- * @param statusCode The status code.
1133
- * @param body The value of the response body.
1134
- *
1135
- * @returns {InvokeResponse} An InvokeResponse object.
1136
- */
1137
- static createInvokeResponse(statusCode: StatusCodes, body?: unknown): InvokeResponse;
1138
- }
1139
-
1140
- /**
1141
- * Log function for customized logging.
1142
- */
1143
- export declare type LogFunction = (level: LogLevel, message: string) => void;
1144
-
1145
- /**
1146
- * Interface for customized logger.
1147
- */
1148
- export declare interface Logger {
1149
- /**
1150
- * Writes to error level logging or lower.
1151
- */
1152
- error(message: string): void;
1153
- /**
1154
- * Writes to warning level logging or lower.
1155
- */
1156
- warn(message: string): void;
1157
- /**
1158
- * Writes to info level logging or lower.
1159
- */
1160
- info(message: string): void;
1161
- /**
1162
- * Writes to verbose level logging.
1163
- */
1164
- verbose(message: string): void;
1165
- }
1166
-
1167
- /**
1168
- * Log level.
1169
- */
1170
- export declare enum LogLevel {
1171
- /**
1172
- * Show verbose, information, warning and error message.
1173
- */
1174
- Verbose = 0,
1175
- /**
1176
- * Show information, warning and error message.
1177
- */
1178
- Info = 1,
1179
- /**
1180
- * Show warning and error message.
1181
- */
1182
- Warn = 2,
1183
- /**
1184
- * Show error message.
1185
- */
1186
- Error = 3
1187
- }
1188
-
1189
- /**
1190
- * A {@link NotificationTarget} that represents a team member.
1191
- *
1192
- * @remarks
1193
- * It's recommended to get members from {@link TeamsBotInstallation.members()}.
1194
- */
1195
- export declare class Member implements NotificationTarget {
1196
- /**
1197
- * The parent {@link TeamsBotInstallation} where this member is created from.
1198
- */
1199
- readonly parent: TeamsBotInstallation;
1200
- /**
1201
- * Detailed member account information.
1202
- */
1203
- readonly account: TeamsChannelAccount;
1204
- /**
1205
- * Notification target type. For member it's always "Person".
1206
- */
1207
- readonly type: NotificationTargetType;
1208
- /**
1209
- * Constructor.
1210
- *
1211
- * @remarks
1212
- * It's recommended to get members from {@link TeamsBotInstallation.members()}, instead of using this constructor.
1213
- *
1214
- * @param parent - The parent {@link TeamsBotInstallation} where this member is created from.
1215
- * @param account - Detailed member account information.
1216
- */
1217
- constructor(parent: TeamsBotInstallation, account: TeamsChannelAccount);
1218
- /**
1219
- * Send a plain text message.
1220
- *
1221
- * @param text - the plain text message.
1222
- * @param onError - an optional error handler that can catch exceptions during message sending.
1223
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
1224
- * @returns the response of sending message.
1225
- */
1226
- sendMessage(text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1227
- /**
1228
- * Send an adaptive card message.
1229
- *
1230
- * @param card - the adaptive card raw JSON.
1231
- * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
1232
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
1233
- * @returns the response of sending adaptive card message.
1234
- */
1235
- sendAdaptiveCard(card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1236
- /**
1237
- * @internal
1238
- */
1239
- private newConversation;
1240
- }
1241
-
1242
- /**
1243
- * Provides utility method to build bot message with cards that supported in Teams.
1244
- */
1245
- export declare class MessageBuilder {
1246
- /**
1247
- * Build a bot message activity attached with adaptive card.
1248
- *
1249
- * @param cardTemplate The adaptive card template.
1250
- * @param data card data used to render the template.
1251
- * @returns A bot message activity attached with an adaptive card.
1252
- *
1253
- * @example
1254
- * ```javascript
1255
- * const cardTemplate = {
1256
- * type: "AdaptiveCard",
1257
- * body: [
1258
- * {
1259
- * "type": "TextBlock",
1260
- * "text": "${title}",
1261
- * "size": "Large"
1262
- * },
1263
- * {
1264
- * "type": "TextBlock",
1265
- * "text": "${description}"
1266
- * }],
1267
- * $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
1268
- * version: "1.4"
1269
- * };
1270
- *
1271
- * type CardData = {
1272
- * title: string,
1273
- * description: string
1274
- * };
1275
- * const card = MessageBuilder.attachAdaptiveCard<CardData>(
1276
- * cardTemplate, {
1277
- * title: "sample card title",
1278
- * description: "sample card description"
1279
- * });
1280
- * ```
1281
- */
1282
- static attachAdaptiveCard<TData extends object>(cardTemplate: unknown, data: TData): Partial<Activity>;
1283
- /**
1284
- * Build a bot message activity attached with an adaptive card.
1285
- *
1286
- * @param card The adaptive card content.
1287
- * @returns A bot message activity attached with an adaptive card.
1288
- */
1289
- static attachAdaptiveCardWithoutData(card: unknown): Partial<Activity>;
1290
- /**
1291
- * Build a bot message activity attached with an hero card.
1292
- *
1293
- * @param title The card title.
1294
- * @param images Optional. The array of images to include on the card.
1295
- * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
1296
- * is converted to an `imBack` button with a title and value set to the value of the string.
1297
- * @param other Optional. Any additional properties to include on the card.
1298
- *
1299
- * @returns A bot message activity attached with a hero card.
1300
- *
1301
- * @example
1302
- * ```javascript
1303
- * const message = MessageBuilder.attachHeroCard(
1304
- * 'sample title',
1305
- * ['https://example.com/sample.jpg'],
1306
- * ['action']
1307
- * );
1308
- * ```
1309
- */
1310
- static attachHeroCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<HeroCard>): Partial<Activity>;
1311
- /**
1312
- * Returns an attachment for a sign-in card.
1313
- *
1314
- * @param title The title for the card's sign-in button.
1315
- * @param url The URL of the sign-in page to use.
1316
- * @param text Optional. Additional text to include on the card.
1317
- *
1318
- * @returns A bot message activity attached with a sign-in card.
1319
- *
1320
- * @remarks
1321
- * For channels that don't natively support sign-in cards, an alternative message is rendered.
1322
- */
1323
- static attachSigninCard(title: string, url: string, text?: string): Partial<Activity>;
1324
- /**
1325
- * Build a bot message activity attached with an Office 365 connector card.
1326
- *
1327
- * @param card A description of the Office 365 connector card.
1328
- * @returns A bot message activity attached with an Office 365 connector card.
1329
- */
1330
- static attachO365ConnectorCard(card: O365ConnectorCard): Partial<Activity>;
1331
- /**
1332
- * Build a message activity attached with a receipt card.
1333
- * @param card A description of the receipt card.
1334
- * @returns A message activity attached with a receipt card.
1335
- */
1336
- static AttachReceiptCard(card: ReceiptCard): Partial<Activity>;
1337
- /**
1338
- *
1339
- * @param title The card title.
1340
- * @param images Optional. The array of images to include on the card.
1341
- * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
1342
- * is converted to an `imBack` button with a title and value set to the value of the string.
1343
- * @param other Optional. Any additional properties to include on the card.
1344
- * @returns A message activity attached with a thumbnail card
1345
- */
1346
- static attachThumbnailCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<ThumbnailCard>): Partial<Activity>;
1347
- /**
1348
- * Add an attachement to a bot activity.
1349
- * @param attachement The attachment object to attach.
1350
- * @returns A message activity with an attachment.
1351
- */
1352
- static attachContent(attachement: Attachment): Partial<Activity>;
1353
- }
1354
-
1355
- /**
1356
- * Token response provided by Teams Bot SSO prompt
1357
- */
1358
- export declare interface MessageExtensionTokenResponse extends TokenResponse {
1359
- /**
1360
- * SSO token for user
1361
- */
1362
- ssoToken: string;
1363
- /**
1364
- * Expire time of SSO token
1365
- */
1366
- ssoTokenExpiration: string;
1367
- }
1368
-
1369
- /**
1370
- * The response of a message action, e.g., `sendMessage`, `sendAdaptiveCard`.
1371
- */
1372
- declare interface MessageResponse {
1373
- /**
1374
- * Id of the message.
1375
- */
1376
- id?: string;
1377
- }
1378
-
1379
- /**
1380
- * Microsoft Graph auth provider for Teams Framework
1381
- */
1382
- export declare class MsGraphAuthProvider implements AuthenticationProvider {
1383
- private teamsfx;
1384
- private scopes;
1385
- /**
1386
- * Constructor of MsGraphAuthProvider.
1387
- *
1388
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth.
1389
- * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1390
- *
1391
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1392
- *
1393
- * @returns An instance of MsGraphAuthProvider.
1394
- */
1395
- constructor(teamsfx: TeamsFxConfiguration, scopes?: string | string[]);
1396
- /**
1397
- * Get access token for Microsoft Graph API requests.
1398
- *
1399
- * @throws {@link ErrorCode|InternalError} when get access token failed due to empty token or unknown other problems.
1400
- * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1401
- * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1402
- * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth or AAD server.
1403
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1404
- *
1405
- * @returns Access token from the credential.
1406
- *
1407
- */
1408
- getAccessToken(): Promise<string>;
1409
- }
1410
-
1411
- /**
1412
- * Provide utilities to send notification to varies targets (e.g., member, group, channel).
1413
- */
1414
- export declare class NotificationBot {
1415
- private readonly conversationReferenceStore;
1416
- private readonly adapter;
1417
- /**
1418
- * constructor of the notification bot.
1419
- *
1420
- * @remarks
1421
- * To ensure accuracy, it's recommended to initialize before handling any message.
1422
- *
1423
- * @param adapter - the bound `BotFrameworkAdapter`
1424
- * @param options - initialize options
1425
- */
1426
- constructor(adapter: BotFrameworkAdapter, options?: NotificationOptions_2);
1427
- /**
1428
- * Get all targets where the bot is installed.
1429
- *
1430
- * @remarks
1431
- * The result is retrieving from the persisted storage.
1432
- *
1433
- * @returns - an array of {@link TeamsBotInstallation}.
1434
- */
1435
- installations(): Promise<TeamsBotInstallation[]>;
1436
- /**
1437
- * Returns the first {@link Member} where predicate is true, and undefined otherwise.
1438
- *
1439
- * @param predicate find calls predicate once for each member of the installation,
1440
- * until it finds one where predicate returns true. If such a member is found, find
1441
- * immediately returns that member. Otherwise, find returns undefined.
1442
- * @param scope the scope to find members from the installations
1443
- * (personal chat, group chat, Teams channel).
1444
- * @returns the first {@link Member} where predicate is true, and undefined otherwise.
1445
- */
1446
- findMember(predicate: (member: Member) => Promise<boolean>, scope?: SearchScope): Promise<Member | undefined>;
1447
- /**
1448
- * Returns the first {@link Channel} where predicate is true, and undefined otherwise.
1449
- * (Ensure the bot app is installed into the `General` channel, otherwise undefined will be returned.)
1450
- *
1451
- * @param predicate find calls predicate once for each channel of the installation,
1452
- * until it finds one where predicate returns true. If such a channel is found, find
1453
- * immediately returns that channel. Otherwise, find returns undefined.
1454
- * @returns the first {@link Channel} where predicate is true, and undefined otherwise.
1455
- */
1456
- findChannel(predicate: (channel: Channel, teamDetails: TeamDetails | undefined) => Promise<boolean>): Promise<Channel | undefined>;
1457
- /**
1458
- * Returns all {@link Member} where predicate is true, and empty array otherwise.
1459
- *
1460
- * @param predicate find calls predicate for each member of the installation.
1461
- * @param scope the scope to find members from the installations
1462
- * (personal chat, group chat, Teams channel).
1463
- * @returns an array of {@link Member} where predicate is true, and empty array otherwise.
1464
- */
1465
- findAllMembers(predicate: (member: Member) => Promise<boolean>, scope?: SearchScope): Promise<Member[]>;
1466
- /**
1467
- * Returns all {@link Channel} where predicate is true, and empty array otherwise.
1468
- * (Ensure the bot app is installed into the `General` channel, otherwise empty array will be returned.)
1469
- *
1470
- * @param predicate find calls predicate for each channel of the installation.
1471
- * @returns an array of {@link Channel} where predicate is true, and empty array otherwise.
1472
- */
1473
- findAllChannels(predicate: (channel: Channel, teamDetails: TeamDetails | undefined) => Promise<boolean>): Promise<Channel[]>;
1474
- private matchSearchScope;
1475
- }
1476
-
1477
- /**
1478
- * Options to initialize {@link NotificationBot}.
1479
- */
1480
- declare interface NotificationOptions_2 {
1481
- /**
1482
- * An optional storage to persist bot notification connections.
1483
- *
1484
- * @remarks
1485
- * If `storage` is not provided, a default local file storage will be used,
1486
- * which stores notification connections into:
1487
- * - ".notification.localstore.json" if running locally
1488
- * - "${process.env.TEMP}/.notification.localstore.json" if `process.env.RUNNING_ON_AZURE` is set to "1"
1489
- *
1490
- * It's recommended to use your own shared storage for production environment.
1491
- */
1492
- storage?: NotificationTargetStorage;
1493
- }
1494
- export { NotificationOptions_2 as NotificationOptions }
1495
-
1496
- /**
1497
- * Represent a notification target.
1498
- */
1499
- export declare interface NotificationTarget {
1500
- /**
1501
- * The type of target, could be "Channel" or "Group" or "Person".
1502
- */
1503
- readonly type?: NotificationTargetType;
1504
- /**
1505
- * Send a plain text message.
1506
- *
1507
- * @param text - the plain text message.
1508
- * @param onError - an optional error handler that can catch exceptions during message sending.
1509
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
1510
- *
1511
- * @returns the response of sending message.
1512
- */
1513
- sendMessage(text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1514
- /**
1515
- * Send an adaptive card message.
1516
- *
1517
- * @param card - the adaptive card raw JSON.
1518
- * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
1519
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
1520
- *
1521
- * @returns the response of sending adaptive card message.
1522
- */
1523
- sendAdaptiveCard(card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1524
- }
1525
-
1526
- /**
1527
- * Interface for a storage provider that stores and retrieves notification target references.
1528
- */
1529
- export declare interface NotificationTargetStorage {
1530
- /**
1531
- * Read one notification target by its key.
1532
- *
1533
- * @param key - the key of a notification target.
1534
- *
1535
- * @returns - the notification target. Or undefined if not found.
1536
- */
1537
- read(key: string): Promise<{
1538
- [key: string]: unknown;
1539
- } | undefined>;
1540
- /**
1541
- * List all stored notification targets.
1542
- *
1543
- * @returns - an array of notification target. Or an empty array if nothing is stored.
1544
- */
1545
- list(): Promise<{
1546
- [key: string]: unknown;
1547
- }[]>;
1548
- /**
1549
- * Write one notification target by its key.
1550
- *
1551
- * @param key - the key of a notification target.
1552
- * @param object - the notification target.
1553
- */
1554
- write(key: string, object: {
1555
- [key: string]: unknown;
1556
- }): Promise<void>;
1557
- /**
1558
- * Delete one notification target by its key.
1559
- *
1560
- * @param key - the key of a notification target.
1561
- */
1562
- delete(key: string): Promise<void>;
1563
- }
1564
-
1565
- /**
1566
- * The target type where the notification will be sent to.
1567
- *
1568
- * @remarks
1569
- * - "Channel" means to a team channel. (By default, notification to a team will be sent to its "General" channel.)
1570
- * - "Group" means to a group chat.
1571
- * - "Person" means to a personal chat.
1572
- */
1573
- export declare enum NotificationTargetType {
1574
- /**
1575
- * The notification will be sent to a team channel.
1576
- * (By default, notification to a team will be sent to its "General" channel.)
1577
- */
1578
- Channel = "Channel",
1579
- /**
1580
- * The notification will be sent to a group chat.
1581
- */
1582
- Group = "Group",
1583
- /**
1584
- * The notification will be sent to a personal chat.
1585
- */
1586
- Person = "Person"
1587
- }
1588
-
1589
- /**
1590
- * Represent on-behalf-of flow to get user identity, and it is designed to be used in server side.
1591
- *
1592
- * @example
1593
- * ```typescript
1594
- * const credential = new OnBehalfOfUserCredential(ssoToken);
1595
- * ```
1596
- *
1597
- * @remarks
1598
- * Can only be used in server side.
1599
- */
1600
- export declare class OnBehalfOfUserCredential implements TokenCredential {
1601
- private msalClient;
1602
- private ssoToken;
1603
- /**
1604
- * Constructor of OnBehalfOfUserCredential
1605
- *
1606
- * @remarks
1607
- * Only works in in server side.
1608
- *
1609
- * @param {string} ssoToken - User token provided by Teams SSO feature.
1610
- * @param {AuthenticationConfiguration} config - The authentication configuration. Use environment variables if not provided.
1611
- *
1612
- * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret, certificate content, authority host or tenant id is not found in config.
1613
- * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1614
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1615
- */
1616
- constructor(ssoToken: string, config: AuthenticationConfiguration);
1617
- /**
1618
- * Get access token from credential.
1619
- *
1620
- * @example
1621
- * ```typescript
1622
- * await credential.getToken([]) // Get SSO token using empty string array
1623
- * await credential.getToken("") // Get SSO token using empty string
1624
- * await credential.getToken([".default"]) // Get Graph access token with default scope using string array
1625
- * await credential.getToken(".default") // Get Graph access token with default scope using string
1626
- * await credential.getToken(["User.Read"]) // Get Graph access token for single scope using string array
1627
- * await credential.getToken("User.Read") // Get Graph access token for single scope using string
1628
- * await credential.getToken(["User.Read", "Application.Read.All"]) // Get Graph access token for multiple scopes using string array
1629
- * await credential.getToken("User.Read Application.Read.All") // Get Graph access token for multiple scopes using space-separated string
1630
- * await credential.getToken("https://graph.microsoft.com/User.Read") // Get Graph access token with full resource URI
1631
- * await credential.getToken(["https://outlook.office.com/Mail.Read"]) // Get Outlook access token
1632
- * ```
1633
- *
1634
- * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1635
- * @param {GetTokenOptions} options - The options used to configure any requests this TokenCredential implementation might make.
1636
- *
1637
- * @throws {@link ErrorCode|InternalError} when failed to acquire access token on behalf of user with unknown error.
1638
- * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1639
- * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1640
- * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth server.
1641
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1642
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1643
- *
1644
- * @returns Access token with expected scopes.
1645
- *
1646
- * @remarks
1647
- * If scopes is empty string or array, it returns SSO token.
1648
- * If scopes is non-empty, it returns access token for target scope.
1649
- */
1650
- getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1651
- /**
1652
- * Get basic user info from SSO token.
1653
- *
1654
- * @example
1655
- * ```typescript
1656
- * const currentUser = getUserInfo();
1657
- * ```
1658
- *
1659
- * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1660
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1661
- *
1662
- * @returns Basic user info with user displayName, objectId and preferredUserName.
1663
- */
1664
- getUserInfo(): UserInfo;
1665
- private generateAuthServerError;
1666
- }
1667
-
1668
- /**
1669
- * The search scope when calling {@link NotificationBot.findMember} and {@link NotificationBot.findAllMembers}.
1670
- * The search scope is a flagged enum and it can be combined with `|`.
1671
- * For example, to search from personal chat and group chat, use `SearchScope.Person | SearchScope.Group`.
1672
- */
1673
- export declare enum SearchScope {
1674
- /**
1675
- * Search members from the installations in personal chat only.
1676
- */
1677
- Person = 1,
1678
- /**
1679
- * Search members from the installations in group chat only.
1680
- */
1681
- Group = 2,
1682
- /**
1683
- * Search members from the installations in Teams channel only.
1684
- */
1685
- Channel = 4,
1686
- /**
1687
- * Search members from all installations including personal chat, group chat and Teams channel.
1688
- */
1689
- All = 7
1690
- }
1691
-
1692
- /**
1693
- * Send an adaptive card message to a notification target.
1694
- *
1695
- * @param target - the notification target.
1696
- * @param card - the adaptive card raw JSON.
1697
- * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
1698
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
1699
- * @returns the response of sending adaptive card message.
1700
- */
1701
- export declare function sendAdaptiveCard(target: NotificationTarget, card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1702
-
1703
- /**
1704
- * Send a plain text message to a notification target.
1705
- *
1706
- * @param target - the notification target.
1707
- * @param text - the plain text message.
1708
- * @param onError - an optional error handler that can catch exceptions during message sending.
1709
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
1710
- * @returns the response of sending message.
1711
- */
1712
- export declare function sendMessage(target: NotificationTarget, text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1713
-
1714
- /**
1715
- * Set custom log function. Use the function if it's set. Priority is lower than setLogger.
1716
- *
1717
- * @param {LogFunction} logFunction - custom log function. If it's undefined, custom log function will be cleared.
1718
- *
1719
- * @example
1720
- * ```typescript
1721
- * setLogFunction((level: LogLevel, message: string) => {
1722
- * if (level === LogLevel.Error) {
1723
- * console.log(message);
1724
- * }
1725
- * });
1726
- * ```
1727
- */
1728
- export declare function setLogFunction(logFunction?: LogFunction): void;
1729
-
1730
- /**
1731
- * Set custom logger. Use the output functions if it's set. Priority is higher than setLogFunction.
1732
- *
1733
- * @param {Logger} logger - custom logger. If it's undefined, custom logger will be cleared.
1734
- *
1735
- * @example
1736
- * ```typescript
1737
- * setLogger({
1738
- * verbose: console.debug,
1739
- * info: console.info,
1740
- * warn: console.warn,
1741
- * error: console.error,
1742
- * });
1743
- * ```
1744
- */
1745
- export declare function setLogger(logger?: Logger): void;
1746
-
1747
- /**
1748
- * Update log level helper.
1749
- *
1750
- * @param { LogLevel } level - log level in configuration
1751
- */
1752
- export declare function setLogLevel(level: LogLevel): void;
1753
-
1754
- /**
1755
- * A {@link NotificationTarget} that represents a bot installation. Teams Bot could be installed into
1756
- * - Personal chat
1757
- * - Group chat
1758
- * - Team (by default the `General` channel)
1759
- *
1760
- * @remarks
1761
- * It's recommended to get bot installations from {@link ConversationBot.installations()}.
1762
- */
1763
- export declare class TeamsBotInstallation implements NotificationTarget {
1764
- /**
1765
- * The bound `BotFrameworkAdapter`.
1766
- */
1767
- readonly adapter: BotFrameworkAdapter;
1768
- /**
1769
- * The bound `ConversationReference`.
1770
- */
1771
- readonly conversationReference: Partial<ConversationReference>;
1772
- /**
1773
- * Notification target type.
1774
- *
1775
- * @remarks
1776
- * - "Channel" means bot is installed into a team and notification will be sent to its "General" channel.
1777
- * - "Group" means bot is installed into a group chat.
1778
- * - "Person" means bot is installed into a personal scope and notification will be sent to personal chat.
1779
- */
1780
- readonly type?: NotificationTargetType;
1781
- /**
1782
- * Constructor
1783
- *
1784
- * @remarks
1785
- * It's recommended to get bot installations from {@link ConversationBot.installations()}, instead of using this constructor.
1786
- *
1787
- * @param adapter - the bound `BotFrameworkAdapter`.
1788
- * @param conversationReference - the bound `ConversationReference`.
1789
- */
1790
- constructor(adapter: BotFrameworkAdapter, conversationReference: Partial<ConversationReference>);
1791
- /**
1792
- * Send a plain text message.
1793
- *
1794
- * @param text - the plain text message.
1795
- * @param onError - an optional error handler that can catch exceptions during message sending.
1796
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
1797
- * @returns the response of sending message.
1798
- */
1799
- sendMessage(text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1800
- /**
1801
- * Send an adaptive card message.
1802
- *
1803
- * @param card - the adaptive card raw JSON.
1804
- * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
1805
- * If not defined, error will be handled by `BotAdapter.onTurnError`.
1806
- * @returns the response of sending adaptive card message.
1807
- */
1808
- sendAdaptiveCard(card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1809
- /**
1810
- * Get channels from this bot installation.
1811
- *
1812
- * @returns an array of channels if bot is installed into a team, otherwise returns an empty array.
1813
- */
1814
- channels(): Promise<Channel[]>;
1815
- /**
1816
- * Get members from this bot installation.
1817
- *
1818
- * @returns an array of members from where the bot is installed.
1819
- */
1820
- members(): Promise<Member[]>;
1821
- /**
1822
- * Get team details from this bot installation
1823
- *
1824
- * @returns the team details if bot is installed into a team, otherwise returns undefined.
1825
- */
1826
- getTeamDetails(): Promise<TeamDetails | undefined>;
1827
- }
1828
-
1829
- /**
1830
- * Creates a new prompt that leverage Teams Single Sign On (SSO) support for bot to automatically sign in user and
1831
- * help receive oauth token, asks the user to consent if needed.
1832
- *
1833
- * @remarks
1834
- * The prompt will attempt to retrieve the users current token of the desired scopes and store it in
1835
- * the token store.
1836
- *
1837
- * User will be automatically signed in leveraging Teams support of Bot Single Sign On(SSO):
1838
- * https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots
1839
- *
1840
- * @example
1841
- * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named
1842
- * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either
1843
- * `DialogContext.beginDialog()` or `DialogContext.prompt()`. The user will be prompted to sign in as
1844
- * needed and their access token will be passed as an argument to the callers next waterfall step:
1845
- *
1846
- * ```JavaScript
1847
- * const { ConversationState, MemoryStorage } = require('botbuilder');
1848
- * const { DialogSet, WaterfallDialog } = require('botbuilder-dialogs');
1849
- * const { TeamsBotSsoPrompt } = require('@microsoft/teamsfx');
1850
- *
1851
- * const convoState = new ConversationState(new MemoryStorage());
1852
- * const dialogState = convoState.createProperty('dialogState');
1853
- * const dialogs = new DialogSet(dialogState);
1854
- *
1855
- * dialogs.add(new TeamsBotSsoPrompt('TeamsBotSsoPrompt', {
1856
- * scopes: ["User.Read"],
1857
- * }));
1858
- *
1859
- * dialogs.add(new WaterfallDialog('taskNeedingLogin', [
1860
- * async (step) => {
1861
- * return await step.beginDialog('TeamsBotSsoPrompt');
1862
- * },
1863
- * async (step) => {
1864
- * const token = step.result;
1865
- * if (token) {
1866
- *
1867
- * // ... continue with task needing access token ...
1868
- *
1869
- * } else {
1870
- * await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
1871
- * return await step.endDialog();
1872
- * }
1873
- * }
1874
- * ]));
1875
- * ```
1876
- */
1877
- export declare class TeamsBotSsoPrompt extends Dialog {
1878
- private teamsfx;
1879
- private settings;
1880
- /**
1881
- * Constructor of TeamsBotSsoPrompt.
1882
- *
1883
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth
1884
- * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
1885
- * @param settings Settings used to configure the prompt.
1886
- *
1887
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1888
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1889
- */
1890
- constructor(teamsfx: TeamsFx, dialogId: string, settings: TeamsBotSsoPromptSettings);
1891
- /**
1892
- * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
1893
- * @remarks
1894
- * If the task is successful, the result indicates whether the prompt is still
1895
- * active after the turn has been processed by the prompt.
1896
- *
1897
- * @param dc The DialogContext for the current turn of the conversation.
1898
- *
1899
- * @throws {@link ErrorCode|InvalidParameter} when timeout property in teams bot sso prompt settings is not number or is not positive.
1900
- * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1901
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1902
- *
1903
- * @returns A `Promise` representing the asynchronous operation.
1904
- */
1905
- beginDialog(dc: DialogContext): Promise<DialogTurnResult>;
1906
- /**
1907
- * Called when a prompt dialog is the active dialog and the user replied with a new activity.
1908
- *
1909
- * @remarks
1910
- * If the task is successful, the result indicates whether the dialog is still
1911
- * active after the turn has been processed by the dialog.
1912
- * The prompt generally continues to receive the user's replies until it accepts the
1913
- * user's reply as valid input for the prompt.
1914
- *
1915
- * @param dc The DialogContext for the current turn of the conversation.
1916
- *
1917
- * @returns A `Promise` representing the asynchronous operation.
1918
- *
1919
- * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1920
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1921
- */
1922
- continueDialog(dc: DialogContext): Promise<DialogTurnResult>;
1923
- private loadAndValidateConfig;
1924
- /**
1925
- * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
1926
- * @param dc dialog context
1927
- * @throws {@link ErrorCode|ChannelNotSupported} if bot channel is not MS Teams
1928
- * @internal
1929
- */
1930
- private ensureMsTeamsChannel;
1931
- /**
1932
- * Send OAuthCard that tells Teams to obtain an authentication token for the bot application.
1933
- * For details see https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots.
1934
- *
1935
- * @internal
1936
- */
1937
- private sendOAuthCardAsync;
1938
- /**
1939
- * Get sign in resource.
1940
- *
1941
- * @throws {@link ErrorCode|InvalidConfiguration} if client id, tenant id or initiate login endpoint is not found in config.
1942
- *
1943
- * @internal
1944
- */
1945
- private getSignInResource;
1946
- /**
1947
- * @internal
1948
- */
1949
- private recognizeToken;
1950
- /**
1951
- * @internal
1952
- */
1953
- private getTokenExchangeInvokeResponse;
1954
- /**
1955
- * @internal
1956
- */
1957
- private isTeamsVerificationInvoke;
1958
- /**
1959
- * @internal
1960
- */
1961
- private isTokenExchangeRequestInvoke;
1962
- /**
1963
- * @internal
1964
- */
1965
- private isTokenExchangeRequest;
1966
- }
1967
-
1968
- /**
1969
- * Settings used to configure an TeamsBotSsoPrompt instance.
1970
- */
1971
- export declare interface TeamsBotSsoPromptSettings {
1972
- /**
1973
- * The array of strings that declare the desired permissions and the resources requested.
1974
- */
1975
- scopes: string[];
1976
- /**
1977
- * (Optional) number of milliseconds the prompt will wait for the user to authenticate.
1978
- * Defaults to a value `900,000` (15 minutes.)
1979
- */
1980
- timeout?: number;
1981
- /**
1982
- * (Optional) value indicating whether the TeamsBotSsoPrompt should end upon receiving an
1983
- * invalid message. Generally the TeamsBotSsoPrompt will end the auth flow when receives user
1984
- * message not related to the auth flow. Setting the flag to false ignores the user's message instead.
1985
- * Defaults to value `true`
1986
- */
1987
- endOnInvalidMessage?: boolean;
1988
- }
1989
-
1990
- /**
1991
- * Token response provided by Teams Bot SSO prompt
1992
- */
1993
- export declare interface TeamsBotSsoPromptTokenResponse extends TokenResponse {
1994
- /**
1995
- * SSO token for user
1996
- */
1997
- ssoToken: string;
1998
- /**
1999
- * Expire time of SSO token
2000
- */
2001
- ssoTokenExpiration: string;
2002
- }
2003
-
2004
- /**
2005
- * A class providing credential and configuration.
2006
- */
2007
- export declare class TeamsFx implements TeamsFxConfiguration {
2008
- private configuration;
2009
- private oboUserCredential?;
2010
- private appCredential?;
2011
- private identityType;
2012
- /**
2013
- * Constructor of TeamsFx
2014
- *
2015
- * @param {IdentityType} identityType - Choose user or app identity
2016
- * @param customConfig - key/value pairs of customized configuration that overrides default ones.
2017
- *
2018
- * @throws {@link ErrorCode|IdentityTypeNotSupported} when setting app identity in browser.
2019
- */
2020
- constructor(identityType?: IdentityType, customConfig?: Record<string, string> | AuthenticationConfiguration);
2021
- /**
2022
- * Identity type set by user.
2023
- *
2024
- * @returns identity type.
2025
- */
2026
- getIdentityType(): IdentityType;
2027
- /**
2028
- * Credential instance according to identity type choice.
2029
- *
2030
- * @remarks If user identity is chose, will return {@link TeamsUserCredential}
2031
- * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
2032
- * identity is chose, will return {@link AppCredential}.
2033
- *
2034
- * @returns instance implements TokenCredential interface.
2035
- */
2036
- getCredential(): TokenCredential;
2037
- /**
2038
- * Get user information.
2039
- * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2040
- * @returns UserInfo object.
2041
- */
2042
- getUserInfo(resources?: string[]): Promise<UserInfo>;
2043
- /**
2044
- * Popup login page to get user's access token with specific scopes.
2045
- *
2046
- * @remarks
2047
- * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
2048
- *
2049
- * @example
2050
- * ```typescript
2051
- * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
2052
- * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
2053
- * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
2054
- * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
2055
- * ```
2056
- * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
2057
- * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2058
- *
2059
- * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
2060
- * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
2061
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
2062
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
2063
- */
2064
- login(scopes: string | string[], resources?: string[]): Promise<void>;
2065
- /**
2066
- * Set SSO token when using user identity in NodeJS.
2067
- * @param {string} ssoToken - used for on behalf of user flow.
2068
- * @returns self instance.
2069
- */
2070
- setSsoToken(ssoToken: string): TeamsFx;
2071
- /**
2072
- * Usually used by service plugins to retrieve specific config
2073
- * @param {string} key - configuration key.
2074
- * @returns value in configuration.
2075
- */
2076
- getConfig(key: string): string;
2077
- /**
2078
- * Check the value of specific key.
2079
- * @param {string} key - configuration key.
2080
- * @returns true if corresponding value is not empty string.
2081
- */
2082
- hasConfig(key: string): boolean;
2083
- /**
2084
- * Get all configurations.
2085
- * @returns key value mappings.
2086
- */
2087
- getConfigs(): Record<string, string>;
2088
- /**
2089
- * Load configuration from environment variables.
2090
- */
2091
- private loadFromEnv;
2092
- }
2093
-
2094
- /**
2095
- * Interface for adaptive card action handler that can process card action invoke and return a response.
2096
- */
2097
- export declare interface TeamsFxAdaptiveCardActionHandler {
2098
- /**
2099
- * The verb defined in adaptive card action that can trigger this handler.
2100
- * The verb string here is case-insensitive.
2101
- */
2102
- triggerVerb: string;
2103
- /**
2104
- * Specify the behavior for how the card response will be sent in Teams conversation.
2105
- * The default value is `AdaptiveCardResponse.ReplaceForInteractor`, which means the card
2106
- * response will replace the current one only for the interactor.
2107
- */
2108
- adaptiveCardResponse?: AdaptiveCardResponse;
2109
- /**
2110
- * The handler function that will be invoked when the action is fired.
2111
- * @param context The turn context.
2112
- * @param actionData The contextual data that associated with the action.
2113
- *
2114
- * @returns A `Promise` representing a invoke response for the adaptive card invoke action.
2115
- * You can use the `InvokeResponseFactory` utility class to create an invoke response from
2116
- * - A text message:
2117
- * ```typescript
2118
- * return InvokeResponseFactory.textMessage("Action is processed successfully!");
2119
- * ```
2120
- * - An adaptive card:
2121
- * ```typescript
2122
- * const responseCard = AdaptiveCards.declare(helloWorldCard).render(actionData);
2123
- return InvokeResponseFactory.adaptiveCard(responseCard);
2124
- * ```
2125
- * - An error response:
2126
- * ```typescript
2127
- * return InvokeResponseFactory.errorResponse(InvokeResponseErrorCode.BadRequest, "Invalid request");
2128
- * ```
2129
- *
2130
- * @remark For more details about the invoke response format, refer to https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model#response-format.
2131
- */
2132
- handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse>;
2133
- }
2134
-
2135
- /**
2136
- * Interface for a command handler that can process command to a TeamsFx bot and return a response.
2137
- */
2138
- export declare interface TeamsFxBotCommandHandler {
2139
- /**
2140
- * The string or regular expression patterns that can trigger this handler.
2141
- */
2142
- triggerPatterns: TriggerPatterns;
2143
- /**
2144
- * Handles a bot command received activity.
2145
- *
2146
- * @param context The bot context.
2147
- * @param message The command message the user types from Teams.
2148
- * @returns A `Promise` representing an activity or text to send as the command response.
2149
- * Or no return value if developers want to send the response activity by themselves in this method.
2150
- */
2151
- handleCommandReceived(context: TurnContext, message: CommandMessage): Promise<string | Partial<Activity> | void>;
2152
- }
2153
-
2154
- /**
2155
- * Interface for a command handler that can process sso command to a TeamsFx bot and return a response.
2156
- */
2157
- export declare interface TeamsFxBotSsoCommandHandler {
2158
- /**
2159
- * The string or regular expression patterns that can trigger this handler.
2160
- */
2161
- triggerPatterns: TriggerPatterns;
2162
- /**
2163
- * Handles a bot command received activity.
2164
- *
2165
- * @param context The bot context.
2166
- * @param message The command message the user types from Teams.
2167
- * @param tokenResponse The tokenResponse which contains sso token that can be used to exchange access token for the bot.
2168
- * @returns A `Promise` representing an activity or text to send as the command response.
2169
- * Or no return value if developers want to send the response activity by themselves in this method.
2170
- */
2171
- handleCommandReceived(context: TurnContext, message: CommandMessage, tokenResponse: TeamsBotSsoPromptTokenResponse): Promise<string | Partial<Activity> | void>;
2172
- }
2173
-
2174
- /**
2175
- * TeamsFx interface that provides credential and configuration.
2176
- */
2177
- declare interface TeamsFxConfiguration {
2178
- /**
2179
- * Identity type set by user.
2180
- *
2181
- * @returns identity type.
2182
- */
2183
- getIdentityType(): IdentityType;
2184
- /**
2185
- * Credential instance according to identity type choice.
2186
- *
2187
- * @remarks If user identity is chose, will return {@link TeamsUserCredential}
2188
- * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
2189
- * identity is chose, will return {@link AppCredential}.
2190
- *
2191
- * @returns instance implements TokenCredential interface.
2192
- */
2193
- getCredential(): TokenCredential;
2194
- /**
2195
- * Get user information.
2196
- * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2197
- * @returns UserInfo object.
2198
- */
2199
- getUserInfo(resources?: string[]): Promise<UserInfo>;
2200
- /**
2201
- * Popup login page to get user's access token with specific scopes.
2202
- *
2203
- * @remarks
2204
- * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
2205
- *
2206
- * @example
2207
- * ```typescript
2208
- * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
2209
- * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
2210
- * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
2211
- * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
2212
- * ```
2213
- * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
2214
- * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2215
- *
2216
- * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
2217
- * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
2218
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
2219
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
2220
- */
2221
- login(scopes: string | string[], resources?: string[]): Promise<void>;
2222
- /**
2223
- * Set SSO token when using user identity in NodeJS.
2224
- * @param {string} ssoToken - used for on behalf of user flow.
2225
- * @returns self instance.
2226
- */
2227
- setSsoToken(ssoToken: string): TeamsFxConfiguration;
2228
- /**
2229
- * Usually used by service plugins to retrieve specific config
2230
- * @param {string} key - configuration key.
2231
- * @returns value in configuration.
2232
- */
2233
- getConfig(key: string): string;
2234
- /**
2235
- * Check the value of specific key.
2236
- * @param {string} key - configuration key.
2237
- * @returns true if corresponding value is not empty string.
2238
- */
2239
- hasConfig(key: string): boolean;
2240
- /**
2241
- * Get all configurations.
2242
- * @returns key value mappings.
2243
- */
2244
- getConfigs(): Record<string, string>;
2245
- }
2246
-
2247
- /**
2248
- * Represent Teams current user's identity, and it is used within Teams client applications.
2249
- *
2250
- * @remarks
2251
- * Can only be used within Teams.
2252
- */
2253
- export declare class TeamsUserCredential implements TokenCredential {
2254
- /**
2255
- * Constructor of TeamsUserCredential.
2256
- * @remarks
2257
- * Can only be used within Teams.
2258
- */
2259
- constructor(authConfig: AuthenticationConfiguration);
2260
- /**
2261
- * Popup login page to get user's access token with specific scopes.
2262
- *
2263
- * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2264
- *
2265
- * @remarks
2266
- * Can only be used within Teams.
2267
- */
2268
- login(scopes: string | string[], resources?: string[]): Promise<void>;
2269
- /**
2270
- * Get access token from credential.
2271
- * @remarks
2272
- * Can only be used within Teams.
2273
- */
2274
- getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
2275
- /**
2276
- * Get basic user info from SSO token
2277
- *
2278
- * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2279
- *
2280
- * @remarks
2281
- * Can only be used within Teams.
2282
- */
2283
- getUserInfo(resources?: string[]): Promise<UserInfo>;
2284
- }
2285
-
2286
- /**
2287
- * The trigger pattern used to trigger a {@link TeamsFxBotCommandHandler} instance.
2288
- */
2289
- export declare type TriggerPatterns = string | RegExp | (string | RegExp)[];
2290
-
2291
- /**
2292
- * UserInfo with user displayName, objectId and preferredUserName.
2293
- */
2294
- export declare interface UserInfo {
2295
- /**
2296
- * User Display Name.
2297
- *
2298
- * @readonly
2299
- */
2300
- displayName: string;
2301
- /**
2302
- * User unique reference within the Azure Active Directory domain.
2303
- *
2304
- * @readonly
2305
- */
2306
- objectId: string;
2307
- /**
2308
- * User tenant ID.
2309
- *
2310
- * @readonly
2311
- */
2312
- tenantId: string;
2313
- /**
2314
- * Usually be the email address.
2315
- *
2316
- * @readonly
2317
- */
2318
- preferredUserName: string;
2319
- }
2320
-
2321
- export { }
414
+ * @param {@link Storage} dedupStorage Helper storage to remove duplicated messages
415
+ * @param {@link TeamsBotSsoPromptSettings} settings The list of scopes for which the token will have access
416
+ * @param {@link TeamsFx} teamsfx instance for authentication
417
+ * @param {string} dialogName custom dialog name
418
+ */
419
+ constructor(dedupStorage: Storage_2, ssoPromptSettings: TeamsBotSsoPromptSettings, teamsfx: TeamsFx, dialogName?: string);
420
+ /**
421
+ * Creates a new instance of the BotSsoExecutionDialog.
422
+ * @param {@link Storage} dedupStorage Helper storage to remove duplicated messages
423
+ * @param {@link TeamsBotSsoPromptSettings} settings The list of scopes for which the token will have access
424
+ * @param {@link OnBehalfOfCredentialAuthConfig} authConfig The authentication configuration.
425
+ * @param {string} initiateLoginEndpoint Login URL for Teams to redirect to.
426
+ * @param {string} dialogName custom dialog name
427
+ */
428
+ constructor(dedupStorage: Storage_2, ssoPromptSettings: TeamsBotSsoPromptSettings, authConfig: OnBehalfOfCredentialAuthConfig, initiateLoginEndpoint: string, dialogName?: string);
429
+ /**
430
+ * Add TeamsFxBotSsoCommandHandler instance
431
+ * @param handler {@link BotSsoExecutionDialogHandler} callback function
432
+ * @param triggerPatterns The trigger pattern
433
+ */
434
+ addCommand(handler: BotSsoExecutionDialogHandler, triggerPatterns: TriggerPatterns): void;
435
+ private getCommandHash;
436
+ /**
437
+ * The run method handles the incoming activity (in the form of a DialogContext) and passes it through the dialog system.
438
+ *
439
+ * @param context The context object for the current turn.
440
+ * @param accessor The instance of StatePropertyAccessor for dialog system.
441
+ */
442
+ run(context: TurnContext, accessor: StatePropertyAccessor): Promise<void>;
443
+ private getActivityText;
444
+ private commandRouteStep;
445
+ private ssoStep;
446
+ private dedupStep;
447
+ /**
448
+ * Called when the component is ending.
449
+ *
450
+ * @param context Context for the current turn of conversation.
451
+ */
452
+ protected onEndDialog(context: TurnContext): Promise<void>;
453
+ /**
454
+ * If a user is signed into multiple Teams clients, the Bot might receive a "signin/tokenExchange" from each client.
455
+ * Each token exchange request for a specific user login will have an identical activity.value.Id.
456
+ * Only one of these token exchange requests should be processed by the bot. For a distributed bot in production,
457
+ * this requires a distributed storage to ensure only one token exchange is processed.
458
+ * @param context Context for the current turn of conversation.
459
+ * @returns boolean value indicate whether the message should be removed
460
+ */
461
+ private shouldDedup;
462
+ private getStorageKey;
463
+ private matchPattern;
464
+ private isPatternMatched;
465
+ private getMatchesCommandId;
466
+ /**
467
+ * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
468
+ * @param dc dialog context
469
+ * @throws {@link ErrorCode|ChannelNotSupported} if bot channel is not MS Teams
470
+ * @internal
471
+ */
472
+ private ensureMsTeamsChannel;
473
+ }
474
+
475
+ export declare type BotSsoExecutionDialogHandler = (context: TurnContext, tokenResponse: TeamsBotSsoPromptTokenResponse, message: CommandMessage) => Promise<void>;
476
+
477
+ /**
478
+ * A card action bot to respond to adaptive card universal actions.
479
+ */
480
+ export declare class CardActionBot {
481
+ private readonly adapter;
482
+ private middleware;
483
+ /**
484
+ * Creates a new instance of the `CardActionBot`.
485
+ *
486
+ * @param adapter The bound `BotFrameworkAdapter`.
487
+ * @param options - initialize options
488
+ */
489
+ constructor(adapter: BotFrameworkAdapter, options?: CardActionOptions);
490
+ /**
491
+ * Registers a card action handler to the bot.
492
+ * @param actionHandler A card action handler to be registered.
493
+ */
494
+ registerHandler(actionHandler: TeamsFxAdaptiveCardActionHandler): void;
495
+ /**
496
+ * Registers card action handlers to the bot.
497
+ * @param actionHandlers A set of card action handlers to be registered.
498
+ */
499
+ registerHandlers(actionHandlers: TeamsFxAdaptiveCardActionHandler[]): void;
500
+ }
501
+
502
+ /**
503
+ * Options to initialize {@link CardActionBot}.
504
+ */
505
+ export declare interface CardActionOptions {
506
+ /**
507
+ * The action handlers to registered with the action bot. Each command should implement the interface {@link TeamsFxAdaptiveCardActionHandler} so that it can be correctly handled by this bot.
508
+ */
509
+ actions?: TeamsFxAdaptiveCardActionHandler[];
510
+ }
511
+
512
+ /**
513
+ * Provider that handles Certificate authentication
514
+ */
515
+ export declare class CertificateAuthProvider implements AuthProvider {
516
+ private certOption;
517
+ /**
518
+ *
519
+ * @param { SecureContextOptions } certOption - information about the cert used in http requests
520
+ *
521
+ * @throws {@link ErrorCode|InvalidParameter} - when cert option is empty.
522
+ */
523
+ constructor(certOption: SecureContextOptions);
524
+ /**
525
+ * Adds authentication info to http requests.
526
+ *
527
+ * @param { AxiosRequestConfig } config - Contains all the request information and can be updated to include extra authentication info.
528
+ * Refer https://axios-http.com/docs/req_config for detailed document.
529
+ *
530
+ * @returns Updated axios request config.
531
+ *
532
+ * @throws {@link ErrorCode|InvalidParameter} - when custom httpsAgent in the request has duplicate properties with certOption provided in constructor.
533
+ */
534
+ AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
535
+ }
536
+
537
+ /**
538
+ * A {@link NotificationTarget} that represents a team channel.
539
+ *
540
+ * @remarks
541
+ * It's recommended to get channels from {@link TeamsBotInstallation.channels()}.
542
+ */
543
+ export declare class Channel implements NotificationTarget {
544
+ /**
545
+ * The parent {@link TeamsBotInstallation} where this channel is created from.
546
+ */
547
+ readonly parent: TeamsBotInstallation;
548
+ /**
549
+ * Detailed channel information.
550
+ */
551
+ readonly info: ChannelInfo;
552
+ /**
553
+ * Notification target type. For channel it's always "Channel".
554
+ */
555
+ readonly type: NotificationTargetType;
556
+ /**
557
+ * Constructor.
558
+ *
559
+ * @remarks
560
+ * It's recommended to get channels from {@link TeamsBotInstallation.channels()}, instead of using this constructor.
561
+ *
562
+ * @param parent - The parent {@link TeamsBotInstallation} where this channel is created from.
563
+ * @param info - Detailed channel information.
564
+ */
565
+ constructor(parent: TeamsBotInstallation, info: ChannelInfo);
566
+ /**
567
+ * Send a plain text message.
568
+ *
569
+ * @param text - the plain text message.
570
+ * @param onError - an optional error handler that can catch exceptions during message sending.
571
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
572
+ * @returns the response of sending message.
573
+ */
574
+ sendMessage(text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
575
+ /**
576
+ * Send an adaptive card message.
577
+ *
578
+ * @param card - the adaptive card raw JSON.
579
+ * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
580
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
581
+ * @returns the response of sending adaptive card message.
582
+ */
583
+ sendAdaptiveCard(card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
584
+ /**
585
+ * @internal
586
+ */
587
+ private newConversation;
588
+ }
589
+
590
+ /**
591
+ * A command bot for receiving commands and sending responses in Teams.
592
+ *
593
+ * @remarks
594
+ * Ensure each command should ONLY be registered with the command once, otherwise it'll cause unexpected behavior if you register the same command more than once.
595
+ */
596
+ export declare class CommandBot {
597
+ private readonly adapter;
598
+ private readonly middleware;
599
+ private readonly ssoConfig;
600
+ /**
601
+ * Creates a new instance of the `CommandBot`.
602
+ *
603
+ * @param adapter The bound `BotFrameworkAdapter`.
604
+ * @param options - initialize options
605
+ */
606
+ constructor(adapter: BotFrameworkAdapter, options?: CommandOptions, ssoCommandActivityHandler?: BotSsoExecutionActivityHandler, ssoConfig?: BotSsoConfig);
607
+ /**
608
+ * Registers a command into the command bot.
609
+ *
610
+ * @param command The command to register.
611
+ */
612
+ registerCommand(command: TeamsFxBotCommandHandler): void;
613
+ /**
614
+ * Registers commands into the command bot.
615
+ *
616
+ * @param commands The commands to register.
617
+ */
618
+ registerCommands(commands: TeamsFxBotCommandHandler[]): void;
619
+ /**
620
+ * Registers a sso command into the command bot.
621
+ *
622
+ * @param command The command to register.
623
+ */
624
+ registerSsoCommand(ssoCommand: TeamsFxBotSsoCommandHandler): void;
625
+ /**
626
+ * Registers commands into the command bot.
627
+ *
628
+ * @param commands The commands to register.
629
+ */
630
+ registerSsoCommands(ssoCommands: TeamsFxBotSsoCommandHandler[]): void;
631
+ private validateSsoActivityHandler;
632
+ }
633
+
634
+ /**
635
+ * Interface for a command message that can handled in a command handler.
636
+ */
637
+ export declare interface CommandMessage {
638
+ /**
639
+ * Text of the message sent by the user.
640
+ */
641
+ text: string;
642
+ /**
643
+ * The capture groups that matched to the {@link TriggerPatterns} in a {@link TeamsFxBotCommandHandler} instance.
644
+ */
645
+ matches?: RegExpMatchArray;
646
+ }
647
+
648
+ /**
649
+ * Options to initialize {@link CommandBot}.
650
+ */
651
+ export declare interface CommandOptions {
652
+ /**
653
+ * The commands to registered with the command bot. Each command should implement the interface {@link TeamsFxBotCommandHandler} so that it can be correctly handled by this command bot.
654
+ */
655
+ commands?: TeamsFxBotCommandHandler[];
656
+ /**
657
+ * The commands to registered with the sso command bot. Each sso command should implement the interface {@link TeamsFxBotSsoCommandHandler} so that it can be correctly handled by this command bot.
658
+ */
659
+ ssoCommands?: TeamsFxBotSsoCommandHandler[];
660
+ }
661
+
662
+ /**
663
+ * Provide utilities for bot conversation, including:
664
+ * - handle command and response.
665
+ * - send notification to varies targets (e.g., member, group, channel).
666
+ *
667
+ * @example
668
+ * For command and response, you can register your commands through the constructor, or use the `registerCommand` and `registerCommands` API to add commands later.
669
+ *
670
+ * ```typescript
671
+ * // register through constructor
672
+ * const conversationBot = new ConversationBot({
673
+ * command: {
674
+ * enabled: true,
675
+ * commands: [ new HelloWorldCommandHandler() ],
676
+ * },
677
+ * });
678
+ *
679
+ * // register through `register*` API
680
+ * conversationBot.command.registerCommand(new HelpCommandHandler());
681
+ * ```
682
+ *
683
+ * For notification, you can enable notification at initialization, then send notifications at any time.
684
+ *
685
+ * ```typescript
686
+ * // enable through constructor
687
+ * const conversationBot = new ConversationBot({
688
+ * notification: {
689
+ * enabled: true,
690
+ * },
691
+ * });
692
+ *
693
+ * // get all bot installations and send message
694
+ * for (const target of await conversationBot.notification.installations()) {
695
+ * await target.sendMessage("Hello Notification");
696
+ * }
697
+ *
698
+ * // alternative - send message to all members
699
+ * for (const target of await conversationBot.notification.installations()) {
700
+ * for (const member of await target.members()) {
701
+ * await member.sendMessage("Hello Notification");
702
+ * }
703
+ * }
704
+ * ```
705
+ *
706
+ * @remarks
707
+ * Set `adapter` in {@link ConversationOptions} to use your own bot adapter.
708
+ *
709
+ * For command and response, ensure each command should ONLY be registered with the command once, otherwise it'll cause unexpected behavior if you register the same command more than once.
710
+ *
711
+ * For notification, set `notification.storage` in {@link ConversationOptions} to use your own storage implementation.
712
+ */
713
+ export declare class ConversationBot {
714
+ /**
715
+ * The bot adapter.
716
+ */
717
+ readonly adapter: BotFrameworkAdapter;
718
+ /**
719
+ * The entrypoint of command and response.
720
+ */
721
+ readonly command?: CommandBot;
722
+ /**
723
+ * The entrypoint of notification.
724
+ */
725
+ readonly notification?: NotificationBot;
726
+ /**
727
+ * The action handler used for adaptive card universal actions.
728
+ */
729
+ readonly cardAction?: CardActionBot;
730
+ /**
731
+ * Creates new instance of the `ConversationBot`.
732
+ *
733
+ * @remarks
734
+ * It's recommended to create your own adapter and storage for production environment instead of the default one.
735
+ *
736
+ * @param options - initialize options
737
+ */
738
+ constructor(options: ConversationOptions);
739
+ private createDefaultAdapter;
740
+ /**
741
+ * The request handler to integrate with web request.
742
+ *
743
+ * @param req - an Express or Restify style request object.
744
+ * @param res - an Express or Restify style response object.
745
+ * @param logic - the additional function to handle bot context.
746
+ *
747
+ * @example
748
+ * For example, to use with Restify:
749
+ * ``` typescript
750
+ * // The default/empty behavior
751
+ * server.post("api/messages", conversationBot.requestHandler);
752
+ *
753
+ * // Or, add your own logic
754
+ * server.post("api/messages", async (req, res) => {
755
+ * await conversationBot.requestHandler(req, res, async (context) => {
756
+ * // your-own-context-logic
757
+ * });
758
+ * });
759
+ * ```
760
+ */
761
+ requestHandler(req: WebRequest, res: WebResponse, logic?: (context: TurnContext) => Promise<any>): Promise<void>;
762
+ }
763
+
764
+ /**
765
+ * Options to initialize {@link ConversationBot}
766
+ */
767
+ export declare interface ConversationOptions {
768
+ /**
769
+ * The bot adapter. If not provided, a default adapter will be created:
770
+ * - with `adapterConfig` as constructor parameter.
771
+ * - with a default error handler that logs error to console, sends trace activity, and sends error message to user.
772
+ *
773
+ * @remarks
774
+ * If neither `adapter` nor `adapterConfig` is provided, will use BOT_ID and BOT_PASSWORD from environment variables.
775
+ */
776
+ adapter?: BotFrameworkAdapter;
777
+ /**
778
+ * If `adapter` is not provided, this `adapterConfig` will be passed to the new `BotFrameworkAdapter` when created internally.
779
+ *
780
+ * @remarks
781
+ * If neither `adapter` nor `adapterConfig` is provided, will use BOT_ID and BOT_PASSWORD from environment variables.
782
+ */
783
+ adapterConfig?: {
784
+ [key: string]: unknown;
785
+ };
786
+ /**
787
+ * Configurations for sso command bot
788
+ */
789
+ ssoConfig?: BotSsoConfig;
790
+ /**
791
+ * The command part.
792
+ */
793
+ command?: CommandOptions & {
794
+ /**
795
+ * Whether to enable command or not.
796
+ */
797
+ enabled?: boolean;
798
+ };
799
+ /**
800
+ * The notification part.
801
+ */
802
+ notification?: NotificationOptions_2 & {
803
+ /**
804
+ * Whether to enable notification or not.
805
+ */
806
+ enabled?: boolean;
807
+ };
808
+ /**
809
+ * The adaptive card action handler part.
810
+ */
811
+ cardAction?: CardActionOptions & {
812
+ /**
813
+ * Whether to enable adaptive card actions or not.
814
+ */
815
+ enabled?: boolean;
816
+ };
817
+ }
818
+
819
+ /**
820
+ * Initializes new Axios instance with specific auth provider
821
+ *
822
+ * @param apiEndpoint - Base url of the API
823
+ * @param authProvider - Auth provider that injects authentication info to each request
824
+ * @returns axios instance configured with specfic auth provider
825
+ *
826
+ * @example
827
+ * ```typescript
828
+ * const client = createApiClient("https://my-api-endpoint-base-url", new BasicAuthProvider("xxx","xxx"));
829
+ * ```
830
+ */
831
+ export declare function createApiClient(apiEndpoint: string, authProvider: AuthProvider): AxiosInstance;
832
+
833
+ /**
834
+ * Get Microsoft graph client.
835
+ * @example
836
+ * Get Microsoft graph client by TokenCredential
837
+ * ```typescript
838
+ * // Sso token example (Azure Function)
839
+ * const ssoToken = "YOUR_TOKEN_STRING";
840
+ * const options = {"AAD_APP_ID", "AAD_APP_SECRET"};
841
+ * const credential = new OnBehalfOfAADUserCredential(ssoToken, options);
842
+ * const graphClient = await createMicrosoftGraphClient(credential);
843
+ * const profile = await graphClient.api("/me").get();
844
+ *
845
+ * // TeamsBotSsoPrompt example (Bot Application)
846
+ * const requiredScopes = ["User.Read"];
847
+ * const config: Configuration = {
848
+ * loginUrl: loginUrl,
849
+ * clientId: clientId,
850
+ * clientSecret: clientSecret,
851
+ * tenantId: tenantId
852
+ * };
853
+ * const prompt = new TeamsBotSsoPrompt(dialogId, {
854
+ * config: config
855
+ * scopes: '["User.Read"],
856
+ * });
857
+ * this.addDialog(prompt);
858
+ *
859
+ * const oboCredential = new OnBehalfOfAADUserCredential(
860
+ * getUserId(dialogContext),
861
+ * {
862
+ * clientId: "AAD_APP_ID",
863
+ * clientSecret: "AAD_APP_SECRET"
864
+ * });
865
+ * try {
866
+ * const graphClient = await createMicrosoftGraphClient(credential);
867
+ * const profile = await graphClient.api("/me").get();
868
+ * } catch (e) {
869
+ * dialogContext.beginDialog(dialogId);
870
+ * return Dialog.endOfTurn();
871
+ * }
872
+ * ```
873
+ *
874
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth.
875
+ * @param scopes - The array of Microsoft Token scope of access. Default value is `[.default]`.
876
+ *
877
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
878
+ *
879
+ * @returns Graph client with specified scopes.
880
+ */
881
+ export declare function createMicrosoftGraphClient(teamsfx: TeamsFxConfiguration, scopes?: string | string[]): Client;
882
+
883
+ /**
884
+ * Get Microsoft graph client.
885
+ * @example
886
+ * Get Microsoft graph client by TokenCredential
887
+ * ```typescript
888
+ * // In browser: TeamsUserCredential
889
+ * const authConfig: TeamsUserCredentialAuthConfig = {
890
+ * clientId: "xxx",
891
+ initiateLoginEndpoint: "https://xxx/auth-start.html",
892
+ * };
893
+
894
+ * const credential = new TeamsUserCredential(authConfig);
895
+
896
+ * const scope = "User.Read";
897
+ * await credential.login(scope);
898
+
899
+ * const client = createMicrosoftGraphClientWithCredential(credential, scope);
900
+
901
+ * // In node: OnBehalfOfUserCredential
902
+ * const oboAuthConfig: OnBehalfOfCredentialAuthConfig = {
903
+ * authorityHost: "xxx",
904
+ * clientId: "xxx",
905
+ * tenantId: "xxx",
906
+ * clientSecret: "xxx",
907
+ * };
908
+
909
+ * const oboCredential = new OnBehalfOfUserCredential(ssoToken, oboAuthConfig);
910
+ * const scope = "User.Read";
911
+ * const client = createMicrosoftGraphClientWithCredential(oboCredential, scope);
912
+
913
+ * // In node: AppCredential
914
+ * const appAuthConfig: AppCredentialAuthConfig = {
915
+ * authorityHost: "xxx",
916
+ * clientId: "xxx",
917
+ * tenantId: "xxx",
918
+ * clientSecret: "xxx",
919
+ * };
920
+ * const appCredential = new AppCredential(appAuthConfig);
921
+ * const scope = "User.Read";
922
+ * const client = createMicrosoftGraphClientWithCredential(appCredential, scope);
923
+ *
924
+ * const profile = await client.api("/me").get();
925
+ * ```
926
+ *
927
+ * @param {TokenCredential} credential - Used to provide configuration and auth.
928
+ * @param scopes - The array of Microsoft Token scope of access. Default value is `[.default]`.
929
+ *
930
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
931
+ *
932
+ * @returns Graph client with specified scopes.
933
+ */
934
+ export declare function createMicrosoftGraphClientWithCredential(credential: TokenCredential, scopes?: string | string[]): Client;
935
+
936
+ /**
937
+ * Helper to create SecureContextOptions from PEM format cert
938
+ *
939
+ * @param { string | Buffer } cert - The cert chain in PEM format
940
+ * @param { string | Buffer } key - The private key for the cert chain
941
+ * @param { {passphrase?: string; ca?: string | Buffer} } options - Optional settings when create the cert options.
942
+ *
943
+ * @returns Instance of SecureContextOptions
944
+ *
945
+ * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
946
+ *
947
+ */
948
+ export declare function createPemCertOption(cert: string | Buffer, key: string | Buffer, options?: {
949
+ passphrase?: string;
950
+ ca?: string | Buffer;
951
+ }): SecureContextOptions;
952
+
953
+ /**
954
+ * Helper to create SecureContextOptions from PFX format cert
955
+ *
956
+ * @param { string | Buffer } pfx - The content of .pfx file
957
+ * @param { {passphrase?: string} } options - Optional settings when create the cert options.
958
+ *
959
+ * @returns Instance of SecureContextOptions
960
+ *
961
+ * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
962
+ *
963
+ */
964
+ export declare function createPfxCertOption(pfx: string | Buffer, options?: {
965
+ passphrase?: string;
966
+ }): SecureContextOptions;
967
+
968
+ /**
969
+ * Error code to trace the error types.
970
+ */
971
+ export declare enum ErrorCode {
972
+ /**
973
+ * Invalid parameter error.
974
+ */
975
+ InvalidParameter = "InvalidParameter",
976
+ /**
977
+ * Invalid configuration error.
978
+ */
979
+ InvalidConfiguration = "InvalidConfiguration",
980
+ /**
981
+ * Invalid certificate error.
982
+ */
983
+ InvalidCertificate = "InvalidCertificate",
984
+ /**
985
+ * Internal error.
986
+ */
987
+ InternalError = "InternalError",
988
+ /**
989
+ * Channel is not supported error.
990
+ */
991
+ ChannelNotSupported = "ChannelNotSupported",
992
+ /**
993
+ * Failed to retrieve sso token
994
+ */
995
+ FailedToRetrieveSsoToken = "FailedToRetrieveSsoToken",
996
+ /**
997
+ * Failed to process sso handler
998
+ */
999
+ FailedToProcessSsoHandler = "FailedToProcessSsoHandler",
1000
+ /**
1001
+ * Cannot find command
1002
+ */
1003
+ CannotFindCommand = "CannotFindCommand",
1004
+ /**
1005
+ * Failed to run sso step
1006
+ */
1007
+ FailedToRunSsoStep = "FailedToRunSsoStep",
1008
+ /**
1009
+ * Failed to run dedup step
1010
+ */
1011
+ FailedToRunDedupStep = "FailedToRunDedupStep",
1012
+ /**
1013
+ * Sso activity handler is undefined
1014
+ */
1015
+ SsoActivityHandlerIsUndefined = "SsoActivityHandlerIsUndefined",
1016
+ /**
1017
+ * Runtime is not supported error.
1018
+ */
1019
+ RuntimeNotSupported = "RuntimeNotSupported",
1020
+ /**
1021
+ * User failed to finish the AAD consent flow failed.
1022
+ */
1023
+ ConsentFailed = "ConsentFailed",
1024
+ /**
1025
+ * The user or administrator has not consented to use the application error.
1026
+ */
1027
+ UiRequiredError = "UiRequiredError",
1028
+ /**
1029
+ * Token is not within its valid time range error.
1030
+ */
1031
+ TokenExpiredError = "TokenExpiredError",
1032
+ /**
1033
+ * Call service (AAD or simple authentication server) failed.
1034
+ */
1035
+ ServiceError = "ServiceError",
1036
+ /**
1037
+ * Operation failed.
1038
+ */
1039
+ FailedOperation = "FailedOperation",
1040
+ /**
1041
+ * Invalid response error.
1042
+ */
1043
+ InvalidResponse = "InvalidResponse",
1044
+ /**
1045
+ * Identity type error.
1046
+ */
1047
+ IdentityTypeNotSupported = "IdentityTypeNotSupported",
1048
+ /**
1049
+ * Authentication info already exists error.
1050
+ */
1051
+ AuthorizationInfoAlreadyExists = "AuthorizationInfoAlreadyExists"
1052
+ }
1053
+
1054
+ /**
1055
+ * Error class with code and message thrown by the SDK.
1056
+ */
1057
+ export declare class ErrorWithCode extends Error {
1058
+ /**
1059
+ * Error code
1060
+ *
1061
+ * @readonly
1062
+ */
1063
+ code: string | undefined;
1064
+ /**
1065
+ * Constructor of ErrorWithCode.
1066
+ *
1067
+ * @param {string} message - error message.
1068
+ * @param {ErrorCode} code - error code.
1069
+ */
1070
+ constructor(message?: string, code?: ErrorCode);
1071
+ }
1072
+
1073
+ /**
1074
+ * Get log level.
1075
+ *
1076
+ * @returns Log level
1077
+ */
1078
+ export declare function getLogLevel(): LogLevel | undefined;
1079
+
1080
+ export declare interface GetTeamsUserTokenOptions extends GetTokenOptions {
1081
+ resources?: string[];
1082
+ }
1083
+
1084
+ /**
1085
+ * Generate connection configuration consumed by tedious.
1086
+ *
1087
+ * @deprecated we recommend you compose your own Tedious configuration for better flexibility.
1088
+ *
1089
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth
1090
+ * @param { string? } databaseName - specify database name to override default one if there are multiple databases.
1091
+ *
1092
+ * @returns Connection configuration of tedious for the SQL.
1093
+ *
1094
+ * @throws {@link ErrorCode|InvalidConfiguration} when SQL config resource configuration is invalid.
1095
+ * @throws {@link ErrorCode|InternalError} when get user MSI token failed or MSI token is invalid.
1096
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1097
+ */
1098
+ export declare function getTediousConnectionConfig(teamsfx: TeamsFx, databaseName?: string): Promise<ConnectionConfig>;
1099
+
1100
+ /**
1101
+ * Users execute query in message extension with SSO or access token.
1102
+ *
1103
+ * @param {TurnContext} context - The context object for the current turn.
1104
+ * @param {OnBehalfOfCredentialAuthConfig} config - User custom the message extension authentication configuration.
1105
+ * @param {initiateLoginEndpoint} initiateLoginEndpoint - Login page for Teams to redirect to.
1106
+ * @param {string| string[]} scopes - The list of scopes for which the token will have access.
1107
+ * @param {function} logic - Business logic when executing the query in message extension with SSO or access token.
1108
+ *
1109
+ * @throws {@link ErrorCode|InternalError} when User invoke not response to message extension query.
1110
+ * @throws {@link ErrorCode|InternalError} when failed to get access token with unknown error.
1111
+ * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1112
+ * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth server.
1113
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1114
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1115
+ *
1116
+ * @returns A MessageExtension Response for the activity. If the logic not return any, return void instead.
1117
+ */
1118
+ export declare function handleMessageExtensionQueryWithSSO(context: TurnContext, config: OnBehalfOfCredentialAuthConfig, initiateLoginEndpoint: string, scopes: string | string[], logic: (token: MessageExtensionTokenResponse) => Promise<any>): Promise<void | MessagingExtensionResponse>;
1119
+
1120
+ /**
1121
+ * Users execute query in message extension with SSO or access token.
1122
+ *
1123
+ *
1124
+ * @param {TurnContext} context - The context object for the current turn.
1125
+ * @param {AuthenticationConfiguration} config - User custom the message extension authentication configuration.
1126
+ * @param {string| string[]} scopes - The list of scopes for which the token will have access.
1127
+ * @param {function} logic - Business logic when executing the query in message extension with SSO or access token.
1128
+ *
1129
+ * @throws {@link ErrorCode|InternalError} when User invoke not response to message extension query.
1130
+ * @throws {@link ErrorCode|InternalError} when failed to get access token with unknown error.
1131
+ * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1132
+ * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth server.
1133
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1134
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1135
+ *
1136
+ * @returns A MessageExtension Response for the activity. If the logic not return any, return void instead.
1137
+ */
1138
+ export declare function handleMessageExtensionQueryWithToken(context: TurnContext, config: AuthenticationConfiguration | null, scopes: string | string[], logic: (token: MessageExtensionTokenResponse) => Promise<any>): Promise<MessagingExtensionResponse | void>;
1139
+
1140
+ /**
1141
+ * Identity type to use in authentication.
1142
+ */
1143
+ export declare enum IdentityType {
1144
+ /**
1145
+ * Represents the current user of Teams.
1146
+ */
1147
+ User = "User",
1148
+ /**
1149
+ * Represents the application itself.
1150
+ */
1151
+ App = "Application"
1152
+ }
1153
+
1154
+ /**
1155
+ * Status code for an `application/vnd.microsoft.error` invoke response.
1156
+ */
1157
+ export declare enum InvokeResponseErrorCode {
1158
+ /**
1159
+ * Invalid request.
1160
+ */
1161
+ BadRequest = 400,
1162
+ /**
1163
+ * Internal server error.
1164
+ */
1165
+ InternalServerError = 500
1166
+ }
1167
+
1168
+ /**
1169
+ * Provides methods for formatting various invoke responses a bot can send to respond to an invoke request.
1170
+ *
1171
+ * @remarks
1172
+ * All of these functions return an {@link InvokeResponse} object, which can be
1173
+ * passed as input to generate a new `invokeResponse` activity.
1174
+ *
1175
+ * This example sends an invoke response that contains an adaptive card.
1176
+ *
1177
+ * ```typescript
1178
+ *
1179
+ * const myCard = {
1180
+ * type: "AdaptiveCard",
1181
+ * body: [
1182
+ * {
1183
+ * "type": "TextBlock",
1184
+ * "text": "This is a sample card"
1185
+ * }],
1186
+ * $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
1187
+ * version: "1.4"
1188
+ * };
1189
+ *
1190
+ * const invokeResponse = InvokeResponseFactory.adaptiveCard(myCard);
1191
+ * await context.sendActivity({
1192
+ * type: ActivityTypes.InvokeResponse,
1193
+ * value: invokeResponse,
1194
+ * });
1195
+ * ```
1196
+ */
1197
+ export declare class InvokeResponseFactory {
1198
+ /**
1199
+ * Create an invoke response from a text message.
1200
+ * The type of the invoke response is `application/vnd.microsoft.activity.message`
1201
+ * indicates the request was successfully processed.
1202
+ *
1203
+ * @param message A text message included in a invoke response.
1204
+ *
1205
+ * @returns {InvokeResponse} An InvokeResponse object.
1206
+ */
1207
+ static textMessage(message: string): InvokeResponse;
1208
+ /**
1209
+ * Create an invoke response from an adaptive card.
1210
+ *
1211
+ * The type of the invoke response is `application/vnd.microsoft.card.adaptive` indicates
1212
+ * the request was successfully processed, and the response includes an adaptive card
1213
+ * that the client should display in place of the current one.
1214
+ *
1215
+ * @param card The adaptive card JSON payload.
1216
+ *
1217
+ * @returns {InvokeResponse} An InvokeResponse object.
1218
+ */
1219
+ static adaptiveCard(card: unknown): InvokeResponse;
1220
+ /**
1221
+ * Create an invoke response with error code and message.
1222
+ *
1223
+ * The type of the invoke response is `application/vnd.microsoft.error` indicates
1224
+ * the request was failed to processed.
1225
+ *
1226
+ * @param errorCode The status code indicates error, available values:
1227
+ * - 400 (BadRequest): indicate the incoming request was invalid.
1228
+ * - 500 (InternalServerError): indicate an unexpected error occurred.
1229
+ * @param errorMessage The error message.
1230
+ *
1231
+ * @returns {InvokeResponse} An InvokeResponse object.
1232
+ */
1233
+ static errorResponse(errorCode: InvokeResponseErrorCode, errorMessage: string): InvokeResponse;
1234
+ /**
1235
+ * Create an invoke response with status code and response value.
1236
+ * @param statusCode The status code.
1237
+ * @param body The value of the response body.
1238
+ *
1239
+ * @returns {InvokeResponse} An InvokeResponse object.
1240
+ */
1241
+ static createInvokeResponse(statusCode: StatusCodes, body?: unknown): InvokeResponse;
1242
+ }
1243
+
1244
+ /**
1245
+ * Log function for customized logging.
1246
+ */
1247
+ export declare type LogFunction = (level: LogLevel, message: string) => void;
1248
+
1249
+ /**
1250
+ * Interface for customized logger.
1251
+ */
1252
+ export declare interface Logger {
1253
+ /**
1254
+ * Writes to error level logging or lower.
1255
+ */
1256
+ error(message: string): void;
1257
+ /**
1258
+ * Writes to warning level logging or lower.
1259
+ */
1260
+ warn(message: string): void;
1261
+ /**
1262
+ * Writes to info level logging or lower.
1263
+ */
1264
+ info(message: string): void;
1265
+ /**
1266
+ * Writes to verbose level logging.
1267
+ */
1268
+ verbose(message: string): void;
1269
+ }
1270
+
1271
+ /**
1272
+ * Log level.
1273
+ */
1274
+ export declare enum LogLevel {
1275
+ /**
1276
+ * Show verbose, information, warning and error message.
1277
+ */
1278
+ Verbose = 0,
1279
+ /**
1280
+ * Show information, warning and error message.
1281
+ */
1282
+ Info = 1,
1283
+ /**
1284
+ * Show warning and error message.
1285
+ */
1286
+ Warn = 2,
1287
+ /**
1288
+ * Show error message.
1289
+ */
1290
+ Error = 3
1291
+ }
1292
+
1293
+ /**
1294
+ * A {@link NotificationTarget} that represents a team member.
1295
+ *
1296
+ * @remarks
1297
+ * It's recommended to get members from {@link TeamsBotInstallation.members()}.
1298
+ */
1299
+ export declare class Member implements NotificationTarget {
1300
+ /**
1301
+ * The parent {@link TeamsBotInstallation} where this member is created from.
1302
+ */
1303
+ readonly parent: TeamsBotInstallation;
1304
+ /**
1305
+ * Detailed member account information.
1306
+ */
1307
+ readonly account: TeamsChannelAccount;
1308
+ /**
1309
+ * Notification target type. For member it's always "Person".
1310
+ */
1311
+ readonly type: NotificationTargetType;
1312
+ /**
1313
+ * Constructor.
1314
+ *
1315
+ * @remarks
1316
+ * It's recommended to get members from {@link TeamsBotInstallation.members()}, instead of using this constructor.
1317
+ *
1318
+ * @param parent - The parent {@link TeamsBotInstallation} where this member is created from.
1319
+ * @param account - Detailed member account information.
1320
+ */
1321
+ constructor(parent: TeamsBotInstallation, account: TeamsChannelAccount);
1322
+ /**
1323
+ * Send a plain text message.
1324
+ *
1325
+ * @param text - the plain text message.
1326
+ * @param onError - an optional error handler that can catch exceptions during message sending.
1327
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
1328
+ * @returns the response of sending message.
1329
+ */
1330
+ sendMessage(text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1331
+ /**
1332
+ * Send an adaptive card message.
1333
+ *
1334
+ * @param card - the adaptive card raw JSON.
1335
+ * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
1336
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
1337
+ * @returns the response of sending adaptive card message.
1338
+ */
1339
+ sendAdaptiveCard(card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1340
+ /**
1341
+ * @internal
1342
+ */
1343
+ private newConversation;
1344
+ }
1345
+
1346
+ /**
1347
+ * Provides utility method to build bot message with cards that supported in Teams.
1348
+ */
1349
+ export declare class MessageBuilder {
1350
+ /**
1351
+ * Build a bot message activity attached with adaptive card.
1352
+ *
1353
+ * @param cardTemplate The adaptive card template.
1354
+ * @param data card data used to render the template.
1355
+ * @returns A bot message activity attached with an adaptive card.
1356
+ *
1357
+ * @example
1358
+ * ```javascript
1359
+ * const cardTemplate = {
1360
+ * type: "AdaptiveCard",
1361
+ * body: [
1362
+ * {
1363
+ * "type": "TextBlock",
1364
+ * "text": "${title}",
1365
+ * "size": "Large"
1366
+ * },
1367
+ * {
1368
+ * "type": "TextBlock",
1369
+ * "text": "${description}"
1370
+ * }],
1371
+ * $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
1372
+ * version: "1.4"
1373
+ * };
1374
+ *
1375
+ * type CardData = {
1376
+ * title: string,
1377
+ * description: string
1378
+ * };
1379
+ * const card = MessageBuilder.attachAdaptiveCard<CardData>(
1380
+ * cardTemplate, {
1381
+ * title: "sample card title",
1382
+ * description: "sample card description"
1383
+ * });
1384
+ * ```
1385
+ */
1386
+ static attachAdaptiveCard<TData extends object>(cardTemplate: unknown, data: TData): Partial<Activity>;
1387
+ /**
1388
+ * Build a bot message activity attached with an adaptive card.
1389
+ *
1390
+ * @param card The adaptive card content.
1391
+ * @returns A bot message activity attached with an adaptive card.
1392
+ */
1393
+ static attachAdaptiveCardWithoutData(card: unknown): Partial<Activity>;
1394
+ /**
1395
+ * Build a bot message activity attached with an hero card.
1396
+ *
1397
+ * @param title The card title.
1398
+ * @param images Optional. The array of images to include on the card.
1399
+ * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
1400
+ * is converted to an `imBack` button with a title and value set to the value of the string.
1401
+ * @param other Optional. Any additional properties to include on the card.
1402
+ *
1403
+ * @returns A bot message activity attached with a hero card.
1404
+ *
1405
+ * @example
1406
+ * ```javascript
1407
+ * const message = MessageBuilder.attachHeroCard(
1408
+ * 'sample title',
1409
+ * ['https://example.com/sample.jpg'],
1410
+ * ['action']
1411
+ * );
1412
+ * ```
1413
+ */
1414
+ static attachHeroCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<HeroCard>): Partial<Activity>;
1415
+ /**
1416
+ * Returns an attachment for a sign-in card.
1417
+ *
1418
+ * @param title The title for the card's sign-in button.
1419
+ * @param url The URL of the sign-in page to use.
1420
+ * @param text Optional. Additional text to include on the card.
1421
+ *
1422
+ * @returns A bot message activity attached with a sign-in card.
1423
+ *
1424
+ * @remarks
1425
+ * For channels that don't natively support sign-in cards, an alternative message is rendered.
1426
+ */
1427
+ static attachSigninCard(title: string, url: string, text?: string): Partial<Activity>;
1428
+ /**
1429
+ * Build a bot message activity attached with an Office 365 connector card.
1430
+ *
1431
+ * @param card A description of the Office 365 connector card.
1432
+ * @returns A bot message activity attached with an Office 365 connector card.
1433
+ */
1434
+ static attachO365ConnectorCard(card: O365ConnectorCard): Partial<Activity>;
1435
+ /**
1436
+ * Build a message activity attached with a receipt card.
1437
+ * @param card A description of the receipt card.
1438
+ * @returns A message activity attached with a receipt card.
1439
+ */
1440
+ static AttachReceiptCard(card: ReceiptCard): Partial<Activity>;
1441
+ /**
1442
+ *
1443
+ * @param title The card title.
1444
+ * @param images Optional. The array of images to include on the card.
1445
+ * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
1446
+ * is converted to an `imBack` button with a title and value set to the value of the string.
1447
+ * @param other Optional. Any additional properties to include on the card.
1448
+ * @returns A message activity attached with a thumbnail card
1449
+ */
1450
+ static attachThumbnailCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<ThumbnailCard>): Partial<Activity>;
1451
+ /**
1452
+ * Add an attachement to a bot activity.
1453
+ * @param attachement The attachment object to attach.
1454
+ * @returns A message activity with an attachment.
1455
+ */
1456
+ static attachContent(attachement: Attachment): Partial<Activity>;
1457
+ }
1458
+
1459
+ /**
1460
+ * Token response provided by Teams Bot SSO prompt
1461
+ */
1462
+ export declare interface MessageExtensionTokenResponse extends TokenResponse {
1463
+ /**
1464
+ * SSO token for user
1465
+ */
1466
+ ssoToken: string;
1467
+ /**
1468
+ * Expire time of SSO token
1469
+ */
1470
+ ssoTokenExpiration: string;
1471
+ }
1472
+
1473
+ /**
1474
+ * The response of a message action, e.g., `sendMessage`, `sendAdaptiveCard`.
1475
+ */
1476
+ declare interface MessageResponse {
1477
+ /**
1478
+ * Id of the message.
1479
+ */
1480
+ id?: string;
1481
+ }
1482
+
1483
+ /**
1484
+ * Microsoft Graph auth provider for Teams Framework
1485
+ */
1486
+ export declare class MsGraphAuthProvider implements AuthenticationProvider {
1487
+ private credentialOrTeamsFx;
1488
+ private scopes;
1489
+ /**
1490
+ * Constructor of MsGraphAuthProvider.
1491
+ *
1492
+ * @param {TeamsFxConfiguration} teamsfx - Used to provide configuration and auth.
1493
+ * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1494
+ *
1495
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1496
+ *
1497
+ * @returns An instance of MsGraphAuthProvider.
1498
+ */
1499
+ constructor(teamsfx: TeamsFxConfiguration, scopes?: string | string[]);
1500
+ /**
1501
+ * Constructor of MsGraphAuthProvider.
1502
+ *
1503
+ * @param {TokenCredential} credential - credential used to provide configuration and auth.
1504
+ * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1505
+ *
1506
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1507
+ *
1508
+ * @returns An instance of MsGraphAuthProvider.
1509
+ */
1510
+ constructor(credential: TokenCredential, scopes?: string | string[]);
1511
+ /**
1512
+ * Get access token for Microsoft Graph API requests.
1513
+ *
1514
+ * @throws {@link ErrorCode|InternalError} when get access token failed due to empty token or unknown other problems.
1515
+ * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1516
+ * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1517
+ * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth or AAD server.
1518
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1519
+ *
1520
+ * @returns Access token from the credential.
1521
+ *
1522
+ */
1523
+ getAccessToken(): Promise<string>;
1524
+ }
1525
+
1526
+ /**
1527
+ * Provide utilities to send notification to varies targets (e.g., member, group, channel).
1528
+ */
1529
+ export declare class NotificationBot {
1530
+ private readonly conversationReferenceStore;
1531
+ private readonly adapter;
1532
+ /**
1533
+ * constructor of the notification bot.
1534
+ *
1535
+ * @remarks
1536
+ * To ensure accuracy, it's recommended to initialize before handling any message.
1537
+ *
1538
+ * @param adapter - the bound `BotFrameworkAdapter`
1539
+ * @param options - initialize options
1540
+ */
1541
+ constructor(adapter: BotFrameworkAdapter, options?: NotificationOptions_2);
1542
+ /**
1543
+ * Get all targets where the bot is installed.
1544
+ *
1545
+ * @remarks
1546
+ * The result is retrieving from the persisted storage.
1547
+ *
1548
+ * @returns - an array of {@link TeamsBotInstallation}.
1549
+ */
1550
+ installations(): Promise<TeamsBotInstallation[]>;
1551
+ /**
1552
+ * Returns the first {@link Member} where predicate is true, and undefined otherwise.
1553
+ *
1554
+ * @param predicate find calls predicate once for each member of the installation,
1555
+ * until it finds one where predicate returns true. If such a member is found, find
1556
+ * immediately returns that member. Otherwise, find returns undefined.
1557
+ * @param scope the scope to find members from the installations
1558
+ * (personal chat, group chat, Teams channel).
1559
+ * @returns the first {@link Member} where predicate is true, and undefined otherwise.
1560
+ */
1561
+ findMember(predicate: (member: Member) => Promise<boolean>, scope?: SearchScope): Promise<Member | undefined>;
1562
+ /**
1563
+ * Returns the first {@link Channel} where predicate is true, and undefined otherwise.
1564
+ * (Ensure the bot app is installed into the `General` channel, otherwise undefined will be returned.)
1565
+ *
1566
+ * @param predicate find calls predicate once for each channel of the installation,
1567
+ * until it finds one where predicate returns true. If such a channel is found, find
1568
+ * immediately returns that channel. Otherwise, find returns undefined.
1569
+ * @returns the first {@link Channel} where predicate is true, and undefined otherwise.
1570
+ */
1571
+ findChannel(predicate: (channel: Channel, teamDetails: TeamDetails | undefined) => Promise<boolean>): Promise<Channel | undefined>;
1572
+ /**
1573
+ * Returns all {@link Member} where predicate is true, and empty array otherwise.
1574
+ *
1575
+ * @param predicate find calls predicate for each member of the installation.
1576
+ * @param scope the scope to find members from the installations
1577
+ * (personal chat, group chat, Teams channel).
1578
+ * @returns an array of {@link Member} where predicate is true, and empty array otherwise.
1579
+ */
1580
+ findAllMembers(predicate: (member: Member) => Promise<boolean>, scope?: SearchScope): Promise<Member[]>;
1581
+ /**
1582
+ * Returns all {@link Channel} where predicate is true, and empty array otherwise.
1583
+ * (Ensure the bot app is installed into the `General` channel, otherwise empty array will be returned.)
1584
+ *
1585
+ * @param predicate find calls predicate for each channel of the installation.
1586
+ * @returns an array of {@link Channel} where predicate is true, and empty array otherwise.
1587
+ */
1588
+ findAllChannels(predicate: (channel: Channel, teamDetails: TeamDetails | undefined) => Promise<boolean>): Promise<Channel[]>;
1589
+ private matchSearchScope;
1590
+ }
1591
+
1592
+ /**
1593
+ * Options to initialize {@link NotificationBot}.
1594
+ */
1595
+ declare interface NotificationOptions_2 {
1596
+ /**
1597
+ * An optional storage to persist bot notification connections.
1598
+ *
1599
+ * @remarks
1600
+ * If `storage` is not provided, a default local file storage will be used,
1601
+ * which stores notification connections into:
1602
+ * - ".notification.localstore.json" if running locally
1603
+ * - "${process.env.TEMP}/.notification.localstore.json" if `process.env.RUNNING_ON_AZURE` is set to "1"
1604
+ *
1605
+ * It's recommended to use your own shared storage for production environment.
1606
+ */
1607
+ storage?: NotificationTargetStorage;
1608
+ }
1609
+ export { NotificationOptions_2 as NotificationOptions }
1610
+
1611
+ /**
1612
+ * Represent a notification target.
1613
+ */
1614
+ export declare interface NotificationTarget {
1615
+ /**
1616
+ * The type of target, could be "Channel" or "Group" or "Person".
1617
+ */
1618
+ readonly type?: NotificationTargetType;
1619
+ /**
1620
+ * Send a plain text message.
1621
+ *
1622
+ * @param text - the plain text message.
1623
+ * @param onError - an optional error handler that can catch exceptions during message sending.
1624
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
1625
+ *
1626
+ * @returns the response of sending message.
1627
+ */
1628
+ sendMessage(text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1629
+ /**
1630
+ * Send an adaptive card message.
1631
+ *
1632
+ * @param card - the adaptive card raw JSON.
1633
+ * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
1634
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
1635
+ *
1636
+ * @returns the response of sending adaptive card message.
1637
+ */
1638
+ sendAdaptiveCard(card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1639
+ }
1640
+
1641
+ /**
1642
+ * Interface for a storage provider that stores and retrieves notification target references.
1643
+ */
1644
+ export declare interface NotificationTargetStorage {
1645
+ /**
1646
+ * Read one notification target by its key.
1647
+ *
1648
+ * @param key - the key of a notification target.
1649
+ *
1650
+ * @returns - the notification target. Or undefined if not found.
1651
+ */
1652
+ read(key: string): Promise<{
1653
+ [key: string]: unknown;
1654
+ } | undefined>;
1655
+ /**
1656
+ * List all stored notification targets.
1657
+ *
1658
+ * @returns - an array of notification target. Or an empty array if nothing is stored.
1659
+ */
1660
+ list(): Promise<{
1661
+ [key: string]: unknown;
1662
+ }[]>;
1663
+ /**
1664
+ * Write one notification target by its key.
1665
+ *
1666
+ * @param key - the key of a notification target.
1667
+ * @param object - the notification target.
1668
+ */
1669
+ write(key: string, object: {
1670
+ [key: string]: unknown;
1671
+ }): Promise<void>;
1672
+ /**
1673
+ * Delete one notification target by its key.
1674
+ *
1675
+ * @param key - the key of a notification target.
1676
+ */
1677
+ delete(key: string): Promise<void>;
1678
+ }
1679
+
1680
+ /**
1681
+ * The target type where the notification will be sent to.
1682
+ *
1683
+ * @remarks
1684
+ * - "Channel" means to a team channel. (By default, notification to a team will be sent to its "General" channel.)
1685
+ * - "Group" means to a group chat.
1686
+ * - "Person" means to a personal chat.
1687
+ */
1688
+ export declare enum NotificationTargetType {
1689
+ /**
1690
+ * The notification will be sent to a team channel.
1691
+ * (By default, notification to a team will be sent to its "General" channel.)
1692
+ */
1693
+ Channel = "Channel",
1694
+ /**
1695
+ * The notification will be sent to a group chat.
1696
+ */
1697
+ Group = "Group",
1698
+ /**
1699
+ * The notification will be sent to a personal chat.
1700
+ */
1701
+ Person = "Person"
1702
+ }
1703
+
1704
+ /**
1705
+ * Authentication configuration for OnBehalfOfCredential used in node environment
1706
+ */
1707
+ export declare type OnBehalfOfCredentialAuthConfig = {
1708
+ /**
1709
+ * Hostname of AAD authority.
1710
+ */
1711
+ authorityHost: string;
1712
+ /**
1713
+ * The client (application) ID of an App Registration in the tenant
1714
+ */
1715
+ clientId: string;
1716
+ /**
1717
+ * AAD tenant id
1718
+ *
1719
+ * @readonly
1720
+ */
1721
+ tenantId: string;
1722
+ } & ({
1723
+ /**
1724
+ * Secret string that the application uses when requesting a token. Only used in confidential client applications. Can be created in the Azure app registration portal.
1725
+ */
1726
+ clientSecret: string;
1727
+ certificateContent?: never;
1728
+ } | {
1729
+ clientSecret?: never;
1730
+ /**
1731
+ * The content of a PEM-encoded public/private key certificate.
1732
+ *
1733
+ * @readonly
1734
+ */
1735
+ certificateContent: string;
1736
+ });
1737
+
1738
+ /**
1739
+ * Represent on-behalf-of flow to get user identity, and it is designed to be used in server side.
1740
+ *
1741
+ * @example
1742
+ * ```typescript
1743
+ * const credential = new OnBehalfOfUserCredential(ssoToken);
1744
+ * ```
1745
+ *
1746
+ * @remarks
1747
+ * Can only be used in server side.
1748
+ */
1749
+ export declare class OnBehalfOfUserCredential implements TokenCredential {
1750
+ private msalClient;
1751
+ private ssoToken;
1752
+ /**
1753
+ * Constructor of OnBehalfOfUserCredential
1754
+ *
1755
+ * @remarks
1756
+ * Only works in in server side.
1757
+ *
1758
+ * @param {string} ssoToken - User token provided by Teams SSO feature.
1759
+ * @param {OnBehalfOfCredentialAuthConfig} config - The authentication configuration.
1760
+ *
1761
+ * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret, certificate content, authority host or tenant id is not found in config.
1762
+ * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1763
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1764
+ */
1765
+ constructor(ssoToken: string, config: OnBehalfOfCredentialAuthConfig);
1766
+ /**
1767
+ * Constructor of OnBehalfOfUserCredential
1768
+ *
1769
+ * @remarks
1770
+ * Only works in in server side.
1771
+ *
1772
+ * @param {string} ssoToken - User token provided by Teams SSO feature.
1773
+ * @param {AuthenticationConfiguration} config - The authentication configuration. Use environment variables if not provided.
1774
+ *
1775
+ * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret, certificate content, authority host or tenant id is not found in config.
1776
+ * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1777
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1778
+ */
1779
+ constructor(ssoToken: string, config: AuthenticationConfiguration);
1780
+ /**
1781
+ * Get access token from credential.
1782
+ *
1783
+ * @example
1784
+ * ```typescript
1785
+ * await credential.getToken([]) // Get SSO token using empty string array
1786
+ * await credential.getToken("") // Get SSO token using empty string
1787
+ * await credential.getToken([".default"]) // Get Graph access token with default scope using string array
1788
+ * await credential.getToken(".default") // Get Graph access token with default scope using string
1789
+ * await credential.getToken(["User.Read"]) // Get Graph access token for single scope using string array
1790
+ * await credential.getToken("User.Read") // Get Graph access token for single scope using string
1791
+ * await credential.getToken(["User.Read", "Application.Read.All"]) // Get Graph access token for multiple scopes using string array
1792
+ * await credential.getToken("User.Read Application.Read.All") // Get Graph access token for multiple scopes using space-separated string
1793
+ * await credential.getToken("https://graph.microsoft.com/User.Read") // Get Graph access token with full resource URI
1794
+ * await credential.getToken(["https://outlook.office.com/Mail.Read"]) // Get Outlook access token
1795
+ * ```
1796
+ *
1797
+ * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1798
+ * @param {GetTokenOptions} options - The options used to configure any requests this TokenCredential implementation might make.
1799
+ *
1800
+ * @throws {@link ErrorCode|InternalError} when failed to acquire access token on behalf of user with unknown error.
1801
+ * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1802
+ * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1803
+ * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth server.
1804
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1805
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1806
+ *
1807
+ * @returns Access token with expected scopes.
1808
+ *
1809
+ * @remarks
1810
+ * If scopes is empty string or array, it returns SSO token.
1811
+ * If scopes is non-empty, it returns access token for target scope.
1812
+ */
1813
+ getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1814
+ /**
1815
+ * Get basic user info from SSO token.
1816
+ *
1817
+ * @example
1818
+ * ```typescript
1819
+ * const currentUser = getUserInfo();
1820
+ * ```
1821
+ *
1822
+ * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1823
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1824
+ *
1825
+ * @returns Basic user info with user displayName, objectId and preferredUserName.
1826
+ */
1827
+ getUserInfo(): UserInfo;
1828
+ private generateAuthServerError;
1829
+ }
1830
+
1831
+ /**
1832
+ * The search scope when calling {@link NotificationBot.findMember} and {@link NotificationBot.findAllMembers}.
1833
+ * The search scope is a flagged enum and it can be combined with `|`.
1834
+ * For example, to search from personal chat and group chat, use `SearchScope.Person | SearchScope.Group`.
1835
+ */
1836
+ export declare enum SearchScope {
1837
+ /**
1838
+ * Search members from the installations in personal chat only.
1839
+ */
1840
+ Person = 1,
1841
+ /**
1842
+ * Search members from the installations in group chat only.
1843
+ */
1844
+ Group = 2,
1845
+ /**
1846
+ * Search members from the installations in Teams channel only.
1847
+ */
1848
+ Channel = 4,
1849
+ /**
1850
+ * Search members from all installations including personal chat, group chat and Teams channel.
1851
+ */
1852
+ All = 7
1853
+ }
1854
+
1855
+ /**
1856
+ * Send an adaptive card message to a notification target.
1857
+ *
1858
+ * @param target - the notification target.
1859
+ * @param card - the adaptive card raw JSON.
1860
+ * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
1861
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
1862
+ * @returns the response of sending adaptive card message.
1863
+ */
1864
+ export declare function sendAdaptiveCard(target: NotificationTarget, card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1865
+
1866
+ /**
1867
+ * Send a plain text message to a notification target.
1868
+ *
1869
+ * @param target - the notification target.
1870
+ * @param text - the plain text message.
1871
+ * @param onError - an optional error handler that can catch exceptions during message sending.
1872
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
1873
+ * @returns the response of sending message.
1874
+ */
1875
+ export declare function sendMessage(target: NotificationTarget, text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1876
+
1877
+ /**
1878
+ * Set custom log function. Use the function if it's set. Priority is lower than setLogger.
1879
+ *
1880
+ * @param {LogFunction} logFunction - custom log function. If it's undefined, custom log function will be cleared.
1881
+ *
1882
+ * @example
1883
+ * ```typescript
1884
+ * setLogFunction((level: LogLevel, message: string) => {
1885
+ * if (level === LogLevel.Error) {
1886
+ * console.log(message);
1887
+ * }
1888
+ * });
1889
+ * ```
1890
+ */
1891
+ export declare function setLogFunction(logFunction?: LogFunction): void;
1892
+
1893
+ /**
1894
+ * Set custom logger. Use the output functions if it's set. Priority is higher than setLogFunction.
1895
+ *
1896
+ * @param {Logger} logger - custom logger. If it's undefined, custom logger will be cleared.
1897
+ *
1898
+ * @example
1899
+ * ```typescript
1900
+ * setLogger({
1901
+ * verbose: console.debug,
1902
+ * info: console.info,
1903
+ * warn: console.warn,
1904
+ * error: console.error,
1905
+ * });
1906
+ * ```
1907
+ */
1908
+ export declare function setLogger(logger?: Logger): void;
1909
+
1910
+ /**
1911
+ * Update log level helper.
1912
+ *
1913
+ * @param { LogLevel } level - log level in configuration
1914
+ */
1915
+ export declare function setLogLevel(level: LogLevel): void;
1916
+
1917
+ /**
1918
+ * A {@link NotificationTarget} that represents a bot installation. Teams Bot could be installed into
1919
+ * - Personal chat
1920
+ * - Group chat
1921
+ * - Team (by default the `General` channel)
1922
+ *
1923
+ * @remarks
1924
+ * It's recommended to get bot installations from {@link ConversationBot.installations()}.
1925
+ */
1926
+ export declare class TeamsBotInstallation implements NotificationTarget {
1927
+ /**
1928
+ * The bound `BotFrameworkAdapter`.
1929
+ */
1930
+ readonly adapter: BotFrameworkAdapter;
1931
+ /**
1932
+ * The bound `ConversationReference`.
1933
+ */
1934
+ readonly conversationReference: Partial<ConversationReference>;
1935
+ /**
1936
+ * Notification target type.
1937
+ *
1938
+ * @remarks
1939
+ * - "Channel" means bot is installed into a team and notification will be sent to its "General" channel.
1940
+ * - "Group" means bot is installed into a group chat.
1941
+ * - "Person" means bot is installed into a personal scope and notification will be sent to personal chat.
1942
+ */
1943
+ readonly type?: NotificationTargetType;
1944
+ /**
1945
+ * Constructor
1946
+ *
1947
+ * @remarks
1948
+ * It's recommended to get bot installations from {@link ConversationBot.installations()}, instead of using this constructor.
1949
+ *
1950
+ * @param adapter - the bound `BotFrameworkAdapter`.
1951
+ * @param conversationReference - the bound `ConversationReference`.
1952
+ */
1953
+ constructor(adapter: BotFrameworkAdapter, conversationReference: Partial<ConversationReference>);
1954
+ /**
1955
+ * Send a plain text message.
1956
+ *
1957
+ * @param text - the plain text message.
1958
+ * @param onError - an optional error handler that can catch exceptions during message sending.
1959
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
1960
+ * @returns the response of sending message.
1961
+ */
1962
+ sendMessage(text: string, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1963
+ /**
1964
+ * Send an adaptive card message.
1965
+ *
1966
+ * @param card - the adaptive card raw JSON.
1967
+ * @param onError - an optional error handler that can catch exceptions during adaptive card sending.
1968
+ * If not defined, error will be handled by `BotAdapter.onTurnError`.
1969
+ * @returns the response of sending adaptive card message.
1970
+ */
1971
+ sendAdaptiveCard(card: unknown, onError?: (context: TurnContext, error: Error) => Promise<void>): Promise<MessageResponse>;
1972
+ /**
1973
+ * Get channels from this bot installation.
1974
+ *
1975
+ * @returns an array of channels if bot is installed into a team, otherwise returns an empty array.
1976
+ */
1977
+ channels(): Promise<Channel[]>;
1978
+ /**
1979
+ * Get members from this bot installation.
1980
+ *
1981
+ * @returns an array of members from where the bot is installed.
1982
+ */
1983
+ members(): Promise<Member[]>;
1984
+ /**
1985
+ * Get team details from this bot installation
1986
+ *
1987
+ * @returns the team details if bot is installed into a team, otherwise returns undefined.
1988
+ */
1989
+ getTeamDetails(): Promise<TeamDetails | undefined>;
1990
+ }
1991
+
1992
+ /**
1993
+ * Creates a new prompt that leverage Teams Single Sign On (SSO) support for bot to automatically sign in user and
1994
+ * help receive oauth token, asks the user to consent if needed.
1995
+ *
1996
+ * @remarks
1997
+ * The prompt will attempt to retrieve the users current token of the desired scopes and store it in
1998
+ * the token store.
1999
+ *
2000
+ * User will be automatically signed in leveraging Teams support of Bot Single Sign On(SSO):
2001
+ * https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots
2002
+ *
2003
+ * @example
2004
+ * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named
2005
+ * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either
2006
+ * `DialogContext.beginDialog()` or `DialogContext.prompt()`. The user will be prompted to sign in as
2007
+ * needed and their access token will be passed as an argument to the callers next waterfall step:
2008
+ *
2009
+ * ```JavaScript
2010
+ * const { ConversationState, MemoryStorage } = require('botbuilder');
2011
+ * const { DialogSet, WaterfallDialog } = require('botbuilder-dialogs');
2012
+ * const { TeamsBotSsoPrompt } = require('@microsoft/teamsfx');
2013
+ *
2014
+ * const convoState = new ConversationState(new MemoryStorage());
2015
+ * const dialogState = convoState.createProperty('dialogState');
2016
+ * const dialogs = new DialogSet(dialogState);
2017
+ *
2018
+ * dialogs.add(new TeamsBotSsoPrompt('TeamsBotSsoPrompt', {
2019
+ * scopes: ["User.Read"],
2020
+ * }));
2021
+ *
2022
+ * dialogs.add(new WaterfallDialog('taskNeedingLogin', [
2023
+ * async (step) => {
2024
+ * return await step.beginDialog('TeamsBotSsoPrompt');
2025
+ * },
2026
+ * async (step) => {
2027
+ * const token = step.result;
2028
+ * if (token) {
2029
+ *
2030
+ * // ... continue with task needing access token ...
2031
+ *
2032
+ * } else {
2033
+ * await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
2034
+ * return await step.endDialog();
2035
+ * }
2036
+ * }
2037
+ * ]));
2038
+ * ```
2039
+ */
2040
+ export declare class TeamsBotSsoPrompt extends Dialog {
2041
+ private authConfig;
2042
+ private initiateLoginEndpoint;
2043
+ private settings;
2044
+ /**
2045
+ * Constructor of TeamsBotSsoPrompt.
2046
+ *
2047
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth
2048
+ * @param {string} dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
2049
+ * @param {TeamsBotSsoPromptSettings} settings Settings used to configure the prompt.
2050
+ *
2051
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
2052
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
2053
+ */
2054
+ constructor(teamsfx: TeamsFx, dialogId: string, settings: TeamsBotSsoPromptSettings);
2055
+ /**
2056
+ * Constructor of TeamsBotSsoPrompt.
2057
+ *
2058
+ * @param {OnBehalfOfCredentialAuthConfig} authConfig - Used to provide configuration and auth
2059
+ * @param {string} initiateLoginEndpoint - Login URL for Teams to redirect to
2060
+ * @param {string} dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
2061
+ * @param {TeamsBotSsoPromptSettings} settings Settings used to configure the prompt.
2062
+ *
2063
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
2064
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
2065
+ */
2066
+ constructor(authConfig: OnBehalfOfCredentialAuthConfig, initiateLoginEndpoint: string, dialogId: string, settings: TeamsBotSsoPromptSettings);
2067
+ /**
2068
+ * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
2069
+ * @remarks
2070
+ * If the task is successful, the result indicates whether the prompt is still
2071
+ * active after the turn has been processed by the prompt.
2072
+ *
2073
+ * @param dc The DialogContext for the current turn of the conversation.
2074
+ *
2075
+ * @throws {@link ErrorCode|InvalidParameter} when timeout property in teams bot sso prompt settings is not number or is not positive.
2076
+ * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
2077
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
2078
+ *
2079
+ * @returns A `Promise` representing the asynchronous operation.
2080
+ */
2081
+ beginDialog(dc: DialogContext): Promise<DialogTurnResult>;
2082
+ /**
2083
+ * Called when a prompt dialog is the active dialog and the user replied with a new activity.
2084
+ *
2085
+ * @remarks
2086
+ * If the task is successful, the result indicates whether the dialog is still
2087
+ * active after the turn has been processed by the dialog.
2088
+ * The prompt generally continues to receive the user's replies until it accepts the
2089
+ * user's reply as valid input for the prompt.
2090
+ *
2091
+ * @param dc The DialogContext for the current turn of the conversation.
2092
+ *
2093
+ * @returns A `Promise` representing the asynchronous operation.
2094
+ *
2095
+ * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
2096
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
2097
+ */
2098
+ continueDialog(dc: DialogContext): Promise<DialogTurnResult>;
2099
+ private loadAndValidateConfig;
2100
+ /**
2101
+ * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
2102
+ * @param dc dialog context
2103
+ * @throws {@link ErrorCode|ChannelNotSupported} if bot channel is not MS Teams
2104
+ * @internal
2105
+ */
2106
+ private ensureMsTeamsChannel;
2107
+ /**
2108
+ * Send OAuthCard that tells Teams to obtain an authentication token for the bot application.
2109
+ * For details see https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots.
2110
+ *
2111
+ * @internal
2112
+ */
2113
+ private sendOAuthCardAsync;
2114
+ /**
2115
+ * Get sign in resource.
2116
+ *
2117
+ * @throws {@link ErrorCode|InvalidConfiguration} if client id, tenant id or initiate login endpoint is not found in config.
2118
+ *
2119
+ * @internal
2120
+ */
2121
+ private getSignInResource;
2122
+ /**
2123
+ * @internal
2124
+ */
2125
+ private recognizeToken;
2126
+ /**
2127
+ * @internal
2128
+ */
2129
+ private getTokenExchangeInvokeResponse;
2130
+ /**
2131
+ * @internal
2132
+ */
2133
+ private isTeamsVerificationInvoke;
2134
+ /**
2135
+ * @internal
2136
+ */
2137
+ private isTokenExchangeRequestInvoke;
2138
+ /**
2139
+ * @internal
2140
+ */
2141
+ private isTokenExchangeRequest;
2142
+ }
2143
+
2144
+ /**
2145
+ * Settings used to configure an TeamsBotSsoPrompt instance.
2146
+ */
2147
+ export declare interface TeamsBotSsoPromptSettings {
2148
+ /**
2149
+ * The array of strings that declare the desired permissions and the resources requested.
2150
+ */
2151
+ scopes: string[];
2152
+ /**
2153
+ * (Optional) number of milliseconds the prompt will wait for the user to authenticate.
2154
+ * Defaults to a value `900,000` (15 minutes.)
2155
+ */
2156
+ timeout?: number;
2157
+ /**
2158
+ * (Optional) value indicating whether the TeamsBotSsoPrompt should end upon receiving an
2159
+ * invalid message. Generally the TeamsBotSsoPrompt will end the auth flow when receives user
2160
+ * message not related to the auth flow. Setting the flag to false ignores the user's message instead.
2161
+ * Defaults to value `true`
2162
+ */
2163
+ endOnInvalidMessage?: boolean;
2164
+ }
2165
+
2166
+ /**
2167
+ * Token response provided by Teams Bot SSO prompt
2168
+ */
2169
+ export declare interface TeamsBotSsoPromptTokenResponse extends TokenResponse {
2170
+ /**
2171
+ * SSO token for user
2172
+ */
2173
+ ssoToken: string;
2174
+ /**
2175
+ * Expire time of SSO token
2176
+ */
2177
+ ssoTokenExpiration: string;
2178
+ }
2179
+
2180
+ /**
2181
+ * A class providing credential and configuration.
2182
+ */
2183
+ export declare class TeamsFx implements TeamsFxConfiguration {
2184
+ private configuration;
2185
+ private oboUserCredential?;
2186
+ private appCredential?;
2187
+ private identityType;
2188
+ /**
2189
+ * Constructor of TeamsFx
2190
+ *
2191
+ * @param {IdentityType} identityType - Choose user or app identity
2192
+ * @param customConfig - key/value pairs of customized configuration that overrides default ones.
2193
+ *
2194
+ * @throws {@link ErrorCode|IdentityTypeNotSupported} when setting app identity in browser.
2195
+ */
2196
+ constructor(identityType?: IdentityType, customConfig?: Record<string, string> | AuthenticationConfiguration);
2197
+ /**
2198
+ * Identity type set by user.
2199
+ *
2200
+ * @returns identity type.
2201
+ */
2202
+ getIdentityType(): IdentityType;
2203
+ /**
2204
+ * Credential instance according to identity type choice.
2205
+ *
2206
+ * @remarks If user identity is chose, will return {@link TeamsUserCredential}
2207
+ * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
2208
+ * identity is chose, will return {@link AppCredential}.
2209
+ *
2210
+ * @returns instance implements TokenCredential interface.
2211
+ */
2212
+ getCredential(): TokenCredential;
2213
+ /**
2214
+ * Get user information.
2215
+ * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2216
+ * @returns UserInfo object.
2217
+ */
2218
+ getUserInfo(resources?: string[]): Promise<UserInfo>;
2219
+ /**
2220
+ * Popup login page to get user's access token with specific scopes.
2221
+ *
2222
+ * @remarks
2223
+ * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
2224
+ *
2225
+ * @example
2226
+ * ```typescript
2227
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
2228
+ * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
2229
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
2230
+ * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
2231
+ * ```
2232
+ * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
2233
+ * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2234
+ *
2235
+ * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
2236
+ * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
2237
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
2238
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
2239
+ */
2240
+ login(scopes: string | string[], resources?: string[]): Promise<void>;
2241
+ /**
2242
+ * Set SSO token when using user identity in NodeJS.
2243
+ * @param {string} ssoToken - used for on behalf of user flow.
2244
+ * @returns self instance.
2245
+ */
2246
+ setSsoToken(ssoToken: string): TeamsFx;
2247
+ /**
2248
+ * Usually used by service plugins to retrieve specific config
2249
+ * @param {string} key - configuration key.
2250
+ * @returns value in configuration.
2251
+ */
2252
+ getConfig(key: string): string;
2253
+ /**
2254
+ * Check the value of specific key.
2255
+ * @param {string} key - configuration key.
2256
+ * @returns true if corresponding value is not empty string.
2257
+ */
2258
+ hasConfig(key: string): boolean;
2259
+ /**
2260
+ * Get all configurations.
2261
+ * @returns key value mappings.
2262
+ */
2263
+ getConfigs(): Record<string, string>;
2264
+ /**
2265
+ * Load configuration from environment variables.
2266
+ */
2267
+ private loadFromEnv;
2268
+ }
2269
+
2270
+ /**
2271
+ * Interface for adaptive card action handler that can process card action invoke and return a response.
2272
+ */
2273
+ export declare interface TeamsFxAdaptiveCardActionHandler {
2274
+ /**
2275
+ * The verb defined in adaptive card action that can trigger this handler.
2276
+ * The verb string here is case-insensitive.
2277
+ */
2278
+ triggerVerb: string;
2279
+ /**
2280
+ * Specify the behavior for how the card response will be sent in Teams conversation.
2281
+ * The default value is `AdaptiveCardResponse.ReplaceForInteractor`, which means the card
2282
+ * response will replace the current one only for the interactor.
2283
+ */
2284
+ adaptiveCardResponse?: AdaptiveCardResponse;
2285
+ /**
2286
+ * The handler function that will be invoked when the action is fired.
2287
+ * @param context The turn context.
2288
+ * @param actionData The contextual data that associated with the action.
2289
+ *
2290
+ * @returns A `Promise` representing a invoke response for the adaptive card invoke action.
2291
+ * You can use the `InvokeResponseFactory` utility class to create an invoke response from
2292
+ * - A text message:
2293
+ * ```typescript
2294
+ * return InvokeResponseFactory.textMessage("Action is processed successfully!");
2295
+ * ```
2296
+ * - An adaptive card:
2297
+ * ```typescript
2298
+ * const responseCard = AdaptiveCards.declare(helloWorldCard).render(actionData);
2299
+ return InvokeResponseFactory.adaptiveCard(responseCard);
2300
+ * ```
2301
+ * - An error response:
2302
+ * ```typescript
2303
+ * return InvokeResponseFactory.errorResponse(InvokeResponseErrorCode.BadRequest, "Invalid request");
2304
+ * ```
2305
+ *
2306
+ * @remark For more details about the invoke response format, refer to https://docs.microsoft.com/en-us/adaptive-cards/authoring-cards/universal-action-model#response-format.
2307
+ */
2308
+ handleActionInvoked(context: TurnContext, actionData: any): Promise<InvokeResponse>;
2309
+ }
2310
+
2311
+ /**
2312
+ * Interface for a command handler that can process command to a TeamsFx bot and return a response.
2313
+ */
2314
+ export declare interface TeamsFxBotCommandHandler {
2315
+ /**
2316
+ * The string or regular expression patterns that can trigger this handler.
2317
+ */
2318
+ triggerPatterns: TriggerPatterns;
2319
+ /**
2320
+ * Handles a bot command received activity.
2321
+ *
2322
+ * @param context The bot context.
2323
+ * @param message The command message the user types from Teams.
2324
+ * @returns A `Promise` representing an activity or text to send as the command response.
2325
+ * Or no return value if developers want to send the response activity by themselves in this method.
2326
+ */
2327
+ handleCommandReceived(context: TurnContext, message: CommandMessage): Promise<string | Partial<Activity> | void>;
2328
+ }
2329
+
2330
+ /**
2331
+ * Interface for a command handler that can process sso command to a TeamsFx bot and return a response.
2332
+ */
2333
+ export declare interface TeamsFxBotSsoCommandHandler {
2334
+ /**
2335
+ * The string or regular expression patterns that can trigger this handler.
2336
+ */
2337
+ triggerPatterns: TriggerPatterns;
2338
+ /**
2339
+ * Handles a bot command received activity.
2340
+ *
2341
+ * @param context The bot context.
2342
+ * @param message The command message the user types from Teams.
2343
+ * @param tokenResponse The tokenResponse which contains sso token that can be used to exchange access token for the bot.
2344
+ * @returns A `Promise` representing an activity or text to send as the command response.
2345
+ * Or no return value if developers want to send the response activity by themselves in this method.
2346
+ */
2347
+ handleCommandReceived(context: TurnContext, message: CommandMessage, tokenResponse: TeamsBotSsoPromptTokenResponse): Promise<string | Partial<Activity> | void>;
2348
+ }
2349
+
2350
+ /**
2351
+ * TeamsFx interface that provides credential and configuration.
2352
+ */
2353
+ declare interface TeamsFxConfiguration {
2354
+ /**
2355
+ * Identity type set by user.
2356
+ *
2357
+ * @returns identity type.
2358
+ */
2359
+ getIdentityType(): IdentityType;
2360
+ /**
2361
+ * Credential instance according to identity type choice.
2362
+ *
2363
+ * @remarks If user identity is chose, will return {@link TeamsUserCredential}
2364
+ * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
2365
+ * identity is chose, will return {@link AppCredential}.
2366
+ *
2367
+ * @returns instance implements TokenCredential interface.
2368
+ */
2369
+ getCredential(): TokenCredential;
2370
+ /**
2371
+ * Get user information.
2372
+ * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2373
+ * @returns UserInfo object.
2374
+ */
2375
+ getUserInfo(resources?: string[]): Promise<UserInfo>;
2376
+ /**
2377
+ * Popup login page to get user's access token with specific scopes.
2378
+ *
2379
+ * @remarks
2380
+ * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
2381
+ *
2382
+ * @example
2383
+ * ```typescript
2384
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
2385
+ * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
2386
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
2387
+ * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
2388
+ * ```
2389
+ * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
2390
+ * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2391
+ *
2392
+ * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
2393
+ * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
2394
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
2395
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
2396
+ */
2397
+ login(scopes: string | string[], resources?: string[]): Promise<void>;
2398
+ /**
2399
+ * Set SSO token when using user identity in NodeJS.
2400
+ * @param {string} ssoToken - used for on behalf of user flow.
2401
+ * @returns self instance.
2402
+ */
2403
+ setSsoToken(ssoToken: string): TeamsFxConfiguration;
2404
+ /**
2405
+ * Usually used by service plugins to retrieve specific config
2406
+ * @param {string} key - configuration key.
2407
+ * @returns value in configuration.
2408
+ */
2409
+ getConfig(key: string): string;
2410
+ /**
2411
+ * Check the value of specific key.
2412
+ * @param {string} key - configuration key.
2413
+ * @returns true if corresponding value is not empty string.
2414
+ */
2415
+ hasConfig(key: string): boolean;
2416
+ /**
2417
+ * Get all configurations.
2418
+ * @returns key value mappings.
2419
+ */
2420
+ getConfigs(): Record<string, string>;
2421
+ }
2422
+
2423
+ /**
2424
+ * Represent Teams current user's identity, and it is used within Teams client applications.
2425
+ *
2426
+ * @remarks
2427
+ * Can only be used within Teams.
2428
+ */
2429
+ export declare class TeamsUserCredential implements TokenCredential {
2430
+ /**
2431
+ * Constructor of TeamsUserCredential.
2432
+ * @remarks
2433
+ * Can only be used within Teams.
2434
+ */
2435
+ constructor(authConfig: TeamsUserCredentialAuthConfig);
2436
+ constructor(authConfig: AuthenticationConfiguration);
2437
+ /**
2438
+ * Popup login page to get user's access token with specific scopes.
2439
+ *
2440
+ * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2441
+ *
2442
+ * @remarks
2443
+ * Can only be used within Teams.
2444
+ */
2445
+ login(scopes: string | string[], resources?: string[]): Promise<void>;
2446
+ /**
2447
+ * Get access token from credential.
2448
+ * @remarks
2449
+ * Can only be used within Teams.
2450
+ */
2451
+ getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
2452
+ /**
2453
+ * Get basic user info from SSO token
2454
+ *
2455
+ * @param {string[]} resources - The optional list of resources for full trust Teams apps.
2456
+ *
2457
+ * @remarks
2458
+ * Can only be used within Teams.
2459
+ */
2460
+ getUserInfo(resources?: string[]): Promise<UserInfo>;
2461
+ }
2462
+
2463
+ /**
2464
+ * Authentication configuration for TeamsUserCredential used in browser environment
2465
+ */
2466
+ export declare type TeamsUserCredentialAuthConfig = {
2467
+ /**
2468
+ * Login page for Teams to redirect to.
2469
+ */
2470
+ initiateLoginEndpoint: string;
2471
+ /**
2472
+ * The client (application) ID of an App Registration in the tenant
2473
+ */
2474
+ clientId: string;
2475
+ };
2476
+
2477
+ /**
2478
+ * The trigger pattern used to trigger a {@link TeamsFxBotCommandHandler} instance.
2479
+ */
2480
+ export declare type TriggerPatterns = string | RegExp | (string | RegExp)[];
2481
+
2482
+ /**
2483
+ * UserInfo with user displayName, objectId and preferredUserName.
2484
+ */
2485
+ export declare interface UserInfo {
2486
+ /**
2487
+ * User Display Name.
2488
+ *
2489
+ * @readonly
2490
+ */
2491
+ displayName: string;
2492
+ /**
2493
+ * User unique reference within the Azure Active Directory domain.
2494
+ *
2495
+ * @readonly
2496
+ */
2497
+ objectId: string;
2498
+ /**
2499
+ * User tenant ID.
2500
+ *
2501
+ * @readonly
2502
+ */
2503
+ tenantId: string;
2504
+ /**
2505
+ * Usually be the email address.
2506
+ *
2507
+ * @readonly
2508
+ */
2509
+ preferredUserName: string;
2510
+ }
2511
+
2512
+ export { }