@ghostery/trackerdb 0.1.3 → 1.0.1

package/README.md

@@ -19,6 +19,26 @@ The Tracker Database is used in [Ghostery Browser Extension](https://www.ghoster
 
 It is also used by universities, journalists, and companies that want to understand the nature of the web data exchange.
 
+## SDK
+
+The Ghostery Tracker Database comes with a JavaScript SDK. Sample usage:
+
+```js
+import loadTrackerDB from '@ghostery/trackerdb';
+
+const trackerDB = await loadTrackerDB();
+
+const domainMatches = await trackerDB.matchDomain('google.com');
+
+const urlMatches = await trackerDB.matchUrl({
+    url: 'https://google.com/gen_204',
+    type: 'xhr',
+    sourceUrl: 'https://google.com/'
+}, {
+    getDomainMetadata: true,
+});
+```
+
 ## CLI
 
 Ghostery Tracker Database can also be used in a commnad line, for example with:

package/cli.js

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
 
-import path from 'node:path';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { FiltersEngine, Request, ENGINE_VERSION } from '@cliqz/adblocker';
-
-import { BASE_PATH } from './scripts/helpers.js';
+import { readFileSync } from 'node:fs';
+import { FiltersEngine, Request } from '@cliqz/adblocker';
+import { generateEngine } from './src/prepare.js';
 
 const debug = process.env.DEBUG === 'true' ? console.log : () => {};
 
@@ -17,30 +15,16 @@ const debug = process.env.DEBUG === 'true' ? console.log : () => {};
     process.exit(1);
   }
 
-  // Generate input JSON if missing
-  const trackerDBPath = path.join(BASE_PATH, 'dist', 'trackerdb.json');
-  if (!existsSync(trackerDBPath)) {
-    await import('./scripts/export-json/index.js');
-  }
-
-  // Generate binary engine if missing
-  const trackerEnginePath = path.join(
-    BASE_PATH,
-    'dist',
-    `trackerdb_${ENGINE_VERSION}.engine`,
-  );
-  if (!existsSync(trackerEnginePath)) {
-    const rawTrackerDB = JSON.parse(readFileSync(trackerDBPath, 'utf-8'));
-    const engine = FiltersEngine.fromTrackerDB(rawTrackerDB);
-    writeFileSync(trackerEnginePath, engine.serialize());
-  }
+  const trackerEnginePath = await generateEngine();
 
   const loadingStart = Date.now();
   const engine = FiltersEngine.deserialize(readFileSync(trackerEnginePath));
   const loadingEnd = Date.now();
 
   const matches = url.startsWith('http')
-    ? engine.getPatternMetadata(Request.fromRawDetails({ url }))
+    ? engine.getPatternMetadata(Request.fromRawDetails({ url, type: 'xhr' }), {
+        getDomainMetadata: true,
+      })
     : engine.metadata.fromDomain(url);
   const matchingEnd = Date.now();
 

package/index.js

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs';
+import { FiltersEngine, Request, ENGINE_VERSION } from '@cliqz/adblocker';
+
+import { generateEngine } from './src/prepare.js';
+
+export { Request as AdblockerRequest };
+
+export default async function loadTrackerDBEngine() {
+  const trackerEnginePath = await generateEngine();
+  const engine = FiltersEngine.deserialize(readFileSync(trackerEnginePath));
+  return {
+    ENGINE_VERSION,
+    engine,
+    matchUrl(
+      requestArgs,
+      getPatternMetadataParams = { getDomainMetadata: true },
+    ) {
+      const params = { ...requestArgs };
+      if (params.type === undefined) {
+        params.type = 'xhr';
+      }
+      return engine.getPatternMetadata(
+        Request.fromRawDetails(params),
+        getPatternMetadataParams,
+      );
+    },
+    matchDomain(domain) {
+      return engine.metadata.fromDomain(domain);
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghostery/trackerdb",
-  "version": "0.1.3",
+  "version": "1.0.1",
   "description": "Ghostery Tracker Database",
   "type": "module",
   "scripts": {
@@ -10,6 +10,8 @@
     "export-engine": "node scripts/export-engine/index.js",
     "export-json": "node scripts/export-json/index.js"
   },
+  "main": "./index.js",
+  "exports": "./index.js",
   "bin": {
     "trackerdb": "./cli.js"
   },
@@ -17,7 +19,7 @@
     "type": "git",
     "url": "git+https://github.com/ghostery/trackerdb.git"
   },
-  "author": "Ghostery",
+  "author": "Ghostery GmbH.",
   "license": "CC-BY-NC-SA-4.0",
   "bugs": {
     "url": "https://github.com/ghostery/trackerdb/issues"
@@ -27,7 +29,7 @@
     "node": ">=18.0"
   },
   "dependencies": {
-    "@cliqz/adblocker": "^1.26.0",
+    "@cliqz/adblocker": "^1.26.5",
     "enolib": "^0.8.2",
     "iso-3166-1-alpha-2": "^1.0.0",
     "sqlite": "^4.1.2",

package/src/prepare.js

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { FiltersEngine, ENGINE_VERSION } from '@cliqz/adblocker';
+
+import { BASE_PATH } from '../scripts/helpers.js';
+
+export async function generateEngine() {
+  // Generate input JSON if missing
+  const trackerDBPath = path.join(BASE_PATH, 'dist', 'trackerdb.json');
+  if (!existsSync(trackerDBPath)) {
+    await import('../scripts/export-json/index.js');
+  }
+
+  // Generate binary engine if missing
+  const trackerEnginePath = path.join(
+    BASE_PATH,
+    'dist',
+    `trackerdb_${ENGINE_VERSION}.engine`,
+  );
+
+  if (!existsSync(trackerEnginePath)) {
+    const rawTrackerDB = JSON.parse(readFileSync(trackerDBPath, 'utf-8'));
+    const engine = FiltersEngine.fromTrackerDB(rawTrackerDB);
+    writeFileSync(trackerEnginePath, engine.serialize());
+  }
+
+  return trackerEnginePath;
+}