{"_id":"@ahopez/zk-workers-lib","_rev":"5-0b44f4e6fee507408ab98093df275b3e","name":"@ahopez/zk-workers-lib","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.0":{"name":"@ahopez/zk-workers-lib","version":"1.0.0","keywords":["zkteco","biometric","fingerprint","attendance","cloudflare-workers","cloudflare-sockets","node","tcp","sdk"],"author":{"url":"https://github.com/AhopeZ-Innovations","name":"ArunKumar","email":"arun@ahopez.in"},"license":"MIT","_id":"@ahopez/zk-workers-lib@1.0.0","maintainers":[{"name":"dev.itsak","email":"arun@ahopez.in"}],"dist":{"shasum":"b964e0678eefaa01e89c324da33ab78eff2d5f33","tarball":"https://registry.npmjs.org/@ahopez/zk-workers-lib/-/zk-workers-lib-1.0.0.tgz","fileCount":22,"integrity":"sha512-4CwVrV0UtXW/IscVIj1v1aWnMVjoIda3AFwTVdm273Imas8u/CzaucPHhpGWBl4LsFHHmNBr23/jutiPGKm4Eg==","signatures":[{"sig":"MEQCIHdf1xLeF4y4gFxd7sivLXWqD5Uek1BmbZwKm7Nu14y9AiAo6HjRuIfbEhdzeYYQZBe1Exhz21IZqnMdxeL2m73YOQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":202687},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./transports/node":{"types":"./dist/transports/node/index.d.ts","import":"./dist/transports/node/index.js","require":"./dist/transports/node/index.cjs"},"./transports/cloudflare":{"types":"./dist/transports/cloudflare/index.d.ts","import":"./dist/transports/cloudflare/index.js"}},"gitHead":"6bbeacb5316d8020c4fb9c6479f1ded668953519","scripts":{"build":"tsup"},"_npmUser":{"name":"dev.itsak","email":"arun@ahopez.in"},"_npmVersion":"11.7.0","description":"A powerful, runtime-agnostic ZKTeco Biometric Device SDK for Node.js and Cloudflare Workers (raw TCP sockets).","directories":{},"_nodeVersion":"25.4.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/zk-workers-lib_1.0.0_1783618824948_0.46102887474373033","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@ahopez/zk-workers-lib","version":"1.0.1","keywords":["zkteco","biometric","fingerprint","attendance","cloudflare-workers","cloudflare-sockets","node","tcp","sdk"],"author":{"url":"https://github.com/AhopeZ-Innovations","name":"ArunKumar","email":"arun@ahopez.in"},"license":"MIT","_id":"@ahopez/zk-workers-lib@1.0.1","maintainers":[{"name":"dev.itsak","email":"arun@ahopez.in"}],"dist":{"shasum":"e9e67ff96b9ff5a787e40f55df06a50132c54628","tarball":"https://registry.npmjs.org/@ahopez/zk-workers-lib/-/zk-workers-lib-1.0.1.tgz","fileCount":22,"integrity":"sha512-NPqydkJ8RFvbZX1VKIKBYp/qXfWuqBhegaU5HLrRkDXun1nRCUlqdVYHm+xw5/DRT0z29RpVBwoPsRt8iD/WbQ==","signatures":[{"sig":"MEUCIDZl3i/OGaDe5Ckf0+N8J8eGAApRkPy4HVIZvV6FhHfxAiEA7NU8NUG2yexaxnk5PgX4tEiLkfOxu5iRlsSXDJnK2JM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":202651},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./transports/node":{"types":"./dist/transports/node/index.d.ts","import":"./dist/transports/node/index.js","require":"./dist/transports/node/index.cjs"},"./transports/cloudflare":{"types":"./dist/transports/cloudflare/index.d.ts","import":"./dist/transports/cloudflare/index.js"}},"gitHead":"d2098ab3a6ec35a1268fe338c06c14de03bcdadd","scripts":{"build":"tsup"},"_npmUser":{"name":"dev.itsak","email":"arun@ahopez.in"},"_npmVersion":"11.7.0","description":"A powerful, runtime-agnostic ZKTeco Biometric Device SDK for Node.js and Cloudflare Workers (raw TCP sockets).","directories":{},"_nodeVersion":"25.4.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/zk-workers-lib_1.0.1_1783619159849_0.0018939314824824027","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@ahopez/zk-workers-lib","version":"1.0.2","keywords":["zkteco","biometric","fingerprint","attendance","cloudflare-workers","cloudflare-sockets","node","tcp","sdk"],"author":{"url":"https://github.com/AhopeZ-Innovations","name":"ArunKumar","email":"arun@ahopez.in"},"license":"MIT","_id":"@ahopez/zk-workers-lib@1.0.2","maintainers":[{"name":"dev.itsak","email":"arun@ahopez.in"}],"homepage":"https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers#readme","bugs":{"url":"https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers/issues"},"dist":{"shasum":"e384dac49606d3c3cbb4ca2fed1dc1397d90331d","tarball":"https://registry.npmjs.org/@ahopez/zk-workers-lib/-/zk-workers-lib-1.0.2.tgz","fileCount":22,"integrity":"sha512-xoadh3BzJXbfGs1TkoQEWrYE4BDn7bxkTyIK3kg1NSg9SasU0OZrtD2RIOrRcgZEm8Hk4g/79OjDlAQ134+1SA==","signatures":[{"sig":"MEUCIHC409B25ON/R4uUN3L87Fdxf1SY2kehf2lRuLWUUCaNAiEAxsn6M7cthhJe6irDiRQz8aOkR/fPfeWKyGIiapDK6fQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":202967},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./transports/node":{"types":"./dist/transports/node/index.d.ts","import":"./dist/transports/node/index.js","require":"./dist/transports/node/index.cjs"},"./transports/cloudflare":{"types":"./dist/transports/cloudflare/index.d.ts","import":"./dist/transports/cloudflare/index.js"}},"gitHead":"f6f25328135009144b0ec35331075e9e97555c20","scripts":{"build":"tsup"},"_npmUser":{"name":"dev.itsak","email":"arun@ahopez.in"},"repository":{"url":"git+https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers.git","type":"git"},"_npmVersion":"11.7.0","description":"A powerful, runtime-agnostic ZKTeco Biometric Device SDK for Node.js and Cloudflare Workers (raw TCP sockets).","directories":{},"_nodeVersion":"25.4.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/zk-workers-lib_1.0.2_1783619497643_0.881832982892629","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@ahopez/zk-workers-lib","version":"1.0.3","keywords":["zkteco","biometric","fingerprint","attendance","cloudflare-workers","cloudflare-sockets","node","tcp","sdk"],"author":{"url":"https://github.com/AhopeZ-Innovations","name":"ArunKumar","email":"arun@ahopez.in"},"license":"MIT","_id":"@ahopez/zk-workers-lib@1.0.3","maintainers":[{"name":"dev.itsak","email":"arun@ahopez.in"}],"homepage":"https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers#readme","bugs":{"url":"https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers/issues"},"dist":{"shasum":"7e6ed4e8d32b611dd41247202e27dfac99ee951d","tarball":"https://registry.npmjs.org/@ahopez/zk-workers-lib/-/zk-workers-lib-1.0.3.tgz","fileCount":22,"integrity":"sha512-R3RqWy6edtPf+TKpdCCtFKt7sCs9pjLOcEde6/VPKY2aQdyDWDpXYyzNpzHAPrd9Znexq6VgO23+dFRDHQ+XOQ==","signatures":[{"sig":"MEQCIGM2Sbu7lZ4ecOk0l9Fg0gWDWApBgHtTqxQpmYTIo//2AiA30ngLEbgmAKn6tlQKYp0Fp+/a2jpmh10FJNyzYcOOvw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":203165},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./transports/node":{"types":"./dist/transports/node/index.d.ts","import":"./dist/transports/node/index.js","require":"./dist/transports/node/index.cjs"},"./transports/cloudflare":{"types":"./dist/transports/cloudflare/index.d.ts","import":"./dist/transports/cloudflare/index.js"}},"gitHead":"f6f25328135009144b0ec35331075e9e97555c20","scripts":{"build":"tsup"},"_npmUser":{"name":"dev.itsak","email":"arun@ahopez.in"},"repository":{"url":"git+https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers.git","type":"git"},"_npmVersion":"11.7.0","description":"A powerful, runtime-agnostic ZKTeco Biometric Device SDK for Node.js and Cloudflare Workers (raw TCP sockets).","directories":{},"_nodeVersion":"25.4.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.2","typescript":"^5.3.3","@types/node":"^20.11.0"},"_npmOperationalInternal":{"tmp":"tmp/zk-workers-lib_1.0.3_1783627639914_0.11550646842481238","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@ahopez/zk-workers-lib","version":"1.0.4","description":"A powerful, runtime-agnostic ZKTeco Biometric Device SDK for Node.js and Cloudflare Workers (raw TCP sockets).","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./transports/node":{"types":"./dist/transports/node/index.d.ts","import":"./dist/transports/node/index.js","require":"./dist/transports/node/index.cjs"},"./transports/cloudflare":{"types":"./dist/transports/cloudflare/index.d.ts","import":"./dist/transports/cloudflare/index.js"}},"scripts":{"build":"tsup"},"keywords":["zkteco","biometric","fingerprint","attendance","cloudflare-workers","cloudflare-sockets","node","tcp","sdk"],"author":{"name":"ArunKumar","email":"arun@ahopez.in","url":"https://github.com/AhopeZ-Innovations"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers.git"},"bugs":{"url":"https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers/issues"},"homepage":"https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers#readme","devDependencies":{"@types/node":"^20.11.0","tsup":"^8.0.2","typescript":"^5.3.3"},"gitHead":"a78bea3604eeb18eb6df2a33b61ab422c8ad22bb","_id":"@ahopez/zk-workers-lib@1.0.4","_nodeVersion":"25.4.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-mxcGLM70PUTmw9JBdd63G0XYa/ZxDOE/100IIxh+DSRDVZOOIeAKNfUpDY1lz4n3vcUyEFkjQwaZuJyEBskFzA==","shasum":"0e66e096a2e1165166573e470f46cc4bfd7283d6","tarball":"https://registry.npmjs.org/@ahopez/zk-workers-lib/-/zk-workers-lib-1.0.4.tgz","fileCount":22,"unpackedSize":203017,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCBc9/lDi9iziVXEQ2q1JFifbSfBeSeec8V/kO6hXQ0gwIgI/ih1CzAn8VGbgKyoav2HFaxxevJQlnpYibR4/Z+JQE="}]},"_npmUser":{"name":"dev.itsak","email":"arun@ahopez.in"},"directories":{},"maintainers":[{"name":"dev.itsak","email":"arun@ahopez.in"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zk-workers-lib_1.0.4_1783632491434_0.9210985786156543"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-09T17:40:24.779Z","modified":"2026-07-09T21:28:11.767Z","1.0.0":"2026-07-09T17:40:25.090Z","1.0.1":"2026-07-09T17:46:00.091Z","1.0.2":"2026-07-09T17:51:37.806Z","1.0.3":"2026-07-09T20:07:20.064Z","1.0.4":"2026-07-09T21:28:11.651Z"},"bugs":{"url":"https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers/issues"},"author":{"name":"ArunKumar","email":"arun@ahopez.in","url":"https://github.com/AhopeZ-Innovations"},"license":"MIT","homepage":"https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers#readme","keywords":["zkteco","biometric","fingerprint","attendance","cloudflare-workers","cloudflare-sockets","node","tcp","sdk"],"repository":{"type":"git","url":"git+https://github.com/AhopeZ-Innovations/zkteco-cloudflare-workers.git"},"description":"A powerful, runtime-agnostic ZKTeco Biometric Device SDK for Node.js and Cloudflare Workers (raw TCP sockets).","maintainers":[{"name":"dev.itsak","email":"arun@ahopez.in"}],"readme":"# @ahopez/zk-workers-lib\n\n[![npm version](https://badge.fury.io/js/%40ahopez%2Fzk-workers-lib.svg)](https://badge.fury.io/js/%40ahopez%2Fzk-workers-lib)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/node/v/%40ahopez%2Fzk-workers-lib.svg)](https://nodejs.org/)\n[![Downloads](https://img.shields.io/npm/dm/%40ahopez%2Fzk-workers-lib.svg)](https://www.npmjs.com/package/%40ahopez%2Fzk-workers-lib)\n\nA modern, **runtime-agnostic ZKTeco Biometric Device SDK** written in TypeScript. Decoupled from native platform modules, this SDK enables communication with physical biometric fingerprint scanners from both **Node.js** and edge-computing runtimes like **Cloudflare Workers**.\n\n---\n\n## ✨ Why This Package? (How It Differs)\n\nTraditional ZKTeco node packages (like `node-zklib` or `zklib-js`) are hardcoded to Node.js's native `net` and `dgram` socket modules. This tightly couples them to a standard server environment and prevents them from executing on edge networks.\n\n* 🌐 **Cloudflare Workers & Edge Support**: The first ZK SDK capable of running inside Cloudflare Workers using the native `cloudflare:sockets` TCP API.\n* 📦 **ESM & CommonJS Dual Bundling**: Full TypeScript support, pre-packaged with type declarations (`.d.ts`) and ESM/CJS exports.\n* 🔒 **Stateless Request Mutexing**: Solves socket dropouts (`STREAM_CLOSED_PREMATURELY`) and interleaving packet collisions by enforcing a thread-safe connection-per-request mutex lock pattern.\n* ⚡ **Zero External Dependencies**: Pure JS/TS implementation using native ArrayBuffer and DataView binary parsing for maximum performance.\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install @ahopez/zk-workers-lib\n```\n\n```bash\nyarn add @ahopez/zk-workers-lib\n```\n\n```bash\npnpm add @ahopez/zk-workers-lib\n```\n\n---\n\n## 🚀 Quick Start\n\n### 1. Node.js Integration\n```typescript\nimport { ZKClient, getUsers, getAttendances } from '@ahopez/zk-workers-lib';\nimport { NodeTransport } from '@ahopez/zk-workers-lib/transports/node';\n\nconst transport = new NodeTransport({ ip: '192.168.1.201', port: 4370, timeout: 10000 });\nconst client = new ZKClient(transport);\n\nasync function main() {\n  try {\n    await client.createSocket();\n    console.log('Connected to device!');\n\n    const users = await getUsers(client);\n    const logs = await getAttendances(client);\n\n    console.log(`Enrolled Users: ${users.length}`);\n    console.log(`Check-in Logs: ${logs.length}`);\n\n    await client.disconnect();\n  } catch (error) {\n    console.error('Connection failed:', error);\n  }\n}\n\nmain();\n```\n\n### 2. Cloudflare Workers Integration\n```typescript\nimport { ZKClient, getUsers } from '@ahopez/zk-workers-lib';\nimport { CloudflareTransport } from '@ahopez/zk-workers-lib/transports/cloudflare';\n\nexport default {\n  async fetch(request, env, ctx) {\n    const transport = new CloudflareTransport({ ip: '122.252.225.190', port: 4370, timeout: 10000 });\n    const client = new ZKClient(transport);\n\n    await client.createSocket();\n    const users = await getUsers(client);\n    await client.disconnect();\n\n    return new Response(JSON.stringify(users), {\n      headers: { 'Content-Type': 'application/json' }\n    });\n  }\n};\n```\n\n---\n\n## 📖 API Reference\n\n### Core Client Methods\n\n| Method | Parameters | Description |\n|--------|------------|-------------|\n| `new ZKClient(transport)` | `transport: ITransport` | Initializes the client with a transport adapter |\n| `createSocket()` | - | Connects to the device and establishes a session |\n| `disconnect()` | - | Closes the connection to the device |\n| `executeCmd()` | `command: number, data: Uint8Array \\| string` | Executes a raw ZK command code |\n\n### User Management\n\n| Method / Function | Parameters | Description |\n|--------|------------|-------------|\n| `getUsers(client)` | `client: ZKClient` | Retrieves all users from the device database |\n| `getUser(client, userId)` | `client: ZKClient, userId: string` | Finds a user by their User String ID |\n| `setUser(client, ...)` | `client, uid, userid, name, password?, role?, cardno?` | Creates or updates a user on the device |\n| `deleteUser(client, uid)` | `client: ZKClient, uid: number` | Deletes a user profile from the device |\n\n### Biometric Management\n\n| Function / Method | Parameters | Description |\n|--------|------------|-------------|\n| `getUserTemplate(client, ...)` | `client, uid, fingerIndex` | Reads a specific fingerprint template of a user |\n| `getAllTemplates(client)` | `client: ZKClient` | Downloads all fingerprint templates inside device memory |\n| `client.enrollFingerprint(...)` | `userId: string, fingerIndex: number` | Wakes up the scanner to enroll a specific finger (0-9) |\n\n### Attendance Records\n\n| Function | Parameters | Description |\n|--------|------------|-------------|\n| `getAttendances(client, cb?)` | `client, cb?` | Reads all attendance records from device memory |\n| `clearAttendanceLog(client)` | `client` | Wipes attendance log records from the storage chip |\n\n### Device Maintenance & Option Controls\n\n| Function | Parameters | Description |\n|--------|------------|-------------|\n| `getInfo(client)` | `client` | Retrieves storage capacity details and count metrics |\n| `getTime(client)` | `client` | Reads the current local time of the device clock |\n| `setTime(client, date)` | `client, date: Date` | Sets the device's clock to the specified date-time |\n| `getOption(client, keyword)` | `client, keyword: string` | Reads a hardware option parameter (e.g., `IPAddress`, `NetMask`) |\n| `voiceTest(client)` | `client` | Plays the device's hardware test sound |\n| `clearData(client)` | `client` | Clears user and template databases |\n| `refreshData(client)` | `client` | Commits changes and flushes device memory |\n| `freeData(client)` | `client` | Frees device transmission buffers |\n\n---\n\n## 💡 Examples\n\n### User Registration & Role Configuration\n```typescript\nimport { ZKClient, setUser } from '@ahopez/zk-workers-lib';\nimport { NodeTransport } from '@ahopez/zk-workers-lib/transports/node';\n\nconst client = new ZKClient(new NodeTransport({ ip: '192.168.1.201' }));\nawait client.createSocket();\n\n// Set user 'John Doe' as an Administrator (role code 14)\nawait setUser(\n  client,\n  2,           // Unique numeric UID\n  'EMP102',    // String User ID\n  'John Doe',  // Name\n  '',          // Password\n  14,          // Role code (0: User, 14: Admin)\n  123456       // RFID Card Number\n);\n\nawait client.disconnect();\n```\n\n### Remote Fingerprint Enrollment Flow\nEnrolls a user's right index finger (index 1) remotely from the dashboard:\n```typescript\nimport { ZKClient } from '@ahopez/zk-workers-lib';\nimport { NodeTransport } from '@ahopez/zk-workers-lib/transports/node';\n\nconst client = new ZKClient(new NodeTransport({ ip: '192.168.1.201' }));\nawait client.createSocket();\n\n// Put device in enroll mode: stops capturing, sets target parameters, prompts verify scan\nawait client.enrollFingerprint('EMP102', 1);\n\n// Device speaker will speak \"Please press your finger\". User scans 3 times.\nawait client.disconnect();\n```\n\n---\n\n## 🔧 Configuration\n\n### Pluggable Transport Construction\n\nChoose the transport layer matching your runtime environment:\n\n```typescript\n// For Node.js (CommonJS or ESM)\nnew NodeTransport({ ip, port, timeout })\n\n// For Cloudflare Workers (ESM)\nnew CloudflareTransport({ ip, port, timeout })\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `ip` | string | - | Biometric device IP address (required) |\n| `port` | number | `4370` | Connection port |\n| `timeout` | number | `10000` | Connection socket timeout in milliseconds |\n\n---\n\n## 🤝 Contributing\n\nThis repository is closed to external contributions. Pull requests and contributions are not accepted.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n---\n\n**Author:** [ArunKumar](https://github.com/AhopeZ-Innovations)  \n**Email:** arun@ahopez.in\n","readmeFilename":"README.md"}