@tbsoft-gmbh/signature-sdk 1.0.0

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\r\n * Type definitions for the Signotec Pad SDK.\r\n * @module types\r\n */\r\n\r\n// ─── Device Info ───────────────────────────────────────────────────────────────\r\n\r\n/** Information about a connected Signotec signing pad. */\r\nexport type DeviceInfo = {\r\n  /** Unique identifier (serial number or device path fallback). */\r\n  serialNo: string;\r\n  /** Device type code (see DEVICE_TYPE_MAPPINGS). */\r\n  type: number;\r\n  /** Human-readable device model name. */\r\n  name: string;\r\n  /** Manufacturer name (always \"Signotec\"). */\r\n  vendor: string;\r\n};\r\n\r\n/** Map of device type codes to human-readable model names. */\r\nexport const DEVICE_TYPE_MAPPINGS: Record<number, string> = {\r\n  1: \"Sigma USB\", 2: \"Sigma seriell\",\r\n  5: \"Zeta USB\", 6: \"Zeta seriell\",\r\n  11: \"Omega USB\", 12: \"Omega seriell\",\r\n  15: \"Gamma USB\", 16: \"Gamma seriell\",\r\n  21: \"Delta USB\", 22: \"Delta seriell\", 23: \"Delta IP\",\r\n  31: \"Alpha USB\", 32: \"Alpha seriell\", 33: \"Alpha IP\",\r\n};\r\n\r\n// ─── Callback Handlers ─────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Handler for user-initiated events (confirm/cancel) from the signing pad.\r\n * @param event - \"confirm\" when signature accepted, \"cancel\" when cancelled\r\n * @param data - Contains serialNo and base64 PNG image (on confirm)\r\n */\r\nexport type SignatureEventHandler = {\r\n  (event: \"cancel\", data: { serialNo: string }): void;\r\n  (event: \"confirm\", data: { serialNo: string; base64Img: string }): void;\r\n};\r\n\r\n/**\r\n * Handler for real-time signature data streaming.\r\n * @param event - \"liveData\" for each pen point, \"clear\" when signature cleared (retry)\r\n * @param data - Contains point coordinates (x, y) and serialNo\r\n */\r\nexport type SignatureEventHandlerLive = {\r\n  (event: \"liveData\", data: { point: { x: number; y: number; pressure?: number }; serialNo: string }): void;\r\n  (event: \"clear\", data: { serialNo: string }): void;\r\n};\r\n\r\n/** Combined callback handlers for a signing session. */\r\nexport type SignatureCallbackHandlers = {\r\n  /** Fires on user actions: confirm (with signature image) or cancel. */\r\n  onUserEvent: SignatureEventHandler;\r\n  /** Fires on pen movement (liveData) or signature clear (retry). */\r\n  onSignatureData: SignatureEventHandlerLive;\r\n};\r\n\r\n// ─── Display Configuration ─────────────────────────────────────────────────────\r\n\r\n/** A single line of text displayed on the signing pad. */\r\nexport type DisplayLine = {\r\n  /** Label prefix (e.g., \"LFS:\", \"Kunde:\"). */\r\n  label: string;\r\n  /** Content value displayed after the label. */\r\n  content: string | number;\r\n  /** Font scale factor (1 = tiny 5x7, 2 = normal, 3 = large). Default: 2 */\r\n  fontSize?: number;\r\n};\r\n\r\n/** Content displayed on the signing pad during a session. */\r\nexport type SignatureDisplayData = {\r\n  /** Main content area (up to 4 lines, displayed below buttons). */\r\n  body?: {\r\n    line1?: DisplayLine | null;\r\n    line2?: DisplayLine | null;\r\n    line3?: DisplayLine | null;\r\n    line4?: DisplayLine | null;\r\n  } | null;\r\n  /** Footer area (up to 2 lines, displayed at bottom). */\r\n  footer?: {\r\n    line1?: DisplayLine | null;\r\n    line2?: DisplayLine | null;\r\n  } | null;\r\n};\r\n\r\n// ─── Output Configuration ───────────────────────────────────────────────────────\r\n\r\n/** Options for the rendered signature image output. */\r\nexport type SignatureOutputOptions = {\r\n  /** Pen stroke width in pixels. Default: 2 */\r\n  strokeWidth?: number;\r\n  /** Output image dimensions. Default: 400x200 */\r\n  imageSize?: { width: number; height: number };\r\n  /** DPI resolution for the output image. Default: 300 */\r\n  resolution?: number;\r\n};\r\n\r\n/** Options passed to startSigningProcess. */\r\nexport type StartSignatureOptions = {\r\n  /** Text content to display on the pad during signing. */\r\n  displayData: SignatureDisplayData;\r\n  /** Configuration for the rendered signature image. */\r\n  outputOptions?: SignatureOutputOptions;\r\n};\r\n\r\n// ─── Driver Configuration ───────────────────────────────────────────────────────\r\n\r\n/**\r\n * Configuration for the HID driver.\r\n * Tune timeouts for slow USB-over-IP connections.\r\n *\r\n * @example\r\n * ```typescript\r\n * // For USB-over-IP with high latency:\r\n * const driver = createHidDriver({\r\n *   commandTimeout: 5000,\r\n *   chunkDelayMs: 10,\r\n *   maxRetries: 3,\r\n * });\r\n * ```\r\n */\r\nexport type DriverConfig = {\r\n  /** Timeout for simple HID commands (ms). Default: 3000 */\r\n  commandTimeout?: number;\r\n  /** Timeout for image transfer operations (ms). Default: 15000 */\r\n  imageTransferTimeout?: number;\r\n  /** Timeout for flash store operations (ms). Default: 25000 */\r\n  flashStoreTimeout?: number;\r\n  /** Delay between data chunks during image transfer (ms). Default: 2.\r\n   *  Increase for slow USB-over-IP connections. */\r\n  chunkDelayMs?: number;\r\n  /** Max retry attempts for failed HID commands. Default: 2 */\r\n  maxRetries?: number;\r\n  /** Max reconnection attempts after device disconnect. Default: 10 */\r\n  reconnectAttempts?: number;\r\n  /** Delay between reconnection attempts (ms). Default: 2000 */\r\n  reconnectIntervalMs?: number;\r\n  /** Logger instance. Defaults to console. Set to null to suppress logs. */\r\n  logger?: Logger | null;\r\n  /**\r\n   * Optional event callback for driver lifecycle events.\r\n   * Receives structured events for logging to Grafana/Loki/external systems.\r\n   * Called for: session start/end, errors, warnings, USB diagnostics.\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * configure({\r\n   *   onDriverEvent: (event) => {\r\n   *     grafanaLogger.log(event.level, event.message, event.data);\r\n   *   }\r\n   * });\r\n   * ```\r\n   */\r\n  onDriverEvent?: (event: DriverEvent) => void;\r\n};\r\n\r\n/** Structured event emitted by the driver for external logging/monitoring. */\r\nexport type DriverEvent = {\r\n  /** Event severity level. */\r\n  level: \"info\" | \"warn\" | \"error\";\r\n  /** Human-readable event description. */\r\n  message: string;\r\n  /** Event category for filtering. */\r\n  category: \"session\" | \"device\" | \"usb\" | \"display\" | \"signature\" | \"flash\";\r\n  /** Optional structured data payload. */\r\n  data?: Record<string, unknown>;\r\n  /** ISO timestamp. */\r\n  timestamp: string;\r\n};\r\n\r\n/** Minimal logger interface (compatible with console, electron-log, winston, etc.) */\r\nexport interface Logger {\r\n  info(...args: any[]): void;\r\n  warn(...args: any[]): void;\r\n  error(...args: any[]): void;\r\n  debug?(...args: any[]): void;\r\n}\r\n\r\n// ─── Driver Interface ───────────────────────────────────────────────────────────\r\n\r\n/** The public API for the Signotec Pad SDK. */\r\nexport interface PadDriver {\r\n  /**\r\n   * Get all connected Signotec signing pads.\r\n   * Returns empty array if no devices found (does NOT throw).\r\n   */\r\n  getSignotecPads(): DeviceInfo[];\r\n\r\n  /**\r\n   * Start a signature capture session on the specified pad.\r\n   * Draws the signing UI (buttons + text), configures hotspots, starts capture.\r\n   *\r\n   * @param serialNo - Serial number of the target pad (from getSignotecPads)\r\n   * @param handlers - Callback handlers for user events and live signature data\r\n   * @param options - Display content and output configuration\r\n   * @throws Error if device cannot be opened or signing session fails to start\r\n   */\r\n  startSigningProcess(\r\n    serialNo: string,\r\n    handlers: SignatureCallbackHandlers,\r\n    options: StartSignatureOptions\r\n  ): Promise<void>;\r\n\r\n  /**\r\n   * Cancel the current signing session.\r\n   * Fires the 'cancel' user event, restores standby display, closes device.\r\n   */\r\n  cancelSignature(): { status: boolean; message: string };\r\n\r\n  /**\r\n   * Confirm the current signature.\r\n   * Renders signature as PNG, fires 'confirm' with base64 image, restores standby.\r\n   * @throws Error if no active signing session\r\n   */\r\n  confirmSignature(): void;\r\n\r\n  /**\r\n   * Skip signature and continue without one.\r\n   * Fires 'confirm' with empty base64Img.\r\n   */\r\n  continueWithoutSignature(): Promise<{ status: boolean; message: string }>;\r\n\r\n  /**\r\n   * Store a standby image to the pad's flash memory.\r\n   * The image persists across power cycles and USB disconnects.\r\n   * After each signing session, the standby is automatically restored via 0x8A.\r\n   *\r\n   * @param imagePath - Path to PNG or BMP image (320x160 for Sigma pads), or null to clear\r\n   * @returns true if stored successfully\r\n   */\r\n  setStandbyImage(imagePath: string | null): Promise<boolean>;\r\n\r\n  /**\r\n   * Wait for a Signotec pad to be connected.\r\n   * Polls USB bus until a device appears or timeout expires.\r\n   *\r\n   * @param timeoutMs - Maximum wait time in milliseconds. Default: 30000\r\n   * @returns DeviceInfo of the first device found, or null on timeout\r\n   */\r\n  waitForDevice?(timeoutMs?: number): Promise<DeviceInfo | null>;\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAoBO,IAAM,uBAA+C;AAAA,EAC1D,GAAG;AAAA,EAAa,GAAG;AAAA,EACnB,GAAG;AAAA,EAAY,GAAG;AAAA,EAClB,IAAI;AAAA,EAAa,IAAI;AAAA,EACrB,IAAI;AAAA,EAAa,IAAI;AAAA,EACrB,IAAI;AAAA,EAAa,IAAI;AAAA,EAAiB,IAAI;AAAA,EAC1C,IAAI;AAAA,EAAa,IAAI;AAAA,EAAiB,IAAI;AAC5C;","names":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@tbsoft-gmbh/signature-sdk",
+    "version": "1.0.0",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist",
+        "udev"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "prepare": "npm run build",
+        "test": "node tests/test-signing-flow.js"
+    },
+    "author": "Marius Klingl",
+    "license": "ISC",
+    "description": "A cross-platform library for direct access to signotec devices. Supports Windows, Linux, and macOS.",
+    "keywords": [
+        "signotec",
+        "typescript",
+        "signature",
+        "device-api",
+        "usb",
+        "hid"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "node-hid": "^3.1.0"
+    },
+    "optionalDependencies": {
+        "usb": "^2.17.0"
+    },
+    "devDependencies": {
+        "cpy-cli": "^5.0.0",
+        "ts-node": "^10.9.2",
+        "tsup": "^8.5.0",
+        "typescript": "^5.8.3"
+    }
+}

package/udev/99-signotec.rules

@@ -0,0 +1,10 @@
+# Signotec signing pad - allow non-root HID and USB access
+# Install: sudo cp 99-signotec.rules /etc/udev/rules.d/
+# Reload: sudo udevadm control --reload-rules && sudo udevadm trigger
+# Then reconnect the USB device.
+
+# Signotec pads (VID 0x2133) - HID access (node-hid)
+SUBSYSTEM=="hidraw", ATTRS{idVendor}=="2133", MODE="0666", GROUP="plugdev", TAG+="uaccess"
+
+# Signotec pads (VID 0x2133) - raw USB access (libusb fallback)
+SUBSYSTEM=="usb", ATTRS{idVendor}=="2133", MODE="0666", GROUP="plugdev", TAG+="uaccess"