smartcard 2.0.0 → 2.0.2

package/README.md

@@ -1,42 +1,108 @@
 # smartcard
 
-Modern PC/SC (Personal Computer/Smart Card) bindings for Node.js using N-API.
+```
+╭────────────────────────────────────────╮
+│                                        │
+│   ╭───────────╮                        │
+│   │ ▄▄▄ ▄▄▄▄▄ │                        │
+│   │ ███ ▄▄▄▄▄ │                        │
+│   │ ▀▀▀ ▀▀▀▀▀ │                        │
+│   ╰───────────╯                        │
+│                                        │
+│                          ░░░░░░░░░░░░  │
+│                          ░░░░░░░░░░░░  │
+╰────────────────────────────────────────╯
+```
 
-Unlike older NAN-based bindings that break with each Node.js major version, this library uses N-API for ABI stability across Node.js versions 12, 14, 16, 18, 20, 22, 24, and beyond - without recompilation.
+Stable PC/SC smart card bindings for Node.js.
 
-## Features
+Works with Node.js 12+ without recompilation. Built on N-API for long-term stability.
 
-- **ABI Stable**: Works across Node.js versions without recompilation
-- **Async/Promise-based**: Non-blocking card operations
-- **Event-driven API**: High-level `Devices` class with EventEmitter
-- **TypeScript support**: Full type definitions included
-- **Cross-platform**: Windows, macOS, and Linux
+## Getting Started
 
-## Installation
+### 1. Install the package
 
 ```bash
 npm install smartcard
 ```
 
-### Prerequisites
-
-**macOS**: No additional setup required (uses built-in PCSC.framework)
+### 2. Platform setup
 
-**Windows**: No additional setup required (uses built-in winscard.dll)
+**macOS/Windows**: Ready to go - no additional setup needed.
 
 **Linux**:
 ```bash
-# Debian/Ubuntu
-sudo apt-get install libpcsclite-dev pcscd
+# Install PC/SC libraries
+sudo apt-get install libpcsclite-dev pcscd   # Debian/Ubuntu
+sudo dnf install pcsc-lite-devel pcsc-lite   # Fedora/RHEL
 
-# Fedora/RHEL
-sudo dnf install pcsc-lite-devel pcsc-lite
-
-# Start the PC/SC daemon
+# Start the daemon
 sudo systemctl start pcscd
 ```
 
-## Quick Start
+### 3. Connect a reader and run your first script
+
+```javascript
+const { Devices } = require('smartcard');
+
+const devices = new Devices();
+
+devices.on('card-inserted', async ({ reader, card }) => {
+    console.log(`Card detected in ${reader.name}`);
+    console.log(`ATR: ${card.atr.toString('hex')}`);
+
+    // Get card UID (works with most contactless cards)
+    const response = await card.transmit([0xFF, 0xCA, 0x00, 0x00, 0x00]);
+    console.log(`UID: ${response.slice(0, -2).toString('hex')}`);
+});
+
+devices.on('error', (err) => console.error(err.message));
+
+devices.start();
+```
+
+Run it:
+```bash
+node app.js
+# Tap a card on your reader...
+# Card detected in ACS ACR122U
+# ATR: 3b8f8001804f0ca0000003060300030000000068
+# UID: 04a23b7a
+```
+
+## Recommended Hardware
+
+### Readers
+
+| Reader | Type | Notes |
+|--------|------|-------|
+| **ACR122U** | USB contactless | Affordable, widely available. Great for getting started. |
+| **ACR1252U** | USB dual-interface | Supports both contactless and contact cards. |
+| **SCM SCR35xx** | USB contact | Tested with SCR35xx v2.0. Good for contact smart cards. |
+| **HID Omnikey 5427** | USB contactless | Enterprise-grade, faster reads. |
+| **Identiv uTrust 3700F** | USB contactless | Compact, reliable. |
+
+Any PC/SC compatible reader should work. The library uses standard PC/SC APIs.
+
+### Cards
+
+| Card Type | Interface | Notes |
+|-----------|-----------|-------|
+| MIFARE Classic 1K/4K | Contactless | Most common NFC cards |
+| MIFARE Ultralight / NTAG | Contactless | Stickers, wristbands, keyfobs |
+| MIFARE DESFire | Contactless | Higher security applications |
+| ISO 14443-4 | Contactless | Generic contactless smart cards |
+| ISO 7816 | Contact | Standard contact smart cards (SIM, bank cards, ID cards) |
+
+## Features
+
+- **ABI Stable**: Works across Node.js versions without recompilation
+- **Async/Promise-based**: Non-blocking card operations
+- **Event-driven API**: High-level `Devices` class with EventEmitter
+- **TypeScript support**: Full type definitions included
+- **Cross-platform**: Windows, macOS, and Linux
+
+## More Examples
 
 ### High-Level API (Event-Driven)
 

package/lib/devices.js

@@ -1,14 +1,29 @@
+// @ts-check
 'use strict';
 
 const EventEmitter = require('events');
 const addon = require('../build/Release/smartcard_napi.node');
 
+/**
+ * @typedef {import('./index').Reader} Reader
+ * @typedef {import('./index').Card} Card
+ * @typedef {import('./index').MonitorEvent} MonitorEvent
+ * @typedef {import('./index').Context} ContextType
+ * @typedef {import('./index').ReaderMonitor} ReaderMonitorType
+ */
+
 const { Context, ReaderMonitor } = addon;
 const SCARD_STATE_PRESENT = addon.SCARD_STATE_PRESENT;
 const SCARD_SHARE_SHARED = addon.SCARD_SHARE_SHARED;
 const SCARD_PROTOCOL_T0 = addon.SCARD_PROTOCOL_T0;
 const SCARD_PROTOCOL_T1 = addon.SCARD_PROTOCOL_T1;
 
+/**
+ * @typedef {Object} ReaderState
+ * @property {boolean} hasCard
+ * @property {Card|null} card
+ */
+
 /**
  * High-level event-driven API for PC/SC devices
  *
@@ -21,14 +36,22 @@ const SCARD_PROTOCOL_T1 = addon.SCARD_PROTOCOL_T1;
  * - 'card-inserted': Emitted when a card is inserted
  * - 'card-removed': Emitted when a card is removed
  * - 'error': Emitted on errors
+ *
+ * @extends EventEmitter
  */
 class Devices extends EventEmitter {
     constructor() {
         super();
+        /** @type {ReaderMonitorType|null} */
         this._monitor = null;
+        /** @type {ContextType|null} */
         this._context = null;
+        /** @type {boolean} */
         this._running = false;
-        this._readers = new Map(); // name -> { hasCard, card }
+        /** @type {Map<string, ReaderState>} */
+        this._readers = new Map();
+        /** @type {Promise<void>} Event queue to serialize event handling */
+        this._eventQueue = Promise.resolve();
     }
 
     /**
@@ -95,7 +118,7 @@ class Devices extends EventEmitter {
 
     /**
      * List currently known readers
-     * @returns {Array} Array of reader names
+     * @returns {Reader[]} Array of readers
      */
     listReaders() {
         if (!this._context || !this._context.isValid) {
@@ -110,8 +133,20 @@ class Devices extends EventEmitter {
 
     /**
      * Handle events from native monitor
+     * Queues events to prevent race conditions when multiple events arrive concurrently
+     * @param {MonitorEvent} event
+     */
+    _handleEvent(event) {
+        // Chain this event onto the queue to serialize processing
+        this._eventQueue = this._eventQueue.then(() => this._processEvent(event));
+    }
+
+    /**
+     * Process a single event (called sequentially via queue)
+     * @param {MonitorEvent} event
+     * @returns {Promise<void>}
      */
-    async _handleEvent(event) {
+    async _processEvent(event) {
         if (!this._running) {
             return;
         }
@@ -120,7 +155,7 @@ class Devices extends EventEmitter {
 
         switch (type) {
             case 'reader-attached':
-                this._handleReaderAttached(readerName, state, atr);
+                await this._handleReaderAttached(readerName, state, atr);
                 break;
 
             case 'reader-detached':
@@ -144,8 +179,12 @@ class Devices extends EventEmitter {
 
     /**
      * Handle reader attached
+     * @param {string} readerName
+     * @param {number} state
+     * @param {Buffer|null} atr
+     * @returns {Promise<void>}
      */
-    _handleReaderAttached(readerName, state, atr) {
+    async _handleReaderAttached(readerName, state, atr) {
         // Initialize reader state
         this._readers.set(readerName, {
             hasCard: false,
@@ -163,12 +202,13 @@ class Devices extends EventEmitter {
 
         // Check if card is already present
         if ((state & SCARD_STATE_PRESENT) !== 0) {
-            this._handleCardInserted(readerName, state, atr);
+            await this._handleCardInserted(readerName, state, atr);
         }
     }
 
     /**
      * Handle reader detached
+     * @param {string} readerName
      */
     _handleReaderDetached(readerName) {
         const state = this._readers.get(readerName);
@@ -186,6 +226,10 @@ class Devices extends EventEmitter {
 
     /**
      * Handle card inserted
+     * @param {string} readerName
+     * @param {number} eventState
+     * @param {Buffer|null} atr
+     * @returns {Promise<void>}
      */
     async _handleCardInserted(readerName, eventState, atr) {
         let state = this._readers.get(readerName);
@@ -222,6 +266,7 @@ class Devices extends EventEmitter {
 
     /**
      * Handle card removed
+     * @param {string} readerName
      */
     _handleCardRemoved(readerName) {
         const state = this._readers.get(readerName);

package/lib/errors.js

@@ -1,9 +1,14 @@
+// @ts-check
 'use strict';
 
 /**
  * Base error class for PC/SC errors
  */
 class PCSCError extends Error {
+    /**
+     * @param {string} message
+     * @param {number} code
+     */
     constructor(message, code) {
         super(message);
         this.name = 'PCSCError';

package/lib/index.js

@@ -1,7 +1,6 @@
+// @ts-check
 'use strict';
 
-const path = require('path');
-
 // Load native addon
 const addon = require('../build/Release/smartcard_napi.node');
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "smartcard",
-    "version": "2.0.0",
+    "version": "2.0.2",
     "description": "PC/SC bindings for Node.js using N-API - ABI stable across Node.js versions",
     "author": "Tom KP",
     "license": "MIT",

package/src/reader_monitor.cpp

@@ -136,6 +136,14 @@ void ReaderMonitor::MonitorLoop() {
     // Get initial reader list
     UpdateReaderList();
 
+    // Emit reader-attached events for all pre-existing readers (Issue #30)
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        for (const auto& reader : readers_) {
+            EmitEvent("reader-attached", reader.name, reader.lastState, reader.atr);
+        }
+    }
+
     // Build initial states array with PnP notification
     std::vector<SCARD_READERSTATE> states;
     std::vector<std::string> readerNames;