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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ht-sdks/events-sdk-js-browser",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/ht-sdks/events-sdk-js-mono",
@@ -24,28 +24,24 @@
   ],
   "sideEffects": false,
   "scripts": {
-    ".": "yarn run -T turbo run --filter=@ht-sdks/events-sdk-js-browser...",
     "build-prep": "sh scripts/build-prep.sh",
-    "version": "yarn run build-prep && git add src/generated/version.ts",
+    "version": "npm run build-prep && git add src/generated/version.ts",
     "umd": "webpack",
-    "eslint": "yarn run -T eslint",
-    "tsc": "yarn run -T tsc",
-    "jest": "yarn run -T jest",
-    "concurrently": "yarn run -T concurrently",
-    "watch": "yarn concurrently 'NODE_ENV=production WATCH=true yarn umd --watch' 'yarn pkg --watch'",
-    "build": "yarn clean && yarn build-prep && yarn concurrently 'NODE_ENV=production yarn umd' 'yarn pkg' 'yarn cjs'",
-    "candidate:cdn": "yarn . build && NODE_ENV=production PATH_PREFIX=browser/candidate bash scripts/release.sh",
-    "release:cdn": "yarn . build && NODE_ENV=production PATH_PREFIX=browser/release bash scripts/release.sh",
-    "pkg": "yarn tsc -p tsconfig.build.json",
-    "cjs": "yarn tsc -p tsconfig.build.json --outDir ./dist/cjs --module commonjs",
+    "watch": "concurrently 'NODE_ENV=production WATCH=true npm run umd -- --watch' 'npm run pkg -- --watch'",
+    "build": "npm run clean && npm run build-prep && concurrently 'NODE_ENV=production npm run umd' 'npm:pkg' 'npm:cjs'",
+    "candidate:cdn": "turbo run build && NODE_ENV=production PATH_PREFIX=browser/candidate bash scripts/release.sh",
+    "release:cdn": "turbo run build && NODE_ENV=production PATH_PREFIX=browser/release bash scripts/release.sh",
+    "pkg": "tsc -p tsconfig.build.json",
+    "cjs": "tsc -p tsconfig.build.json --outDir ./dist/cjs --module commonjs",
     "clean": "rm -rf dist",
-    "lint": "yarn concurrently 'yarn:eslint .' 'yarn:tsc --noEmit'",
-    "test": "yarn jest"
+    "lint": "concurrently 'eslint .' 'tsc --noEmit'",
+    "test": "jest",
+    "size-limit": "size-limit"
   },
   "size-limit": [
     {
       "path": "dist/umd/index.js",
-      "limit": "28.9 KB"
+      "limit": "37 KB"
     }
   ],
   "dependencies": {
@@ -86,7 +82,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",
@@ -101,6 +97,5 @@
     "webpack": "^5.76.0",
     "webpack-bundle-analyzer": "^4.4.2",
     "webpack-cli": "^4.8.0"
-  },
-  "packageManager": "yarn@3.4.1"
+  }
 }

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'
@@ -29,6 +30,7 @@ import {
 import { ClassicIntegrationSource } from '../plugins/ajs-destination/types'
 import { attachInspector } from '../core/inspector'
 import { setGlobalAnalyticsKey } from '../lib/global-analytics-helper'
+import { createDestination } from '../plugins/destinations'
 
 export interface LegacyIntegrationConfiguration {
   /* @deprecated - This does not indicate browser types anymore */
@@ -269,6 +271,18 @@ async function registerPlugins(
     )
   }
 
+  // destination plugins
+  await Promise.allSettled(
+    Object.entries(options.destinations ?? {}).map(async ([name, settings]) => {
+      const plugin = await createDestination(name, settings)
+      if (plugin) {
+        toRegister.push(plugin)
+      } else {
+        console.warn(`failed to load destination plugin: ${name}`)
+      }
+    })
+  )
+
   const ctx = await analytics.register(...toRegister)
 
   if (
@@ -359,6 +373,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
+    ).catch((err): undefined => console.error(err) as undefined)
+  }
+
   const opts: InitOptions = { retryQueue, ...options }
   const analytics = new Analytics(settings, opts)
 

package/src/core/analytics/index.ts

@@ -55,6 +55,11 @@ 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'
+import type { DestinationSettings } from '../../plugins/destinations'
 
 const deprecationWarning =
   'This is being deprecated and will be not be available in future releases of Analytics JS'
@@ -129,6 +134,20 @@ export interface InitOptions {
    */
   globalAnalyticsKey?: string
 
+  /**
+   * Allows specifying plugins as configuration. Used to load plugins in `plugins/destinations/*`.
+   */
+  destinations?: Record<string, DestinationSettings>
+
+  /**
+   * 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 +210,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,97 @@
+# 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` status code.
+
+## Server Examples
+
+- [Express.js and NGINX](./server-examples/node-express-js.md)
+- [Next.js and Vercel](./server-examples/node-next-js.md)
+- [AWS Lambda and API Gateway](./server-examples/node-aws-lambda.md)
+
+## More information
+- Safari: https://webkit.org/blog/9521/intelligent-tracking-prevention-2-3/

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

@@ -0,0 +1,165 @@
+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) {
+    const urls = HTTPCookieService.urlHelper(options)
+    this.renewUrl = urls.renewUrl
+    this.clearUrl = urls.clearUrl
+
+    this.backoff = options.backoff ?? 300
+    this.retries = options.retries ?? 3
+    this.flushInterval = options.flushInterval ?? 1000
+    this.queue = []
+  }
+
+  static urlHelper(options: HTTPCookieServiceOptions): {
+    renewUrl: string
+    clearUrl: string
+  } {
+    const origin = window.location.origin
+    return {
+      renewUrl: new URL(options.renewUrl, origin).href,
+      clearUrl: new URL(options.clearUrl, origin).href,
+    }
+  }
+
+  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(cookieService.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/http-cookies/server-examples/node-aws-lambda.md

@@ -0,0 +1,167 @@
+**These server examples should not be used as is. They should be adapted to your setup and "productionized".**
+
+An example HTTPCookieService written as an AWS Lambda Function:
+
+```Javascript
+const USER_COOKIE = "htjs_user_id";
+const ANON_COOKIE = "htjs_anonymous_id";
+const DOMAIN = "CHANGEME.example.com";
+
+function renewCookies(request, response, browserName, serverName) {
+  let cookie = request.cookies[browserName] ?? request.cookies[serverName];
+  if (!cookie) return "";
+  const maxAge = 31_536_000; // 1 year in seconds
+  response.cookies= (response.cookies ?? []).concat([
+    `${browserName}=${cookie}; Max-Age=${maxAge}; Domain=${DOMAIN}; Path=/; SameSite=Lax;`,
+    `${serverName}=${cookie}; Max-Age=${maxAge}; Domain=${DOMAIN}; Path=/; SameSite=Lax; httpOnly=true;`,
+  ]);
+  return cookie;
+}
+
+function clearServerCookie(request, response, serverName) {
+  const cookie = "";
+  const maxAge = 0;
+  response.cookies = (response.cookies ?? []).concat([
+    `${serverName}=${cookie}; Max-Age=${maxAge}; Domain=${DOMAIN}; Path=/; SameSite=Lax; httpOnly;`,
+  ]);
+  return cookie;
+}
+
+function getCookies(reqCookies) {
+  const cookies = {};
+  if (!reqCookies) return cookies;
+  for (const cookieStr of reqCookies) {
+    const cookieArr = cookieStr.split("=");
+    if (cookieArr.length == 1) {
+      cookies[cookieArr[0]] = "";
+    } else if (cookieArr.length == 2) {
+      cookies[cookieArr[0]] = cookieArr[1]; 
+    } else {
+      console.log("cookieArr", cookieArr);
+    }
+  }
+  return cookies;
+}
+
+export const handler = async (event, context) => {
+  const request = {
+    method: event.requestContext.http.method,
+    path: event.pathParameters.proxy,
+    headers: event.headers,
+    cookies: getCookies(event.cookies),
+  }
+  const response = {
+    statusCode: '200',
+    headers: {
+      "Content-Type": "application/json"
+    },
+    isBase64Encoded: false,
+    multiValueHeaders: {},
+    body: "{}",
+  };
+    
+  if (request.method?.toUpperCase() !== "POST") {
+    response.statusCode = 404;
+    return response;
+  }
+
+  if (request.path === "renew") {
+    const userId = renewCookies(request, response, USER_COOKIE, `${USER_COOKIE}_srvr`);
+    const anonymousId = renewCookies(request, response, ANON_COOKIE, `${ANON_COOKIE}_srvr`);
+    response.body = JSON.stringify({
+      userId,
+      anonymousId,
+    })
+  } else if (request.path === "clear") {
+    const userId = clearServerCookie(request, response, `${USER_COOKIE}_srvr`);
+    const anonymousId = clearServerCookie(request, response, `${ANON_COOKIE}_srvr`);
+    response.body = JSON.stringify({
+      userId,
+      anonymousId,
+    })
+  } else {
+    response.statusCode = 404;
+  }
+  return response;
+};
+```
+
+After creating the above Lambda Function, you'll need to setup an [API Gateway](https://aws.amazon.com/api-gateway/). Specifically, create a new `Route` and input the value of `/ht/{proxy}`. Then attach an `integration` for this route, and select your Lambda. Your HTTPCookieService lambda will now be callable over HTTP at `${ApiGatewayURL}.com/default/ht/renew`.
+
+However, the HTTPCookieService must live on the same domain and IP address as your website's HTML document.
+
+As one way to accomplish this, you could use a CDN to front both your HTML document and your API Gateway. To do this, create a Cloudfront Distribution. Then create multiple origin configurations. One will have a `customOriginSource`, and a `pathPattern` of `/ht/*` pointing at your API Gateway's URL. The other origin configuration will point at an `s3OriginSource` if your HTML website is being hosted on S3. You would then configure your Web SDK to point at `/ht/renew` and `/ht/clear` for the HTTPCookieService routes.
+
+---
+
+Alternatively, if you simply want a "Hello World" example for a fully functioning HTTPCookieService, you can create two lambdas (one for HTML and another for HTTPCookieService), and put them both on the same API Gateway. You can then test against the API Gateway domain.
+
+Example "Lambda for HTML". This is only intended for testing and "Hello World" purposes:
+
+```Javascript
+const cdnDomain = "https://cdn.hightouch-events.com/browser/release/v1-latest/events.min.js";
+
+const writeKey = "WRITE KEY";
+
+const html = `
+<head>
+<script type="text/javascript">
+!function(){var e=window.htevents=window.htevents||[];if(!e.initialize)if(e.invoked)window.console&&console.error&&console.error("Hightouch snippet included twice.");else{e.invoked=!0,e.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware"],e.factory=function(t){return function(){var n=Array.prototype.slice.call(arguments);return n.unshift(t),e.push(n),e}};for(var t=0;t<e.methods.length;t++){var n=e.methods[t];e[n]=e.factory(n)}e.load=function(t,n){var o=document.createElement("script");o.type="text/javascript",o.async=!0,o.src="${cdnDomain}";var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(o,r),e._loadOptions=n,e._writeKey=t},e.SNIPPET_VERSION="0.0.1",
+e.load('${writeKey}',{
+  apiHost:'us-east-1.hightouch-events.com',
+  httpCookieServiceOptions: {clearUrl: 'default/ht/clear', renewUrl: 'default/ht/renew', backoff: 5000},
+}),
+e.page()}}();
+</script>
+
+</head>
+<body>
+  Hightouch
+  <a href="#" onClick="(function(){
+    htevents.identify(
+      '123', {
+        email: 'bob@hightouch.io'
+      }, {},
+      () => {
+        console.log('identify call');
+      }
+    );
+    })();return false;">identify
+  </a>
+  <br>
+  <br>
+  <a href="#" onClick="(function(){
+    htevents.track(
+      'clickEvent', {
+        revenue: 30,
+        currency: 'USD',
+        user_actual_id: 123
+      }, {},
+      () => {
+        console.log('track call');
+      }
+    );
+    })();return false;">track
+  </a>
+  <br>
+  <br>
+    <a href="#" onClick="(function(){
+    htevents.reset();
+    htevents.identify('456', { email: 'george@hightouch.com'})
+    })();return false;">reset
+  </a>
+</body>
+`;
+
+export const handler = async () => {
+    const response = {
+        statusCode: 200,
+        headers: {
+            'Content-Type': 'text/html',
+        },
+        body: html,
+    };
+    return response;
+};
+
+```

package/src/core/http-cookies/server-examples/node-express-js.md

@@ -0,0 +1,103 @@
+**These server examples should not be used as is. They should be adapted to your setup and "productionized".**
+
+An example HTTPCookieService written in Node.js/Express.js:
+
+```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(process.env.PORT || 3000, () => {
+  console.log(`Listening on port ${process.env.PORT}...`);
+});
+```
+
+The HTTPCookieService must live on the same domain and IP address as your website's HTML document.
+
+As one way to accomplish this, you could have NGINX both serve your HTML document and forward requests to the Node.js/Express server.
+
+An **overly simplified** NGINX reverse proxy:
+```
+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/*;
+}
+```