@kubesense/kubesense-browser-rum-core 1.7.0 → 2.0.0-beta.1

package/cjs/boot/rumPublicApi.d.ts

@@ -1,27 +1,32 @@
-import type { Context, DeflateWorker, DeflateEncoderStreamId, DeflateEncoder, PublicApi, ContextManager, TrackingConsent, User, Account, RumInternalContext, Telemetry, Encoder } from '@kubesense/kubesense-browser-core';
+import type { Context, DeflateWorker, DeflateEncoderStreamId, DeflateEncoder, PublicApi, ContextManager, TrackingConsent, User, Account, RumInternalContext, Telemetry, Encoder, SessionManager } from '@kubesense/kubesense-browser-core';
 import type { LifeCycle } from '../domain/lifeCycle';
 import type { ViewHistory } from '../domain/contexts/viewHistory';
-import type { RumSessionManager } from '../domain/rumSessionManager';
 import type { ReplayStats } from '../rawRumEvent.types';
+import { DEFAULT_TRACKED_RESOURCE_HEADERS } from '../domain/configuration';
 import type { RumConfiguration, RumInitConfiguration } from '../domain/configuration';
 import type { ViewOptions } from '../domain/view/trackViews';
-import type { AddDurationVitalOptions, DurationVitalReference, DurationVitalOptions, FeatureOperationOptions, FailureReason } from '../domain/vital/vitalCollection';
+import type { AddDurationVitalOptions, DurationVitalOptions, OperationOptions, FeatureOperationOptions, FailureReason } from '../domain/vital/vitalCollection';
 import type { Hooks } from '../domain/hooks';
 import type { SdkName } from '../domain/contexts/defaultContext';
-import type { LongTaskContexts } from '../domain/longTask/longTaskCollection';
-import type { StartRum, StartRumResult } from './startRum';
+import type { ActionOptions } from '../domain/action/trackManualActions';
+import type { ResourceOptions, ResourceStopOptions } from '../domain/resource/trackManualResources';
+import type { StartRumResult } from './startRum';
 export interface StartRecordingOptions {
     force: boolean;
 }
 /**
  * Public API for the RUM browser SDK.
  *
+ * See [RUM Browser Monitoring Setup](https://docs.kubesense.ai/real_user_monitoring/browser) for further information.
+ *
  * @category Main
  */
 export interface RumPublicApi extends PublicApi {
     /**
      * Init the RUM browser SDK.
      *
+     * See [RUM Browser Monitoring Setup](https://docs.kubesense.ai/real_user_monitoring/browser) for further information.
+     *
      * @category Init
      * @param initConfiguration - Configuration options of the SDK
      * @example
@@ -33,13 +38,11 @@ export interface RumPublicApi extends PublicApi {
      *   // ...
      * })
      * ```
-     *
      */
     init: (initConfiguration: RumInitConfiguration) => void;
     /**
      * Set the tracking consent of the current user.
      *
-     *
      * Data will be sent only if it is set to "granted". This value won't be stored by the library
      * across page loads: you will need to call this method or set the appropriate `trackingConsent`
      * field in the init() method at each page load.
@@ -47,7 +50,8 @@ export interface RumPublicApi extends PublicApi {
      * If this method is called before the init() method, the provided value will take precedence
      * over the one provided as initialization parameter.
      *
-     * *
+     * See [User tracking consent](https://docs.kubesense.ai/real_user_monitoring/browser/advanced_configuration/#user-tracking-consent) for further information.
+     *
      * @category Privacy
      * @param trackingConsent - The user tracking consent
      */
@@ -56,22 +60,26 @@ export interface RumPublicApi extends PublicApi {
      * Set View Name.
      *
      * Enable to manually change the name of the current view.
+     * See [Override default RUM view names](https://docs.kubesense.ai/real_user_monitoring/browser/advanced_configuration/#override-default-rum-view-names) for further information.
+     *
      * @category Context - View
-     * @param name name of the view
+     * @param name - Name of the view
      */
     setViewName: (name: string) => void;
     /**
      * Set View Context.
      *
      * Enable to manually set the context of the current view.
+     *
      * @category Context - View
-     * @param context context of the view
+     * @param context - Context of the view
      */
     setViewContext: (context: Context) => void;
     /**
      * Set View Context Property.
      *
      * Enable to manually set a property of the context of the current view.
+     *
      * @category Context - View
      * @param key - key of the property
      * @param value - value of the property
@@ -79,50 +87,121 @@ export interface RumPublicApi extends PublicApi {
     setViewContextProperty: (key: string, value: any) => void;
     /**
      * Get View Context.
-     * @category Context - View
      *
+     * @category Context - View
      */
     getViewContext(): Context;
     /**
-     * Set the global context information to all events, stored in `@context`
-     *
-     * @category internal - View
-     * @param context Global context
+     * [Internal API] Get the internal SDK context
      *
+     * @internal
      */
     getInternalContext: (startTime?: number) => RumInternalContext | undefined;
     /**
      * Get the init configuration
+     *
+     * @category Init
+     * @returns RumInitConfiguration | undefined
      */
     getInitConfiguration: () => RumInitConfiguration | undefined;
     /**
      * Add a custom action, stored in `@action`
-     * @category Data Collection
-     * @param name Name of the action
-     * @param context Context of the action
      *
+     * See [Send RUM Custom Actions](https://docs.kubesense.ai/real_user_monitoring/guide/send-rum-custom-actions) for further information.
+     *
+     * @category Data Collection
+     * @param name - Name of the action
+     * @param context - Context of the action
      */
     addAction: (name: string, context?: object) => void;
     /**
-     * Add a custom error, stored in `@error`.
+     * Start tracking a custom action.
+     *
+     * Call {@link stopAction} with the same name (and optional `actionKey`) to send a RUM action event
+     * with the elapsed duration. Errors and resources triggered between start and stop are associated
+     * with the action.
+     *
+     * @category Data Collection
+     * @param name - Name of the action
+     * @param options - Options of the action (@default type: 'custom')
+     * @example
+     * ```ts
+     * kubesenseSdk.startAction('checkout', { context: { cartId: 'abc' } })
+     * // ... user completes checkout
+     * kubesenseSdk.stopAction('checkout')
+     * ```
+     */
+    startAction: (name: string, options?: ActionOptions) => void;
+    /**
+     * Stop tracking a custom action started with {@link startAction}.
+     *
+     * Sends a RUM action event with the elapsed duration since the matching start call. Context from
+     * start and stop calls is merged into the event.
+     *
+     * @category Data Collection
+     * @param name - Name of the action
+     * @param options - Options of the action
+     */
+    stopAction: (name: string, options?: ActionOptions) => void;
+    /**
+     * Start tracking a resource manually.
+     *
+     * Use this for network activity that the SDK cannot automatically instrument. Call {@link stopResource}
+     * with the same URL (and optional `resourceKey`) to send a RUM resource event with the elapsed duration.
+     *
+     * @category Data Collection
+     * @param url - URL of the resource
+     * @param options - Options of the resource (@default type: 'other')
+     * @example
+     * ```ts
+     * kubesenseSdk.startResource('https://api.example.com/users', { type: 'fetch', method: 'POST' })
+     * // ... perform the request
+     * kubesenseSdk.stopResource('https://api.example.com/users', { statusCode: 201 })
+     * ```
+     */
+    startResource: (url: string, options?: ResourceOptions) => void;
+    /**
+     * Stop tracking a resource started with {@link startResource}.
+     *
+     * Sends a RUM resource event with the elapsed duration since the matching start call. Context from
+     * start and stop calls is merged into the event.
+     *
      * @category Data Collection
-     * @param error Error. Favor sending a [Javascript Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) to have a stack trace attached to the error event.
-     * @param context Context of the error
+     * @param url - URL of the resource
+     * @param options - Options of the resource
+     */
+    stopResource: (url: string, options?: ResourceStopOptions) => void;
+    /**
+     * Add a custom error, stored in `@error`.
+     *
+     * See [Send RUM Custom Actions](https://docs.kubesense.ai/real_user_monitoring/guide/send-rum-custom-actions) for further information.
      *
+     * @category Data Collection
+     * @param error - Error. Favor sending a [Javascript Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) to have a stack trace attached to the error event.
+     * @param context - Context of the error
      */
     addError: (error: unknown, context?: object) => void;
     /**
      * Add a custom timing relative to the start of the current view,
      * stored in `@view.custom_timings.<timing_name>`
      *
-     * @category Data Collection
-     * @param name Name of the custom timing
-     * @param [time] Epoch timestamp of the custom timing (if not set, will use current time)
-     *
      * Note: passing a relative time is discouraged since it is actually used as-is but displayed relative to the view start.
      * We currently don't provide a way to retrieve the view start time, so it can be challenging to provide a timing relative to the view start.
+     *
+     * @category Data Collection
+     * @param name - Name of the custom timing
+     * @param [time] - Epoch timestamp of the custom timing (if not set, will use current time)
      */
     addTiming: (name: string, time?: number) => void;
+    /**
+     * [Experimental] Manually set the current view's loading time.
+     *
+     * Call this method when the view has finished loading. The loading time is computed as the
+     * elapsed time since the view started. Each call replaces any previously set value (last-call-wins).
+     *
+     * @category Data Collection
+     */
+    setViewLoadingTime: () => void;
     /**
      * Set the global context information to all events, stored in `@context`
      * See [Global context](https://docs.kubesense.ai/real_user_monitoring/browser/advanced_configuration/#global-context) for further information.
@@ -263,7 +342,7 @@ export interface RumPublicApi extends PublicApi {
      *
      * Context - @category Data Collection
      *
-     * @param nameOrOptions - Name or options (name, service, version) for the view
+     * @param nameOrOptions - The view name, or a {@link ViewOptions} object to configure the view
      */
     startView(nameOrOptions?: string | ViewOptions): void;
     /**
@@ -321,67 +400,122 @@ export interface RumPublicApi extends PublicApi {
     /**
      * Start a custom duration vital.
      *
-     * If you plan to have multiple durations for the same vital, you should use the reference returned by this method.
+     * If you plan to have multiple durations for the same vital, use the `vitalKey` option to
+     * differentiate them. Provide the same key when calling `stopDurationVital`.
      *
      * @category Vital - Duration
      * @param name - Name of the custom vital
-     * @param options - Options for the custom vital (context, description)
-     * @returns reference to the custom vital
+     * @param options - Options for the custom vital (vitalKey, context, description)
+     * @example
+     * ```ts
+     * // Simple usage
+     * kubesenseSdk.startDurationVital('my-vital')
+     * kubesenseSdk.stopDurationVital('my-vital')
+     *
+     * // Multiple simultaneous vitals with the same name
+     * const key = crypto.randomUUID()
+     * kubesenseSdk.startDurationVital('my-vital', { vitalKey: key })
+     * kubesenseSdk.stopDurationVital('my-vital', { vitalKey: key })
+     * ```
      */
-    startDurationVital: (name: string, options?: DurationVitalOptions) => DurationVitalReference;
+    startDurationVital: (name: string, options?: DurationVitalOptions) => void;
     /**
      * Stop a custom duration vital
      *
      * @category Vital - Duration
-     * @param nameOrRef - Name or reference of the custom vital
-     * @param options - Options for the custom vital (operationKey, context, description)
+     * @param name - Name of the custom vital
+     * @param options - Options for the custom vital (vitalKey, context, description)
+     */
+    stopDurationVital: (name: string, options?: DurationVitalOptions) => void;
+    /**
+     * Start an operation.
+     *
+     * Call {@link succeedOperation} or {@link failOperation} with the same name (and optional
+     * `operationKey`) to send a RUM vital event marking the end of the operation.
+     *
+     * @category Vital - Operation
+     * @param name - Name of the operation
+     * @param options - Options for the operation (operationKey, context, description)
+     * @example
+     * ```ts
+     * kubesenseSdk.startOperation('checkout')
+     * // ... perform the operation
+     * kubesenseSdk.succeedOperation('checkout')
+     * ```
      */
-    stopDurationVital: (nameOrRef: string | DurationVitalReference, options?: DurationVitalOptions) => void;
+    startOperation: (name: string, options?: OperationOptions) => void;
     /**
-     * start a feature operation
+     * Mark an operation as successful.
+     *
+     * Sends a RUM vital event marking the end of the operation started with {@link startOperation}.
+     *
+     * @category Vital - Operation
+     * @param name - Name of the operation
+     * @param options - Options for the operation (operationKey, context, description)
+     */
+    succeedOperation: (name: string, options?: OperationOptions) => void;
+    /**
+     * Mark an operation as failed.
+     *
+     * Sends a RUM vital event marking the end of the operation started with {@link startOperation}.
+     *
+     * @category Vital - Operation
+     * @param name - Name of the operation
+     * @param failureReason - Reason for the failure
+     * @param options - Options for the operation (operationKey, context, description)
+     */
+    failOperation: (name: string, failureReason: FailureReason, options?: OperationOptions) => void;
+    /**
+     * Start a feature operation.
      *
      * @category Vital - Feature Operation
-     * @param name - Name of the operation step
-     * @param options - Options for the operation step (operationKey, context, description)
-     * @hidden // TODO: replace by @since when GA
+     * @deprecated Use {@link startOperation} instead.
+     * @param name - Name of the operation
+     * @param options - Options for the operation (operationKey, context, description)
      */
     startFeatureOperation: (name: string, options?: FeatureOperationOptions) => void;
     /**
-     * succeed a feature operation
+     * Mark a feature operation as successful.
      *
      * @category Vital - Feature Operation
-     * @param name - Name of the operation step
-     * @param options - Options for the operation step (operationKey, context, description)
-     * @hidden // TODO: replace by @since when GA
+     * @deprecated Use {@link succeedOperation} instead.
+     * @param name - Name of the operation
+     * @param options - Options for the operation (operationKey, context, description)
      */
     succeedFeatureOperation: (name: string, options?: FeatureOperationOptions) => void;
     /**
-     * fail a feature operation
+     * Mark a feature operation as failed.
      *
      * @category Vital - Feature Operation
-     * @param name - Name of the operation step
-     * @param failureReason
-     * @param options - Options for the operation step (operationKey, context, description)
-     * @hidden // TODO: replace by @since when GA
+     * @deprecated Use {@link failOperation} instead.
+     * @param name - Name of the operation
+     * @param failureReason - Reason for the failure
+     * @param options - Options for the operation (operationKey, context, description)
+     */
+    failFeatureOperation: (name: string, failureReason: FailureReason, options?: FeatureOperationOptions) => void;
+    /**
+     * List of default headers used by the {@link RumInitConfiguration.trackResourceHeaders | trackResourceHeaders} option.
+     *
+     * @deprecated You can now omit `name` from a MatchHeader entry to include default headers.
      */
-    failFeatureOperation: (name: string, failureReaon: FailureReason, options?: FeatureOperationOptions) => void;
+    DEFAULT_TRACKED_RESOURCE_HEADERS: typeof DEFAULT_TRACKED_RESOURCE_HEADERS;
 }
 export interface RecorderApi {
     start: (options?: StartRecordingOptions) => void;
     stop: () => void;
-    onRumStart: (lifeCycle: LifeCycle, configuration: RumConfiguration, sessionManager: RumSessionManager, viewHistory: ViewHistory, deflateWorker: DeflateWorker | undefined, telemetry: Telemetry) => void;
+    onRumStart: (lifeCycle: LifeCycle, configuration: RumConfiguration, sessionManager: SessionManager, viewHistory: ViewHistory, deflateWorker: DeflateWorker | undefined, telemetry: Telemetry) => void;
     isRecording: () => boolean;
     getReplayStats: (viewId: string) => ReplayStats | undefined;
     getSessionReplayLink: () => string | undefined;
 }
 export interface ProfilerApi {
     stop: () => void;
-    onRumStart: (lifeCycle: LifeCycle, hooks: Hooks, configuration: RumConfiguration, sessionManager: RumSessionManager, viewHistory: ViewHistory, longTaskContexts: LongTaskContexts, createEncoder: (streamId: DeflateEncoderStreamId) => Encoder) => void;
+    onRumStart: (lifeCycle: LifeCycle, hooks: Hooks, configuration: RumConfiguration, sessionManager: SessionManager, viewHistory: ViewHistory, createEncoder: (streamId: DeflateEncoderStreamId) => Encoder) => void;
 }
 export interface RumPublicApiOptions {
     ignoreInitIfSyntheticsWillInjectRum?: boolean;
     startDeflateWorker?: (configuration: RumConfiguration, source: string, onInitializationFailure: () => void) => DeflateWorker | undefined;
-    createDeflateEncoder?: (configuration: RumConfiguration, worker: DeflateWorker, streamId: DeflateEncoderStreamId) => DeflateEncoder;
+    createDeflateEncoder?: (worker: DeflateWorker, streamId: DeflateEncoderStreamId) => DeflateEncoder;
     sdkName?: SdkName;
 }
 export interface Strategy {
@@ -390,6 +524,7 @@ export interface Strategy {
     getInternalContext: StartRumResult['getInternalContext'];
     stopSession: StartRumResult['stopSession'];
     addTiming: StartRumResult['addTiming'];
+    setLoadingTime: StartRumResult['setLoadingTime'];
     startView: StartRumResult['startView'];
     setViewName: StartRumResult['setViewName'];
     setViewContext: StartRumResult['setViewContext'];
@@ -399,6 +534,10 @@ export interface Strategy {
     userContext: ContextManager;
     accountContext: ContextManager;
     addAction: StartRumResult['addAction'];
+    startAction: StartRumResult['startAction'];
+    stopAction: StartRumResult['stopAction'];
+    startResource: StartRumResult['startResource'];
+    stopResource: StartRumResult['stopResource'];
     addError: StartRumResult['addError'];
     addFeatureFlagEvaluation: StartRumResult['addFeatureFlagEvaluation'];
     startDurationVital: StartRumResult['startDurationVital'];
@@ -406,4 +545,4 @@ export interface Strategy {
     addDurationVital: StartRumResult['addDurationVital'];
     addOperationStepVital: StartRumResult['addOperationStepVital'];
 }
-export declare function makeRumPublicApi(startRumImpl: StartRum, recorderApi: RecorderApi, profilerApi: ProfilerApi, options?: RumPublicApiOptions): RumPublicApi;
+export declare function makeRumPublicApi(recorderApi: RecorderApi, profilerApi: ProfilerApi, options?: RumPublicApiOptions): RumPublicApi;