zklib-ts 1.0.0-development

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Gustavo Paz <gusti.paz@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+<h1 align="center">zklib ts</h1>
+<p align="center">An unofficial library that provides a robust solution for Node.js developers to interface with ZKTeco Devices.</p>
+<p align="center">
+    <img src="https://img.shields.io/badge/node-latest-green?style=flat-square"/>
+    <img src="https://img.shields.io/badge/TypeScript-latest-blue?style=flat-square"/>
+    <img src="https://img.shields.io/badge/Jest-latest-red?style=flat-square"/>
+    <img src="https://img.shields.io/badge/npm-red?style=flat-square"/>
+</p>
+<p align="center">
+    <b style="color:red;">Disclaimer</b>
+    <b>⚠️ This repository is not recommended for use in production. ⚠️</b>
+    This repository is currently in development and may contain bugs or incomplete features. Use at your own risk and do not deploy to a production environment
+</p>
+
+## 📋 **Index**
+1. [⚙️ Usage](#-usage)
+2. [🛠️ Testing](#-testing)
+3. [🗄️Alternatives](#-alternatives)
+4. [📄 Documentation](#-documentation)
+
+## 🛠️ **Usage**
+create a connection. <b>constructor</b> receives `(ip, timeout, inport, port, comm_key) `
+```js
+import Zklib from 'zklib'
+
+const zkInstance = new Zklib("10.0.0.10",10000,10000,4370,0)
+
+await zkInstance.createSocket()
+
+```
+Get <b>all</b> users:
+```js
+
+const users = await zkInstance.getUsers()
+
+```
+Get <b>all</b> attendances:
+```js
+
+const attendances = await zkInstance.getAttendances()
+
+```
+get All templates
+```js
+const templates = await zkInstance.getTemplates() 
+```
+
+save user templates. receives a `User` instance class and an array of `Finger` class. currently only save one template per call.
+```js
+const templates = await zkInstance.saveUserTemplate(user, templates) 
+```
+
+
+enrollUser: receives a user `user_id` and finger ID `fid` where `0 <= fid <= 9`
+```js
+await zkInstance.enrollUser(50,5)
+```
+delete template. receives user id `uid` and finger id where `0 <= fid <= 9`
+```js
+await zkInstance.deleteTemplate(50,5)
+```
+<b>Check the Testing section for more functionalities coverage.</b>
+
+## 🛠️ **Testing**
+
+The repo uses Jest. There is a mock file for test without having a phisical device connected.
+
+for testing your phisical device first create .env file in root directory with the values down below:
+```
+DEVICE_IP=10.10.10.1
+DEVICE_PORT=4370
+DEVICE_PASSWORD=1234
+```
+and then run tests:
+```
+npm t
+```
+
+for testing especific file after "npm t" type some name that matches a test file ...
+for example the next command will execute "Generic.test.ts"
+```
+npm t Generic
+```
+
+## 🗄️ **Alternatives**
+#### Javascript
+- [caobo171/node-zklib](https://github.com/caobo171/node-zklib)
+- [conding-libs/zkteco-js](https://github.com/coding-libs/zkteco-js)
+#### Python:
+- [dnaextrim/python_zklib](https://github.com/dnaextrim/python_zklib)
+- [fananimi/pyzk](https://github.com/fananimi/pyzk)
+#### ☕ Java:
+- [mkhoudary/ZKTeco4J](https://github.com/mkhoudary/ZKTeco4J)
+
+## 📄 **Documentation**
+- [adrobinoga/zk-protocol](https://github.com/adrobinoga/zk-protocol)
+
+
+## License
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

package/dist/exceptions/handler.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Error types for device communication
+ */
+export declare const ERROR_TYPES: {
+    readonly ECONNRESET: "ECONNRESET";
+    readonly ECONNREFUSED: "ECONNREFUSED";
+    readonly EADDRINUSE: "EADDRINUSE";
+    readonly ETIMEDOUT: "ETIMEDOUT";
+};
+type ErrorType = keyof typeof ERROR_TYPES;
+interface ErrorInfo {
+    message: string;
+    code?: ErrorType | string;
+}
+interface ZkErrorDetails {
+    err: {
+        message: string;
+        code?: string;
+    };
+    ip: string;
+    command: string | number;
+}
+/**
+ * Custom error class for device communication errors
+ */
+export declare class ZkError {
+    private err;
+    private ip;
+    private command;
+    /**
+     * Creates a new ZkError instance
+     * @param err The error object
+     * @param command The command that caused the error
+     * @param ip The IP address of the device
+     */
+    constructor(err: ErrorInfo, command: number | string, ip: string);
+    /**
+     * Gets a user-friendly error message
+     * @returns A formatted error message
+     */
+    toast(): string;
+    /**
+     * Gets detailed error information
+     * @returns An object containing error details
+     */
+    getError(): ZkErrorDetails;
+}
+declare const _default: {
+    ZkError: typeof ZkError;
+    ERROR_TYPES: {
+        readonly ECONNRESET: "ECONNRESET";
+        readonly ECONNREFUSED: "ECONNREFUSED";
+        readonly EADDRINUSE: "EADDRINUSE";
+        readonly ETIMEDOUT: "ETIMEDOUT";
+    };
+};
+export default _default;

package/dist/helper/command.d.ts

@@ -0,0 +1,110 @@
+export declare const COMMANDS: {
+    readonly CMD_CONNECT: 1000;
+    readonly CMD_EXIT: 1001;
+    readonly CMD_ENABLEDEVICE: 1002;
+    readonly CMD_DISABLEDEVICE: 1003;
+    readonly CMD_RESTART: 1004;
+    readonly CMD_POWEROFF: 1005;
+    readonly CMD_SLEEP: 1006;
+    readonly CMD_RESUME: 1007;
+    readonly CMD_CAPTUREFINGER: 1009;
+    readonly CMD_TEST_TEMP: 1011;
+    readonly CMD_CAPTUREIMAGE: 1012;
+    readonly CMD_REFRESHDATA: 1013;
+    readonly CMD_REFRESHOPTION: 1014;
+    readonly CMD_TESTVOICE: 1017;
+    readonly CMD_GET_VERSION: 1100;
+    readonly CMD_CHANGE_SPEED: 1101;
+    readonly CMD_AUTH: 1102;
+    readonly CMD_PREPARE_DATA: 1500;
+    readonly CMD_DATA: 1501;
+    readonly CMD_FREE_DATA: 1502;
+    readonly CMD_DATA_WRRQ: 1503;
+    readonly CMD_DATA_RDY: 1504;
+    readonly CMD_DB_RRQ: 7;
+    readonly CMD_USER_WRQ: 8;
+    readonly CMD_USERTEMP_RRQ: 9;
+    readonly CMD_USERTEMP_WRQ: 10;
+    readonly CMD_OPTIONS_RRQ: 11;
+    readonly CMD_OPTIONS_WRQ: 12;
+    readonly CMD_ATTLOG_RRQ: 13;
+    readonly CMD_CLEAR_DATA: 14;
+    readonly CMD_CLEAR_ATTLOG: 15;
+    readonly CMD_DELETE_USER: 18;
+    readonly CMD_DELETE_USERTEMP: 19;
+    readonly CMD_CLEAR_ADMIN: 20;
+    readonly CMD_USERGRP_RRQ: 21;
+    readonly CMD_USERGRP_WRQ: 22;
+    readonly CMD_USERTZ_RRQ: 23;
+    readonly CMD_USERTZ_WRQ: 24;
+    readonly CMD_GRPTZ_RRQ: 25;
+    readonly CMD_GRPTZ_WRQ: 26;
+    readonly CMD_TZ_RRQ: 27;
+    readonly CMD_TZ_WRQ: 28;
+    readonly CMD_ULG_RRQ: 29;
+    readonly CMD_ULG_WRQ: 30;
+    readonly CMD_UNLOCK: 31;
+    readonly CMD_CLEAR_ACC: 32;
+    readonly CMD_CLEAR_OPLOG: 33;
+    readonly CMD_OPLOG_RRQ: 34;
+    readonly CMD_GET_FREE_SIZES: 50;
+    readonly CMD_ENABLE_CLOCK: 57;
+    readonly CMD_STARTVERIFY: 60;
+    readonly CMD_STARTENROLL: 61;
+    readonly CMD_CANCELCAPTURE: 62;
+    readonly CMD_STATE_RRQ: 64;
+    readonly CMD_WRITE_LCD: 66;
+    readonly CMD_CLEAR_LCD: 67;
+    readonly CMD_GET_PINWIDTH: 69;
+    readonly CMD_SMS_WRQ: 70;
+    readonly CMD_SMS_RRQ: 71;
+    readonly CMD_DELETE_SMS: 72;
+    readonly CMD_UDATA_WRQ: 73;
+    readonly CMD_DELETE_UDATA: 74;
+    readonly CMD_DOORSTATE_RRQ: 75;
+    readonly CMD_WRITE_MIFARE: 76;
+    readonly CMD_EMPTY_MIFARE: 78;
+    readonly CMD_VERIFY_WRQ: 79;
+    readonly CMD_VERIFY_RRQ: 80;
+    readonly CMD_TMP_WRITE: 87;
+    readonly CMD_GET_USERTEMP: 88;
+    readonly CMD_CHECKSUM_BUFFER: 119;
+    readonly CMD_DEL_FPTMP: 134;
+    readonly CMD_GET_TIME: 201;
+    readonly CMD_SET_TIME: 202;
+    readonly CMD_REG_EVENT: 500;
+    readonly CMD_ACK_OK: 2000;
+    readonly CMD_ACK_ERROR: 2001;
+    readonly CMD_ACK_DATA: 2002;
+    readonly CMD_ACK_RETRY: 2003;
+    readonly CMD_ACK_REPEAT: 2004;
+    readonly CMD_ACK_UNAUTH: 2005;
+    readonly CMD_ACK_UNKNOWN: 65535;
+    readonly CMD_ACK_ERROR_CMD: 65533;
+    readonly CMD_ACK_ERROR_INIT: 65532;
+    readonly CMD_ACK_ERROR_DATA: 65531;
+    readonly EF_ATTLOG: 1;
+    readonly EF_FINGER: 2;
+    readonly EF_ENROLLUSER: 4;
+    readonly EF_ENROLLFINGER: 8;
+    readonly EF_BUTTON: 16;
+    readonly EF_UNLOCK: 32;
+    readonly EF_VERIFY: 128;
+    readonly EF_FPFTR: 256;
+    readonly EF_ALARM: 512;
+};
+export type CommandKeys = keyof typeof COMMANDS;
+export type CommandValues = typeof COMMANDS[CommandKeys];
+export declare const USHRT_MAX: number;
+export declare const MAX_CHUNK: number;
+export declare const MACHINE_PREPARE_DATA_1: number;
+export declare const MACHINE_PREPARE_DATA_2: number;
+interface RequestData {
+    DISABLE_DEVICE: Buffer;
+    GET_REAL_TIME_EVENT: Buffer;
+    GET_ATTENDANCE_LOGS: Buffer;
+    GET_USERS: Buffer;
+    GET_TEMPLATES: Buffer;
+}
+export declare const REQUEST_DATA: RequestData;
+export {};

package/dist/helper/models/Attendance.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents an Attendance Records
+ */
+export declare class Attendance {
+    private sn;
+    private user_id;
+    private record_time;
+    private type?;
+    private state?;
+    private ip?;
+    constructor(sn: number, user_id: string, record_time: Date, type?: number, state?: number);
+}

package/dist/helper/models/Finger.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Represents a fingerprint template with associated metadata
+ */
+export declare class Finger {
+    uid: number;
+    fid: number;
+    valid: number;
+    template: Buffer;
+    size: number;
+    readonly mark: string;
+    /**
+     * Creates a new Finger instance
+     * @param uid User internal reference
+     * @param fid Finger ID (value >= 0 && value <= 9)
+     * @param valid Flag indicating 0 = invalid | 1 = valid | 3 = duress
+     * @param template Fingerprint template data buffer
+     */
+    constructor(uid: number, fid: number, valid: number, template: Buffer);
+    /**
+     * Packs the fingerprint data with metadata into a Buffer
+     * @returns Buffer containing packed fingerprint data
+     */
+    repack(): Buffer;
+    /**
+     * Packs only the fingerprint template data into a Buffer
+     * @returns Buffer containing just the template data
+     */
+    repackOnly(): Buffer;
+    /**
+     * Compares this fingerprint with another for equality
+     * @param other Another Finger instance to compare with
+     * @returns true if all properties and template data match
+     */
+    equals(other: Finger): boolean;
+}

package/dist/helper/models/User.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Represents a User as is from ZkDevice and contain methods
+ * */
+export declare class User {
+    uid: number;
+    name: string;
+    privilege: number;
+    password: string;
+    group_id: string | number;
+    user_id: string;
+    card: number;
+    /**
+     * Creates a new User instance
+     * @param uid User ID
+     * @param name User name
+     * @param privilege Privilege level
+     * @param password User password (default: "")
+     * @param group_id Group ID (default: "")
+     * @param user_id Alternate user ID (default: "")
+     * @param card Card number (default: 0)
+     */
+    constructor(uid: number, name: string, privilege: number, password?: string, group_id?: string | number, user_id?: string, card?: number);
+    private ensureEncoding;
+    repack29(): Buffer;
+    repack73(): Buffer;
+}

package/dist/helper/time.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    encode: (date: any) => any;
+    decode: (time: any) => Date;
+};
+export default _default;

package/dist/helper/utils.d.ts

@@ -0,0 +1,40 @@
+import { User } from '../models/User';
+import { Attendance } from "../models/Attendance";
+export interface DeviceInfo {
+    userCounts: number;
+    logCounts: number;
+    logCapacity: number;
+}
+export type UserData28 = Omit<User, 'password' | 'group_id' | 'card' | 'repack29' | 'repack73'>;
+export interface RecordData16 {
+    record_time: Date;
+    user_id: string;
+    ip?: string;
+}
+export type RealTimeLog = RecordData16;
+interface UDPHeader {
+    commandId: number;
+    checkSum: number;
+    sessionId: number;
+    replyId: number;
+}
+interface TCPHeader extends UDPHeader {
+    payloadSize: number;
+}
+export declare const createUDPHeader: (command: number, sessionId: number, replyId: number, data: any) => Buffer;
+export declare const createTCPHeader: (command: number, sessionId: number, replyId: number, data: any) => Buffer;
+export declare const removeTcpHeader: (buf: Buffer) => Buffer;
+export declare const parseTimeToDate: (time: number) => Date;
+export declare const decodeUserData28: (userData: Buffer) => UserData28;
+export declare const decodeUserData72: (userData: Buffer) => User;
+export declare const decodeRecordData40: (recordData: Buffer) => Attendance;
+export declare const decodeRecordData16: (recordData: Buffer) => RecordData16;
+export declare const decodeRecordRealTimeLog18: (recordData: Buffer) => RealTimeLog;
+export declare const decodeRecordRealTimeLog52: (recordData: Buffer) => RealTimeLog;
+export declare const decodeUDPHeader: (header: Buffer) => UDPHeader;
+export declare const decodeTCPHeader: (header: Buffer) => TCPHeader;
+export declare const exportErrorMessage: (commandValue: number) => string;
+export declare const checkNotEventTCP: (data: Buffer) => boolean;
+export declare const checkNotEventUDP: (data: Buffer) => boolean;
+export declare const authKey: (comKey: number, sessionId: number) => number[];
+export {};