@microsoft/applicationinsights-web 2.8.0-beta.2202-06 → 2.8.0-beta.2203-02

package/dist/applicationinsights-web.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft.ApplicationInsights, 2.8.0-beta.2202-06
+ * Microsoft.ApplicationInsights, 2.8.0-beta.2203-02
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -418,6 +418,10 @@ declare namespace ApplicationInsights {
          */
         addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
         getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+        /**
+         * Returns the unique event namespace that should be used
+         */
+        evtNamespace(): string;
         protected releaseQueue(): void;
     }
 
@@ -466,8 +470,26 @@ declare namespace ApplicationInsights {
          * Internal helper to allow setting of the internal initialized setting for inherited instances and unit testing
          */
         protected setInitialized: (isInitialized: boolean) => void;
+        /**
+         * 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;
         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;
         /**
          * Add this hook so that it is automatically removed during unloading
@@ -579,7 +601,6 @@ declare namespace ApplicationInsights {
         priority: number;
         constructor();
         initialize(config: IConfiguration & IConfig, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
-        teardown(): void;
         processTelemetry(item: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
         /**
          * Logs dependency call
@@ -602,20 +623,13 @@ declare namespace ApplicationInsights {
         }): void;
     }
 
-    enum DistributedTracingModes {
-        /**
-         * (Default) Send Application Insights correlation headers
-         */
-        AI = 0,
-        /**
-         * Send both W3C Trace Context headers and back-compatibility Application Insights headers
-         */
-        AI_AND_W3C = 1,
-        /**
-         * Send W3C Trace Context headers
-         */
-        W3C = 2
-    }
+    const DistributedTracingModes: {
+        AI: number;
+        AI_AND_W3C: number;
+        W3C: number;
+    };
+
+    type DistributedTracingModes = number | eDistributedTracingModes;
 
     /**
      * The abstract common base of all domains.
@@ -633,6 +647,117 @@ declare namespace ApplicationInsights {
      */
     function doPerf<T>(mgrSource: IPerfManagerProvider | IPerfManager, getSource: () => string, func: (perfEvt?: IPerfEvent) => T, details?: () => any, isAsync?: boolean): T;
 
+    const enum eDistributedTracingModes {
+        /**
+         * (Default) Send Application Insights correlation headers
+         */
+        AI = 0,
+        /**
+         * Send both W3C Trace Context headers and back-compatibility Application Insights headers
+         */
+        AI_AND_W3C = 1,
+        /**
+         * Send W3C Trace Context headers
+         */
+        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
+    }
+
     class Envelope extends Envelope_2 implements IEnvelope {
         /**
          * The data contract for serializing this object.
@@ -930,6 +1055,10 @@ declare namespace ApplicationInsights {
          * @param pluginIdentifier
          */
         getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+        /**
+         * Returns the unique event namespace that should be used when registering events
+         */
+        evtNamespace(): string;
     }
 
     interface IAppInsightsDeprecated {
@@ -1183,6 +1312,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: Function, 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
      */
@@ -1196,9 +1386,14 @@ 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
@@ -2053,7 +2248,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
@@ -2528,6 +2723,19 @@ declare namespace ApplicationInsights {
 
     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;
     }
 
     interface ILocation {
@@ -2756,7 +2964,7 @@ declare namespace ApplicationInsights {
         InMemoryStorageBufferFull: number;
     };
 
-    type _InternalMessageId = number | typeof _InternalMessageId;
+    type _InternalMessageId = number | _eInternalMessageId;
 
     interface IOperatingSystem {
         name: string;
@@ -3009,10 +3217,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
          */
@@ -3027,67 +3239,42 @@ 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, 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;
+    interface IProcessTelemetryContext extends IBaseProcessingContext {
         /**
          * 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)
          */
-        processNext: (env: ITelemetryItem) => 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;
+        processNext: (env: ITelemetryItem) => 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;
+    }
+
+    /**
+     * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
+     * between multiple AppInsights instances
+     */
+    interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
         /**
-         * Set the function to call when the current chain has executed all processNext or unloadNext items.
+         * 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)
          */
-        onComplete: (onComplete: () => void) => void;
+        processNext: (unloadState: ITelemetryUnloadState) => boolean | 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) => IProcessTelemetryUnloadContext;
     }
 
     interface IPropertiesPlugin {
@@ -3443,15 +3630,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
@@ -3467,7 +3646,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
          */
@@ -3476,6 +3655,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
@@ -3483,7 +3672,7 @@ 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;
     }
 
     interface ITelemetryTrace {
@@ -3505,6 +3694,12 @@ declare namespace ApplicationInsights {
         name?: string;
     }
 
+    interface ITelemetryUnloadState {
+        reason: TelemetryUnloadReason;
+        isAsync: boolean;
+        flushComplete?: boolean;
+    }
+
     interface ITraceState {
     }
 
@@ -3778,16 +3973,12 @@ declare namespace ApplicationInsights {
         domain: 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: {
+        CRITICAL: number;
+        WARNING: number;
+    };
+
+    type LoggingSeverity = number | eLoggingSeverity;
 
     /**
      * Instances of Message represent printf-like trace statements that are text-searched. Log4Net, NLog and other text-based log file entries are translated into intances of this type. The message does not have measurements.
@@ -4565,7 +4756,11 @@ declare namespace ApplicationInsights {
             SessionExt: string;
             SDKExt: string;
         };
-        DistributedTracingModes: typeof DistributedTracingModes;
+        DistributedTracingModes: {
+            AI: number;
+            AI_AND_W3C: number;
+            W3C: number;
+        };
     };
 
     type TelemetryInitializerFunction = <T extends ITelemetryItem>(item: T) => boolean | void;
@@ -4587,6 +4782,16 @@ declare namespace ApplicationInsights {
         }): ITelemetryItem;
     }
 
+    /**
+     * 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
+    }
+
     class Trace extends MessageData implements ISerializable {
         static envelopeType: string;
         static dataType: string;