@ht-sdks/events-sdk-js-browser 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ht-sdks/events-sdk-js-browser",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/ht-sdks/events-sdk-js-mono",
@@ -86,7 +86,7 @@
     "jest-dev-server": "^6.0.3",
     "jest-environment-jsdom": "^28.1.1",
     "jquery": "^3.5.1",
-    "jsdom": "^19.0.0",
+    "jsdom": "^20.0.0",
     "lighthouse": "^9.6.3",
     "log-update": "^4.0.0",
     "micro-memoize": "^4.0.9",

package/src/browser/index.ts

@@ -4,6 +4,7 @@ import { getCDN, setGlobalCDNUrl } from '../lib/parse-cdn'
 import { fetch } from '../lib/fetch'
 import { Analytics, AnalyticsSettings, InitOptions } from '../core/analytics'
 import { Context } from '../core/context'
+import { HTTPCookieService } from '../core/http-cookies'
 import { Plan } from '../core/events'
 import { Plugin } from '../core/plugin'
 import { MetricsOptions } from '../core/stats/remote-metrics'
@@ -359,6 +360,12 @@ async function loadAnalytics(
   const retryQueue: boolean =
     legacySettings.integrations['Hightouch.io']?.retryQueue ?? true
 
+  if (!options.disableClientPersistence && options.httpCookieServiceOptions) {
+    options.httpCookieService = await HTTPCookieService.load(
+      options.httpCookieServiceOptions
+    )
+  }
+
   const opts: InitOptions = { retryQueue, ...options }
   const analytics = new Analytics(settings, opts)
 

package/src/core/analytics/index.ts

@@ -55,6 +55,10 @@ import {
 import { PluginFactory } from '../../plugins/remote-loader'
 import { setGlobalAnalytics } from '../../lib/global-analytics-helper'
 import { popPageContext } from '../buffer'
+import type {
+  HTTPCookieService,
+  HTTPCookieServiceOptions,
+} from '../http-cookies'
 
 const deprecationWarning =
   'This is being deprecated and will be not be available in future releases of Analytics JS'
@@ -129,6 +133,15 @@ export interface InitOptions {
    */
   globalAnalyticsKey?: string
 
+  /**
+   * When setting httpCookieServiceOptions, an HTTPCookieService is automatically created
+   */
+  httpCookieServiceOptions?: HTTPCookieServiceOptions
+  /**
+   * When not setting httpCookieServiceOptions, you may pass your own instance of HTTPCookieService
+   */
+  httpCookieService?: HTTPCookieService
+
   /**
    * Shortcuts for overriding the default Hightouch.io integration settings
    */
@@ -191,6 +204,7 @@ export class Analytics
         {
           persist: !disablePersistance,
           storage: options?.storage,
+          httpCookieService: options?.httpCookieService,
           // Any User specific options override everything else
           ...options?.user,
         },

package/src/core/http-cookies/README.md

@@ -0,0 +1,194 @@
+# HTTPOnly Cookies
+
+## "Browser Cookies" vs "Server Cookies"
+
+**Cookies are serialized sets of key-value pairs that the browser can send to the server when making an HTTP request (e.g. on the `Cookie` header)**. Traditionally, the browser does this to identify itself when calling the server. For example, it might receive a cookie when calling a `/login` route, and then continue to send this cookie on subsequent requests, proving that the user is still logged-in. Alternatively, browsers can use cookies just for storing local data, like localStorage.
+
+Normally, **both** the client and the server can CRUD cookies.
+
+However, as a security measure, browsers restrict Javascript access to cookies containing the `HTTPOnly` property. These cookies are **only** intended to be created and read by the server.
+
+## "Browser Cookies" for event attribution
+
+Certain browsers (e.g. Safari) limit "Browser Cookies" to a 7 day expiry.
+
+A user visiting a website on both 01/01/2023 and 01/14/2023 will look like two different users. The browser will delete the user's "anonymousId cookie" before the user begins their second session on 01/14/2023.
+
+## "Server Cookies" for event attribution
+
+These expiry limits don't have to apply to "Server Cookies".
+
+A user visiting a website on both 01/01/2023 and 01/14/2023 can still look like the same user, provided that there is a way to "regenerate" the user's same "anonymousId cookie" from the earlier session. To do this, the following must happen:
+1. User begins their session on 01/01/2023
+1. Events SDK creates an anonymousId "browser cookie"
+1. Events SDK sends "browser cookie" to `$server` and receives back an HTTPOnly cookie with the same anonymousId
+1. HTTPOnly cookie remains on the user's device
+1. User begins their second session on 01/14/2023
+1. Events SDK sends the HTTPOnly cookie to `$server` and receives back a "browser cookie" with the same anonymousId as the first session
+
+**The `$server` must be the same server that serves your website.** Certain browsers (e.g. Safari) will still enforce a 7 day expiry--even for "server cookies"--unless the following criteria are met:
+1. The `$server` providing the HTTPOnly cookie must be on the same domain as the website.
+1. If `$server` is on a subdomain of the website, its IP address must match the IP address that served the main HTML document.
+
+Routing a subdomain via DNS will not suffice. You'll need **one of** the following:
+- A **webserver** that serves  both your HTML document and an API (e.g. something like Django, Rails, Spring, etc)
+- A **reverse proxy** that can forward requests for your HTML document to one place, your API requests to another, and make it look like it's all on one server (e.g. NGINX, Caddy, etc)
+- A **CDN** that can run programmatic logic when matching certain requests (e.g. Lambda@Edge, Clouflare Workers, etc)
+
+## Client SDK Setup
+
+```javascript
+import { HtEventsBrowser } from '@ht-sdks/events-sdk-js-browser'
+
+const htevents = HtEventsBrowser.load(
+  { writeKey: '<YOUR_WRITE_KEY>'},
+  { 
+    apiHost: "us-east-1.hightouch-events.com", // HtEvents API remains the same
+    httpCookieServiceOptions: {
+      clearUrl: 'ht/clear', // route hosted on *your* domain and infra
+      renewUrl: 'ht/renew', // route hosted on *your* domain and infra
+    }
+  },
+)
+
+htevents.identify('hello world')
+
+document.body?.addEventListener('click', () => {
+  htevents.track('document body clicked!')
+})
+```
+
+## Server Setup
+
+The Events SDK expects to interact with a customer's `$server` that implements a specific spec for two routes. You can name the endpoints whatever you want.
+
+### An API for **creating** server and browser cookies
+
+This route should look for the following **browser** cookies (from Events SDK):
+* `request.headers.get('Cookie')["htjs_anonymous_id"]`
+* `request.headers.get('Cookie')["htjs_user_id"]`
+
+This route should return these values as **server** cookies:
+* `response.cookie("htjs_anonymous_id_srvr", anonVal, {httpOnly:true, ...})`
+* `response.cookie("htjs_user_id_srvr", userIdVal, {httpOnly:true, ...})`
+
+If there are no browser cookies found, return any server cookies as browser cookies:
+* `response.cookie("htjs_anonymous_id", anonVal, ...)`
+* `response.cookie("htjs_user_id", userIdVal, ...)`
+
+### An API for **clearing** server cookies
+
+This route should look for **server** cookies and clean them:
+* `res.cookie("htjs_anonymous_id_srvr", "", {maxAge: 0, httpOnly:true});`
+* `res.cookie("htjs_user_id_srvr", "", {maxAge: 0, httpOnly:true});`
+
+### API Spec
+The spec of the actual `request` and `response` payloads are kept intentionally vague. The spec should fit a variety of server environments.
+
+The Events SDK only requires that the server: A) handles cookies and B) returns a `200` statuscode.
+
+## Server Example
+
+A simplified Node.js/Express server:
+
+```Javascript
+const express = require("express");
+const cookieParser = require('cookie-parser');
+const cors = require('cors');
+
+const USER_COOKIE = "htjs_user_id";
+const ANON_COOKIE = "htjs_anonymous_id";
+
+function getDomain(req) {
+  let domain = process.env.DOMAIN || req.headers["x-forwarded-for"] || req.get("host");
+  if (domain.startsWith("localhost")) return "localhost";
+  return domain;
+}
+
+function renewCookies(req, res, browserName, serverName) {
+  const cookie = req.cookies[browserName] || req.cookies[serverName];
+  if (!cookie) return "";
+  const cookieParams = {maxAge:31536000*1000, domain: getDomain(req), sameSite: "lax"};
+  res.cookie(browserName, cookie, {...cookieParams});
+  res.cookie(serverName, cookie, {...cookieParams, httpOnly:true});
+  return cookie;
+}
+
+function clearServerCookie(req, res, serverName) {
+  const cookie = "";
+  const cookieParams = {maxAge:0, domain: getDomain(req), sameSite: "lax"};
+  res.cookie(serverName, "", {...cookieParams, httpOnly:true});
+  return cookie;
+}
+
+const app = express();
+app.use(cookieParser());
+app.use(cors())
+
+app.post("/ht/renew", (req, res) => {
+  // recreate a browser cookie from an existing server cookie, OR
+  // create a new server cookie that can later be used to recreate from.
+  return res.json({
+    userId: renewCookies(req, res, USER_COOKIE, `${USER_COOKIE}_srvr`),
+    anonymousId: renewCookies(req, res, ANON_COOKIE, `${ANON_COOKIE}_srvr`),
+  })
+});
+
+app.post("/ht/clear", (req, res) => {
+  // clear server cookies, e.g. if the user asks to clear all cookies.
+  return res.json({
+    userId: clearServerCookie(req, res, `${USER_COOKIE}_srvr`),
+    anonymousId: clearServerCookie(req, res, `${ANON_COOKIE}_srvr`),
+  })
+});
+
+app.listen(3000, () => {
+  console.log("Listening on port 3000...");
+});
+```
+
+A **very** simplified NGINX reverse proxy serving your document and API from the same domain:
+```
+worker_processes  1;
+
+events {
+    worker_connections  1024;
+}
+
+http {
+    default_type  application/octet-stream;
+    sendfile        on;
+    keepalive_timeout  65;
+
+    server {
+        listen       8080;
+        server_name  localhost;
+
+        location / {
+            root   /Users/name/src/website/html;
+            index  index.html index.htm;
+        }
+
+        location /cdn {
+            #autoindex on;
+            alias  /Users/name/src/website/cdn;
+            try_files $uri /index.html =404;
+        }
+
+        location /ht {
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header Host $host;
+            proxy_pass http://127.0.0.1:3000;
+        }
+
+    }
+
+    include servers/*;
+}
+```
+
+**These server examples should not be used as is.** They should be adapted to your setup and "productionized". The general concepts remain the same though.
+
+## More information
+- Safari: https://webkit.org/blog/9521/intelligent-tracking-prevention-2-3/
+

package/src/core/http-cookies/index.ts

@@ -0,0 +1,152 @@
+import { fetch } from '../../lib/fetch'
+
+type DeferredRequest = () => Promise<Response>
+
+export type HTTPCookieServiceOptions = {
+  renewUrl: string
+  clearUrl: string
+  retries?: number
+  backoff?: number
+  flushInterval?: number
+}
+
+/**
+ * `HTTPCookieService.load(...)` should be awaited inside `loadAnalytics(...)`.
+ * If the server can recreate an expired "Browser Cookie", by inspecting existing
+ * "Server Cookies", we should delay dispatching events until receiving the Cookie.
+ *
+ *  dispatch$Method class methods should be used after any cookie interactions:
+ * `dispatchCreate()` should be called after creating any new browser cookies.
+ * `dispatchClear()` should be called after clearing any browser cookies.
+ *
+ * Manual `startQueueConsumer()` or `stopQueueConsumer()` is not usually necessary.
+ *
+ * Glossary:
+ * "Server Cookies": `HTTPOnly:true`, stored on client, but only server can access.
+ * "Browser Cookies": `HTTPOnly:false`, stored on client, and both client and server can access.
+ */
+export class HTTPCookieService {
+  private queue: DeferredRequest[]
+  private renewUrl: string
+  private clearUrl: string
+  private retries: number
+  private backoff: number
+  private flushInterval: number
+  private flushIntervalId?: NodeJS.Timer
+
+  private constructor(options: HTTPCookieServiceOptions) {
+    this.renewUrl = options.renewUrl
+    this.clearUrl = options.clearUrl
+    this.backoff = options.backoff ?? 300
+    this.retries = options.retries ?? 3
+    this.flushInterval = options.flushInterval ?? 1000
+    this.queue = []
+  }
+
+  static async load(
+    options: HTTPCookieServiceOptions
+  ): Promise<HTTPCookieService> {
+    const cookieService = new HTTPCookieService(options)
+
+    // renew any existing HTTPCookies already on the device
+    // we want `load()` to block on this, so await directly instead of calling dispatch
+    const req = cookieService.sendHTTPCookies(options.renewUrl)
+    await retry(req, cookieService.retries, cookieService.backoff).catch(
+      console.error
+    )
+
+    // consume HTTPCookie actions, sequentially, as needed
+    cookieService.startQueueConsumer()
+
+    return cookieService
+  }
+
+  dispatchCreate() {
+    this.queue.push(this.sendHTTPCookies(this.renewUrl))
+  }
+
+  dispatchClear() {
+    this.queue.push(this.sendHTTPCookies(this.clearUrl))
+  }
+
+  startQueueConsumer() {
+    if (this.flushIntervalId) {
+      console.error('HTTPCookie queue consumer is already running.')
+      return
+    }
+    const bound = this.consumeQueue.bind(this)
+    this.flushIntervalId = setInterval(
+      () => bound().catch(console.error),
+      this.flushInterval
+    )
+  }
+
+  stopQueueConsumer() {
+    if (!this.flushIntervalId) {
+      console.error('HTTPCookie queue consumer is already stopped.')
+      return
+    }
+    clearInterval(this.flushIntervalId)
+    this.flushIntervalId = undefined
+  }
+
+  private sendHTTPCookies(serviceUrl: string): DeferredRequest {
+    return async function (): Promise<Response> {
+      return await fetch(serviceUrl, {
+        credentials: 'include',
+        headers: {
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        },
+        method: 'post',
+        body: JSON.stringify({
+          sentAt: new Date().toISOString(),
+        }),
+      })
+    }
+  }
+
+  /**
+   * This queue exists to avoid race conditions.
+   *
+   * Customer-developers may not `await` all promises.
+   *
+   * Therefore, introducing async code into analytics.track(), etc
+   * could create race conditions in customer code.
+   *
+   * The queue enforces: if someone calls analytics.clear()
+   * before calling analytics.identify(), the cookie service
+   * will consume those actions, sequentially, even if no promises
+   * are awaited.
+   */
+  private async consumeQueue() {
+    while (this.queue.length > 0) {
+      const req = this.queue.shift() as DeferredRequest
+      await retry(req, this.retries, this.backoff).catch(console.error)
+    }
+  }
+}
+
+async function sleep(delayMS: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, delayMS))
+}
+
+async function retry(
+  req: DeferredRequest,
+  retries: number,
+  backoff: number
+): Promise<Response> {
+  while (retries >= 0) {
+    try {
+      return await req().then((res) => {
+        if (res.ok) return res
+        throw new Error(`Status: ${res.status} ${res.statusText}`)
+      })
+    } catch (error) {
+      retries -= 1
+      if (retries <= 0) throw error
+      await sleep(backoff)
+    }
+  }
+  throw Error('HtEvents: Problem with DeferredRequest')
+}

package/src/core/user/index.ts

@@ -21,6 +21,7 @@ import {
   hasSessionExpired,
   updateSessionExpiration,
 } from '../session'
+import type { HTTPCookieService } from '../http-cookies'
 
 export type ID = string | null | undefined
 
@@ -32,6 +33,11 @@ export interface UserOptions {
   localStorageFallbackDisabled?: boolean
   persist?: boolean
 
+  /**
+   * Replicates "BrowserCookie" actions against a matching "ServerCookie".
+   */
+  httpCookieService?: HTTPCookieService
+
   cookie?: {
     key?: string
     oldKey?: string
@@ -145,11 +151,22 @@ export class User {
     const prevId = this.identityStore.getAndSync(this.idKey)
 
     if (id !== undefined) {
+      const clearingIdentity = id === null
+      const changingIdentity = id !== prevId && prevId !== null && id !== null
+      const creatingIdentity = id !== prevId && prevId === null && id !== null
+
       this.identityStore.set(this.idKey, id)
 
-      const changingIdentity = id !== prevId && prevId !== null && id !== null
+      if (clearingIdentity) {
+        this.options?.httpCookieService?.dispatchClear()
+      }
+
       if (changingIdentity) {
-        this.anonymousId(null)
+        this.anonymousId(null) // this also runs dispatchClear()
+      }
+
+      if (changingIdentity || creatingIdentity) {
+        this.options?.httpCookieService?.dispatchCreate()
       }
     }
 
@@ -176,28 +193,36 @@ export class User {
 
     if (id === undefined) {
       let val = this.identityStore.getAndSync(this.anonKey)
+      let migrated = false
 
       // support anonymousId migration from other analytics providers
       if (!val) {
         val = decryptRudderHtValue(
           this.identityStore.getAndSync(rudderHtAnonymousIdKey) ?? ''
         )
+        migrated = Boolean(val)
         if (val) this.identityStore.set(this.anonKey, val)
       }
       if (!val) {
         val = this.identityStore.getAndSync(segmentAnonymousIdKey)
+        migrated = Boolean(val)
         if (val) this.identityStore.set(this.anonKey, val)
       }
       if (!val) {
         val = decryptRudderValue(
           this.identityStore.getAndSync(rudderAnonymousIdKey) ?? ''
         )
+        migrated = Boolean(val)
         if (val) this.identityStore.set(this.anonKey, val)
       }
       if (!val) {
         val = this.legacySIO()?.[0] ?? null
       }
 
+      if (migrated) {
+        this.options?.httpCookieService?.dispatchCreate()
+      }
+
       if (val) {
         return val
       }
@@ -205,11 +230,16 @@ export class User {
 
     if (id === null) {
       this.identityStore.set(this.anonKey, null)
-      return this.identityStore.getAndSync(this.anonKey)
+      const clearedVal = this.identityStore.getAndSync(this.anonKey)
+      this.options?.httpCookieService?.dispatchClear()
+      return clearedVal
     }
 
     this.identityStore.set(this.anonKey, id ?? uuid())
-    return this.identityStore.getAndSync(this.anonKey)
+    const syncedVal = this.identityStore.getAndSync(this.anonKey)
+
+    this.options?.httpCookieService?.dispatchCreate()
+    return syncedVal
   }
 
   traits = (traits?: Traits | null): Traits | undefined => {

package/src/generated/version.ts

@@ -1,2 +1,2 @@
 // This file is generated.
-export const version = '1.1.0'
+export const version = '1.2.0'

package/src/node/index.ts

@@ -20,7 +20,7 @@ export class AnalyticsNode {
 
     const nodeSettings = {
       writeKey: settings.writeKey,
-      name: 'analytics-node-next',
+      name: 'events-sdk-js-node',
       type: 'after' as Plugin['type'],
       version: 'latest',
     }

package/src/plugins/analytics-node/index.ts

@@ -23,7 +23,7 @@ export async function post(
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        'User-Agent': 'analytics-node-next/latest',
+        'User-Agent': 'events-sdk-js-node/latest',
         Authorization: `Basic ${btoa(writeKey)}`,
       },
       body: JSON.stringify(event),
@@ -39,7 +39,7 @@ export async function post(
 
 export function analyticsNode(settings: AnalyticsNodeSettings): Plugin {
   const send = async (ctx: Context): Promise<Context> => {
-    ctx.updateEvent('context.library.name', 'analytics-node-next')
+    ctx.updateEvent('context.library.name', 'events-sdk-js-node')
     ctx.updateEvent('context.library.version', version)
     ctx.updateEvent('_metadata.nodeVersion', process.versions.node)