@microsoft/applicationinsights-web 2.7.4-nightly.2202-07 → 2.8.0-beta.2202-06

package/dist/applicationinsights-web.api.md

@@ -7,12 +7,8 @@
 // @public (undocumented)
 export class AppInsightsCore extends BaseCore implements IAppInsightsCore {
     constructor();
-    addNotificationListener(listener: INotificationListener): void;
     // (undocumented)
     initialize(config: IConfiguration, extensions: IPlugin[], logger?: IDiagnosticLogger, notificationManager?: INotificationManager): void;
-    pollInternalLogs(eventName?: string): number;
-    removeNotificationListener(listener: INotificationListener): void;
-    stopPollingInternalLogs(): void;
     // (undocumented)
     track(telemetryItem: ITelemetryItem): void;
 }
@@ -160,6 +156,10 @@ export class ApplicationInsightsContainer {
 // @public (undocumented)
 export class BaseCore implements IAppInsightsCore {
     constructor();
+    addNotificationListener(listener: INotificationListener): void;
+    // Warning: (ae-forgotten-export) The symbol "TelemetryInitializerFunction" needs to be exported by the entry point applicationinsights-web.d.ts
+    // Warning: (ae-forgotten-export) The symbol "ITelemetryInitializerHandler" needs to be exported by the entry point applicationinsights-web.d.ts
+    addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
     // (undocumented)
     config: IConfiguration;
     // (undocumented)
@@ -173,6 +173,10 @@ export class BaseCore implements IAppInsightsCore {
     getNotifyMgr(): INotificationManager;
     // (undocumented)
     getPerfMgr(): IPerfManager;
+    // Warning: (ae-forgotten-export) The symbol "ILoadedPlugin" needs to be exported by the entry point applicationinsights-web.d.ts
+    //
+    // (undocumented)
+    getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
     // (undocumented)
     getProcessTelContext(): IProcessTelemetryContext;
     // Warning: (ae-forgotten-export) The symbol "IChannelControls" needs to be exported by the entry point applicationinsights-web.d.ts
@@ -185,11 +189,14 @@ export class BaseCore implements IAppInsightsCore {
     isInitialized: () => boolean;
     // (undocumented)
     logger: IDiagnosticLogger;
+    pollInternalLogs(eventName?: string): number;
     // (undocumented)
     protected releaseQueue(): void;
+    removeNotificationListener(listener: INotificationListener): void;
     setCookieMgr(cookieMgr: ICookieMgr): void;
     // (undocumented)
     setPerfMgr(perfMgr: IPerfManager): void;
+    stopPollingInternalLogs(): void;
     // (undocumented)
     track(telemetryItem: ITelemetryItem): void;
 }
@@ -197,6 +204,8 @@ export class BaseCore implements IAppInsightsCore {
 // @public
 export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
     constructor();
+    // Warning: (ae-forgotten-export) The symbol "IInstrumentHook" needs to be exported by the entry point applicationinsights-web.d.ts
+    protected _addHook(hooks: IInstrumentHook | IInstrumentHook[]): void;
     core: IAppInsightsCore;
     diagLog: (itemCtx?: IProcessTelemetryContext) => IDiagnosticLogger;
     protected _getTelCtx: (currentCtx?: IProcessTelemetryContext) => IProcessTelemetryContext;
@@ -374,10 +383,12 @@ export interface IAppInsights {
 // @public (undocumented)
 export interface IAppInsightsCore extends IPerfManagerProvider {
     addNotificationListener?(listener: INotificationListener): void;
+    addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
     // (undocumented)
     config: IConfiguration;
     getCookieMgr(): ICookieMgr;
     getNotifyMgr(): INotificationManager;
+    getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
     getProcessTelContext(): IProcessTelemetryContext;
     // (undocumented)
     getTransmissionControls(): IChannelControls[][];
@@ -911,10 +922,13 @@ export interface IProcessTelemetryContext {
     createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryContext;
     diagLog: () => IDiagnosticLogger;
     getCfg: () => IConfiguration;
-    getConfig: (identifier: string, field: string, defaultValue?: number | string | boolean) => number | string | boolean;
-    getExtCfg: <T>(identifier: string, defaultValue?: T | any) => T;
+    getConfig: (identifier: string, field: string, defaultValue?: number | string | boolean | string[] | RegExp[] | Function) => number | string | boolean | string[] | RegExp[] | Function;
+    // Warning: (ae-forgotten-export) The symbol "GetExtCfgMergeType" needs to be exported by the entry point applicationinsights-web.d.ts
+    getExtCfg: <T>(identifier: string, defaultValue?: T | any, mergeDefault?: GetExtCfgMergeType) => T;
     getNext: () => ITelemetryPluginChain;
     hasNext: () => boolean;
+    iterate: <T extends ITelemetryPlugin = ITelemetryPlugin>(callback: (plugin: T) => void) => void;
+    onComplete: (onComplete: () => void) => void;
     processNext: (env: ITelemetryItem) => void;
     setNext: (nextCtx: ITelemetryPluginChain) => void;
 }

package/dist/applicationinsights-web.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft.ApplicationInsights, 2.7.4-nightly.2202-07
+ * Microsoft.ApplicationInsights, 2.8.0-beta.2202-06
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -44,26 +44,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;
     }
 
     class ApplicationAnalytics extends BaseTelemetryPlugin implements IAppInsights, IAppInsightsInternal {
@@ -399,6 +379,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
          */
@@ -411,6 +403,21 @@ 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;
+        getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
         protected releaseQueue(): void;
     }
 
@@ -420,6 +427,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
@@ -441,13 +455,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
@@ -459,13 +466,14 @@ declare namespace ApplicationInsights {
          * Internal helper to allow setting of the internal initialized setting for inherited instances and unit testing
          */
         protected setInitialized: (isInitialized: boolean) => void;
-        /**
-         * Internal helper to initialize the instance
-         */
-        private _baseTelInit;
         constructor();
         initialize(config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
         abstract processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): 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;
     }
 
     class ConfigurationManager {
@@ -824,6 +832,12 @@ declare namespace ApplicationInsights {
      */
     function _formatErrorCode(errorObj: any): any;
 
+    const enum GetExtCfgMergeType {
+        None = 0,
+        MergeDefaultOnly = 1,
+        MergeDefaultFromRootOrDefault = 2
+    }
+
     interface IAjaxRecordResponse {
         statusText: string;
         headerMap: Object;
@@ -899,12 +913,23 @@ 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;
+        /**
+         * Find and return the (first) plugin with the specified identifier if present
+         * @param pluginIdentifier
+         */
+        getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
     }
 
     interface IAppInsightsDeprecated {
@@ -1176,10 +1201,13 @@ declare namespace ApplicationInsights {
         teardown(): void;
         /**
          * 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 {
@@ -2407,6 +2435,73 @@ declare namespace ApplicationInsights {
         includeCorrelationHeaders: (ajaxData: ajaxRecord, input?: Request | string, init?: RequestInit, xhr?: XMLHttpRequestInstrumented) => any;
     }
 
+    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 {
+        /**
+         * 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 IInternal {
         /**
          * The SDK version used to create this telemetry item.
@@ -2431,6 +2526,10 @@ declare namespace ApplicationInsights {
         sdkSrc: string;
     }
 
+    interface ILoadedPlugin<T extends IPlugin> {
+        plugin: T;
+    }
+
     interface ILocation {
         /**
          * Client IP address for reverse lookup
@@ -2556,6 +2655,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;
@@ -2938,7 +3043,7 @@ declare namespace ApplicationInsights {
         /**
          * Gets the named extension config
          */
-        getExtCfg: <T>(identifier: string, defaultValue?: T | any) => T;
+        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
@@ -2946,7 +3051,7 @@ declare namespace ApplicationInsights {
          * @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) => number | string | boolean;
+        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
@@ -2965,6 +3070,12 @@ declare namespace ApplicationInsights {
          * @param env - This is the current event being reported
          */
         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;
         /**
          * Create a new context using the core and config from the current instance
          * @param plugins - The execution order to process the plugins, if null or not supplied
@@ -2973,6 +3084,10 @@ declare namespace ApplicationInsights {
          *                  order then the next plugin will be NOT set.
          */
         createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryContext;
+        /**
+         * Set the function to call when the current chain has executed all processNext or unloadNext items.
+         */
+        onComplete: (onComplete: () => void) => void;
     }
 
     interface IPropertiesPlugin {
@@ -3275,6 +3390,10 @@ declare namespace ApplicationInsights {
         addTelemetryInitializer(telemetryInitializer: (envelope: IEnvelope) => boolean | void): void;
     }
 
+    interface ITelemetryInitializerHandler {
+        remove(): void;
+    }
+
     /**
      * Telemety item supported in Core
      */
@@ -4449,6 +4568,8 @@ declare namespace ApplicationInsights {
         DistributedTracingModes: typeof DistributedTracingModes;
     };
 
+    type TelemetryInitializerFunction = <T extends ITelemetryItem>(item: T) => boolean | void;
+
     class TelemetryItemCreator {
         /**
          * Create a telemetry item that the 1DS channel understands