@microsoft/teamsfx 0.6.3-alpha.768a76f6e.0 → 0.6.3-alpha.81c48cbfc.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.
@@ -1,3 +1,5 @@
1
+ /// <reference types="node" />
2
+
1
3
  import { AccessToken } from '@azure/identity';
2
4
  import { Activity } from 'botbuilder-core';
3
5
  import { Activity as Activity_2 } from 'botbuilder';
@@ -19,6 +21,7 @@ import { GetTokenOptions } from '@azure/identity';
19
21
  import { HeroCard } from 'botbuilder';
20
22
  import { O365ConnectorCard } from 'botbuilder';
21
23
  import { ReceiptCard } from 'botbuilder';
24
+ import { SecureContextOptions } from 'tls';
22
25
  import { TeamsChannelAccount } from 'botbuilder';
23
26
  import { ThumbnailCard } from 'botbuilder';
24
27
  import { TokenCredential } from '@azure/identity';
@@ -183,6 +186,35 @@ export declare class BearerTokenAuthProvider implements AuthProvider {
183
186
  AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
184
187
  }
185
188
 
189
+ /**
190
+ * Provider that handles Certificate authentication
191
+ *
192
+ * @beta
193
+ */
194
+ export declare class CertificateAuthProvider implements AuthProvider {
195
+ private certOption;
196
+ /**
197
+ *
198
+ * @param { SecureContextOptions } certOption - information about the cert used in http requests
199
+ *
200
+ * @beta
201
+ */
202
+ constructor(certOption: SecureContextOptions);
203
+ /**
204
+ * Adds authentication info to http requests.
205
+ *
206
+ * @param { AxiosRequestConfig } config - Contains all the request information and can be updated to include extra authentication info.
207
+ * Refer https://axios-http.com/docs/req_config for detailed document.
208
+ *
209
+ * @returns Updated axios request config.
210
+ *
211
+ * @throws {@link ErrorCode|InvalidParameter} - when custom httpsAgent in the request has duplicate properties with certOption provided in constructor.
212
+ *
213
+ * @beta
214
+ */
215
+ AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
216
+ }
217
+
186
218
  /**
187
219
  * A {@link NotificationTarget} that represents a team channel.
188
220
  *
@@ -548,1251 +580,1279 @@ export declare function createApiClient(apiEndpoint: string, authProvider: AuthP
548
580
  export declare function createMicrosoftGraphClient(teamsfx: TeamsFxConfiguration, scopes?: string | string[]): Client;
549
581
 
550
582
  /**
551
- * Error code to trace the error types.
552
- * @beta
553
- */
554
- export declare enum ErrorCode {
555
- /**
556
- * Invalid parameter error.
557
- */
558
- InvalidParameter = "InvalidParameter",
559
- /**
560
- * Invalid configuration error.
561
- */
562
- InvalidConfiguration = "InvalidConfiguration",
563
- /**
564
- * Invalid certificate error.
565
- */
566
- InvalidCertificate = "InvalidCertificate",
567
- /**
568
- * Internal error.
569
- */
570
- InternalError = "InternalError",
571
- /**
572
- * Channel is not supported error.
573
- */
574
- ChannelNotSupported = "ChannelNotSupported",
575
- /**
576
- * Runtime is not supported error.
577
- */
578
- RuntimeNotSupported = "RuntimeNotSupported",
579
- /**
580
- * User failed to finish the AAD consent flow failed.
581
- */
582
- ConsentFailed = "ConsentFailed",
583
- /**
584
- * The user or administrator has not consented to use the application error.
585
- */
586
- UiRequiredError = "UiRequiredError",
587
- /**
588
- * Token is not within its valid time range error.
589
- */
590
- TokenExpiredError = "TokenExpiredError",
591
- /**
592
- * Call service (AAD or simple authentication server) failed.
593
- */
594
- ServiceError = "ServiceError",
595
- /**
596
- * Operation failed.
597
- */
598
- FailedOperation = "FailedOperation",
599
- /**
600
- * Invalid response error.
601
- */
602
- InvalidResponse = "InvalidResponse",
603
- /**
604
- * Identity type error.
605
- */
606
- IdentityTypeNotSupported = "IdentityTypeNotSupported"
607
- }
608
-
609
- /**
610
- * Error class with code and message thrown by the SDK.
583
+ * Helper to create SecureContextOptions from PEM format cert
611
584
  *
612
- * @beta
613
- */
614
- export declare class ErrorWithCode extends Error {
615
- /**
616
- * Error code
585
+ * @param { string | Buffer } cert - The cert chain in PEM format
586
+ * @param { string | Buffer } key - The private key for the cert chain
587
+ * @param { string? } passphrase - The passphrase for private key
588
+ * @param { string? | Buffer? } ca - Overrides the trusted CA certificates
617
589
  *
618
- * @readonly
619
- */
620
- code: string | undefined;
621
- /**
622
- * Constructor of ErrorWithCode.
590
+ * @returns Instance of SecureContextOptions
623
591
  *
624
- * @param {string} message - error message.
625
- * @param {ErrorCode} code - error code.
592
+ * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
626
593
  *
627
- * @beta
628
594
  */
629
- constructor(message?: string, code?: ErrorCode);
630
- }
595
+ export declare function createPemCertOption(cert: string | Buffer, key: string | Buffer, passphrase?: string, ca?: string | Buffer): SecureContextOptions;
631
596
 
632
- /**
633
- * Get log level.
634
- *
635
- * @returns Log level
636
- *
637
- * @beta
638
- */
639
- export declare function getLogLevel(): LogLevel | undefined;
597
+ /**
598
+ * Helper to create SecureContextOptions from PFX format cert
599
+ *
600
+ * @param { string | Buffer } pfx - The content of .pfx file
601
+ * @param { string? } passphrase - Optional. The passphrase of .pfx file
602
+ *
603
+ * @returns Instance of SecureContextOptions
604
+ *
605
+ * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
606
+ *
607
+ */
608
+ export declare function createPfxCertOption(pfx: string | Buffer, passphrase?: string): SecureContextOptions;
640
609
 
641
- /**
642
- * Generate connection configuration consumed by tedious.
643
- *
644
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth
645
- * @param { string? } databaseName - specify database name to override default one if there are multiple databases.
646
- *
647
- * @returns Connection configuration of tedious for the SQL.
648
- *
649
- * @throws {@link ErrorCode|InvalidConfiguration} when SQL config resource configuration is invalid.
650
- * @throws {@link ErrorCode|InternalError} when get user MSI token failed or MSI token is invalid.
651
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
652
- *
653
- * @beta
654
- */
655
- export declare function getTediousConnectionConfig(teamsfx: TeamsFx, databaseName?: string): Promise<ConnectionConfig>;
610
+ /**
611
+ * Error code to trace the error types.
612
+ * @beta
613
+ */
614
+ export declare enum ErrorCode {
615
+ /**
616
+ * Invalid parameter error.
617
+ */
618
+ InvalidParameter = "InvalidParameter",
619
+ /**
620
+ * Invalid configuration error.
621
+ */
622
+ InvalidConfiguration = "InvalidConfiguration",
623
+ /**
624
+ * Invalid certificate error.
625
+ */
626
+ InvalidCertificate = "InvalidCertificate",
627
+ /**
628
+ * Internal error.
629
+ */
630
+ InternalError = "InternalError",
631
+ /**
632
+ * Channel is not supported error.
633
+ */
634
+ ChannelNotSupported = "ChannelNotSupported",
635
+ /**
636
+ * Runtime is not supported error.
637
+ */
638
+ RuntimeNotSupported = "RuntimeNotSupported",
639
+ /**
640
+ * User failed to finish the AAD consent flow failed.
641
+ */
642
+ ConsentFailed = "ConsentFailed",
643
+ /**
644
+ * The user or administrator has not consented to use the application error.
645
+ */
646
+ UiRequiredError = "UiRequiredError",
647
+ /**
648
+ * Token is not within its valid time range error.
649
+ */
650
+ TokenExpiredError = "TokenExpiredError",
651
+ /**
652
+ * Call service (AAD or simple authentication server) failed.
653
+ */
654
+ ServiceError = "ServiceError",
655
+ /**
656
+ * Operation failed.
657
+ */
658
+ FailedOperation = "FailedOperation",
659
+ /**
660
+ * Invalid response error.
661
+ */
662
+ InvalidResponse = "InvalidResponse",
663
+ /**
664
+ * Identity type error.
665
+ */
666
+ IdentityTypeNotSupported = "IdentityTypeNotSupported"
667
+ }
656
668
 
657
- /**
658
- * Identity type to use in authentication.
659
- *
660
- * @beta
661
- */
662
- export declare enum IdentityType {
663
- /**
664
- * Represents the current user of Teams.
665
- */
666
- User = "User",
667
- /**
668
- * Represents the application itself.
669
- */
670
- App = "Application"
671
- }
669
+ /**
670
+ * Error class with code and message thrown by the SDK.
671
+ *
672
+ * @beta
673
+ */
674
+ export declare class ErrorWithCode extends Error {
675
+ /**
676
+ * Error code
677
+ *
678
+ * @readonly
679
+ */
680
+ code: string | undefined;
681
+ /**
682
+ * Constructor of ErrorWithCode.
683
+ *
684
+ * @param {string} message - error message.
685
+ * @param {ErrorCode} code - error code.
686
+ *
687
+ * @beta
688
+ */
689
+ constructor(message?: string, code?: ErrorCode);
690
+ }
672
691
 
673
- /**
674
- * Log function for customized logging.
675
- *
676
- * @beta
677
- */
678
- export declare type LogFunction = (level: LogLevel, message: string) => void;
692
+ /**
693
+ * Get log level.
694
+ *
695
+ * @returns Log level
696
+ *
697
+ * @beta
698
+ */
699
+ export declare function getLogLevel(): LogLevel | undefined;
679
700
 
680
- /**
681
- * Interface for customized logger.
682
- * @beta
683
- */
684
- export declare interface Logger {
685
- /**
686
- * Writes to error level logging or lower.
687
- */
688
- error(message: string): void;
689
- /**
690
- * Writes to warning level logging or lower.
691
- */
692
- warn(message: string): void;
693
- /**
694
- * Writes to info level logging or lower.
695
- */
696
- info(message: string): void;
697
- /**
698
- * Writes to verbose level logging.
699
- */
700
- verbose(message: string): void;
701
- }
701
+ /**
702
+ * Generate connection configuration consumed by tedious.
703
+ *
704
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth
705
+ * @param { string? } databaseName - specify database name to override default one if there are multiple databases.
706
+ *
707
+ * @returns Connection configuration of tedious for the SQL.
708
+ *
709
+ * @throws {@link ErrorCode|InvalidConfiguration} when SQL config resource configuration is invalid.
710
+ * @throws {@link ErrorCode|InternalError} when get user MSI token failed or MSI token is invalid.
711
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
712
+ *
713
+ * @beta
714
+ */
715
+ export declare function getTediousConnectionConfig(teamsfx: TeamsFx, databaseName?: string): Promise<ConnectionConfig>;
702
716
 
703
- /**
704
- * Log level.
705
- *
706
- * @beta
707
- */
708
- export declare enum LogLevel {
709
- /**
710
- * Show verbose, information, warning and error message.
711
- */
712
- Verbose = 0,
713
- /**
714
- * Show information, warning and error message.
715
- */
716
- Info = 1,
717
- /**
718
- * Show warning and error message.
719
- */
720
- Warn = 2,
721
- /**
722
- * Show error message.
723
- */
724
- Error = 3
725
- }
717
+ /**
718
+ * Identity type to use in authentication.
719
+ *
720
+ * @beta
721
+ */
722
+ export declare enum IdentityType {
723
+ /**
724
+ * Represents the current user of Teams.
725
+ */
726
+ User = "User",
727
+ /**
728
+ * Represents the application itself.
729
+ */
730
+ App = "Application"
731
+ }
726
732
 
727
- /**
728
- * A {@link NotificationTarget} that represents a team member.
729
- *
730
- * @remarks
731
- * It's recommended to get members from {@link TeamsBotInstallation.members()}.
732
- *
733
- * @beta
734
- */
735
- export declare class Member implements NotificationTarget {
736
- /**
737
- * The parent {@link TeamsBotInstallation} where this member is created from.
738
- *
739
- * @beta
740
- */
741
- readonly parent: TeamsBotInstallation;
742
- /**
743
- * Detailed member account information.
744
- *
745
- * @beta
746
- */
747
- readonly account: TeamsChannelAccount;
748
- /**
749
- * Notification target type. For member it's always "Person".
750
- *
751
- * @beta
752
- */
753
- readonly type: NotificationTargetType;
754
- /**
755
- * Constuctor.
756
- *
757
- * @remarks
758
- * It's recommended to get members from {@link TeamsBotInstallation.members()}, instead of using this constructor.
759
- *
760
- * @param parent - The parent {@link TeamsBotInstallation} where this member is created from.
761
- * @param account - Detailed member account information.
762
- *
763
- * @beta
764
- */
765
- constructor(parent: TeamsBotInstallation, account: TeamsChannelAccount);
766
- /**
767
- * Send a plain text message.
768
- *
769
- * @param text - the plain text message.
770
- * @returns A `Promise` representing the asynchronous operation.
771
- *
772
- * @beta
773
- */
774
- sendMessage(text: string): Promise<void>;
775
- /**
776
- * Send an adaptive card message.
777
- *
778
- * @param card - the adaptive card raw JSON.
779
- * @returns A `Promise` representing the asynchronous operation.
780
- *
781
- * @beta
782
- */
783
- sendAdaptiveCard(card: unknown): Promise<void>;
784
- /**
785
- * @internal
786
- */
787
- private newConversation;
788
- }
733
+ /**
734
+ * Log function for customized logging.
735
+ *
736
+ * @beta
737
+ */
738
+ export declare type LogFunction = (level: LogLevel, message: string) => void;
789
739
 
790
- /**
791
- * Provides utility method to build bot message with cards that supported in Teams.
792
- */
793
- export declare class MessageBuilder {
794
- /**
795
- * Build a bot message activity attached with adaptive card.
796
- *
797
- * @param getCardData Function to prepare your card data.
798
- * @param cardTemplate The adaptive card template.
799
- * @returns A bot message activity attached with an adaptive card.
800
- *
801
- * @example
802
- * ```javascript
803
- * const cardTemplate = {
804
- * type: "AdaptiveCard",
805
- * body: [
806
- * {
807
- * "type": "TextBlock",
808
- * "text": "${title}",
809
- * "size": "Large"
810
- * },
811
- * {
812
- * "type": "TextBlock",
813
- * "text": "${description}"
814
- * }],
815
- * $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
816
- * version: "1.4"
817
- * };
818
- *
819
- * type CardData = {
820
- * title: string,
821
- * description: string
822
- * };
823
- * const card = MessageBuilder.attachAdaptiveCard<CardData>(() => {
824
- * return {
825
- * title: "sample card title",
826
- * description: "sample card description"
827
- * }}, cardTemplate);
828
- * ```
829
- *
830
- * @beta
831
- */
832
- static attachAdaptiveCard<TData>(getCardData: () => TData, cardTemplate: any): Partial<Activity_2>;
833
- /**
834
- * Build a bot message activity attached with an adaptive card.
835
- *
836
- * @param card The adaptive card content.
837
- * @returns A bot message activity attached with an adaptive card.
838
- *
839
- * @beta
840
- */
841
- static attachAdaptiveCardWithoutData(card: any): Partial<Activity_2>;
842
- /**
843
- * Build a bot message activity attached with an hero card.
844
- *
845
- * @param title The card title.
846
- * @param images Optional. The array of images to include on the card.
847
- * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
848
- * is converted to an `imBack` button with a title and value set to the value of the string.
849
- * @param other Optional. Any additional properties to include on the card.
850
- *
851
- * @returns A bot message activity attached with a hero card.
852
- *
853
- * @example
854
- * ```javascript
855
- * const message = MessageBuilder.attachHeroCard(
856
- * 'sample title',
857
- * ['https://example.com/sample.jpg'],
858
- * ['action']
859
- * );
860
- * ```
861
- *
862
- * @beta
863
- */
864
- static attachHeroCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<HeroCard>): Partial<Activity_2>;
865
- /**
866
- * Returns an attachment for a sign-in card.
867
- *
868
- * @param title The title for the card's sign-in button.
869
- * @param url The URL of the sign-in page to use.
870
- * @param text Optional. Additional text to include on the card.
871
- *
872
- * @returns A bot message activity attached with a sign-in card.
873
- *
874
- * @remarks
875
- * For channels that don't natively support sign-in cards, an alternative message is rendered.
876
- *
877
- * @beta
878
- */
879
- static attachSigninCard(title: string, url: string, text?: string): Partial<Activity_2>;
880
- /**
881
- * Build a bot message activity attached with an Office 365 connector card.
882
- *
883
- * @param card A description of the Office 365 connector card.
884
- * @returns A bot message activity attached with an Office 365 connector card.
885
- *
886
- * @beta
887
- */
888
- static attachO365ConnectorCard(card: O365ConnectorCard): Partial<Activity_2>;
889
- /**
890
- * Build a message activity attached with a receipt card.
891
- * @param card A description of the receipt card.
892
- * @returns A message activity attached with a receipt card.
893
- *
894
- * @beta
895
- */
896
- static AttachReceiptCard(card: ReceiptCard): Partial<Activity_2>;
897
- /**
898
- *
899
- * @param title The card title.
900
- * @param images Optional. The array of images to include on the card.
901
- * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
902
- * is converted to an `imBack` button with a title and value set to the value of the string.
903
- * @param other Optional. Any additional properties to include on the card.
904
- * @returns A message activity attached with a thumbnail card
905
- *
906
- * @beta
907
- */
908
- static attachThumbnailCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<ThumbnailCard>): Partial<Activity_2>;
909
- /**
910
- * Add an attachement to a bot activity.
911
- * @param attachement The attachment object to attach.
912
- * @returns A message activity with an attachment.
913
- *
914
- * @beta
915
- */
916
- static attachContent(attachement: Attachment): Partial<Activity_2>;
917
- }
740
+ /**
741
+ * Interface for customized logger.
742
+ * @beta
743
+ */
744
+ export declare interface Logger {
745
+ /**
746
+ * Writes to error level logging or lower.
747
+ */
748
+ error(message: string): void;
749
+ /**
750
+ * Writes to warning level logging or lower.
751
+ */
752
+ warn(message: string): void;
753
+ /**
754
+ * Writes to info level logging or lower.
755
+ */
756
+ info(message: string): void;
757
+ /**
758
+ * Writes to verbose level logging.
759
+ */
760
+ verbose(message: string): void;
761
+ }
918
762
 
919
- /**
920
- * Microsoft Graph auth provider for Teams Framework
921
- *
922
- * @beta
923
- */
924
- export declare class MsGraphAuthProvider implements AuthenticationProvider {
925
- private teamsfx;
926
- private scopes;
927
- /**
928
- * Constructor of MsGraphAuthProvider.
929
- *
930
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth.
931
- * @param {string | string[]} scopes - The list of scopes for which the token will have access.
932
- *
933
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
934
- *
935
- * @returns An instance of MsGraphAuthProvider.
936
- *
937
- * @beta
938
- */
939
- constructor(teamsfx: TeamsFxConfiguration, scopes?: string | string[]);
940
- /**
941
- * Get access token for Microsoft Graph API requests.
942
- *
943
- * @throws {@link ErrorCode|InternalError} when get access token failed due to empty token or unknown other problems.
944
- * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
945
- * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
946
- * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth or AAD server.
947
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
948
- *
949
- * @returns Access token from the credential.
950
- *
951
- */
952
- getAccessToken(): Promise<string>;
953
- }
763
+ /**
764
+ * Log level.
765
+ *
766
+ * @beta
767
+ */
768
+ export declare enum LogLevel {
769
+ /**
770
+ * Show verbose, information, warning and error message.
771
+ */
772
+ Verbose = 0,
773
+ /**
774
+ * Show information, warning and error message.
775
+ */
776
+ Info = 1,
777
+ /**
778
+ * Show warning and error message.
779
+ */
780
+ Warn = 2,
781
+ /**
782
+ * Show error message.
783
+ */
784
+ Error = 3
785
+ }
954
786
 
955
- /**
956
- * Provide utilities to send notification to varies targets (e.g., member, group, channel).
957
- *
958
- * @beta
959
- */
960
- export declare class NotificationBot {
961
- private readonly conversationReferenceStore;
962
- private readonly adapter;
963
- /**
964
- * constructor of the notification bot.
965
- *
966
- * @remarks
967
- * To ensure accuracy, it's recommended to initialize before handling any message.
968
- *
969
- * @param adapter - the bound `BotFrameworkAdapter`
970
- * @param options - initialize options
971
- *
972
- * @beta
973
- */
974
- constructor(adapter: BotFrameworkAdapter, options?: NotificationOptions_2);
975
- /**
976
- * Get all targets where the bot is installed.
977
- *
978
- * @remarks
979
- * The result is retrieving from the persisted storage.
980
- *
981
- * @returns - an array of {@link TeamsBotInstallation}.
982
- *
983
- * @beta
984
- */
985
- installations(): Promise<TeamsBotInstallation[]>;
986
- }
787
+ /**
788
+ * A {@link NotificationTarget} that represents a team member.
789
+ *
790
+ * @remarks
791
+ * It's recommended to get members from {@link TeamsBotInstallation.members()}.
792
+ *
793
+ * @beta
794
+ */
795
+ export declare class Member implements NotificationTarget {
796
+ /**
797
+ * The parent {@link TeamsBotInstallation} where this member is created from.
798
+ *
799
+ * @beta
800
+ */
801
+ readonly parent: TeamsBotInstallation;
802
+ /**
803
+ * Detailed member account information.
804
+ *
805
+ * @beta
806
+ */
807
+ readonly account: TeamsChannelAccount;
808
+ /**
809
+ * Notification target type. For member it's always "Person".
810
+ *
811
+ * @beta
812
+ */
813
+ readonly type: NotificationTargetType;
814
+ /**
815
+ * Constuctor.
816
+ *
817
+ * @remarks
818
+ * It's recommended to get members from {@link TeamsBotInstallation.members()}, instead of using this constructor.
819
+ *
820
+ * @param parent - The parent {@link TeamsBotInstallation} where this member is created from.
821
+ * @param account - Detailed member account information.
822
+ *
823
+ * @beta
824
+ */
825
+ constructor(parent: TeamsBotInstallation, account: TeamsChannelAccount);
826
+ /**
827
+ * Send a plain text message.
828
+ *
829
+ * @param text - the plain text message.
830
+ * @returns A `Promise` representing the asynchronous operation.
831
+ *
832
+ * @beta
833
+ */
834
+ sendMessage(text: string): Promise<void>;
835
+ /**
836
+ * Send an adaptive card message.
837
+ *
838
+ * @param card - the adaptive card raw JSON.
839
+ * @returns A `Promise` representing the asynchronous operation.
840
+ *
841
+ * @beta
842
+ */
843
+ sendAdaptiveCard(card: unknown): Promise<void>;
844
+ /**
845
+ * @internal
846
+ */
847
+ private newConversation;
848
+ }
987
849
 
988
- /**
989
- * Options to initialize {@link NotificationBot}.
990
- *
991
- * @beta
992
- */
993
- declare interface NotificationOptions_2 {
994
- /**
995
- * An optional storage to persist bot notification connections.
996
- *
997
- * @remarks
998
- * If `storage` is not provided, a default local file storage will be used,
999
- * which stores notification connections into:
1000
- * - ".notification.localstore.json" if running locally
1001
- * - "${process.env.TEMP}/.notification.localstore.json" if `process.env.RUNNING_ON_AZURE` is set to "1"
1002
- *
1003
- * It's recommended to use your own shared storage for production environment.
1004
- *
1005
- * @beta
1006
- */
1007
- storage?: NotificationTargetStorage;
1008
- }
1009
- export { NotificationOptions_2 as NotificationOptions }
850
+ /**
851
+ * Provides utility method to build bot message with cards that supported in Teams.
852
+ */
853
+ export declare class MessageBuilder {
854
+ /**
855
+ * Build a bot message activity attached with adaptive card.
856
+ *
857
+ * @param getCardData Function to prepare your card data.
858
+ * @param cardTemplate The adaptive card template.
859
+ * @returns A bot message activity attached with an adaptive card.
860
+ *
861
+ * @example
862
+ * ```javascript
863
+ * const cardTemplate = {
864
+ * type: "AdaptiveCard",
865
+ * body: [
866
+ * {
867
+ * "type": "TextBlock",
868
+ * "text": "${title}",
869
+ * "size": "Large"
870
+ * },
871
+ * {
872
+ * "type": "TextBlock",
873
+ * "text": "${description}"
874
+ * }],
875
+ * $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
876
+ * version: "1.4"
877
+ * };
878
+ *
879
+ * type CardData = {
880
+ * title: string,
881
+ * description: string
882
+ * };
883
+ * const card = MessageBuilder.attachAdaptiveCard<CardData>(() => {
884
+ * return {
885
+ * title: "sample card title",
886
+ * description: "sample card description"
887
+ * }}, cardTemplate);
888
+ * ```
889
+ *
890
+ * @beta
891
+ */
892
+ static attachAdaptiveCard<TData>(getCardData: () => TData, cardTemplate: any): Partial<Activity_2>;
893
+ /**
894
+ * Build a bot message activity attached with an adaptive card.
895
+ *
896
+ * @param card The adaptive card content.
897
+ * @returns A bot message activity attached with an adaptive card.
898
+ *
899
+ * @beta
900
+ */
901
+ static attachAdaptiveCardWithoutData(card: any): Partial<Activity_2>;
902
+ /**
903
+ * Build a bot message activity attached with an hero card.
904
+ *
905
+ * @param title The card title.
906
+ * @param images Optional. The array of images to include on the card.
907
+ * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
908
+ * is converted to an `imBack` button with a title and value set to the value of the string.
909
+ * @param other Optional. Any additional properties to include on the card.
910
+ *
911
+ * @returns A bot message activity attached with a hero card.
912
+ *
913
+ * @example
914
+ * ```javascript
915
+ * const message = MessageBuilder.attachHeroCard(
916
+ * 'sample title',
917
+ * ['https://example.com/sample.jpg'],
918
+ * ['action']
919
+ * );
920
+ * ```
921
+ *
922
+ * @beta
923
+ */
924
+ static attachHeroCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<HeroCard>): Partial<Activity_2>;
925
+ /**
926
+ * Returns an attachment for a sign-in card.
927
+ *
928
+ * @param title The title for the card's sign-in button.
929
+ * @param url The URL of the sign-in page to use.
930
+ * @param text Optional. Additional text to include on the card.
931
+ *
932
+ * @returns A bot message activity attached with a sign-in card.
933
+ *
934
+ * @remarks
935
+ * For channels that don't natively support sign-in cards, an alternative message is rendered.
936
+ *
937
+ * @beta
938
+ */
939
+ static attachSigninCard(title: string, url: string, text?: string): Partial<Activity_2>;
940
+ /**
941
+ * Build a bot message activity attached with an Office 365 connector card.
942
+ *
943
+ * @param card A description of the Office 365 connector card.
944
+ * @returns A bot message activity attached with an Office 365 connector card.
945
+ *
946
+ * @beta
947
+ */
948
+ static attachO365ConnectorCard(card: O365ConnectorCard): Partial<Activity_2>;
949
+ /**
950
+ * Build a message activity attached with a receipt card.
951
+ * @param card A description of the receipt card.
952
+ * @returns A message activity attached with a receipt card.
953
+ *
954
+ * @beta
955
+ */
956
+ static AttachReceiptCard(card: ReceiptCard): Partial<Activity_2>;
957
+ /**
958
+ *
959
+ * @param title The card title.
960
+ * @param images Optional. The array of images to include on the card.
961
+ * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
962
+ * is converted to an `imBack` button with a title and value set to the value of the string.
963
+ * @param other Optional. Any additional properties to include on the card.
964
+ * @returns A message activity attached with a thumbnail card
965
+ *
966
+ * @beta
967
+ */
968
+ static attachThumbnailCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<ThumbnailCard>): Partial<Activity_2>;
969
+ /**
970
+ * Add an attachement to a bot activity.
971
+ * @param attachement The attachment object to attach.
972
+ * @returns A message activity with an attachment.
973
+ *
974
+ * @beta
975
+ */
976
+ static attachContent(attachement: Attachment): Partial<Activity_2>;
977
+ }
1010
978
 
1011
- /**
1012
- * Represent a notification target.
1013
- *
1014
- * @beta
1015
- */
1016
- export declare interface NotificationTarget {
1017
- /**
1018
- * The type of target, could be "Channel" or "Group" or "Person".
1019
- *
1020
- * @beta
1021
- */
1022
- readonly type?: NotificationTargetType;
1023
- /**
1024
- * Send a plain text message.
1025
- *
1026
- * @param text - the plain text message.
1027
- *
1028
- * @beta
1029
- */
1030
- sendMessage(text: string): Promise<void>;
1031
- /**
1032
- * Send an adaptive card message.
1033
- *
1034
- * @param card - the adaptive card raw JSON.
1035
- *
1036
- * @beta
1037
- */
1038
- sendAdaptiveCard(card: unknown): Promise<void>;
1039
- }
979
+ /**
980
+ * Microsoft Graph auth provider for Teams Framework
981
+ *
982
+ * @beta
983
+ */
984
+ export declare class MsGraphAuthProvider implements AuthenticationProvider {
985
+ private teamsfx;
986
+ private scopes;
987
+ /**
988
+ * Constructor of MsGraphAuthProvider.
989
+ *
990
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth.
991
+ * @param {string | string[]} scopes - The list of scopes for which the token will have access.
992
+ *
993
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
994
+ *
995
+ * @returns An instance of MsGraphAuthProvider.
996
+ *
997
+ * @beta
998
+ */
999
+ constructor(teamsfx: TeamsFxConfiguration, scopes?: string | string[]);
1000
+ /**
1001
+ * Get access token for Microsoft Graph API requests.
1002
+ *
1003
+ * @throws {@link ErrorCode|InternalError} when get access token failed due to empty token or unknown other problems.
1004
+ * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1005
+ * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1006
+ * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth or AAD server.
1007
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1008
+ *
1009
+ * @returns Access token from the credential.
1010
+ *
1011
+ */
1012
+ getAccessToken(): Promise<string>;
1013
+ }
1040
1014
 
1041
- /**
1042
- * Interface for a storage provider that stores and retrieves notification target references.
1043
- *
1044
- * @beta
1045
- */
1046
- export declare interface NotificationTargetStorage {
1047
- /**
1048
- * Read one notification target by its key.
1049
- *
1050
- * @param key - the key of a notification target.
1051
- *
1052
- * @returns - the notification target. Or undefined if not found.
1053
- *
1054
- * @beta
1055
- */
1056
- read(key: string): Promise<{
1057
- [key: string]: unknown;
1058
- } | undefined>;
1059
- /**
1060
- * List all stored notification targets.
1061
- *
1062
- * @returns - an array of notification target. Or an empty array if nothing is stored.
1063
- *
1064
- * @beta
1065
- */
1066
- list(): Promise<{
1067
- [key: string]: unknown;
1068
- }[]>;
1069
- /**
1070
- * Write one notification target by its key.
1071
- *
1072
- * @param key - the key of a notification target.
1073
- * @param object - the notification target.
1074
- *
1075
- * @beta
1076
- */
1077
- write(key: string, object: {
1078
- [key: string]: unknown;
1079
- }): Promise<void>;
1080
- /**
1081
- * Delete one notificaton target by its key.
1082
- *
1083
- * @param key - the key of a notification target.
1084
- *
1085
- * @beta
1086
- */
1087
- delete(key: string): Promise<void>;
1088
- }
1015
+ /**
1016
+ * Provide utilities to send notification to varies targets (e.g., member, group, channel).
1017
+ *
1018
+ * @beta
1019
+ */
1020
+ export declare class NotificationBot {
1021
+ private readonly conversationReferenceStore;
1022
+ private readonly adapter;
1023
+ /**
1024
+ * constructor of the notification bot.
1025
+ *
1026
+ * @remarks
1027
+ * To ensure accuracy, it's recommended to initialize before handling any message.
1028
+ *
1029
+ * @param adapter - the bound `BotFrameworkAdapter`
1030
+ * @param options - initialize options
1031
+ *
1032
+ * @beta
1033
+ */
1034
+ constructor(adapter: BotFrameworkAdapter, options?: NotificationOptions_2);
1035
+ /**
1036
+ * Get all targets where the bot is installed.
1037
+ *
1038
+ * @remarks
1039
+ * The result is retrieving from the persisted storage.
1040
+ *
1041
+ * @returns - an array of {@link TeamsBotInstallation}.
1042
+ *
1043
+ * @beta
1044
+ */
1045
+ installations(): Promise<TeamsBotInstallation[]>;
1046
+ }
1089
1047
 
1090
- /**
1091
- * The target type where the notification will be sent to.
1092
- *
1093
- * @remarks
1094
- * - "Channel" means to a team channel. (By default, notification to a team will be sent to its "General" channel.)
1095
- * - "Group" means to a group chat.
1096
- * - "Person" means to a personal chat.
1097
- *
1098
- * @beta
1099
- */
1100
- export declare type NotificationTargetType = "Channel" | "Group" | "Person";
1048
+ /**
1049
+ * Options to initialize {@link NotificationBot}.
1050
+ *
1051
+ * @beta
1052
+ */
1053
+ declare interface NotificationOptions_2 {
1054
+ /**
1055
+ * An optional storage to persist bot notification connections.
1056
+ *
1057
+ * @remarks
1058
+ * If `storage` is not provided, a default local file storage will be used,
1059
+ * which stores notification connections into:
1060
+ * - ".notification.localstore.json" if running locally
1061
+ * - "${process.env.TEMP}/.notification.localstore.json" if `process.env.RUNNING_ON_AZURE` is set to "1"
1062
+ *
1063
+ * It's recommended to use your own shared storage for production environment.
1064
+ *
1065
+ * @beta
1066
+ */
1067
+ storage?: NotificationTargetStorage;
1068
+ }
1069
+ export { NotificationOptions_2 as NotificationOptions }
1101
1070
 
1102
- /**
1103
- * Represent on-behalf-of flow to get user identity, and it is designed to be used in server side.
1104
- *
1105
- * @example
1106
- * ```typescript
1107
- * const credential = new OnBehalfOfUserCredential(ssoToken);
1108
- * ```
1109
- *
1110
- * @remarks
1111
- * Can only be used in server side.
1112
- *
1113
- * @beta
1114
- */
1115
- export declare class OnBehalfOfUserCredential implements TokenCredential {
1116
- private msalClient;
1117
- private ssoToken;
1118
- /**
1119
- * Constructor of OnBehalfOfUserCredential
1120
- *
1121
- * @remarks
1122
- * Only works in in server side.
1123
- *
1124
- * @param {string} ssoToken - User token provided by Teams SSO feature.
1125
- * @param {AuthenticationConfiguration} config - The authentication configuration. Use environment variables if not provided.
1126
- *
1127
- * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret, certificate content, authority host or tenant id is not found in config.
1128
- * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1129
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1130
- *
1131
- * @beta
1132
- */
1133
- constructor(ssoToken: string, config: AuthenticationConfiguration);
1134
- /**
1135
- * Get access token from credential.
1136
- *
1137
- * @example
1138
- * ```typescript
1139
- * await credential.getToken([]) // Get SSO token using empty string array
1140
- * await credential.getToken("") // Get SSO token using empty string
1141
- * await credential.getToken([".default"]) // Get Graph access token with default scope using string array
1142
- * await credential.getToken(".default") // Get Graph access token with default scope using string
1143
- * await credential.getToken(["User.Read"]) // Get Graph access token for single scope using string array
1144
- * await credential.getToken("User.Read") // Get Graph access token for single scope using string
1145
- * await credential.getToken(["User.Read", "Application.Read.All"]) // Get Graph access token for multiple scopes using string array
1146
- * await credential.getToken("User.Read Application.Read.All") // Get Graph access token for multiple scopes using space-separated string
1147
- * await credential.getToken("https://graph.microsoft.com/User.Read") // Get Graph access token with full resource URI
1148
- * await credential.getToken(["https://outlook.office.com/Mail.Read"]) // Get Outlook access token
1149
- * ```
1150
- *
1151
- * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1152
- * @param {GetTokenOptions} options - The options used to configure any requests this TokenCredential implementation might make.
1153
- *
1154
- * @throws {@link ErrorCode|InternalError} when failed to acquire access token on behalf of user with unknown error.
1155
- * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1156
- * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1157
- * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth server.
1158
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1159
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1160
- *
1161
- * @returns Access token with expected scopes.
1162
- *
1163
- * @remarks
1164
- * If scopes is empty string or array, it returns SSO token.
1165
- * If scopes is non-empty, it returns access token for target scope.
1166
- *
1167
- * @beta
1168
- */
1169
- getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1170
- /**
1171
- * Get basic user info from SSO token.
1172
- *
1173
- * @example
1174
- * ```typescript
1175
- * const currentUser = getUserInfo();
1176
- * ```
1177
- *
1178
- * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1179
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1180
- *
1181
- * @returns Basic user info with user displayName, objectId and preferredUserName.
1182
- *
1183
- * @beta
1184
- */
1185
- getUserInfo(): UserInfo;
1186
- private generateAuthServerError;
1187
- }
1071
+ /**
1072
+ * Represent a notification target.
1073
+ *
1074
+ * @beta
1075
+ */
1076
+ export declare interface NotificationTarget {
1077
+ /**
1078
+ * The type of target, could be "Channel" or "Group" or "Person".
1079
+ *
1080
+ * @beta
1081
+ */
1082
+ readonly type?: NotificationTargetType;
1083
+ /**
1084
+ * Send a plain text message.
1085
+ *
1086
+ * @param text - the plain text message.
1087
+ *
1088
+ * @beta
1089
+ */
1090
+ sendMessage(text: string): Promise<void>;
1091
+ /**
1092
+ * Send an adaptive card message.
1093
+ *
1094
+ * @param card - the adaptive card raw JSON.
1095
+ *
1096
+ * @beta
1097
+ */
1098
+ sendAdaptiveCard(card: unknown): Promise<void>;
1099
+ }
1188
1100
 
1189
- /**
1190
- * Send an adaptive card message to a notification target.
1191
- *
1192
- * @param target - the notification target.
1193
- * @param card - the adaptive card raw JSON.
1194
- * @returns A `Promise` representing the asynchronous operation.
1195
- *
1196
- * @beta
1197
- */
1198
- export declare function sendAdaptiveCard(target: NotificationTarget, card: unknown): Promise<void>;
1101
+ /**
1102
+ * Interface for a storage provider that stores and retrieves notification target references.
1103
+ *
1104
+ * @beta
1105
+ */
1106
+ export declare interface NotificationTargetStorage {
1107
+ /**
1108
+ * Read one notification target by its key.
1109
+ *
1110
+ * @param key - the key of a notification target.
1111
+ *
1112
+ * @returns - the notification target. Or undefined if not found.
1113
+ *
1114
+ * @beta
1115
+ */
1116
+ read(key: string): Promise<{
1117
+ [key: string]: unknown;
1118
+ } | undefined>;
1119
+ /**
1120
+ * List all stored notification targets.
1121
+ *
1122
+ * @returns - an array of notification target. Or an empty array if nothing is stored.
1123
+ *
1124
+ * @beta
1125
+ */
1126
+ list(): Promise<{
1127
+ [key: string]: unknown;
1128
+ }[]>;
1129
+ /**
1130
+ * Write one notification target by its key.
1131
+ *
1132
+ * @param key - the key of a notification target.
1133
+ * @param object - the notification target.
1134
+ *
1135
+ * @beta
1136
+ */
1137
+ write(key: string, object: {
1138
+ [key: string]: unknown;
1139
+ }): Promise<void>;
1140
+ /**
1141
+ * Delete one notificaton target by its key.
1142
+ *
1143
+ * @param key - the key of a notification target.
1144
+ *
1145
+ * @beta
1146
+ */
1147
+ delete(key: string): Promise<void>;
1148
+ }
1199
1149
 
1200
- /**
1201
- * Send a plain text message to a notification target.
1202
- *
1203
- * @param target - the notification target.
1204
- * @param text - the plain text message.
1205
- * @returns A `Promise` representing the asynchronous operation.
1206
- *
1207
- * @beta
1208
- */
1209
- export declare function sendMessage(target: NotificationTarget, text: string): Promise<void>;
1150
+ /**
1151
+ * The target type where the notification will be sent to.
1152
+ *
1153
+ * @remarks
1154
+ * - "Channel" means to a team channel. (By default, notification to a team will be sent to its "General" channel.)
1155
+ * - "Group" means to a group chat.
1156
+ * - "Person" means to a personal chat.
1157
+ *
1158
+ * @beta
1159
+ */
1160
+ export declare type NotificationTargetType = "Channel" | "Group" | "Person";
1210
1161
 
1211
- /**
1212
- * Set custom log function. Use the function if it's set. Priority is lower than setLogger.
1213
- *
1214
- * @param {LogFunction} logFunction - custom log function. If it's undefined, custom log function will be cleared.
1215
- *
1216
- * @example
1217
- * ```typescript
1218
- * setLogFunction((level: LogLevel, message: string) => {
1219
- * if (level === LogLevel.Error) {
1220
- * console.log(message);
1221
- * }
1222
- * });
1223
- * ```
1224
- *
1225
- * @beta
1226
- */
1227
- export declare function setLogFunction(logFunction?: LogFunction): void;
1162
+ /**
1163
+ * Represent on-behalf-of flow to get user identity, and it is designed to be used in server side.
1164
+ *
1165
+ * @example
1166
+ * ```typescript
1167
+ * const credential = new OnBehalfOfUserCredential(ssoToken);
1168
+ * ```
1169
+ *
1170
+ * @remarks
1171
+ * Can only be used in server side.
1172
+ *
1173
+ * @beta
1174
+ */
1175
+ export declare class OnBehalfOfUserCredential implements TokenCredential {
1176
+ private msalClient;
1177
+ private ssoToken;
1178
+ /**
1179
+ * Constructor of OnBehalfOfUserCredential
1180
+ *
1181
+ * @remarks
1182
+ * Only works in in server side.
1183
+ *
1184
+ * @param {string} ssoToken - User token provided by Teams SSO feature.
1185
+ * @param {AuthenticationConfiguration} config - The authentication configuration. Use environment variables if not provided.
1186
+ *
1187
+ * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret, certificate content, authority host or tenant id is not found in config.
1188
+ * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1189
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1190
+ *
1191
+ * @beta
1192
+ */
1193
+ constructor(ssoToken: string, config: AuthenticationConfiguration);
1194
+ /**
1195
+ * Get access token from credential.
1196
+ *
1197
+ * @example
1198
+ * ```typescript
1199
+ * await credential.getToken([]) // Get SSO token using empty string array
1200
+ * await credential.getToken("") // Get SSO token using empty string
1201
+ * await credential.getToken([".default"]) // Get Graph access token with default scope using string array
1202
+ * await credential.getToken(".default") // Get Graph access token with default scope using string
1203
+ * await credential.getToken(["User.Read"]) // Get Graph access token for single scope using string array
1204
+ * await credential.getToken("User.Read") // Get Graph access token for single scope using string
1205
+ * await credential.getToken(["User.Read", "Application.Read.All"]) // Get Graph access token for multiple scopes using string array
1206
+ * await credential.getToken("User.Read Application.Read.All") // Get Graph access token for multiple scopes using space-separated string
1207
+ * await credential.getToken("https://graph.microsoft.com/User.Read") // Get Graph access token with full resource URI
1208
+ * await credential.getToken(["https://outlook.office.com/Mail.Read"]) // Get Outlook access token
1209
+ * ```
1210
+ *
1211
+ * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1212
+ * @param {GetTokenOptions} options - The options used to configure any requests this TokenCredential implementation might make.
1213
+ *
1214
+ * @throws {@link ErrorCode|InternalError} when failed to acquire access token on behalf of user with unknown error.
1215
+ * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1216
+ * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1217
+ * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth server.
1218
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1219
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1220
+ *
1221
+ * @returns Access token with expected scopes.
1222
+ *
1223
+ * @remarks
1224
+ * If scopes is empty string or array, it returns SSO token.
1225
+ * If scopes is non-empty, it returns access token for target scope.
1226
+ *
1227
+ * @beta
1228
+ */
1229
+ getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1230
+ /**
1231
+ * Get basic user info from SSO token.
1232
+ *
1233
+ * @example
1234
+ * ```typescript
1235
+ * const currentUser = getUserInfo();
1236
+ * ```
1237
+ *
1238
+ * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1239
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1240
+ *
1241
+ * @returns Basic user info with user displayName, objectId and preferredUserName.
1242
+ *
1243
+ * @beta
1244
+ */
1245
+ getUserInfo(): UserInfo;
1246
+ private generateAuthServerError;
1247
+ }
1228
1248
 
1229
- /**
1230
- * Set custom logger. Use the output functions if it's set. Priority is higher than setLogFunction.
1231
- *
1232
- * @param {Logger} logger - custom logger. If it's undefined, custom logger will be cleared.
1233
- *
1234
- * @example
1235
- * ```typescript
1236
- * setLogger({
1237
- * verbose: console.debug,
1238
- * info: console.info,
1239
- * warn: console.warn,
1240
- * error: console.error,
1241
- * });
1242
- * ```
1243
- *
1244
- * @beta
1245
- */
1246
- export declare function setLogger(logger?: Logger): void;
1249
+ /**
1250
+ * Send an adaptive card message to a notification target.
1251
+ *
1252
+ * @param target - the notification target.
1253
+ * @param card - the adaptive card raw JSON.
1254
+ * @returns A `Promise` representing the asynchronous operation.
1255
+ *
1256
+ * @beta
1257
+ */
1258
+ export declare function sendAdaptiveCard(target: NotificationTarget, card: unknown): Promise<void>;
1247
1259
 
1248
- /**
1249
- * Update log level helper.
1250
- *
1251
- * @param { LogLevel } level - log level in configuration
1252
- *
1253
- * @beta
1254
- */
1255
- export declare function setLogLevel(level: LogLevel): void;
1260
+ /**
1261
+ * Send a plain text message to a notification target.
1262
+ *
1263
+ * @param target - the notification target.
1264
+ * @param text - the plain text message.
1265
+ * @returns A `Promise` representing the asynchronous operation.
1266
+ *
1267
+ * @beta
1268
+ */
1269
+ export declare function sendMessage(target: NotificationTarget, text: string): Promise<void>;
1256
1270
 
1257
- /**
1258
- * A {@link NotificationTarget} that represents a bot installation. Teams Bot could be installed into
1259
- * - Personal chat
1260
- * - Group chat
1261
- * - Team (by default the `General` channel)
1262
- *
1263
- * @remarks
1264
- * It's recommended to get bot installations from {@link ConversationBot.installations()}.
1265
- *
1266
- * @beta
1267
- */
1268
- export declare class TeamsBotInstallation implements NotificationTarget {
1269
- /**
1270
- * The bound `BotFrameworkAdapter`.
1271
- *
1272
- * @beta
1273
- */
1274
- readonly adapter: BotFrameworkAdapter;
1275
- /**
1276
- * The bound `ConversationReference`.
1277
- *
1278
- * @beta
1279
- */
1280
- readonly conversationReference: Partial<ConversationReference>;
1281
- /**
1282
- * Notification target type.
1283
- *
1284
- * @remarks
1285
- * - "Channel" means bot is installed into a team and notification will be sent to its "General" channel.
1286
- * - "Group" means bot is installed into a group chat.
1287
- * - "Person" means bot is installed into a personal scope and notification will be sent to personal chat.
1288
- *
1289
- * @beta
1290
- */
1291
- readonly type?: NotificationTargetType;
1292
- /**
1293
- * Constructor
1294
- *
1295
- * @remarks
1296
- * It's recommended to get bot installations from {@link ConversationBot.installations()}, instead of using this constructor.
1297
- *
1298
- * @param adapter - the bound `BotFrameworkAdapter`.
1299
- * @param conversationReference - the bound `ConversationReference`.
1300
- *
1301
- * @beta
1302
- */
1303
- constructor(adapter: BotFrameworkAdapter, conversationReference: Partial<ConversationReference>);
1304
- /**
1305
- * Send a plain text message.
1306
- *
1307
- * @param text - the plain text message.
1308
- * @returns A `Promise` representing the asynchronous operation.
1309
- *
1310
- * @beta
1311
- */
1312
- sendMessage(text: string): Promise<void>;
1313
- /**
1314
- * Send an adaptive card message.
1315
- *
1316
- * @param card - the adaptive card raw JSON.
1317
- * @returns A `Promise` representing the asynchronous operation.
1318
- *
1319
- * @beta
1320
- */
1321
- sendAdaptiveCard(card: unknown): Promise<void>;
1322
- /**
1323
- * Get channels from this bot installation.
1324
- *
1325
- * @returns an array of channels if bot is installed into a team, otherwise returns an empty array.
1326
- *
1327
- * @beta
1328
- */
1329
- channels(): Promise<Channel[]>;
1330
- /**
1331
- * Get members from this bot installation.
1332
- *
1333
- * @returns an array of members from where the bot is installed.
1334
- *
1335
- * @beta
1336
- */
1337
- members(): Promise<Member[]>;
1338
- }
1271
+ /**
1272
+ * Set custom log function. Use the function if it's set. Priority is lower than setLogger.
1273
+ *
1274
+ * @param {LogFunction} logFunction - custom log function. If it's undefined, custom log function will be cleared.
1275
+ *
1276
+ * @example
1277
+ * ```typescript
1278
+ * setLogFunction((level: LogLevel, message: string) => {
1279
+ * if (level === LogLevel.Error) {
1280
+ * console.log(message);
1281
+ * }
1282
+ * });
1283
+ * ```
1284
+ *
1285
+ * @beta
1286
+ */
1287
+ export declare function setLogFunction(logFunction?: LogFunction): void;
1339
1288
 
1340
- /**
1341
- * Creates a new prompt that leverage Teams Single Sign On (SSO) support for bot to automatically sign in user and
1342
- * help receive oauth token, asks the user to consent if needed.
1343
- *
1344
- * @remarks
1345
- * The prompt will attempt to retrieve the users current token of the desired scopes and store it in
1346
- * the token store.
1347
- *
1348
- * User will be automatically signed in leveraging Teams support of Bot Single Sign On(SSO):
1349
- * https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots
1350
- *
1351
- * @example
1352
- * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named
1353
- * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either
1354
- * `DialogContext.beginDialog()` or `DialogContext.prompt()`. The user will be prompted to sign in as
1355
- * needed and their access token will be passed as an argument to the callers next waterfall step:
1356
- *
1357
- * ```JavaScript
1358
- * const { ConversationState, MemoryStorage } = require('botbuilder');
1359
- * const { DialogSet, WaterfallDialog } = require('botbuilder-dialogs');
1360
- * const { TeamsBotSsoPrompt } = require('@microsoft/teamsfx');
1361
- *
1362
- * const convoState = new ConversationState(new MemoryStorage());
1363
- * const dialogState = convoState.createProperty('dialogState');
1364
- * const dialogs = new DialogSet(dialogState);
1365
- *
1366
- * dialogs.add(new TeamsBotSsoPrompt('TeamsBotSsoPrompt', {
1367
- * scopes: ["User.Read"],
1368
- * }));
1369
- *
1370
- * dialogs.add(new WaterfallDialog('taskNeedingLogin', [
1371
- * async (step) => {
1372
- * return await step.beginDialog('TeamsBotSsoPrompt');
1373
- * },
1374
- * async (step) => {
1375
- * const token = step.result;
1376
- * if (token) {
1377
- *
1378
- * // ... continue with task needing access token ...
1379
- *
1380
- * } else {
1381
- * await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
1382
- * return await step.endDialog();
1383
- * }
1384
- * }
1385
- * ]));
1386
- * ```
1387
- *
1388
- * @beta
1389
- */
1390
- export declare class TeamsBotSsoPrompt extends Dialog {
1391
- private teamsfx;
1392
- private settings;
1393
- /**
1394
- * Constructor of TeamsBotSsoPrompt.
1395
- *
1396
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth
1397
- * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
1398
- * @param settings Settings used to configure the prompt.
1399
- *
1400
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1401
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1402
- *
1403
- * @beta
1404
- */
1405
- constructor(teamsfx: TeamsFx, dialogId: string, settings: TeamsBotSsoPromptSettings);
1406
- /**
1407
- * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
1408
- * @remarks
1409
- * If the task is successful, the result indicates whether the prompt is still
1410
- * active after the turn has been processed by the prompt.
1411
- *
1412
- * @param dc The DialogContext for the current turn of the conversation.
1413
- *
1414
- * @throws {@link ErrorCode|InvalidParameter} when timeout property in teams bot sso prompt settings is not number or is not positive.
1415
- * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1416
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1417
- *
1418
- * @returns A `Promise` representing the asynchronous operation.
1419
- *
1420
- * @beta
1421
- */
1422
- beginDialog(dc: DialogContext): Promise<DialogTurnResult>;
1423
- /**
1424
- * Called when a prompt dialog is the active dialog and the user replied with a new activity.
1425
- *
1426
- * @remarks
1427
- * If the task is successful, the result indicates whether the dialog is still
1428
- * active after the turn has been processed by the dialog.
1429
- * The prompt generally continues to receive the user's replies until it accepts the
1430
- * user's reply as valid input for the prompt.
1431
- *
1432
- * @param dc The DialogContext for the current turn of the conversation.
1433
- *
1434
- * @returns A `Promise` representing the asynchronous operation.
1435
- *
1436
- * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1437
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1438
- *
1439
- * @beta
1440
- */
1441
- continueDialog(dc: DialogContext): Promise<DialogTurnResult>;
1442
- private loadAndValidateConfig;
1443
- /**
1444
- * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
1445
- * @param dc dialog context
1446
- * @throws {@link ErrorCode|ChannelNotSupported} if bot channel is not MS Teams
1447
- * @internal
1448
- */
1449
- private ensureMsTeamsChannel;
1450
- /**
1451
- * Send OAuthCard that tells Teams to obtain an authentication token for the bot application.
1452
- * For details see https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots.
1453
- *
1454
- * @internal
1455
- */
1456
- private sendOAuthCardAsync;
1457
- /**
1458
- * Get sign in resource.
1459
- *
1460
- * @throws {@link ErrorCode|InvalidConfiguration} if client id, tenant id or initiate login endpoint is not found in config.
1461
- *
1462
- * @internal
1463
- */
1464
- private getSignInResource;
1465
- /**
1466
- * @internal
1467
- */
1468
- private recognizeToken;
1469
- /**
1470
- * @internal
1471
- */
1472
- private getTokenExchangeInvokeResponse;
1473
- /**
1474
- * @internal
1475
- */
1476
- private isTeamsVerificationInvoke;
1477
- /**
1478
- * @internal
1479
- */
1480
- private isTokenExchangeRequestInvoke;
1481
- /**
1482
- * @internal
1483
- */
1484
- private isTokenExchangeRequest;
1485
- }
1289
+ /**
1290
+ * Set custom logger. Use the output functions if it's set. Priority is higher than setLogFunction.
1291
+ *
1292
+ * @param {Logger} logger - custom logger. If it's undefined, custom logger will be cleared.
1293
+ *
1294
+ * @example
1295
+ * ```typescript
1296
+ * setLogger({
1297
+ * verbose: console.debug,
1298
+ * info: console.info,
1299
+ * warn: console.warn,
1300
+ * error: console.error,
1301
+ * });
1302
+ * ```
1303
+ *
1304
+ * @beta
1305
+ */
1306
+ export declare function setLogger(logger?: Logger): void;
1486
1307
 
1487
- /**
1488
- * Settings used to configure an TeamsBotSsoPrompt instance.
1489
- *
1490
- * @beta
1491
- */
1492
- export declare interface TeamsBotSsoPromptSettings {
1493
- /**
1494
- * The array of strings that declare the desired permissions and the resources requested.
1495
- */
1496
- scopes: string[];
1497
- /**
1498
- * (Optional) number of milliseconds the prompt will wait for the user to authenticate.
1499
- * Defaults to a value `900,000` (15 minutes.)
1500
- */
1501
- timeout?: number;
1502
- /**
1503
- * (Optional) value indicating whether the TeamsBotSsoPrompt should end upon receiving an
1504
- * invalid message. Generally the TeamsBotSsoPrompt will end the auth flow when receives user
1505
- * message not related to the auth flow. Setting the flag to false ignores the user's message instead.
1506
- * Defaults to value `true`
1507
- */
1508
- endOnInvalidMessage?: boolean;
1509
- }
1308
+ /**
1309
+ * Update log level helper.
1310
+ *
1311
+ * @param { LogLevel } level - log level in configuration
1312
+ *
1313
+ * @beta
1314
+ */
1315
+ export declare function setLogLevel(level: LogLevel): void;
1510
1316
 
1511
- /**
1512
- * Token response provided by Teams Bot SSO prompt
1513
- *
1514
- * @beta
1515
- */
1516
- export declare interface TeamsBotSsoPromptTokenResponse extends TokenResponse {
1517
- /**
1518
- * SSO token for user
1519
- */
1520
- ssoToken: string;
1521
- /**
1522
- * Expire time of SSO token
1523
- */
1524
- ssoTokenExpiration: string;
1525
- }
1317
+ /**
1318
+ * A {@link NotificationTarget} that represents a bot installation. Teams Bot could be installed into
1319
+ * - Personal chat
1320
+ * - Group chat
1321
+ * - Team (by default the `General` channel)
1322
+ *
1323
+ * @remarks
1324
+ * It's recommended to get bot installations from {@link ConversationBot.installations()}.
1325
+ *
1326
+ * @beta
1327
+ */
1328
+ export declare class TeamsBotInstallation implements NotificationTarget {
1329
+ /**
1330
+ * The bound `BotFrameworkAdapter`.
1331
+ *
1332
+ * @beta
1333
+ */
1334
+ readonly adapter: BotFrameworkAdapter;
1335
+ /**
1336
+ * The bound `ConversationReference`.
1337
+ *
1338
+ * @beta
1339
+ */
1340
+ readonly conversationReference: Partial<ConversationReference>;
1341
+ /**
1342
+ * Notification target type.
1343
+ *
1344
+ * @remarks
1345
+ * - "Channel" means bot is installed into a team and notification will be sent to its "General" channel.
1346
+ * - "Group" means bot is installed into a group chat.
1347
+ * - "Person" means bot is installed into a personal scope and notification will be sent to personal chat.
1348
+ *
1349
+ * @beta
1350
+ */
1351
+ readonly type?: NotificationTargetType;
1352
+ /**
1353
+ * Constructor
1354
+ *
1355
+ * @remarks
1356
+ * It's recommended to get bot installations from {@link ConversationBot.installations()}, instead of using this constructor.
1357
+ *
1358
+ * @param adapter - the bound `BotFrameworkAdapter`.
1359
+ * @param conversationReference - the bound `ConversationReference`.
1360
+ *
1361
+ * @beta
1362
+ */
1363
+ constructor(adapter: BotFrameworkAdapter, conversationReference: Partial<ConversationReference>);
1364
+ /**
1365
+ * Send a plain text message.
1366
+ *
1367
+ * @param text - the plain text message.
1368
+ * @returns A `Promise` representing the asynchronous operation.
1369
+ *
1370
+ * @beta
1371
+ */
1372
+ sendMessage(text: string): Promise<void>;
1373
+ /**
1374
+ * Send an adaptive card message.
1375
+ *
1376
+ * @param card - the adaptive card raw JSON.
1377
+ * @returns A `Promise` representing the asynchronous operation.
1378
+ *
1379
+ * @beta
1380
+ */
1381
+ sendAdaptiveCard(card: unknown): Promise<void>;
1382
+ /**
1383
+ * Get channels from this bot installation.
1384
+ *
1385
+ * @returns an array of channels if bot is installed into a team, otherwise returns an empty array.
1386
+ *
1387
+ * @beta
1388
+ */
1389
+ channels(): Promise<Channel[]>;
1390
+ /**
1391
+ * Get members from this bot installation.
1392
+ *
1393
+ * @returns an array of members from where the bot is installed.
1394
+ *
1395
+ * @beta
1396
+ */
1397
+ members(): Promise<Member[]>;
1398
+ }
1526
1399
 
1527
- /**
1528
- * A class providing credential and configuration.
1529
- * @beta
1530
- */
1531
- export declare class TeamsFx implements TeamsFxConfiguration {
1532
- private configuration;
1533
- private oboUserCredential?;
1534
- private appCredential?;
1535
- private identityType;
1536
- /**
1537
- * Constructor of TeamsFx
1538
- *
1539
- * @param {IdentityType} identityType - Choose user or app identity
1540
- * @param customConfig - key/value pairs of customized configuration that overrides default ones.
1541
- *
1542
- * @throws {@link ErrorCode|IdentityTypeNotSupported} when setting app identity in browser.
1543
- *
1544
- * @beta
1545
- */
1546
- constructor(identityType?: IdentityType, customConfig?: Record<string, string>);
1547
- /**
1548
- * Identity type set by user.
1549
- *
1550
- * @returns identity type.
1551
- * @beta
1552
- */
1553
- getIdentityType(): IdentityType;
1554
- /**
1555
- * Credential instance according to identity type choice.
1556
- *
1557
- * @remarks If user identity is chose, will return {@link TeamsUserCredential}
1558
- * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
1559
- * identity is chose, will return {@link AppCredential}.
1560
- *
1561
- * @returns instance implements TokenCredential interface.
1562
- * @beta
1563
- */
1564
- getCredential(): TokenCredential;
1565
- /**
1566
- * Get user information.
1567
- * @returns UserInfo object.
1568
- * @beta
1569
- */
1570
- getUserInfo(): Promise<UserInfo>;
1571
- /**
1572
- * Popup login page to get user's access token with specific scopes.
1573
- *
1574
- * @remarks
1575
- * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
1576
- *
1577
- * @example
1578
- * ```typescript
1579
- * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
1580
- * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
1581
- * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
1582
- * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
1583
- * ```
1584
- * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
1585
- *
1586
- * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
1587
- * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
1588
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1589
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1590
- *
1591
- * @beta
1592
- */
1593
- login(scopes: string | string[]): Promise<void>;
1594
- /**
1595
- * Set SSO token when using user identity in NodeJS.
1596
- * @param {string} ssoToken - used for on behalf of user flow.
1597
- * @returns self instance.
1598
- * @beta
1599
- */
1600
- setSsoToken(ssoToken: string): TeamsFx;
1601
- /**
1602
- * Usually used by service plugins to retrieve specific config
1603
- * @param {string} key - configuration key.
1604
- * @returns value in configuration.
1605
- * @beta
1606
- */
1607
- getConfig(key: string): string;
1608
- /**
1609
- * Check the value of specific key.
1610
- * @param {string} key - configuration key.
1611
- * @returns true if corresponding value is not empty string.
1612
- * @beta
1613
- */
1614
- hasConfig(key: string): boolean;
1615
- /**
1616
- * Get all configurations.
1617
- * @returns key value mappings.
1618
- * @beta
1619
- */
1620
- getConfigs(): Record<string, string>;
1621
- /**
1622
- * Load configuration from environment variables.
1623
- */
1624
- private loadFromEnv;
1625
- }
1400
+ /**
1401
+ * Creates a new prompt that leverage Teams Single Sign On (SSO) support for bot to automatically sign in user and
1402
+ * help receive oauth token, asks the user to consent if needed.
1403
+ *
1404
+ * @remarks
1405
+ * The prompt will attempt to retrieve the users current token of the desired scopes and store it in
1406
+ * the token store.
1407
+ *
1408
+ * User will be automatically signed in leveraging Teams support of Bot Single Sign On(SSO):
1409
+ * https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots
1410
+ *
1411
+ * @example
1412
+ * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named
1413
+ * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either
1414
+ * `DialogContext.beginDialog()` or `DialogContext.prompt()`. The user will be prompted to sign in as
1415
+ * needed and their access token will be passed as an argument to the callers next waterfall step:
1416
+ *
1417
+ * ```JavaScript
1418
+ * const { ConversationState, MemoryStorage } = require('botbuilder');
1419
+ * const { DialogSet, WaterfallDialog } = require('botbuilder-dialogs');
1420
+ * const { TeamsBotSsoPrompt } = require('@microsoft/teamsfx');
1421
+ *
1422
+ * const convoState = new ConversationState(new MemoryStorage());
1423
+ * const dialogState = convoState.createProperty('dialogState');
1424
+ * const dialogs = new DialogSet(dialogState);
1425
+ *
1426
+ * dialogs.add(new TeamsBotSsoPrompt('TeamsBotSsoPrompt', {
1427
+ * scopes: ["User.Read"],
1428
+ * }));
1429
+ *
1430
+ * dialogs.add(new WaterfallDialog('taskNeedingLogin', [
1431
+ * async (step) => {
1432
+ * return await step.beginDialog('TeamsBotSsoPrompt');
1433
+ * },
1434
+ * async (step) => {
1435
+ * const token = step.result;
1436
+ * if (token) {
1437
+ *
1438
+ * // ... continue with task needing access token ...
1439
+ *
1440
+ * } else {
1441
+ * await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
1442
+ * return await step.endDialog();
1443
+ * }
1444
+ * }
1445
+ * ]));
1446
+ * ```
1447
+ *
1448
+ * @beta
1449
+ */
1450
+ export declare class TeamsBotSsoPrompt extends Dialog {
1451
+ private teamsfx;
1452
+ private settings;
1453
+ /**
1454
+ * Constructor of TeamsBotSsoPrompt.
1455
+ *
1456
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth
1457
+ * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
1458
+ * @param settings Settings used to configure the prompt.
1459
+ *
1460
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1461
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1462
+ *
1463
+ * @beta
1464
+ */
1465
+ constructor(teamsfx: TeamsFx, dialogId: string, settings: TeamsBotSsoPromptSettings);
1466
+ /**
1467
+ * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
1468
+ * @remarks
1469
+ * If the task is successful, the result indicates whether the prompt is still
1470
+ * active after the turn has been processed by the prompt.
1471
+ *
1472
+ * @param dc The DialogContext for the current turn of the conversation.
1473
+ *
1474
+ * @throws {@link ErrorCode|InvalidParameter} when timeout property in teams bot sso prompt settings is not number or is not positive.
1475
+ * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1476
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1477
+ *
1478
+ * @returns A `Promise` representing the asynchronous operation.
1479
+ *
1480
+ * @beta
1481
+ */
1482
+ beginDialog(dc: DialogContext): Promise<DialogTurnResult>;
1483
+ /**
1484
+ * Called when a prompt dialog is the active dialog and the user replied with a new activity.
1485
+ *
1486
+ * @remarks
1487
+ * If the task is successful, the result indicates whether the dialog is still
1488
+ * active after the turn has been processed by the dialog.
1489
+ * The prompt generally continues to receive the user's replies until it accepts the
1490
+ * user's reply as valid input for the prompt.
1491
+ *
1492
+ * @param dc The DialogContext for the current turn of the conversation.
1493
+ *
1494
+ * @returns A `Promise` representing the asynchronous operation.
1495
+ *
1496
+ * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1497
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1498
+ *
1499
+ * @beta
1500
+ */
1501
+ continueDialog(dc: DialogContext): Promise<DialogTurnResult>;
1502
+ private loadAndValidateConfig;
1503
+ /**
1504
+ * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
1505
+ * @param dc dialog context
1506
+ * @throws {@link ErrorCode|ChannelNotSupported} if bot channel is not MS Teams
1507
+ * @internal
1508
+ */
1509
+ private ensureMsTeamsChannel;
1510
+ /**
1511
+ * Send OAuthCard that tells Teams to obtain an authentication token for the bot application.
1512
+ * For details see https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots.
1513
+ *
1514
+ * @internal
1515
+ */
1516
+ private sendOAuthCardAsync;
1517
+ /**
1518
+ * Get sign in resource.
1519
+ *
1520
+ * @throws {@link ErrorCode|InvalidConfiguration} if client id, tenant id or initiate login endpoint is not found in config.
1521
+ *
1522
+ * @internal
1523
+ */
1524
+ private getSignInResource;
1525
+ /**
1526
+ * @internal
1527
+ */
1528
+ private recognizeToken;
1529
+ /**
1530
+ * @internal
1531
+ */
1532
+ private getTokenExchangeInvokeResponse;
1533
+ /**
1534
+ * @internal
1535
+ */
1536
+ private isTeamsVerificationInvoke;
1537
+ /**
1538
+ * @internal
1539
+ */
1540
+ private isTokenExchangeRequestInvoke;
1541
+ /**
1542
+ * @internal
1543
+ */
1544
+ private isTokenExchangeRequest;
1545
+ }
1626
1546
 
1627
- /**
1628
- * Interface for a command handler that can process command to a TeamsFx bot and return a response.
1629
- *
1630
- * @beta
1631
- */
1632
- export declare interface TeamsFxBotCommandHandler {
1633
- /**
1634
- * The string or regular expression patterns that can trigger this handler.
1635
- */
1636
- triggerPatterns: TriggerPatterns;
1637
- /**
1638
- * Handles a bot command received activity.
1639
- *
1640
- * @param context The bot context.
1641
- * @param message The command message the user types from Teams.
1642
- * @returns A `Promise` representing an activity or text to send as the command response.
1643
- */
1644
- handleCommandReceived(context: TurnContext, message: CommandMessage): Promise<string | Partial<Activity>>;
1645
- }
1547
+ /**
1548
+ * Settings used to configure an TeamsBotSsoPrompt instance.
1549
+ *
1550
+ * @beta
1551
+ */
1552
+ export declare interface TeamsBotSsoPromptSettings {
1553
+ /**
1554
+ * The array of strings that declare the desired permissions and the resources requested.
1555
+ */
1556
+ scopes: string[];
1557
+ /**
1558
+ * (Optional) number of milliseconds the prompt will wait for the user to authenticate.
1559
+ * Defaults to a value `900,000` (15 minutes.)
1560
+ */
1561
+ timeout?: number;
1562
+ /**
1563
+ * (Optional) value indicating whether the TeamsBotSsoPrompt should end upon receiving an
1564
+ * invalid message. Generally the TeamsBotSsoPrompt will end the auth flow when receives user
1565
+ * message not related to the auth flow. Setting the flag to false ignores the user's message instead.
1566
+ * Defaults to value `true`
1567
+ */
1568
+ endOnInvalidMessage?: boolean;
1569
+ }
1646
1570
 
1647
- /**
1648
- * TeamsFx interface that provides credential and configuration.
1649
- * @beta
1650
- */
1651
- declare interface TeamsFxConfiguration {
1652
- /**
1653
- * Identity type set by user.
1654
- *
1655
- * @returns identity type.
1656
- * @beta
1657
- */
1658
- getIdentityType(): IdentityType;
1659
- /**
1660
- * Credential instance according to identity type choice.
1661
- *
1662
- * @remarks If user identity is chose, will return {@link TeamsUserCredential}
1663
- * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
1664
- * identity is chose, will return {@link AppCredential}.
1665
- *
1666
- * @returns instance implements TokenCredential interface.
1667
- * @beta
1668
- */
1669
- getCredential(): TokenCredential;
1670
- /**
1671
- * Get user information.
1672
- * @returns UserInfo object.
1673
- * @beta
1674
- */
1675
- getUserInfo(): Promise<UserInfo>;
1676
- /**
1677
- * Popup login page to get user's access token with specific scopes.
1678
- *
1679
- * @remarks
1680
- * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
1681
- *
1682
- * @example
1683
- * ```typescript
1684
- * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
1685
- * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
1686
- * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
1687
- * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
1688
- * ```
1689
- * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
1690
- *
1691
- * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
1692
- * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
1693
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1694
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1695
- *
1696
- * @beta
1697
- */
1698
- login(scopes: string | string[]): Promise<void>;
1699
- /**
1700
- * Set SSO token when using user identity in NodeJS.
1701
- * @param {string} ssoToken - used for on behalf of user flow.
1702
- * @returns self instance.
1703
- * @beta
1704
- */
1705
- setSsoToken(ssoToken: string): TeamsFxConfiguration;
1706
- /**
1707
- * Usually used by service plugins to retrieve specific config
1708
- * @param {string} key - configuration key.
1709
- * @returns value in configuration.
1710
- * @beta
1711
- */
1712
- getConfig(key: string): string;
1713
- /**
1714
- * Check the value of specific key.
1715
- * @param {string} key - configuration key.
1716
- * @returns true if corresponding value is not empty string.
1717
- * @beta
1718
- */
1719
- hasConfig(key: string): boolean;
1720
- /**
1721
- * Get all configurations.
1722
- * @returns key value mappings.
1723
- * @beta
1724
- */
1725
- getConfigs(): Record<string, string>;
1726
- }
1571
+ /**
1572
+ * Token response provided by Teams Bot SSO prompt
1573
+ *
1574
+ * @beta
1575
+ */
1576
+ export declare interface TeamsBotSsoPromptTokenResponse extends TokenResponse {
1577
+ /**
1578
+ * SSO token for user
1579
+ */
1580
+ ssoToken: string;
1581
+ /**
1582
+ * Expire time of SSO token
1583
+ */
1584
+ ssoTokenExpiration: string;
1585
+ }
1727
1586
 
1728
- /**
1729
- * Represent Teams current user's identity, and it is used within Teams client applications.
1730
- *
1731
- * @remarks
1732
- * Can only be used within Teams.
1733
- *
1734
- * @beta
1735
- */
1736
- export declare class TeamsUserCredential implements TokenCredential {
1737
- /**
1738
- * Constructor of TeamsUserCredential.
1739
- * @remarks
1740
- * Can only be used within Teams.
1741
- * @beta
1742
- */
1743
- constructor(authConfig: AuthenticationConfiguration);
1744
- /**
1745
- * Popup login page to get user's access token with specific scopes.
1746
- * @remarks
1747
- * Can only be used within Teams.
1748
- * @beta
1749
- */
1750
- login(scopes: string | string[]): Promise<void>;
1751
- /**
1752
- * Get access token from credential.
1753
- * @remarks
1754
- * Can only be used within Teams.
1755
- * @beta
1756
- */
1757
- getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1758
- /**
1759
- * Get basic user info from SSO token
1760
- * @remarks
1761
- * Can only be used within Teams.
1762
- * @beta
1763
- */
1764
- getUserInfo(): Promise<UserInfo>;
1765
- }
1587
+ /**
1588
+ * A class providing credential and configuration.
1589
+ * @beta
1590
+ */
1591
+ export declare class TeamsFx implements TeamsFxConfiguration {
1592
+ private configuration;
1593
+ private oboUserCredential?;
1594
+ private appCredential?;
1595
+ private identityType;
1596
+ /**
1597
+ * Constructor of TeamsFx
1598
+ *
1599
+ * @param {IdentityType} identityType - Choose user or app identity
1600
+ * @param customConfig - key/value pairs of customized configuration that overrides default ones.
1601
+ *
1602
+ * @throws {@link ErrorCode|IdentityTypeNotSupported} when setting app identity in browser.
1603
+ *
1604
+ * @beta
1605
+ */
1606
+ constructor(identityType?: IdentityType, customConfig?: Record<string, string>);
1607
+ /**
1608
+ * Identity type set by user.
1609
+ *
1610
+ * @returns identity type.
1611
+ * @beta
1612
+ */
1613
+ getIdentityType(): IdentityType;
1614
+ /**
1615
+ * Credential instance according to identity type choice.
1616
+ *
1617
+ * @remarks If user identity is chose, will return {@link TeamsUserCredential}
1618
+ * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
1619
+ * identity is chose, will return {@link AppCredential}.
1620
+ *
1621
+ * @returns instance implements TokenCredential interface.
1622
+ * @beta
1623
+ */
1624
+ getCredential(): TokenCredential;
1625
+ /**
1626
+ * Get user information.
1627
+ * @returns UserInfo object.
1628
+ * @beta
1629
+ */
1630
+ getUserInfo(): Promise<UserInfo>;
1631
+ /**
1632
+ * Popup login page to get user's access token with specific scopes.
1633
+ *
1634
+ * @remarks
1635
+ * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
1636
+ *
1637
+ * @example
1638
+ * ```typescript
1639
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
1640
+ * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
1641
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
1642
+ * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
1643
+ * ```
1644
+ * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
1645
+ *
1646
+ * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
1647
+ * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
1648
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1649
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1650
+ *
1651
+ * @beta
1652
+ */
1653
+ login(scopes: string | string[]): Promise<void>;
1654
+ /**
1655
+ * Set SSO token when using user identity in NodeJS.
1656
+ * @param {string} ssoToken - used for on behalf of user flow.
1657
+ * @returns self instance.
1658
+ * @beta
1659
+ */
1660
+ setSsoToken(ssoToken: string): TeamsFx;
1661
+ /**
1662
+ * Usually used by service plugins to retrieve specific config
1663
+ * @param {string} key - configuration key.
1664
+ * @returns value in configuration.
1665
+ * @beta
1666
+ */
1667
+ getConfig(key: string): string;
1668
+ /**
1669
+ * Check the value of specific key.
1670
+ * @param {string} key - configuration key.
1671
+ * @returns true if corresponding value is not empty string.
1672
+ * @beta
1673
+ */
1674
+ hasConfig(key: string): boolean;
1675
+ /**
1676
+ * Get all configurations.
1677
+ * @returns key value mappings.
1678
+ * @beta
1679
+ */
1680
+ getConfigs(): Record<string, string>;
1681
+ /**
1682
+ * Load configuration from environment variables.
1683
+ */
1684
+ private loadFromEnv;
1685
+ }
1766
1686
 
1767
- /**
1768
- * The trigger pattern used to trigger a {@link TeamsFxBotCommandHandler} instance.
1769
- */
1770
- export declare type TriggerPatterns = string | RegExp | (string | RegExp)[];
1687
+ /**
1688
+ * Interface for a command handler that can process command to a TeamsFx bot and return a response.
1689
+ *
1690
+ * @beta
1691
+ */
1692
+ export declare interface TeamsFxBotCommandHandler {
1693
+ /**
1694
+ * The string or regular expression patterns that can trigger this handler.
1695
+ */
1696
+ triggerPatterns: TriggerPatterns;
1697
+ /**
1698
+ * Handles a bot command received activity.
1699
+ *
1700
+ * @param context The bot context.
1701
+ * @param message The command message the user types from Teams.
1702
+ * @returns A `Promise` representing an activity or text to send as the command response.
1703
+ */
1704
+ handleCommandReceived(context: TurnContext, message: CommandMessage): Promise<string | Partial<Activity>>;
1705
+ }
1771
1706
 
1772
- /**
1773
- * UserInfo with user displayName, objectId and preferredUserName.
1774
- *
1775
- * @beta
1776
- */
1777
- export declare interface UserInfo {
1778
- /**
1779
- * User Display Name.
1780
- *
1781
- * @readonly
1782
- */
1783
- displayName: string;
1784
- /**
1785
- * User unique reference within the Azure Active Directory domain.
1786
- *
1787
- * @readonly
1788
- */
1789
- objectId: string;
1790
- /**
1791
- * Usually be the email address.
1792
- *
1793
- * @readonly
1794
- */
1795
- preferredUserName: string;
1796
- }
1707
+ /**
1708
+ * TeamsFx interface that provides credential and configuration.
1709
+ * @beta
1710
+ */
1711
+ declare interface TeamsFxConfiguration {
1712
+ /**
1713
+ * Identity type set by user.
1714
+ *
1715
+ * @returns identity type.
1716
+ * @beta
1717
+ */
1718
+ getIdentityType(): IdentityType;
1719
+ /**
1720
+ * Credential instance according to identity type choice.
1721
+ *
1722
+ * @remarks If user identity is chose, will return {@link TeamsUserCredential}
1723
+ * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
1724
+ * identity is chose, will return {@link AppCredential}.
1725
+ *
1726
+ * @returns instance implements TokenCredential interface.
1727
+ * @beta
1728
+ */
1729
+ getCredential(): TokenCredential;
1730
+ /**
1731
+ * Get user information.
1732
+ * @returns UserInfo object.
1733
+ * @beta
1734
+ */
1735
+ getUserInfo(): Promise<UserInfo>;
1736
+ /**
1737
+ * Popup login page to get user's access token with specific scopes.
1738
+ *
1739
+ * @remarks
1740
+ * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
1741
+ *
1742
+ * @example
1743
+ * ```typescript
1744
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
1745
+ * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
1746
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
1747
+ * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
1748
+ * ```
1749
+ * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
1750
+ *
1751
+ * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
1752
+ * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
1753
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1754
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1755
+ *
1756
+ * @beta
1757
+ */
1758
+ login(scopes: string | string[]): Promise<void>;
1759
+ /**
1760
+ * Set SSO token when using user identity in NodeJS.
1761
+ * @param {string} ssoToken - used for on behalf of user flow.
1762
+ * @returns self instance.
1763
+ * @beta
1764
+ */
1765
+ setSsoToken(ssoToken: string): TeamsFxConfiguration;
1766
+ /**
1767
+ * Usually used by service plugins to retrieve specific config
1768
+ * @param {string} key - configuration key.
1769
+ * @returns value in configuration.
1770
+ * @beta
1771
+ */
1772
+ getConfig(key: string): string;
1773
+ /**
1774
+ * Check the value of specific key.
1775
+ * @param {string} key - configuration key.
1776
+ * @returns true if corresponding value is not empty string.
1777
+ * @beta
1778
+ */
1779
+ hasConfig(key: string): boolean;
1780
+ /**
1781
+ * Get all configurations.
1782
+ * @returns key value mappings.
1783
+ * @beta
1784
+ */
1785
+ getConfigs(): Record<string, string>;
1786
+ }
1787
+
1788
+ /**
1789
+ * Represent Teams current user's identity, and it is used within Teams client applications.
1790
+ *
1791
+ * @remarks
1792
+ * Can only be used within Teams.
1793
+ *
1794
+ * @beta
1795
+ */
1796
+ export declare class TeamsUserCredential implements TokenCredential {
1797
+ /**
1798
+ * Constructor of TeamsUserCredential.
1799
+ * @remarks
1800
+ * Can only be used within Teams.
1801
+ * @beta
1802
+ */
1803
+ constructor(authConfig: AuthenticationConfiguration);
1804
+ /**
1805
+ * Popup login page to get user's access token with specific scopes.
1806
+ * @remarks
1807
+ * Can only be used within Teams.
1808
+ * @beta
1809
+ */
1810
+ login(scopes: string | string[]): Promise<void>;
1811
+ /**
1812
+ * Get access token from credential.
1813
+ * @remarks
1814
+ * Can only be used within Teams.
1815
+ * @beta
1816
+ */
1817
+ getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1818
+ /**
1819
+ * Get basic user info from SSO token
1820
+ * @remarks
1821
+ * Can only be used within Teams.
1822
+ * @beta
1823
+ */
1824
+ getUserInfo(): Promise<UserInfo>;
1825
+ }
1826
+
1827
+ /**
1828
+ * The trigger pattern used to trigger a {@link TeamsFxBotCommandHandler} instance.
1829
+ */
1830
+ export declare type TriggerPatterns = string | RegExp | (string | RegExp)[];
1831
+
1832
+ /**
1833
+ * UserInfo with user displayName, objectId and preferredUserName.
1834
+ *
1835
+ * @beta
1836
+ */
1837
+ export declare interface UserInfo {
1838
+ /**
1839
+ * User Display Name.
1840
+ *
1841
+ * @readonly
1842
+ */
1843
+ displayName: string;
1844
+ /**
1845
+ * User unique reference within the Azure Active Directory domain.
1846
+ *
1847
+ * @readonly
1848
+ */
1849
+ objectId: string;
1850
+ /**
1851
+ * Usually be the email address.
1852
+ *
1853
+ * @readonly
1854
+ */
1855
+ preferredUserName: string;
1856
+ }
1797
1857
 
1798
- export { }
1858
+ export { }