@microsoft/applicationinsights-web-basic 2.8.0-nightly.2202-06 → 2.8.0-nightly.2204-06

package/dist/applicationinsights-web-basic.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft.ApplicationInsights, 2.8.0-nightly.2202-06
+ * Microsoft.ApplicationInsights, 2.8.0-nightly.2204-06
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -11,26 +11,6 @@ declare namespace ApplicationInsights {
         constructor();
         initialize(config: IConfiguration, extensions: IPlugin[], logger?: IDiagnosticLogger, notificationManager?: INotificationManager): void;
         track(telemetryItem: ITelemetryItem): void;
-        /**
-         * Adds a notification listener. The SDK calls methods on the listener when an appropriate notification is raised.
-         * The added plugins must raise notifications. If the plugins do not implement the notifications, then no methods will be
-         * called.
-         * @param {INotificationListener} listener - An INotificationListener object.
-         */
-        addNotificationListener(listener: INotificationListener): void;
-        /**
-         * Removes all instances of the listener.
-         * @param {INotificationListener} listener - INotificationListener to remove.
-         */
-        removeNotificationListener(listener: INotificationListener): void;
-        /**
-         * Periodically check logger.queue for
-         */
-        pollInternalLogs(eventName?: string): number;
-        /**
-         * Periodically check logger.queue for
-         */
-        stopPollingInternalLogs(): void;
     }
 
     /**
@@ -39,7 +19,6 @@ declare namespace ApplicationInsights {
      */
     class ApplicationInsights {
         config: IConfiguration & IConfig;
-        private core;
         /**
          * Creates an instance of ApplicationInsights.
          * @param {IConfiguration & IConfig} config
@@ -65,11 +44,51 @@ declare namespace ApplicationInsights {
          * @memberof ApplicationInsights
          */
         flush(async?: boolean): void;
-        private pollInternalLogs;
+        pollInternalLogs(): void;
         stopPollingInternalLogs(): void;
-        private getSKUDefaults;
+        getSKUDefaults(): void;
+        /**
+         * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
+         * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
+         * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
+         * approach is to create a new instance and initialize that instance.
+         * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
+         * to successfully remove any global references or they may just be completing the unload process asynchronously.
+         */
+        unload(isAsync?: boolean, unloadComplete?: () => void): void;
+        /**
+         * Find and return the (first) plugin with the specified identifier if present
+         * @param pluginIdentifier
+         */
+        getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+        /**
+         * Add a new plugin to the installation
+         * @param plugin - The new plugin to add
+         * @param replaceExisting - should any existing plugin be replaced
+         * @param doAsync - Should the add be performed asynchronously
+         */
+        addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
+        /**
+         * Returns the unique event namespace that should be used
+         */
+        evtNamespace(): string;
+        /**
+         * Add an unload handler that will be called when the SDK is being unloaded
+         * @param handler - the handler
+         */
+        addUnloadCb(handler: UnloadHandler): void;
     }
 
+    /**
+     * Performs the specified action for each element in an array. This helper exists to avoid adding a polyfil for older browsers
+     * that do not define Array.prototype.xxxx (eg. ES3 only, IE8) just in case any page checks for presence/absence of the prototype
+     * implementation. Note: For consistency this will not use the Array.prototype.xxxx implementation if it exists as this would
+     * cause a testing requirement to test with and without the implementations
+     * @param callbackfn  A function that accepts up to three arguments. forEach calls the callbackfn function one time for each element in the array. It can return -1 to break out of the loop
+     * @param thisArg  [Optional] An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
+     */
+    function arrForEach<T = any>(arr: T[], callbackfn: (value: T, index?: number, array?: T[]) => undefined | void | number, thisArg?: any): void;
+
     class BaseCore implements IAppInsightsCore {
         static defaultConfig: IConfiguration;
         config: IConfiguration;
@@ -82,6 +101,18 @@ declare namespace ApplicationInsights {
         track(telemetryItem: ITelemetryItem): void;
         getProcessTelContext(): IProcessTelemetryContext;
         getNotifyMgr(): INotificationManager;
+        /**
+         * Adds a notification listener. The SDK calls methods on the listener when an appropriate notification is raised.
+         * The added plugins must raise notifications. If the plugins do not implement the notifications, then no methods will be
+         * called.
+         * @param {INotificationListener} listener - An INotificationListener object.
+         */
+        addNotificationListener(listener: INotificationListener): void;
+        /**
+         * Removes all instances of the listener.
+         * @param {INotificationListener} listener - INotificationListener to remove.
+         */
+        removeNotificationListener(listener: INotificationListener): void;
         /**
          * Get the current cookie manager for this instance
          */
@@ -94,7 +125,67 @@ declare namespace ApplicationInsights {
         getPerfMgr(): IPerfManager;
         setPerfMgr(perfMgr: IPerfManager): void;
         eventCnt(): number;
+        /**
+         * Periodically check logger.queue for
+         */
+        pollInternalLogs(eventName?: string): number;
+        /**
+         * Periodically check logger.queue for
+         */
+        stopPollingInternalLogs(): void;
+        /**
+         * Add a telemetry processor to decorate or drop telemetry events.
+         * @param telemetryInitializer - The Telemetry Initializer function
+         * @returns - A ITelemetryInitializerHandler to enable the initializer to be removed
+         */
+        addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+        /**
+         * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
+         * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
+         * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
+         * approach is to create a new instance and initialize that instance.
+         * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
+         * to successfully remove any global references or they may just be completing the unload process asynchronously.
+         * @param isAsync - Can the unload be performed asynchronously (default)
+         * @param unloadComplete - An optional callback that will be called once the unload has completed
+         * @param cbTimeout - An optional timeout to wait for any flush operations to complete before proceeding with the unload. Defaults to 5 seconds.
+         */
+        unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
+        getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+        /**
+         * Add a new plugin to the installation
+         * @param plugin - The new plugin to add
+         * @param replaceExisting - should any existing plugin be replaced, default is false
+         * @param doAsync - Should the add be performed asynchronously
+         * @param addCb - [Optional] callback to call after the plugin has been added
+         */
+        addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting?: boolean, doAsync?: boolean, addCb?: (added?: boolean) => void): void;
+        /**
+         * Returns the unique event namespace that should be used
+         */
+        evtNamespace(): string;
+        /**
+         * Add an unload handler that will be called when the SDK is being unloaded
+         * @param handler - the handler
+         */
+        addUnloadCb(handler: UnloadHandler): void;
+        /**
+         * Flush and send any batched / cached data immediately
+         * @param async - send data asynchronously when true (defaults to true)
+         * @param callBack - if specified, notify caller when send is complete, the channel should return true to indicate to the caller that it will be called.
+         * If the caller doesn't return true the caller should assume that it may never be called.
+         * @param sendReason - specify the reason that you are calling "flush" defaults to ManualFlush (1) if not specified
+         * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
+         */
+        flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason): void;
         protected releaseQueue(): void;
+        /**
+         * Hook for Core extensions to allow them to update their own configuration before updating all of the plugins.
+         * @param updateCtx - The plugin update context
+         * @param updateState - The Update State
+         * @returns boolean - True means the extension class will call updateState otherwise the Core will
+         */
+        protected _updateHook?(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
     }
 
     /**
@@ -103,6 +194,13 @@ declare namespace ApplicationInsights {
      * implementation so that new default implementations can be added without breaking all plugins.
      */
     abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
+        identifier: string;
+        version?: string;
+        /**
+         * Holds the core instance that was used during initialization
+         */
+        core: IAppInsightsCore;
+        priority: number;
         /**
          * Call back for telemetry processing before it it is sent
          * @param env - This is the current event being reported
@@ -124,13 +222,6 @@ declare namespace ApplicationInsights {
          * Returns whether the plugin has been initialized
          */
         isInitialized: () => boolean;
-        identifier: string;
-        version?: string;
-        /**
-         * Holds the core instance that was used during initialization
-         */
-        core: IAppInsightsCore;
-        priority: number;
         /**
          * Helper to return the current IProcessTelemetryContext, if the passed argument exists this just
          * returns that value (helps with minification for callers), otherwise it will return the configured
@@ -143,12 +234,51 @@ declare namespace ApplicationInsights {
          */
         protected setInitialized: (isInitialized: boolean) => void;
         /**
-         * Internal helper to initialize the instance
+         * Teardown / Unload hook to allow implementations to perform some additional unload operations before the BaseTelemetryPlugin
+         * finishes it's removal.
+         * @param unloadCtx - This is the context that should be used during unloading.
+         * @param unloadState - The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.
+         * @param asyncCallback - An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async unload/teardown operations.
+         * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
+         */
+        protected _doTeardown?: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: () => void) => void | boolean;
+        /**
+         * Extension hook to allow implementations to perform some additional update operations before the BaseTelemetryPlugin finishes it's removal
+         * @param updateCtx - This is the context that should be used during updating.
+         * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+         * @param asyncCallback - An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async update operations.
+         * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
          */
-        private _baseTelInit;
+        protected _doUpdate?: (updateCtx?: IProcessTelemetryUpdateContext, updateState?: ITelemetryUpdateState, asyncCallback?: () => void) => void | boolean;
         constructor();
         initialize(config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
+        /**
+         * Tear down the plugin and remove any hooked value, the plugin should be removed so that it is no longer initialized and
+         * therefore could be re-initialized after being torn down. The plugin should ensure that once this has been called any further
+         * processTelemetry calls are ignored and it just calls the processNext() with the provided context.
+         * @param unloadCtx - This is the context that should be used during unloading.
+         * @param unloadState - The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.
+         * @returns boolean - true if the plugin has or will call processNext(), this for backward compatibility as previously teardown was synchronous and returned nothing.
+         */
+        teardown(unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState): void | boolean;
         abstract processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
+        /**
+         * The the plugin should re-evaluate configuration and update any cached configuration settings.
+         * @param updateCtx - This is the context that should be used during updating.
+         * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+         * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
+         */
+        update(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
+        /**
+         * Add an unload handler that will be called when the SDK is being unloaded
+         * @param handler - the handler
+         */
+        protected _addUnloadCb(handler: UnloadHandler): void;
+        /**
+         * Add this hook so that it is automatically removed during unloading
+         * @param hooks - The single hook or an array of IInstrumentHook objects
+         */
+        protected _addHook(hooks: IInstrumentHook | IInstrumentHook[]): void;
     }
 
     /**
@@ -159,7 +289,15 @@ declare namespace ApplicationInsights {
      */
     const CoreUtils: ICoreUtils;
 
-    enum DistributedTracingModes {
+    const DistributedTracingModes: EnumValue<    {
+    AI: number;
+    AI_AND_W3C: number;
+    W3C: number;
+    }>;
+
+    type DistributedTracingModes = number | eDistributedTracingModes;
+
+    const enum eDistributedTracingModes {
         /**
          * (Default) Send Application Insights correlation headers
          */
@@ -174,6 +312,112 @@ declare namespace ApplicationInsights {
         W3C = 2
     }
 
+    const enum _eInternalMessageId {
+        BrowserDoesNotSupportLocalStorage = 0,
+        BrowserCannotReadLocalStorage = 1,
+        BrowserCannotReadSessionStorage = 2,
+        BrowserCannotWriteLocalStorage = 3,
+        BrowserCannotWriteSessionStorage = 4,
+        BrowserFailedRemovalFromLocalStorage = 5,
+        BrowserFailedRemovalFromSessionStorage = 6,
+        CannotSendEmptyTelemetry = 7,
+        ClientPerformanceMathError = 8,
+        ErrorParsingAISessionCookie = 9,
+        ErrorPVCalc = 10,
+        ExceptionWhileLoggingError = 11,
+        FailedAddingTelemetryToBuffer = 12,
+        FailedMonitorAjaxAbort = 13,
+        FailedMonitorAjaxDur = 14,
+        FailedMonitorAjaxOpen = 15,
+        FailedMonitorAjaxRSC = 16,
+        FailedMonitorAjaxSend = 17,
+        FailedMonitorAjaxGetCorrelationHeader = 18,
+        FailedToAddHandlerForOnBeforeUnload = 19,
+        FailedToSendQueuedTelemetry = 20,
+        FailedToReportDataLoss = 21,
+        FlushFailed = 22,
+        MessageLimitPerPVExceeded = 23,
+        MissingRequiredFieldSpecification = 24,
+        NavigationTimingNotSupported = 25,
+        OnError = 26,
+        SessionRenewalDateIsZero = 27,
+        SenderNotInitialized = 28,
+        StartTrackEventFailed = 29,
+        StopTrackEventFailed = 30,
+        StartTrackFailed = 31,
+        StopTrackFailed = 32,
+        TelemetrySampledAndNotSent = 33,
+        TrackEventFailed = 34,
+        TrackExceptionFailed = 35,
+        TrackMetricFailed = 36,
+        TrackPVFailed = 37,
+        TrackPVFailedCalc = 38,
+        TrackTraceFailed = 39,
+        TransmissionFailed = 40,
+        FailedToSetStorageBuffer = 41,
+        FailedToRestoreStorageBuffer = 42,
+        InvalidBackendResponse = 43,
+        FailedToFixDepricatedValues = 44,
+        InvalidDurationValue = 45,
+        TelemetryEnvelopeInvalid = 46,
+        CreateEnvelopeError = 47,
+        CannotSerializeObject = 48,
+        CannotSerializeObjectNonSerializable = 49,
+        CircularReferenceDetected = 50,
+        ClearAuthContextFailed = 51,
+        ExceptionTruncated = 52,
+        IllegalCharsInName = 53,
+        ItemNotInArray = 54,
+        MaxAjaxPerPVExceeded = 55,
+        MessageTruncated = 56,
+        NameTooLong = 57,
+        SampleRateOutOfRange = 58,
+        SetAuthContextFailed = 59,
+        SetAuthContextFailedAccountName = 60,
+        StringValueTooLong = 61,
+        StartCalledMoreThanOnce = 62,
+        StopCalledWithoutStart = 63,
+        TelemetryInitializerFailed = 64,
+        TrackArgumentsNotSpecified = 65,
+        UrlTooLong = 66,
+        SessionStorageBufferFull = 67,
+        CannotAccessCookie = 68,
+        IdTooLong = 69,
+        InvalidEvent = 70,
+        FailedMonitorAjaxSetRequestHeader = 71,
+        SendBrowserInfoOnUserInit = 72,
+        PluginException = 73,
+        NotificationException = 74,
+        SnippetScriptLoadFailure = 99,
+        InvalidInstrumentationKey = 100,
+        CannotParseAiBlobValue = 101,
+        InvalidContentBlob = 102,
+        TrackPageActionEventFailed = 103,
+        FailedAddingCustomDefinedRequestContext = 104,
+        InMemoryStorageBufferFull = 105
+    }
+
+    const enum eLoggingSeverity {
+        /**
+         * Error will be sent as internal telemetry
+         */
+        CRITICAL = 1,
+        /**
+         * Error will NOT be sent as internal telemetry, and will only be shown in browser console
+         */
+        WARNING = 2
+    }
+
+    type EnumValue<E = any> = {
+        readonly [key in keyof E]: E[key];
+    };
+
+    const enum GetExtCfgMergeType {
+        None = 0,
+        MergeDefaultOnly = 1,
+        MergeDefaultFromRootOrDefault = 2
+    }
+
     interface IAppInsightsCore extends IPerfManagerProvider {
         config: IConfiguration;
         logger: IDiagnosticLogger;
@@ -209,12 +453,62 @@ declare namespace ApplicationInsights {
          * @param {INotificationListener} listener - INotificationListener to remove.
          */
         removeNotificationListener?(listener: INotificationListener): void;
+        /**
+         * Add a telemetry processor to decorate or drop telemetry events.
+         * @param telemetryInitializer - The Telemetry Initializer function
+         * @returns - A ITelemetryInitializerHandler to enable the initializer to be removed
+         */
+        addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
         pollInternalLogs?(eventName?: string): number;
         stopPollingInternalLogs?(): void;
         /**
          * Return a new instance of the IProcessTelemetryContext for processing events
          */
         getProcessTelContext(): IProcessTelemetryContext;
+        /**
+         * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
+         * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
+         * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
+         * approach is to create a new instance and initialize that instance.
+         * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
+         * to successfully remove any global references or they may just be completing the unload process asynchronously.
+         * @param isAsync - Can the unload be performed asynchronously (default)
+         * @param unloadComplete - An optional callback that will be called once the unload has completed
+         * @param cbTimeout - An optional timeout to wait for any flush operations to complete before proceeding with the unload. Defaults to 5 seconds.
+         */
+        unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
+        /**
+         * Find and return the (first) plugin with the specified identifier if present
+         * @param pluginIdentifier
+         */
+        getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+        /**
+         * Add a new plugin to the installation
+         * @param plugin - The new plugin to add
+         * @param replaceExisting - should any existing plugin be replaced, default is false
+         * @param doAsync - Should the add be performed asynchronously
+         * @param addCb - [Optional] callback to call after the plugin has been added
+         */
+        addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting?: boolean, doAsync?: boolean, addCb?: (added?: boolean) => void): void;
+        /**
+         * Returns the unique event namespace that should be used when registering events
+         */
+        evtNamespace(): string;
+        /**
+         * Add a handler that will be called when the SDK is being unloaded
+         * @param handler - the handler
+         */
+        addUnloadCb(handler: UnloadHandler): void;
+        /**
+         * Flush and send any batched / cached data immediately
+         * @param async - send data asynchronously when true (defaults to true)
+         * @param callBack - if specified, notify caller when send is complete, the channel should return true to indicate to the caller that it will be called.
+         * If the caller doesn't return true the caller should assume that it may never be called.
+         * @param sendReason - specify the reason that you are calling "flush" defaults to ManualFlush (1) if not specified
+         * @param cbTimeout - An optional timeout to wait for any flush operations to complete before proceeding with the unload. Defaults to 5 seconds.
+         * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
+         */
+        flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason, cbTimeout?: number): boolean | void;
     }
 
     /**
@@ -298,6 +592,67 @@ declare namespace ApplicationInsights {
         readonly appId?: string;
     }
 
+    interface IBaseProcessingContext {
+        /**
+         * The current core instance for the request
+         */
+        core: () => IAppInsightsCore;
+        /**
+         * THe current diagnostic logger for the request
+         */
+        diagLog: () => IDiagnosticLogger;
+        /**
+         * Gets the current core config instance
+         */
+        getCfg: () => IConfiguration;
+        /**
+         * Gets the named extension config
+         */
+        getExtCfg: <T>(identifier: string, defaultValue?: T | any, mergeDefault?: GetExtCfgMergeType) => T;
+        /**
+         * Gets the named config from either the named identifier extension or core config if neither exist then the
+         * default value is returned
+         * @param identifier The named extension identifier
+         * @param field The config field name
+         * @param defaultValue The default value to return if no defined config exists
+         */
+        getConfig: (identifier: string, field: string, defaultValue?: number | string | boolean | string[] | RegExp[] | Function) => number | string | boolean | string[] | RegExp[] | Function;
+        /**
+         * Helper to allow plugins to check and possibly shortcut executing code only
+         * required if there is a nextPlugin
+         */
+        hasNext: () => boolean;
+        /**
+         * Returns the next configured plugin proxy
+         */
+        getNext: () => ITelemetryPluginChain;
+        /**
+         * Helper to set the next plugin proxy
+         */
+        setNext: (nextCtx: ITelemetryPluginChain) => void;
+        /**
+         * Synchronously iterate over the context chain running the callback for each plugin, once
+         * every plugin has been executed via the callback, any associated onComplete will be called.
+         * @param callback - The function call for each plugin in the context chain
+         */
+        iterate: <T extends ITelemetryPlugin = ITelemetryPlugin>(callback: (plugin: T) => void) => void;
+        /**
+         * Set the function to call when the current chain has executed all processNext or unloadNext items.
+         * @param onComplete - The onComplete to call
+         * @param that - The "this" value to use for the onComplete call, if not provided or undefined defaults to the current context
+         * @param args - Any additional arguments to pass to the onComplete function
+         */
+        onComplete: (onComplete: () => void, that?: any, ...args: any[]) => void;
+        /**
+         * Create a new context using the core and config from the current instance, returns a new instance of the same type
+         * @param plugins - The execution order to process the plugins, if null or not supplied
+         *                  then the current execution order will be copied.
+         * @param startAt - The plugin to start processing from, if missing from the execution
+         *                  order then the next plugin will be NOT set.
+         */
+        createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IBaseProcessingContext;
+    }
+
     /**
      * Provides data transmission capabilities
      */
@@ -311,15 +666,23 @@ declare namespace ApplicationInsights {
          */
         resume(): void;
         /**
-         * Tear down transmission pipeline
+         * Tear down the plugin and remove any hooked value, the plugin should be removed so that it is no longer initialized and
+         * therefore could be re-initialized after being torn down. The plugin should ensure that once this has been called any further
+         * processTelemetry calls are ignored and it just calls the processNext() with the provided context.
+         * @param unloadCtx - This is the context that should be used during unloading.
+         * @param unloadState - The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.
+         * @returns boolean - true if the plugin has or will call processNext(), this for backward compatibility as previously teardown was synchronous and returned nothing.
          */
-        teardown(): void;
+        teardown: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState) => void | boolean;
         /**
          * Flush to send data immediately; channel should default to sending data asynchronously
-         * @param async: send data asynchronously when true
-         * @param callBack: if specified, notify caller when send is complete
+         * @param async - send data asynchronously when true
+         * @param callBack - if specified, notify caller when send is complete, the channel should return true to indicate to the caller that it will be called.
+         * If the caller doesn't return true the caller should assume that it may never be called.
+         * @param sendReason - specify the reason that you are calling "flush" defaults to ManualFlush (1) if not specified
+         * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
          */
-        flush(async: boolean, callBack?: () => void): void;
+        flush(async: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason): boolean | void;
     }
 
     interface IChannelControlsAI extends IChannelControls {
@@ -994,7 +1357,7 @@ declare namespace ApplicationInsights {
          * @param callback {any} - The callback function that needs to be executed for the given event
          * @return {boolean} - true if the handler was successfully added
          */
-        addEventHandler: (eventName: string, callback: any) => boolean;
+        addEventHandler: (eventName: string, callback: any, evtNamespace?: string | string[]) => boolean;
         /**
          * Return the current time via the Date now() function (if available) and falls back to (new Date()).getTime() if now() is unavailable (IE8 or less)
          * https://caniuse.com/#search=Date.now
@@ -1127,15 +1490,39 @@ declare namespace ApplicationInsights {
     }
 
     interface IEnvelope extends ISerializable {
+        /**
+         * Envelope version. For internal use only. By assigning this the default, it will not be serialized within the payload unless changed to a value other than #1.
+         */
         ver: number;
+        /**
+         * Type name of telemetry data item.
+         */
         name: string;
+        /**
+         * Event date time when telemetry item was created. This is the wall clock time on the client when the event was generated. There is no guarantee that the client's time is accurate. This field must be formatted in UTC ISO 8601 format, with a trailing 'Z' character, as described publicly on https://en.wikipedia.org/wiki/ISO_8601#UTC. Note: the number of decimal seconds digits provided are variable (and unspecified). Consumers should handle this, i.e. managed code consumers should not use format 'O' for parsing as it specifies a fixed length. Example: 2009-06-15T13:45:30.0000000Z.
+         */
         time: string;
+        /**
+         * Sampling rate used in application. This telemetry item represents 1 / sampleRate actual telemetry items.
+         */
         sampleRate: number;
+        /**
+         * Sequence field used to track absolute order of uploaded events.
+         */
         seq: string;
+        /**
+         * The application's instrumentation key. The key is typically represented as a GUID, but there are cases when it is not a guid. No code should rely on iKey being a GUID. Instrumentation key is case insensitive.
+         */
         iKey: string;
+        /**
+         * Key/value collection of context properties. See ContextTagKeys for information on available properties.
+         */
         tags: {
             [name: string]: any;
         };
+        /**
+         * Telemetry data item.
+         */
         data: any;
     }
 
@@ -1154,6 +1541,96 @@ declare namespace ApplicationInsights {
         iKey?: string;
     }
 
+    interface IInstrumentCallDetails {
+        name: string;
+        inst: any;
+        /**
+         * This returns an object that the hook function can use to store hook specific
+         * context, it it not shared with any other hook instances and is unique for the
+         * current call.
+         * A hook implementation can use this to pass / share context between different
+         * hook callbacks eg. request/response requst/hookErrors etc.
+         */
+        ctx: () => any;
+        /**
+         * Allows the hook functions to replace the original arguments
+         * @param idx - The argument index (0 based)
+         * @param value - The new value for the argument
+         */
+        set: (idx: number, value: any) => void;
+        /**
+         * The result of the original method, only populated after the original method has returned
+         */
+        rslt?: any;
+        /**
+         * The error (exception) which occurred while executing the original method
+         */
+        err?: Error;
+        /**
+         * The Event object from (window.event) at the start of the original call
+         */
+        evt?: Event;
+    }
+
+    /**
+     * The holder of the specific instance callback
+     */
+    interface IInstrumentHook {
+        /** Unique Id for this callback on the hooked method */
+        id: number;
+        /** Holds the callbacks */
+        cbks: IInstrumentHooksCallbacks;
+        /** Remove this hook from the function */
+        rm: () => void;
+    }
+
+    /**
+     * The callbacks to call for the instrumented function, you must provide at least the request and/or response callbacks, both are not required.
+     * You must always supply the error callback
+     */
+    interface IInstrumentHooksCallbacks {
+        /**
+         * [Optional] Namespace details (same as the namespace used for events), useful for debugging and testing to
+         * identify the source of the instrumented hooks
+         */
+        ns?: string | string[];
+        /**
+         * The hook callback to call before the original function is called
+         */
+        req?: InstrumentorHooksCallback;
+        /**
+         * The hook callback to call after the original function was called
+         */
+        rsp?: InstrumentorHooksCallback;
+        /**
+         * The callback to call if the hook function causes an exception
+         */
+        hkErr?: InstrumentorHooksCallback;
+        /**
+         * The callback to call if the original function causes an exception, even if you
+         * supply a callback the original exception will still be thrown
+         */
+        fnErr?: InstrumentorHooksCallback;
+    }
+
+    interface ILoadedPlugin<T extends IPlugin> {
+        plugin: T;
+        /**
+         * Identifies whether the plugin is enabled and can process events. This is slightly different from isInitialized as the plugin may be initialized but disabled
+         * via the setEnabled() or it may be a shared plugin which has had it's teardown function called from another instance..
+         * @returns boolean = true if the plugin is in a state where it is operational.
+         */
+        isEnabled: () => boolean;
+        /**
+         * You can optionally enable / disable a plugin from processing events.
+         * Setting enabled to true will not necessarily cause the `isEnabled()` to also return true
+         * as the plugin must also have been successfully initialized and not had it's `teardown` method called
+         * (unless it's also been re-initialized)
+         */
+        setEnabled: (isEnabled: boolean) => void;
+        remove: (isAsync?: boolean, removeCb?: (removed?: boolean) => void) => void;
+    }
+
     interface IMetricTelemetry extends IPartC {
         /**
          * @description (required) - name of this metric
@@ -1272,6 +1749,12 @@ declare namespace ApplicationInsights {
         perfEvent?(perfEvent: IPerfEvent): void;
     }
 
+    /**
+     * A callback function that will be called for the wrapped instrumentation function
+     * before the original function is executed.
+     */
+    type InstrumentorHooksCallback = (funcArgs: IInstrumentCallDetails, ...orgArgs: any[]) => void;
+
     class _InternalLogMessage {
         static dataType: string;
         message: string;
@@ -1282,92 +1765,9 @@ declare namespace ApplicationInsights {
     /**
      * Internal message ID. Please create a new one for every conceptually different message. Please keep alphabetically ordered
      */
-    const _InternalMessageId: {
-        BrowserDoesNotSupportLocalStorage: number;
-        BrowserCannotReadLocalStorage: number;
-        BrowserCannotReadSessionStorage: number;
-        BrowserCannotWriteLocalStorage: number;
-        BrowserCannotWriteSessionStorage: number;
-        BrowserFailedRemovalFromLocalStorage: number;
-        BrowserFailedRemovalFromSessionStorage: number;
-        CannotSendEmptyTelemetry: number;
-        ClientPerformanceMathError: number;
-        ErrorParsingAISessionCookie: number;
-        ErrorPVCalc: number;
-        ExceptionWhileLoggingError: number;
-        FailedAddingTelemetryToBuffer: number;
-        FailedMonitorAjaxAbort: number;
-        FailedMonitorAjaxDur: number;
-        FailedMonitorAjaxOpen: number;
-        FailedMonitorAjaxRSC: number;
-        FailedMonitorAjaxSend: number;
-        FailedMonitorAjaxGetCorrelationHeader: number;
-        FailedToAddHandlerForOnBeforeUnload: number;
-        FailedToSendQueuedTelemetry: number;
-        FailedToReportDataLoss: number;
-        FlushFailed: number;
-        MessageLimitPerPVExceeded: number;
-        MissingRequiredFieldSpecification: number;
-        NavigationTimingNotSupported: number;
-        OnError: number;
-        SessionRenewalDateIsZero: number;
-        SenderNotInitialized: number;
-        StartTrackEventFailed: number;
-        StopTrackEventFailed: number;
-        StartTrackFailed: number;
-        StopTrackFailed: number;
-        TelemetrySampledAndNotSent: number;
-        TrackEventFailed: number;
-        TrackExceptionFailed: number;
-        TrackMetricFailed: number;
-        TrackPVFailed: number;
-        TrackPVFailedCalc: number;
-        TrackTraceFailed: number;
-        TransmissionFailed: number;
-        FailedToSetStorageBuffer: number;
-        FailedToRestoreStorageBuffer: number;
-        InvalidBackendResponse: number;
-        FailedToFixDepricatedValues: number;
-        InvalidDurationValue: number;
-        TelemetryEnvelopeInvalid: number;
-        CreateEnvelopeError: number;
-        CannotSerializeObject: number;
-        CannotSerializeObjectNonSerializable: number;
-        CircularReferenceDetected: number;
-        ClearAuthContextFailed: number;
-        ExceptionTruncated: number;
-        IllegalCharsInName: number;
-        ItemNotInArray: number;
-        MaxAjaxPerPVExceeded: number;
-        MessageTruncated: number;
-        NameTooLong: number;
-        SampleRateOutOfRange: number;
-        SetAuthContextFailed: number;
-        SetAuthContextFailedAccountName: number;
-        StringValueTooLong: number;
-        StartCalledMoreThanOnce: number;
-        StopCalledWithoutStart: number;
-        TelemetryInitializerFailed: number;
-        TrackArgumentsNotSpecified: number;
-        UrlTooLong: number;
-        SessionStorageBufferFull: number;
-        CannotAccessCookie: number;
-        IdTooLong: number;
-        InvalidEvent: number;
-        FailedMonitorAjaxSetRequestHeader: number;
-        SendBrowserInfoOnUserInit: number;
-        PluginException: number;
-        NotificationException: number;
-        SnippetScriptLoadFailure: number;
-        InvalidInstrumentationKey: number;
-        CannotParseAiBlobValue: number;
-        InvalidContentBlob: number;
-        TrackPageActionEventFailed: number;
-        FailedAddingCustomDefinedRequestContext: number;
-        InMemoryStorageBufferFull: number;
-    };
+    const _InternalMessageId: EnumValue<typeof _eInternalMessageId>;
 
-    type _InternalMessageId = number | typeof _InternalMessageId;
+    type _InternalMessageId = number | _eInternalMessageId;
 
     interface IPageViewPerformanceTelemetry extends IPartC {
         /**
@@ -1582,10 +1982,14 @@ declare namespace ApplicationInsights {
          */
         isInitialized?: () => boolean;
         /**
-         * Tear down the plugin and remove any hooked value, the plugin should remove that it is no longer initialized and
-         * therefore can be re-initialized after being torn down.
+         * Tear down the plugin and remove any hooked value, the plugin should be removed so that it is no longer initialized and
+         * therefore could be re-initialized after being torn down. The plugin should ensure that once this has been called any further
+         * processTelemetry calls are ignored and it just calls the processNext() with the provided context.
+         * @param unloadCtx - This is the context that should be used during unloading.
+         * @param unloadState - The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.
+         * @returns boolean - true if the plugin has or will call processNext(), this for backward compatibility as previously teardown was synchronous and returned nothing.
          */
-        teardown?: () => void;
+        teardown?: (unloadCtx: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState) => void | boolean;
         /**
          * Extension name
          */
@@ -1600,57 +2004,63 @@ declare namespace ApplicationInsights {
      * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
      * between multiple AppInsights instances
      */
-    interface IProcessTelemetryContext {
-        /**
-         * The current core instance for the request
-         */
-        core: () => IAppInsightsCore;
-        /**
-         * THe current diagnostic logger for the request
-         */
-        diagLog: () => IDiagnosticLogger;
-        /**
-         * Gets the current core config instance
-         */
-        getCfg: () => IConfiguration;
-        /**
-         * Gets the named extension config
-         */
-        getExtCfg: <T>(identifier: string, defaultValue?: T | any) => T;
+    interface IProcessTelemetryContext extends IBaseProcessingContext {
         /**
-         * Gets the named config from either the named identifier extension or core config if neither exist then the
-         * default value is returned
-         * @param identifier The named extension identifier
-         * @param field The config field name
-         * @param defaultValue The default value to return if no defined config exists
+         * Call back for telemetry processing before it it is sent
+         * @param env - This is the current event being reported
+         * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
          */
-        getConfig: (identifier: string, field: string, defaultValue?: number | string | boolean) => number | string | boolean;
+        processNext: (env: ITelemetryItem) => boolean | void;
         /**
-         * Helper to allow plugins to check and possibly shortcut executing code only
-         * required if there is a nextPlugin
+         * Create a new context using the core and config from the current instance, returns a new instance of the same type
+         * @param plugins - The execution order to process the plugins, if null or not supplied
+         *                  then the current execution order will be copied.
+         * @param startAt - The plugin to start processing from, if missing from the execution
+         *                  order then the next plugin will be NOT set.
          */
-        hasNext: () => boolean;
+        createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryContext;
+    }
+
+    /**
+     * The current context for the current call to teardown() implementations, used to support when plugins are being removed
+     * or the SDK is being unloaded.
+     */
+    interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
         /**
-         * Returns the next configured plugin proxy
+         * This Plugin has finished unloading, so unload the next one
+         * @param uploadState - The state of the unload process
+         * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
          */
-        getNext: () => ITelemetryPluginChain;
+        processNext: (unloadState: ITelemetryUnloadState) => boolean | void;
         /**
-         * Helper to set the next plugin proxy
+         * Create a new context using the core and config from the current instance, returns a new instance of the same type
+         * @param plugins - The execution order to process the plugins, if null or not supplied
+         *                  then the current execution order will be copied.
+         * @param startAt - The plugin to start processing from, if missing from the execution
+         *                  order then the next plugin will be NOT set.
          */
-        setNext: (nextCtx: ITelemetryPluginChain) => void;
+        createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUnloadContext;
+    }
+
+    /**
+     * The current context for the current call to the plugin update() implementations, used to support the notifications
+     * for when plugins are added, removed or the configuration was changed.
+     */
+    interface IProcessTelemetryUpdateContext extends IBaseProcessingContext {
         /**
-         * Call back for telemetry processing before it it is sent
-         * @param env - This is the current event being reported
+         * This Plugin has finished unloading, so unload the next one
+         * @param updateState - The update State
+         * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
          */
-        processNext: (env: ITelemetryItem) => void;
+        processNext: (updateState: ITelemetryUpdateState) => boolean | void;
         /**
-         * Create a new context using the core and config from the current instance
+         * Create a new context using the core and config from the current instance, returns a new instance of the same type
          * @param plugins - The execution order to process the plugins, if null or not supplied
          *                  then the current execution order will be copied.
          * @param startAt - The plugin to start processing from, if missing from the execution
          *                  order then the next plugin will be NOT set.
          */
-        createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryContext;
+        createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUpdateContext;
     }
 
     interface IRequestContext {
@@ -1787,11 +2197,17 @@ declare namespace ApplicationInsights {
         aiDataContract: any;
     }
 
+    function isNullOrUndefined(value: any): value is null | undefined;
+
     interface IStackDetails {
         src: string;
         obj: string[];
     }
 
+    interface ITelemetryInitializerHandler {
+        remove(): void;
+    }
+
     /**
      * Telemety item supported in Core
      */
@@ -1841,15 +2257,7 @@ declare namespace ApplicationInsights {
     /**
      * Configuration provided to SDK core
      */
-    interface ITelemetryPlugin extends IPlugin {
-        /**
-         * Call back for telemetry processing before it it is sent
-         * @param env - This is the current event being reported
-         * @param itemCtx - This is the context for the current request, ITelemetryPlugin instances
-         * can optionally use this to access the current core instance or define / pass additional information
-         * to later plugins (vs appending items to the telemetry item)
-         */
-        processTelemetry: (env: ITelemetryItem, itemCtx?: IProcessTelemetryContext) => void;
+    interface ITelemetryPlugin extends ITelemetryProcessor, IPlugin {
         /**
          * Set next extension for telemetry processing, this is not optional as plugins should use the
          * processNext() function of the passed IProcessTelemetryContext instead. It is being kept for
@@ -1865,7 +2273,7 @@ declare namespace ApplicationInsights {
     /**
      * Configuration provided to SDK core
      */
-    interface ITelemetryPluginChain {
+    interface ITelemetryPluginChain extends ITelemetryProcessor {
         /**
          * Returns the underlying plugin that is being proxied for the processTelemetry call
          */
@@ -1874,6 +2282,16 @@ declare namespace ApplicationInsights {
          * Returns the next plugin
          */
         getNext: () => ITelemetryPluginChain;
+        /**
+         * This plugin is being unloaded and should remove any hooked events and cleanup any global/scoped values, after this
+         * call the plugin will be removed from the telemetry processing chain and will no longer receive any events..
+         * @param unloadCtx - The unload context to use for this call.
+         * @param unloadState - The details of the unload operation
+         */
+        unload?: (unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+    }
+
+    interface ITelemetryProcessor {
         /**
          * Call back for telemetry processing before it it is sent
          * @param env - This is the current event being reported
@@ -1881,7 +2299,43 @@ declare namespace ApplicationInsights {
          * can optionally use this to access the current core instance or define / pass additional information
          * to later plugins (vs appending items to the telemetry item)
          */
-        processTelemetry: (env: ITelemetryItem, itemCtx: IProcessTelemetryContext) => void;
+        processTelemetry: (env: ITelemetryItem, itemCtx?: IProcessTelemetryContext) => void;
+        /**
+         * The the plugin should re-evaluate configuration and update any cached configuration settings or
+         * plugins. If implemented this method will be called whenever a plugin is added or removed and if
+         * the configuration has bee updated.
+         * @param updateCtx - This is the context that should be used during updating.
+         * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+         * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
+         */
+        update?: (updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState) => void | boolean;
+    }
+
+    interface ITelemetryUnloadState {
+        reason: TelemetryUnloadReason;
+        isAsync: boolean;
+        flushComplete?: boolean;
+    }
+
+    interface ITelemetryUpdateState {
+        /**
+         * Identifies the reason for the update notification, this is a bitwise numeric value
+         */
+        reason: TelemetryUpdateReason;
+        /**
+         * If this is a configuration update this was the previous configuration that was used
+         */
+        /**
+         * If this is a configuration update is the new configuration that is being used
+         */
+        /**
+         * This holds a collection of plugins that have been added (if the reason identifies that one or more plugins have been added)
+         */
+        added?: IPlugin[];
+        /**
+         * This holds a collection of plugins that have been removed (if the reason identifies that one or more plugins have been removed)
+         */
+        removed?: IPlugin[];
     }
 
     interface ITraceTelemetry extends IPartC {
@@ -1905,16 +2359,19 @@ declare namespace ApplicationInsights {
         iKey?: string;
     }
 
-    enum LoggingSeverity {
-        /**
-         * Error will be sent as internal telemetry
-         */
-        CRITICAL = 1,
-        /**
-         * Error will NOT be sent as internal telemetry, and will only be shown in browser console
-         */
-        WARNING = 2
-    }
+    const LoggingSeverity: EnumValue<typeof eLoggingSeverity>;
+
+    type LoggingSeverity = number | eLoggingSeverity;
+
+    /**
+     * Creates proxy functions on the target which internally will call the source version with all arguments passed to the target method.
+     *
+     * @param target - The target object to be assigned with the source properties and functions
+     * @param source - The source object which will be assigned / called by setting / calling the targets proxies
+     * @param functionsToProxy - An array of function names that will be proxied on the target
+     * @param overwriteTarget - If false this will not replace any pre-existing name otherwise (the default) it will overwrite any existing name
+     */
+    function proxyFunctions<T, S>(target: T, source: S | (() => S), functionsToProxy: (keyof S)[], overwriteTarget?: boolean): T;
 
     class Sender extends BaseTelemetryPlugin implements IChannelControlsAI {
         static constructEnvelope(orig: ITelemetryItem, iKey: string, logger: IDiagnosticLogger, convertUndefined?: any): IEnvelope;
@@ -1960,7 +2417,6 @@ declare namespace ApplicationInsights {
          * Will not flush if the Send has been paused.
          */
         onunloadFlush(): void;
-        teardown(): void;
         initialize(config: IConfiguration & IConfig, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
         processTelemetry(telemetryItem: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
         /**
@@ -2031,6 +2487,10 @@ declare namespace ApplicationInsights {
          * The event(s) being sent as a retry
          */
         Retry = 5,
+        /**
+         * The SDK is unloading
+         */
+        SdkUnload = 6,
         /**
          * Maximum batch size would be exceeded
          */
@@ -2056,6 +2516,55 @@ declare namespace ApplicationInsights {
         [key: string]: any;
     }
 
+    type TelemetryInitializerFunction = <T extends ITelemetryItem>(item: T) => boolean | void;
+
+    /**
+     * The TelemetryUnloadReason enumeration contains the possible reasons for why a plugin is being unloaded / torndown().
+     */
+    const enum TelemetryUnloadReason {
+        /**
+         * Teardown has been called without any context.
+         */
+        ManualTeardown = 0,
+        /**
+         * Just this plugin is being removed
+         */
+        PluginUnload = 1,
+        /**
+         * This instance of the plugin is being removed and replaced
+         */
+        PluginReplace = 2,
+        /**
+         * The entire SDK is being unloaded
+         */
+        SdkUnload = 50
+    }
+
+    /**
+     * The TelemetryUpdateReason enumeration contains a set of bit-wise values that specify the reason for update request.
+     */
+    const enum TelemetryUpdateReason {
+        /**
+         * Unknown.
+         */
+        Unknown = 0,
+        /**
+         * The configuration has ben updated or changed
+         */
+        /**
+         * One or more plugins have been added
+         */
+        PluginAdded = 16,
+        /**
+         * One or more plugins have been removed
+         */
+        PluginRemoved = 32
+    }
+
+    function throwError(message: string): never;
+
+    type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+
     interface XDomainRequest extends XMLHttpRequestEventTarget {
         readonly responseText: string;
         send(payload: string): void;