launchdarkly-js-sdk-common 4.3.2 → 5.0.0-alpha.1

package/typings.d.ts

@@ -103,9 +103,9 @@ declare module 'launchdarkly-js-sdk-common' {
      * Whether or not to use the REPORT verb to fetch flag settings.
      *
      * If this is true, flag settings will be fetched with a REPORT request
-     * including a JSON entity body with the user object.
+     * including a JSON entity body with the context object.
      *
-     * Otherwise (by default) a GET request will be issued with the user passed as
+     * Otherwise (by default) a GET request will be issued with the context passed as
      * a base64 URL-encoded path parameter.
      *
      * Do not use unless advised by LaunchDarkly.
@@ -150,7 +150,7 @@ declare module 'launchdarkly-js-sdk-common' {
     sendEvents?: boolean;
 
     /**
-     * Whether all user attributes (except the user key) should be marked as private, and
+     * Whether all context attributes (except the context key) should be marked as private, and
      * not sent to LaunchDarkly in analytics events.
      *
      * By default, this is false.
@@ -158,30 +158,11 @@ declare module 'launchdarkly-js-sdk-common' {
     allAttributesPrivate?: boolean;
 
     /**
-     * The names of user attributes that should be marked as private, and not sent
-     * to LaunchDarkly in analytics events. You can also specify this on a per-user basis
-     * with [[LDUser.privateAttributeNames]].
+     * The names of context attributes that should be marked as private, and not sent
+     * to LaunchDarkly in analytics events. You can also specify this on a per-context basis
+     * with [[LDContextMeta.privateAttributes]].
      */
-    privateAttributeNames?: Array<string>;
-
-    /**
-     * Whether to include full user details in every analytics event.
-     *
-     * The default is `false`: events will only include the user key, except for one "index" event
-     * that provides the full details for the user.
-     */
-    inlineUsersInEvents?: boolean;
-
-    /**
-     * This option is deprecated, and setting it has no effect.
-     *
-     * The behavior is now to allow frequent duplicate events.
-     *
-     * This is not a problem because most events will be summarized, and
-     * events which are not summarized are important to the operation of features such as
-     * experimentation.
-     */
-    allowFrequentDuplicateEvents?: boolean;
+    privateAttributes?: Array<string>;
 
     /**
      * Whether analytics events should be sent only when you call variation (true), or also when you
@@ -255,18 +236,10 @@ declare module 'launchdarkly-js-sdk-common' {
      */
     wrapperVersion?: string;
 
-    /**
-     * Whether to disable the automatic sending of an alias event when [[identify]] is
-     * called with a non-anonymous user when the previous user is anonymous.
-     *
-     * The default value is `false`.
-     */
-    autoAliasingOptOut?: boolean;
-
     /**
      * Information about the application where the LaunchDarkly SDK is running.
      */
-    application?: {
+     application?: {
       /**
        * A unique identifier representing the application where the LaunchDarkly SDK is running.
        * 
@@ -294,6 +267,113 @@ declare module 'launchdarkly-js-sdk-common' {
     inspectors?: LDInspection[];
   }
 
+  /**
+   * 
+   * TKTK
+   * 
+   * Meta attributes are used to control behavioral aspects of the Context.
+   * They cannot be addressed in targetting rules.
+   */
+   export interface LDContextMeta {
+    /**
+     * An optional secondary key for a context.
+     *
+     * TKTK
+     * 
+     * This affects [feature flag targeting](https://docs.launchdarkly.com/home/flags/targeting-users#targeting-rules-based-on-user-attributes) 
+     * as follows: if you have chosen to bucket context by a specific attribute, the secondary key (if set)
+     * is used to further distinguish between contexts which are otherwise identical according to that attribute.
+     */
+    secondary?: string;
+
+    /**
+     * 
+     * TKTK
+     * 
+     * Specifies a list of attribute names (either built-in or custom) which should be
+     * marked as private, and not sent to LaunchDarkly in analytics events. This is in
+     * addition to any private attributes designated in the global configuration
+     * with [[LDOptions.privateAttributes]] or [[LDOptions.allAttributesPrivate]].
+     */
+    privateAttributes?: string[];
+  }
+
+  /**
+   * TKTK
+   */
+  interface LDContextCommon {
+      /**
+       * If true, the context will _not_ appear on the Contexts page in the LaunchDarkly dashboard.
+       */
+      anonymous?: boolean;
+
+      /**
+       * A unique string identifying a context.
+       */
+      key: string;
+
+      /**
+       * The context's name.
+       *
+       * You can search for contexts on the Contexts page by name.
+       */
+      name?: string;
+
+      /**
+       * 
+       * TODO: U2C We will need some uniform description for this.
+       * 
+       * Meta attributes are used to control behavioral aspects of the Context.
+       * They cannot be addressed in targetting rules.
+       */
+      _meta?: LDContextMeta;
+
+      /**
+       * Any additional attributes associated with the context.
+       */
+      [attribute: string]: any;
+  }
+
+
+  /**
+   * 
+   * TTKTK
+   * 
+   * A single-kind context.
+   */
+  interface LDSingleKindContext extends LDContextCommon {
+      /**
+       * The kind of the context.
+       */
+      kind: string;
+  }
+
+  /**
+   * 
+   * TKTK
+   * 
+   * A multi-kind context.
+   */
+  interface LDMultiKindContext {
+      /**
+       * The kind of the context.
+       */
+      kind: "multi",
+
+      /**
+       * The contexts which compose this multi-kind context.
+       * 
+       * These should be of type LDContextCommon. "multi" is to allow
+       * for the top level "kind" attribute.
+       */
+      [kind: string]: "multi" | LDContextCommon;
+  }
+
+  /**
+   * A LaunchDarkly context object.
+   */
+  export type LDContext = LDUser | LDSingleKindContext | LDMultiKindContext;
+
   /**
    * A LaunchDarkly user object.
    */
@@ -388,9 +468,9 @@ declare module 'launchdarkly-js-sdk-common' {
      * The general category of the reason:
      *
      * - `'OFF'`: The flag was off and therefore returned its configured off value.
-     * - `'FALLTHROUGH'`: The flag was on but the user did not match any targets or rules.
-     * - `'TARGET_MATCH'`: The user key was specifically targeted for this flag.
-     * - `'RULE_MATCH'`: the user matched one of the flag's rules.
+     * - `'FALLTHROUGH'`: The flag was on but the context did not match any targets or rules.
+     * - `'TARGET_MATCH'`: The context key was specifically targeted for this flag.
+     * - `'RULE_MATCH'`: the context matched one of the flag's rules.
      * - `'PREREQUISITE_FAILED'`: The flag was considered off because it had at least one
      *   prerequisite flag that either was off or did not return the desired variation.
      * - `'ERROR'`: The flag could not be evaluated, e.g. because it does not exist or due
@@ -523,39 +603,39 @@ declare module 'launchdarkly-js-sdk-common' {
     waitForInitialization(): Promise<void>;
 
     /**
-     * Identifies a user to LaunchDarkly.
+     * Identifies a context to LaunchDarkly.
      *
-     * Unlike the server-side SDKs, the client-side JavaScript SDKs maintain a current user state,
-     * which is set at initialization time. You only need to call `identify()` if the user has changed
+     * Unlike the server-side SDKs, the client-side JavaScript SDKs maintain a current context state,
+     * which is set at initialization time. You only need to call `identify()` if the context has changed
      * since then.
      *
-     * Changing the current user also causes all feature flag values to be reloaded. Until that has
-     * finished, calls to [[variation]] will still return flag values for the previous user. You can
+     * Changing the current context also causes all feature flag values to be reloaded. Until that has
+     * finished, calls to [[variation]] will still return flag values for the previous context. You can
      * use a callback or a Promise to determine when the new flag values are available.
      *
-     * @param user
-     *   The user properties. Must contain at least the `key` property.
+     * @param context
+     *   The context properties. Must contain at least the `key` property.
      * @param hash
-     *   The signed user key if you are using [Secure Mode](https://docs.launchdarkly.com/sdk/features/secure-mode#configuring-secure-mode-in-the-javascript-client-side-sdk).
+     *   The signed context key if you are using [Secure Mode](https://docs.launchdarkly.com/sdk/features/secure-mode#configuring-secure-mode-in-the-javascript-client-side-sdk).
      * @param onDone
-     *   A function which will be called as soon as the flag values for the new user are available,
+     *   A function which will be called as soon as the flag values for the new context are available,
      *   with two parameters: an error value (if any), and an [[LDFlagSet]] containing the new values
      *   (which can also be obtained by calling [[variation]]). If the callback is omitted, you will
      *   receive a Promise instead.
      * @returns
      *   If you provided a callback, then nothing. Otherwise, a Promise which resolve once the flag
-     *   values for the new user are available, providing an [[LDFlagSet]] containing the new values
+     *   values for the new context are available, providing an [[LDFlagSet]] containing the new values
      *   (which can also be obtained by calling [[variation]]).
      */
-    identify(user: LDUser, hash?: string, onDone?: (err: Error | null, flags: LDFlagSet | null) => void): Promise<LDFlagSet>;
+    identify(context: LDContext, hash?: string, onDone?: (err: Error | null, flags: LDFlagSet | null) => void): Promise<LDFlagSet>;
 
     /**
-     * Returns the client's current user.
+     * Returns the client's current context.
      *
-     * This is the user that was most recently passed to [[identify]], or, if [[identify]] has never
-     * been called, the initial user specified when the client was created.
+     * This is the context that was most recently passed to [[identify]], or, if [[identify]] has never
+     * been called, the initial context specified when the client was created.
      */
-    getUser(): LDUser;
+    getContext(): LDContext;
 
     /**
      * Flushes all pending analytics events.
@@ -575,10 +655,10 @@ declare module 'launchdarkly-js-sdk-common' {
     flush(onDone?: () => void): Promise<void>;
 
     /**
-     * Determines the variation of a feature flag for the current user.
+     * Determines the variation of a feature flag for the current context.
      *
      * In the client-side JavaScript SDKs, this is always a fast synchronous operation because all of
-     * the feature flag values for the current user have already been loaded into memory.
+     * the feature flag values for the current context have already been loaded into memory.
      *
      * @param key
      *   The unique key of the feature flag.
@@ -590,7 +670,7 @@ declare module 'launchdarkly-js-sdk-common' {
     variation(key: string, defaultValue?: LDFlagValue): LDFlagValue;
 
     /**
-     * Determines the variation of a feature flag for a user, along with information about how it was
+     * Determines the variation of a feature flag for a context, along with information about how it was
      * calculated.
      *
      * Note that this will only work if you have set `evaluationExplanations` to true in [[LDOptions]].
@@ -639,7 +719,7 @@ declare module 'launchdarkly-js-sdk-common' {
      *   The callback parameter is an Error object. If you do not listen for "error"
      *   events, then the errors will be logged with `console.log()`.
      * - `"change"`: The client has received new feature flag data. This can happen either
-     *   because you have switched users with [[identify]], or because the client has a
+     *   because you have switched contexts with [[identify]], or because the client has a
      *   stream connection and has received a live change to a flag value (see below).
      *   The callback parameter is an [[LDFlagChangeset]].
      * - `"change:FLAG-KEY"`: The client has received a new value for a specific flag
@@ -694,23 +774,7 @@ declare module 'launchdarkly-js-sdk-common' {
     track(key: string, data?: any, metricValue?: number): void;
 
     /**
-     * Associates two users for analytics purposes.
-     *
-     * This can be helpful in the situation where a person is represented by multiple
-     * LaunchDarkly users. This may happen, for example, when a person initially logs into
-     * an application-- the person might be represented by an anonymous user prior to logging
-     * in and a different user after logging in, as denoted by a different user key.
-     *
-     * @param user
-     *   The newly identified user.
-     * @param previousUser
-     *   The previously identified user.
-     */
-    alias(user: LDUser, previousUser: LDUser): void;
-
-    /**
-     * Returns a map of all available flags to the current user's values. This will send analytics
-     * events unless [[LDOptions.sendEventsOnlyForVariation]] is true.
+     * Returns a map of all available flags to the current context's values.
      *
      * @returns
      *   An object in which each key is a feature flag key and each value is the flag value.
@@ -848,7 +912,7 @@ declare module 'launchdarkly-js-sdk-common' {
      * wrapper SDKs which have different methods of tracking when a flag was accessed. It is not called when a call is made
      * to allFlags.
      */
-    method: (flagKey: string, flagDetail: LDEvaluationDetail, user: LDUser) => void;
+    method: (flagKey: string, flagDetail: LDEvaluationDetail, context: LDContext) => void;
   }
   
   /**
@@ -922,7 +986,7 @@ declare module 'launchdarkly-js-sdk-common' {
     /**
      * This method will be called when an identify operation completes.
      */
-    method: (user: LDUser) => void;
+    method: (context: LDContext) => void;
   }
 
   type LDInspection = LDInspectionFlagUsedHandler | LDInspectionFlagDetailsChangedHandler

package/src/UserFilter.js

@@ -1,75 +0,0 @@
-const utils = require('./utils');
-
-/**
- * The UserFilter object transforms user objects into objects suitable to be sent as JSON to
- * the server, hiding any private user attributes.
- *
- * @param {Object} the LaunchDarkly client configuration object
- **/
-function UserFilter(config) {
-  const filter = {};
-  const allAttributesPrivate = config.allAttributesPrivate;
-  const privateAttributeNames = config.privateAttributeNames || [];
-  const ignoreAttrs = { key: true, custom: true, anonymous: true };
-  const allowedTopLevelAttrs = {
-    key: true,
-    secondary: true,
-    ip: true,
-    country: true,
-    email: true,
-    firstName: true,
-    lastName: true,
-    avatar: true,
-    name: true,
-    anonymous: true,
-    custom: true,
-  };
-
-  filter.filterUser = function(user) {
-    if (!user) {
-      return null;
-    }
-    const userPrivateAttrs = user.privateAttributeNames || [];
-
-    const isPrivateAttr = function(name) {
-      return (
-        !ignoreAttrs[name] &&
-        (allAttributesPrivate || userPrivateAttrs.indexOf(name) !== -1 || privateAttributeNames.indexOf(name) !== -1)
-      );
-    };
-    const filterAttrs = function(props, isAttributeAllowed) {
-      return Object.keys(props).reduce(
-        (acc, name) => {
-          const ret = acc;
-          if (isAttributeAllowed(name)) {
-            if (isPrivateAttr(name)) {
-              // add to hidden list
-              ret[1][name] = true;
-            } else {
-              ret[0][name] = props[name];
-            }
-          }
-          return ret;
-        },
-        [{}, {}]
-      );
-    };
-    const result = filterAttrs(user, key => allowedTopLevelAttrs[key]);
-    const filteredProps = result[0];
-    let removedAttrs = result[1];
-    if (user.custom) {
-      const customResult = filterAttrs(user.custom, () => true);
-      filteredProps.custom = customResult[0];
-      removedAttrs = utils.extend({}, removedAttrs, customResult[1]);
-    }
-    const removedAttrNames = Object.keys(removedAttrs);
-    if (removedAttrNames.length) {
-      removedAttrNames.sort();
-      filteredProps.privateAttrs = removedAttrNames;
-    }
-    return filteredProps;
-  };
-  return filter;
-}
-
-module.exports = UserFilter;

package/src/UserValidator.js

@@ -1,56 +0,0 @@
-const { v1: uuidv1 } = require('uuid');
-
-const errors = require('./errors');
-const messages = require('./messages');
-const utils = require('./utils');
-
-// Transforms the user object if necessary to make sure it has a valid key.
-// 1. If a key is present, but is not a string, change it to a string.
-// 2. If no key is present, and "anonymous" is true, use a UUID as a key. This is cached in local
-// storage if possible.
-// 3. If there is no key (or no user object), return an error.
-
-const ldUserIdKey = 'ld:$anonUserId';
-
-function UserValidator(persistentStorage) {
-  function getCachedUserId() {
-    return persistentStorage.get(ldUserIdKey);
-  }
-
-  function setCachedUserId(id) {
-    return persistentStorage.set(ldUserIdKey, id);
-  }
-
-  const ret = {};
-
-  // Validates the user, returning a Promise that resolves to the validated user, or rejects if there is an error.
-  ret.validateUser = user => {
-    if (!user) {
-      return Promise.reject(new errors.LDInvalidUserError(messages.userNotSpecified()));
-    }
-
-    const userOut = utils.clone(user);
-    if (userOut.key !== null && userOut.key !== undefined) {
-      userOut.key = userOut.key.toString();
-      return Promise.resolve(userOut);
-    }
-    if (userOut.anonymous) {
-      return getCachedUserId().then(cachedId => {
-        if (cachedId) {
-          userOut.key = cachedId;
-          return userOut;
-        } else {
-          const id = uuidv1();
-          userOut.key = id;
-          return setCachedUserId(id).then(() => userOut);
-        }
-      });
-    } else {
-      return Promise.reject(new errors.LDInvalidUserError(messages.invalidUser()));
-    }
-  };
-
-  return ret;
-}
-
-module.exports = UserValidator;

package/src/__tests__/UserFilter-test.js

@@ -1,93 +0,0 @@
-import UserFilter from '../UserFilter';
-
-describe('UserFilter', () => {
-  // users to serialize
-  const user = {
-    key: 'abc',
-    firstName: 'Sue',
-    custom: { bizzle: 'def', dizzle: 'ghi' },
-  };
-
-  const userSpecifyingOwnPrivateAttr = {
-    key: 'abc',
-    firstName: 'Sue',
-    custom: { bizzle: 'def', dizzle: 'ghi' },
-    privateAttributeNames: ['dizzle', 'unused'],
-  };
-
-  const userWithUnknownTopLevelAttrs = {
-    key: 'abc',
-    firstName: 'Sue',
-    species: 'human',
-    hatSize: 6,
-    custom: { bizzle: 'def', dizzle: 'ghi' },
-  };
-
-  const anonUser = {
-    key: 'abc',
-    anonymous: true,
-    custom: { bizzle: 'def', dizzle: 'ghi' },
-  };
-
-  // expected results from serializing user
-  const userWithAllAttrsHidden = {
-    key: 'abc',
-    custom: {},
-    privateAttrs: ['bizzle', 'dizzle', 'firstName'],
-  };
-
-  const userWithSomeAttrsHidden = {
-    key: 'abc',
-    custom: { dizzle: 'ghi' },
-    privateAttrs: ['bizzle', 'firstName'],
-  };
-
-  const userWithOwnSpecifiedAttrHidden = {
-    key: 'abc',
-    firstName: 'Sue',
-    custom: { bizzle: 'def' },
-    privateAttrs: ['dizzle'],
-  };
-
-  const anonUserWithAllAttrsHidden = {
-    key: 'abc',
-    anonymous: true,
-    custom: {},
-    privateAttrs: ['bizzle', 'dizzle'],
-  };
-
-  it('includes all user attributes by default', () => {
-    const uf = UserFilter({});
-    expect(uf.filterUser(user)).toEqual(user);
-  });
-
-  it('hides all except key if allAttributesPrivate is true', () => {
-    const uf = UserFilter({ allAttributesPrivate: true });
-    expect(uf.filterUser(user)).toEqual(userWithAllAttrsHidden);
-  });
-
-  it('hides some attributes if privateAttributeNames is set', () => {
-    const uf = UserFilter({ privateAttributeNames: ['firstName', 'bizzle'] });
-    expect(uf.filterUser(user)).toEqual(userWithSomeAttrsHidden);
-  });
-
-  it('hides attributes specified in per-user privateAttrs', () => {
-    const uf = UserFilter({});
-    expect(uf.filterUser(userSpecifyingOwnPrivateAttr)).toEqual(userWithOwnSpecifiedAttrHidden);
-  });
-
-  it('looks at both per-user privateAttrs and global config', () => {
-    const uf = UserFilter({ privateAttributeNames: ['firstName', 'bizzle'] });
-    expect(uf.filterUser(userSpecifyingOwnPrivateAttr)).toEqual(userWithAllAttrsHidden);
-  });
-
-  it('strips unknown top-level attributes', () => {
-    const uf = UserFilter({});
-    expect(uf.filterUser(userWithUnknownTopLevelAttrs)).toEqual(user);
-  });
-
-  it('leaves the "anonymous" attribute as is', () => {
-    const uf = UserFilter({ allAttributesPrivate: true });
-    expect(uf.filterUser(anonUser)).toEqual(anonUserWithAllAttrsHidden);
-  });
-});

package/src/__tests__/UserValidator-test.js

@@ -1,57 +0,0 @@
-import UserValidator from '../UserValidator';
-
-describe('UserValidator', () => {
-  let localStorage;
-  let logger;
-  let uv;
-
-  beforeEach(() => {
-    localStorage = {};
-    logger = {
-      warn: jest.fn(),
-    };
-    uv = UserValidator(localStorage, logger);
-  });
-
-  it('rejects null user', async () => {
-    await expect(uv.validateUser(null)).rejects.toThrow();
-  });
-
-  it('leaves user with string key unchanged', async () => {
-    const u = { key: 'someone', name: 'me' };
-    expect(await uv.validateUser(u)).toEqual(u);
-  });
-
-  it('stringifies non-string key', async () => {
-    const u0 = { key: 123, name: 'me' };
-    const u1 = { key: '123', name: 'me' };
-    expect(await uv.validateUser(u0)).toEqual(u1);
-  });
-
-  it('uses cached key for anonymous user', async () => {
-    const cachedKey = 'thing';
-    let storageKey;
-    localStorage.get = async key => {
-      storageKey = key;
-      return cachedKey;
-    };
-    const u = { anonymous: true };
-    expect(await uv.validateUser(u)).toEqual({ key: cachedKey, anonymous: true });
-    expect(storageKey).toEqual('ld:$anonUserId');
-  });
-
-  it('generates and stores key for anonymous user', async () => {
-    let storageKey;
-    let storedValue;
-    localStorage.get = async () => null;
-    localStorage.set = async (key, value) => {
-      storageKey = key;
-      storedValue = value;
-    };
-    const u0 = { anonymous: true };
-    const u1 = await uv.validateUser(u0);
-    expect(storedValue).toEqual(expect.anything());
-    expect(u1).toEqual({ key: storedValue, anonymous: true });
-    expect(storageKey).toEqual('ld:$anonUserId');
-  });
-});