npm package: @raj-dev/env-meta
Description: Browser-safe environment metadata (device, runtime, hardware, network, locale)
Author: Raj
Latest version: 1.0.0

# @raj-dev/env-meta

Dependency-free JavaScript library for browser environment metadata: device detection (mobile, tablet, desktop), OS and browser detection, hardware info, network hints, and locale. Vanilla JS, framework-agnostic, no fingerprinting, no tracking, no IP collection. Use with React, Vue, Angular, or plain scripts.

---

## What it does

Runs once in the client-side browser and returns a plain object describing the current environment: device type (mobile/tablet/desktop), operating system and version, browser name and version, CPU cores, approximate device memory, touch support, network connection hints (when available), optional bandwidth estimate, and locale (language and timezone). All values are derived from standard browser APIs and user-agent signals. The library does not persist, cache, or send data anywhere.

## What it does not do

- Does not collect IP addresses
- Does not fingerprint or infer identity
- Does not track users or sessions
- Does not persist or cache any data
- Does not include analytics or telemetry

Suitable for use in contexts that require clear privacy guarantees (e.g. App Store review, GDPR-conscious deployments).

---

## Data collected (high-level)

- **Device:** Classification as mobile, tablet, or desktop.
- **OS:** Operating system name and version when detectable.
- **Browser:** Browser name and major version when detectable.
- **Hardware:** Logical CPU core count, device memory tier (when exposed), and whether the device supports touch.
- **Network:** Connection type, effective type, downlink, RTT, and save-data preference when the Network Information API is available (not supported in Safari).
- **Speed (opt-in):** Optional bandwidth estimate via a small download test; only when explicitly requested.
- **Locale:** Primary language and timezone from the browser.

---

## Browser support

Works in modern evergreen browsers (Chrome, Firefox, Edge, Safari). Uses only standard, non-deprecated APIs. Network Information API (`navigator.connection`) is not supported in Safari; the `network` field is then `null`. Speed test requires `fetch` and `AbortController`. No polyfills; the library fails gracefully and returns `null` for unsupported fields.

---

## Installation

**npm**

```bash
npm install @raj-dev/env-meta
```

---

## Usage

**ESM**

```js
import EnvMeta from "@raj-dev/env-meta";

const meta = await EnvMeta.collect();
console.log(meta.device.type, meta.locale.language);

// With optional speed test
const metaWithSpeed = await EnvMeta.collect({ networkSpeed: true, timeout: 5000 });
```

**UMD**

```html
<script src="dist/env-meta.umd.js"></script>
<script>
  EnvMeta.collect().then(function (meta) {
    console.log(meta);
  });
</script>
```

---

## API

### `collect(options?)`

Returns a Promise that resolves to a single metadata object. Safe to call in any environment; unsupported values are `null` or sensible defaults. Does not throw.

**Options**

| Option           | Type    | Default | Description |
|------------------|---------|---------|-------------|
| `networkSpeed`   | boolean | `false` | If `true`, runs an opt-in download-based bandwidth estimate and adds a `speed` field. |
| `timeout`        | number  | `5000`  | Max time in ms for the speed test. Ignored when `networkSpeed` is false. |
| `speedTestUrl`   | string  | (built-in) | URL used for the speed test. Override for custom endpoints. |

**Return value**

Object with: `device`, `os`, `browser`, `hardware`, `network` (or `null`), `locale`, `timestamp`. If `networkSpeed: true`, also `speed` with `estimatedMbps` and `method: "download-test"`.

**Response format**

```json
{
  "device": { "type": "mobile" | "tablet" | "desktop" },
  "os": { "name": string | null, "version": string | null },
  "browser": { "name": string | null, "version": string | null },
  "hardware": { "cores": number | null, "memoryGB": number | null, "touch": boolean },
  "network": {
    "connectionType": string | null,
    "effectiveType": string | null,
    "downlinkMbps": number | null,
    "rtt": number | null,
    "saveData": boolean
  } | null,
  "speed": { "estimatedMbps": number | null, "method": "download-test" },
  "locale": { "language": string, "timezone": string },
  "timestamp": number
}
```

`speed` is only present when `networkSpeed: true` is passed. `network` is `null` when the Network Information API is not available (e.g. Safari).

---

## Support

If this library is useful to you, you can support the maintainer:

- [Buy Me a Coffee](https://buymeacoffee.com/rajappar412)
- [GitHub Sponsors](https://github.com/sponsors/RajappaR)

---

## License

MIT