@microsoft/teamsfx 0.6.3-alpha.8d048e1f1.0 → 0.6.3-alpha.99edddd1f.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/teamsfx",
-  "version": "0.6.3-alpha.8d048e1f1.0",
+  "version": "0.6.3-alpha.99edddd1f.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.8d048e1f1.0",
+    "@microsoft/adaptivecards-tools": "0.1.6-alpha.99edddd1f.0",
     "@microsoft/microsoft-graph-client": "^3.0.1",
     "axios": "^0.24.0",
     "botbuilder": ">=4.15.0 <5.0.0",
@@ -128,7 +128,7 @@
     "webpack": "^5.62.1",
     "yargs": "^17.2.1"
   },
-  "gitHead": "d55f232456a8deb251fe611625ca23ead1d7421a",
+  "gitHead": "61cd724dac104531901eedb4f815c19d0a7775e4",
   "publishConfig": {
     "access": "public"
   },

package/types/teamsfx.d.ts

@@ -1,3 +1,5 @@
+/// <reference types="node" />
+
 import { AccessToken } from '@azure/identity';
 import { Activity } from 'botbuilder-core';
 import { Activity as Activity_2 } from 'botbuilder';
@@ -19,11 +21,68 @@ import { GetTokenOptions } from '@azure/identity';
 import { HeroCard } from 'botbuilder';
 import { O365ConnectorCard } from 'botbuilder';
 import { ReceiptCard } from 'botbuilder';
+import { SecureContextOptions } from 'tls';
 import { TeamsChannelAccount } from 'botbuilder';
 import { ThumbnailCard } from 'botbuilder';
 import { TokenCredential } from '@azure/identity';
 import { TokenResponse } from 'botframework-schema';
 import { TurnContext } from 'botbuilder-core';
+import { TurnContext as TurnContext_2 } from 'botbuilder';
+import { WebRequest } from 'botbuilder';
+import { WebResponse } from 'botbuilder';
+
+/**
+ * Define available location for API Key location
+ *
+ * @beta
+ */
+export declare enum ApiKeyLocation {
+    /**
+     * The API Key is placed in request header
+     */
+    Header = 0,
+    /**
+     * The API Key is placed in query parameter
+     */
+    QueryParams = 1
+}
+
+/**
+ * Provider that handles API Key authentication
+ *
+ * @beta
+ */
+export declare class ApiKeyProvider implements AuthProvider {
+    private keyName;
+    private keyValue;
+    private keyLocation;
+    /**
+     *
+     * @param { string } keyName - The name of request header or query parameter that specifies API Key
+     * @param { string } keyValue - The value of API Key
+     * @param { ApiKeyLocation } keyLocation - The location of API Key: request header or query parameter.
+     *
+     * @throws {@link ErrorCode|InvalidParameter} - when key name or key value is empty.
+     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
+     *
+     * @beta
+     */
+    constructor(keyName: string, keyValue: string, keyLocation: ApiKeyLocation);
+    /**
+     * Adds authentication info to http requests
+     *
+     * @param { AxiosRequestConfig } 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.
+     *
+     * @returns Updated axios request config.
+     *
+     * @throws {@link ErrorCode|AuthorizationInfoAlreadyExists} - when API key already exists in request header or url query parameter.
+     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
+     *
+     * @beta
+     */
+    AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
+}
 
 /**
  * Represent Microsoft 365 tenant identity, and it is usually used when user is not involved like time-triggered automation job.
@@ -148,7 +207,7 @@ 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.
+     * @param { AxiosRequestConfig } 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
@@ -156,6 +215,43 @@ export declare interface AuthProvider {
     AddAuthenticationInfo: (config: AxiosRequestConfig) => Promise<AxiosRequestConfig>;
 }
 
+export { AxiosInstance }
+
+/**
+ * Provider that handles Basic authentication
+ *
+ * @beta
+ */
+export declare class BasicAuthProvider implements AuthProvider {
+    private userName;
+    private password;
+    /**
+     *
+     * @param { string } userName - Username used in basic auth
+     * @param { string } password - Password used in basic auth
+     *
+     * @throws {@link ErrorCode|InvalidParameter} - when username or password is empty.
+     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
+     *
+     * @beta
+     */
+    constructor(userName: string, password: string);
+    /**
+     * Adds authentication info to http requests
+     *
+     * @param { AxiosRequestConfig } 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.
+     *
+     * @returns Updated axios request config.
+     *
+     * @throws {@link ErrorCode|AuthorizationInfoAlreadyExists} - when Authorization header or auth property already exists in request configuration.
+     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
+     *
+     * @beta
+     */
+    AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
+}
+
 /**
  * Provider that handles Bearer Token authentication
  *
@@ -164,7 +260,7 @@ export declare interface AuthProvider {
 export declare class BearerTokenAuthProvider implements AuthProvider {
     private getToken;
     /**
-     * @param getToken Function that returns the content of bearer token used in http request
+     * @param { () => Promise<string> } getToken - Function that returns the content of bearer token used in http request
      *
      * @beta
      */
@@ -172,9 +268,44 @@ export declare class BearerTokenAuthProvider implements AuthProvider {
     /**
      * Adds authentication info to http requests
      *
-     * @param config - Contains all the request information and can be updated to include extra authentication info.
+     * @param { AxiosRequestConfig } 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.
      *
+     * @returns Updated axios request config.
+     *
+     * @throws {@link ErrorCode|AuthorizationInfoAlreadyExists} - when Authorization header already exists in request configuration.
+     *
+     * @beta
+     */
+    AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
+}
+
+/**
+ * Provider that handles Certificate authentication
+ *
+ * @beta
+ */
+export declare class CertificateAuthProvider implements AuthProvider {
+    private certOption;
+    /**
+     *
+     * @param { SecureContextOptions } certOption - information about the cert used in http requests
+     *
+     * @throws {@link ErrorCode|InvalidParameter} - when cert option is empty.
+     *
+     * @beta
+     */
+    constructor(certOption: SecureContextOptions);
+    /**
+     * Adds authentication info to http requests.
+     *
+     * @param { AxiosRequestConfig } 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.
+     *
+     * @returns Updated axios request config.
+     *
+     * @throws {@link ErrorCode|InvalidParameter} - when custom httpsAgent in the request has duplicate properties with certOption provided in constructor.
+     *
      * @beta
      */
     AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
@@ -290,7 +421,7 @@ export declare interface CommandMessage {
      */
     text: string;
     /**
-     * The capture groups that matched to the {@link triggerPatterns} in a {@link TeamsFxBotCommandHandler} instance.
+     * The capture groups that matched to the {@link TriggerPatterns} in a {@link TeamsFxBotCommandHandler} instance.
      */
     matches?: RegExpMatchArray;
 }
@@ -312,7 +443,7 @@ export declare interface CommandOptions {
 /**
  * Provide utilities for bot conversation, including:
  *   - handle command and response.
- *   - send notification to varies targets (e.g., member, channel, incoming wehbook).
+ *   - send notification to varies targets (e.g., member, group, channel).
  *
  * @example
  * 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 +453,7 @@ export declare interface CommandOptions {
  * const conversationBot = new ConversationBot({
  *   command: {
  *     enabled: true,
- *     options: {
- *         commands: [ new HelloWorldCommandHandler() ],
- *     },
+ *     commands: [ new HelloWorldCommandHandler() ],
  *   },
  * });
  *
@@ -332,7 +461,7 @@ export declare interface CommandOptions {
  * conversationBot.command.registerCommand(new HelpCommandHandler());
  * ```
  *
- * For notification, you can enable notification at initialization, then send notificaations at any time.
+ * For notification, you can enable notification at initialization, then send notifications at any time.
  *
  * ```typescript
  * // enable through constructor
@@ -360,7 +489,7 @@ export declare interface CommandOptions {
  *
  * 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.
+ * For notification, set `notification.storage` in {@link ConversationOptions} to use your own storage implementation.
  *
  * @beta
  */
@@ -386,11 +515,39 @@ export declare class ConversationBot {
     /**
      * Creates new instance of the `ConversationBot`.
      *
+     * @remarks
+     * It's recommended to create your own adapter and storage for production environment instead of the default one.
+     *
      * @param options - initialize options
      *
      * @beta
      */
     constructor(options: ConversationOptions);
+    private createDefaultAdapter;
+    /**
+     * The request handler to integrate with web request.
+     *
+     * @param req - an Express or Restify style request object.
+     * @param res - an Express or Restify style response object.
+     * @param logic - the additional function to handle bot context.
+     *
+     * @example
+     * For example, to use with Restify:
+     * ``` typescript
+     * // The default/empty behavior
+     * server.post("api/messages", conversationBot.requestHandler);
+     *
+     * // Or, add your own logic
+     * server.post("api/messages", async (req, res) => {
+     *   await conversationBot.requestHandler(req, res, async (context) => {
+     *     // your-own-context-logic
+     *   });
+     * });
+     * ```
+     *
+     * @beta
+     */
+    requestHandler(req: WebRequest, res: WebResponse, logic?: (context: TurnContext_2) => Promise<any>): Promise<void>;
 }
 
 /**
@@ -400,48 +557,52 @@ export declare class ConversationBot {
  */
 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.
+     * The bot adapter. If not provided, a default adapter will be created:
+     * - with `adapterConfig` as constructor parameter.
+     * - with a default error handler that logs error to console, sends trace activity, and sends error message to user.
+     *
+     * @remarks
+     * If neither `adapter` nor `adapterConfig` is provided, will use BOT_ID and BOT_PASSWORD from environment variables.
      *
      * @beta
      */
     adapter?: BotFrameworkAdapter;
+    /**
+     * If `adapter` is not provided, this `adapterConfig` will be passed to the new `BotFrameworkAdapter` when created internally.
+     *
+     * @remarks
+     * If neither `adapter` nor `adapterConfig` is provided, will use BOT_ID and BOT_PASSWORD from environment variables.
+     *
+     * @beta
+     */
+    adapterConfig?: {
+        [key: string]: unknown;
+    };
     /**
      * The command part.
      *
      * @beta
      */
-    command: {
+    command?: CommandOptions & {
         /**
          * Whether to enable command or not.
          *
          * @beta
          */
-        enabled: boolean;
-        /**
-         * The command options if command is enabled.
-         *
-         * @beta
-         */
-        options: CommandOptions;
+        enabled?: boolean;
     };
     /**
      * The notification part.
      *
      * @beta
      */
-    notification: {
+    notification?: NotificationOptions_2 & {
         /**
          * Whether to enable notification or not.
          *
          * @beta
          */
-        enabled: boolean;
-        /**
-         * The notification options if notification is enabled.
-         *
-         * @beta
-         */
-        options: NotificationOptions_2;
+        enabled?: boolean;
     };
 }
 
@@ -514,6 +675,38 @@ export declare function createApiClient(apiEndpoint: string, authProvider: AuthP
  */
 export declare function createMicrosoftGraphClient(teamsfx: TeamsFxConfiguration, scopes?: string | string[]): Client;
 
+/**
+ * Helper to create SecureContextOptions from PEM format cert
+ *
+ * @param { string | Buffer } cert - The cert chain in PEM format
+ * @param { string | Buffer } key - The private key for the cert chain
+ * @param { {passphrase?: string; ca?: string | Buffer} } options - Optional settings when create the cert options.
+ *
+ * @returns Instance of SecureContextOptions
+ *
+ * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
+ *
+ */
+export declare function createPemCertOption(cert: string | Buffer, key: string | Buffer, options?: {
+    passphrase?: string;
+    ca?: string | Buffer;
+}): SecureContextOptions;
+
+/**
+ * Helper to create SecureContextOptions from PFX format cert
+ *
+ * @param { string | Buffer } pfx - The content of .pfx file
+ * @param { {passphrase?: string} } options - Optional settings when create the cert options.
+ *
+ * @returns Instance of SecureContextOptions
+ *
+ * @throws {@link ErrorCode|InvalidParameter} - when any parameter is empty
+ *
+ */
+export declare function createPfxCertOption(pfx: string | Buffer, options?: {
+    passphrase?: string;
+}): SecureContextOptions;
+
 /**
  * Error code to trace the error types.
  * @beta
@@ -570,7 +763,11 @@ export declare enum ErrorCode {
     /**
      * Identity type error.
      */
-    IdentityTypeNotSupported = "IdentityTypeNotSupported"
+    IdentityTypeNotSupported = "IdentityTypeNotSupported",
+    /**
+     * Authentication info already exists error.
+     */
+    AuthorizationInfoAlreadyExists = "AuthorizationInfoAlreadyExists"
 }
 
 /**
@@ -761,8 +958,8 @@ export declare class MessageBuilder {
     /**
      * Build a bot message activity attached with adaptive card.
      *
-     * @param getCardData Function to prepare your card data.
      * @param cardTemplate The adaptive card template.
+     * @param data card data used to render the template.
      * @returns A bot message activity attached with an adaptive card.
      *
      * @example
@@ -787,16 +984,16 @@ export declare class MessageBuilder {
      *   title: string,
      *   description: string
      * };
-     * const card = MessageBuilder.attachAdaptiveCard<CardData>(() => {
-     *     return {
-     *       title: "sample card title",
-     *       description: "sample card description"
-     *     }}, cardTemplate);
+     * const card = MessageBuilder.attachAdaptiveCard<CardData>(
+     *   cardTemplate, {
+     *   title: "sample card title",
+     *   description: "sample card description"
+     * });
      * ```
      *
      * @beta
      */
-    static attachAdaptiveCard<TData>(getCardData: () => TData, cardTemplate: any): Partial<Activity_2>;
+    static attachAdaptiveCard<TData>(cardTemplate: any, data: TData): Partial<Activity_2>;
     /**
      * Build a bot message activity attached with an adaptive card.
      *
@@ -920,7 +1117,7 @@ export declare class MsGraphAuthProvider implements AuthenticationProvider {
 }
 
 /**
- * Provide utilities to send notification to varies targets (e.g., member, channel, incoming wehbook).
+ * Provide utilities to send notification to varies targets (e.g., member, group, channel).
  *
  * @beta
  */