Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

22.2 KB
Raw Blame
import { deepEqual as equal } from 'fast-equals'
import { LogicWrapper } from 'kea'
import { routerType } from 'kea-router/lib/routerType'

import { FEATURE_FLAGS } from 'lib/constants'
import { dayjs } from 'lib/dayjs'
import { dateStringToDayJs } from 'lib/utils/dateFilters'
import { compactNumber } from 'lib/utils/numbers'
import { wordPluralize } from 'lib/utils/strings'
import { Params } from 'scenes/sceneTypes'

import { BillingPeriod, BillingProductV2AddonType, BillingProductV2Type, BillingTierType, BillingType } from '~/types'

import { SPEND_TYPES, USAGE_TYPES } from './constants'
import type { BillingFilters, BillingUsageInteractionProps } from './types'
import { BillingGaugeItemKind, BillingGaugeItemType } from './types'

export const isProductVariantPrimary = (productType: string): boolean =>
    ['session_replay', 'realtime_destinations', 'data_warehouse', 'workflows_emails', 'logs'].includes(productType)

export const isProductVariantSecondary = (productType: string): boolean =>
    [
        'mobile_replay',
        'batch_exports',
        'data_warehouse_historical',
        'workflows_destinations',
        'logs_retention_30d',
    ].includes(productType)

export const calculateFreeTier = (product: BillingProductV2Type | BillingProductV2AddonType): number => {
    // If subscribed and has tiers, check if the first tier is free
    if (product.subscribed && product.tiers && product.tiers.length > 0) {
        if (product.tiers[0].unit_amount_usd === '0') {
            return product.tiers[0].up_to || 0
        }
        return 0
    }
    // Otherwise use free_allocation (for unsubscribed products)
    return product.free_allocation || 0
}

// Add-ons never carry the flag, and older billing omits it, so both count as allowing a limit.
export const canHaveBillingLimit = (product: BillingProductV2Type | BillingProductV2AddonType): boolean =>
    !('no_billing_limit' in product && product.no_billing_limit === true)

// Whether the product card shows its billing limit block.
export const isBillingLimitShown = (product: BillingProductV2Type, billing: BillingType | null): boolean =>
    billing?.billing_period?.interval === 'month' &&
    !!product.subscribed &&
    !product.inclusion_only &&
    canHaveBillingLimit(product)

export const createGaugeItems = (
    product: BillingProductV2Type | BillingProductV2AddonType,
    options: {
        billing?: BillingType | null
        billingLimitAsUsage?: number
    } = {}
): BillingGaugeItemType[] => {
    const freeTier = calculateFreeTier(product)

    return [
        // Billing limit (only for main products, excl. product variants setup)
        options.billingLimitAsUsage &&
        options.billing?.discount_percent !== 100 &&
        !isProductVariantPrimary(product.type) &&
        canHaveBillingLimit(product)
            ? {
                  type: BillingGaugeItemKind.BillingLimit,
                  text: 'Billing limit',
                  value: options.billingLimitAsUsage || 0,
              }
            : undefined,

        // Free tier
        freeTier
            ? {
                  type: BillingGaugeItemKind.FreeTier,
                  text: 'Free tier limit',
                  value: freeTier,
              }
            : undefined,

        // Projected usage
        product.projected_usage && product.projected_usage > (product.current_usage || 0)
            ? {
                  type: BillingGaugeItemKind.ProjectedUsage,
                  text: 'Projected',
                  value: product.projected_usage || 0,
              }
            : undefined,

        // Current usage
        {
            type: BillingGaugeItemKind.CurrentUsage,
            text: 'Current',
            value: product.current_usage || 0,
        },
    ].filter(Boolean) as BillingGaugeItemType[]
}

export const summarizeUsage = (usage: number | null): string => {
    if (usage === null) {
        return ''
    }
    return compactNumber(usage)
}

/**
 * Check if a product has display formatting configured.
 */
export const hasDisplayFormatting = (product: BillingProductV2Type | BillingProductV2AddonType): boolean => {
    return !!(product.display_divisor != null || product.display_decimals != null || product.display_unit)
}

/**
 * Formats a usage value for human-friendly display based on product display config.
 * If the product has display formatting fields set, applies them. Otherwise returns
 * either a compact number (compactFallback: true) or full number with commas.
 *
 * Examples:
 * - Storage: 27648 MB → "27.65 GB" (divisor=1000, decimals=2, unit="GB")
 * - No config: 1234567 → "1,234,567" (default) or "1.23 M" (compactFallback)
 */
export const formatDisplayUsage = (
    value: number | null,
    product: BillingProductV2Type | BillingProductV2AddonType,
    options?: { compactFallback?: boolean }
): string => {
    if (value === null) {
        return ''
    }

    // If no display formatting configured, return appropriate fallback
    if (!hasDisplayFormatting(product)) {
        return options?.compactFallback ? compactNumber(value) : value.toLocaleString()
    }

    const { display_divisor, display_decimals, display_unit } = product

    // Apply divisor if set
    let displayValue = display_divisor ? value / display_divisor : value

    // Format with decimals if set
    let formattedValue: string
    if (typeof display_decimals === 'number') {
        formattedValue = displayValue.toFixed(display_decimals)
    } else {
        formattedValue = displayValue.toLocaleString()
    }

    // Append unit if set (pluralized appropriately)
    if (display_unit) {
        // Don't pluralize abbreviations (all uppercase like "GB", "MB") or if value rounds to 1
        const isAbbreviation = display_unit === display_unit.toUpperCase()
        const roundedValue =
            typeof display_decimals === 'number' ? parseFloat(displayValue.toFixed(display_decimals)) : displayValue
        const shouldPluralize = !isAbbreviation && roundedValue !== 1
        const unitLabel = shouldPluralize ? wordPluralize(display_unit) : display_unit
        return `${formattedValue} ${unitLabel}`
    }

    return formattedValue
}

/**
 * Create a value formatter function for a product.
 * Uses formatDisplayUsage with compactFallback for non-configured products.
 */
export const createProductValueFormatter = (
    product: BillingProductV2Type | BillingProductV2AddonType
): ((value: number | null) => string) => {
    return (value: number | null): string => formatDisplayUsage(value, product, { compactFallback: true })
}

/**
 * Get the unit label for display (pluralized).
 * Returns empty string when display formatting is enabled, since the unit is already
 * included in the formatted value from formatDisplayUsage.
 */
export const getProductUnitLabel = (product: BillingProductV2Type | BillingProductV2AddonType): string => {
    // When display formatting is enabled, the unit is already in the formatted value
    if (hasDisplayFormatting(product)) {
        return ''
    }
    return product.unit ? `${product.unit}s` : ''
}

export const projectUsage = (usage: number | undefined, period: BillingType['billing_period']): number | undefined => {
    if (typeof usage === 'undefined') {
        return usage
    }
    if (!period) {
        return usage
    }

    const timeSoFar = dayjs().diff(period.current_period_start, 'hours')

    // If less than 6 hours have passed, we don't have enough data to project
    if (timeSoFar <= 6) {
        return usage
    }
    const timeTotal = period.current_period_end.diff(period.current_period_start, 'hours')

    return Math.round((usage / timeSoFar) * timeTotal)
}

export const convertUsageToAmount = (
    usage: number,
    productAndAddonTiers: BillingTierType[][],
    percentDiscount?: number
): string => {
    if (!productAndAddonTiers) {
        return ''
    }
    let remainingUsage = usage
    let amount = 0
    let previousTier: BillingTierType | undefined = undefined

    const tiers = productAndAddonTiers[0].map((tier, index) => {
        const allAddonsTiers = productAndAddonTiers.slice(1)
        let totalAmount = parseFloat(tier.unit_amount_usd)
        let flatFee = parseFloat(tier.flat_amount_usd || '0')
        for (const addonTiers of allAddonsTiers) {
            totalAmount += parseFloat(addonTiers[index].unit_amount_usd)
            flatFee += parseFloat(addonTiers[index].flat_amount_usd || '0')
        }
        return {
            ...tier,
            unit_amount_usd: totalAmount.toString(),
            flat_amount_usd: flatFee.toString(),
        }
    })

    for (const tier of tiers) {
        if (remainingUsage <= 0) {
            break
        }

        const tierUsageMax = tier.up_to ? tier.up_to - (previousTier?.up_to || 0) : Infinity
        const amountFloatUsd = parseFloat(tier.unit_amount_usd)
        const tierFlatFee = parseFloat(tier.flat_amount_usd || '0')
        const usageThisTier = Math.min(remainingUsage, tierUsageMax)
        remainingUsage -= usageThisTier
        amount += amountFloatUsd * usageThisTier
        if (tierFlatFee) {
            amount += tierFlatFee
        }
        previousTier = tier
    }

    // remove discount from total price
    if (percentDiscount) {
        amount = amount * (1 - percentDiscount / 100)
    }

    return amount.toFixed(2)
}

export const convertAmountToUsage = (
    amount: string,
    productAndAddonTiers: BillingTierType[][],
    discountPercent?: number
): number => {
    if (!amount) {
        return 0
    }
    if (!productAndAddonTiers || productAndAddonTiers.length === 0) {
        return 0
    }

    const tiers = productAndAddonTiers[0].map((tier, index) => {
        const allAddonsTiers = productAndAddonTiers.slice(1)
        let totalAmount = parseFloat(tier.unit_amount_usd)
        let flatFee = parseFloat(tier.flat_amount_usd || '0')
        for (const addonTiers of allAddonsTiers) {
            totalAmount += parseFloat(addonTiers[index]?.unit_amount_usd || '0')
            flatFee += parseFloat(addonTiers[index]?.flat_amount_usd || '0')
        }
        return {
            ...tier,
            unit_amount_usd: totalAmount.toString(),
            flat_amount_usd: flatFee.toString(),
        }
    })

    let remainingAmount = parseFloat(amount)
    let usage = 0
    let previousTier: BillingTierType | undefined = undefined

    if (remainingAmount === 0) {
        if (parseFloat(tiers[0].unit_amount_usd) === 0) {
            return tiers[0].up_to || 0
        }
        return 0
    }

    // consider discounts so user knows what unit amount they'll be throttled at
    if (discountPercent) {
        remainingAmount = remainingAmount / (1 - discountPercent / 100)
    }

    const allTiersZero = tiers.every((tier) => !parseFloat(tier.unit_amount_usd))

    if (allTiersZero) {
        // Free plan - usage cannot be calculated
        return tiers[0].up_to || 0
    }

    for (const tier of tiers) {
        if (remainingAmount <= 0) {
            break
        }

        const tierUsageMax = tier.up_to ? tier.up_to - (previousTier?.up_to || 0) : Infinity
        const amountFloatUsd = parseFloat(tier.unit_amount_usd)
        const tierFlatFee = parseFloat(tier.flat_amount_usd || '0')
        const usageThisTier = Math.min(remainingAmount / amountFloatUsd, tierUsageMax)

        usage += usageThisTier
        remainingAmount -= amountFloatUsd * usageThisTier
        if (tierFlatFee) {
            remainingAmount -= tierFlatFee
        }
        previousTier = tier
    }

    return Math.round(usage)
}

export const convertLargeNumberToWords = (
    // The number to convert
    num: number | null,
    // The previous tier's number
    previousNum: number | null,
    // Whether we will be showing multiple tiers (to denote the first tier with 'first')
    multipleTiers: boolean = false,
    // The product type (to denote the unit)
    productType: BillingProductV2Type['type'] | null = null
): string => {
    if (num === null && previousNum) {
        return `${convertLargeNumberToWords(previousNum, null)} +`
    }
    if (num === null) {
        return ''
    }

    let denominator = 1
    if (num >= 1000000) {
        denominator = 1000000
    } else if (num >= 1000) {
        denominator = 1000
    }

    let prevDenominator = 1
    if (previousNum && previousNum >= 1000000) {
        prevDenominator = 1000000
    } else if (previousNum && previousNum >= 1000) {
        prevDenominator = 1000
    }

    return `${previousNum ? `${((previousNum + 1) / prevDenominator).toFixed(0)}-` : multipleTiers ? 'First ' : ''}${(
        num / denominator
    ).toFixed(0)}${denominator === 1000000 ? ' million' : denominator === 1000 ? 'k' : ''}${
        !previousNum && multipleTiers ? ` ${productType}s/mo` : ''
    }`
}

export const getProration = ({
    timeRemainingInSeconds,
    timeTotalInSeconds,
    amountUsd,
    hasActiveSubscription,
}: {
    timeRemainingInSeconds: number
    timeTotalInSeconds: number
    amountUsd?: string | null
    hasActiveSubscription?: boolean
}): {
    isProrated: boolean
    prorationAmount: string
} => {
    if (timeTotalInSeconds === 0) {
        return {
            isProrated: false,
            prorationAmount: '0.00',
        }
    }

    const prorationAmount = amountUsd ? parseInt(amountUsd) * (timeRemainingInSeconds / timeTotalInSeconds) : 0

    return {
        isProrated: hasActiveSubscription && amountUsd ? prorationAmount !== parseInt(amountUsd || '') : false,
        prorationAmount: prorationAmount.toFixed(2),
    }
}

export const getProrationMessage = (prorationAmount: string, unitAmountUsd: string | null): string => {
    return `Pay ~$${prorationAmount} today (prorated) and $${parseInt(unitAmountUsd || '0')} every month thereafter.`
}

/**
 * Formats the plan status for display, trial or not
 */
export const formatPlanStatus = (billing: BillingType | null): string => {
    if (!billing) {
        return ''
    }

    // Check for old-style active trial
    if (billing.free_trial_until && billing.free_trial_until.isAfter(dayjs())) {
        return '(trial plan)'
    }

    // Check for new-style active trial
    if (billing.trial?.status === 'active') {
        return '(trial plan)'
    }

    // Check for expired trial
    if (billing.trial?.status === 'expired' && billing.trial.expires_at) {
        return `(trial expired)`
    }

    // Regular paid plan
    if (billing.subscription_level !== 'free') {
        return '(your plan)'
    }

    return ''
}

/**
 * Formats a number as a currency string
 */
export const currencyFormatter = (value: number): string => {
    return new Intl.NumberFormat('en-US', {
        style: 'currency',
        currency: 'USD',
    }).format(value)
}

/**
 * Synchronizes URL search parameters with billing filter state.
 * Returns the appropriate router action format for kea-router.
 * Only updates the URL if parameters have actually changed.
 */
export function syncBillingSearchParams(
    router: LogicWrapper<routerType>,
    updateParams: (searchParams: Params) => Params
): [string, Params, Record<string, any>, { replace: boolean }] {
    const currentSearchParams = { ...router.values.searchParams }
    const updatedSearchParams = updateParams(currentSearchParams)
    if (!equal(updatedSearchParams, router.values.searchParams)) {
        return [router.values.location.pathname, updatedSearchParams, router.values.hashParams, { replace: true }]
    }
    return [router.values.location.pathname, router.values.searchParams, router.values.hashParams, { replace: false }]
}

/**
 * Updates a search parameter if the value differs from the default.
 * Removes the parameter entirely if it matches the default to keep URLs clean.
 */
export function updateBillingSearchParams<T>(searchParams: Params, key: string, value: T, defaultValue: T): void {
    if (!equal(value, defaultValue)) {
        searchParams[key] = value
    } else {
        delete searchParams[key]
    }
}

/**
 * Builds properties for billing usage and spend interaction events
 */
export function buildTrackingProperties(
    action: BillingUsageInteractionProps['action'],
    values: {
        filters: BillingFilters
        dateFrom: string
        dateTo: string | null
        excludeEmptySeries: boolean
        teamOptions: { key: string; label: string }[]
    },
    usageTypesTotal: number = USAGE_TYPES.length
): BillingUsageInteractionProps {
    return {
        action,
        filters: values.filters,
        date_from: values.dateFrom,
        date_to: values.dateTo,
        exclude_empty: values.excludeEmptySeries,
        usage_types_count: values.filters.usage_types?.length || 0,
        usage_types_total: usageTypesTotal,
        teams_count: values.filters.team_ids?.length || 0,
        teams_total: values.teamOptions.length,
        has_team_breakdown: (values.filters.breakdowns || []).includes('team'),
        interval: values.filters.interval || 'day',
    }
}

export const buildSpendTrackingProperties = (
    action: BillingUsageInteractionProps['action'],
    values: Parameters<typeof buildTrackingProperties>[1]
): BillingUsageInteractionProps => buildTrackingProperties(action, values, getSpendTypeOptions().length)

export const getUsageTypeOptions = (): { key: string; label: string }[] =>
    USAGE_TYPES.map((opt) => ({ key: opt.value, label: opt.label }))

export const getSpendTypeOptions = (): { key: string; label: string }[] =>
    SPEND_TYPES.map((opt) => ({ key: opt.value, label: opt.label }))

const SPEND_TYPE_VALUES = new Set<string>(SPEND_TYPES.map((option) => option.value))

export const filterSpendUsageTypes = (usageTypes: string[] | undefined): string[] =>
    usageTypes?.filter((usageType) => SPEND_TYPE_VALUES.has(usageType)) ?? []

export const isAddonVisible = (
    product: BillingProductV2Type,
    addon: BillingProductV2AddonType,
    featureFlags: Record<string, any>
): boolean => {
    // Filter out inclusion-only addons if personless events are not supported
    if (addon.inclusion_only && featureFlags[FEATURE_FLAGS.PERSONLESS_EVENTS_NOT_SUPPORTED]) {
        return false
    }

    // Filter out legacy addons for platform_and_support if not subscribed
    if (product.type === 'platform_and_support' && addon.legacy_product && !addon.subscribed) {
        return false
    }

    // Filter out addons that are hidden by feature flag
    const hideAddonFlag = `billing_hide_addon_${addon.type}`
    if (featureFlags[hideAddonFlag]) {
        return false
    }

    return true
}

/**
 * Calculate billing period markers for a given date range
 * @param billingPeriodUTC - The billing period with UTC dates (start, end, interval)
 * @param dateFrom - Start date string (can be relative like '30d' or absolute)
 * @param dateTo - End date string, or null for a range that has no end yet
 * @returns Array of billing period markers
 */
export function calculateBillingPeriodMarkers(
    billingPeriodUTC: BillingPeriod,
    dateFrom: string,
    dateTo: string | null
): Array<{ date: dayjs.Dayjs }> {
    if (!billingPeriodUTC?.start || !billingPeriodUTC?.interval) {
        return []
    }

    // Convert user dates to UTC for comparison with billingPeriodUTC. An open-ended range runs
    // to today.
    const from = dateStringToDayJs(dateFrom)?.utc() || dayjs(dateFrom).utc()
    const to = dateTo ? dateStringToDayJs(dateTo)?.utc() || dayjs(dateTo).utc() : dayjs().utc()
    const interval = billingPeriodUTC.interval

    // Find the first period start that could be visible
    const periodsSinceStart = Math.ceil(billingPeriodUTC.start.diff(from, interval))
    const firstVisiblePeriod = billingPeriodUTC.start.subtract(Math.max(0, periodsSinceStart), interval)

    // Collect all period starts within the range
    const markers = []
    let periodStart = firstVisiblePeriod

    while (periodStart.isSameOrBefore(to)) {
        if (periodStart.isSameOrAfter(from)) {
            markers.push({
                date: periodStart,
            })
        }
        periodStart = periodStart.add(1, interval)
    }

    return markers
}

/**
 * Keep up to N decimals without trailing zeros.
 * Falls back to 10 decimals for very small numbers if not specified.
 */
export const formatWithDecimals = (value: number, decimals?: number): string => {
    const needsFixedFormat = typeof decimals === 'number' || (Math.abs(value) < 1e-6 && value !== 0)

    return needsFixedFormat
        ? value
              .toFixed(decimals ?? 10)
              .replace(/0+$/, '')
              .replace(/\.$/, '')
        : String(value)
}

/**
 * Formats a tier's unit price, scaled to the product's display unit when it has one (e.g. per-MB → per-GB).
 */
export const formatTierPrice = (
    unitAmountUsd: string | null | undefined,
    product: BillingProductV2Type | BillingProductV2AddonType
): string => {
    const price = parseFloat(unitAmountUsd || '0')
    if (hasDisplayFormatting(product) && product.display_divisor) {
        // Per-unit prices are stored rounded, so scaling leaves residue: 0.00000166666667 * 30000 = 0.0500000001.
        return `$${formatWithDecimals(price * product.display_divisor, 8)}`
    }
    return `$${formatWithDecimals(price)}`
}

/**
 * Whether a project selection covers every project there is, in which case it is not a filter.
 *
 * Sending it as one puts every project id into the query string and into the URL the person is
 * looking at. Omitting it means the same thing, because the API treats an absent project filter
 * as every project.
 */
export function selectionCoversEveryProject(teamIds: number[] | undefined, options: { key: string }[]): boolean {
    if (!teamIds?.length || !options.length) {
        return false
    }
    const selected = new Set(teamIds.map(String))
    return options.every((option) => selected.has(option.key))
}

/**
 * What the page says when billing refuses or cancels a breakdown. Billing's own `detail` is
 * written for API callers - it talks about paging - so the page carries its own sentence per
 * code and falls back to billing's text for a code it does not know.
 */
export function billingErrorGuidance(error: { code: string; detail: string }): string {
    switch (error.code) {
        case 'usage_query_timeout':
            return 'This took too long to load. Select fewer projects or products, choose a shorter date range, or export it instead.'
        case 'usage_breakdown_too_large':
            return 'This breakdown is too large to show at once. Select fewer projects or products, choose a shorter date range or a coarser interval, or export it instead - an export streams, so it has no such limit.'
        default:
            return error.detail
    }
}