@microsoft/teamsfx 0.6.2-alpha.444739e17.0 → 0.6.2-alpha.52f41e8aa.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/teamsfx",
-  "version": "0.6.2-alpha.444739e17.0",
+  "version": "0.6.2-alpha.52f41e8aa.0",
   "description": "Microsoft Teams Framework for Node.js and browser.",
   "main": "dist/index.node.cjs.js",
   "browser": "dist/index.esm2017.js",
@@ -49,7 +49,7 @@
     "@azure/identity": "^2.0.1",
     "@azure/msal-browser": "^2.21.0",
     "@azure/msal-node": "~1.1.0",
-    "@microsoft/adaptivecards-tools": "0.1.6-alpha.444739e17.0",
+    "@microsoft/adaptivecards-tools": "0.1.6-alpha.52f41e8aa.0",
     "@microsoft/microsoft-graph-client": "^3.0.1",
     "axios": "^0.24.0",
     "botbuilder": ">=4.15.0 <5.0.0",
@@ -85,6 +85,7 @@
     "@typescript-eslint/eslint-plugin": "^5.0.0",
     "@typescript-eslint/parser": "^4.13.0",
     "adm-zip": "^0.5.9",
+    "axios-mock-adapter": "^1.20.0",
     "botbuilder-core": ">=4.15.0 <5.0.0",
     "chai": "^4.3.4",
     "chai-as-promised": "^7.1.1",
@@ -127,7 +128,7 @@
     "webpack": "^5.62.1",
     "yargs": "^17.2.1"
   },
-  "gitHead": "128f6dbe9e01e989cdc717967e0ffe7b0280d8f9",
+  "gitHead": "b73c402779226ef96977f0cdfce9dc1df617259c",
   "publishConfig": {
     "access": "public"
   },

package/types/teamsfx.d.ts

@@ -3,6 +3,8 @@ import { Activity } from 'botbuilder-core';
 import { Activity as Activity_2 } from 'botbuilder';
 import { Attachment } from 'botbuilder';
 import { AuthenticationProvider } from '@microsoft/microsoft-graph-client';
+import { AxiosInstance } from 'axios';
+import { AxiosRequestConfig } from 'axios';
 import { BotFrameworkAdapter } from 'botbuilder';
 import { CardAction } from 'botbuilder';
 import { CardImage } from 'botbuilder';
@@ -137,6 +139,47 @@ export declare interface AuthenticationConfiguration {
     readonly applicationIdUri?: string;
 }
 
+/**
+ * Defines method that injects authentication info to http requests
+ *
+ * @beta
+ */
+export declare interface AuthProvider {
+    /**
+     * Adds authentication info to http requests
+     *
+     * @param config - Contains all the request information and can be updated to include extra authentication info.
+     * Refer https://axios-http.com/docs/req_config for detailed document.
+     *
+     * @beta
+     */
+    AddAuthenticationInfo: (config: AxiosRequestConfig) => Promise<AxiosRequestConfig>;
+}
+
+/**
+ * Provider that handles Bearer Token authentication
+ *
+ * @beta
+ */
+export declare class BearerTokenAuthProvider implements AuthProvider {
+    private getToken;
+    /**
+     * @param getToken Function that returns the content of bearer token used in http request
+     *
+     * @beta
+     */
+    constructor(getToken: () => Promise<string>);
+    /**
+     * Adds authentication info to http requests
+     *
+     * @param config - Contains all the request information and can be updated to include extra authentication info.
+     * Refer https://axios-http.com/docs/req_config for detailed document.
+     *
+     * @beta
+     */
+    AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
+}
+
 /**
  * A {@link NotificationTarget} that represents a team channel.
  *
@@ -206,31 +249,20 @@ export declare class Channel implements NotificationTarget {
  * @remarks
  * 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.
  *
- * @example
- * You can register your commands  through the constructor of the {@link CommandBot}, or use the `registerCommand` and `registerCommands` API to add commands after creating the `CommandBot` instance.
- *
- * ```typescript
- * // register through constructor
- * const commandBot = new CommandBot(adapter, [ new HelloWorldCommandHandler() ]);
- *
- * // register through `register*` API
- * commandBot.registerCommand(new HelpCommandHandler());
- * ```
- *
  * @beta
  */
 export declare class CommandBot {
-    readonly adapter: BotFrameworkAdapter;
+    private readonly adapter;
     private readonly middleware;
     /**
      * Creates a new instance of the `CommandBot`.
      *
      * @param adapter The bound `BotFrameworkAdapter`.
-     * @param commands The commands to registered with the command bot. Each command should implement the interface {@link TeamsFxBotCommandHandler} so that it can be correctly handled by this command bot.
+     * @param options - initialize options
      *
      * @beta
      */
-    constructor(adapter: BotFrameworkAdapter, commands?: TeamsFxBotCommandHandler[]);
+    constructor(adapter: BotFrameworkAdapter, options?: CommandOptions);
     /**
      * Registers a command into the command bot.
      *
@@ -249,6 +281,186 @@ export declare class CommandBot {
     registerCommands(commands: TeamsFxBotCommandHandler[]): void;
 }
 
+/**
+ * Interface for a command messagge that can handled in a command handler.
+ */
+export declare interface CommandMessage {
+    /**
+     * Text of the message sent by the user.
+     */
+    text: string;
+    /**
+     * The capture groups that matched to the {@link triggerPatterns} in a {@link TeamsFxBotCommandHandler} instance.
+     */
+    matches?: RegExpMatchArray;
+}
+
+/**
+ * Options to initialize {@link CommandBot}.
+ *
+ * @beta
+ */
+export declare interface CommandOptions {
+    /**
+     * The commands to registered with the command bot. Each command should implement the interface {@link TeamsFxBotCommandHandler} so that it can be correctly handled by this command bot.
+     *
+     * @beta
+     */
+    commands?: TeamsFxBotCommandHandler[];
+}
+
+/**
+ * Provide utilities for bot conversation, including:
+ *   - handle command and response.
+ *   - send notification to varies targets (e.g., member, channel, incoming wehbook).
+ *
+ * @example
+ * For command and response, you can register your commands through the constructor, or use the `registerCommand` and `registerCommands` API to add commands later.
+ *
+ * ```typescript
+ * // register through constructor
+ * const conversationBot = new ConversationBot({
+ *   command: {
+ *     enabled: true,
+ *     options: {
+ *         commands: [ new HelloWorldCommandHandler() ],
+ *     },
+ *   },
+ * });
+ *
+ * // register through `register*` API
+ * conversationBot.command.registerCommand(new HelpCommandHandler());
+ * ```
+ *
+ * For notification, you can enable notification at initialization, then send notificaations at any time.
+ *
+ * ```typescript
+ * // enable through constructor
+ * const conversationBot = new ConversationBot({
+ *   notification: {
+ *     enabled: true,
+ *   },
+ * });
+ *
+ * // get all bot installations and send message
+ * for (const target of await conversationBot.notification.installations()) {
+ *   await target.sendMessage("Hello Notification");
+ * }
+ *
+ * // alternative - send message to all members
+ * for (const target of await conversationBot.notification.installations()) {
+ *   for (const member of await target.members()) {
+ *     await member.sendMessage("Hello Notification");
+ *   }
+ * }
+ * ```
+ *
+ * @remarks
+ * Set `adapter` in {@link ConversationOptions} to use your own bot adapter.
+ *
+ * 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.
+ *
+ * For notification, set `notification.options.storage` in {@link ConversationOptions} to use your own storage implementation.
+ *
+ * @beta
+ */
+export declare class ConversationBot {
+    /**
+     * The bot adapter.
+     *
+     * @beta
+     */
+    readonly adapter: BotFrameworkAdapter;
+    /**
+     * The entrypoint of command and response.
+     *
+     * @beta
+     */
+    readonly command?: CommandBot;
+    /**
+     * The entrypoint of notification.
+     *
+     * @beta
+     */
+    readonly notification?: NotificationBot;
+    /**
+     * Creates new instance of the `ConversationBot`.
+     *
+     * @param options - initialize options
+     *
+     * @beta
+     */
+    constructor(options: ConversationOptions);
+}
+
+/**
+ * Options to initialize {@link ConversationBot}
+ *
+ * @beta
+ */
+export declare interface ConversationOptions {
+    /**
+     * The bot adapter. If not provided, a default adapter will be created with BOT_ID and BOT_PASSWORD from environment variables.
+     *
+     * @beta
+     */
+    adapter?: BotFrameworkAdapter;
+    /**
+     * The command part.
+     *
+     * @beta
+     */
+    command: {
+        /**
+         * Whether to enable command or not.
+         *
+         * @beta
+         */
+        enabled: boolean;
+        /**
+         * The command options if command is enabled.
+         *
+         * @beta
+         */
+        options: CommandOptions;
+    };
+    /**
+     * The notification part.
+     *
+     * @beta
+     */
+    notification: {
+        /**
+         * Whether to enable notification or not.
+         *
+         * @beta
+         */
+        enabled: boolean;
+        /**
+         * The notification options if notification is enabled.
+         *
+         * @beta
+         */
+        options: NotificationOptions_2;
+    };
+}
+
+/**
+ * Initializes new Axios instance with specific auth provider
+ *
+ * @param apiEndpoint - Base url of the API
+ * @param authProvider - Auth provider that injects authentication info to each request
+ * @returns axios instance configured with specfic auth provider
+ *
+ * @example
+ * ```typescript
+ * const client = createApiClient("https://my-api-endpoint-base-url", new BasicAuthProvider("xxx","xxx"));
+ * ```
+ *
+ * @beta
+ */
+export declare function createApiClient(apiEndpoint: string, authProvider: AuthProvider): AxiosInstance;
+
 /**
  * Get Microsoft graph client.
  *
@@ -708,28 +920,7 @@ export declare class MsGraphAuthProvider implements AuthenticationProvider {
 }
 
 /**
- * Provide static utilities for bot conversation, including
- * - send notification to varies targets (e.g., member, channel, incoming wehbook)
- * - handle command and response.
- *
- * @example
- * Here's an example on how to send notification via Teams Bot.
- * ```typescript
- * // initialize (it's recommended to be called before handling any bot message)
- * const notificationBot = new NotificationBot(adapter);
- *
- * // get all bot installations and send message
- * for (const target of await notificationBot.installations()) {
- *   await target.sendMessage("Hello Notification");
- * }
- *
- * // alternative - send message to all members
- * for (const target of await notificationBot.installations()) {
- *   for (const member of await target.members()) {
- *     await member.sendMessage("Hello Notification");
- *   }
- * }
- * ```
+ * Provide utilities to send notification to varies targets (e.g., member, channel, incoming wehbook).
  *
  * @beta
  */
@@ -819,7 +1010,7 @@ export declare interface NotificationTarget {
  *
  * @beta
  */
-declare interface NotificationTargetStorage {
+export declare interface NotificationTargetStorage {
     /**
      * Read one notification target by its key.
      *
@@ -1407,17 +1598,17 @@ export declare class TeamsFx implements TeamsFxConfiguration {
  */
 export declare interface TeamsFxBotCommandHandler {
     /**
-     * The command name or RegExp pattern that can trigger this handler.
+     * The string or regular expression patterns that can trigger this handler.
      */
-    commandNameOrPattern: string | RegExp;
+    triggerPatterns: TriggerPatterns;
     /**
      * Handles a bot command received activity.
      *
      * @param context The bot context.
-     * @param receivedText The command text the user types from Teams.
+     * @param message The command message the user types from Teams.
      * @returns A `Promise` representing an activity or text to send as the command response.
      */
-    handleCommandReceived(context: TurnContext, receivedText: string): Promise<string | Partial<Activity>>;
+    handleCommandReceived(context: TurnContext, message: CommandMessage): Promise<string | Partial<Activity>>;
 }
 
 /**
@@ -1540,6 +1731,11 @@ export declare class TeamsUserCredential implements TokenCredential {
     getUserInfo(): Promise<UserInfo>;
 }
 
+/**
+ * The trigger pattern used to trigger a {@link TeamsFxBotCommandHandler} instance.
+ */
+export declare type TriggerPatterns = string | RegExp | (string | RegExp)[];
+
 /**
  * UserInfo with user displayName, objectId and preferredUserName.
  *