@microsoft/applicationinsights-web-basic 2.8.0-beta.2203-04 → 2.8.0-beta.2203-07

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

@@ -1,5 +1,5 @@
 /*
- * Microsoft.ApplicationInsights, 2.8.0-beta.2203-04
+ * Microsoft.ApplicationInsights, 2.8.0-beta.2203-07
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -113,10 +113,20 @@ declare class BaseCore implements IAppInsightsCore {
      * 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?: () => void): void;
+    unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
     getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
-    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
+    /**
+     * 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
      */
@@ -126,7 +136,23 @@ declare class BaseCore implements IAppInsightsCore {
      * @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;
 }
 
 /**
@@ -183,6 +209,14 @@ declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
      * @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.
+     */
+    protected _doUpdate?: (updateCtx?: IProcessTelemetryUpdateContext, updateState?: ITelemetryUpdateState, asyncCallback?: () => void) => void | boolean;
     constructor();
     initialize(config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
     /**
@@ -195,6 +229,13 @@ declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
      */
     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
@@ -394,8 +435,11 @@ export declare interface IAppInsightsCore extends IPerfManagerProvider {
      * 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?: () => void): void;
+    unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
     /**
      * Find and return the (first) plugin with the specified identifier if present
      * @param pluginIdentifier
@@ -404,10 +448,11 @@ export declare interface IAppInsightsCore extends IPerfManagerProvider {
     /**
      * Add a new plugin to the installation
      * @param plugin - The new plugin to add
-     * @param replaceExisting - should any existing plugin be replaced
+     * @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;
+    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
      */
@@ -417,6 +462,16 @@ export declare interface IAppInsightsCore extends IPerfManagerProvider {
      * @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;
 }
 
 /**
@@ -1473,6 +1528,11 @@ declare interface IInstrumentHook {
  * You must always supply the error callback
  */
 declare 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
      */
@@ -1984,8 +2044,8 @@ declare interface IProcessTelemetryContext extends IBaseProcessingContext {
 }
 
 /**
- * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
- * between multiple AppInsights instances
+ * The current context for the current call to teardown() implementations, used to support when plugins are being removed
+ * or the SDK is being unloaded.
  */
 declare interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
     /**
@@ -2004,6 +2064,27 @@ declare interface IProcessTelemetryUnloadContext extends IBaseProcessingContext
     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.
+ */
+declare interface IProcessTelemetryUpdateContext extends IBaseProcessingContext {
+    /**
+     * 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: (updateState: ITelemetryUpdateState) => 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) => IProcessTelemetryUpdateContext;
+}
+
 declare interface IRequestContext {
     status?: number;
     xhr?: XMLHttpRequest;
@@ -2239,6 +2320,15 @@ declare interface ITelemetryProcessor {
      * to later plugins (vs appending items to the telemetry item)
      */
     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;
 }
 
 declare interface ITelemetryUnloadState {
@@ -2247,6 +2337,27 @@ declare interface ITelemetryUnloadState {
     flushComplete?: boolean;
 }
 
+declare 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[];
+}
+
 export declare interface ITraceTelemetry extends IPartC {
     /**
      * @description A message string
@@ -2443,6 +2554,27 @@ declare const enum TelemetryUnloadReason {
     SdkUnload = 50
 }
 
+/**
+ * The TelemetryUpdateReason enumeration contains a set of bit-wise values that specify the reason for update request.
+ */
+declare 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
+}
+
 declare type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
 
 declare interface XDomainRequest extends XMLHttpRequestEventTarget {

package/dist-esm/index.js

@@ -1,5 +1,5 @@
 /*
- * Application Insights JavaScript Web SDK - Basic, 2.8.0-beta.2203-04
+ * Application Insights JavaScript Web SDK - Basic, 2.8.0-beta.2203-07
  * Copyright (c) Microsoft and contributors. All rights reserved.
  */
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@microsoft/applicationinsights-web-basic",
-    "version": "2.8.0-beta.2203-04",
+    "version": "2.8.0-beta.2203-07",
     "description": "Microsoft Application Insights Javascript SDK core and channel",
     "homepage": "https://github.com/microsoft/ApplicationInsights-JS#readme",
     "author": "Microsoft Application Insights Team",
@@ -49,9 +49,9 @@
     "dependencies": {
         "@microsoft/dynamicproto-js": "^1.1.4",
         "@microsoft/applicationinsights-shims": "2.0.1",
-        "@microsoft/applicationinsights-common": "2.8.0-beta.2203-04",
-        "@microsoft/applicationinsights-channel-js": "2.8.0-beta.2203-04",
-        "@microsoft/applicationinsights-core-js": "2.8.0-beta.2203-04"
+        "@microsoft/applicationinsights-common": "2.8.0-beta.2203-07",
+        "@microsoft/applicationinsights-channel-js": "2.8.0-beta.2203-07",
+        "@microsoft/applicationinsights-core-js": "2.8.0-beta.2203-07"
     },
     "license": "MIT",
     "publishConfig": {

package/browser/aib.2.8.0-beta.2203-04.integrity.json

@@ -1,26 +0,0 @@
-{
-    "name": "aib",
-    "version": "2.8.0-beta.2203-04",
-    "ext": {
-        "@js": {
-            "file": "aib.2.8.0-beta.2203-04.js",
-            "type": "text/javascript; charset=utf-8",
-            "integrity": "sha256-jf7SNn8jwON6bIJJ1kHXDOvHq7tL6DDn2KHm66bFB1g= sha384-iGUVpD8Kw1h9irCex4NSBebbJ88MBDP4gc92xJiyWtUFDLgM36L3pUPdJEkNIYjS sha512-+d/1rf6zTA7824akyNFRIaIeQW7wmSjqwiLmRooWVUSQO4k/LH6HVpbXPYtyIwdvYNiArno4axyOdTKNoXq3Qw==",
-            "hashes": {
-                "sha256": "jf7SNn8jwON6bIJJ1kHXDOvHq7tL6DDn2KHm66bFB1g=",
-                "sha384": "iGUVpD8Kw1h9irCex4NSBebbJ88MBDP4gc92xJiyWtUFDLgM36L3pUPdJEkNIYjS",
-                "sha512": "+d/1rf6zTA7824akyNFRIaIeQW7wmSjqwiLmRooWVUSQO4k/LH6HVpbXPYtyIwdvYNiArno4axyOdTKNoXq3Qw=="
-            }
-        },
-        "@min.js": {
-            "file": "aib.2.8.0-beta.2203-04.min.js",
-            "type": "text/javascript; charset=utf-8",
-            "integrity": "sha256-f3MCk+/gx1y7kuIeq5MeIGsfw9ZD3mGsEVtDarhbpdo= sha384-LqoDEkW5ot0qWo/HZNB6n5U6ZGfYSh6Ky426qdocdByvQohbffN0Lm7LRTZp9XB6 sha512-hN78HLUacgdBUdKJD7vS5mzcLYo9wSn+RuatGQjFoK0zy2ktObEP6S7F1nKWgbos7mvoMgEb312PUIgDy7V/YQ==",
-            "hashes": {
-                "sha256": "f3MCk+/gx1y7kuIeq5MeIGsfw9ZD3mGsEVtDarhbpdo=",
-                "sha384": "LqoDEkW5ot0qWo/HZNB6n5U6ZGfYSh6Ky426qdocdByvQohbffN0Lm7LRTZp9XB6",
-                "sha512": "hN78HLUacgdBUdKJD7vS5mzcLYo9wSn+RuatGQjFoK0zy2ktObEP6S7F1nKWgbos7mvoMgEb312PUIgDy7V/YQ=="
-            }
-        }
-    }
-}