@dynatrace/dtrum-api-types 1.319.3 → 1.321.4

package/README.md

@@ -2,7 +2,7 @@
 This package contains the Typescript type information for the dtrum.* API of the RUM JavaScript.
 
 Keep in mind that when the RUM JavaScript is updated, this type package might not provide accurate types.
-Version: 1.319.3
+Version: 1.321.4
 
 ## Installation
 > npm install --save-dev @dynatrace/dtrum-api-types

package/dtrum.d.ts

@@ -1,287 +1,372 @@
 /**
- * Signature of the function passed as callback in {@link DtrumApi.addLeaveActionListener}
- *
- * @param actionId     the ID for which the leave is called
- * @param stoptime     start resp. endtime of the action
- * @param isRootAction true if the action with the provided ID is a root action
+ * @inline
+ * @ignore
  */
 export interface ActionLeaveListener {
     (actionId: number, stoptime: number, isRootAction: boolean): void;
 }
 
 /**
- * Signature of the function passed as callback in {@link DtrumApi.addEnterActionListener}
- *
- * @param actionId     the ID for which the enter is called
- * @param starttime    start resp. endtime of the action
- * @param isRootAction true if the action with the provided ID is a root action
- * @param [element]    the element which resulted in the initiation of the event
+ * @inline
+ * @ignore
  */
-export interface ActionEnterListener {
-    (actionId: number, starttime: number, isRootAction: boolean, element?: EventTarget | string): void;
-}
+export type ActionEnterListener = (actionId: number, starttime: number, isRootAction: boolean, element?: EventTarget | string) => void;
 
 /**
- * Signature of new the view to start.
- *
- * @param name  New view name. Usually it matches the location.pathname or location.hash
- * @param group New view group. It is recommended to contain the dynamic placeholders of the view name.
- *              For example, if the view name is "/books/123", view group should be "books/:bookId" or similar.
- *              If null or undefined is passed in, the dynatrace server will calculate the group based on the name.
+ * @inline
+ * @ignore
  */
 export interface APIPage {
+    /**
+     * The name of the new view, typically matching the location.pathname or location.hash.
+     */
     name: string;
+    /**
+     * The group of the new view, recommended to include dynamic placeholders of the view name.
+     * For example, if the view name is "/books/123", the view group should be "books/:bookId" or similar.
+     * If null or undefined, the Dynatrace server calculates the group based on the name.
+     */
     group?: string;
 }
 
+/**
+ * @ignore
+ * @inline
+ */
 export type PageLeaveListener = (unloadRunning: boolean) => void;
 
+/**
+ * @ignore
+ * @inline
+ */
 export type AllowedMapTypes = Date | string | number;
 
 // this is used for dtrum doc
+/**
+ * @category API
+ */
 // eslint-disable-next-line @typescript-eslint/naming-convention -- dtrum is fine here
 export type dtrum = DtrumApi;
+/**
+ * @category API
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention -- dynatrace is fine here
+export type dynatrace = DynatraceApi;
 
+/**
+ * @category Custom Reporting
+ * @typeParam S - The type of the captured property.
+ */
 export interface Property<S> {
+    /** The value of the property. */
     value: S;
+    /** Indicates if the property is public. If not set to true, the value will be sent as masked (dT_pv) in doNotTrack
+     * mode. */
     public?: boolean;
 }
 
+/**
+ * @category Custom Reporting
+ */
 export interface PropertyMap<S extends AllowedMapTypes> {
+    /** A map of properties, keyed by string. */
     [key: string]: Property<S> | S;
 }
 
+/**
+ * @category Custom Reporting
+ */
 export interface FailedProperty {
+    /** The key of the failed property. */
     key: string;
+    /** The reason for the failure. */
     reason: string;
 }
 
+/**
+ * @category Custom Reporting
+ */
 export interface SuccessfulProperty {
+    /** The key of the successfully collected property. */
     key: string;
+    /** The value of the successfully collected property. */
     value: AllowedMapTypes;
 }
 
+/**
+ * @category Custom Reporting
+ */
 export interface PropertiesSendingReport {
+    /** A list of properties that failed to send, with reasons. */
     failedProperties: FailedProperty[];
+    /** A list of properties that were successfully sent. */
     sentProperties: SuccessfulProperty[];
+    /** Additional information about the sending process. */
     info: string;
 }
 
+/**
+ * @category Custom Reporting
+ */
 export interface PropertyObject {
+    /** A map of Java long properties. */
     javaLong?: PropertyMap<number>;
+    /** A map of date properties. */
     date?: PropertyMap<Date>;
+    /** A map of short string properties. */
     shortString?: PropertyMap<string>;
+    /** A map of Java double properties. */
     javaDouble?: PropertyMap<number>;
 }
 
+/**
+ * @category Actions
+ */
 export interface DtRumUserInput {
+    /** The target element or string that initiated the input. */
     target: EventTarget | string | undefined;
+    /** The name of the user input. */
     name: string;
+    /** Additional information about the input. */
     info: string;
+    /** The title of the current document. */
     title: string;
 }
 
 /**
- * Defines the type of resources for the summary
- */
-export const enum ResourceSummaryTypes {
-    /** Stylesheet resource (e.g. .css) */
-    CSS = "c",
-    /** Custom resource */
-    CUSTOM = "y",
-    /** Image resource (e.g. .jpg, .png) */
-    IMAGES = "i",
-    /** Undefined resource */
-    OTHER = "o",
-    /** Script resource (e.g. .js) */
-    SCRIPTS = "s"
-}
-
-/**
- * Provides information about call results to actionName.
+ * Provides information about call results to {@link dtrum.actionName}.
+ *
+ * @category Actions
  */
 export const enum ActionNameResult {
-    /** Action naming was successful with the provided name */
+    /** Action naming was successful with the provided name. */
     SUCCESS = 0,
-    /** The action with the provided ID was not found, or there was no currently active action */
+    /** The action with the provided ID was not found, or there was no currently active action. */
     ACTION_NOT_FOUND = 1,
-    /** The provided action name was not of type string */
+    /** The provided action name was not of type string. */
     INVALID_ACTION_NAME = 2,
-    /** The provided action ID was provided, not of type number */
+    /** The provided action ID was provided, not of type number. */
     INVALID_ACTION_ID = 3
 }
 
+/**
+ * @category Custom Reporting
+ */
 export interface MetaData {
     /**
      * An internally used id
      *
-     * @hidden
+     * @ignore
      */
     id: string;
     /**
-     * Specifies where the metadata is collected from:
-     * * CSS Selector
-     * * JavaScript Variable
-     * * Cookie
-     * * Query String
-     * * JavaScript Function
+     * Specifies where the metadata is collected from, such as:
+     * - CSS Selector
+     * - JavaScript Variable
+     * - Cookie
+     * - Query String
+     * - JavaScript Function
      */
     type: string;
     /**
-     * How the metadata can be retrieved(cookie name, css selector, javascript variable name, ...)
+     * Describes how the metadata can be retrieved (e.g., cookie name, CSS selector, JavaScript variable name).
      */
     expression: string;
     /**
-     * The current value for the given expression
+     * The current value for the given expression.
      */
     value: string | null;
     /**
-     * Shows information about captured value
+     * Additional information about the captured value.
      */
     info?: string;
 }
 
+/**
+ * @inline
+ * @ignore
+ */
 export interface DtrumApi {
     /**
-     * Enables/disables automatic action detection. Use when you want to instrument your application only manually.
+     * Enables or disables automatic action detection. Use this method when you want to manually instrument your application.
      *
+     * @group Actions
      * @see {@link enterAction}
      * @see {@link leaveAction}
-     * @param enabled Whether automatic action detection should be enabled or disabled
+     * @param enabled Specifies whether automatic action detection should be enabled or disabled.
      */
     setAutomaticActionDetection(enabled: boolean): void;
     /**
-     * Tells the RUM monitoring code to not automatically detect the load end event.
-     * The load end event must be set explicitly via {@link signalLoadEnd}.
-     * Needs to be called immediately after the RUM monitoring code is injected!
+     * Prevents RUM JavaScript from automatically detecting the load end event.
+     * The load end event must be explicitly set using {@link signalLoadEnd}.
+     * Call this method immediately after injecting RUM JavaScript.
      *
+     * @group Actions
      */
     setLoadEndManually(): void;
     /**
      * Signals that the page has finished loading.
      * Use in combination with {@link setLoadEndManually} to define your own load end times.
      *
+     * @group Actions
      * @see {@link setLoadEndManually}
      */
     signalLoadEnd(): void;
     /**
-     * Report the HTTP status code and a custom message for the response of the current page.
-     * For example, use to mark your 404 pages that respond with a HTTP status code of 200.
-     * Needs to be called before the onload event of the page has finished, otherwise the information will be discarded.
+     * Reports the HTTP status code and a custom message for the response of the current page.
+     * For example, use this method to mark your 404 pages that respond with an HTTP status code of 200.
+     * This method must be called before the page's onload event finishes; otherwise, the information will be discarded.
      *
-     * @param responseCode Sets the HTTP status code
-     * @param message      An additional informational message
-     * @returns            false if the values were incorrect or the function has been called too late, true otherwise
+     * @group Custom Reporting
+     * @param responseCode The HTTP status code to set.
+     * @param message      An additional informational message.
+     * @returns            Returns false if the values were incorrect or the method was called too late; otherwise, returns true.
      */
     markAsErrorPage(responseCode: number, message: string): boolean;
     /**
      * Reports the HTTP status code and an additional message for the response of the current XHR action.
-     * For example, use when the HTTP status code of your XHR response returns 200, while the result returned
-     * by the server indicates a failed request.
-     * Needs to be called before the XHR action is finished and all listeners have been invoked.
+     * For example, use this method when the HTTP status code of your XHR response is 200, but the server's result indicates a failed request.
+     * This method must be called before the XHR action finishes and all listeners have been invoked.
      *
-     * @param responseCode   The response code of the current XHR action
-     * @param message        An additional informational message
-     * @param parentActionId The optional ID of the action to mark as failed. If it is not present,
-     *                       the currently open action is used.
-     * @returns              false if the values were incorrect or the function has been called too late, true otherwise
+     * @group Custom Reporting
+     * @param responseCode   The HTTP status code of the current XHR action.
+     * @param message        An additional informational message.
+     * @param parentActionId The optional ID of the action to mark as failed. If not provided, the currently open action is used.
+     * @returns              Returns false if the values were incorrect or the method was called too late; otherwise, returns true.
      */
     markXHRFailed(responseCode: number, message: string, parentActionId?: number): boolean;
     /**
-     * Forces beacon sending to make sure actions aren't lost.
-     * For example, use before a window unload event by adding a {@link addPageLeavingListener}.
+     * Forces the sending of a beacon to ensure actions are not lost.
+     * For example, use this method before a window unload event by adding a {@link addPageLeavingListener}.
      *
+     * @group Lifecycle
      * @see {@link addPageLeavingListener}
-     * @param forceSync      DEPRECATED: not used anymore and has no effect if provided.
-     * @param sendPreview    Force sending of preview beacons which haven't been closed yet.
-     * @param killUnfinished Kills unfinished actions and sends them immediately. Handle with care, actions might be inaccurate.
+     * @param forceSync      DEPRECATED: This parameter is not used anymore and has no effect if provided.
+     * @param sendPreview    Forces the sending of preview beacons containing actions that have not yet been closed.
+     * @param killUnfinished Terminates unfinished actions and sends them immediately. Handle with care, as actions might be inaccurate.
      */
     sendBeacon(forceSync: boolean, sendPreview: boolean, killUnfinished: boolean): void;
     /**
-     * Enters a new custom action. Use to set the load start event for a new custom action.
-     * Needs to be called before {@link leaveAction}, which closes the custom action.
+     * Enters a new custom action. Use this method to create a custom action.<br />
+     * This method must be called before {@link leaveAction}, which closes the custom action.
      *
+     * @group Actions
      * @see {@link leaveAction}
-     * @param actionName Name of the action
-     * @param actionType DEPRECATED: not used any more and has no effect if provided
-     * @param startTime  Timestamp in milliseconds. if null, current time is used.
-     * @param sourceUrl  Source url for the action
-     * @returns          ID of the created action or 0 if action was not created.
+     * @param actionName The name of the action.
+     * @param actionType DEPRECATED: This parameter is not used anymore and has no effect if provided.
+     * @param startTime  The timestamp in milliseconds. If falsy, the current time is used.
+     * @param sourceUrl  The source URL for the action.
+     * @returns          The ID of the created action, or 0 if the action was not created.
      */
     enterAction(actionName: string, actionType?: string, startTime?: number, sourceUrl?: string): number;
     /**
-     * Attaches a listener that gets called while entering an action <br />
-     * Remove the listener if not needed or make sure to filter actions if using {@link addActionProperties},
-     * to prevent sending the same action property for every action.
-     * Use to hook into automatic action creation event to influence related concepts like
-     * action naming or action properties.
+     * Attaches a listener that is called while entering an action.<br />
+     * Remove the listener if not needed, or filter actions using {@link addActionProperties} to prevent sending the
+     * same action property for every action. Use this method to hook into the automatic action creation event to
+     * influence related concepts such as action naming or action properties.
      *
+     * @group Actions
      * @see {@link removeEnterActionListener}
      * @see {@link actionName}
      * @see {@link addActionProperties}
-     * @param listener A function that will be called when entering a new action
-     */
-    addEnterActionListener(listener: ActionEnterListener): void;
-    /**
-     * Removes a previously attached listener that detects the enter action event
-     *
-     * @param listener The reference to the listener that needs to be removed
      */
-    removeEnterActionListener(listener: ActionEnterListener): void;
-    /**
-     * Leaves an action that has previously been created by an enterAction call.
-     * Use to set the load end event for a custom action and to complete its creation.
-     * Needs to be called after {@link enterAction}.
-     *
+    addEnterActionListener(
+        /**
+         * The callback function to be triggered when an action is entered.
+         *
+         * @param actionId     The ID of the action being entered.
+         * @param starttime    The start time of the action.
+         * @param isRootAction Indicates if the action is a root action.
+         * @param element      The element that initiated the event.
+         */
+        listener: ActionEnterListener
+    ): void;
+    /**
+     * Removes a previously attached listener that detects the enter action event.
+     *
+     * @group Actions
+     * @see {@link addEnterActionListener}
+     * @param listener The reference to the listener to be removed.
+     */
+    removeEnterActionListener(
+        /**
+         * The callback function to be triggered when an action is entered.
+         *
+         * @param actionId     The ID of the action being entered.
+         * @param starttime    The start time of the action.
+         * @param isRootAction Indicates if the action is a root action.
+         * @param element      The element that initiated the event.
+         */
+        listener: ActionEnterListener
+    ): void;
+    /**
+     * Leaves an action that was previously created using {@link enterAction}. Use this method to set the load end event
+     * for a custom action and complete its creation. This method must be called after {@link enterAction}.
+     *
+     * @group Actions
      * @see {@link enterAction}
-     * @param actionId  ID of the action to leave. must be the value returned by enterAction
-     * @param stopTime  Timestamp in milliseconds.
-     *                  Note that, when providing a stop time, it will force stop the action and prevent visually complete from extending it.
-     * @param startTime Optional start time in milliseconds (necessary if start time should be modified).
-     *                  Note that, when providing a start time, it mustn't be longer than an hour in the past, otherwise the
-     *                  RUM monitoring code will ignore it.
+     * @param actionId  The ID of the action to leave. This must be the value returned by {@link enterAction}.
+     * @param stopTime  The timestamp in milliseconds. Providing a stop time will force the action to stop and prevent
+     *                  the visually complete module from extending it.
+     * @param startTime Optional start time in milliseconds (necessary if the start time should be modified). Note that
+     *                  the start time must not be more than an hour in the past; otherwise it is ignored.
      */
     leaveAction(actionId: number, stopTime?: number, startTime?: number): void;
     /**
-     * Attaches a listener that gets called when leaving an action <br />
-     * Remove the listener if not needed or make sure to filter actions if using {@link addActionProperties},
-     * to prevent sending the same action property for every action.
-     * Use to hook into the out of the box action closing event.
+     * Attaches a listener that is called when leaving an action.<br />
+     * Remove the listener if not needed, or filter actions using {@link addActionProperties} to prevent sending the
+     * same action property for every action. Use this method to hook into the out-of-the-box action closing event.
      *
+     * @group Actions
      * @see {@link removeLeaveActionListener}
      * @see {@link addActionProperties}
-     * @param listener A function that will be called when leaving an action
-     */
-    addLeaveActionListener(listener: ActionLeaveListener): void;
-    /**
-     * Removes a previously attached listener that detects the leave action event
-     *
-     * @param listener A leave action listener to be removed
      */
-    removeLeaveActionListener(listener: ActionLeaveListener): void;
+    addLeaveActionListener(
+        /**
+         * The callback function to be triggered when an action is left.
+         *
+         * @param actionId     The ID of the action being left.
+         * @param stoptime     The end time of the action.
+         * @param isRootAction Indicates if the action is a root action.
+         */
+        listener: ActionLeaveListener
+    ): void;
+    /**
+     * Removes a previously attached listener that detects the leave action event.
+     *
+     * @group Actions
+     * @see {@link addLeaveActionListener}
+     */
+    removeLeaveActionListener(
+        /**
+         * The callback function to be removed.
+         *
+         * @param actionId     The ID of the action being left.
+         * @param stoptime     The end time of the action.
+         * @param isRootAction Indicates if the action is a root action.
+         */
+        listener: ActionLeaveListener
+    ): void;
+
     /**
      * Adds custom {@link https://www.dynatrace.com/support/help/shortlink/user-session-properties | action properties}
      * to the currently active action.  <br />
-     * Only accepts valid java long, java double (as a string representation), Date objects, and
-     * short strings with a maximum length of 100-1000 characters (as configured under Application Settings). <br />
-     * Action properties must be defined first under Application settings and use a lower case key.
+     * Only accepts valid java long, java double (as a string representation), Date objects, and short strings with a
+     * maximum length of 100-1000 characters (as configured under Application Settings). <br />
+     * Action properties must be defined under Application settings and use a lowercase key.
      *
+     * @group Custom Reporting
      * @see {@link sendSessionProperties}
-     * @param parentActionId ID of the action.
-     * @param javaLong       JSON object containing key value pairs of valid numbers. <br /> Value should be between
-     *                       range -9223372036854776000 & 9223372036854776000
-     * @param date           JSON object containing key value pairs of JavaScript Date objects.<br />  Value should be JavaScript Date object
-     * @param shortString    JSON object containing key value pairs of strings.<br />  Value character count should be less
-     *                       than 100 characters
-     * @param javaDouble     JSON object containing key value pairs of valid floating point numbers.<br />
-     *                       Value should be between range -1.7976931348623157e+308 & 1.7976931348623157e+308
-     *
-     *                       Each key value pair must be defined in the following format 'key: { value: value<AllowedMapTypes>, public?: boolean }'
-     *                       Public property is optional and if not declared as true values will be sent as masked(dT_pv) in doNotTrack mode
-     *
-     * @returns              Status report about properties that were passed to the function.
-     *                       It contains data about failed properties with the failure reason.
-     *                       Contains data about properties that were sent successfully and a general message with information about total failed properties.
+     * @param parentActionId The ID of the action.
+     * @param javaLong       A JSON object containing key-value pairs of valid numbers.
+     *                       The values must be within the range -9223372036854776000 to 9223372036854776000.
+     * @param date           A JSON object containing key-value pairs of JavaScript Date objects.
+     * @param shortString    A JSON object containing key-value pairs of strings. Each string must be less than 100 characters.
+     * @param javaDouble     A JSON object containing key-value pairs of valid floating point numbers.
+     *                       The values must be within the range -1.7976931348623157e+308 to 1.7976931348623157e+308.
+     * @returns              A status report about the properties passed to the function. This report contains information about any
+     *                       failed properties with the reason for failure, as well as details of properties that were sent successfully,
+     *                       and a summary message regarding the total number of failed properties.
      */
     addActionProperties(
         parentActionId: number,
@@ -290,207 +375,263 @@ export interface DtrumApi {
         shortString?: PropertyMap<string>,
         javaDouble?: PropertyMap<number>
     ): PropertiesSendingReport | undefined;
+
     /**
-     * Reports an error object to Dynatrace. Use when you catch errors in your own application code
-     * but you also want to propagate them to Dynatrace instead of logging them yourself.
-     * If errors are handled by your own application code it will stop the error from being handled
-     * by the global JavaScript {@link https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror | onerror event handler},
-     * which is used by Dynatrace to automatically capture JavaScript errors.
+     * Reports an error to Dynatrace. Use this method when you catch errors in your application code and want to
+     * propagate them to Dynatrace, rather than handling them solely with your own logging. If the error is managed by
+     * your application, it will not be handled by the global JavaScript
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror | onerror event handler},
+     * which Dynatrace uses to automatically capture JavaScript errors.
      *
-     * @param error          The error to be reported. Any browser error object is supported and if the error doesn't
-     *                       have a stacktrace the RUM JavaScipt monitoring code will attempt to generate one.
-     *                       Alternatively create your own object that has the following properties set: 'message',
-     *                       'file', 'line', 'column', and 'stack'. The 'message' property must be provided; all other values are optional.
-     * @param parentActionId parent action id. if not passed or null, error is added to current action
+     * @group Custom Reporting
+     * @param error          The error to report. Any standard browser error object is supported. If the error does not
+     *                       include a stack trace, the RUM JavaScript monitoring code will attempt to generate one.
+     *                       Alternatively, you can provide your own object with the following properties: 'message',
+     *                       'file', 'line', 'column', and 'stack'. The 'message' property is required; all other
+     *                       properties are optional.
+     * @param parentActionId The parent action ID. If not provided or null, the error is added to the current action.
      */
     reportError(error: Error | string, parentActionId?: number): void;
+
     /**
-     * Sets the {@link https://www.dynatrace.com/support/help/shortlink/user-tagging#user-tagging-via-javascript-api | user tag}.
-     * Use to identify individual users across different browsers, devices, and user sessions.
+     * Sets the
+     * {@link https://www.dynatrace.com/support/help/shortlink/user-tagging#user-tagging-via-javascript-api | user tag},
+     * which is used to identify individual users across different browsers, devices, and sessions.
      *
-     * @param value The name of the user. For example, use a name, userid, or your user's email address.
+     * @group Custom Reporting
+     * @param value The username. This can be a name, user ID, or email address.
      */
     identifyUser(value: string): void;
+
     /**
-     * Adds a listener that is called when the user is leaving the page, but before the RUM monitoring beacon is sent
-     * Use when you want to hook into the unload of the page.
+     * Adds a listener that is called when the user is leaving the page, before the RUM monitoring beacon is sent.
+     * Use this method to hook into the page unload event.
      *
-     * @param listener A function that will be called in case the user leaves the page
+     * @group Lifecycle
      */
-    addPageLeavingListener(listener: PageLeaveListener): void;
+    addPageLeavingListener(
+        /**
+         * A function that will be called in case the user leaves the page.
+         *
+         * @param unloadRunning A boolean that is true if the page is currently being dismissed.
+         */
+        listener: PageLeaveListener
+    ): void;
+
     /**
-     * Indicates the start of a user input. User inputs must always be stopped by calling {@link endUserInput}.
-     * If an XHR call or a page load happens, the RUM monitoring code checks if a user input is active. If so, that user input is
-     * set to have triggered the user action.
-     * Use when a user input is not automatically detected by the RUM monitoring code.
+     * Indicates the start of a user input. Every user input must be concluded by calling {@link endUserInput}.
+     * RUM JavaScript checks for an active user input when an XHR call or a page load occurs. If a user input is active,
+     * that input is marked as having triggered the user action. Use this method when a user input is not automatically detected by RUM JavaScript.
      *
+     * @group Actions
      * @see {@link endUserInput}
-     * @param domNode   DOM node which triggered the action (button, etc) or a string is used for determining its caption
-     * @param type      Type of action: 'click', 'keypress', 'scroll',...
-     * @param addInfo   Additional info for user input such as key, mouse button, etc ('F5', 'RETURN',...)
-     * @param validTime How long this userInput should be valid(in ms)
-     * @returns         An object containing all the information about the userInput
+     * @param domNode   The DOM node (or a string identifier) that triggered the action (e.g., a button). Determines the
+     *                  caption for the resulting action.
+     * @param type      The type of action (e.g., 'click', 'keypress', 'scroll').
+     * @param addInfo   Optional additional information about the user input (e.g., key, mouse button, etc.).
+     * @param validTime The duration (in milliseconds) for which this user input should remain valid.
+     * @returns         An object containing information about the user input.
      */
     beginUserInput(domNode: HTMLElement | string, type: string, addInfo?: string, validTime?: number): DtRumUserInput;
+
     /**
-     * Ends a user input.
+     * Ends a user input that was started with {@link beginUserInput}.
      *
-     * @param userInputObject The user input object returned by {@link beginUserInput}
+     * @group Actions
+     * @param userInputObject The user input object returned by {@link beginUserInput}.
      */
     endUserInput(userInputObject: DtRumUserInput): void;
+
     /**
-     * Extends or initiates actions.
-     * Use when you want to extend an active Load or XHR action by another unlinked XHR call (i.e., action).
-     * This is particularly useful when the XHR call in question is asynchronous in nature
-     * and therefore can't automatically be correlated to an action, which otherwise
-     * would lead to the action being closed too early and inaccurate metrics measurements (e.g., user action duration).
-     * Needs to be called before {@link leaveXhrAction}.
+     * Extends or initiates actions. Use this method when you want to extend an active Load or XHR action with an unlinked XHR call, i.e., an action.
+     * It is particularly useful when the XHR call is asynchronous and cannot be automatically correlated with an action,
+     * which might otherwise cause the action to close prematurely, leading to inaccurate metrics (such as user action duration).
+     * This method must be called before {@link leaveXhrAction}.
      *
+     * @group Actions
      * @see {@link leaveXhrAction}
-     * @param type   Optional additional info about type of XHR (e.g., framework name, etc.)
-     * @param xmode  XHR action creation mode
-     *               0 ... Just extend running XHR actions
-     *               1 ... Extend any running action
-     *               3 ... Start action if user input is present
-     * @param xhrUrl url of the requested resource
-     *               This argument should always be provided. If it is not provided, the request will show as `/undefined` in the waterfall
-     * @returns      ID of the XhrAction
+     * @param type   Optional information about the type of XHR (e.g., framework name).
+     * @param xmode  XHR action creation mode:<br />
+     *               0 ... Extend only running XHR actions.<br />
+     *               1 ... Extend any running action.<br />
+     *               3 ... Start an action if a user input is present.
+     * @param xhrUrl The URL of the requested resource. This argument should always be provided. If omitted, the request will appear as "/undefined" in the waterfall.
+     * @returns      The ID of the XHR action.
      */
     enterXhrAction(type: string, xmode?: 0 | 1 | 3, xhrUrl?: string): number;
+
     /**
-     * Indicates the end of an XHR action
+     * Indicates the end of an XHR action.
      *
-     * @param actionId   ID of the XHR Action
-     * @param [stopTime] The stop time of the XHR Action
+     * @group Actions
+     * @see {@link enterXhrAction}
+     * @param actionId The ID of the XHR action.
+     * @param stopTime The stop time of the XHR action in milliseconds.
      */
     leaveXhrAction(actionId: number, stopTime?: number): void;
+
     /**
-     * Indicates that an XHR callback is active (eg. XMLHttpRequest onreadystatechange) and relinks subsequently triggered XHR actions.
-     * For example, when an XHR callback adds a script tag to your page, any XHR call triggered by it
-     * would not be automatically added to the currently running action.
-     * Calling this function allows relinking to such a subsequent XHR call (i.e., XHR actions) to its initial action.
-     * The XHR callback must also be stopped by {@link leaveXhrCallback}.
+     * Indicates that an XHR callback is active (e.g., XMLHttpRequest onreadystatechange) and links subsequently triggered
+     * XHR actions to this callback.
+     * For example, if an XHR callback adds a script tag to your page and triggers another XHR call, that call
+     * would not automatically be added to the current action. Calling this method allows the subsequent XHR call
+     * to be linked to its initial action. The XHR callback must be concluded with {@link leaveXhrCallback}.
      *
-     * @param actionId ID of the action where callback belongs to
+     * @group Actions
+     * @param actionId The ID of the action to which the callback belongs.
      */
     enterXhrCallback(actionId: number): void;
+
     /**
      * Indicates the end of an XHR callback.
      *
+     * @group Actions
      * @see {@link enterXhrCallback}
-     * @param actionId ID of the action where callback belongs to
+     * @param actionId The ID of the action to which the callback belongs.
      */
     leaveXhrCallback(actionId: number): void;
+
     /**
-     * Indicates the start of a load action. Frameworks often have their own load callback functions
-     * this can be used when framework starts load before 'DOMContentLoaded'.
+     * Indicates the start of a load action. Frameworks often have their own load callback functions, and this method
+     * can be used when a framework begins loading before the 'DOMContentLoaded' event.
      *
+     * @group Actions
      */
     signalOnLoadStart(): void;
+
     /**
-     * Signals that the load end event is provided manually.
-     * Use when you want to extend the onload duration (e.g. to encompass also the initialization of a framework)
+     * Instructs RUM JavaScript to wait for an additional call to {@link signalOnLoadEnd} before closing the 'onload'
+     * action. Note: The load action will only use the provided load end event correctly if {@link signalOnLoadEnd} is
+     * called afterward.
      *
+     * @group Actions
      * @see {@link setLoadEndManually}
-     * Notifies the RUM monitoring code to wait for an additional call of {@link signalOnLoadEnd}, before closing the 'onload' action.
-     * Note: Only when {@link signalOnLoadEnd} is called after, the load action will use the provided load end event correctly.
      */
     incrementOnLoadEndMarkers(): void;
+
     /**
-     * Indicates the end of a load action. needs {@link incrementOnLoadEndMarkers} to be called before.
-     * When the last {@link signalOnLoadEnd} is called, the action is closed.
+     * Indicates the end of a load action. This method requires that {@link incrementOnLoadEndMarkers} has been called beforehand.
+     * The action is closed after the final call to {@link signalOnLoadEnd}.
      *
+     * @group Actions
      * @see {@link signalOnLoadStart}
      */
     signalOnLoadEnd(): void;
+
     /**
-     * Sets the actionName of the currently active action, or the action with the provided id
+     * Sets the name of the currently active action, or the action corresponding to the provided ID.
      *
-     * @param actionName The new name of the action
-     * @param actionId   The action ID of the to be updated action name
-     * @returns          an {@link  ActionNameResult} whether the process was successful
+     * @group Actions
+     * @param actionName The new name for the action.
+     * @param actionId   The ID of the action to update. If omitted, the currently active action is updated.
+     * @returns          An {@link ActionNameResult} indicating whether the update was successful.
      */
     actionName(actionName: string, actionId?: number): ActionNameResult;
+
     /**
-     * Ends the currently active session immediately.
+     * Immediately ends the current session.
+     *
+     * @group Lifecycle
      */
     endSession(): void;
+
     /**
-     * Returns the current time in milliseconds.
-     * It automatically chooses the most accurate way to determine the current time.
+     * Returns the current time in milliseconds using the most accurate method available.
      *
-     * @returns the current time in milliseconds
+     * @group Utilities
+     * @returns The current time in milliseconds.
      */
     now(): number;
+
     /**
-     * Enables the RUM monitoring code in case it was initially disabled via the
+     * Enables RUM JavaScript if it was previously disabled via the
      * {@link https://www.dynatrace.com/support/help/shortlink/configure-rum-privacy#opt-in-mode | opt-in mode}.
-     * Use in combination with a user consent tool to enable RUM monitoring in case the consent has been provided.
+     * Use this method in conjunction with a user consent tool to enable RUM monitoring once consent has been provided.
      *
+     * @group Lifecycle
      * @see {@link disable}
      */
     enable(): void;
+
     /**
-     * Disables the RUM monitoring code and removes all cookies in case dtrum.enable() has been called earlier,
-     * enabling the {@link https://www.dynatrace.com/support/help/shortlink/configure-rum-privacy#opt-in-mode | opt-in mode}.
-     * Use in combination with a user consent tool to disable RUM monitoring in case the consent has not been provided.
+     * Disables RUM JavaScript and removes all cookies if it was previously enabled with {@link enable}, thereby activating
+     * the {@link https://www.dynatrace.com/support/help/shortlink/configure-rum-privacy#opt-in-mode | opt-in mode}.
+     * Use this method along with a user consent tool to disable RUM monitoring when consent is not provided.
      *
+     * @group Lifecycle
      * @see {@link enable}
      */
     disable(): void;
+
     /**
-     * Adds a listener that gets triggered when the current visit times out and before a new visit id is generted.
-     *
-     * @param listener The listener to add
-     */
-    addVisitTimeoutListener(listener: (visitId: string, newVisitAfterTimeout: boolean) => void): void;
+     * Adds a listener that is triggered when the current visit times out and before a new visit ID is generated.
+     *
+     * @group Lifecycle
+     * @param listener The listener function to add, which receives the current visit ID and a boolean indicating if a
+     *                 new visit will start due to timeout.
+     */
+    addVisitTimeoutListener(listener: (
+        /**
+         * The timed out visit ID.
+         */
+        visitId: string,
+        /**
+         * True if a new visit will start due to timeout.
+         */
+        newVisitAfterTimeout: boolean
+    ) => void): void;
+
     /**
-     * Enables session replay
+     * Enables session replay.
      *
-     * @param ignoreCostControl Allows to enable session replay despite cost control configuration
+     * @group Lifecycle
+     * @param ignoreCostControl If true, enables session replay regardless of the cost control configuration.
      */
     enableSessionReplay(ignoreCostControl: boolean): void;
+
     /**
-     * Disables session replay
+     * Disables session replay.
+     *
+     * @group Lifecycle
      */
     disableSessionReplay(): void;
+
     /**
-     * Get and evaluate meta-data for the page.
-     * Use to troubleshoot RUM monitoring.
+     * Retrieves and evaluates metadata for the page, which can be used for troubleshooting RUM monitoring.
      *
-     * @returns Array of metadata objects with configured ids, type, expression, and captured values
+     * @group Custom Reporting
+     * @returns An array of metadata objects, each containing an id, type, expression, the captured value, and an
+     *  optional failure reason.
      */
-    getAndEvaluateMetaData(): {
-        id: string;
-        type: string;
-        expression: string;
-        value: string | null;
-        failureReason?: string;
-    }[];
+    getAndEvaluateMetaData(): MetaData[];
+
     /**
-     * Enables persistent values again. Only applies if 'disablePersistentValues' has been called previously.
-     * Use when you want to re-enable monitoring returning users.
+     * Re-enables persistent values if they were previously disabled by calling {@link disablePersistentValues}.
+     * Use this method when you want to resume monitoring returning users.
+     *
+     * @group Lifecycle
      */
     enablePersistentValues(): void;
+
     /**
-     * Removes all traces of persistent values and disables all functionality that would
-     * recreate one. Note that this has to be called on every page, since it removes persistent RUM monitoring data, including
-     * the information that persistent data shouldn't be stored.
-     * Use when you want to disable monitoring of returning users.
-     * Read more about {@link https://www.dynatrace.com/support/help/shortlink/cookies#cookie-storage | cookie storage}.
+     * Removes all persistent values and disables any functionality that would recreate them. Note that this must be
+     * called on every page, as it erases persistent RUM monitoring data, including the information that prevents
+     * persistent data from being stored.<br />
+     * Use this method when you want to disable monitoring of returning users.
+     * For more information, see {@link https://www.dynatrace.com/support/help/shortlink/cookies#cookie-storage | cookie storage}.
      *
-     * @param remember If true, this configuration state is persisted in local storage, so that it doesn't
-     *                 reset on each page load
+     * @group Lifecycle
+     * @param remember If true, the configuration state is saved in local storage so that it persists across page loads.
      */
     disablePersistentValues(remember: boolean): void;
+
+    // eslint-disable-next-line @dynatrace/dem-eslint-rules/jsagent-changelog-sprint-annotation -- apparently unused since 2018
     /**
-     * Registers a method which will be invoked before the 'diff' action in session replay during recording.
-     *
-     * @param method Listener which will be called before diff action. Listener receives one argument
-     *               which is a string with diff. Listener also must return the diff string.
-     *               Read more about {@link https://www.dynatrace.com/support/help/shortlink/cookies#cookie-storage | cookie storage}.
+     * @deprecated
+     * @ignore
      */
     registerPreDiffMethod(method: (diff: string) => string): void;
+
     /**
      * Sends {@link https://www.dynatrace.com/support/help/shortlink/user-session-properties | session properties} on a beacon
      * currently only accepts valid java long, java double (as a string representation), Date objects, and short strings of
@@ -499,64 +640,110 @@ export interface DtrumApi {
      *
      * Make sure to first define session properties under Application settings before making this API call.
      *
+     * @group Custom Reporting
      * @see {@link addActionProperties} is related and works similarly.
-     * @param javaLongOrObject JSON object containing key value pairs of valid numbers. <br /> Value should be between range -9223372036854776000 & 9223372036854776000
-     * @param date             JSON object containing key value pairs of JavaScript date objects.<br />  Value should be JavaScript Date object
-     * @param shortString      JSON object containing key value pairs of strings.<br />  Value character count should be less than
-     *                         100 characters
-     * @param javaDouble       JSON object containing key value pairs of valid floating point numbers.<br />
-     *                         Value should be between range -1.7976931348623157e+308 & 1.7976931348623157e+308
-     *
-     *                         Each key value pair must be defined in the following format 'key: { value: value<AllowedMapTypes>, public?: boolean }'
-     *                         Public property is optional and if not declared as true values will be sent as masked(dT_pv) in doNotTrack mode
-     *
-     * @returns                Status report about properties that were passed to the function.
-     *                         It contains data about failed properties with the failure reason.
-     *                         Contains data about properties that were sent successfully and a general message with information about total failed properties.
+     * @param javaLongOrObject A JSON object containing key-value pairs of valid numbers.
+     *                         The values must be within the range -9223372036854776000 to 9223372036854776000.
+     * @param date             A JSON object containing key-value pairs of JavaScript Date objects.
+     * @param shortString      A JSON object containing key-value pairs of strings. Each string must be less than 100 characters.
+     * @param javaDouble       A JSON object containing key-value pairs of valid floating point numbers.
+     *                         The values must be within the range -1.7976931348623157e+308 to 1.7976931348623157e+308.
+     * @returns                A status report about the properties passed to the function. This report contains information about any
+     *                         failed properties with the reason for failure, as well as details of properties that were sent successfully,
+     *                         and a summary message regarding the total number of failed properties.
      */
     sendSessionProperties(
         javaLongOrObject?: PropertyMap<number> | PropertyObject,
         date?: PropertyMap<Date>,
         shortString?: PropertyMap<string>,
         javaDouble?: PropertyMap<number>
-
     ): PropertiesSendingReport | undefined;
+
     /**
-     * Report your own{@link https://www.dynatrace.com/support/help/shortlink/configure-application-errors#configure-custom-errors | custom errors}.
-     * For example, use when you want to capture form validation errors in your signup process.
-     * Custom errors must first be defined in the Application settings.
+     * Reports {@link https://www.dynatrace.com/support/help/shortlink/configure-application-errors#configure-custom-errors | custom errors}
+     * to Dynatrace. Use this method to capture custom errors, such as form validation errors, that are defined in Application settings.
      *
-     * @param key           The key of the error. For example, 'validation error'
-     * @param value         The error value. For example, 'Email validation failed'
-     * @param hint          A hint to pinpoint the problem, e.g. content of the input element which triggered the failed validation
-     * @param parentingInfo How the custom error should be attached (default = false).
-     *                      When providing a number: To which open action the custom error event should be attached.
-     *                      When providing a boolean: If true it will get attached to the current active action
+     * @group Custom Reporting
+     * @param key           The key of the error (e.g., 'validation error').
+     * @param value         The error value (e.g., 'Email validation failed').
+     * @param hint          An optional hint to identify the issue, such as the content of the input element that triggered the error.
+     * @param parentingInfo Defines how the custom error should be attached. When a number is provided, the error is attached
+     *                      to the specified open action. When a boolean is provided and true, it is attached to the currently active action.
      */
     reportCustomError(key: string, value: string, hint?: string, parentingInfo?: number | boolean): void;
 
     /**
-     * Enables manual page detection.
-     * After this is called the RUM monitoring code will stop detecting page and page group names automatically and only accepts them via {@link setPage}.
+     * Enables manual page detection. Once this method is called, RUM JavaScript will stop automatically detecting page and page group names
+     * and will only use the values provided via {@link setPage}.
      * It is recommended to call this as early as possible.
+     *
+     * @group Custom Reporting
      */
     enableManualPageDetection(): void;
 
     /**
-     * Starts a new page view and reports it to dynatrace server.
+     * Starts a new page view and reports it to the Dynatrace server.
      *
-     * @param newPage New page containing page name and page group.
-     * @returns       1 if new page is started succesfully.
-     *                2 if new page is started during onload. It means it is cached and will be sent with load action.
-     *                - 1 if page that is being set is the same as previous one.
-     *                - 2 if page is trying to be set but mechanism is not active. Probably 'dtrum.enableManualPageDetection()' was not called.
-     *                Negative number means new page failed to start and positive means that new page is started successfully.
+     * @group Custom Reporting
+     * @returns A negative number if starting the new page failed, or a positive number if the new page was started successfully.
+     *  * -2: The page is being set while manual page detection is inactive (perhaps {@link enableManualPageDetection} was not called).
+     *  * -1: The new page is the same as the previous one.
+     *  * 1: The new page started successfully.
+     *  * 2: The new page started during onload, meaning it is cached and will be sent with the load action.
      */
     setPage(newPage: APIPage): number;
 }
 
-declare global {
-    interface Window {
-        dtrum?: DtrumApi;
-    }
+/**
+ * A valid json object which does not contain functions, undefined, Infinity or NaN as values.
+ * A JSONValue may only be:
+ * 1. primitive (string, number, boolean, null)
+ * 2. an array of JSONValues
+ * 3. another valid JSONObject
+ *
+ * @category Utilities
+ */
+export type JSONObject = { [k: string]: JSONValue };
+/**
+ * @category Utilities
+ */
+export type Primitive = string | number | boolean | null;
+/**
+ * @category Utilities
+ */
+export type JSONArray = JSONValue[];
+/**
+ * @category Utilities
+ */
+export type JSONValue = JSONArray | JSONObject | Primitive;
+
+/**
+ * @inline
+ * @ignore
+ */
+export interface DynatraceApi {
+    /**
+     * Send a Business Event
+     *
+     * With sendBizEvent, you can report a business event. These standalone events are being sent detached from user actions or sessions.
+     * Note: Business events are only supported on Dynatrace SaaS deployments currently.
+     *
+     * @example
+     * ```typescript
+     * dynatrace.sendBizEvent("type", {
+     *     prop: "value",
+     *     name: "biz event name",
+     *     timestamp: 123,
+     *     url: "www.dynatrace.com",
+     *     "page_id": "123456789",
+     *     "window.orientation": "diagonal"
+     * });
+     *```
+     *
+     * @param type   Mandatory event type
+     * @param fields Must be a valid JSON object and cannot contain functions, undefined, Infinity and NaN as values, otherwise they will be replaced with null.
+     *               `Attributes` need to be serializable using JSON.stringify.
+     *               The resulting event will be populated with `attributes` parameter, and enriched with additional properties, thus also empty objects are valid.
+     */
+    sendBizEvent(type: string, fields: JSONObject): void;
 }

package/package.json

@@ -1,9 +1,9 @@
 {
     "name": "@dynatrace/dtrum-api-types",
-    "version": "1.319.3",
+    "version": "1.321.4",
     "description": "Typescript types for the Dynatrace RUM JavaScript dtrum.* API",
     "main": "",
-    "typings": "dtrum.d.ts",
+    "typings": "index.d.ts",
     "homepage": "https://www.dynatrace.com",
     "author": "Dynatrace",
     "license": "SEE LICENSE IN LICENSE.md",