@microsoft/teamsfx 0.6.3-alpha.8d048e1f1.0 → 0.6.3-alpha.cc1068ff9.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,11 +21,66 @@ 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';
25
28
  import { TokenResponse } from 'botframework-schema';
26
29
  import { TurnContext } from 'botbuilder-core';
30
+ import { TurnContext as TurnContext_2 } from 'botbuilder';
31
+ import { WebRequest } from 'botbuilder';
32
+ import { WebResponse } from 'botbuilder';
33
+
34
+ /**
35
+ * Define available location for API Key location
36
+ *
37
+ * @beta
38
+ */
39
+ export declare enum ApiKeyLocation {
40
+ /**
41
+ * The API Key is placed in request header
42
+ */
43
+ Header = 0,
44
+ /**
45
+ * The API Key is placed in query parameter
46
+ */
47
+ QueryParams = 1
48
+ }
49
+
50
+ /**
51
+ * Provider that handles API Key authentication
52
+ *
53
+ * @beta
54
+ */
55
+ export declare class ApiKeyProvider implements AuthProvider {
56
+ private keyName;
57
+ private keyValue;
58
+ private keyLocation;
59
+ /**
60
+ *
61
+ * @param { string } keyName - The name of request header or query parameter that specifies API Key
62
+ * @param { string } keyValue - The value of API Key
63
+ * @param { ApiKeyLocation } keyLocation - The location of API Key: request header or query parameter.
64
+ *
65
+ * @throws {@link ErrorCode|InvalidParameter} - when key name or key value is empty.
66
+ *
67
+ * @beta
68
+ */
69
+ constructor(keyName: string, keyValue: string, keyLocation: ApiKeyLocation);
70
+ /**
71
+ * Adds authentication info to http requests
72
+ *
73
+ * @param { AxiosRequestConfig } config - Contains all the request information and can be updated to include extra authentication info.
74
+ * Refer https://axios-http.com/docs/req_config for detailed document.
75
+ *
76
+ * @returns Updated axios request config.
77
+ *
78
+ * @throws {@link ErrorCode|AuthorizationInfoAlreadyExists} - when API key already exists in request header or url query parameter.
79
+ *
80
+ * @beta
81
+ */
82
+ AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
83
+ }
27
84
 
28
85
  /**
29
86
  * Represent Microsoft 365 tenant identity, and it is usually used when user is not involved like time-triggered automation job.
@@ -148,7 +205,7 @@ export declare interface AuthProvider {
148
205
  /**
149
206
  * Adds authentication info to http requests
150
207
  *
151
- * @param config - Contains all the request information and can be updated to include extra authentication info.
208
+ * @param { AxiosRequestConfig } config - Contains all the request information and can be updated to include extra authentication info.
152
209
  * Refer https://axios-http.com/docs/req_config for detailed document.
153
210
  *
154
211
  * @beta
@@ -156,6 +213,41 @@ export declare interface AuthProvider {
156
213
  AddAuthenticationInfo: (config: AxiosRequestConfig) => Promise<AxiosRequestConfig>;
157
214
  }
158
215
 
216
+ export { AxiosInstance }
217
+
218
+ /**
219
+ * Provider that handles Basic authentication
220
+ *
221
+ * @beta
222
+ */
223
+ export declare class BasicAuthProvider implements AuthProvider {
224
+ private userName;
225
+ private password;
226
+ /**
227
+ *
228
+ * @param { string } userName - Username used in basic auth
229
+ * @param { string } password - Password used in basic auth
230
+ *
231
+ * @throws {@link ErrorCode|InvalidParameter} - when username or password is empty.
232
+ *
233
+ * @beta
234
+ */
235
+ constructor(userName: string, password: string);
236
+ /**
237
+ * Adds authentication info to http requests
238
+ *
239
+ * @param { AxiosRequestConfig } config - Contains all the request information and can be updated to include extra authentication info.
240
+ * Refer https://axios-http.com/docs/req_config for detailed document.
241
+ *
242
+ * @returns Updated axios request config.
243
+ *
244
+ * @throws {@link ErrorCode|AuthorizationInfoAlreadyExists} - when Authorization header or auth property already exists in request configuration.
245
+ *
246
+ * @beta
247
+ */
248
+ AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
249
+ }
250
+
159
251
  /**
160
252
  * Provider that handles Bearer Token authentication
161
253
  *
@@ -164,7 +256,7 @@ export declare interface AuthProvider {
164
256
  export declare class BearerTokenAuthProvider implements AuthProvider {
165
257
  private getToken;
166
258
  /**
167
- * @param getToken Function that returns the content of bearer token used in http request
259
+ * @param { () => Promise<string> } getToken - Function that returns the content of bearer token used in http request
168
260
  *
169
261
  * @beta
170
262
  */
@@ -172,9 +264,44 @@ export declare class BearerTokenAuthProvider implements AuthProvider {
172
264
  /**
173
265
  * Adds authentication info to http requests
174
266
  *
175
- * @param config - Contains all the request information and can be updated to include extra authentication info.
267
+ * @param { AxiosRequestConfig } config - Contains all the request information and can be updated to include extra authentication info.
268
+ * Refer https://axios-http.com/docs/req_config for detailed document.
269
+ *
270
+ * @returns Updated axios request config.
271
+ *
272
+ * @throws {@link ErrorCode|AuthorizationInfoAlreadyExists} - when Authorization header already exists in request configuration.
273
+ *
274
+ * @beta
275
+ */
276
+ AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
277
+ }
278
+
279
+ /**
280
+ * Provider that handles Certificate authentication
281
+ *
282
+ * @beta
283
+ */
284
+ export declare class CertificateAuthProvider implements AuthProvider {
285
+ private certOption;
286
+ /**
287
+ *
288
+ * @param { SecureContextOptions } certOption - information about the cert used in http requests
289
+ *
290
+ * @throws {@link ErrorCode|InvalidParameter} - when cert option is empty.
291
+ *
292
+ * @beta
293
+ */
294
+ constructor(certOption: SecureContextOptions);
295
+ /**
296
+ * Adds authentication info to http requests.
297
+ *
298
+ * @param { AxiosRequestConfig } config - Contains all the request information and can be updated to include extra authentication info.
176
299
  * Refer https://axios-http.com/docs/req_config for detailed document.
177
300
  *
301
+ * @returns Updated axios request config.
302
+ *
303
+ * @throws {@link ErrorCode|InvalidParameter} - when custom httpsAgent in the request has duplicate properties with certOption provided in constructor.
304
+ *
178
305
  * @beta
179
306
  */
180
307
  AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
@@ -290,7 +417,7 @@ export declare interface CommandMessage {
290
417
  */
291
418
  text: string;
292
419
  /**
293
- * The capture groups that matched to the {@link triggerPatterns} in a {@link TeamsFxBotCommandHandler} instance.
420
+ * The capture groups that matched to the {@link TriggerPatterns} in a {@link TeamsFxBotCommandHandler} instance.
294
421
  */
295
422
  matches?: RegExpMatchArray;
296
423
  }
@@ -312,7 +439,7 @@ export declare interface CommandOptions {
312
439
  /**
313
440
  * Provide utilities for bot conversation, including:
314
441
  * - handle command and response.
315
- * - send notification to varies targets (e.g., member, channel, incoming wehbook).
442
+ * - send notification to varies targets (e.g., member, group, channel).
316
443
  *
317
444
  * @example
318
445
  * For command and response, you can register your commands through the constructor, or use the `registerCommand` and `registerCommands` API to add commands later.
@@ -322,9 +449,7 @@ export declare interface CommandOptions {
322
449
  * const conversationBot = new ConversationBot({
323
450
  * command: {
324
451
  * enabled: true,
325
- * options: {
326
- * commands: [ new HelloWorldCommandHandler() ],
327
- * },
452
+ * commands: [ new HelloWorldCommandHandler() ],
328
453
  * },
329
454
  * });
330
455
  *
@@ -332,7 +457,7 @@ export declare interface CommandOptions {
332
457
  * conversationBot.command.registerCommand(new HelpCommandHandler());
333
458
  * ```
334
459
  *
335
- * For notification, you can enable notification at initialization, then send notificaations at any time.
460
+ * For notification, you can enable notification at initialization, then send notifications at any time.
336
461
  *
337
462
  * ```typescript
338
463
  * // enable through constructor
@@ -360,7 +485,7 @@ export declare interface CommandOptions {
360
485
  *
361
486
  * 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.
362
487
  *
363
- * For notification, set `notification.options.storage` in {@link ConversationOptions} to use your own storage implementation.
488
+ * For notification, set `notification.storage` in {@link ConversationOptions} to use your own storage implementation.
364
489
  *
365
490
  * @beta
366
491
  */
@@ -386,11 +511,39 @@ export declare class ConversationBot {
386
511
  /**
387
512
  * Creates new instance of the `ConversationBot`.
388
513
  *
514
+ * @remarks
515
+ * It's recommended to create your own adapter and storage for production environment instead of the default one.
516
+ *
389
517
  * @param options - initialize options
390
518
  *
391
519
  * @beta
392
520
  */
393
521
  constructor(options: ConversationOptions);
522
+ private createDefaultAdapter;
523
+ /**
524
+ * The request handler to integrate with web request.
525
+ *
526
+ * @param req - an Express or Restify style request object.
527
+ * @param res - an Express or Restify style response object.
528
+ * @param logic - the additional function to handle bot context.
529
+ *
530
+ * @example
531
+ * For example, to use with Restify:
532
+ * ``` typescript
533
+ * // The default/empty behavior
534
+ * server.post("api/messages", conversationBot.requestHandler);
535
+ *
536
+ * // Or, add your own logic
537
+ * server.post("api/messages", async (req, res) => {
538
+ * await conversationBot.requestHandler(req, res, async (context) => {
539
+ * // your-own-context-logic
540
+ * });
541
+ * });
542
+ * ```
543
+ *
544
+ * @beta
545
+ */
546
+ requestHandler(req: WebRequest, res: WebResponse, logic?: (context: TurnContext_2) => Promise<any>): Promise<void>;
394
547
  }
395
548
 
396
549
  /**
@@ -400,48 +553,52 @@ export declare class ConversationBot {
400
553
  */
401
554
  export declare interface ConversationOptions {
402
555
  /**
403
- * The bot adapter. If not provided, a default adapter will be created with BOT_ID and BOT_PASSWORD from environment variables.
556
+ * The bot adapter. If not provided, a default adapter will be created:
557
+ * - with `adapterConfig` as constructor parameter.
558
+ * - with a default error handler that logs error to console, sends trace activity, and sends error message to user.
559
+ *
560
+ * @remarks
561
+ * If neither `adapter` nor `adapterConfig` is provided, will use BOT_ID and BOT_PASSWORD from environment variables.
404
562
  *
405
563
  * @beta
406
564
  */
407
565
  adapter?: BotFrameworkAdapter;
566
+ /**
567
+ * If `adapter` is not provided, this `adapterConfig` will be passed to the new `BotFrameworkAdapter` when created internally.
568
+ *
569
+ * @remarks
570
+ * If neither `adapter` nor `adapterConfig` is provided, will use BOT_ID and BOT_PASSWORD from environment variables.
571
+ *
572
+ * @beta
573
+ */
574
+ adapterConfig?: {
575
+ [key: string]: unknown;
576
+ };
408
577
  /**
409
578
  * The command part.
410
579
  *
411
580
  * @beta
412
581
  */
413
- command: {
582
+ command?: CommandOptions & {
414
583
  /**
415
584
  * Whether to enable command or not.
416
585
  *
417
586
  * @beta
418
587
  */
419
- enabled: boolean;
420
- /**
421
- * The command options if command is enabled.
422
- *
423
- * @beta
424
- */
425
- options: CommandOptions;
588
+ enabled?: boolean;
426
589
  };
427
590
  /**
428
591
  * The notification part.
429
592
  *
430
593
  * @beta
431
594
  */
432
- notification: {
595
+ notification?: NotificationOptions_2 & {
433
596
  /**
434
597
  * Whether to enable notification or not.
435
598
  *
436
599
  * @beta
437
600
  */
438
- enabled: boolean;
439
- /**
440
- * The notification options if notification is enabled.
441
- *
442
- * @beta
443
- */
444
- options: NotificationOptions_2;
601
+ enabled?: boolean;
445
602
  };
446
603
  }
447
604
 
@@ -515,1251 +672,1283 @@ export declare function createApiClient(apiEndpoint: string, authProvider: AuthP
515
672
  export declare function createMicrosoftGraphClient(teamsfx: TeamsFxConfiguration, scopes?: string | string[]): Client;
516
673
 
517
674
  /**
518
- * Error code to trace the error types.
519
- * @beta
520
- */
521
- export declare enum ErrorCode {
522
- /**
523
- * Invalid parameter error.
524
- */
525
- InvalidParameter = "InvalidParameter",
526
- /**
527
- * Invalid configuration error.
528
- */
529
- InvalidConfiguration = "InvalidConfiguration",
530
- /**
531
- * Invalid certificate error.
532
- */
533
- InvalidCertificate = "InvalidCertificate",
534
- /**
535
- * Internal error.
536
- */
537
- InternalError = "InternalError",
538
- /**
539
- * Channel is not supported error.
540
- */
541
- ChannelNotSupported = "ChannelNotSupported",
542
- /**
543
- * Runtime is not supported error.
544
- */
545
- RuntimeNotSupported = "RuntimeNotSupported",
546
- /**
547
- * User failed to finish the AAD consent flow failed.
548
- */
549
- ConsentFailed = "ConsentFailed",
550
- /**
551
- * The user or administrator has not consented to use the application error.
552
- */
553
- UiRequiredError = "UiRequiredError",
554
- /**
555
- * Token is not within its valid time range error.
556
- */
557
- TokenExpiredError = "TokenExpiredError",
558
- /**
559
- * Call service (AAD or simple authentication server) failed.
560
- */
561
- ServiceError = "ServiceError",
562
- /**
563
- * Operation failed.
564
- */
565
- FailedOperation = "FailedOperation",
566
- /**
567
- * Invalid response error.
568
- */
569
- InvalidResponse = "InvalidResponse",
570
- /**
571
- * Identity type error.
572
- */
573
- IdentityTypeNotSupported = "IdentityTypeNotSupported"
574
- }
575
-
576
- /**
577
- * Error class with code and message thrown by the SDK.
675
+ * Helper to create SecureContextOptions from PEM format cert
578
676
  *
579
- * @beta
580
- */
581
- export declare class ErrorWithCode extends Error {
582
- /**
583
- * Error code
677
+ * @param { string | Buffer } cert - The cert chain in PEM format
678
+ * @param { string | Buffer } key - The private key for the cert chain
679
+ * @param { string? } passphrase - The passphrase for private key
680
+ * @param { string? | Buffer? } ca - Overrides the trusted CA certificates
584
681
  *
585
- * @readonly
586
- */
587
- code: string | undefined;
588
- /**
589
- * Constructor of ErrorWithCode.
682
+ * @returns Instance of SecureContextOptions
590
683
  *
591
- * @param {string} message - error message.
592
- * @param {ErrorCode} code - error code.
684
+ * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
593
685
  *
594
- * @beta
595
686
  */
596
- constructor(message?: string, code?: ErrorCode);
597
- }
687
+ export declare function createPemCertOption(cert: string | Buffer, key: string | Buffer, passphrase?: string, ca?: string | Buffer): SecureContextOptions;
598
688
 
599
- /**
600
- * Get log level.
601
- *
602
- * @returns Log level
603
- *
604
- * @beta
605
- */
606
- export declare function getLogLevel(): LogLevel | undefined;
689
+ /**
690
+ * Helper to create SecureContextOptions from PFX format cert
691
+ *
692
+ * @param { string | Buffer } pfx - The content of .pfx file
693
+ * @param { string? } passphrase - Optional. The passphrase of .pfx file
694
+ *
695
+ * @returns Instance of SecureContextOptions
696
+ *
697
+ * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
698
+ *
699
+ */
700
+ export declare function createPfxCertOption(pfx: string | Buffer, passphrase?: string): SecureContextOptions;
607
701
 
608
- /**
609
- * Generate connection configuration consumed by tedious.
610
- *
611
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth
612
- * @param { string? } databaseName - specify database name to override default one if there are multiple databases.
613
- *
614
- * @returns Connection configuration of tedious for the SQL.
615
- *
616
- * @throws {@link ErrorCode|InvalidConfiguration} when SQL config resource configuration is invalid.
617
- * @throws {@link ErrorCode|InternalError} when get user MSI token failed or MSI token is invalid.
618
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
619
- *
620
- * @beta
621
- */
622
- export declare function getTediousConnectionConfig(teamsfx: TeamsFx, databaseName?: string): Promise<ConnectionConfig>;
702
+ /**
703
+ * Error code to trace the error types.
704
+ * @beta
705
+ */
706
+ export declare enum ErrorCode {
707
+ /**
708
+ * Invalid parameter error.
709
+ */
710
+ InvalidParameter = "InvalidParameter",
711
+ /**
712
+ * Invalid configuration error.
713
+ */
714
+ InvalidConfiguration = "InvalidConfiguration",
715
+ /**
716
+ * Invalid certificate error.
717
+ */
718
+ InvalidCertificate = "InvalidCertificate",
719
+ /**
720
+ * Internal error.
721
+ */
722
+ InternalError = "InternalError",
723
+ /**
724
+ * Channel is not supported error.
725
+ */
726
+ ChannelNotSupported = "ChannelNotSupported",
727
+ /**
728
+ * Runtime is not supported error.
729
+ */
730
+ RuntimeNotSupported = "RuntimeNotSupported",
731
+ /**
732
+ * User failed to finish the AAD consent flow failed.
733
+ */
734
+ ConsentFailed = "ConsentFailed",
735
+ /**
736
+ * The user or administrator has not consented to use the application error.
737
+ */
738
+ UiRequiredError = "UiRequiredError",
739
+ /**
740
+ * Token is not within its valid time range error.
741
+ */
742
+ TokenExpiredError = "TokenExpiredError",
743
+ /**
744
+ * Call service (AAD or simple authentication server) failed.
745
+ */
746
+ ServiceError = "ServiceError",
747
+ /**
748
+ * Operation failed.
749
+ */
750
+ FailedOperation = "FailedOperation",
751
+ /**
752
+ * Invalid response error.
753
+ */
754
+ InvalidResponse = "InvalidResponse",
755
+ /**
756
+ * Identity type error.
757
+ */
758
+ IdentityTypeNotSupported = "IdentityTypeNotSupported",
759
+ /**
760
+ * Authentication info already exists error.
761
+ */
762
+ AuthorizationInfoAlreadyExists = "AuthorizationInfoAlreadyExists"
763
+ }
623
764
 
624
- /**
625
- * Identity type to use in authentication.
626
- *
627
- * @beta
628
- */
629
- export declare enum IdentityType {
630
- /**
631
- * Represents the current user of Teams.
632
- */
633
- User = "User",
634
- /**
635
- * Represents the application itself.
636
- */
637
- App = "Application"
638
- }
765
+ /**
766
+ * Error class with code and message thrown by the SDK.
767
+ *
768
+ * @beta
769
+ */
770
+ export declare class ErrorWithCode extends Error {
771
+ /**
772
+ * Error code
773
+ *
774
+ * @readonly
775
+ */
776
+ code: string | undefined;
777
+ /**
778
+ * Constructor of ErrorWithCode.
779
+ *
780
+ * @param {string} message - error message.
781
+ * @param {ErrorCode} code - error code.
782
+ *
783
+ * @beta
784
+ */
785
+ constructor(message?: string, code?: ErrorCode);
786
+ }
639
787
 
640
- /**
641
- * Log function for customized logging.
642
- *
643
- * @beta
644
- */
645
- export declare type LogFunction = (level: LogLevel, message: string) => void;
788
+ /**
789
+ * Get log level.
790
+ *
791
+ * @returns Log level
792
+ *
793
+ * @beta
794
+ */
795
+ export declare function getLogLevel(): LogLevel | undefined;
646
796
 
647
- /**
648
- * Interface for customized logger.
649
- * @beta
650
- */
651
- export declare interface Logger {
652
- /**
653
- * Writes to error level logging or lower.
654
- */
655
- error(message: string): void;
656
- /**
657
- * Writes to warning level logging or lower.
658
- */
659
- warn(message: string): void;
660
- /**
661
- * Writes to info level logging or lower.
662
- */
663
- info(message: string): void;
664
- /**
665
- * Writes to verbose level logging.
666
- */
667
- verbose(message: string): void;
668
- }
797
+ /**
798
+ * Generate connection configuration consumed by tedious.
799
+ *
800
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth
801
+ * @param { string? } databaseName - specify database name to override default one if there are multiple databases.
802
+ *
803
+ * @returns Connection configuration of tedious for the SQL.
804
+ *
805
+ * @throws {@link ErrorCode|InvalidConfiguration} when SQL config resource configuration is invalid.
806
+ * @throws {@link ErrorCode|InternalError} when get user MSI token failed or MSI token is invalid.
807
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
808
+ *
809
+ * @beta
810
+ */
811
+ export declare function getTediousConnectionConfig(teamsfx: TeamsFx, databaseName?: string): Promise<ConnectionConfig>;
669
812
 
670
- /**
671
- * Log level.
672
- *
673
- * @beta
674
- */
675
- export declare enum LogLevel {
676
- /**
677
- * Show verbose, information, warning and error message.
678
- */
679
- Verbose = 0,
680
- /**
681
- * Show information, warning and error message.
682
- */
683
- Info = 1,
684
- /**
685
- * Show warning and error message.
686
- */
687
- Warn = 2,
688
- /**
689
- * Show error message.
690
- */
691
- Error = 3
692
- }
813
+ /**
814
+ * Identity type to use in authentication.
815
+ *
816
+ * @beta
817
+ */
818
+ export declare enum IdentityType {
819
+ /**
820
+ * Represents the current user of Teams.
821
+ */
822
+ User = "User",
823
+ /**
824
+ * Represents the application itself.
825
+ */
826
+ App = "Application"
827
+ }
693
828
 
694
- /**
695
- * A {@link NotificationTarget} that represents a team member.
696
- *
697
- * @remarks
698
- * It's recommended to get members from {@link TeamsBotInstallation.members()}.
699
- *
700
- * @beta
701
- */
702
- export declare class Member implements NotificationTarget {
703
- /**
704
- * The parent {@link TeamsBotInstallation} where this member is created from.
705
- *
706
- * @beta
707
- */
708
- readonly parent: TeamsBotInstallation;
709
- /**
710
- * Detailed member account information.
711
- *
712
- * @beta
713
- */
714
- readonly account: TeamsChannelAccount;
715
- /**
716
- * Notification target type. For member it's always "Person".
717
- *
718
- * @beta
719
- */
720
- readonly type: NotificationTargetType;
721
- /**
722
- * Constuctor.
723
- *
724
- * @remarks
725
- * It's recommended to get members from {@link TeamsBotInstallation.members()}, instead of using this constructor.
726
- *
727
- * @param parent - The parent {@link TeamsBotInstallation} where this member is created from.
728
- * @param account - Detailed member account information.
729
- *
730
- * @beta
731
- */
732
- constructor(parent: TeamsBotInstallation, account: TeamsChannelAccount);
733
- /**
734
- * Send a plain text message.
735
- *
736
- * @param text - the plain text message.
737
- * @returns A `Promise` representing the asynchronous operation.
738
- *
739
- * @beta
740
- */
741
- sendMessage(text: string): Promise<void>;
742
- /**
743
- * Send an adaptive card message.
744
- *
745
- * @param card - the adaptive card raw JSON.
746
- * @returns A `Promise` representing the asynchronous operation.
747
- *
748
- * @beta
749
- */
750
- sendAdaptiveCard(card: unknown): Promise<void>;
751
- /**
752
- * @internal
753
- */
754
- private newConversation;
755
- }
829
+ /**
830
+ * Log function for customized logging.
831
+ *
832
+ * @beta
833
+ */
834
+ export declare type LogFunction = (level: LogLevel, message: string) => void;
756
835
 
757
- /**
758
- * Provides utility method to build bot message with cards that supported in Teams.
759
- */
760
- export declare class MessageBuilder {
761
- /**
762
- * Build a bot message activity attached with adaptive card.
763
- *
764
- * @param getCardData Function to prepare your card data.
765
- * @param cardTemplate The adaptive card template.
766
- * @returns A bot message activity attached with an adaptive card.
767
- *
768
- * @example
769
- * ```javascript
770
- * const cardTemplate = {
771
- * type: "AdaptiveCard",
772
- * body: [
773
- * {
774
- * "type": "TextBlock",
775
- * "text": "${title}",
776
- * "size": "Large"
777
- * },
778
- * {
779
- * "type": "TextBlock",
780
- * "text": "${description}"
781
- * }],
782
- * $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
783
- * version: "1.4"
784
- * };
785
- *
786
- * type CardData = {
787
- * title: string,
788
- * description: string
789
- * };
790
- * const card = MessageBuilder.attachAdaptiveCard<CardData>(() => {
791
- * return {
792
- * title: "sample card title",
793
- * description: "sample card description"
794
- * }}, cardTemplate);
795
- * ```
796
- *
797
- * @beta
798
- */
799
- static attachAdaptiveCard<TData>(getCardData: () => TData, cardTemplate: any): Partial<Activity_2>;
800
- /**
801
- * Build a bot message activity attached with an adaptive card.
802
- *
803
- * @param card The adaptive card content.
804
- * @returns A bot message activity attached with an adaptive card.
805
- *
806
- * @beta
807
- */
808
- static attachAdaptiveCardWithoutData(card: any): Partial<Activity_2>;
809
- /**
810
- * Build a bot message activity attached with an hero card.
811
- *
812
- * @param title The card title.
813
- * @param images Optional. The array of images to include on the card.
814
- * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
815
- * is converted to an `imBack` button with a title and value set to the value of the string.
816
- * @param other Optional. Any additional properties to include on the card.
817
- *
818
- * @returns A bot message activity attached with a hero card.
819
- *
820
- * @example
821
- * ```javascript
822
- * const message = MessageBuilder.attachHeroCard(
823
- * 'sample title',
824
- * ['https://example.com/sample.jpg'],
825
- * ['action']
826
- * );
827
- * ```
828
- *
829
- * @beta
830
- */
831
- static attachHeroCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<HeroCard>): Partial<Activity_2>;
832
- /**
833
- * Returns an attachment for a sign-in card.
834
- *
835
- * @param title The title for the card's sign-in button.
836
- * @param url The URL of the sign-in page to use.
837
- * @param text Optional. Additional text to include on the card.
838
- *
839
- * @returns A bot message activity attached with a sign-in card.
840
- *
841
- * @remarks
842
- * For channels that don't natively support sign-in cards, an alternative message is rendered.
843
- *
844
- * @beta
845
- */
846
- static attachSigninCard(title: string, url: string, text?: string): Partial<Activity_2>;
847
- /**
848
- * Build a bot message activity attached with an Office 365 connector card.
849
- *
850
- * @param card A description of the Office 365 connector card.
851
- * @returns A bot message activity attached with an Office 365 connector card.
852
- *
853
- * @beta
854
- */
855
- static attachO365ConnectorCard(card: O365ConnectorCard): Partial<Activity_2>;
856
- /**
857
- * Build a message activity attached with a receipt card.
858
- * @param card A description of the receipt card.
859
- * @returns A message activity attached with a receipt card.
860
- *
861
- * @beta
862
- */
863
- static AttachReceiptCard(card: ReceiptCard): Partial<Activity_2>;
864
- /**
865
- *
866
- * @param title The card title.
867
- * @param images Optional. The array of images to include on the card.
868
- * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
869
- * is converted to an `imBack` button with a title and value set to the value of the string.
870
- * @param other Optional. Any additional properties to include on the card.
871
- * @returns A message activity attached with a thumbnail card
872
- *
873
- * @beta
874
- */
875
- static attachThumbnailCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<ThumbnailCard>): Partial<Activity_2>;
876
- /**
877
- * Add an attachement to a bot activity.
878
- * @param attachement The attachment object to attach.
879
- * @returns A message activity with an attachment.
880
- *
881
- * @beta
882
- */
883
- static attachContent(attachement: Attachment): Partial<Activity_2>;
884
- }
836
+ /**
837
+ * Interface for customized logger.
838
+ * @beta
839
+ */
840
+ export declare interface Logger {
841
+ /**
842
+ * Writes to error level logging or lower.
843
+ */
844
+ error(message: string): void;
845
+ /**
846
+ * Writes to warning level logging or lower.
847
+ */
848
+ warn(message: string): void;
849
+ /**
850
+ * Writes to info level logging or lower.
851
+ */
852
+ info(message: string): void;
853
+ /**
854
+ * Writes to verbose level logging.
855
+ */
856
+ verbose(message: string): void;
857
+ }
885
858
 
886
- /**
887
- * Microsoft Graph auth provider for Teams Framework
888
- *
889
- * @beta
890
- */
891
- export declare class MsGraphAuthProvider implements AuthenticationProvider {
892
- private teamsfx;
893
- private scopes;
894
- /**
895
- * Constructor of MsGraphAuthProvider.
896
- *
897
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth.
898
- * @param {string | string[]} scopes - The list of scopes for which the token will have access.
899
- *
900
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
901
- *
902
- * @returns An instance of MsGraphAuthProvider.
903
- *
904
- * @beta
905
- */
906
- constructor(teamsfx: TeamsFxConfiguration, scopes?: string | string[]);
907
- /**
908
- * Get access token for Microsoft Graph API requests.
909
- *
910
- * @throws {@link ErrorCode|InternalError} when get access token failed due to empty token or unknown other problems.
911
- * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
912
- * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
913
- * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth or AAD server.
914
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
915
- *
916
- * @returns Access token from the credential.
917
- *
918
- */
919
- getAccessToken(): Promise<string>;
920
- }
859
+ /**
860
+ * Log level.
861
+ *
862
+ * @beta
863
+ */
864
+ export declare enum LogLevel {
865
+ /**
866
+ * Show verbose, information, warning and error message.
867
+ */
868
+ Verbose = 0,
869
+ /**
870
+ * Show information, warning and error message.
871
+ */
872
+ Info = 1,
873
+ /**
874
+ * Show warning and error message.
875
+ */
876
+ Warn = 2,
877
+ /**
878
+ * Show error message.
879
+ */
880
+ Error = 3
881
+ }
921
882
 
922
- /**
923
- * Provide utilities to send notification to varies targets (e.g., member, channel, incoming wehbook).
924
- *
925
- * @beta
926
- */
927
- export declare class NotificationBot {
928
- private readonly conversationReferenceStore;
929
- private readonly adapter;
930
- /**
931
- * constructor of the notification bot.
932
- *
933
- * @remarks
934
- * To ensure accuracy, it's recommended to initialize before handling any message.
935
- *
936
- * @param adapter - the bound `BotFrameworkAdapter`
937
- * @param options - initialize options
938
- *
939
- * @beta
940
- */
941
- constructor(adapter: BotFrameworkAdapter, options?: NotificationOptions_2);
942
- /**
943
- * Get all targets where the bot is installed.
944
- *
945
- * @remarks
946
- * The result is retrieving from the persisted storage.
947
- *
948
- * @returns - an array of {@link TeamsBotInstallation}.
949
- *
950
- * @beta
951
- */
952
- installations(): Promise<TeamsBotInstallation[]>;
953
- }
883
+ /**
884
+ * A {@link NotificationTarget} that represents a team member.
885
+ *
886
+ * @remarks
887
+ * It's recommended to get members from {@link TeamsBotInstallation.members()}.
888
+ *
889
+ * @beta
890
+ */
891
+ export declare class Member implements NotificationTarget {
892
+ /**
893
+ * The parent {@link TeamsBotInstallation} where this member is created from.
894
+ *
895
+ * @beta
896
+ */
897
+ readonly parent: TeamsBotInstallation;
898
+ /**
899
+ * Detailed member account information.
900
+ *
901
+ * @beta
902
+ */
903
+ readonly account: TeamsChannelAccount;
904
+ /**
905
+ * Notification target type. For member it's always "Person".
906
+ *
907
+ * @beta
908
+ */
909
+ readonly type: NotificationTargetType;
910
+ /**
911
+ * Constuctor.
912
+ *
913
+ * @remarks
914
+ * It's recommended to get members from {@link TeamsBotInstallation.members()}, instead of using this constructor.
915
+ *
916
+ * @param parent - The parent {@link TeamsBotInstallation} where this member is created from.
917
+ * @param account - Detailed member account information.
918
+ *
919
+ * @beta
920
+ */
921
+ constructor(parent: TeamsBotInstallation, account: TeamsChannelAccount);
922
+ /**
923
+ * Send a plain text message.
924
+ *
925
+ * @param text - the plain text message.
926
+ * @returns A `Promise` representing the asynchronous operation.
927
+ *
928
+ * @beta
929
+ */
930
+ sendMessage(text: string): Promise<void>;
931
+ /**
932
+ * Send an adaptive card message.
933
+ *
934
+ * @param card - the adaptive card raw JSON.
935
+ * @returns A `Promise` representing the asynchronous operation.
936
+ *
937
+ * @beta
938
+ */
939
+ sendAdaptiveCard(card: unknown): Promise<void>;
940
+ /**
941
+ * @internal
942
+ */
943
+ private newConversation;
944
+ }
954
945
 
955
- /**
956
- * Options to initialize {@link NotificationBot}.
957
- *
958
- * @beta
959
- */
960
- declare interface NotificationOptions_2 {
961
- /**
962
- * An optional storage to persist bot notification connections.
963
- *
964
- * @remarks
965
- * If `storage` is not provided, a default local file storage will be used,
966
- * which stores notification connections into:
967
- * - ".notification.localstore.json" if running locally
968
- * - "${process.env.TEMP}/.notification.localstore.json" if `process.env.RUNNING_ON_AZURE` is set to "1"
969
- *
970
- * It's recommended to use your own shared storage for production environment.
971
- *
972
- * @beta
973
- */
974
- storage?: NotificationTargetStorage;
975
- }
976
- export { NotificationOptions_2 as NotificationOptions }
946
+ /**
947
+ * Provides utility method to build bot message with cards that supported in Teams.
948
+ */
949
+ export declare class MessageBuilder {
950
+ /**
951
+ * Build a bot message activity attached with adaptive card.
952
+ *
953
+ * @param cardTemplate The adaptive card template.
954
+ * @param data card data used to render the template.
955
+ * @returns A bot message activity attached with an adaptive card.
956
+ *
957
+ * @example
958
+ * ```javascript
959
+ * const cardTemplate = {
960
+ * type: "AdaptiveCard",
961
+ * body: [
962
+ * {
963
+ * "type": "TextBlock",
964
+ * "text": "${title}",
965
+ * "size": "Large"
966
+ * },
967
+ * {
968
+ * "type": "TextBlock",
969
+ * "text": "${description}"
970
+ * }],
971
+ * $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
972
+ * version: "1.4"
973
+ * };
974
+ *
975
+ * type CardData = {
976
+ * title: string,
977
+ * description: string
978
+ * };
979
+ * const card = MessageBuilder.attachAdaptiveCard<CardData>(
980
+ * cardTemplate, {
981
+ * title: "sample card title",
982
+ * description: "sample card description"
983
+ * });
984
+ * ```
985
+ *
986
+ * @beta
987
+ */
988
+ static attachAdaptiveCard<TData>(cardTemplate: any, data: TData): Partial<Activity_2>;
989
+ /**
990
+ * Build a bot message activity attached with an adaptive card.
991
+ *
992
+ * @param card The adaptive card content.
993
+ * @returns A bot message activity attached with an adaptive card.
994
+ *
995
+ * @beta
996
+ */
997
+ static attachAdaptiveCardWithoutData(card: any): Partial<Activity_2>;
998
+ /**
999
+ * Build a bot message activity attached with an hero card.
1000
+ *
1001
+ * @param title The card title.
1002
+ * @param images Optional. The array of images to include on the card.
1003
+ * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
1004
+ * is converted to an `imBack` button with a title and value set to the value of the string.
1005
+ * @param other Optional. Any additional properties to include on the card.
1006
+ *
1007
+ * @returns A bot message activity attached with a hero card.
1008
+ *
1009
+ * @example
1010
+ * ```javascript
1011
+ * const message = MessageBuilder.attachHeroCard(
1012
+ * 'sample title',
1013
+ * ['https://example.com/sample.jpg'],
1014
+ * ['action']
1015
+ * );
1016
+ * ```
1017
+ *
1018
+ * @beta
1019
+ */
1020
+ static attachHeroCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<HeroCard>): Partial<Activity_2>;
1021
+ /**
1022
+ * Returns an attachment for a sign-in card.
1023
+ *
1024
+ * @param title The title for the card's sign-in button.
1025
+ * @param url The URL of the sign-in page to use.
1026
+ * @param text Optional. Additional text to include on the card.
1027
+ *
1028
+ * @returns A bot message activity attached with a sign-in card.
1029
+ *
1030
+ * @remarks
1031
+ * For channels that don't natively support sign-in cards, an alternative message is rendered.
1032
+ *
1033
+ * @beta
1034
+ */
1035
+ static attachSigninCard(title: string, url: string, text?: string): Partial<Activity_2>;
1036
+ /**
1037
+ * Build a bot message activity attached with an Office 365 connector card.
1038
+ *
1039
+ * @param card A description of the Office 365 connector card.
1040
+ * @returns A bot message activity attached with an Office 365 connector card.
1041
+ *
1042
+ * @beta
1043
+ */
1044
+ static attachO365ConnectorCard(card: O365ConnectorCard): Partial<Activity_2>;
1045
+ /**
1046
+ * Build a message activity attached with a receipt card.
1047
+ * @param card A description of the receipt card.
1048
+ * @returns A message activity attached with a receipt card.
1049
+ *
1050
+ * @beta
1051
+ */
1052
+ static AttachReceiptCard(card: ReceiptCard): Partial<Activity_2>;
1053
+ /**
1054
+ *
1055
+ * @param title The card title.
1056
+ * @param images Optional. The array of images to include on the card.
1057
+ * @param buttons Optional. The array of buttons to include on the card. Each `string` in the array
1058
+ * is converted to an `imBack` button with a title and value set to the value of the string.
1059
+ * @param other Optional. Any additional properties to include on the card.
1060
+ * @returns A message activity attached with a thumbnail card
1061
+ *
1062
+ * @beta
1063
+ */
1064
+ static attachThumbnailCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<ThumbnailCard>): Partial<Activity_2>;
1065
+ /**
1066
+ * Add an attachement to a bot activity.
1067
+ * @param attachement The attachment object to attach.
1068
+ * @returns A message activity with an attachment.
1069
+ *
1070
+ * @beta
1071
+ */
1072
+ static attachContent(attachement: Attachment): Partial<Activity_2>;
1073
+ }
977
1074
 
978
- /**
979
- * Represent a notification target.
980
- *
981
- * @beta
982
- */
983
- export declare interface NotificationTarget {
984
- /**
985
- * The type of target, could be "Channel" or "Group" or "Person".
986
- *
987
- * @beta
988
- */
989
- readonly type?: NotificationTargetType;
990
- /**
991
- * Send a plain text message.
992
- *
993
- * @param text - the plain text message.
994
- *
995
- * @beta
996
- */
997
- sendMessage(text: string): Promise<void>;
998
- /**
999
- * Send an adaptive card message.
1000
- *
1001
- * @param card - the adaptive card raw JSON.
1002
- *
1003
- * @beta
1004
- */
1005
- sendAdaptiveCard(card: unknown): Promise<void>;
1006
- }
1075
+ /**
1076
+ * Microsoft Graph auth provider for Teams Framework
1077
+ *
1078
+ * @beta
1079
+ */
1080
+ export declare class MsGraphAuthProvider implements AuthenticationProvider {
1081
+ private teamsfx;
1082
+ private scopes;
1083
+ /**
1084
+ * Constructor of MsGraphAuthProvider.
1085
+ *
1086
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth.
1087
+ * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1088
+ *
1089
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1090
+ *
1091
+ * @returns An instance of MsGraphAuthProvider.
1092
+ *
1093
+ * @beta
1094
+ */
1095
+ constructor(teamsfx: TeamsFxConfiguration, scopes?: string | string[]);
1096
+ /**
1097
+ * Get access token for Microsoft Graph API requests.
1098
+ *
1099
+ * @throws {@link ErrorCode|InternalError} when get access token failed due to empty token or unknown other problems.
1100
+ * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1101
+ * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1102
+ * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth or AAD server.
1103
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1104
+ *
1105
+ * @returns Access token from the credential.
1106
+ *
1107
+ */
1108
+ getAccessToken(): Promise<string>;
1109
+ }
1007
1110
 
1008
- /**
1009
- * Interface for a storage provider that stores and retrieves notification target references.
1010
- *
1011
- * @beta
1012
- */
1013
- export declare interface NotificationTargetStorage {
1014
- /**
1015
- * Read one notification target by its key.
1016
- *
1017
- * @param key - the key of a notification target.
1018
- *
1019
- * @returns - the notification target. Or undefined if not found.
1020
- *
1021
- * @beta
1022
- */
1023
- read(key: string): Promise<{
1024
- [key: string]: unknown;
1025
- } | undefined>;
1026
- /**
1027
- * List all stored notification targets.
1028
- *
1029
- * @returns - an array of notification target. Or an empty array if nothing is stored.
1030
- *
1031
- * @beta
1032
- */
1033
- list(): Promise<{
1034
- [key: string]: unknown;
1035
- }[]>;
1036
- /**
1037
- * Write one notification target by its key.
1038
- *
1039
- * @param key - the key of a notification target.
1040
- * @param object - the notification target.
1041
- *
1042
- * @beta
1043
- */
1044
- write(key: string, object: {
1045
- [key: string]: unknown;
1046
- }): Promise<void>;
1047
- /**
1048
- * Delete one notificaton target by its key.
1049
- *
1050
- * @param key - the key of a notification target.
1051
- *
1052
- * @beta
1053
- */
1054
- delete(key: string): Promise<void>;
1055
- }
1111
+ /**
1112
+ * Provide utilities to send notification to varies targets (e.g., member, group, channel).
1113
+ *
1114
+ * @beta
1115
+ */
1116
+ export declare class NotificationBot {
1117
+ private readonly conversationReferenceStore;
1118
+ private readonly adapter;
1119
+ /**
1120
+ * constructor of the notification bot.
1121
+ *
1122
+ * @remarks
1123
+ * To ensure accuracy, it's recommended to initialize before handling any message.
1124
+ *
1125
+ * @param adapter - the bound `BotFrameworkAdapter`
1126
+ * @param options - initialize options
1127
+ *
1128
+ * @beta
1129
+ */
1130
+ constructor(adapter: BotFrameworkAdapter, options?: NotificationOptions_2);
1131
+ /**
1132
+ * Get all targets where the bot is installed.
1133
+ *
1134
+ * @remarks
1135
+ * The result is retrieving from the persisted storage.
1136
+ *
1137
+ * @returns - an array of {@link TeamsBotInstallation}.
1138
+ *
1139
+ * @beta
1140
+ */
1141
+ installations(): Promise<TeamsBotInstallation[]>;
1142
+ }
1056
1143
 
1057
- /**
1058
- * The target type where the notification will be sent to.
1059
- *
1060
- * @remarks
1061
- * - "Channel" means to a team channel. (By default, notification to a team will be sent to its "General" channel.)
1062
- * - "Group" means to a group chat.
1063
- * - "Person" means to a personal chat.
1064
- *
1065
- * @beta
1066
- */
1067
- export declare type NotificationTargetType = "Channel" | "Group" | "Person";
1144
+ /**
1145
+ * Options to initialize {@link NotificationBot}.
1146
+ *
1147
+ * @beta
1148
+ */
1149
+ declare interface NotificationOptions_2 {
1150
+ /**
1151
+ * An optional storage to persist bot notification connections.
1152
+ *
1153
+ * @remarks
1154
+ * If `storage` is not provided, a default local file storage will be used,
1155
+ * which stores notification connections into:
1156
+ * - ".notification.localstore.json" if running locally
1157
+ * - "${process.env.TEMP}/.notification.localstore.json" if `process.env.RUNNING_ON_AZURE` is set to "1"
1158
+ *
1159
+ * It's recommended to use your own shared storage for production environment.
1160
+ *
1161
+ * @beta
1162
+ */
1163
+ storage?: NotificationTargetStorage;
1164
+ }
1165
+ export { NotificationOptions_2 as NotificationOptions }
1068
1166
 
1069
- /**
1070
- * Represent on-behalf-of flow to get user identity, and it is designed to be used in server side.
1071
- *
1072
- * @example
1073
- * ```typescript
1074
- * const credential = new OnBehalfOfUserCredential(ssoToken);
1075
- * ```
1076
- *
1077
- * @remarks
1078
- * Can only be used in server side.
1079
- *
1080
- * @beta
1081
- */
1082
- export declare class OnBehalfOfUserCredential implements TokenCredential {
1083
- private msalClient;
1084
- private ssoToken;
1085
- /**
1086
- * Constructor of OnBehalfOfUserCredential
1087
- *
1088
- * @remarks
1089
- * Only works in in server side.
1090
- *
1091
- * @param {string} ssoToken - User token provided by Teams SSO feature.
1092
- * @param {AuthenticationConfiguration} config - The authentication configuration. Use environment variables if not provided.
1093
- *
1094
- * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret, certificate content, authority host or tenant id is not found in config.
1095
- * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1096
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1097
- *
1098
- * @beta
1099
- */
1100
- constructor(ssoToken: string, config: AuthenticationConfiguration);
1101
- /**
1102
- * Get access token from credential.
1103
- *
1104
- * @example
1105
- * ```typescript
1106
- * await credential.getToken([]) // Get SSO token using empty string array
1107
- * await credential.getToken("") // Get SSO token using empty string
1108
- * await credential.getToken([".default"]) // Get Graph access token with default scope using string array
1109
- * await credential.getToken(".default") // Get Graph access token with default scope using string
1110
- * await credential.getToken(["User.Read"]) // Get Graph access token for single scope using string array
1111
- * await credential.getToken("User.Read") // Get Graph access token for single scope using string
1112
- * await credential.getToken(["User.Read", "Application.Read.All"]) // Get Graph access token for multiple scopes using string array
1113
- * await credential.getToken("User.Read Application.Read.All") // Get Graph access token for multiple scopes using space-separated string
1114
- * await credential.getToken("https://graph.microsoft.com/User.Read") // Get Graph access token with full resource URI
1115
- * await credential.getToken(["https://outlook.office.com/Mail.Read"]) // Get Outlook access token
1116
- * ```
1117
- *
1118
- * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1119
- * @param {GetTokenOptions} options - The options used to configure any requests this TokenCredential implementation might make.
1120
- *
1121
- * @throws {@link ErrorCode|InternalError} when failed to acquire access token on behalf of user with unknown error.
1122
- * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1123
- * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1124
- * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth server.
1125
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1126
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1127
- *
1128
- * @returns Access token with expected scopes.
1129
- *
1130
- * @remarks
1131
- * If scopes is empty string or array, it returns SSO token.
1132
- * If scopes is non-empty, it returns access token for target scope.
1133
- *
1134
- * @beta
1135
- */
1136
- getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1137
- /**
1138
- * Get basic user info from SSO token.
1139
- *
1140
- * @example
1141
- * ```typescript
1142
- * const currentUser = getUserInfo();
1143
- * ```
1144
- *
1145
- * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1146
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1147
- *
1148
- * @returns Basic user info with user displayName, objectId and preferredUserName.
1149
- *
1150
- * @beta
1151
- */
1152
- getUserInfo(): UserInfo;
1153
- private generateAuthServerError;
1154
- }
1167
+ /**
1168
+ * Represent a notification target.
1169
+ *
1170
+ * @beta
1171
+ */
1172
+ export declare interface NotificationTarget {
1173
+ /**
1174
+ * The type of target, could be "Channel" or "Group" or "Person".
1175
+ *
1176
+ * @beta
1177
+ */
1178
+ readonly type?: NotificationTargetType;
1179
+ /**
1180
+ * Send a plain text message.
1181
+ *
1182
+ * @param text - the plain text message.
1183
+ *
1184
+ * @beta
1185
+ */
1186
+ sendMessage(text: string): Promise<void>;
1187
+ /**
1188
+ * Send an adaptive card message.
1189
+ *
1190
+ * @param card - the adaptive card raw JSON.
1191
+ *
1192
+ * @beta
1193
+ */
1194
+ sendAdaptiveCard(card: unknown): Promise<void>;
1195
+ }
1155
1196
 
1156
- /**
1157
- * Send an adaptive card message to a notification target.
1158
- *
1159
- * @param target - the notification target.
1160
- * @param card - the adaptive card raw JSON.
1161
- * @returns A `Promise` representing the asynchronous operation.
1162
- *
1163
- * @beta
1164
- */
1165
- export declare function sendAdaptiveCard(target: NotificationTarget, card: unknown): Promise<void>;
1197
+ /**
1198
+ * Interface for a storage provider that stores and retrieves notification target references.
1199
+ *
1200
+ * @beta
1201
+ */
1202
+ export declare interface NotificationTargetStorage {
1203
+ /**
1204
+ * Read one notification target by its key.
1205
+ *
1206
+ * @param key - the key of a notification target.
1207
+ *
1208
+ * @returns - the notification target. Or undefined if not found.
1209
+ *
1210
+ * @beta
1211
+ */
1212
+ read(key: string): Promise<{
1213
+ [key: string]: unknown;
1214
+ } | undefined>;
1215
+ /**
1216
+ * List all stored notification targets.
1217
+ *
1218
+ * @returns - an array of notification target. Or an empty array if nothing is stored.
1219
+ *
1220
+ * @beta
1221
+ */
1222
+ list(): Promise<{
1223
+ [key: string]: unknown;
1224
+ }[]>;
1225
+ /**
1226
+ * Write one notification target by its key.
1227
+ *
1228
+ * @param key - the key of a notification target.
1229
+ * @param object - the notification target.
1230
+ *
1231
+ * @beta
1232
+ */
1233
+ write(key: string, object: {
1234
+ [key: string]: unknown;
1235
+ }): Promise<void>;
1236
+ /**
1237
+ * Delete one notificaton target by its key.
1238
+ *
1239
+ * @param key - the key of a notification target.
1240
+ *
1241
+ * @beta
1242
+ */
1243
+ delete(key: string): Promise<void>;
1244
+ }
1166
1245
 
1167
- /**
1168
- * Send a plain text message to a notification target.
1169
- *
1170
- * @param target - the notification target.
1171
- * @param text - the plain text message.
1172
- * @returns A `Promise` representing the asynchronous operation.
1173
- *
1174
- * @beta
1175
- */
1176
- export declare function sendMessage(target: NotificationTarget, text: string): Promise<void>;
1246
+ /**
1247
+ * The target type where the notification will be sent to.
1248
+ *
1249
+ * @remarks
1250
+ * - "Channel" means to a team channel. (By default, notification to a team will be sent to its "General" channel.)
1251
+ * - "Group" means to a group chat.
1252
+ * - "Person" means to a personal chat.
1253
+ *
1254
+ * @beta
1255
+ */
1256
+ export declare type NotificationTargetType = "Channel" | "Group" | "Person";
1177
1257
 
1178
- /**
1179
- * Set custom log function. Use the function if it's set. Priority is lower than setLogger.
1180
- *
1181
- * @param {LogFunction} logFunction - custom log function. If it's undefined, custom log function will be cleared.
1182
- *
1183
- * @example
1184
- * ```typescript
1185
- * setLogFunction((level: LogLevel, message: string) => {
1186
- * if (level === LogLevel.Error) {
1187
- * console.log(message);
1188
- * }
1189
- * });
1190
- * ```
1191
- *
1192
- * @beta
1193
- */
1194
- export declare function setLogFunction(logFunction?: LogFunction): void;
1258
+ /**
1259
+ * Represent on-behalf-of flow to get user identity, and it is designed to be used in server side.
1260
+ *
1261
+ * @example
1262
+ * ```typescript
1263
+ * const credential = new OnBehalfOfUserCredential(ssoToken);
1264
+ * ```
1265
+ *
1266
+ * @remarks
1267
+ * Can only be used in server side.
1268
+ *
1269
+ * @beta
1270
+ */
1271
+ export declare class OnBehalfOfUserCredential implements TokenCredential {
1272
+ private msalClient;
1273
+ private ssoToken;
1274
+ /**
1275
+ * Constructor of OnBehalfOfUserCredential
1276
+ *
1277
+ * @remarks
1278
+ * Only works in in server side.
1279
+ *
1280
+ * @param {string} ssoToken - User token provided by Teams SSO feature.
1281
+ * @param {AuthenticationConfiguration} config - The authentication configuration. Use environment variables if not provided.
1282
+ *
1283
+ * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret, certificate content, authority host or tenant id is not found in config.
1284
+ * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1285
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1286
+ *
1287
+ * @beta
1288
+ */
1289
+ constructor(ssoToken: string, config: AuthenticationConfiguration);
1290
+ /**
1291
+ * Get access token from credential.
1292
+ *
1293
+ * @example
1294
+ * ```typescript
1295
+ * await credential.getToken([]) // Get SSO token using empty string array
1296
+ * await credential.getToken("") // Get SSO token using empty string
1297
+ * await credential.getToken([".default"]) // Get Graph access token with default scope using string array
1298
+ * await credential.getToken(".default") // Get Graph access token with default scope using string
1299
+ * await credential.getToken(["User.Read"]) // Get Graph access token for single scope using string array
1300
+ * await credential.getToken("User.Read") // Get Graph access token for single scope using string
1301
+ * await credential.getToken(["User.Read", "Application.Read.All"]) // Get Graph access token for multiple scopes using string array
1302
+ * await credential.getToken("User.Read Application.Read.All") // Get Graph access token for multiple scopes using space-separated string
1303
+ * await credential.getToken("https://graph.microsoft.com/User.Read") // Get Graph access token with full resource URI
1304
+ * await credential.getToken(["https://outlook.office.com/Mail.Read"]) // Get Outlook access token
1305
+ * ```
1306
+ *
1307
+ * @param {string | string[]} scopes - The list of scopes for which the token will have access.
1308
+ * @param {GetTokenOptions} options - The options used to configure any requests this TokenCredential implementation might make.
1309
+ *
1310
+ * @throws {@link ErrorCode|InternalError} when failed to acquire access token on behalf of user with unknown error.
1311
+ * @throws {@link ErrorCode|TokenExpiredError} when SSO token has already expired.
1312
+ * @throws {@link ErrorCode|UiRequiredError} when need user consent to get access token.
1313
+ * @throws {@link ErrorCode|ServiceError} when failed to get access token from simple auth server.
1314
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1315
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1316
+ *
1317
+ * @returns Access token with expected scopes.
1318
+ *
1319
+ * @remarks
1320
+ * If scopes is empty string or array, it returns SSO token.
1321
+ * If scopes is non-empty, it returns access token for target scope.
1322
+ *
1323
+ * @beta
1324
+ */
1325
+ getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1326
+ /**
1327
+ * Get basic user info from SSO token.
1328
+ *
1329
+ * @example
1330
+ * ```typescript
1331
+ * const currentUser = getUserInfo();
1332
+ * ```
1333
+ *
1334
+ * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
1335
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1336
+ *
1337
+ * @returns Basic user info with user displayName, objectId and preferredUserName.
1338
+ *
1339
+ * @beta
1340
+ */
1341
+ getUserInfo(): UserInfo;
1342
+ private generateAuthServerError;
1343
+ }
1195
1344
 
1196
- /**
1197
- * Set custom logger. Use the output functions if it's set. Priority is higher than setLogFunction.
1198
- *
1199
- * @param {Logger} logger - custom logger. If it's undefined, custom logger will be cleared.
1200
- *
1201
- * @example
1202
- * ```typescript
1203
- * setLogger({
1204
- * verbose: console.debug,
1205
- * info: console.info,
1206
- * warn: console.warn,
1207
- * error: console.error,
1208
- * });
1209
- * ```
1210
- *
1211
- * @beta
1212
- */
1213
- export declare function setLogger(logger?: Logger): void;
1345
+ /**
1346
+ * Send an adaptive card message to a notification target.
1347
+ *
1348
+ * @param target - the notification target.
1349
+ * @param card - the adaptive card raw JSON.
1350
+ * @returns A `Promise` representing the asynchronous operation.
1351
+ *
1352
+ * @beta
1353
+ */
1354
+ export declare function sendAdaptiveCard(target: NotificationTarget, card: unknown): Promise<void>;
1214
1355
 
1215
- /**
1216
- * Update log level helper.
1217
- *
1218
- * @param { LogLevel } level - log level in configuration
1219
- *
1220
- * @beta
1221
- */
1222
- export declare function setLogLevel(level: LogLevel): void;
1356
+ /**
1357
+ * Send a plain text message to a notification target.
1358
+ *
1359
+ * @param target - the notification target.
1360
+ * @param text - the plain text message.
1361
+ * @returns A `Promise` representing the asynchronous operation.
1362
+ *
1363
+ * @beta
1364
+ */
1365
+ export declare function sendMessage(target: NotificationTarget, text: string): Promise<void>;
1223
1366
 
1224
- /**
1225
- * A {@link NotificationTarget} that represents a bot installation. Teams Bot could be installed into
1226
- * - Personal chat
1227
- * - Group chat
1228
- * - Team (by default the `General` channel)
1229
- *
1230
- * @remarks
1231
- * It's recommended to get bot installations from {@link ConversationBot.installations()}.
1232
- *
1233
- * @beta
1234
- */
1235
- export declare class TeamsBotInstallation implements NotificationTarget {
1236
- /**
1237
- * The bound `BotFrameworkAdapter`.
1238
- *
1239
- * @beta
1240
- */
1241
- readonly adapter: BotFrameworkAdapter;
1242
- /**
1243
- * The bound `ConversationReference`.
1244
- *
1245
- * @beta
1246
- */
1247
- readonly conversationReference: Partial<ConversationReference>;
1248
- /**
1249
- * Notification target type.
1250
- *
1251
- * @remarks
1252
- * - "Channel" means bot is installed into a team and notification will be sent to its "General" channel.
1253
- * - "Group" means bot is installed into a group chat.
1254
- * - "Person" means bot is installed into a personal scope and notification will be sent to personal chat.
1255
- *
1256
- * @beta
1257
- */
1258
- readonly type?: NotificationTargetType;
1259
- /**
1260
- * Constructor
1261
- *
1262
- * @remarks
1263
- * It's recommended to get bot installations from {@link ConversationBot.installations()}, instead of using this constructor.
1264
- *
1265
- * @param adapter - the bound `BotFrameworkAdapter`.
1266
- * @param conversationReference - the bound `ConversationReference`.
1267
- *
1268
- * @beta
1269
- */
1270
- constructor(adapter: BotFrameworkAdapter, conversationReference: Partial<ConversationReference>);
1271
- /**
1272
- * Send a plain text message.
1273
- *
1274
- * @param text - the plain text message.
1275
- * @returns A `Promise` representing the asynchronous operation.
1276
- *
1277
- * @beta
1278
- */
1279
- sendMessage(text: string): Promise<void>;
1280
- /**
1281
- * Send an adaptive card message.
1282
- *
1283
- * @param card - the adaptive card raw JSON.
1284
- * @returns A `Promise` representing the asynchronous operation.
1285
- *
1286
- * @beta
1287
- */
1288
- sendAdaptiveCard(card: unknown): Promise<void>;
1289
- /**
1290
- * Get channels from this bot installation.
1291
- *
1292
- * @returns an array of channels if bot is installed into a team, otherwise returns an empty array.
1293
- *
1294
- * @beta
1295
- */
1296
- channels(): Promise<Channel[]>;
1297
- /**
1298
- * Get members from this bot installation.
1299
- *
1300
- * @returns an array of members from where the bot is installed.
1301
- *
1302
- * @beta
1303
- */
1304
- members(): Promise<Member[]>;
1305
- }
1367
+ /**
1368
+ * Set custom log function. Use the function if it's set. Priority is lower than setLogger.
1369
+ *
1370
+ * @param {LogFunction} logFunction - custom log function. If it's undefined, custom log function will be cleared.
1371
+ *
1372
+ * @example
1373
+ * ```typescript
1374
+ * setLogFunction((level: LogLevel, message: string) => {
1375
+ * if (level === LogLevel.Error) {
1376
+ * console.log(message);
1377
+ * }
1378
+ * });
1379
+ * ```
1380
+ *
1381
+ * @beta
1382
+ */
1383
+ export declare function setLogFunction(logFunction?: LogFunction): void;
1306
1384
 
1307
- /**
1308
- * Creates a new prompt that leverage Teams Single Sign On (SSO) support for bot to automatically sign in user and
1309
- * help receive oauth token, asks the user to consent if needed.
1310
- *
1311
- * @remarks
1312
- * The prompt will attempt to retrieve the users current token of the desired scopes and store it in
1313
- * the token store.
1314
- *
1315
- * User will be automatically signed in leveraging Teams support of Bot Single Sign On(SSO):
1316
- * https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots
1317
- *
1318
- * @example
1319
- * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named
1320
- * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either
1321
- * `DialogContext.beginDialog()` or `DialogContext.prompt()`. The user will be prompted to sign in as
1322
- * needed and their access token will be passed as an argument to the callers next waterfall step:
1323
- *
1324
- * ```JavaScript
1325
- * const { ConversationState, MemoryStorage } = require('botbuilder');
1326
- * const { DialogSet, WaterfallDialog } = require('botbuilder-dialogs');
1327
- * const { TeamsBotSsoPrompt } = require('@microsoft/teamsfx');
1328
- *
1329
- * const convoState = new ConversationState(new MemoryStorage());
1330
- * const dialogState = convoState.createProperty('dialogState');
1331
- * const dialogs = new DialogSet(dialogState);
1332
- *
1333
- * dialogs.add(new TeamsBotSsoPrompt('TeamsBotSsoPrompt', {
1334
- * scopes: ["User.Read"],
1335
- * }));
1336
- *
1337
- * dialogs.add(new WaterfallDialog('taskNeedingLogin', [
1338
- * async (step) => {
1339
- * return await step.beginDialog('TeamsBotSsoPrompt');
1340
- * },
1341
- * async (step) => {
1342
- * const token = step.result;
1343
- * if (token) {
1344
- *
1345
- * // ... continue with task needing access token ...
1346
- *
1347
- * } else {
1348
- * await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
1349
- * return await step.endDialog();
1350
- * }
1351
- * }
1352
- * ]));
1353
- * ```
1354
- *
1355
- * @beta
1356
- */
1357
- export declare class TeamsBotSsoPrompt extends Dialog {
1358
- private teamsfx;
1359
- private settings;
1360
- /**
1361
- * Constructor of TeamsBotSsoPrompt.
1362
- *
1363
- * @param {TeamsFx} teamsfx - Used to provide configuration and auth
1364
- * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
1365
- * @param settings Settings used to configure the prompt.
1366
- *
1367
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1368
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1369
- *
1370
- * @beta
1371
- */
1372
- constructor(teamsfx: TeamsFx, dialogId: string, settings: TeamsBotSsoPromptSettings);
1373
- /**
1374
- * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
1375
- * @remarks
1376
- * If the task is successful, the result indicates whether the prompt is still
1377
- * active after the turn has been processed by the prompt.
1378
- *
1379
- * @param dc The DialogContext for the current turn of the conversation.
1380
- *
1381
- * @throws {@link ErrorCode|InvalidParameter} when timeout property in teams bot sso prompt settings is not number or is not positive.
1382
- * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1383
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1384
- *
1385
- * @returns A `Promise` representing the asynchronous operation.
1386
- *
1387
- * @beta
1388
- */
1389
- beginDialog(dc: DialogContext): Promise<DialogTurnResult>;
1390
- /**
1391
- * Called when a prompt dialog is the active dialog and the user replied with a new activity.
1392
- *
1393
- * @remarks
1394
- * If the task is successful, the result indicates whether the dialog is still
1395
- * active after the turn has been processed by the dialog.
1396
- * The prompt generally continues to receive the user's replies until it accepts the
1397
- * user's reply as valid input for the prompt.
1398
- *
1399
- * @param dc The DialogContext for the current turn of the conversation.
1400
- *
1401
- * @returns A `Promise` representing the asynchronous operation.
1402
- *
1403
- * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1404
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1405
- *
1406
- * @beta
1407
- */
1408
- continueDialog(dc: DialogContext): Promise<DialogTurnResult>;
1409
- private loadAndValidateConfig;
1410
- /**
1411
- * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
1412
- * @param dc dialog context
1413
- * @throws {@link ErrorCode|ChannelNotSupported} if bot channel is not MS Teams
1414
- * @internal
1415
- */
1416
- private ensureMsTeamsChannel;
1417
- /**
1418
- * Send OAuthCard that tells Teams to obtain an authentication token for the bot application.
1419
- * For details see https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots.
1420
- *
1421
- * @internal
1422
- */
1423
- private sendOAuthCardAsync;
1424
- /**
1425
- * Get sign in resource.
1426
- *
1427
- * @throws {@link ErrorCode|InvalidConfiguration} if client id, tenant id or initiate login endpoint is not found in config.
1428
- *
1429
- * @internal
1430
- */
1431
- private getSignInResource;
1432
- /**
1433
- * @internal
1434
- */
1435
- private recognizeToken;
1436
- /**
1437
- * @internal
1438
- */
1439
- private getTokenExchangeInvokeResponse;
1440
- /**
1441
- * @internal
1442
- */
1443
- private isTeamsVerificationInvoke;
1444
- /**
1445
- * @internal
1446
- */
1447
- private isTokenExchangeRequestInvoke;
1448
- /**
1449
- * @internal
1450
- */
1451
- private isTokenExchangeRequest;
1452
- }
1385
+ /**
1386
+ * Set custom logger. Use the output functions if it's set. Priority is higher than setLogFunction.
1387
+ *
1388
+ * @param {Logger} logger - custom logger. If it's undefined, custom logger will be cleared.
1389
+ *
1390
+ * @example
1391
+ * ```typescript
1392
+ * setLogger({
1393
+ * verbose: console.debug,
1394
+ * info: console.info,
1395
+ * warn: console.warn,
1396
+ * error: console.error,
1397
+ * });
1398
+ * ```
1399
+ *
1400
+ * @beta
1401
+ */
1402
+ export declare function setLogger(logger?: Logger): void;
1453
1403
 
1454
- /**
1455
- * Settings used to configure an TeamsBotSsoPrompt instance.
1456
- *
1457
- * @beta
1458
- */
1459
- export declare interface TeamsBotSsoPromptSettings {
1460
- /**
1461
- * The array of strings that declare the desired permissions and the resources requested.
1462
- */
1463
- scopes: string[];
1464
- /**
1465
- * (Optional) number of milliseconds the prompt will wait for the user to authenticate.
1466
- * Defaults to a value `900,000` (15 minutes.)
1467
- */
1468
- timeout?: number;
1469
- /**
1470
- * (Optional) value indicating whether the TeamsBotSsoPrompt should end upon receiving an
1471
- * invalid message. Generally the TeamsBotSsoPrompt will end the auth flow when receives user
1472
- * message not related to the auth flow. Setting the flag to false ignores the user's message instead.
1473
- * Defaults to value `true`
1474
- */
1475
- endOnInvalidMessage?: boolean;
1476
- }
1404
+ /**
1405
+ * Update log level helper.
1406
+ *
1407
+ * @param { LogLevel } level - log level in configuration
1408
+ *
1409
+ * @beta
1410
+ */
1411
+ export declare function setLogLevel(level: LogLevel): void;
1477
1412
 
1478
- /**
1479
- * Token response provided by Teams Bot SSO prompt
1480
- *
1481
- * @beta
1482
- */
1483
- export declare interface TeamsBotSsoPromptTokenResponse extends TokenResponse {
1484
- /**
1485
- * SSO token for user
1486
- */
1487
- ssoToken: string;
1488
- /**
1489
- * Expire time of SSO token
1490
- */
1491
- ssoTokenExpiration: string;
1492
- }
1413
+ /**
1414
+ * A {@link NotificationTarget} that represents a bot installation. Teams Bot could be installed into
1415
+ * - Personal chat
1416
+ * - Group chat
1417
+ * - Team (by default the `General` channel)
1418
+ *
1419
+ * @remarks
1420
+ * It's recommended to get bot installations from {@link ConversationBot.installations()}.
1421
+ *
1422
+ * @beta
1423
+ */
1424
+ export declare class TeamsBotInstallation implements NotificationTarget {
1425
+ /**
1426
+ * The bound `BotFrameworkAdapter`.
1427
+ *
1428
+ * @beta
1429
+ */
1430
+ readonly adapter: BotFrameworkAdapter;
1431
+ /**
1432
+ * The bound `ConversationReference`.
1433
+ *
1434
+ * @beta
1435
+ */
1436
+ readonly conversationReference: Partial<ConversationReference>;
1437
+ /**
1438
+ * Notification target type.
1439
+ *
1440
+ * @remarks
1441
+ * - "Channel" means bot is installed into a team and notification will be sent to its "General" channel.
1442
+ * - "Group" means bot is installed into a group chat.
1443
+ * - "Person" means bot is installed into a personal scope and notification will be sent to personal chat.
1444
+ *
1445
+ * @beta
1446
+ */
1447
+ readonly type?: NotificationTargetType;
1448
+ /**
1449
+ * Constructor
1450
+ *
1451
+ * @remarks
1452
+ * It's recommended to get bot installations from {@link ConversationBot.installations()}, instead of using this constructor.
1453
+ *
1454
+ * @param adapter - the bound `BotFrameworkAdapter`.
1455
+ * @param conversationReference - the bound `ConversationReference`.
1456
+ *
1457
+ * @beta
1458
+ */
1459
+ constructor(adapter: BotFrameworkAdapter, conversationReference: Partial<ConversationReference>);
1460
+ /**
1461
+ * Send a plain text message.
1462
+ *
1463
+ * @param text - the plain text message.
1464
+ * @returns A `Promise` representing the asynchronous operation.
1465
+ *
1466
+ * @beta
1467
+ */
1468
+ sendMessage(text: string): Promise<void>;
1469
+ /**
1470
+ * Send an adaptive card message.
1471
+ *
1472
+ * @param card - the adaptive card raw JSON.
1473
+ * @returns A `Promise` representing the asynchronous operation.
1474
+ *
1475
+ * @beta
1476
+ */
1477
+ sendAdaptiveCard(card: unknown): Promise<void>;
1478
+ /**
1479
+ * Get channels from this bot installation.
1480
+ *
1481
+ * @returns an array of channels if bot is installed into a team, otherwise returns an empty array.
1482
+ *
1483
+ * @beta
1484
+ */
1485
+ channels(): Promise<Channel[]>;
1486
+ /**
1487
+ * Get members from this bot installation.
1488
+ *
1489
+ * @returns an array of members from where the bot is installed.
1490
+ *
1491
+ * @beta
1492
+ */
1493
+ members(): Promise<Member[]>;
1494
+ }
1493
1495
 
1494
- /**
1495
- * A class providing credential and configuration.
1496
- * @beta
1497
- */
1498
- export declare class TeamsFx implements TeamsFxConfiguration {
1499
- private configuration;
1500
- private oboUserCredential?;
1501
- private appCredential?;
1502
- private identityType;
1503
- /**
1504
- * Constructor of TeamsFx
1505
- *
1506
- * @param {IdentityType} identityType - Choose user or app identity
1507
- * @param customConfig - key/value pairs of customized configuration that overrides default ones.
1508
- *
1509
- * @throws {@link ErrorCode|IdentityTypeNotSupported} when setting app identity in browser.
1510
- *
1511
- * @beta
1512
- */
1513
- constructor(identityType?: IdentityType, customConfig?: Record<string, string>);
1514
- /**
1515
- * Identity type set by user.
1516
- *
1517
- * @returns identity type.
1518
- * @beta
1519
- */
1520
- getIdentityType(): IdentityType;
1521
- /**
1522
- * Credential instance according to identity type choice.
1523
- *
1524
- * @remarks If user identity is chose, will return {@link TeamsUserCredential}
1525
- * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
1526
- * identity is chose, will return {@link AppCredential}.
1527
- *
1528
- * @returns instance implements TokenCredential interface.
1529
- * @beta
1530
- */
1531
- getCredential(): TokenCredential;
1532
- /**
1533
- * Get user information.
1534
- * @returns UserInfo object.
1535
- * @beta
1536
- */
1537
- getUserInfo(): Promise<UserInfo>;
1538
- /**
1539
- * Popup login page to get user's access token with specific scopes.
1540
- *
1541
- * @remarks
1542
- * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
1543
- *
1544
- * @example
1545
- * ```typescript
1546
- * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
1547
- * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
1548
- * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
1549
- * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
1550
- * ```
1551
- * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
1552
- *
1553
- * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
1554
- * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
1555
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1556
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1557
- *
1558
- * @beta
1559
- */
1560
- login(scopes: string | string[]): Promise<void>;
1561
- /**
1562
- * Set SSO token when using user identity in NodeJS.
1563
- * @param {string} ssoToken - used for on behalf of user flow.
1564
- * @returns self instance.
1565
- * @beta
1566
- */
1567
- setSsoToken(ssoToken: string): TeamsFx;
1568
- /**
1569
- * Usually used by service plugins to retrieve specific config
1570
- * @param {string} key - configuration key.
1571
- * @returns value in configuration.
1572
- * @beta
1573
- */
1574
- getConfig(key: string): string;
1575
- /**
1576
- * Check the value of specific key.
1577
- * @param {string} key - configuration key.
1578
- * @returns true if corresponding value is not empty string.
1579
- * @beta
1580
- */
1581
- hasConfig(key: string): boolean;
1582
- /**
1583
- * Get all configurations.
1584
- * @returns key value mappings.
1585
- * @beta
1586
- */
1587
- getConfigs(): Record<string, string>;
1588
- /**
1589
- * Load configuration from environment variables.
1590
- */
1591
- private loadFromEnv;
1592
- }
1496
+ /**
1497
+ * Creates a new prompt that leverage Teams Single Sign On (SSO) support for bot to automatically sign in user and
1498
+ * help receive oauth token, asks the user to consent if needed.
1499
+ *
1500
+ * @remarks
1501
+ * The prompt will attempt to retrieve the users current token of the desired scopes and store it in
1502
+ * the token store.
1503
+ *
1504
+ * User will be automatically signed in leveraging Teams support of Bot Single Sign On(SSO):
1505
+ * https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots
1506
+ *
1507
+ * @example
1508
+ * When used with your bots `DialogSet` you can simply add a new instance of the prompt as a named
1509
+ * dialog using `DialogSet.add()`. You can then start the prompt from a waterfall step using either
1510
+ * `DialogContext.beginDialog()` or `DialogContext.prompt()`. The user will be prompted to sign in as
1511
+ * needed and their access token will be passed as an argument to the callers next waterfall step:
1512
+ *
1513
+ * ```JavaScript
1514
+ * const { ConversationState, MemoryStorage } = require('botbuilder');
1515
+ * const { DialogSet, WaterfallDialog } = require('botbuilder-dialogs');
1516
+ * const { TeamsBotSsoPrompt } = require('@microsoft/teamsfx');
1517
+ *
1518
+ * const convoState = new ConversationState(new MemoryStorage());
1519
+ * const dialogState = convoState.createProperty('dialogState');
1520
+ * const dialogs = new DialogSet(dialogState);
1521
+ *
1522
+ * dialogs.add(new TeamsBotSsoPrompt('TeamsBotSsoPrompt', {
1523
+ * scopes: ["User.Read"],
1524
+ * }));
1525
+ *
1526
+ * dialogs.add(new WaterfallDialog('taskNeedingLogin', [
1527
+ * async (step) => {
1528
+ * return await step.beginDialog('TeamsBotSsoPrompt');
1529
+ * },
1530
+ * async (step) => {
1531
+ * const token = step.result;
1532
+ * if (token) {
1533
+ *
1534
+ * // ... continue with task needing access token ...
1535
+ *
1536
+ * } else {
1537
+ * await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
1538
+ * return await step.endDialog();
1539
+ * }
1540
+ * }
1541
+ * ]));
1542
+ * ```
1543
+ *
1544
+ * @beta
1545
+ */
1546
+ export declare class TeamsBotSsoPrompt extends Dialog {
1547
+ private teamsfx;
1548
+ private settings;
1549
+ /**
1550
+ * Constructor of TeamsBotSsoPrompt.
1551
+ *
1552
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth
1553
+ * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
1554
+ * @param settings Settings used to configure the prompt.
1555
+ *
1556
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1557
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1558
+ *
1559
+ * @beta
1560
+ */
1561
+ constructor(teamsfx: TeamsFx, dialogId: string, settings: TeamsBotSsoPromptSettings);
1562
+ /**
1563
+ * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
1564
+ * @remarks
1565
+ * If the task is successful, the result indicates whether the prompt is still
1566
+ * active after the turn has been processed by the prompt.
1567
+ *
1568
+ * @param dc The DialogContext for the current turn of the conversation.
1569
+ *
1570
+ * @throws {@link ErrorCode|InvalidParameter} when timeout property in teams bot sso prompt settings is not number or is not positive.
1571
+ * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1572
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1573
+ *
1574
+ * @returns A `Promise` representing the asynchronous operation.
1575
+ *
1576
+ * @beta
1577
+ */
1578
+ beginDialog(dc: DialogContext): Promise<DialogTurnResult>;
1579
+ /**
1580
+ * Called when a prompt dialog is the active dialog and the user replied with a new activity.
1581
+ *
1582
+ * @remarks
1583
+ * If the task is successful, the result indicates whether the dialog is still
1584
+ * active after the turn has been processed by the dialog.
1585
+ * The prompt generally continues to receive the user's replies until it accepts the
1586
+ * user's reply as valid input for the prompt.
1587
+ *
1588
+ * @param dc The DialogContext for the current turn of the conversation.
1589
+ *
1590
+ * @returns A `Promise` representing the asynchronous operation.
1591
+ *
1592
+ * @throws {@link ErrorCode|ChannelNotSupported} when bot channel is not MS Teams.
1593
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
1594
+ *
1595
+ * @beta
1596
+ */
1597
+ continueDialog(dc: DialogContext): Promise<DialogTurnResult>;
1598
+ private loadAndValidateConfig;
1599
+ /**
1600
+ * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
1601
+ * @param dc dialog context
1602
+ * @throws {@link ErrorCode|ChannelNotSupported} if bot channel is not MS Teams
1603
+ * @internal
1604
+ */
1605
+ private ensureMsTeamsChannel;
1606
+ /**
1607
+ * Send OAuthCard that tells Teams to obtain an authentication token for the bot application.
1608
+ * For details see https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/authentication/auth-aad-sso-bots.
1609
+ *
1610
+ * @internal
1611
+ */
1612
+ private sendOAuthCardAsync;
1613
+ /**
1614
+ * Get sign in resource.
1615
+ *
1616
+ * @throws {@link ErrorCode|InvalidConfiguration} if client id, tenant id or initiate login endpoint is not found in config.
1617
+ *
1618
+ * @internal
1619
+ */
1620
+ private getSignInResource;
1621
+ /**
1622
+ * @internal
1623
+ */
1624
+ private recognizeToken;
1625
+ /**
1626
+ * @internal
1627
+ */
1628
+ private getTokenExchangeInvokeResponse;
1629
+ /**
1630
+ * @internal
1631
+ */
1632
+ private isTeamsVerificationInvoke;
1633
+ /**
1634
+ * @internal
1635
+ */
1636
+ private isTokenExchangeRequestInvoke;
1637
+ /**
1638
+ * @internal
1639
+ */
1640
+ private isTokenExchangeRequest;
1641
+ }
1593
1642
 
1594
- /**
1595
- * Interface for a command handler that can process command to a TeamsFx bot and return a response.
1596
- *
1597
- * @beta
1598
- */
1599
- export declare interface TeamsFxBotCommandHandler {
1600
- /**
1601
- * The string or regular expression patterns that can trigger this handler.
1602
- */
1603
- triggerPatterns: TriggerPatterns;
1604
- /**
1605
- * Handles a bot command received activity.
1606
- *
1607
- * @param context The bot context.
1608
- * @param message The command message the user types from Teams.
1609
- * @returns A `Promise` representing an activity or text to send as the command response.
1610
- */
1611
- handleCommandReceived(context: TurnContext, message: CommandMessage): Promise<string | Partial<Activity>>;
1612
- }
1643
+ /**
1644
+ * Settings used to configure an TeamsBotSsoPrompt instance.
1645
+ *
1646
+ * @beta
1647
+ */
1648
+ export declare interface TeamsBotSsoPromptSettings {
1649
+ /**
1650
+ * The array of strings that declare the desired permissions and the resources requested.
1651
+ */
1652
+ scopes: string[];
1653
+ /**
1654
+ * (Optional) number of milliseconds the prompt will wait for the user to authenticate.
1655
+ * Defaults to a value `900,000` (15 minutes.)
1656
+ */
1657
+ timeout?: number;
1658
+ /**
1659
+ * (Optional) value indicating whether the TeamsBotSsoPrompt should end upon receiving an
1660
+ * invalid message. Generally the TeamsBotSsoPrompt will end the auth flow when receives user
1661
+ * message not related to the auth flow. Setting the flag to false ignores the user's message instead.
1662
+ * Defaults to value `true`
1663
+ */
1664
+ endOnInvalidMessage?: boolean;
1665
+ }
1613
1666
 
1614
- /**
1615
- * TeamsFx interface that provides credential and configuration.
1616
- * @beta
1617
- */
1618
- declare interface TeamsFxConfiguration {
1619
- /**
1620
- * Identity type set by user.
1621
- *
1622
- * @returns identity type.
1623
- * @beta
1624
- */
1625
- getIdentityType(): IdentityType;
1626
- /**
1627
- * Credential instance according to identity type choice.
1628
- *
1629
- * @remarks If user identity is chose, will return {@link TeamsUserCredential}
1630
- * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
1631
- * identity is chose, will return {@link AppCredential}.
1632
- *
1633
- * @returns instance implements TokenCredential interface.
1634
- * @beta
1635
- */
1636
- getCredential(): TokenCredential;
1637
- /**
1638
- * Get user information.
1639
- * @returns UserInfo object.
1640
- * @beta
1641
- */
1642
- getUserInfo(): Promise<UserInfo>;
1643
- /**
1644
- * Popup login page to get user's access token with specific scopes.
1645
- *
1646
- * @remarks
1647
- * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
1648
- *
1649
- * @example
1650
- * ```typescript
1651
- * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
1652
- * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
1653
- * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
1654
- * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
1655
- * ```
1656
- * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
1657
- *
1658
- * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
1659
- * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
1660
- * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1661
- * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1662
- *
1663
- * @beta
1664
- */
1665
- login(scopes: string | string[]): Promise<void>;
1666
- /**
1667
- * Set SSO token when using user identity in NodeJS.
1668
- * @param {string} ssoToken - used for on behalf of user flow.
1669
- * @returns self instance.
1670
- * @beta
1671
- */
1672
- setSsoToken(ssoToken: string): TeamsFxConfiguration;
1673
- /**
1674
- * Usually used by service plugins to retrieve specific config
1675
- * @param {string} key - configuration key.
1676
- * @returns value in configuration.
1677
- * @beta
1678
- */
1679
- getConfig(key: string): string;
1680
- /**
1681
- * Check the value of specific key.
1682
- * @param {string} key - configuration key.
1683
- * @returns true if corresponding value is not empty string.
1684
- * @beta
1685
- */
1686
- hasConfig(key: string): boolean;
1687
- /**
1688
- * Get all configurations.
1689
- * @returns key value mappings.
1690
- * @beta
1691
- */
1692
- getConfigs(): Record<string, string>;
1693
- }
1667
+ /**
1668
+ * Token response provided by Teams Bot SSO prompt
1669
+ *
1670
+ * @beta
1671
+ */
1672
+ export declare interface TeamsBotSsoPromptTokenResponse extends TokenResponse {
1673
+ /**
1674
+ * SSO token for user
1675
+ */
1676
+ ssoToken: string;
1677
+ /**
1678
+ * Expire time of SSO token
1679
+ */
1680
+ ssoTokenExpiration: string;
1681
+ }
1694
1682
 
1695
- /**
1696
- * Represent Teams current user's identity, and it is used within Teams client applications.
1697
- *
1698
- * @remarks
1699
- * Can only be used within Teams.
1700
- *
1701
- * @beta
1702
- */
1703
- export declare class TeamsUserCredential implements TokenCredential {
1704
- /**
1705
- * Constructor of TeamsUserCredential.
1706
- * @remarks
1707
- * Can only be used within Teams.
1708
- * @beta
1709
- */
1710
- constructor(authConfig: AuthenticationConfiguration);
1711
- /**
1712
- * Popup login page to get user's access token with specific scopes.
1713
- * @remarks
1714
- * Can only be used within Teams.
1715
- * @beta
1716
- */
1717
- login(scopes: string | string[]): Promise<void>;
1718
- /**
1719
- * Get access token from credential.
1720
- * @remarks
1721
- * Can only be used within Teams.
1722
- * @beta
1723
- */
1724
- getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1725
- /**
1726
- * Get basic user info from SSO token
1727
- * @remarks
1728
- * Can only be used within Teams.
1729
- * @beta
1730
- */
1731
- getUserInfo(): Promise<UserInfo>;
1732
- }
1683
+ /**
1684
+ * A class providing credential and configuration.
1685
+ * @beta
1686
+ */
1687
+ export declare class TeamsFx implements TeamsFxConfiguration {
1688
+ private configuration;
1689
+ private oboUserCredential?;
1690
+ private appCredential?;
1691
+ private identityType;
1692
+ /**
1693
+ * Constructor of TeamsFx
1694
+ *
1695
+ * @param {IdentityType} identityType - Choose user or app identity
1696
+ * @param customConfig - key/value pairs of customized configuration that overrides default ones.
1697
+ *
1698
+ * @throws {@link ErrorCode|IdentityTypeNotSupported} when setting app identity in browser.
1699
+ *
1700
+ * @beta
1701
+ */
1702
+ constructor(identityType?: IdentityType, customConfig?: Record<string, string>);
1703
+ /**
1704
+ * Identity type set by user.
1705
+ *
1706
+ * @returns identity type.
1707
+ * @beta
1708
+ */
1709
+ getIdentityType(): IdentityType;
1710
+ /**
1711
+ * Credential instance according to identity type choice.
1712
+ *
1713
+ * @remarks If user identity is chose, will return {@link TeamsUserCredential}
1714
+ * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
1715
+ * identity is chose, will return {@link AppCredential}.
1716
+ *
1717
+ * @returns instance implements TokenCredential interface.
1718
+ * @beta
1719
+ */
1720
+ getCredential(): TokenCredential;
1721
+ /**
1722
+ * Get user information.
1723
+ * @returns UserInfo object.
1724
+ * @beta
1725
+ */
1726
+ getUserInfo(): Promise<UserInfo>;
1727
+ /**
1728
+ * Popup login page to get user's access token with specific scopes.
1729
+ *
1730
+ * @remarks
1731
+ * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
1732
+ *
1733
+ * @example
1734
+ * ```typescript
1735
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
1736
+ * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
1737
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
1738
+ * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
1739
+ * ```
1740
+ * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
1741
+ *
1742
+ * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
1743
+ * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
1744
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1745
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1746
+ *
1747
+ * @beta
1748
+ */
1749
+ login(scopes: string | string[]): Promise<void>;
1750
+ /**
1751
+ * Set SSO token when using user identity in NodeJS.
1752
+ * @param {string} ssoToken - used for on behalf of user flow.
1753
+ * @returns self instance.
1754
+ * @beta
1755
+ */
1756
+ setSsoToken(ssoToken: string): TeamsFx;
1757
+ /**
1758
+ * Usually used by service plugins to retrieve specific config
1759
+ * @param {string} key - configuration key.
1760
+ * @returns value in configuration.
1761
+ * @beta
1762
+ */
1763
+ getConfig(key: string): string;
1764
+ /**
1765
+ * Check the value of specific key.
1766
+ * @param {string} key - configuration key.
1767
+ * @returns true if corresponding value is not empty string.
1768
+ * @beta
1769
+ */
1770
+ hasConfig(key: string): boolean;
1771
+ /**
1772
+ * Get all configurations.
1773
+ * @returns key value mappings.
1774
+ * @beta
1775
+ */
1776
+ getConfigs(): Record<string, string>;
1777
+ /**
1778
+ * Load configuration from environment variables.
1779
+ */
1780
+ private loadFromEnv;
1781
+ }
1733
1782
 
1734
- /**
1735
- * The trigger pattern used to trigger a {@link TeamsFxBotCommandHandler} instance.
1736
- */
1737
- export declare type TriggerPatterns = string | RegExp | (string | RegExp)[];
1783
+ /**
1784
+ * Interface for a command handler that can process command to a TeamsFx bot and return a response.
1785
+ *
1786
+ * @beta
1787
+ */
1788
+ export declare interface TeamsFxBotCommandHandler {
1789
+ /**
1790
+ * The string or regular expression patterns that can trigger this handler.
1791
+ */
1792
+ triggerPatterns: TriggerPatterns;
1793
+ /**
1794
+ * Handles a bot command received activity.
1795
+ *
1796
+ * @param context The bot context.
1797
+ * @param message The command message the user types from Teams.
1798
+ * @returns A `Promise` representing an activity or text to send as the command response.
1799
+ */
1800
+ handleCommandReceived(context: TurnContext, message: CommandMessage): Promise<string | Partial<Activity>>;
1801
+ }
1738
1802
 
1739
- /**
1740
- * UserInfo with user displayName, objectId and preferredUserName.
1741
- *
1742
- * @beta
1743
- */
1744
- export declare interface UserInfo {
1745
- /**
1746
- * User Display Name.
1747
- *
1748
- * @readonly
1749
- */
1750
- displayName: string;
1751
- /**
1752
- * User unique reference within the Azure Active Directory domain.
1753
- *
1754
- * @readonly
1755
- */
1756
- objectId: string;
1757
- /**
1758
- * Usually be the email address.
1759
- *
1760
- * @readonly
1761
- */
1762
- preferredUserName: string;
1763
- }
1803
+ /**
1804
+ * TeamsFx interface that provides credential and configuration.
1805
+ * @beta
1806
+ */
1807
+ declare interface TeamsFxConfiguration {
1808
+ /**
1809
+ * Identity type set by user.
1810
+ *
1811
+ * @returns identity type.
1812
+ * @beta
1813
+ */
1814
+ getIdentityType(): IdentityType;
1815
+ /**
1816
+ * Credential instance according to identity type choice.
1817
+ *
1818
+ * @remarks If user identity is chose, will return {@link TeamsUserCredential}
1819
+ * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
1820
+ * identity is chose, will return {@link AppCredential}.
1821
+ *
1822
+ * @returns instance implements TokenCredential interface.
1823
+ * @beta
1824
+ */
1825
+ getCredential(): TokenCredential;
1826
+ /**
1827
+ * Get user information.
1828
+ * @returns UserInfo object.
1829
+ * @beta
1830
+ */
1831
+ getUserInfo(): Promise<UserInfo>;
1832
+ /**
1833
+ * Popup login page to get user's access token with specific scopes.
1834
+ *
1835
+ * @remarks
1836
+ * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
1837
+ *
1838
+ * @example
1839
+ * ```typescript
1840
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
1841
+ * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
1842
+ * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
1843
+ * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
1844
+ * ```
1845
+ * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
1846
+ *
1847
+ * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
1848
+ * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
1849
+ * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
1850
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
1851
+ *
1852
+ * @beta
1853
+ */
1854
+ login(scopes: string | string[]): Promise<void>;
1855
+ /**
1856
+ * Set SSO token when using user identity in NodeJS.
1857
+ * @param {string} ssoToken - used for on behalf of user flow.
1858
+ * @returns self instance.
1859
+ * @beta
1860
+ */
1861
+ setSsoToken(ssoToken: string): TeamsFxConfiguration;
1862
+ /**
1863
+ * Usually used by service plugins to retrieve specific config
1864
+ * @param {string} key - configuration key.
1865
+ * @returns value in configuration.
1866
+ * @beta
1867
+ */
1868
+ getConfig(key: string): string;
1869
+ /**
1870
+ * Check the value of specific key.
1871
+ * @param {string} key - configuration key.
1872
+ * @returns true if corresponding value is not empty string.
1873
+ * @beta
1874
+ */
1875
+ hasConfig(key: string): boolean;
1876
+ /**
1877
+ * Get all configurations.
1878
+ * @returns key value mappings.
1879
+ * @beta
1880
+ */
1881
+ getConfigs(): Record<string, string>;
1882
+ }
1883
+
1884
+ /**
1885
+ * Represent Teams current user's identity, and it is used within Teams client applications.
1886
+ *
1887
+ * @remarks
1888
+ * Can only be used within Teams.
1889
+ *
1890
+ * @beta
1891
+ */
1892
+ export declare class TeamsUserCredential implements TokenCredential {
1893
+ /**
1894
+ * Constructor of TeamsUserCredential.
1895
+ * @remarks
1896
+ * Can only be used within Teams.
1897
+ * @beta
1898
+ */
1899
+ constructor(authConfig: AuthenticationConfiguration);
1900
+ /**
1901
+ * Popup login page to get user's access token with specific scopes.
1902
+ * @remarks
1903
+ * Can only be used within Teams.
1904
+ * @beta
1905
+ */
1906
+ login(scopes: string | string[]): Promise<void>;
1907
+ /**
1908
+ * Get access token from credential.
1909
+ * @remarks
1910
+ * Can only be used within Teams.
1911
+ * @beta
1912
+ */
1913
+ getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
1914
+ /**
1915
+ * Get basic user info from SSO token
1916
+ * @remarks
1917
+ * Can only be used within Teams.
1918
+ * @beta
1919
+ */
1920
+ getUserInfo(): Promise<UserInfo>;
1921
+ }
1922
+
1923
+ /**
1924
+ * The trigger pattern used to trigger a {@link TeamsFxBotCommandHandler} instance.
1925
+ */
1926
+ export declare type TriggerPatterns = string | RegExp | (string | RegExp)[];
1927
+
1928
+ /**
1929
+ * UserInfo with user displayName, objectId and preferredUserName.
1930
+ *
1931
+ * @beta
1932
+ */
1933
+ export declare interface UserInfo {
1934
+ /**
1935
+ * User Display Name.
1936
+ *
1937
+ * @readonly
1938
+ */
1939
+ displayName: string;
1940
+ /**
1941
+ * User unique reference within the Azure Active Directory domain.
1942
+ *
1943
+ * @readonly
1944
+ */
1945
+ objectId: string;
1946
+ /**
1947
+ * Usually be the email address.
1948
+ *
1949
+ * @readonly
1950
+ */
1951
+ preferredUserName: string;
1952
+ }
1764
1953
 
1765
- export { }
1954
+ export { }