ZKTeco Standalone Device TypeScript SDK

A standalone, highly decoupled, and production-ready TypeScript SDK designed to communicate with ZKTeco biometric terminals using the TCP/IP-based ZKProtocol (via a local patched node-zklib module).

This SDK includes dynamic fallback engines to gracefully handle structural protocol differences between high-end Linux multi-biometric devices and lightweight compact Wi-Fi terminals.

1. Project Directory Structure

zkteco-device-sdk/
├── src/
│   ├── index.ts                # Package entry point (module exports)
│   └── zk-sdk.ts               # SDK implementation class & interfaces
├── dist/                       # Output compiled Javascript & .d.ts files
├── package.json                # Project configurations & dependencies
├── tsconfig.json               # TypeScript compiler options
└── readme.md                   # Documentation

2. Dynamic Hardware Compatibility Matrix

This SDK automatically adapts to structural differences in ZKTeco device responses:

| Feature / Detail | Linux Multi-Biometric Terminal | Compact Wi-Fi Terminal | | :--- | :--- | :--- | | Device Category | Premium Multi-Biometric (Face/FP/Card) | Compact Wi-Fi Fingerprint | | Response Buffer Size | Full $\ge 80$ bytes | Compact $12$ bytes | | getInfo() Opcode Parsing | Reads hardware offsets 24, 40, 72 | Safe boundary parsing prevents RangeError | | Dynamic Fallback Stats | Instant socket retrieval | Automatically queries getUsers() and getLogs() | | Standard Log Capacity | Retrieved from device | Defaulted to hardware limit (50,000 logs) |

3. Installation & Local Integration

To use this SDK inside another local project (such as your web application) without uploading it to npm, you can link it locally.

Step 1: Compile the SDK

Navigate to the SDK directory and install dependencies and compile the TypeScript code:

cd d:\flo\projects\2026\zkteco-device-sdk
npm install
npm run build

This will compile the TypeScript files and generate type declarations inside the dist/ directory:

• dist/index.js & dist/zk-sdk.js (Executable CommonJS Javascript)
• dist/index.d.ts & dist/zk-sdk.d.ts (Strongly-typed declaration maps)

Step 2: Register Local Link

Inside the SDK folder, register the package with your local Node environment:

npm link

Step 3: Link in your Target Project

Navigate to your main Next.js project directory (zkteco-device-management) and link the SDK:

cd d:\flo\projects\2026\zkteco-device-management
npm link @your-org/zkteco-device-sdk

Now, you can import and use the SDK inside your application's routes and components:

import { ZkDeviceSdk } from "@your-org/zkteco-device-sdk";

4. API Usage Reference

Direct Connection

import { ZkDeviceSdk } from "@your-org/zkteco-device-sdk";

const sdk = new ZkDeviceSdk();

const isConnected = await sdk.connect({
  ipAddress: "192.168.31.190",
  port: 4370,
  timeoutMs: 10000,
  commKey: 0
});

if (isConnected) {
  console.log("Connected successfully!");
}

Fetching Device Info (Multi-Biometric / Compact Terminal Compatible)

// Works flawlessly on both multi-biometric and compact terminals without RangeError crashes!
const info = await sdk.getDeviceInfo();
console.log(`Capacity: ${info.logCounts} / ${info.logCapacity} logs.`);
console.log(`Enrolled Employees: ${info.userCounts}`);

Fetching Logs and Enrolled Users

const users = await sdk.getUsers();
console.log("Fetched users:", users.length);

const logs = await sdk.getLogs();
console.log("Fetched logs:", logs.length);

Clean Disconnect (Crucial)

try {
  await sdk.connect(config);
  // Perform queries ...
} finally {
  await sdk.disconnect(); // Always runs to release sockets
}

5. Development and Publication

To package and publish this module to public or private NPM scopes:

1. Sign in to npm:

   npm login

2. Build and Publish:

   npm publish --access public