Use newer TestTrack APIs (#98)

This PR migrates from TestTrack's v1 APIs to the v4 APIs, which require
app versioning information. This allows TestTrack to serve split
configurations specific to each build of your application.

## `load`

Fetches visitor config from the server to create a `TestTrack` instance.

```ts
import { load, createCookieStorage } from '@betterment-oss/test-track';

const testTrack = await load({
  client: {
    url: 'https://testtrack.example.com',
    appName: 'my-app',
    appVersion: '0.0.0',
    buildTimestamp: import.meta.env.TT_BUILD_TIMESTAMP
  },
  storage: createCookieStorage({ name: 'tt_visitor_id', domain: '.example.com' })
});
```

## `create`

Creates a `TestTrack` instance with preloaded data (e.g.,
server-rendered).

```ts
import { create, createCookieStorage } from '@betterment-oss/test-track';

const testTrack = create({
  client: {
    url: 'https://testtrack.example.com',
    appName: 'my-app',
    appVersion: '0.0.0',
    buildTimestamp: import.meta.env.TT_BUILD_TIMESTAMP
  },
  storage: createCookieStorage({ name: 'tt_visitor_id', domain: '.example.com' }),
  visitorConfig: { visitor: { id: '...', assignments: [...] }, splits: [...] }
});
```

## `initialize` (Deprecated)

Uses `window.TT` for configuration. Use `load` or `create` instead.

```ts
import { initialize } from '@betterment-oss/test-track';

const testTrack = initialize({
  client: {
    appName: 'my-app',
    appVersion: '0.0.0',
    buildTimestamp: import.meta.env.TT_BUILD_TIMESTAMP
  }
});
```

**Breaking changes:**
- Now requires a `client` option with `appName`, `appVersion`, and
`buildTimestamp`
- Now synchronous (returns `TestTrack` instead of `Promise<TestTrack>`)

## API Endpoints

- `GET
/api/v4/apps/:app/versions/:version/builds/:build/visitors/:id/config`
replaces `GET /api/v1/visitors/:id`
- `POST /api/v4/apps/:app/versions/:version/builds/:build/identifier`
replaces `POST /api/v1/identifier`
- `POST /api/v2/visitors/:id/assignment_overrides` replaces `POST
/api/v1/assignment_override`
- Request bodies are now JSON instead of form-encoded. This means POST
requests to the Test Track API will run a preflight request. See:
Betterment/testtrack-cli#69.

## Type Changes

- `logIn` and `signUp` now accept `value` as a `string` instead of
`number`

## Vite Plugin


Provides `import.meta.env.TT_BUILD_TIMESTAMP`.

```ts
import { testTrackPlugin } from '@betterment-oss/test-track/vite';

export default defineConfig({
  plugins: [testTrackPlugin()]
});
```

Author: rzane

README.md

@@ -18,18 +18,94 @@ pnpm add @betterment-oss/test-track
 
 You can find the latest version of the test track JS client [here](https://github.com/Betterment/test_track_js_client/releases).
 
+## Setup
+
+There are two ways to set up TestTrack:
+
+### `load(options)`
+
+Fetches visitor configuration from the TestTrack server and creates a TestTrack instance. This is the recommended approach for most use cases.
+
 ```javascript
-import { initialize } from '@betterment-oss/test-track';
+import { load, createCookieStorage } from '@betterment-oss/test-track';
+
+const testTrack = await load({
+  client: {
+    url: 'https://testtrack.example.com',
+    appName: 'my_app',
+    appVersion: '1.0.0',
+    buildTimestamp: '2024-01-01T00:00:00Z'
+  },
+  storage: createCookieStorage({
+    domain: '.example.com'
+  })
+});
+```
+
+**Parameters:**
+
+- `client.url` - The URL of your TestTrack server
+- `client.appName` - Your application name
+- `client.appVersion` - Your application version
+- `client.buildTimestamp` - The build timestamp (ISO 8601 format)
+- `storage` - A storage provider for persisting visitor IDs (e.g. `createCookieStorage()`)
+- `analytics` (optional) - An analytics provider for tracking assignments (see [Advanced Configuration](#advanced-configuration))
+- `errorLogger` (optional) - A function for logging errors
 
-const testTrack = await initialize();
+### `create(options)`
+
+Creates a TestTrack instance with preloaded visitor configuration. Use this when you have visitor configuration data available (e.g., from server-side rendering or a cached response).
+
+```javascript
+import { create, createCookieStorage } from '@betterment-oss/test-track';
+
+const testTrack = create({
+  client: {
+    url: 'https://testtrack.example.com',
+    appName: 'my_app',
+    appVersion: '1.0.0',
+    buildTimestamp: '2024-01-01T00:00:00Z'
+  },
+  storage: createCookieStorage({
+    domain: '.example.com'
+  }),
+  visitorConfig: {
+    splits: [
+      {
+        name: 'button_color',
+        variants: [
+          { name: 'blue', weight: 50 },
+          { name: 'red', weight: 50 }
+        ],
+        feature_gate: false
+      }
+    ],
+    visitor: {
+      id: 'visitor-uuid',
+      assignments: [{ split_name: 'button_color', variant: 'blue' }]
+    },
+    experience_sampling_weight: 1
+  }
+});
 ```
 
-## Configuration
+**Parameters:**
 
-Before using the client you must call `initialize()`. This method also takes some optional [configuration parameters](#advanced-configuration), if you fancy.
+- Same as `load()`, plus:
+- `visitorConfig` - Preloaded visitor configuration data from the TestTrack API
+
+## Configuration
 
 ### API
 
+#### `.visitorId`
+
+Returns the current visitor's unique identifier as a string. This ID is persisted in the storage provider and used to maintain consistent split assignments across sessions.
+
+```js
+console.log(testTrack.visitorId); // "abc123-def456-..."
+```
+
 #### `.vary(split_name, options)`
 
 The `vary` method is used to perform a split. It takes 2 arguments and returns the assigned variant as a string.
@@ -90,57 +166,80 @@ The `ab` method is used exclusively for two-way splits and feature toggles. It t
 The `logIn` method is used to ensure a consistent experience across devices. For instance, when a user logs in to your app on a new device, you should also log the user into Test Track in order to grab their existing split assignments instead of treating them like a new visitor. It takes 2 arguments.
 
 - `identifier` -- The first argument is the name of the identifier. This will be a snake_case string, e.g. `"myapp_user_id"`.
-- `value` -- The second argument is a primitive value, e.g. `12345`, `"abcd"`
+- `value` -- The second argument is a string value, e.g. `"12345"`, `"abcd"`
 
 ```js
-await testTrack.logIn('myapp_user_id', 12345);
+await testTrack.logIn('myapp_user_id', '12345');
 // From this point on you have existing split assignments from a previous device.
 ```
 
 ## Advanced Configuration
 
-When you call `initialize()` you can optionally pass in an analytics object and an error logger. For example:
+When you call `load()` or `create()` you can optionally pass in an analytics object and an error logger. For example:
 
 ```js
-const testTrack = await initialize({
+const testTrack = await load({
+  client: {
+    url: 'https://testtrack.example.com',
+    appName: 'my_app',
+    appVersion: '1.0.0',
+    buildTimestamp: '2024-01-01T00:00:00Z'
+  },
+  storage: createCookieStorage({ domain: '.example.com' }),
   analytics: {
-    trackAssignment: function (visitorId, assignment, callback) {
-      var props = {
+    trackAssignment: (visitorId, assignment) => {
+      const props = {
         SplitName: assignment.splitName,
         SplitVariant: assignment.variant,
         SplitContext: assignment.context
       };
 
-      remoteAnalyticsService.track('SplitAssigned', props, callback);
+      remoteAnalyticsService.track('SplitAssigned', props);
     },
-    identify: function (visitorId) {
+    identify: visitorId => {
       remoteAnalyticsService.identify(visitorId);
     },
-    alias: function (visitorId) {
+    alias: visitorId => {
       remoteAnalyticsService.alias(visitorId);
     }
   },
-  errorLogger: function (message) {
+  errorLogger: message => {
     RemoteLoggingService.log(message); // logs remotely so that you can be alerted to any misconfigured splits
   }
 });
 ```
 
+## Vite Plugin
+
+The `@betterment-oss/test-track` package includes a Vite plugin that automatically defines `import.meta.env.TT_BUILD_TIMESTAMP`, which can be used to configure Test Track.
+
+```ts
+import { defineConfig } from 'vite';
+import { testTrackPlugin } from '@betterment-oss/test-track/vite';
+
+export default defineConfig({
+  plugins: [testTrackPlugin()]
+});
+```
+
 ## Using TestTrack without a build tool
 
-The `@betterment-oss/test-track` package is distributed as an ES module. The package also provides `dist/index.iffe.js`. This artifact includes all dependencies and can be used directly in the browser.
+The `@betterment-oss/test-track` package is distributed as an ES module. The package also provides `dist/index.iife.js`. This artifact includes all dependencies and can be used directly in the browser.
 
 ```html
-<script>
-  window.TT = btoa(
-    JSON.stringify({
-      /* Config */
-    })
-  );
-</script>
 <script src="/path/to/index.iife.js"></script>
 <script type="module">
-  const testTrack = await TestTrack.initialize();
+  const testTrack = await TestTrack.load({
+    client: {
+      url: 'https://testtrack.example.com',
+      appName: 'my_app',
+      appVersion: '1.0.0',
+      buildTimestamp: '2024-01-01T00:00:00Z'
+    },
+    storage: TestTrack.createCookieStorage({
+      domain: '.example.com'
+    })
+  });
   // Use testTrack.vary(), testTrack.ab(), etc.
 </script>
 ```

demo.html

@@ -63,7 +63,14 @@
       }
 
       // Initialize
-      const testTrack = await TestTrack.initialize();
+      const testTrack = await TestTrack.initialize({
+        client: {
+          appName: 'TestTrack',
+          appVersion: '0.0.0',
+          buildTimestamp: '1970-01-01T00:00:00Z'
+        }
+      });
+
       const visitorId = testTrack.visitorId;
       visitorIdEl.textContent = visitorId;
       await runSplits();

package.json

@@ -8,6 +8,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
     }
   },
   "scripts": {
@@ -39,6 +43,14 @@
     "js-md5": "^0.8.3",
     "uuid": "^13.0.0"
   },
+  "peerDependencies": {
+    "vite": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "files": [
     "dist/*"
   ],

pnpm-lock.yaml

@@ -0,0 +1,106 @@
+import { create, initialize, load } from './api';
+import type { StorageProvider } from './storageProvider';
+import type { ClientConfig, V4VisitorConfig } from './client';
+import { v4 as uuid } from 'uuid';
+import { server } from './setupTests';
+import { http, HttpResponse } from 'msw';
+
+vi.mock('uuid');
+
+const buildURL = 'http://testtrack.dev/api/v4/apps/test_app/versions/1.0.0/builds/2019-04-16T14:35:30Z';
+const clientConfig: ClientConfig = {
+  url: 'http://testtrack.dev',
+  appName: 'test_app',
+  appVersion: '1.0.0',
+  buildTimestamp: '2019-04-16T14:35:30Z'
+};
+
+const storage: StorageProvider = {
+  getVisitorId: vi.fn(),
+  setVisitorId: vi.fn()
+};
+
+const buildVisitorConfig = (visitorId: string): V4VisitorConfig => ({
+  splits: [
+    {
+      name: 'jabba',
+      variants: [
+        { name: 'cgi', weight: 50 },
+        { name: 'puppet', weight: 50 }
+      ],
+      feature_gate: true
+    }
+  ],
+  visitor: {
+    id: visitorId,
+    assignments: [{ split_name: 'jabba', variant: 'puppet' }]
+  },
+  experience_sampling_weight: 1
+});
+
+describe('load', () => {
+  beforeEach(() => {
+    server.use(
+      http.get(`${buildURL}/visitors/:visitorId/config`, ({ params }) => {
+        return HttpResponse.json(buildVisitorConfig(params.visitorId as string));
+      })
+    );
+  });
+
+  it('reads the visitor id from storage and sets it back', async () => {
+    vi.mocked(storage.getVisitorId).mockReturnValue('existing_visitor_id');
+
+    const testTrack = await load({ client: clientConfig, storage });
+    expect(testTrack.visitorId).toEqual('existing_visitor_id');
+    expect(testTrack.assignments).toEqual([{ splitName: 'jabba', variant: 'puppet', context: null }]);
+
+    expect(storage.getVisitorId).toHaveBeenCalledTimes(1);
+    expect(storage.setVisitorId).toHaveBeenCalledWith('existing_visitor_id');
+  });
+
+  it('generates and saves a visitor id when none exists', async () => {
+    // @ts-expect-error uuid mock return type
+    vi.mocked(uuid).mockReturnValue('generated_visitor_id');
+    vi.mocked(storage.getVisitorId).mockReturnValue(undefined);
+
+    const testTrack = await load({ client: clientConfig, storage });
+    expect(testTrack.visitorId).toEqual('generated_visitor_id');
+    expect(testTrack.assignments).toEqual([{ splitName: 'jabba', variant: 'puppet', context: null }]);
+
+    expect(storage.getVisitorId).toHaveBeenCalledTimes(1);
+    expect(storage.setVisitorId).toHaveBeenCalledWith('generated_visitor_id');
+  });
+});
+
+describe('create', () => {
+  it('allows visitorConfig to be provided', () => {
+    const visitorConfig = buildVisitorConfig('existing_visitor_id');
+    const testTrack = create({ client: clientConfig, storage, visitorConfig });
+
+    expect(testTrack.visitorId).toEqual('existing_visitor_id');
+    expect(testTrack.assignments).toEqual([{ splitName: 'jabba', variant: 'puppet', context: null }]);
+  });
+});
+
+describe('initialize', () => {
+  it('creates TestTrack from window.TT config', () => {
+    const config = {
+      url: 'http://testtrack.dev',
+      cookieDomain: '.example.com',
+      experienceSamplingWeight: 1,
+      assignments: { jabba: 'puppet' }
+    };
+
+    // @ts-expect-error uuid mock return type
+    vi.mocked(uuid).mockReturnValue('generated_visitor_id');
+
+    window.TT = btoa(JSON.stringify(config));
+
+    const testTrack = initialize({
+      client: { appName: 'test_app', appVersion: '1.0.0', buildTimestamp: '2019-04-16T14:35:30Z' }
+    });
+
+    expect(testTrack.visitorId).toEqual('generated_visitor_id');
+    expect(testTrack.assignments).toEqual([{ splitName: 'jabba', variant: 'puppet', context: null }]);
+  });
+});