📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
import path from 'path'
import fs from 'fs'
import crypto from 'crypto'
import net from 'net'
import { Reader, CityResponse } from 'maxmind'
import { HttpException } from '@nestjs/common'
import timezones from 'countries-and-timezones'
import _sample from 'lodash/sample'
import _toNumber from 'lodash/toNumber'
import _replace from 'lodash/replace'
import _find from 'lodash/find'
import _size from 'lodash/size'
import _round from 'lodash/round'
import _split from 'lodash/split'
import { redis, isDevelopment } from './constants'
/*
Returns a 32-character hash of the provided string using Node.js crypto module.
(SHA-256 truncated to 32 chars)
*/
export const hash = (content: string): string => {
return crypto
.createHash('sha256')
.update(content)
.digest('hex')
.substring(0, 32)
}
/**
* Derives a key from the SECRET_KEY_BASE environment variable using the HKDF algorithm.
*/
export const deriveKey = (
purpose:
| 'refresh-token'
| 'access-token'
| 'gsc-token'
| 'ga4-token'
| 'revenue'
| 'api-key'
| 'data-export',
length = 32,
) => {
const baseStr = process.env.SECRET_KEY_BASE
// If SECRET_KEY_BASE is missing, token secrets become predictable across deployments.
// Fail closed outside dev/test.
if (!baseStr) {
const env = process.env.NODE_ENV
if (env === 'development' || env === 'test') {
return crypto
.createHash('sha256')
.update(`dev:${purpose}`)
.digest('hex')
.substring(0, length * 2)
}
throw new Error(
'SECRET_KEY_BASE environment variable is not set. This would make derived secrets predictable.',
)
}
const base = Buffer.from(baseStr, 'utf8')
const info = Buffer.from(purpose, 'utf8')
return Buffer.from(
crypto.hkdfSync('sha256', base, Buffer.alloc(0), info, length),
).toString('hex')
}
export const generateRandomId = (alphabet: string, size: number) => {
const bytes = crypto.randomBytes(size)
let id = ''
for (let i = 0; i < size; i++) {
id += alphabet[bytes[i] % alphabet.length]
}
return id
}
const marketingTips = {
en: [
'Blog frequently and consistently to build search engine presence.\nTo get website visitors, you need lots and lots of content. Your prospects are using Google every day to search for what they want. One of the most reliable ways to show up in Google results is to blog about lots of topics your customers care about.',
'Build an active presence on the top social media networks.\nWhen your prospects are not using Google, they are using Facebook, Twitter, Google Plus, LInkedIn, and Pinterest. You need a presence on at least 3 of these top 5 networks. Ideally, you should be updating them several times each week or even every single day if possible.',
'Focus on the most important rule in marketing: Content Is King!\nBurn this one into your brain forever. This is the golden rule of marketing — Content Is King! It is the rule you need to follow in every medium where you are creating new marketing messages: email, blogging, social media, web content, etc.',
'Use Email Marketing\nEmails should not be just limited to welcoming your new customers, it can also help to push customers to your website with promotions, deals, discounts, and contests.',
'Contribute Articles to Expert Sites\nFind blogs or websites that are thought leaders in your industry, then submit articles that can put in front of their audience. This is also a great way to build backlinks and drive organic traffic to your website.',
'Create an Affiliate Program\nAffiliate programs are an easy way to get people clicking to your website to learn more about your company. To date, 81% of brands have adopted an affiliate marketing program.\nAn affiliate program is a long term investment; you will have to build a program people will want to join, try to get and manage quality affiliates so you can get the fruits of your labour.',
'Add Your Website Link To All Your Platforms\nAdding your links to all your platforms allows you to optimise your website for more clicks.',
"Have a Backlink Strategy\nGoogle's search engine uses links as one of the three most important search engine ranking factors for a website.\nBelieve it or not, you can improve your website's SEO by backlinking your website in the article you contribute as a guest writer.\nOnce you have a strategy in place, you will begin to see your website's click-through rate increase and traffic coming your way.",
'Host a Giveaway on Your Website\nHosting a giveaway on your website is a sure way to promote your website. Giveaways pack more of a punch for your business than you think.',
'Use Influencers To Market Your Website\nInfluencer Marketing has been in the top five marketing tools and strategies for the past four years and counting.\nYou can use influencers in a wide variety of ways. One way is to partner with an influencer for a do co-promotions like a giveaway, a special discount, or prize package.',
'Fix Broken External Links & Errors\nBroken external links, just as the states, are links that lead nowhere or give users an error.\nMaybe your busy sharing other links from your site or there are some old content or web pages you forgot you deleted. Over time you will be losing potential traffic and clients if you forget to audit your site to find broken external links.',
'Combine offline marketing with online marketing.\nYes, it is true, print media is still alive and well.',
'Promote your product features.\nSince social media contests get so much engagement, treat it almost like mini ads for your products. Listing out the benefits and features so that potential buyers can see what your products have to offer. It will not only convince customers that they want your product but that they need it and can not live without it!',
'Link internally.\nThe strength of your link profile is not solely determined by how many sites link back to you - it can also be affected by your internal linking structure. When creating and publishing content, be sure to keep an eye out for opportunities for internal links. This not only helps with SEO, but also results in a better, more useful experience for the user - the cornerstone of increasing traffic to your website.',
'Make sure your site is responsive.\nThe days when internet browsing was done exclusively on desktop PCs are long gone. Today, more people than ever before are using mobile devices to access the web, and if you force your visitors to pinch and scroll their way around your site, you are basically telling them to go elsewhere. Even if you have a basic website, you still need to ensure that it is accessible and comfortably viewable across a range of devices, including smaller smartphones.',
'Make sure your site is fast.\nEver found yourself waiting thirty seconds for a webpage to load? Me neither. If your site takes forever to load, your bounce rate will be sky high. Make sure that your pages are as technically optimized as possible, including image file sizes, page structure and the functionality of third-party plugins. The faster your site loads, the better.',
'Submit your content to aggregator sites.\nFirstly, a disclaimer - do not spam Reddit and other similar sites hoping to "hit the jackpot" of referral traffic, because it is not going to happen. Members of communities like Reddit are extraordinarily savvy to spam disguised as legitimate links, but every now and again, it does not hurt to submit links that these audiences will find genuinely useful. Choose a relevant subreddit, submit your content, then watch the traffic pour in.',
],
}
const RATE_LIMIT_REQUESTS_AMOUNT = 3
const RATE_LIMIT_TIMEOUT = 86400 // 24 hours
const getRateLimitHash = (ipOrApiKey: string, salt = '') =>
`rl:${hash(`${ipOrApiKey}${salt}`)}`
const REDIS_INCR_WITH_EXPIRE_LUA = `
local current = redis.call("INCR", KEYS[1])
if tonumber(current) == 1 then
redis.call("EXPIRE", KEYS[1], ARGV[1])
end
return current
`
const incrWithExpiry = async (key: string, expiresInSeconds: number) => {
const res = await redis.eval(
REDIS_INCR_WITH_EXPIRE_LUA,
1,
key,
String(expiresInSeconds),
)
return Number(res)
}
export const getRandomTip = (language = 'en'): string => {
return _sample(marketingTips[language])
}
// 'action' is used as a salt to differ rate limiting routes
export const checkRateLimit = async (
key: string,
action: string,
reqAmount: number = RATE_LIMIT_REQUESTS_AMOUNT,
reqTimeout: number = RATE_LIMIT_TIMEOUT,
) => {
if (isDevelopment) {
return
}
const rlHash = getRateLimitHash(key, action)
const rlCount = await incrWithExpiry(rlHash, reqTimeout)
if (rlCount > reqAmount) {
throw new HttpException('Too many requests, please try again later', 429)
}
}
const RATE_LIMIT_FOR_API_KEY_TIMEOUT = 60 * 60 // 1 hour
export const checkRateLimitForApiKey = async (
apiKey: string,
reqAmount: number,
): Promise<boolean> => {
if (isDevelopment) {
return true
}
const rlHash = getRateLimitHash(apiKey)
const rlCount = await incrWithExpiry(rlHash, RATE_LIMIT_FOR_API_KEY_TIMEOUT)
if (rlCount > reqAmount) {
throw new HttpException('Too many requests, please try again later', 429)
}
return true
}
/**
* Checking the % change in one number relative to the other
* @param oldVal The initial value
* @param newVal The value that changed
* @param round Numbers after floating point
*/
export const calculateRelativePercentage = (
oldVal: number,
newVal: number,
round = 2,
) => {
if (oldVal === newVal) return 0
if (oldVal === 0) return 100
if (newVal === 0) return -100
if (newVal > oldVal) {
return _round((newVal / oldVal) * 100, round)
}
return _round((1 - newVal / oldVal) * -100, round)
}
const ALPHA_UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
export const generateRecoveryCode = () => generateRandomId(ALPHA_UPPER, 30)
export const millisecondsToSeconds = (milliseconds: number) =>
milliseconds / 1000
const ALPHANUMERIC =
'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
export const generateRandomString = (length: number): string =>
generateRandomId(ALPHANUMERIC, length)
/**
* This is used to determine if the current node is the primary node.
*
* NODE_APP_INSTANCE is set to 0 (or undefined if not running on PM2) on primary node, and any other number on secondary nodes.
*
* @see https://pm2.keymetrics.io/docs/usage/environment/#specific-environment-variables
*/
export const isPrimaryClusterNode = () => {
if (!process.env.NODE_APP_INSTANCE) {
return true
}
return process.env.NODE_APP_INSTANCE === '0'
}
export const isPrimaryNode = () => {
return process.env.IS_PRIMARY_NODE === 'true'
}
const dummyLookup = () => ({
country: {
names: {
en: null,
},
},
city: {
names: {
en: null,
},
},
subdivisions: [
{
names: {
en: null,
},
},
],
})
const DEVELOPMENT_GEOIP_DB_PATH = path.join(
__dirname,
'../../../..',
'ip-geolocation-db.mmdb',
)
const PRODUCTION_GEOIP_DB_PATH = path.join(
__dirname,
'../..',
'ip-geolocation-db.mmdb',
)
let lookup: Reader<CityResponse> = {
// @ts-ignore
get: dummyLookup,
}
if (fs.existsSync(PRODUCTION_GEOIP_DB_PATH)) {
const buffer = fs.readFileSync(PRODUCTION_GEOIP_DB_PATH)
lookup = new Reader<CityResponse>(buffer)
} else if (fs.existsSync(DEVELOPMENT_GEOIP_DB_PATH)) {
const buffer = fs.readFileSync(DEVELOPMENT_GEOIP_DB_PATH)
lookup = new Reader<CityResponse>(buffer)
}
interface IPDetails {
country: string | null
region: string | null
regionCode: string | null
city: string | null
isp: string | null
organization: string | null
userType: string | null
connectionType: string | null
isHosting: boolean
}
export const getIPDetails = (ip: string, tz?: string): IPDetails => {
let data
try {
data = ip ? lookup.get(ip) : null
} catch {
data = null
}
const traits = data?.traits ?? {}
const isHosting =
traits.is_hosting_provider === true || traits.user_type === 'hosting'
// Stage 1: Using IP address based geo lookup
const country = data?.country?.iso_code || null
const city = data?.city?.names?.en || null
const region = data?.subdivisions?.[0]?.names?.en || null
const regionCode = data?.subdivisions?.[0]?.iso_code || null
const isp = traits.isp || null
const organization = traits.organization || null
const userType = traits.user_type || null
const connectionType = traits.connection_type || null
if (country) {
return {
country,
city,
region,
regionCode,
isp,
organization,
userType,
connectionType,
isHosting,
}
}
const tzCountry = timezones.getCountryForTimezone(tz)?.id || null
return {
country: tzCountry,
city: null,
region: null,
regionCode: null,
isp: null,
organization: null,
userType: null,
connectionType: null,
isHosting,
}
}
interface ExtendedGeoDetails {
country: string | null
countryName: string | null
city: string | null
region: string | null
regionCode: string | null
continentCode: string | null
continentName: string | null
postalCode: string | null
latitude: number | null
longitude: number | null
timezone: string | null
isp: string | null
organization: string | null
userType: string | null
connectionType: string | null
}
export const getExtendedGeoDetails = (ip: string): ExtendedGeoDetails => {
const data = lookup.get(ip)
if (!data) {
return {
country: null,
countryName: null,
city: null,
region: null,
regionCode: null,
continentCode: null,
continentName: null,
postalCode: null,
latitude: null,
longitude: null,
timezone: null,
isp: null,
organization: null,
userType: null,
connectionType: null,
}
}
const traits = data.traits ?? {}
return {
country: data.country?.iso_code || null,
countryName: data.country?.names?.en || null,
city: data.city?.names?.en || null,
region: data.subdivisions?.[0]?.names?.en || null,
regionCode: data.subdivisions?.[0]?.iso_code || null,
continentCode: data.continent?.code || null,
continentName: data.continent?.names?.en || null,
postalCode: data.postal?.code || null,
latitude: data.location?.latitude || null,
longitude: data.location?.longitude || null,
timezone: data.location?.time_zone || null,
isp: traits.isp || null,
organization: traits.organization || null,
userType: traits.user_type || null,
connectionType: traits.connection_type || null,
}
}
const normalise = (raw: unknown): string | null => {
if (!raw) return null
const str = String(raw)
const first = str.split(',')[0]?.trim()
if (!first) return null
// Handle bracketed IPv6 like: [::1]:1234
const unbracketed = first.replace(/^\[([^\]]+)\](?::\d+)?$/, '$1')
if (net.isIP(unbracketed)) return unbracketed
// Handle IPv4 with port like: 203.0.113.1:1234
const ipv4PortMatch = unbracketed.match(/^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/)
if (ipv4PortMatch?.[1] && net.isIP(ipv4PortMatch[1])) {
return ipv4PortMatch[1]
}
return null
}
const getHeader = (headers: any, name: string): string | null | undefined => {
if (typeof headers?.get === 'function') {
return headers.get(name)
}
return headers?.[name] ?? headers?.[name.toLowerCase()]
}
// Egress IPs of our own relays (the web app's server-side fetches, the
// managed proxy edge). Requests arriving from these carry the real visitor
// IP in X-Forwarded-For; for every other connection the only trustworthy
// source is X-Real-IP, which nginx derives from the TCP connection itself.
export const TRUSTED_PROXY_IPS: ReadonlySet<string> = new Set(
(process.env.TRUSTED_PROXY_IPS || '')
.split(',')
.map((entry) => entry.trim())
.filter(Boolean),
)
export const getIPFromHeaders = (headers: unknown) => {
// Legacy header; must keep precedence over X-Forwarded-For so pre-2026
// server-side tracking setups keep working.
const customHeader = process.env.CLIENT_IP_HEADER
if (customHeader) {
const headerValue = getHeader(headers, customHeader)
if (headerValue) {
return normalise(headerValue)
}
}
const forwardedFor = String(getHeader(headers, 'x-forwarded-for') ?? '')
const realIp = normalise(getHeader(headers, 'x-real-ip'))
if (!realIp) {
return normalise(forwardedFor)
}
if (!TRUSTED_PROXY_IPS.has(realIp)) {
return normalise(forwardedFor) ?? realIp
}
// The connection is one of our own relays. Recover the visitor from
// X-Forwarded-For, walking from the right past our own hops so a
// client-supplied prefix never wins.
const hops = forwardedFor.split(',')
for (let i = hops.length - 1; i >= 0; --i) {
const candidate = normalise(hops[i])
if (candidate && !TRUSTED_PROXY_IPS.has(candidate)) {
return candidate
}
}
return realIp
}
export const sumArrays = (source: number[], target: number[]) => {
const result = []
const size = _size(source)
for (let i = 0; i < size; ++i) {
result.push(source[i] + target[i])
}
return result
}
/**
* Format duration in seconds to human-readable format (e.g., "3m 42s")
* @param seconds Duration in seconds
* @returns Formatted duration string
*/
export const formatDuration = (seconds: number | null | undefined): string => {
if (seconds == null || !Number.isFinite(seconds) || seconds <= 0) return '0s'
const roundedSeconds = Math.round(seconds)
if (roundedSeconds < 60) {
return `${roundedSeconds}s`
}
const minutes = Math.floor(roundedSeconds / 60)
const remainingSeconds = roundedSeconds % 60
if (minutes < 60) {
return remainingSeconds > 0
? `${minutes}m ${remainingSeconds}s`
: `${minutes}m`
}
const hours = Math.floor(minutes / 60)
const remainingMinutes = minutes % 60
if (remainingMinutes > 0) {
return `${hours}h ${remainingMinutes}m`
}
return `${hours}h`
}