# @tap-payments/browser-info

> Browser fingerprinting SDK for Tap Payments — collects device, browser, and location headers in Tap's required format

Latest version **3.0.1** (published 2026-09-16) · ISC license · 0 weekly downloads

## Install

```sh
npm install @tap-payments/browser-info
pnpm add @tap-payments/browser-info
yarn add @tap-payments/browser-info
bun add @tap-payments/browser-info
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.0.1 |
| Published | 2026-09-16 |
| First published | 2022-10-19 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 5.9 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Ahmed Elsharkawy |
| Maintainers | elsharkawy, waqast, kalpanatap, sherifashraftap, sadbarkhattak, muhammadazhar007, mud_fahmi, haitham-tap, mostafaabobakr.tap, aya_tap, its.sehrish.tap, mahmoudallam, bsmsisy, a.safwat-tap, ali-sanad-tap, omar_saber, madel-tap |
| Keywords | tap-payments, browser-info, fingerprint, device-detection |

## Links

- npm: https://www.npmjs.com/package/@tap-payments/browser-info
- npm.io page: https://npm.io/package/@tap-payments/browser-info

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 3.0.1 (latest) — 2026-09-16
- 3.0.0 — 2026-09-16
- 2.0.1 — 2026-08-02
- 2.0.0 — 2026-08-02
- 1.0.2 — 2023-03-13
- 1.0.1 — 2023-03-12
- 1.0.0 — 2022-10-19

## README

# @tap-payments/browser-info

Collects device, browser, and location data in the browser and returns it in three forms: encrypted short keys, plain-text short keys, or a full snake_case device profile. The output is purpose-neutral — you decide whether to send it as headers, a request body, or an event payload.

## Install

```bash
yarn add @tap-payments/browser-info
```

```bash
npm install @tap-payments/browser-info
```

## Quick start

One class, three methods. The constructor takes only the app basics; everything else is per-method.

```typescript
import { BrowserInfo, getClientIpv4, getGeoLocation } from "@tap-payments/browser-info"

const browserInfo = new BrowserInfo({
  name: "MyApp",
  language: "en",
  version: "1.0.0"
})

// `location` is required — obtain it from `getGeoLocation()`, or supply your own object
const location = await getGeoLocation()

// 1. Short keys, encrypted — every value except `authorization` passes through `encrypt`
const encrypted = await browserInfo.getEncrypted({
  credentials: { pk: "pk_...", mdn: "example.com" },
  encrypt: (key, value) => encryptValue(key, value),
  location
})

// 2. Short keys, plain text — same keys, no encryption
const plain = await browserInfo.getPlain({
  credentials: { pk: "pk_...", mdn: "example.com" },
  location
})

// 3. Full snake_case device profile — no credentials needed
const info = await browserInfo.getDeviceInfo({
  location,
  device: { brand: "Apple", model: "iPhone 15 Pro" }
})

// Client public IPv4 address — standalone helper
const ip = await getClientIpv4()
```

## Constructor

```typescript
new BrowserInfo(app: AppConfig)
```

| Field | Type | Description |
|-------|------|-------------|
| `app.name` | `string` | Application name |
| `app.language` | `string` | Application locale (e.g. `ar`, `en`) |
| `app.version` | `string?` | Application version |

## Short-key methods

### `getEncrypted(options)` → `Promise<ShortBrowserInfo>`

The compact short-key object with every value encrypted through your `encrypt` callback (except `authorization`).

### `getPlain(options)` → `Promise<ShortBrowserInfo>`

The same short-key object as plain text.

| Option | Type | Description |
|--------|------|-------------|
| `credentials.pk` | `string` | Authorization public key |
| `credentials.mdn` | `string` | Merchant domain or bundle ID |
| `encrypt` | `(key, value) => string` | Per-field encryption (required by `getEncrypted` only) |
| `location` | `LocationData` | IP and coordinates — required |

### Short-key output (`ShortBrowserInfo`)

| Key | Description |
|-----|-------------|
| `authorization` | Authorization public key |
| `mdn` | Merchant domain name or bundle ID |
| `cu` | Current page URL |
| `al` | Application locale |
| `at` | Application type (`"browser"`) |
| `aid` | Application identifier (reserved, `""`) |
| `an` | Application name |
| `av` | Application version |
| `rn` | Device name (reserved, `""`) |
| `rt` | Device type (desktop, smartphone, tablet) |
| `rb` | Device brand |
| `rm` | Device model |
| `ro` | Device OS name |
| `rov` | Device OS version |
| `bn` | Browser name |
| `bb` | Third-party browser brand (`""`) |
| `bv` | Browser version |
| `bua` | User agent string (truncated to 80 chars) |
| `bi` | Browser fingerprint ID |
| `ci` | Client IP address |
| `cm` | MAC address (not available in browsers, `""`) |
| `l` | Location as `"latitude-longitude"` |

## Device-info method

### `getDeviceInfo(options)` → `Promise<DeviceInfo>`

The full device/browser/geo/network picture in snake_case names. No credentials or encryption involved.

| Option | Type | Description |
|--------|------|-------------|
| `location` | `LocationData` | IP/coordinates + optional geo/ASN enrichment — required |
| `device` | `DeviceOverride?` | Fallback for device fields the browser can't collect |

### Device output (`DeviceInfo`)

| Field | Description |
|-------|-------------|
| `app_name` / `app_language` / `app_version` | Application basics from the constructor |
| `app_type` | Application type (`"browser"`) |
| `browser_name` / `browser_version` | Browser name and version |
| `browser_id` | Browser fingerprint ID |
| `user_agent_name` / `user_agent_os` / `user_agent_version` | User agent attributes |
| `device_type` | Device type (desktop, smartphone, tablet) |
| `device_brand` | Device manufacturer/brand |
| `device_model` | Device model |
| `device_os_name` / `device_os_version` | Operating system name and version |
| `browser_width` / `browser_height` | Viewport size |
| `client_ip` | Client public IP address |
| `city` / `country_code` / `region_code` | IP geo enrichment — set only when supplied via `location` |
| `asn` / `asn_latitude` / `asn_longitude` / `asn_organization` | Network/ASN enrichment — set only when supplied via `location` |
| `isp` / `timezone` / `ip_version` | ISP, IANA timezone, and IP version of the client IP — from `location` |
| `hostname` | Site hostname (no path) |
| `page_url` | Full page URL |
| `referrer_url` | Referrer URL |

Safari and Firefox expose less device detail than Chromium browsers — pass `device` there if you need brand/model.

## Location input

Pass an object with any of these fields:

| Field | Type | Description |
|-------|------|-------------|
| `ip` | `string` | Client IP address |
| `latitude` | `string` | Latitude |
| `longitude` | `string` | Longitude |
| `city` | `string?` | IP city (feeds `getDeviceInfo` only) |
| `country_code` | `string?` | IP country (feeds `getDeviceInfo` only) |
| `region_code` | `string?` | IP region (feeds `getDeviceInfo` only) |
| `asn` | `string?` | Autonomous system number (feeds `getDeviceInfo` only) |
| `asn_latitude` | `string?` | ASN latitude (feeds `getDeviceInfo` only) |
| `asn_longitude` | `string?` | ASN longitude (feeds `getDeviceInfo` only) |
| `asn_organization` | `string?` | ASN organization (feeds `getDeviceInfo` only) |
| `isp` | `string?` | ISP / network operator (feeds `getDeviceInfo` only) |
| `timezone` | `string?` | IANA timezone of the IP (feeds `getDeviceInfo` only) |
| `ip_version` | `string?` | `IPv4` or `IPv6` (feeds `getDeviceInfo` only) |

`location` is **required** on every method. Obtain a `LocationData` via `getGeoLocation()`
or build your own. The values are passed through as-is — the SDK does not look location
up itself. Only the fields listed as `getDeviceInfo`-only are optional; `ip`,
`latitude`, and `longitude` are required.

## `getClientIpv4()` → `Promise<string>`

Standalone helper (exported beside the class) that returns the client's public **IPv4** address.

## `getGeoLocation(ip?)` → `Promise<LocationData>`

Standalone helper that resolves a location (IP, coordinates, city, country,
ASN/network, ISP, timezone) from free public geo-IP services. Called with no argument
it looks up the caller's own IP; pass an explicit `ip` string to look that one up.
Returns a `LocationData`, or `"n/a"` defaults for `ip`/`latitude`/`longitude` if the
lookup fails. Results are cached per lookup for the page's lifetime — pass one as
`location` to any method.

## Caching

Fingerprinting, `getGeoLocation()`, and `getClientIpv4()` cache their results for the
page's lifetime: calling the methods repeatedly (e.g. from a React component) reuses the
cached values instead of re-fetching. A failed lookup is retried on the next call.

## TypeScript

```typescript
import type {
  ShortBrowserInfo,
  DeviceInfo,
  AppConfig,
  LocationData,
  Credentials,
  DeviceOverride,
  EncryptedOptions,
  PlainOptions,
  DeviceInfoOptions
} from "@tap-payments/browser-info"
```

## Browser support

Modern browsers with ES2018+, `window`, `navigator`, and `fetch`.

## License

ISC

---
_Source: https://npm.io/package/@tap-payments/browser-info · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._