@tap-payments/browser-info

@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