@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

yarn add @tap-payments/browser-info

npm install @tap-payments/browser-info

Quick start

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

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

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

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