npm package: @0biwank/gethwid
Description: Get Hardware ID (HWID) of the machine using a native Node.js addon built with N-API.
Author: Kunal Dubey
Latest version: 1.0.3

# getHWID

A native Node.js module for retrieving hardware identification information on Windows systems. This module uses N-API to access Windows WMI (Windows Management Instrumentation) and system firmware data.

## Features

- CPU Serial: Get the processor ID from CPU
- Disk Serial: Retrieve the serial number of physical storage devices
- Motherboard Serial: Fetch motherboard serial number
- MAC Address: Get the network adapter's MAC address
- Built with N-API for native access
- Includes TypeScript definitions

## Requirements

- **Node.js**: >= 14.0.0
- **Platform**: Windows (Win32) only
- **Build Tools**: Python 3.x and C++ compiler (for building from source)

## Installation

```bash
npm install @0biwank/gethwid
```

## Usage

### JavaScript (ESM)

```javascript
import { getCPUSerial, getDiskSerial, getMotherboardSerial, getMacAddress } from '@0biwank/gethwid';

// Get CPU Serial
const cpuSerial = getCPUSerial();
console.log('CPU Serial:', cpuSerial);

// Get Disk Serial
const diskSerial = getDiskSerial();
console.log('Disk Serial:', diskSerial);

// Get Motherboard Serial
const mbSerial = getMotherboardSerial();
console.log('Motherboard Serial:', mbSerial);

// Get MAC Address
const macAddress = getMacAddress();
console.log('MAC Address:', macAddress);
```

### JavaScript (CommonJS with default export)

```javascript
import getHWID from '@0biwank/gethwid';

const cpu = getHWID.getCPUSerial();
const disk = getHWID.getDiskSerial();
const mb = getHWID.getMotherboardSerial();
const mac = getHWID.getMacAddress();

console.log({ cpu, disk, mb, mac });
```

### TypeScript

```typescript
import { getCPUSerial, getDiskSerial, getMotherboardSerial, getMacAddress } from '@0biwank/gethwid';

const cpuSerial: string = getCPUSerial();
const diskSerial: string = getDiskSerial();
const mbSerial: string = getMotherboardSerial();
const macAddress: string = getMacAddress();

console.log({
  cpu: cpuSerial,
  disk: diskSerial,
  motherboard: mbSerial,
  mac: macAddress
});
```

## API Reference

### `getCPUSerial(): string`

Returns the processor ID from the CPU.

**Returns**: A string containing the CPU processor ID.

**Example**:
```javascript
const cpu = getCPUSerial();
```

### `getDiskSerial(): string`

Returns the serial number of the primary physical disk/storage device.

**Returns**: A string containing the disk serial number.

**Example**:
```javascript
const disk = getDiskSerial();
```

### `getMotherboardSerial(): string`

Returns the serial number of the motherboard/baseboard.

**Returns**: A string containing the motherboard serial number.

**Example**:
```javascript
const mb = getMotherboardSerial();
```

### `getMacAddress(): string`

Returns the MAC (Media Access Control) address of the primary network adapter.

**Returns**: A string containing the MAC address in standard notation (XX:XX:XX:XX:XX:XX).

**Example**:
```javascript
const mac = getMacAddress();
```

## How It Works

This module uses:

1. **Windows WMI (Windows Management Instrumentation)** for CPU, disk, and motherboard information
2. **System Firmware Table** (via `GetSystemFirmwareTable`) for system UUID and detailed hardware info
3. **N-API** for seamless integration between Node.js and native C++ code

## Building from Source

If you need to rebuild the module:

```bash
# Install dependencies
npm install

# Rebuild the native addon
npm run rebuild
```

### Prerequisites for Building

- **Node.js** with development headers
- **Python 3.x**
- **Microsoft Visual Studio** (Community Edition is sufficient) with C++ workload

## Testing

Run the test suite:

```bash
npm test
```

This will execute `test.js` and display hardware information for your system.

## Limitations

- Windows Only: This module only works on Windows systems (Win32)
- Administrator Privileges: Some information may require elevated privileges
- Virtual Machines: Virtualized environments may return virtual hardware identifiers
- Dual Boot: Only detects hardware of the current Windows installation

## Error Handling

Functions return empty strings if hardware information cannot be retrieved:

```javascript
const cpuSerial = getCPUSerial();

if (!cpuSerial) {
  console.warn('Could not retrieve CPU serial');
} else {
  console.log('CPU:', cpuSerial);
}
```

## Performance

All functions execute synchronously and typically complete quickly by accessing system information through WMI queries.

## License

MIT © [Kunal Dubey](https://github.com/0biwank)

## Repository

[GitHub: 0biwank/getHWID](https://github.com/0biwank/getHWID)

## Contributing

Contributions and bug reports are welcome. Please open an issue or submit a pull request on GitHub.

## Disclaimer

This module retrieves hardware identification information for legitimate purposes such as:
- System administration
- License key generation
- Device identification for software activation
- Hardware inventory management

Users are responsible for complying with applicable laws and privacy regulations when using hardware identification data.