@rudderstack/analytics-js 3.31.8 → 3.32.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [3.32.0](https://github.com/rudderlabs/rudder-sdk-js/compare/@rudderstack/analytics-js@3.31.8...@rudderstack/analytics-js@3.32.0) (2026-08-24)
+
+### Dependency Updates
+
+* `@rudderstack/analytics-js-cookies` updated to version `0.5.13`
+* `@rudderstack/analytics-js-common` updated to version `3.28.4`
+* `@rudderstack/analytics-js-plugins` updated to version `3.15.13`
+
+### Features
+
+* sdk-5054 add state-backed custom context store ([#3129](https://github.com/rudderlabs/rudder-sdk-js/issues/3129)) ([b5ef16f](https://github.com/rudderlabs/rudder-sdk-js/commit/b5ef16fbc71bbdd21fbbdeb38ae98133cf7a7b4b))
+* sdk-5055 seed load-time custom context ([#3132](https://github.com/rudderlabs/rudder-sdk-js/issues/3132)) ([fdda1e0](https://github.com/rudderlabs/rudder-sdk-js/commit/fdda1e046bbdb108f022f550e991a3b8e6c5e6e2))
+* sdk-5056 enrich events with custom context ([#3133](https://github.com/rudderlabs/rudder-sdk-js/issues/3133)) ([fafbd52](https://github.com/rudderlabs/rudder-sdk-js/commit/fafbd5265fb61bdae844f4df1307fd8c11b9d6f1))
+* sdk-5057 add custom context validation foundation ([#3128](https://github.com/rudderlabs/rudder-sdk-js/issues/3128)) ([a197998](https://github.com/rudderlabs/rudder-sdk-js/commit/a19799864f80357f6e67d9e8b0a0d3d065d483aa))
+* sdk-5058 expose custom context public api ([#3131](https://github.com/rudderlabs/rudder-sdk-js/issues/3131)) ([08686ce](https://github.com/rudderlabs/rudder-sdk-js/commit/08686ce687069c5f344c15653691dc35879bc63a))
+
 ## [3.31.8](https://github.com/rudderlabs/rudder-sdk-js/compare/@rudderstack/analytics-js@3.31.7...@rudderstack/analytics-js@3.31.8) (2026-08-19)
 
 ### Dependency Updates

package/dist/npm/index.d.cts

@@ -1,3 +1,5 @@
+import { Signal } from '@preact/signals-core';
+
 type LoggerProvider$1 = Record<Exclude<Lowercase<LogLevel>, Lowercase<'NONE'>>, (...data: any[]) => void>;
 interface ILogger {
     minLogLevel: number;
@@ -202,6 +204,15 @@ type ConsentOptions = {
     trackConsent?: boolean;
 };
 
+type CustomContextValue = string | number | boolean | Date | CustomContext | CustomContextValue[];
+interface CustomContext {
+    [key: string]: CustomContextValue;
+}
+type InputCustomContextValue = string | number | boolean | Date | null | undefined | InputCustomContext | InputCustomContextValue[];
+interface InputCustomContext {
+    [key: string]: InputCustomContextValue;
+}
+
 type UaChTrackLevel = 'none' | 'default' | 'full';
 /**
  * Represents the options parameter for anonymousId
@@ -305,6 +316,7 @@ type SourceConfigurationOverride = {
  * Represents the options parameter in the load API
  */
 type LoadOptions = {
+    context?: InputCustomContext;
     logLevel?: LogLevel;
     integrations?: IntegrationOpts;
     configUrl?: string;
@@ -456,6 +468,38 @@ type ScreenInfo = {
 };
 type UTMParameters = Record<string, string>;
 
+type PageCallOptions = {
+    category?: string;
+    name?: string;
+    properties?: Nullable<ApiObject>;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+type TrackCallOptions = {
+    name: string;
+    properties?: Nullable<ApiObject>;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+type IdentifyCallOptions = {
+    userId?: Nullable<string>;
+    traits?: Nullable<IdentifyTraits>;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+type AliasCallOptions = {
+    to: string;
+    from?: string;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+type GroupCallOptions = {
+    groupId?: Nullable<string>;
+    traits?: Nullable<ApiObject>;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+
 type PageLifecycle = {
     pageViewId: string;
 };
@@ -682,6 +726,18 @@ interface IRudderAnalytics<T = any> {
      * To get group traits set in the SDK
      */
     getGroupTraits(): Nullable<ApiObject> | undefined;
+    /**
+     * Merge fields into the in-memory custom context for subsequent event calls.
+     */
+    setCustomContext(context: InputCustomContext): void;
+    /**
+     * Get a defensive snapshot of the current in-memory custom context.
+     */
+    getCustomContext(): CustomContext;
+    /**
+     * Clear the complete in-memory custom context.
+     */
+    clearCustomContext(): void;
     /**
      * To manually start user session in the SDK
      */
@@ -717,7 +773,7 @@ type RSAnalytics = Pick<IRudderAnalytics, 'track' | 'page' | 'identify' | 'group
  * For now, it is the same as the base destination config
  * but in the future, it can be extended to include more properties
  */
-type CustomDestinationConfig = BaseDestinationConfig & {};
+type CustomDestinationConfig = BaseDestinationConfig;
 /**
  * Type for the custom integration to be used in addCustomIntegration API
  * Defines the contract that all custom integrations must implement
@@ -921,38 +977,6 @@ interface IInMemoryStorageOptions {
     enabled?: boolean;
 }
 
-type PageCallOptions = {
-    category?: string;
-    name?: string;
-    properties?: Nullable<ApiObject>;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-type TrackCallOptions = {
-    name: string;
-    properties?: Nullable<ApiObject>;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-type IdentifyCallOptions = {
-    userId?: Nullable<string>;
-    traits?: Nullable<IdentifyTraits>;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-type AliasCallOptions = {
-    to: string;
-    from?: string;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-type GroupCallOptions = {
-    groupId?: Nullable<string>;
-    traits?: Nullable<ApiObject>;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-
 /**
  * A buffer queue to serve as a store for any type of data
  */
@@ -1130,7 +1154,7 @@ interface IConfigManager {
 
 interface IEventManager {
     init(): void;
-    addEvent(event: APIEvent): void;
+    addEvent(event: APIEvent, customContext: CustomContext): void;
     resume(): void;
 }
 
@@ -1151,6 +1175,17 @@ type RudderAnalyticsPreloader = {
     [index: string]: (...args: any[]) => any;
 };
 
+type CustomContextState = Signal<CustomContext>;
+
+declare class CustomContextStore {
+    private readonly state;
+    private readonly logger;
+    constructor(state: CustomContextState, logger: ILogger);
+    set(context: unknown): void;
+    get(): CustomContext;
+    clear(): void;
+}
+
 interface IAnalytics {
     preloadBuffer: BufferQueue<PreloadedEventCall>;
     initialized: boolean;
@@ -1165,6 +1200,7 @@ interface IAnalytics {
     userSessionManager?: IUserSessionManager;
     pluginsManager?: IPluginsManager;
     clientDataStore?: Store;
+    customContextStore: CustomContextStore;
     /**
      * Start application lifecycle if not already started
      */
@@ -1278,6 +1314,18 @@ interface IAnalytics {
      * To get group traits set in the SDK
      */
     getGroupTraits(): Nullable<ApiObject> | undefined;
+    /**
+     * Merge fields into the current custom context
+     */
+    setCustomContext(context: InputCustomContext): void;
+    /**
+     * Get a defensive snapshot of the current custom context
+     */
+    getCustomContext(): CustomContext;
+    /**
+     * Clear the current custom context
+     */
+    clearCustomContext(): void;
     /**
      * To manually start user session in the SDK
      */
@@ -1439,6 +1487,9 @@ declare class RudderAnalytics implements IRudderAnalytics<IAnalytics> {
     getUserTraits(): Nullable<ApiObject> | undefined;
     getGroupId(): Nullable<string> | undefined;
     getGroupTraits(): Nullable<ApiObject> | undefined;
+    setCustomContext(context: InputCustomContext): void;
+    getCustomContext(): CustomContext;
+    clearCustomContext(): void;
     startSession(sessionId?: number): void;
     endSession(): void;
     getSessionId(): Nullable<number> | undefined;
@@ -1454,4 +1505,4 @@ declare global {
 }
 
 export { RudderAnalytics };
-export type { AnonymousIdOptions, ApiCallback, ApiObject, ApiOptions, BeaconQueueOpts, ConsentOptions, CookieSameSite, CustomDestinationConfig, DestinationsQueueOpts, IdentifyTraits, IntegrationOpts, LoadOptions, LogLevel, PluginName, PreloadedEventCall, QueueOpts, RSACustomIntegration, RSAEvent, RSALogger, RSAnalytics, RudderAnalyticsPreloader, SessionOpts, UaChTrackLevel };
+export type { AnonymousIdOptions, ApiCallback, ApiObject, ApiOptions, BeaconQueueOpts, ConsentOptions, CookieSameSite, CustomContext, CustomContextValue, CustomDestinationConfig, DestinationsQueueOpts, IdentifyTraits, InputCustomContext, InputCustomContextValue, IntegrationOpts, LoadOptions, LogLevel, PluginName, PreloadedEventCall, QueueOpts, RSACustomIntegration, RSAEvent, RSALogger, RSAnalytics, RudderAnalyticsPreloader, SessionOpts, UaChTrackLevel };

package/dist/npm/index.d.mts

@@ -1,3 +1,5 @@
+import { Signal } from '@preact/signals-core';
+
 type LoggerProvider$1 = Record<Exclude<Lowercase<LogLevel>, Lowercase<'NONE'>>, (...data: any[]) => void>;
 interface ILogger {
     minLogLevel: number;
@@ -202,6 +204,15 @@ type ConsentOptions = {
     trackConsent?: boolean;
 };
 
+type CustomContextValue = string | number | boolean | Date | CustomContext | CustomContextValue[];
+interface CustomContext {
+    [key: string]: CustomContextValue;
+}
+type InputCustomContextValue = string | number | boolean | Date | null | undefined | InputCustomContext | InputCustomContextValue[];
+interface InputCustomContext {
+    [key: string]: InputCustomContextValue;
+}
+
 type UaChTrackLevel = 'none' | 'default' | 'full';
 /**
  * Represents the options parameter for anonymousId
@@ -305,6 +316,7 @@ type SourceConfigurationOverride = {
  * Represents the options parameter in the load API
  */
 type LoadOptions = {
+    context?: InputCustomContext;
     logLevel?: LogLevel;
     integrations?: IntegrationOpts;
     configUrl?: string;
@@ -456,6 +468,38 @@ type ScreenInfo = {
 };
 type UTMParameters = Record<string, string>;
 
+type PageCallOptions = {
+    category?: string;
+    name?: string;
+    properties?: Nullable<ApiObject>;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+type TrackCallOptions = {
+    name: string;
+    properties?: Nullable<ApiObject>;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+type IdentifyCallOptions = {
+    userId?: Nullable<string>;
+    traits?: Nullable<IdentifyTraits>;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+type AliasCallOptions = {
+    to: string;
+    from?: string;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+type GroupCallOptions = {
+    groupId?: Nullable<string>;
+    traits?: Nullable<ApiObject>;
+    options?: Nullable<ApiOptions>;
+    callback?: ApiCallback;
+};
+
 type PageLifecycle = {
     pageViewId: string;
 };
@@ -682,6 +726,18 @@ interface IRudderAnalytics<T = any> {
      * To get group traits set in the SDK
      */
     getGroupTraits(): Nullable<ApiObject> | undefined;
+    /**
+     * Merge fields into the in-memory custom context for subsequent event calls.
+     */
+    setCustomContext(context: InputCustomContext): void;
+    /**
+     * Get a defensive snapshot of the current in-memory custom context.
+     */
+    getCustomContext(): CustomContext;
+    /**
+     * Clear the complete in-memory custom context.
+     */
+    clearCustomContext(): void;
     /**
      * To manually start user session in the SDK
      */
@@ -717,7 +773,7 @@ type RSAnalytics = Pick<IRudderAnalytics, 'track' | 'page' | 'identify' | 'group
  * For now, it is the same as the base destination config
  * but in the future, it can be extended to include more properties
  */
-type CustomDestinationConfig = BaseDestinationConfig & {};
+type CustomDestinationConfig = BaseDestinationConfig;
 /**
  * Type for the custom integration to be used in addCustomIntegration API
  * Defines the contract that all custom integrations must implement
@@ -921,38 +977,6 @@ interface IInMemoryStorageOptions {
     enabled?: boolean;
 }
 
-type PageCallOptions = {
-    category?: string;
-    name?: string;
-    properties?: Nullable<ApiObject>;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-type TrackCallOptions = {
-    name: string;
-    properties?: Nullable<ApiObject>;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-type IdentifyCallOptions = {
-    userId?: Nullable<string>;
-    traits?: Nullable<IdentifyTraits>;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-type AliasCallOptions = {
-    to: string;
-    from?: string;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-type GroupCallOptions = {
-    groupId?: Nullable<string>;
-    traits?: Nullable<ApiObject>;
-    options?: Nullable<ApiOptions>;
-    callback?: ApiCallback;
-};
-
 /**
  * A buffer queue to serve as a store for any type of data
  */
@@ -1130,7 +1154,7 @@ interface IConfigManager {
 
 interface IEventManager {
     init(): void;
-    addEvent(event: APIEvent): void;
+    addEvent(event: APIEvent, customContext: CustomContext): void;
     resume(): void;
 }
 
@@ -1151,6 +1175,17 @@ type RudderAnalyticsPreloader = {
     [index: string]: (...args: any[]) => any;
 };
 
+type CustomContextState = Signal<CustomContext>;
+
+declare class CustomContextStore {
+    private readonly state;
+    private readonly logger;
+    constructor(state: CustomContextState, logger: ILogger);
+    set(context: unknown): void;
+    get(): CustomContext;
+    clear(): void;
+}
+
 interface IAnalytics {
     preloadBuffer: BufferQueue<PreloadedEventCall>;
     initialized: boolean;
@@ -1165,6 +1200,7 @@ interface IAnalytics {
     userSessionManager?: IUserSessionManager;
     pluginsManager?: IPluginsManager;
     clientDataStore?: Store;
+    customContextStore: CustomContextStore;
     /**
      * Start application lifecycle if not already started
      */
@@ -1278,6 +1314,18 @@ interface IAnalytics {
      * To get group traits set in the SDK
      */
     getGroupTraits(): Nullable<ApiObject> | undefined;
+    /**
+     * Merge fields into the current custom context
+     */
+    setCustomContext(context: InputCustomContext): void;
+    /**
+     * Get a defensive snapshot of the current custom context
+     */
+    getCustomContext(): CustomContext;
+    /**
+     * Clear the current custom context
+     */
+    clearCustomContext(): void;
     /**
      * To manually start user session in the SDK
      */
@@ -1439,6 +1487,9 @@ declare class RudderAnalytics implements IRudderAnalytics<IAnalytics> {
     getUserTraits(): Nullable<ApiObject> | undefined;
     getGroupId(): Nullable<string> | undefined;
     getGroupTraits(): Nullable<ApiObject> | undefined;
+    setCustomContext(context: InputCustomContext): void;
+    getCustomContext(): CustomContext;
+    clearCustomContext(): void;
     startSession(sessionId?: number): void;
     endSession(): void;
     getSessionId(): Nullable<number> | undefined;
@@ -1454,4 +1505,4 @@ declare global {
 }
 
 export { RudderAnalytics };
-export type { AnonymousIdOptions, ApiCallback, ApiObject, ApiOptions, BeaconQueueOpts, ConsentOptions, CookieSameSite, CustomDestinationConfig, DestinationsQueueOpts, IdentifyTraits, IntegrationOpts, LoadOptions, LogLevel, PluginName, PreloadedEventCall, QueueOpts, RSACustomIntegration, RSAEvent, RSALogger, RSAnalytics, RudderAnalyticsPreloader, SessionOpts, UaChTrackLevel };
+export type { AnonymousIdOptions, ApiCallback, ApiObject, ApiOptions, BeaconQueueOpts, ConsentOptions, CookieSameSite, CustomContext, CustomContextValue, CustomDestinationConfig, DestinationsQueueOpts, IdentifyTraits, InputCustomContext, InputCustomContextValue, IntegrationOpts, LoadOptions, LogLevel, PluginName, PreloadedEventCall, QueueOpts, RSACustomIntegration, RSAEvent, RSALogger, RSAnalytics, RudderAnalyticsPreloader, SessionOpts, UaChTrackLevel };