@rudderstack/analytics-js 3.31.8 → 3.32.0-beta.pr.3194.9b9fe31

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/README.md

@@ -2,7 +2,10 @@
 
 <p align="center">
   <a href="https://rudderstack.com/">
-    <img alt="RudderStack" width="512" src="https://raw.githubusercontent.com/rudderlabs/rudder-sdk-js/develop/assets/rs-logo-full-light.jpg">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rudderlabs/rudder-sdk-js/develop/assets/rs-logo-full-dark.png">
+      <img alt="RudderStack" width="512" src="https://raw.githubusercontent.com/rudderlabs/rudder-sdk-js/develop/assets/rs-logo-full-light.jpg">
+    </picture>
   </a>
   <br />
   <caption>The Customer Data Platform for Developers</caption>
@@ -91,8 +94,8 @@ RudderStack JS SDK [service worker](https://www.npmjs.com/package/@rudderstack/a
 
 For more details, see:
 
-- [Vercel Edge Usage](https://github.com/rudderlabs/rudder-sdk-js/blob/main/examples/serverless/USAGE.md)
-- [Cloudflare Worker Usage](https://github.com/rudderlabs/rudder-sdk-js/blob/main/examples/serverless/USAGE.md)
+- [Vercel Edge Usage](https://github.com/rudderlabs/rudder-sdk-js/blob/main/examples/serverless/USAGE.md#vercel-edge)
+- [Cloudflare Worker Usage](https://github.com/rudderlabs/rudder-sdk-js/blob/main/examples/serverless/USAGE.md#cloudflare-worker)
 
 ## License
 

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
@@ -265,9 +276,22 @@ type DestinationsQueueOpts = {
 };
 type OnLoadedCallback = (analytics: any) => void;
 type DeliveryType = 'immediate' | 'buffer';
+/**
+ * @deprecated Use the `storage` load API option to control what is persisted before consent is given. It will be removed in the next major version.
+ */
 type StorageStrategy = 'none' | 'session' | 'anonymousId';
 type PreConsentStorageOptions = {
-    strategy: StorageStrategy;
+    /**
+     * Applies the `storage` load API option during the pre-consent phase, taking precedence over
+     * `strategy`. When it is not enabled, `strategy` decides what is persisted instead, and with
+     * neither of them nothing is persisted before consent is given. Defaults to false.
+     */
+    enabled?: boolean;
+    /**
+     * Only applies when `enabled` is not set. Defaults to persisting nothing.
+     * @deprecated Enable `storage` in the pre-consent options and use the `storage` load API option instead. It will be removed in the next major version.
+     */
+    strategy?: StorageStrategy;
 };
 type PreConsentEventsOptions = {
     delivery: DeliveryType;
@@ -305,6 +329,7 @@ type SourceConfigurationOverride = {
  * Represents the options parameter in the load API
  */
 type LoadOptions = {
+    context?: InputCustomContext;
     logLevel?: LogLevel;
     integrations?: IntegrationOpts;
     configUrl?: string;
@@ -456,6 +481,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 +739,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 +786,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 +990,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
  */
@@ -1024,6 +1061,18 @@ declare class Store implements IStore {
     onError(error: unknown, customMessage?: string, groupingHash?: string): void;
 }
 
+type StatsCollection = {
+    errors: {
+        enabled: boolean;
+        provider?: string;
+    };
+    metrics: {
+        enabled: boolean;
+    };
+};
+
+type CustomContextState = Signal<CustomContext>;
+
 interface IUserSessionManager {
     storeManager?: IStoreManager;
     init(): void;
@@ -1046,16 +1095,6 @@ interface IUserSessionManager {
     setAuthToken(token: Nullable<string>): void;
 }
 
-type StatsCollection = {
-    errors: {
-        enabled: boolean;
-        provider?: string;
-    };
-    metrics: {
-        enabled: boolean;
-    };
-};
-
 type DestinationDefinition = {
     name: string;
     displayName: string;
@@ -1130,7 +1169,7 @@ interface IConfigManager {
 
 interface IEventManager {
     init(): void;
-    addEvent(event: APIEvent): void;
+    addEvent(event: APIEvent, customContext: CustomContext): void;
     resume(): void;
 }
 
@@ -1151,6 +1190,15 @@ type RudderAnalyticsPreloader = {
     [index: string]: (...args: any[]) => any;
 };
 
+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 +1213,7 @@ interface IAnalytics {
     userSessionManager?: IUserSessionManager;
     pluginsManager?: IPluginsManager;
     clientDataStore?: Store;
+    customContextStore: CustomContextStore;
     /**
      * Start application lifecycle if not already started
      */
@@ -1278,6 +1327,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 +1500,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 +1518,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
@@ -265,9 +276,22 @@ type DestinationsQueueOpts = {
 };
 type OnLoadedCallback = (analytics: any) => void;
 type DeliveryType = 'immediate' | 'buffer';
+/**
+ * @deprecated Use the `storage` load API option to control what is persisted before consent is given. It will be removed in the next major version.
+ */
 type StorageStrategy = 'none' | 'session' | 'anonymousId';
 type PreConsentStorageOptions = {
-    strategy: StorageStrategy;
+    /**
+     * Applies the `storage` load API option during the pre-consent phase, taking precedence over
+     * `strategy`. When it is not enabled, `strategy` decides what is persisted instead, and with
+     * neither of them nothing is persisted before consent is given. Defaults to false.
+     */
+    enabled?: boolean;
+    /**
+     * Only applies when `enabled` is not set. Defaults to persisting nothing.
+     * @deprecated Enable `storage` in the pre-consent options and use the `storage` load API option instead. It will be removed in the next major version.
+     */
+    strategy?: StorageStrategy;
 };
 type PreConsentEventsOptions = {
     delivery: DeliveryType;
@@ -305,6 +329,7 @@ type SourceConfigurationOverride = {
  * Represents the options parameter in the load API
  */
 type LoadOptions = {
+    context?: InputCustomContext;
     logLevel?: LogLevel;
     integrations?: IntegrationOpts;
     configUrl?: string;
@@ -456,6 +481,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 +739,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 +786,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 +990,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
  */
@@ -1024,6 +1061,18 @@ declare class Store implements IStore {
     onError(error: unknown, customMessage?: string, groupingHash?: string): void;
 }
 
+type StatsCollection = {
+    errors: {
+        enabled: boolean;
+        provider?: string;
+    };
+    metrics: {
+        enabled: boolean;
+    };
+};
+
+type CustomContextState = Signal<CustomContext>;
+
 interface IUserSessionManager {
     storeManager?: IStoreManager;
     init(): void;
@@ -1046,16 +1095,6 @@ interface IUserSessionManager {
     setAuthToken(token: Nullable<string>): void;
 }
 
-type StatsCollection = {
-    errors: {
-        enabled: boolean;
-        provider?: string;
-    };
-    metrics: {
-        enabled: boolean;
-    };
-};
-
 type DestinationDefinition = {
     name: string;
     displayName: string;
@@ -1130,7 +1169,7 @@ interface IConfigManager {
 
 interface IEventManager {
     init(): void;
-    addEvent(event: APIEvent): void;
+    addEvent(event: APIEvent, customContext: CustomContext): void;
     resume(): void;
 }
 
@@ -1151,6 +1190,15 @@ type RudderAnalyticsPreloader = {
     [index: string]: (...args: any[]) => any;
 };
 
+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 +1213,7 @@ interface IAnalytics {
     userSessionManager?: IUserSessionManager;
     pluginsManager?: IPluginsManager;
     clientDataStore?: Store;
+    customContextStore: CustomContextStore;
     /**
      * Start application lifecycle if not already started
      */
@@ -1278,6 +1327,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 +1500,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 +1518,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 };