@ninetailed/experience.js 7.4.2 → 7.5.0-beta.0

package/README.md

@@ -1,7 +1,32 @@
-# experience-sdk-javascript
+# @ninetailed/experience.js
 
-This library was generated with [Nx](https://nx.dev).
+<!--Insert badges begin-->
+<!--GENERATED TEXT - DO NOT EDIT HERE -->
+<p align="center">
+<a href="https://www.npmjs.com/package/@ninetailed/experience.js"><img src="https://img.shields.io/npm/v/@ninetailed/experience.js.svg" alt="NPM Version" /></a>
+<a href="https://www.npmjs.com/package/@ninetailed/experience.js"><img src="https://img.shields.io/npm/l/@ninetailed/experience.js.svg" alt="Package License" /></a>
+<a href="https://www.npmjs.com/package/@ninetailed/experience.js"><img src="https://img.shields.io/npm/dm/@ninetailed/experience.js.svg" alt="NPM Downloads" /></a>
+<a href="https://docs.ninetailed.io/" target="_blank"><img src="https://img.shields.io/badge/%F0%9F%93%96-Documentation-green.svg" alt="Documentation"/></a>
+<a href="ninetailed-community.slack.com" target="_blank"><img src="https://img.shields.io/badge/Slack-Ninetailed%20Community-blue.svg" alt="Join the official Slack community"/>
+</p>
+
+<!--Insert badges end-->
+
+<!--Insert template begin-->
+<!--GENERATED TEXT - DO NOT EDIT HERE -->
+
+## About Ninetailed
+
+Our extensible [Experience SDKs](https://docs.ninetailed.io/#getting-started-for-developers) help you integrate Ninetailed Experiences into your JavaScript / TypeScript applications. With support for ESR and SSR, out-of-the-box utilities, and plugins, you have all the tools you need to get started.
+
+Using a framework we don't currently support? No problem! Our [Experience API](https://docs.ninetailed.io/for-developers/experience-api) enables you to use Ninetailed Experiences virtually anywhere.
+
+<!--Insert template end-->
+
+## Building
+
+Run `nx build sdks-javascript` to build the library.
 
 ## Running unit tests
 
-Run `nx test experience-sdk-javascript` to execute the unit tests via [Jest](https://jestjs.io).
+Run `nx test sdks-javascript` to execute the unit tests via [Jest](https://jestjs.io).

package/index.cjs

@@ -66,9 +66,8 @@ const buildClientNinetailedRequestContext = () => ({
 });
 
 /**
- * Similar to _.throttle but waits for the promise to resolve. There is no
- * wait time because you can simply await `Promise.timeout` inside `fn`
- * to wait some time before the next call.
+ * Similar to _.throttle but waits for the promise to resolve.
+ * There is no "wait time" because you can simply await `Promise.timeout` inside `fn` to wait some time before the next call.
  */
 function asyncThrottle(fn) {
   let runningPromise;
@@ -107,11 +106,11 @@ const EMPTY_MERGE_ID = 'nt:empty-merge-id';
 
 const PLUGIN_NAME = 'ninetailed';
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
-const ninetailedPlugin = ({
+const ninetailedCorePlugin = ({
   apiClient,
-  profile,
   locale,
   ninetailed,
+  onInitProfileId,
   buildClientContext
 }) => {
   let _instance;
@@ -168,7 +167,6 @@ const ninetailedPlugin = ({
         experience_jsShared.logger.debug('No fallback profile found - setting profile to null.');
         _instance.dispatch({
           type: PROFILE_CHANGE,
-          // TODO is it a good idea to set the profile to null?
           profile: null,
           experiences: fallbackExperiences,
           error
@@ -209,8 +207,11 @@ const ninetailedPlugin = ({
         instance.storage.setItem(ANONYMOUS_ID, legacyAnonymousId);
         instance.storage.removeItem(LEGACY_ANONYMOUS_ID);
       }
-      if (profile) {
-        instance.storage.setItem(ANONYMOUS_ID, profile.id);
+      if (typeof onInitProfileId === 'function') {
+        const profileId = onInitProfileId(instance.storage.getItem(ANONYMOUS_ID));
+        if (typeof profileId === 'string') {
+          instance.storage.setItem(ANONYMOUS_ID, profileId);
+        }
       }
       instance.on(SET_ENABLED_FEATURES, ({
         payload
@@ -282,7 +283,6 @@ const ninetailedPlugin = ({
     },
     methods: {
       reset: (...args) => __awaiter(void 0, void 0, void 0, function* () {
-        // TODO it seems reset gets called during Next.js SSR builds. Need to verify that.
         experience_jsShared.logger.debug('Resetting profile.');
         const instance = args[args.length - 1];
         instance.dispatch({
@@ -371,6 +371,7 @@ class Ninetailed {
     onLog,
     onError,
     buildClientContext,
+    onInitProfileId,
     componentViewTrackingThreshold = 2000,
     storageImpl
   } = {}) {
@@ -383,7 +384,7 @@ class Ninetailed {
         }
         yield this.waitUntilInitialized();
         yield this.instance.page(data, this.buildOptions(options));
-        return this.eventQueue.flush();
+        return this.ninetailedCorePlugin.flush();
       } catch (error) {
         experience_jsShared.logger.error(error);
         if (error instanceof RangeError) {
@@ -400,7 +401,7 @@ class Ninetailed {
         }
         yield this.waitUntilInitialized();
         yield this.instance.track(event.toString(), result.data, this.buildOptions(options));
-        return this.eventQueue.flush();
+        return this.ninetailedCorePlugin.flush();
       } catch (error) {
         experience_jsShared.logger.error(error);
         if (error instanceof RangeError) {
@@ -460,7 +461,7 @@ class Ninetailed {
         }
         yield this.waitUntilInitialized();
         yield this.instance.identify(uid && uid.toString() !== '' ? uid.toString() : EMPTY_MERGE_ID, result.data, this.buildOptions(options));
-        return this.eventQueue.flush();
+        return this.ninetailedCorePlugin.flush();
       } catch (error) {
         experience_jsShared.logger.error(error);
         if (error instanceof RangeError) {
@@ -573,16 +574,17 @@ class Ninetailed {
       experience_jsShared.logger.addSink(new experience_jsShared.OnErrorLogSink(onError));
     }
     this.logger = experience_jsShared.logger;
-    this.eventQueue = ninetailedPlugin({
+    this.ninetailedCorePlugin = ninetailedCorePlugin({
       apiClient: this.apiClient,
       locale,
       requestTimeout,
       buildClientContext,
+      onInitProfileId,
       ninetailed: this
     });
     this.instance = Analytics__default["default"](Object.assign({
       app: 'ninetailed',
-      plugins: [...this.plugins, this.eventQueue]
+      plugins: [...this.plugins, this.ninetailedCorePlugin]
     }, storageImpl ? {
       storage: storageImpl
     } : {}));
@@ -730,9 +732,6 @@ const TrackComponentProperties = zod.z.object({
   isPersonalized: zod.z.boolean()
 });
 
-/**
- * @deprecated Use `NinetailedPlugin` from the sdks/javascript package instead.
- */
 class NinetailedPlugin {}
 
 const ElementSeenPayloadSchema = zod.z.object({
@@ -932,7 +931,7 @@ exports.TrackComponentProperties = TrackComponentProperties;
 exports.buildClientNinetailedRequestContext = buildClientNinetailedRequestContext;
 exports.decodeExperienceVariantsMap = decodeExperienceVariantsMap;
 exports.makeExperienceSelectMiddleware = makeExperienceSelectMiddleware;
-exports.ninetailedPlugin = ninetailedPlugin;
+exports.ninetailedCorePlugin = ninetailedCorePlugin;
 exports.selectPluginsHavingExperienceSelectionMiddleware = selectPluginsHavingExperienceSelectionMiddleware;
 exports.selectPluginsHavingOnChangeEmitter = selectPluginsHavingOnChangeEmitter;
 exports.selectVariant = selectVariant;

package/index.js

@@ -59,9 +59,8 @@ const buildClientNinetailedRequestContext = () => ({
 });
 
 /**
- * Similar to _.throttle but waits for the promise to resolve. There is no
- * wait time because you can simply await `Promise.timeout` inside `fn`
- * to wait some time before the next call.
+ * Similar to _.throttle but waits for the promise to resolve.
+ * There is no "wait time" because you can simply await `Promise.timeout` inside `fn` to wait some time before the next call.
  */
 function asyncThrottle(fn) {
   let runningPromise;
@@ -100,11 +99,11 @@ const EMPTY_MERGE_ID = 'nt:empty-merge-id';
 
 const PLUGIN_NAME = 'ninetailed';
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
-const ninetailedPlugin = ({
+const ninetailedCorePlugin = ({
   apiClient,
-  profile,
   locale,
   ninetailed,
+  onInitProfileId,
   buildClientContext
 }) => {
   let _instance;
@@ -161,7 +160,6 @@ const ninetailedPlugin = ({
         logger.debug('No fallback profile found - setting profile to null.');
         _instance.dispatch({
           type: PROFILE_CHANGE,
-          // TODO is it a good idea to set the profile to null?
           profile: null,
           experiences: fallbackExperiences,
           error
@@ -202,8 +200,11 @@ const ninetailedPlugin = ({
         instance.storage.setItem(ANONYMOUS_ID, legacyAnonymousId);
         instance.storage.removeItem(LEGACY_ANONYMOUS_ID);
       }
-      if (profile) {
-        instance.storage.setItem(ANONYMOUS_ID, profile.id);
+      if (typeof onInitProfileId === 'function') {
+        const profileId = onInitProfileId(instance.storage.getItem(ANONYMOUS_ID));
+        if (typeof profileId === 'string') {
+          instance.storage.setItem(ANONYMOUS_ID, profileId);
+        }
       }
       instance.on(SET_ENABLED_FEATURES, ({
         payload
@@ -275,7 +276,6 @@ const ninetailedPlugin = ({
     },
     methods: {
       reset: (...args) => __awaiter(void 0, void 0, void 0, function* () {
-        // TODO it seems reset gets called during Next.js SSR builds. Need to verify that.
         logger.debug('Resetting profile.');
         const instance = args[args.length - 1];
         instance.dispatch({
@@ -364,6 +364,7 @@ class Ninetailed {
     onLog,
     onError,
     buildClientContext,
+    onInitProfileId,
     componentViewTrackingThreshold = 2000,
     storageImpl
   } = {}) {
@@ -376,7 +377,7 @@ class Ninetailed {
         }
         yield this.waitUntilInitialized();
         yield this.instance.page(data, this.buildOptions(options));
-        return this.eventQueue.flush();
+        return this.ninetailedCorePlugin.flush();
       } catch (error) {
         logger.error(error);
         if (error instanceof RangeError) {
@@ -393,7 +394,7 @@ class Ninetailed {
         }
         yield this.waitUntilInitialized();
         yield this.instance.track(event.toString(), result.data, this.buildOptions(options));
-        return this.eventQueue.flush();
+        return this.ninetailedCorePlugin.flush();
       } catch (error) {
         logger.error(error);
         if (error instanceof RangeError) {
@@ -453,7 +454,7 @@ class Ninetailed {
         }
         yield this.waitUntilInitialized();
         yield this.instance.identify(uid && uid.toString() !== '' ? uid.toString() : EMPTY_MERGE_ID, result.data, this.buildOptions(options));
-        return this.eventQueue.flush();
+        return this.ninetailedCorePlugin.flush();
       } catch (error) {
         logger.error(error);
         if (error instanceof RangeError) {
@@ -566,16 +567,17 @@ class Ninetailed {
       logger.addSink(new OnErrorLogSink(onError));
     }
     this.logger = logger;
-    this.eventQueue = ninetailedPlugin({
+    this.ninetailedCorePlugin = ninetailedCorePlugin({
       apiClient: this.apiClient,
       locale,
       requestTimeout,
       buildClientContext,
+      onInitProfileId,
       ninetailed: this
     });
     this.instance = Analytics(Object.assign({
       app: 'ninetailed',
-      plugins: [...this.plugins, this.eventQueue]
+      plugins: [...this.plugins, this.ninetailedCorePlugin]
     }, storageImpl ? {
       storage: storageImpl
     } : {}));
@@ -723,9 +725,6 @@ const TrackComponentProperties = z.object({
   isPersonalized: z.boolean()
 });
 
-/**
- * @deprecated Use `NinetailedPlugin` from the sdks/javascript package instead.
- */
 class NinetailedPlugin {}
 
 const ElementSeenPayloadSchema = z.object({
@@ -865,4 +864,4 @@ const makeExperienceSelectMiddleware = ({
   };
 };
 
-export { ANONYMOUS_ID, COMPONENT, COMPONENT_START, CONSENT, DEBUG_FLAG, EMPTY_MERGE_ID, EXPERIENCES_FALLBACK_CACHE, ElementSeenPayloadSchema, HAS_SEEN_COMPONENT, HAS_SEEN_ELEMENT, LEGACY_ANONYMOUS_ID, Ninetailed, NinetailedPlugin, OnChangeEmitter, PAGE_HIDDEN, PLUGIN_NAME, PROFILE_CHANGE, PROFILE_FALLBACK_CACHE, PROFILE_RESET, SET_ENABLED_FEATURES, TrackComponentProperties, buildClientNinetailedRequestContext, decodeExperienceVariantsMap, makeExperienceSelectMiddleware, ninetailedPlugin, selectPluginsHavingExperienceSelectionMiddleware, selectPluginsHavingOnChangeEmitter, selectVariant };
+export { ANONYMOUS_ID, COMPONENT, COMPONENT_START, CONSENT, DEBUG_FLAG, EMPTY_MERGE_ID, EXPERIENCES_FALLBACK_CACHE, ElementSeenPayloadSchema, HAS_SEEN_COMPONENT, HAS_SEEN_ELEMENT, LEGACY_ANONYMOUS_ID, Ninetailed, NinetailedPlugin, OnChangeEmitter, PAGE_HIDDEN, PLUGIN_NAME, PROFILE_CHANGE, PROFILE_FALLBACK_CACHE, PROFILE_RESET, SET_ENABLED_FEATURES, TrackComponentProperties, buildClientNinetailedRequestContext, decodeExperienceVariantsMap, makeExperienceSelectMiddleware, ninetailedCorePlugin, selectPluginsHavingExperienceSelectionMiddleware, selectPluginsHavingOnChangeEmitter, selectVariant };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@ninetailed/experience.js",
-  "version": "7.4.2",
+  "version": "7.5.0-beta.0",
+  "license": "BSL-1.1",
   "module": "./index.js",
   "main": "./index.cjs",
   "type": "module",
-  "types": "./index.d.ts",
+  "types": "./src/index.d.ts",
   "dependencies": {
-    "@ninetailed/experience.js-shared": "7.4.2",
+    "@ninetailed/experience.js-shared": "7.5.0-beta.0",
     "analytics": "0.8.1",
     "zod": "3.21.4"
   },

package/{index.d.ts → src/index.d.ts}

@@ -1,5 +1,5 @@
 export * from './lib/constants';
-export * from './lib/analytics';
+export * from './lib/ninetailedCorePlugin';
 export * from './lib/Ninetailed';
 export * from './lib/selectVariant';
 export * from './lib/types';

package/{lib → src/lib}/Ninetailed.d.ts

@@ -28,6 +28,7 @@ type Options = {
     onLog?: OnLogHandler;
     onError?: OnErrorHandler;
     componentViewTrackingThreshold?: number;
+    onInitProfileId?: (profileId?: string) => string | undefined;
     buildClientContext?: () => NinetailedRequestContext;
     storageImpl?: Storage;
 };
@@ -37,7 +38,7 @@ export declare class Ninetailed implements NinetailedInstance {
     private _profileState;
     private isInitialized;
     private readonly apiClient;
-    private readonly eventQueue;
+    private readonly ninetailedCorePlugin;
     private readonly elementSeenObserver;
     private readonly observedElements;
     private readonly clientId;
@@ -45,7 +46,7 @@ export declare class Ninetailed implements NinetailedInstance {
     readonly plugins: NinetailedPlugin[];
     readonly logger: Logger;
     private readonly componentViewTrackingThreshold;
-    constructor(ninetailedApiClientInstanceOrOptions: NinetailedApiClientInstanceOrOptions, { plugins, url, locale, requestTimeout, onLog, onError, buildClientContext, componentViewTrackingThreshold, storageImpl, }?: Options);
+    constructor(ninetailedApiClientInstanceOrOptions: NinetailedApiClientInstanceOrOptions, { plugins, url, locale, requestTimeout, onLog, onError, buildClientContext, onInitProfileId, componentViewTrackingThreshold, storageImpl, }?: Options);
     page: (data?: Partial<PageviewProperties>, options?: EventFunctionOptions) => Promise<import("./types").FlushResult>;
     track: (event: string, properties?: Properties, options?: EventFunctionOptions) => Promise<import("./types").FlushResult>;
     /**

package/{lib/analytics → src/lib/ninetailedCorePlugin}/index.d.ts

@@ -1,3 +1,3 @@
-export * from './get-analytics-plugin';
+export * from './ninetailedCorePlugin';
 export * from './constants';
 export * from './Events';

package/src/lib/ninetailedCorePlugin/ninetailedCorePlugin.d.ts

@@ -0,0 +1,16 @@
+import { Locale, NinetailedApiClient, NinetailedRequestContext } from '@ninetailed/experience.js-shared';
+import { NinetailedInstance, FlushResult, NinetailedPlugin } from '../types';
+type AnalyticsPluginNinetailedConfig = {
+    apiClient: NinetailedApiClient;
+    locale?: Locale;
+    requestTimeout?: number;
+    onInitProfileId?: (profileId?: string) => string | undefined;
+    buildClientContext?: () => NinetailedRequestContext;
+    ninetailed: NinetailedInstance;
+};
+export declare const PLUGIN_NAME = "ninetailed";
+export interface NinetailedCorePlugin extends NinetailedPlugin {
+    flush: () => Promise<FlushResult>;
+}
+export declare const ninetailedCorePlugin: ({ apiClient, locale, ninetailed, onInitProfileId, buildClientContext, }: AnalyticsPluginNinetailedConfig) => NinetailedCorePlugin;
+export {};

package/{lib → src/lib}/types/NinetailedPlugin.d.ts

@@ -5,9 +5,6 @@ export type EventHandlerParams<T = unknown> = {
     instance: AnalyticsInstance;
 };
 export type EventHandler<T = unknown> = (params: EventHandlerParams<T>) => void;
-/**
- * @deprecated Use `NinetailedPlugin` from the sdks/javascript package instead.
- */
 export declare abstract class NinetailedPlugin implements AnalyticsPlugin {
     [x: string]: unknown;
     abstract readonly name: string;

package/src/lib/utils/asyncThrottle.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Similar to _.throttle but waits for the promise to resolve.
+ * There is no "wait time" because you can simply await `Promise.timeout` inside `fn` to wait some time before the next call.
+ */
+export declare function asyncThrottle<I, O = void>(fn: (args: I) => Promise<O>): (args: I) => Promise<O>;

package/lib/analytics/get-analytics-plugin.d.ts

@@ -1,17 +0,0 @@
-import { AnalyticsPlugin } from 'analytics';
-import { Profile, Locale, NinetailedApiClient, NinetailedRequestContext } from '@ninetailed/experience.js-shared';
-import { NinetailedInstance, FlushResult } from '../types';
-type AnalyticsPluginNinetailedConfig = {
-    apiClient: NinetailedApiClient;
-    profile?: Profile;
-    locale?: Locale;
-    requestTimeout?: number;
-    buildClientContext?: () => NinetailedRequestContext;
-    ninetailed: NinetailedInstance;
-};
-export declare const PLUGIN_NAME = "ninetailed";
-export interface NinetailedEventQueue extends AnalyticsPlugin {
-    flush: () => Promise<FlushResult>;
-}
-export declare const ninetailedPlugin: ({ apiClient, profile, locale, ninetailed, buildClientContext, }: AnalyticsPluginNinetailedConfig) => NinetailedEventQueue;
-export {};

package/lib/utils/asyncThrottle.d.ts

@@ -1,6 +0,0 @@
-/**
- * Similar to _.throttle but waits for the promise to resolve. There is no
- * wait time because you can simply await `Promise.timeout` inside `fn`
- * to wait some time before the next call.
- */
-export declare function asyncThrottle<I, O = void>(fn: (args: I) => Promise<O>): (args: I) => Promise<O>;