ENG-4043: Add device tracking library

.prettierignore

@@ -0,0 +1,3 @@
+dist/
+node_modules/
+pnpm-lock.yaml

README.md

@@ -1,18 +1,69 @@
 # MaxMind Device Tracking Add-On
 
+A thin loader package for MaxMind's [minFraud device tracking](https://dev.maxmind.com/minfraud/track-devices)
+system. This package dynamically loads the device fingerprinting module from
+MaxMind's servers at runtime, ensuring you always get the latest version without
+updating the npm package.
+
+The package itself contains no fingerprinting logic — it validates inputs, loads
+the remote module, and returns the tracking token.
+
 ## Installation
 
 ```bash
 npm install @maxmind/device-tracking
 ```
 
-## License
+## Usage
+
+```typescript
+import { trackDevice } from '@maxmind/device-tracking';
+
+const result = await trackDevice({ accountId: 123456 });
+console.log(result.trackingToken);
+```
+
+### Ad-blocker bypass
+
+If you proxy MaxMind's device tracking through your own subdomain (to avoid
+ad-blockers), pass the `host` option. The module will be loaded from your
+custom host, and the host value is passed to the remote module for its own use:
+
+```typescript
+const result = await trackDevice({
+  accountId: 123456,
+  host: 'tracking.yourdomain.com',
+});
+```
+
+### Disable WebGL hash
+
+For performance or compatibility, you can disable WebGL hash collection:
+
+```typescript
+const result = await trackDevice({
+  accountId: 123456,
+  disableWebglHash: true,
+});
+```
+
+## API reference
+
+### `trackDevice(options: TrackDeviceOptions): Promise<TrackResult>`
+
+Loads the device tracking module (if not already cached) and collects a device
+fingerprint.
+
+### `TrackDeviceOptions`
 
-Licensed under either of
+| Property           | Type      | Required | Description                                     |
+| ------------------ | --------- | -------- | ----------------------------------------------- |
+| `accountId`        | `number`  | Yes      | Your MaxMind account ID (positive integer)      |
+| `host`             | `string`  | No       | Custom hostname for ad-blocker bypass            |
+| `disableWebglHash` | `boolean` | No       | Disable WebGL hash collection                    |
 
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
-  https://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or
-  https://opensource.org/licenses/MIT)
+### `TrackResult`
 
-at your option.
+| Property        | Type     | Description                    |
+| --------------- | -------- | ------------------------------ |
+| `trackingToken` | `string` | Opaque device tracking token   |

eslint.config.mjs

@@ -0,0 +1,27 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettierConfig from 'eslint-config-prettier';
+import globals from 'globals';
+
+export default tseslint.config(
+  {
+    ignores: ['dist/', 'node_modules/', 'coverage/', 'jest.config.js', '*.mjs'],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  prettierConfig,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+      parserOptions: {
+        projectService: {
+          allowDefaultProject: ['src/*.spec.ts'],
+        },
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  }
+);

jest.config.js

@@ -0,0 +1,18 @@
+/** @type {import('jest').Config} */
+export default {
+  testEnvironment: 'jest-environment-jsdom',
+  extensionsToTreatAsEsm: ['.ts'],
+  transform: {
+    '^.+\\.ts$': [
+      'ts-jest',
+      {
+        useESM: true,
+        tsconfig: 'tsconfig.eslint.json',
+      },
+    ],
+  },
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$',
+};

mise.lock

@@ -1,3 +1,12 @@
+[[tools."github:houseabsolute/precious"]]
+version = "0.10.1"
+backend = "github:houseabsolute/precious"
+"platforms.linux-arm64" = { checksum = "sha256:3db65f6d3b3502b3b5aaf6df889bc41bda3bb5fac09952c74d6e831652a9df8b", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.1/precious-Linux-musl-arm64.tar.gz", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/309267455"}
+"platforms.linux-x64" = { checksum = "sha256:34e378aed182421ffacf3f06c80c1f3f7d98c4c9b61b2cacde3ea70868bccfd5", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.1/precious-Linux-musl-x86_64.tar.gz", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/309267664"}
+"platforms.macos-arm64" = { checksum = "sha256:dbaba885c2d79d3213389c81890720bed390c37cb275cd93bd59a4a0a59721a5", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.1/precious-macOS-arm64.tar.gz", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/309267548"}
+"platforms.macos-x64" = { checksum = "sha256:5e7a9a50d388e7d6c04bcccd654f7bcf6095a347899d308d35e7768caead6ba6", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.1/precious-macOS-x86_64.tar.gz", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/309267052"}
+"platforms.windows-x64" = { checksum = "sha256:22f452a5559b81f4528e5cc3cc79263ca30d61af6c09e0b008c3816ff9d40760", url = "https://github.com/houseabsolute/precious/releases/download/v0.10.1/precious-Windows-msvc-x86_64.zip", url_api = "https://api.github.com/repos/houseabsolute/precious/releases/assets/309267436"}
+
 [[tools.node]]
 version = "25.6.1"
 backend = "core:node"

mise.toml

@@ -13,6 +13,7 @@ disable_backends = [
 [tools]
 node = "latest"
 pnpm = "latest"
+"github:houseabsolute/precious" = "0.10.1"
 
 [hooks]
 enter = "mise install --quiet"

package.json

@@ -4,6 +4,15 @@
   "description": "MaxMind Device Tracking Add-On",
   "license": "Apache-2.0 OR MIT",
   "author": "MaxMind",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/maxmind/device-tracking.git"
@@ -20,6 +29,29 @@
   "files": [
     "dist"
   ],
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts"
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "lint": "eslint . && tsc --noEmit",
+    "prettier:ts": "prettier --parser typescript --write 'src/**/*.ts'",
+    "prettier:ci": "prettier --parser typescript --list-different 'src/**/*.ts'",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test:watch": "NODE_OPTIONS='--experimental-vm-modules' jest --watch",
+    "prepublishOnly": "pnpm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.10.0",
+    "@jest/globals": "^30.0.0",
+    "eslint": "^9.10.0",
+    "eslint-config-prettier": "^10.0.1",
+    "globals": "^16.0.0",
+    "jest": "^30.0.0",
+    "jest-environment-jsdom": "^30.0.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.5.0"
+  }
 }