@microsoft/teamsfx 0.5.1 → 0.5.2-alpha.0535e2d27.0

package/types/teamsfx.d.ts

@@ -9,6 +9,73 @@ import { GetTokenOptions } from '@azure/identity';
 import { TokenCredential } from '@azure/identity';
 import { TokenResponse } from 'botframework-schema';
 
+/**
+ * Represent Microsoft 365 tenant identity, and it is usually used when user is not involved like time-triggered automation job.
+ *
+ * @example
+ * ```typescript
+ * loadConfiguration(); // load configuration from environment variables
+ * const credential = new AppCredential();
+ * ```
+ *
+ * @remarks
+ * Only works in in server side.
+ *
+ * @beta
+ */
+export declare class AppCredential implements TokenCredential {
+    private readonly msalClient;
+    /**
+     * Constructor of AppCredential.
+     *
+     * @remarks
+     * Only works in in server side.
+     *
+     * @param {AuthenticationConfiguration} authConfig - The authentication configuration. Use environment variables if not provided.
+     *
+     * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret or tenant id is not found in config.
+     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
+     *
+     * @beta
+     */
+    constructor(authConfig: AuthenticationConfiguration);
+    /**
+     * Get access token for credential.
+     *
+     * @example
+     * ```typescript
+     * await credential.getToken(["User.Read.All"]) // Get Graph access token for single scope using string array
+     * await credential.getToken("User.Read.All") // Get Graph access token for single scope using string
+     * await credential.getToken(["User.Read.All", "Calendars.Read"]) // Get Graph access token for multiple scopes using string array
+     * await credential.getToken("User.Read.All Calendars.Read") // Get Graph access token for multiple scopes using space-separated string
+     * await credential.getToken("https://graph.microsoft.com/User.Read.All") // Get Graph access token with full resource URI
+     * await credential.getToken(["https://outlook.office.com/Mail.Read"]) // Get Outlook access token
+     * ```
+     *
+     * @param {string | string[]} scopes - The list of scopes for which the token will have access.
+     * @param {GetTokenOptions} options - The options used to configure any requests this TokenCredential implementation might make.
+     *
+     * @throws {@link ErrorCode|ServiceError} when get access token with authentication error.
+     * @throws {@link ErrorCode|InternalError} when get access token with unknown error.
+     * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
+     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
+     *
+     * @returns Access token with expected scopes.
+     * Throw error if get access token failed.
+     *
+     * @beta
+     */
+    getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
+    /**
+     * Load and validate authentication configuration
+     *
+     * @param {AuthenticationConfiguration} authConfig - The authentication configuration. Use environment variables if not provided.
+     *
+     * @returns Authentication configuration
+     */
+    private loadAndValidateConfig;
+}
+
 /**
  * Authentication related configuration.
  * @beta
@@ -44,12 +111,6 @@ export declare interface AuthenticationConfiguration {
      * @readonly
      */
     readonly certificateContent?: string;
-    /**
-     * Endpoint of auth service provisioned by Teams Framework. Default value comes from SIMPLE_AUTH_ENDPOINT environment variable.
-     *
-     * @readonly
-     */
-    readonly simpleAuthEndpoint?: string;
     /**
      * Login page for Teams to redirect to.  Default value comes from INITIATE_LOGIN_ENDPOINT environment variable.
      *
@@ -62,25 +123,6 @@ export declare interface AuthenticationConfiguration {
     readonly applicationIdUri?: string;
 }
 
-/**
- * Configuration for current environment.
- * @beta
- */
-export declare interface Configuration {
-    /**
-     * Authentication related configuration.
-     *
-     * @readonly
-     */
-    readonly authentication?: AuthenticationConfiguration;
-    /**
-     * Configuration for resources.
-     *
-     * @readonly
-     */
-    readonly resources?: ResourceConfiguration[];
-}
-
 /**
  * Get Microsoft graph client.
  *
@@ -123,7 +165,7 @@ export declare interface Configuration {
  * }
  * ```
  *
- * @param {TokenCredential} credential - token credential instance.
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth.
  * @param scopes - The array of Microsoft Token scope of access. Default value is `[.default]`.
  *
  * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
@@ -132,71 +174,7 @@ export declare interface Configuration {
  *
  * @beta
  */
-export declare function createMicrosoftGraphClient(credential: TokenCredential, scopes?: string | string[]): Client;
-
-/**
- * SQL connection configuration instance.
- * @remarks
- * Only works in in server side.
- *
- * @beta
- *
- */
-export declare class DefaultTediousConnectionConfiguration {
-    /**
-     * MSSQL default scope
-     * https://docs.microsoft.com/en-us/azure/app-service/app-service-web-tutorial-connect-msi
-     */
-    private readonly defaultSQLScope;
-    /**
-     * Generate connection configuration consumed by tedious.
-     *
-     * @param { string? } databaseName - specify database name to override default one if there are multiple databases.
-     *
-     * @returns Connection configuration of tedious for the SQL.
-     *
-     * @throws {@link ErrorCode|InvalidConfiguration} when SQL config resource configuration is invalid.
-     * @throws {@link ErrorCode|InternalError} when get user MSI token failed or MSI token is invalid.
-     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
-     *
-     * @beta
-     */
-    getConfig(databaseName?: string): Promise<ConnectionConfig>;
-    /**
-     * Check SQL use MSI identity or username and password.
-     *
-     * @returns false - login with SQL MSI identity, true - login with username and password.
-     * @internal
-     */
-    private isMsiAuthentication;
-    /**
-     * check configuration is an available configurations.
-     * @param { SqlConfiguration } sqlConfig
-     *
-     * @returns true - SQL configuration has a valid SQL endpoints, SQL username with password or identity ID.
-     *          false - configuration is not valid.
-     * @internal
-     */
-    private isSQLConfigurationValid;
-    /**
-     * Generate tedious connection configuration with default authentication type.
-     *
-     * @param { SqlConfiguration } SQL configuration with username and password.
-     *
-     * @returns Tedious connection configuration with username and password.
-     * @internal
-     */
-    private generateDefaultConfig;
-    /**
-     * Generate tedious connection configuration with azure-active-directory-access-token authentication type.
-     *
-     * @param { SqlConfiguration } SQL configuration with AAD access token.
-     *
-     * @returns Tedious connection configuration with access token.
-     * @internal
-     */
-    private generateTokenConfig;
-}
+export declare function createMicrosoftGraphClient(teamsfx: TeamsFxConfiguration, scopes?: string | string[]): Client;
 
 /**
  * Error code to trace the error types.
@@ -250,7 +228,11 @@ export declare enum ErrorCode {
     /**
      * Invalid response error.
      */
-    InvalidResponse = "InvalidResponse"
+    InvalidResponse = "InvalidResponse",
+    /**
+     * Identity type error.
+     */
+    IdentityTypeNotSupported = "IdentityTypeNotSupported"
 }
 
 /**
@@ -276,17 +258,6 @@ export declare class ErrorWithCode extends Error {
     constructor(message?: string, code?: ErrorCode);
 }
 
-/**
- * Get configuration for authentication.
- *
- * @returns Authentication configuration from global configuration instance, the value may be undefined if no authentication config exists in current environment.
- *
- * @throws {@link ErrorCode|InvalidConfiguration} when global configuration does not exist
- *
- * @beta
- */
-export declare function getAuthenticationConfiguration(): AuthenticationConfiguration | undefined;
-
 /**
  * Get log level.
  *
@@ -297,30 +268,36 @@ export declare function getAuthenticationConfiguration(): AuthenticationConfigur
 export declare function getLogLevel(): LogLevel | undefined;
 
 /**
- * Get configuration for a specific resource.
- * @param {ResourceType} resourceType - The type of resource
- * @param {string} resourceName - The name of resource, default value is "default".
+ * Generate connection configuration consumed by tedious.
+ *
+ * @param {TeamsFx} teamsfx - Used to provide configuration and auth
+ * @param { string? } databaseName - specify database name to override default one if there are multiple databases.
  *
- * @returns Resource configuration for target resource from global configuration instance.
+ * @returns Connection configuration of tedious for the SQL.
  *
- * @throws {@link ErrorCode|InvalidConfiguration} when resource configuration with the specific type and name is not found
+ * @throws {@link ErrorCode|InvalidConfiguration} when SQL config resource configuration is invalid.
+ * @throws {@link ErrorCode|InternalError} when get user MSI token failed or MSI token is invalid.
+ * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is browser.
  *
  * @beta
  */
-export declare function getResourceConfiguration(resourceType: ResourceType, resourceName?: string): {
-    [index: string]: any;
-};
+export declare function getTediousConnectionConfig(teamsfx: TeamsFx, databaseName?: string): Promise<ConnectionConfig>;
 
 /**
- * Initialize configuration from environment variables or configuration object and set the global instance
- *
- * @param {Configuration} configuration - Optional configuration that overrides the default configuration values. The override depth is 1.
- *
- * @throws {@link ErrorCode|InvalidParameter} when configuration is not passed in browser environment
+ * Identity type to use in authentication.
  *
  * @beta
  */
-export declare function loadConfiguration(configuration?: Configuration): void;
+export declare enum IdentityType {
+    /**
+     * Represents the current user of Teams.
+     */
+    User = "User",
+    /**
+     * Represents the application itself.
+     */
+    App = "Application"
+}
 
 /**
  * Log function for customized logging.
@@ -376,80 +353,18 @@ export declare enum LogLevel {
     Error = 3
 }
 
-/**
- * Represent Microsoft 365 tenant identity, and it is usually used when user is not involved like time-triggered automation job.
- *
- * @example
- * ```typescript
- * loadConfiguration(); // load configuration from environment variables
- * const credential = new M365TenantCredential();
- * ```
- *
- * @remarks
- * Only works in in server side.
- *
- * @beta
- */
-export declare class M365TenantCredential implements TokenCredential {
-    private readonly msalClient;
-    /**
-     * Constructor of M365TenantCredential.
-     *
-     * @remarks
-     * Only works in in server side.
-     *
-     * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret or tenant id is not found in config.
-     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
-     *
-     * @beta
-     */
-    constructor();
-    /**
-     * Get access token for credential.
-     *
-     * @example
-     * ```typescript
-     * await credential.getToken(["User.Read.All"]) // Get Graph access token for single scope using string array
-     * await credential.getToken("User.Read.All") // Get Graph access token for single scope using string
-     * await credential.getToken(["User.Read.All", "Calendars.Read"]) // Get Graph access token for multiple scopes using string array
-     * await credential.getToken("User.Read.All Calendars.Read") // Get Graph access token for multiple scopes using space-separated string
-     * await credential.getToken("https://graph.microsoft.com/User.Read.All") // Get Graph access token with full resource URI
-     * await credential.getToken(["https://outlook.office.com/Mail.Read"]) // Get Outlook access token
-     * ```
-     *
-     * @param {string | string[]} scopes - The list of scopes for which the token will have access.
-     * @param {GetTokenOptions} options - The options used to configure any requests this TokenCredential implementation might make.
-     *
-     * @throws {@link ErrorCode|ServiceError} when get access token with authentication error.
-     * @throws {@link ErrorCode|InternalError} when get access token with unknown error.
-     * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
-     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
-     *
-     * @returns Access token with expected scopes.
-     * Throw error if get access token failed.
-     *
-     * @beta
-     */
-    getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
-    /**
-     * Load and validate authentication configuration
-     * @returns Authentication configuration
-     */
-    private loadAndValidateConfig;
-}
-
 /**
  * Microsoft Graph auth provider for Teams Framework
  *
  * @beta
  */
 export declare class MsGraphAuthProvider implements AuthenticationProvider {
-    private credential;
+    private teamsfx;
     private scopes;
     /**
      * Constructor of MsGraphAuthProvider.
      *
-     * @param {TokenCredential} credential - Credential used to invoke Microsoft Graph APIs.
+     * @param {TeamsFx} teamsfx - Used to provide configuration and auth.
      * @param {string | string[]} scopes - The list of scopes for which the token will have access.
      *
      * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
@@ -458,7 +373,7 @@ export declare class MsGraphAuthProvider implements AuthenticationProvider {
      *
      * @beta
      */
-    constructor(credential: TokenCredential, scopes?: string | string[]);
+    constructor(teamsfx: TeamsFxConfiguration, scopes?: string | string[]);
     /**
      * Get access token for Microsoft Graph API requests.
      *
@@ -479,7 +394,6 @@ export declare class MsGraphAuthProvider implements AuthenticationProvider {
  *
  * @example
  * ```typescript
- * loadConfiguration(); // load configuration from environment variables
  * const credential = new OnBehalfOfUserCredential(ssoToken);
  * ```
  *
@@ -498,6 +412,7 @@ export declare class OnBehalfOfUserCredential implements TokenCredential {
      * Only works in in server side.
      *
      * @param {string} ssoToken - User token provided by Teams SSO feature.
+     * @param {AuthenticationConfiguration} config - The authentication configuration. Use environment variables if not provided.
      *
      * @throws {@link ErrorCode|InvalidConfiguration} when client id, client secret, certificate content, authority host or tenant id is not found in config.
      * @throws {@link ErrorCode|InternalError} when SSO token is not valid.
@@ -505,7 +420,7 @@ export declare class OnBehalfOfUserCredential implements TokenCredential {
      *
      * @beta
      */
-    constructor(ssoToken: string);
+    constructor(ssoToken: string, config: AuthenticationConfiguration);
     /**
      * Get access token from credential.
      *
@@ -561,50 +476,6 @@ export declare class OnBehalfOfUserCredential implements TokenCredential {
     private generateAuthServerError;
 }
 
-/**
- * Configuration for resources.
- * @beta
- */
-export declare interface ResourceConfiguration {
-    /**
-     * Resource type.
-     *
-     * @readonly
-     */
-    readonly type: ResourceType;
-    /**
-     * Resource name.
-     *
-     * @readonly
-     */
-    readonly name: string;
-    /**
-     * Config for the resource.
-     *
-     * @readonly
-     */
-    readonly properties: {
-        [index: string]: any;
-    };
-}
-
-/**
- * Available resource type.
- * @beta
- */
-export declare enum ResourceType {
-    /**
-     * SQL database.
-     *
-     */
-    SQL = 0,
-    /**
-     * Rest API.
-     *
-     */
-    API = 1
-}
-
 /**
  * Set custom log function. Use the function if it's set. Priority is lower than setLogger.
  *
@@ -677,7 +548,6 @@ export declare function setLogLevel(level: LogLevel): void;
  * const dialogState = convoState.createProperty('dialogState');
  * const dialogs = new DialogSet(dialogState);
  *
- * loadConfiguration();
  * dialogs.add(new TeamsBotSsoPrompt('TeamsBotSsoPrompt', {
  *    scopes: ["User.Read"],
  * }));
@@ -703,10 +573,12 @@ export declare function setLogLevel(level: LogLevel): void;
  * @beta
  */
 export declare class TeamsBotSsoPrompt extends Dialog {
+    private teamsfx;
     private settings;
     /**
      * Constructor of TeamsBotSsoPrompt.
      *
+     * @param {TeamsFx} teamsfx - Used to provide configuration and auth
      * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
      * @param settings Settings used to configure the prompt.
      *
@@ -715,7 +587,7 @@ export declare class TeamsBotSsoPrompt extends Dialog {
      *
      * @beta
      */
-    constructor(dialogId: string, settings: TeamsBotSsoPromptSettings);
+    constructor(teamsfx: TeamsFx, dialogId: string, settings: TeamsBotSsoPromptSettings);
     /**
      * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
      * @remarks
@@ -752,6 +624,7 @@ export declare class TeamsBotSsoPrompt extends Dialog {
      * @beta
      */
     continueDialog(dc: DialogContext): Promise<DialogTurnResult>;
+    private loadAndValidateConfig;
     /**
      * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
      * @param dc dialog context
@@ -836,6 +709,187 @@ export declare interface TeamsBotSsoPromptTokenResponse extends TokenResponse {
     ssoTokenExpiration: string;
 }
 
+/**
+ * A class providing credential and configuration.
+ * @beta
+ */
+export declare class TeamsFx implements TeamsFxConfiguration {
+    private configuration;
+    private oboUserCredential?;
+    private appCredential?;
+    private identityType;
+    /**
+     * Constructor of TeamsFx
+     *
+     * @param {IdentityType} identityType - Choose user or app identity
+     * @param customConfig - key/value pairs of customized configuration that overrides default ones.
+     *
+     * @throws {@link ErrorCode|IdentityTypeNotSupported} when setting app identity in browser.
+     *
+     * @beta
+     */
+    constructor(identityType?: IdentityType, customConfig?: Record<string, string>);
+    /**
+     * Identity type set by user.
+     *
+     * @returns identity type.
+     * @beta
+     */
+    getIdentityType(): IdentityType;
+    /**
+     * Credential instance according to identity type choice.
+     *
+     * @remarks If user identity is chose, will return {@link TeamsUserCredential}
+     * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
+     * identity is chose, will return {@link AppCredential}.
+     *
+     * @returns instance implements TokenCredential interface.
+     * @beta
+     */
+    getCredential(): TokenCredential;
+    /**
+     * Get user information.
+     * @returns UserInfo object.
+     * @beta
+     */
+    getUserInfo(): Promise<UserInfo>;
+    /**
+     * Popup login page to get user's access token with specific scopes.
+     *
+     * @remarks
+     * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
+     *
+     * @example
+     * ```typescript
+     * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
+     * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
+     * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
+     * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
+     * ```
+     * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
+     *
+     * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
+     * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
+     * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
+     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
+     *
+     * @beta
+     */
+    login(scopes: string | string[]): Promise<void>;
+    /**
+     * Set SSO token when using user identity in NodeJS.
+     * @param {string} ssoToken - used for on behalf of user flow.
+     * @returns self instance.
+     * @beta
+     */
+    setSsoToken(ssoToken: string): TeamsFx;
+    /**
+     * Usually used by service plugins to retrieve specific config
+     * @param {string} key - configuration key.
+     * @returns value in configuration.
+     * @beta
+     */
+    getConfig(key: string): string;
+    /**
+     * Check the value of specific key.
+     * @param {string} key - configuration key.
+     * @returns true if corresponding value is not empty string.
+     * @beta
+     */
+    hasConfig(key: string): boolean;
+    /**
+     * Get all configurations.
+     * @returns key value mappings.
+     * @beta
+     */
+    getConfigs(): Record<string, string>;
+    /**
+     * Load configuration from environment variables.
+     */
+    private loadFromEnv;
+}
+
+/**
+ * TeamsFx interface that provides credential and configuration.
+ * @beta
+ */
+declare interface TeamsFxConfiguration {
+    /**
+     * Identity type set by user.
+     *
+     * @returns identity type.
+     * @beta
+     */
+    getIdentityType(): IdentityType;
+    /**
+     * Credential instance according to identity type choice.
+     *
+     * @remarks If user identity is chose, will return {@link TeamsUserCredential}
+     * in browser environment and {@link OnBehalfOfUserCredential} in NodeJS. If app
+     * identity is chose, will return {@link AppCredential}.
+     *
+     * @returns instance implements TokenCredential interface.
+     * @beta
+     */
+    getCredential(): TokenCredential;
+    /**
+     * Get user information.
+     * @returns UserInfo object.
+     * @beta
+     */
+    getUserInfo(): Promise<UserInfo>;
+    /**
+     * Popup login page to get user's access token with specific scopes.
+     *
+     * @remarks
+     * Only works in Teams client APP. User will be redirected to the authorization page to login and consent.
+     *
+     * @example
+     * ```typescript
+     * await teamsfx.login(["https://graph.microsoft.com/User.Read"]); // single scope using string array
+     * await teamsfx.login("https://graph.microsoft.com/User.Read"); // single scopes using string
+     * await teamsfx.login(["https://graph.microsoft.com/User.Read", "Calendars.Read"]); // multiple scopes using string array
+     * await teamsfx.login("https://graph.microsoft.com/User.Read Calendars.Read"); // multiple scopes using string
+     * ```
+     * @param scopes - The list of scopes for which the token will have access, before that, we will request user to consent.
+     *
+     * @throws {@link ErrorCode|InternalError} when failed to login with unknown error.
+     * @throws {@link ErrorCode|ConsentFailed} when user canceled or failed to consent.
+     * @throws {@link ErrorCode|InvalidParameter} when scopes is not a valid string or string array.
+     * @throws {@link ErrorCode|RuntimeNotSupported} when runtime is nodeJS.
+     *
+     * @beta
+     */
+    login(scopes: string | string[]): Promise<void>;
+    /**
+     * Set SSO token when using user identity in NodeJS.
+     * @param {string} ssoToken - used for on behalf of user flow.
+     * @returns self instance.
+     * @beta
+     */
+    setSsoToken(ssoToken: string): TeamsFxConfiguration;
+    /**
+     * Usually used by service plugins to retrieve specific config
+     * @param {string} key - configuration key.
+     * @returns value in configuration.
+     * @beta
+     */
+    getConfig(key: string): string;
+    /**
+     * Check the value of specific key.
+     * @param {string} key - configuration key.
+     * @returns true if corresponding value is not empty string.
+     * @beta
+     */
+    hasConfig(key: string): boolean;
+    /**
+     * Get all configurations.
+     * @returns key value mappings.
+     * @beta
+     */
+    getConfigs(): Record<string, string>;
+}
+
 /**
  * Represent Teams current user's identity, and it is used within Teams client applications.
  *
@@ -851,7 +905,7 @@ export declare class TeamsUserCredential implements TokenCredential {
      * Can only be used within Teams.
      * @beta
      */
-    constructor();
+    constructor(authConfig: AuthenticationConfiguration);
     /**
      * Popup login page to get user's access token with specific scopes.
      * @remarks