Quickstart

Get up and running with the Heuristik JavaScript SDK in minutes.

Prerequisites

• Fingerprint scanner (provided by Heuristik)
• Local driver installed and running (provided by Heuristik)
• API credentials: apiKey, apiSecret, and tenant UUID (provided by Heuristik)
• Node.js 24.8.0 or a modern browser

Package managers

Manager	Minimum version
npm	≥ 11.0
yarn	≥ 1.22
pnpm	≥ 9.0

Supported browsers

Browser	Minimum version
Chrome	≥ 80
Edge	≥ 80
Firefox	≥ 74
Opera	≥ 67

Registry configuration

The SDK is published on a private registry. Add a .npmrc file to your project root:

@heuristik:registry=https://npm.heuristik.link/

Installation

npm

npm install @heuristik/hhjssdk

yarn

yarn add @heuristik/hhjssdk

pnpm

pnpm add @heuristik/hhjssdk

Module formats

The SDK ships with dual module formats and TypeScript declarations:

Format	Entry point	Usage
ES Modules	dist/index.esm.js	import { HeuristikClient } from '@heuristik/hhjssdk'
CommonJS	dist/index.cjs	const { HeuristikClient } = require('@heuristik/hhjssdk')
TypeScript	dist/types/index.d.ts	Full type declarations included

The package uses conditional exports — your bundler or runtime will resolve the correct format automatically.

How it works

Minimal example

import { HeuristikClient, setStorageProvider } from '@heuristik/hhjssdk';

// ⚠️ For production, use HttpOnly cookies instead of localStorage
setStorageProvider({
  getItem: async (k) => localStorage.getItem(k),
  setItem: async (k, v) => localStorage.setItem(k, v),
  removeItem: async (k) => localStorage.removeItem(k),
});

const client = new HeuristikClient({
  apiBase: 'https://api.example.com/public/v1',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
  tenant: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  country: 'CO',
});

// Authenticate and load stored tokens
await client.init();

// Identify a person by fingerprint (finger index 1 = right index)
const result = await client.operations.identifyPerson(1);
console.log('Identified:', result);

// Clean up when done
await client.logout();

TypeScript support

The SDK is written in TypeScript and ships with full type declarations. All types are exported from the main @heuristik/hhjssdk package.

Next steps

• Authentication — understand the auth lifecycle and token management
• Operations — explore all fingerprint and person operations
• Scanner Driver — learn about the WebSocket connection to the fingerprint scanner
• Storage — configure token persistence for your environment
• Error Handling — handle errors gracefully