@rudderstack/analytics-js 3.22.1 → 3.23.0-beta.pr.2434.a0c7ef8

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [3.23.0](https://github.com/rudderlabs/rudder-sdk-js/compare/@rudderstack/analytics-js@3.22.1...@rudderstack/analytics-js@3.23.0) (2025-08-11)
+
+### Dependency Updates
+
+* `@rudderstack/analytics-js-cookies` updated to version `0.5.1`
+* `@rudderstack/analytics-js-common` updated to version `3.23.0`
+* `@rudderstack/analytics-js-plugins` updated to version `3.12.0`
+
+### Features
+
+* add custom device mode integrations support ([#2309](https://github.com/rudderlabs/rudder-sdk-js/issues/2309)) ([db078e6](https://github.com/rudderlabs/rudder-sdk-js/commit/db078e6bae9ab57a18003ac3fa231be8d94cdcaa)), closes [#2295](https://github.com/rudderlabs/rudder-sdk-js/issues/2295) [#2299](https://github.com/rudderlabs/rudder-sdk-js/issues/2299)
+
 ## [3.22.1](https://github.com/rudderlabs/rudder-sdk-js/compare/@rudderstack/analytics-js@3.22.0...@rudderstack/analytics-js@3.22.1) (2025-07-30)
 
 ### Dependency Updates

package/dist/npm/index.d.cts

@@ -12,6 +12,7 @@ interface ILogger {
     setMinLogLevel(logLevel: LogLevel): void;
 }
 type LogLevel = 'LOG' | 'INFO' | 'DEBUG' | 'WARN' | 'ERROR' | 'NONE';
+type RSALogger = Pick<ILogger, 'log' | 'info' | 'debug' | 'warn' | 'error' | 'setMinLogLevel'>;
 
 type LoggerProvider = Record<Exclude<Lowercase<LogLevel>, Lowercase<'NONE'>>, (...data: any[]) => void>;
 
@@ -60,6 +61,7 @@ type IntegrationOpts = {
     [index: string]: DestinationIntgConfig;
 };
 
+type Traits = Nullable<ApiObject>;
 type ApiCallback = (data?: any) => void;
 /**
  * Represents the options parameter in the APIs
@@ -159,6 +161,11 @@ type CookieSameSite = 'Strict' | 'Lax' | 'None';
 type OneTrustCookieCategory = {
     oneTrustCookieCategory: string;
 };
+type ConsentManagement = {
+    deniedConsentIds: Consents;
+    allowedConsentIds: Consents;
+    provider: ConsentManagementProvider;
+};
 type ConsentManagementMetadata = {
     providers: ConsentManagementProviderMetadata[];
 };
@@ -419,6 +426,137 @@ type IdentifyTraits = {
     [index: string]: string | number | boolean | ApiObject | null | Date | (string | number | boolean | null | Date | ApiObject)[] | undefined;
 };
 
+type AppInfo = {
+    readonly name: string;
+    readonly version: string;
+    readonly namespace: string;
+    readonly installType: string;
+};
+type LibraryInfo = {
+    readonly name: string;
+    readonly version: string;
+    readonly snippetVersion?: string;
+};
+type OSInfo = {
+    readonly name: string;
+    readonly version: string;
+};
+type ScreenInfo = {
+    readonly density: number;
+    readonly width: number;
+    readonly height: number;
+    readonly innerWidth: number;
+    readonly innerHeight: number;
+};
+type UTMParameters = Record<string, string>;
+
+type PageLifecycle = {
+    pageViewId: string;
+};
+type AutoTrack = {
+    page: PageLifecycle;
+};
+type RudderContext = {
+    [index: string]: string | number | boolean | ApiObject | UADataValues | Nullable<string> | (string | number | boolean | ApiObject)[] | undefined;
+    traits?: Nullable<ApiObject>;
+    sessionId?: number;
+    sessionStart?: boolean;
+    consentManagement?: ConsentManagement;
+    'ua-ch'?: UADataValues;
+    app: AppInfo;
+    library: LibraryInfo;
+    userAgent: Nullable<string>;
+    os: OSInfo;
+    locale: Nullable<string>;
+    screen: ScreenInfo;
+    campaign?: UTMParameters;
+    trulyAnonymousTracking?: boolean;
+    timezone: string;
+    autoTrack?: AutoTrack;
+};
+type RudderEvent = {
+    type: RudderEventType;
+    channel: string;
+    anonymousId: string;
+    context: RudderContext;
+    originalTimestamp: string;
+    integrations: IntegrationOpts;
+    messageId: string;
+    event: Nullable<string>;
+    previousId?: string;
+    userId?: Nullable<string>;
+    sentAt?: string;
+    properties?: Nullable<ApiObject>;
+    name?: Nullable<string>;
+    category?: Nullable<string>;
+    traits?: Traits;
+    groupId?: Nullable<string>;
+};
+type RSAEvent = {
+    message: RudderEvent;
+};
+
+type DestinationConnectionMode = 'hybrid' | 'cloud' | 'device';
+type DestinationEvent = {
+    eventName: string;
+};
+type ConsentsConfig = {
+    consent: string;
+};
+type ConsentManagementProviderConfig = {
+    provider: ConsentManagementProvider;
+    consents: ConsentsConfig[];
+    resolutionStrategy: string | undefined;
+};
+/**
+ * The common configuration properties for all device
+ * and hybrid mode supported destinations.
+ */
+type BaseDestinationConfig = {
+    blacklistedEvents: DestinationEvent[];
+    whitelistedEvents: DestinationEvent[];
+    eventFilteringOption: EventFilteringOption;
+    consentManagement: ConsentManagementProviderConfig[];
+    connectionMode: DestinationConnectionMode;
+};
+type DestinationConfig = BaseDestinationConfig & {
+    iubendaConsentPurposes?: IubendaConsentPurpose[];
+    oneTrustCookieCategories?: OneTrustCookieCategory[];
+    ketchConsentPurposes?: KetchConsentPurpose[];
+    clickEventConversions?: Conversion[];
+    pageLoadConversions?: Conversion[];
+    conversionID?: string;
+    conversionLinker?: boolean;
+    disableAdPersonalization?: boolean;
+    dynamicRemarketing?: boolean;
+    sendPageView?: boolean;
+    defaultPageConversion?: string;
+    enableConversionEventsFiltering?: boolean;
+    trackConversions?: boolean;
+    trackDynamicRemarketing?: boolean;
+    tagID?: string;
+    advertiserId?: string;
+    partnerId?: string;
+    measurementId?: string;
+    capturePageView?: string;
+    useNativeSDKToSend?: boolean;
+    extendPageViewParams?: boolean;
+    eventMappingFromConfig?: EventMapping[];
+    appKey?: string;
+    dataCenter?: string;
+    enableBrazeLogging?: boolean;
+    enableNestedArrayOperations?: boolean;
+    enableSubscriptionGroupInGroupCall?: boolean;
+    supportDedup?: boolean;
+    trackAnonymousUser?: boolean;
+    serverUrl?: string;
+    containerID?: string;
+    fs_debug_mode?: boolean;
+    fs_org?: boolean;
+    siteID?: string;
+    [key: string]: any;
+};
+
 type AnalyticsIdentifyMethod = {
     (userId: string, traits?: Nullable<IdentifyTraits>, options?: Nullable<ApiOptions>, callback?: ApiCallback): void;
     (userId: string, traits?: Nullable<IdentifyTraits>, callback?: ApiCallback): void;
@@ -556,7 +694,82 @@ interface IRudderAnalytics<T = any> {
      * @param options Consent API options
      */
     consent(options?: ConsentOptions): void;
+    /**
+     * To add a custom integration for a custom destination
+     * @param destinationId The ID of the custom destination from the RudderStack dashboard
+     * @param integration The custom integration object
+     */
+    addCustomIntegration(destinationId: string, integration: RSACustomIntegration): void;
 }
+type RSAnalytics = Pick<IRudderAnalytics, 'track' | 'page' | 'identify' | 'group' | 'alias' | 'getAnonymousId' | 'getUserId' | 'getUserTraits' | 'getGroupId' | 'getGroupTraits' | 'getSessionId'>;
+/**
+ * Type for the custom destination configuration object
+ * 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 for the custom integration to be used in addCustomIntegration API
+ * Defines the contract that all custom integrations must implement
+ */
+type RSACustomIntegration = {
+    /**
+     * Initialize the integration
+     * @param destinationConfig - The custom destination configuration object
+     * @param analytics - The RudderStack analytics instance
+     * @param logger - The logger instance for this integration
+     * @optional
+     */
+    init?: (destinationConfig: CustomDestinationConfig, analytics: RSAnalytics, logger: RSALogger) => void;
+    /**
+     * Check if the integration is ready to process events
+     * @param analytics - The RudderStack analytics instance
+     * @param logger - The logger instance for this integration
+     * @returns boolean indicating whether the integration is ready
+     * @required
+     */
+    isReady: (analytics: RSAnalytics, logger: RSALogger) => boolean;
+    /**
+     * Process track events
+     * @param analytics - The RudderStack analytics instance
+     * @param logger - The logger instance for this integration
+     * @param event - The track event payload to process
+     * @optional
+     */
+    track?: (analytics: RSAnalytics, logger: RSALogger, event: RSAEvent) => void;
+    /**
+     * Process page events
+     * @param analytics - The RudderStack analytics instance
+     * @param logger - The logger instance for this integration
+     * @param event - The page event payload to process
+     * @optional
+     */
+    page?: (analytics: RSAnalytics, logger: RSALogger, event: RSAEvent) => void;
+    /**
+     * Process identify events
+     * @param analytics - The RudderStack analytics instance
+     * @param logger - The logger instance for this integration
+     * @param event - The identify event payload to process
+     * @optional
+     */
+    identify?: (analytics: RSAnalytics, logger: RSALogger, event: RSAEvent) => void;
+    /**
+     * Process group events
+     * @param analytics - The RudderStack analytics instance
+     * @param logger - The logger instance for this integration
+     * @param event - The group event payload to process
+     * @optional
+     */
+    group?: (analytics: RSAnalytics, logger: RSALogger, event: RSAEvent) => void;
+    /**
+     * Process alias events
+     * @param analytics - The RudderStack analytics instance
+     * @param logger - The logger instance for this integration
+     * @param event - The alias event payload to process
+     * @optional
+     */
+    alias?: (analytics: RSAnalytics, logger: RSALogger, event: RSAEvent) => void;
+};
 
 type SDKError = unknown | Error | ErrorEvent | Event | PromiseRejectionEvent;
 type ErrorInfo = {
@@ -825,61 +1038,6 @@ interface IUserSessionManager {
     setAuthToken(token: Nullable<string>): void;
 }
 
-type DestinationConnectionMode = 'hybrid' | 'cloud' | 'device';
-type DestinationEvent = {
-    eventName: string;
-};
-type ConsentsConfig = {
-    consent: string;
-};
-type ConsentManagementProviderConfig = {
-    provider: ConsentManagementProvider;
-    consents: ConsentsConfig[];
-    resolutionStrategy: string | undefined;
-};
-type DestinationConfig = {
-    blacklistedEvents: DestinationEvent[];
-    whitelistedEvents: DestinationEvent[];
-    iubendaConsentPurposes?: IubendaConsentPurpose[];
-    oneTrustCookieCategories?: OneTrustCookieCategory[];
-    ketchConsentPurposes?: KetchConsentPurpose[];
-    consentManagement?: ConsentManagementProviderConfig[];
-    eventFilteringOption: EventFilteringOption;
-    clickEventConversions?: Conversion[];
-    pageLoadConversions?: Conversion[];
-    conversionID?: string;
-    conversionLinker?: boolean;
-    disableAdPersonalization?: boolean;
-    dynamicRemarketing?: boolean;
-    sendPageView?: boolean;
-    defaultPageConversion?: string;
-    enableConversionEventsFiltering?: boolean;
-    trackConversions?: boolean;
-    trackDynamicRemarketing?: boolean;
-    tagID?: string;
-    advertiserId?: string;
-    partnerId?: string;
-    measurementId?: string;
-    capturePageView?: string;
-    useNativeSDKToSend?: boolean;
-    connectionMode?: DestinationConnectionMode;
-    extendPageViewParams?: boolean;
-    eventMappingFromConfig?: EventMapping[];
-    appKey?: string;
-    dataCenter?: string;
-    enableBrazeLogging?: boolean;
-    enableNestedArrayOperations?: boolean;
-    enableSubscriptionGroupInGroupCall?: boolean;
-    supportDedup?: boolean;
-    trackAnonymousUser?: boolean;
-    serverUrl?: string;
-    containerID?: string;
-    fs_debug_mode?: boolean;
-    fs_org?: boolean;
-    siteID?: string;
-    [key: string]: any;
-};
-
 type StatsCollection = {
     errors: {
         enabled: boolean;
@@ -1132,6 +1290,13 @@ interface IAnalytics {
      * To set auth token
      */
     setAuthToken(token: string): void;
+    /**
+     * Add a custom integration for a custom destination
+     * @param destinationId - Unique ID for the custom destination from the RudderStack dashboard
+     * @param integration - The custom integration instance implementing RSACustomIntegration
+     * @param isBufferedInvocation - Internal flag to indicate if this is a buffered call
+     */
+    addCustomIntegration(destinationId: string, integration: RSACustomIntegration, isBufferedInvocation?: boolean): void;
 }
 
 declare class RudderAnalytics implements IRudderAnalytics<IAnalytics> {
@@ -1140,6 +1305,12 @@ declare class RudderAnalytics implements IRudderAnalytics<IAnalytics> {
     defaultAnalyticsKey: string;
     logger: Logger;
     constructor();
+    /**
+     * Create an instance of the current instance that can be used
+     * to call a subset of methods of the current instance.
+     * It is typically used to expose the analytics instance to the integrations (standard and custom)
+     */
+    createSafeAnalyticsInstance(): void;
     static initializeGlobalResources(): void;
     /**
      * Set instance to use if no specific writeKey is provided in methods
@@ -1234,6 +1405,7 @@ declare class RudderAnalytics implements IRudderAnalytics<IAnalytics> {
     getSessionId(): Nullable<number> | undefined;
     setAuthToken(token: string): void;
     consent(options?: ConsentOptions): void;
+    addCustomIntegration(destinationId: string, integration: RSACustomIntegration): void;
 }
 //# sourceMappingURL=RudderAnalytics.d.ts.map
 
@@ -1245,4 +1417,4 @@ declare global {
 //# sourceMappingURL=index.d.ts.map
 
 export { RudderAnalytics };
-export type { AnonymousIdOptions, ApiCallback, ApiObject, ApiOptions, BeaconQueueOpts, ConsentOptions, CookieSameSite, DestinationsQueueOpts, IdentifyTraits, IntegrationOpts, LoadOptions, LogLevel, PluginName, PreloadedEventCall, QueueOpts, RudderAnalyticsPreloader, SessionOpts, UaChTrackLevel };
+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 };