📈 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
Improve event billing counting
Blue Mouseade1804fbcf9
diff --git a/backend/apps/cloud/src/analytics/analytics.service.ts b/backend/apps/cloud/src/analytics/analytics.service.tsindex 1bcf1d0e0..fbeb9412e 100644--- a/backend/apps/cloud/src/analytics/analytics.service.ts+++ b/backend/apps/cloud/src/analytics/analytics.service.ts@@ -2390,6 +2390,10 @@ export class AnalyticsService {await Promise.all(commands)+ if (!_isEmpty(eventTableTypes)) {+ await this.projectService.refreshUsageAfterDeletion(pid)+ }+// Session replays live in their own table + object storage, so they are// removed on a dedicated path after the events-table mutations settle.if (_includes(safeTypes, 'session_replay')) {diff --git a/backend/apps/cloud/src/common/constants.ts b/backend/apps/cloud/src/common/constants.tsindex 917cf3403..1849c8f3a 100644--- a/backend/apps/cloud/src/common/constants.ts+++ b/backend/apps/cloud/src/common/constants.ts@@ -3,6 +3,7 @@ import path from 'path'import _toNumber from 'lodash/toNumber'import 'dotenv/config'import { deriveKey, hash } from './utils'+import { TRAFFIC_SPIKE_ALLOWED_PERCENTAGE } from '../user/plan-usage'const { EMAIL_ACTION_ENCRYPTION_KEY } = process.env@@ -73,8 +74,6 @@ const CAPTCHA_SECRET_KEY_LENGTH = 50const MIN_PAGES_IN_FUNNEL = 2const MAX_PAGES_IN_FUNNEL = 10-const TRAFFIC_SPIKE_ALLOWED_PERCENTAGE = 0.3-const BLOG_POSTS_PATH = isDevelopment? path.join(__dirname, '../../../..', 'blog-posts', 'posts'): path.join(__dirname, '../..', 'blog-posts', 'posts')diff --git a/backend/apps/cloud/src/common/templates/en/dashboard-locked-exceeding-limits.html b/backend/apps/cloud/src/common/templates/en/dashboard-locked-exceeding-limits.htmlindex 880d048f7..8dc06b04d 100644--- a/backend/apps/cloud/src/common/templates/en/dashboard-locked-exceeding-limits.html+++ b/backend/apps/cloud/src/common/templates/en/dashboard-locked-exceeding-limits.html@@ -1,6 +1,6 @@-We emailed you a week ago because your traffic exceeded your Swetrix+We emailed you at least {{upgradePeriodDays}} days ago because your traffic exceeded your Swetrixsubscription{{#if hitPercentageLimit}} by more than {{percentageLimit}}% this-month{{else}} for two months in a row{{/if}}. <br /><br />+month{{else}} by more than {{repeatedPercentageLimit}}% for two months in a row{{/if}}. <br /><br />Your dashboard is now temporarily locked. Your subscription is still active,we're still collecting stats, and we haven't deleted any data. Upgrade to a planthat matches your traffic to restore dashboard access. You can find the usage@@ -13,4 +13,6 @@ to this email and we'll help you choose a plan for your traffic.{{suggestedPlanLimit}} events per month plan. Your upgrade will be proratedbased on what you've already paid for your current plan.<br /><br />-{{/ifNotEquals}} Reply to this email if you have questions or need help.+{{/ifNotEquals}} If unwanted traffic caused the overage, you can delete it in your+project settings. We will recheck your usage and restore access if it no longer+exceeds the allowance rules. Reply to this email if you have questions or need help.diff --git a/backend/apps/cloud/src/common/templates/en/usage-over-limit.html b/backend/apps/cloud/src/common/templates/en/usage-over-limit.htmlindex bc7ddf6ee..843dc7b1f 100644--- a/backend/apps/cloud/src/common/templates/en/usage-over-limit.html+++ b/backend/apps/cloud/src/common/templates/en/usage-over-limit.html@@ -2,18 +2,18 @@ Hi, thanks for {{#ifEquals user.planCode "trial"}}tryingSwetrix{{/ifEquals}}{{#ifNotEquals user.planCode "trial"}}being a Swetrixsubscriber{{/ifNotEquals}}. <br /><br />Your traffic has exceeded your subscription plan{{#if hitPercentageLimit}} by-more than {{percentageLimit}}% this month{{else}} for two months in a+more than {{percentageLimit}}% this month{{else}} by more than {{repeatedPercentageLimit}}% for two months in arow{{/if}}.<br /><br />Please upgrade within {{upgradePeriodDays}} days to keep dashboard access. If-you don't upgrade by then, your dashboard will be temporarily locked. We'll keep+your usage still exceeds the allowance rules then, your dashboard will be temporarily locked. We'll keepcollecting data and won't delete your existing data.<br /><br />{{#if hitPercentageLimit}} This month, you have used {{thisMonthUsage}} billableevents, more than {{percentageLimit}}% over your plan limit. {{else}} Thismonth, you have used {{thisMonthUsage}} billable events. Last month, you used{{lastMonthUsage}} events. {{/if}} Billable events include pageviews, custom-events, and CAPTCHA events. You can see the full usage report on the+events, errors, and successful CAPTCHA verifications. You can see the full usage report on the<a href="{{billingUrl}}" target="_blank">billing page</a>. <br /><br />{{#ifEquals user.planCode "10m"}} Your usage is above our standard plans. Replyto this email and we'll help you choose a plan for your traffic.@@ -22,4 +22,6 @@ to this email and we'll help you choose a plan for your traffic.{{suggestedPlanLimit}} events per month plan. Your upgrade will be proratedbased on what you've already paid for your current plan.<br /><br />-{{/ifNotEquals}} Reply to this email if you have questions or need help.+{{/ifNotEquals}} If unwanted traffic caused the overage, you can delete it in your+project settings. We will recheck your usage and clear the warning if it no longer+exceeds the allowance rules. Reply to this email if you have questions or need help.diff --git a/backend/apps/cloud/src/project/plan-usage.spec.ts b/backend/apps/cloud/src/project/plan-usage.spec.tsnew file mode 100644index 000000000..2051fde57--- /dev/null+++ b/backend/apps/cloud/src/project/plan-usage.spec.ts@@ -0,0 +1,102 @@+jest.mock('../common/constants', () => ({+ redis: { del: jest.fn() },+ getRedisUserCountKey: (uid: string) => `count:${uid}`,+ getRedisUserUsageInfoKey: (uid: string) => `usage:${uid}`,+}))+jest.mock('../common/integrations/clickhouse', () => ({+ clickhouse: { query: jest.fn() },+}))+jest.mock('../user/user.service', () => ({ UserService: class {} }))+jest.mock('../mailer/mailer.service', () => ({ MailerService: class {} }))+jest.mock('../common/utils', () => ({}))++import dayjs from 'dayjs'+import { ProjectService } from './project.service'+import { clickhouse } from '../common/integrations/clickhouse'+import { redis } from '../common/constants'+import {+ DashboardBlockReason,+ PlanCode,+ User,+} from '../user/entities/user.entity'++describe('usage after traffic cleanup', () => {+ let service: ProjectService+ let user: User+ let userService: { findOne: jest.Mock; updatePlanUsageState: jest.Mock }++ beforeEach(() => {+ jest.clearAllMocks()+ user = {+ id: 'owner',+ planCode: PlanCode['200k'],+ projects: [{ id: 'project00001' }, { id: 'project00002' }],+ planExceedContactedAt: new Date('2026-09-01T00:00:00Z'),+ dashboardBlockReason: DashboardBlockReason.exceeding_plan_limits,+ } as User+ userService = {+ findOne: jest.fn().mockResolvedValue(user),+ updatePlanUsageState: jest.fn().mockResolvedValue(true),+ }+ service = Object.assign(Object.create(ProjectService.prototype), {+ userService,+ })+ service.findOne = jest.fn().mockResolvedValue({ admin: { id: 'owner' } })+ service.clearProjectsRedisCache = jest.fn()+ jest.mocked(clickhouse.query).mockResolvedValue({+ json: async () => ({ data: [{ current: '210000', previous: '250000' }] }),+ } as never)+ })++ it('clears all cached totals and resolves an existing usage lock', async () => {+ await service.refreshUsageAfterDeletion('project00001')+ expect(redis.del).toHaveBeenCalledWith(+ 'count:owner',+ 'usage:owner',+ 'usage:owner_last30d',+ )+ expect(userService.updatePlanUsageState).toHaveBeenCalledWith(user, {+ planExceedContactedAt: null,+ dashboardBlockReason: null,+ })+ expect(service.clearProjectsRedisCache).toHaveBeenCalledWith('owner')+ })++ it('clears a pending warning before the grace period ends', async () => {+ user.dashboardBlockReason = null+ await service.refreshUsageAfterDeletion('project00001')+ expect(userService.updatePlanUsageState).toHaveBeenCalledTimes(1)+ })++ it('preserves the warning if remaining traffic still exceeds either rule', async () => {+ jest.mocked(clickhouse.query).mockResolvedValue({+ json: async () => ({ data: [{ current: 230000, previous: 230000 }] }),+ } as never)+ await service.refreshUsageAfterDeletion('project00001')+ expect(userService.updatePlanUsageState).not.toHaveBeenCalled()+ })++ it('uses both UTC calendar months, all owned projects, and excludes imported events', async () => {+ await service.getPlanUsage(user, dayjs.utc('2026-09-25'))+ const query = jest.mocked(clickhouse.query).mock.calls[0][0]+ expect(query.query_params).toEqual({+ pids: ['project00001', 'project00002'],+ previousMonthStart: '2026-08-01 00:00:00',+ monthStart: '2026-09-01 00:00:00',+ nextMonthStart: '2026-10-01 00:00:00',+ })+ expect(query.query).toContain('importID IS NULL')+ expect(query.query).toContain("'pageview', 'custom_event', 'error'")+ expect(query.query).toContain("= 'pass'")+ })++ it('does not resolve usage restrictions when the usage query fails', async () => {+ jest+ .mocked(clickhouse.query)+ .mockRejectedValue(new Error('ClickHouse unavailable'))+ await expect(+ service.refreshUsageAfterDeletion('project00001'),+ ).rejects.toThrow('ClickHouse unavailable')+ expect(userService.updatePlanUsageState).not.toHaveBeenCalled()+ })+})diff --git a/backend/apps/cloud/src/project/project.service.ts b/backend/apps/cloud/src/project/project.service.tsindex 8fa50b6dd..78f8b03e8 100644--- a/backend/apps/cloud/src/project/project.service.ts+++ b/backend/apps/cloud/src/project/project.service.ts@@ -80,9 +80,14 @@ import { CreateProjectViewDto } from './dto/create-project-view.dto'import { Organisation } from '../organisation/entity/organisation.entity'import { OrganisationRole } from '../organisation/entity/organisation-member.entity'import {+ ACCOUNT_PLANS,+ DashboardBlockReason,+ PlanCode,PlanFeatureCode,+ User,userHasPlanFeature,} from '../user/entities/user.entity'+import { evaluatePlanUsage, PlanUsage } from '../user/plan-usage'dayjs.extend(utc)@@ -860,6 +865,100 @@ export class ProjectService {this.validateCountryBlacklist(projectDTO)}+ async getPlanUsage(user: User, now = dayjs.utc()): Promise<PlanUsage> {+ const pids = (user.projects || []).map((project) => project.id)+ let thisMonthUsage = 0+ let lastMonthUsage = 0++ for (let i = 0; i < pids.length; i += 5000) {+ const result = await clickhouse.query({+ query: `+ SELECT+ countIf(created >= {monthStart:DateTime}) AS current,+ countIf(created < {monthStart:DateTime}) AS previous+ FROM events+ WHERE pid IN ({pids:Array(FixedString(12))})+ AND (type IN ('pageview', 'custom_event', 'error') OR (${CAPTCHA_PASS_CONDITION}))+ AND importID IS NULL+ AND created >= {previousMonthStart:DateTime}+ AND created < {nextMonthStart:DateTime}+ `,+ query_params: {+ pids: pids.slice(i, i + 5000),+ monthStart: now.startOf('month').format('YYYY-MM-DD HH:mm:ss'),+ previousMonthStart: now+ .subtract(1, 'month')+ .startOf('month')+ .format('YYYY-MM-DD HH:mm:ss'),+ nextMonthStart: now+ .add(1, 'month')+ .startOf('month')+ .format('YYYY-MM-DD HH:mm:ss'),+ },+ })+ const { data } = await result.json<{+ current: string | number+ previous: string | number+ }>()+ thisMonthUsage += Number(data[0]?.current || 0)+ lastMonthUsage += Number(data[0]?.previous || 0)+ }++ return evaluatePlanUsage(+ ACCOUNT_PLANS[user.planCode].monthlyUsageLimit,+ thisMonthUsage,+ lastMonthUsage,+ )+ }++ async clearResolvedPlanUsage(user: User, usage: PlanUsage): Promise<void> {+ if (+ usage.exceedsLimit ||+ (!user.planExceedContactedAt && !user.dashboardBlockReason)+ ) {+ return+ }++ if (+ await this.userService.updatePlanUsageState(user, {+ planExceedContactedAt: null,+ dashboardBlockReason: null,+ })+ ) {+ await this.clearProjectsRedisCache(user.id)+ }+ }++ async refreshUsageAfterDeletion(pid: string): Promise<void> {+ const project = await this.findOne({+ where: { id: pid },+ relations: ['admin'],+ })+ if (!project?.admin) return++ const uid = project.admin.id+ await redis.del(+ getRedisUserCountKey(uid),+ getRedisUserUsageInfoKey(uid),+ `${getRedisUserUsageInfoKey(uid)}_last30d`,+ )++ const user = await this.userService.findOne({+ where: { id: uid },+ relations: ['projects'],+ })+ if (+ !user ||+ [PlanCode.none, PlanCode.trial].includes(user.planCode) ||+ (!user.planExceedContactedAt &&+ user.dashboardBlockReason !==+ DashboardBlockReason.exceeding_plan_limits)+ )+ return++ await this.clearResolvedPlanUsage(user, await this.getPlanUsage(user))+ }+// Returns amount of existing events starting from monthasync getRedisCount(uid: string): Promise<number | null> {const countKey = getRedisUserCountKey(uid)diff --git a/backend/apps/cloud/src/task-manager/plan-usage.spec.ts b/backend/apps/cloud/src/task-manager/plan-usage.spec.tsnew file mode 100644index 000000000..6ad8b0a89--- /dev/null+++ b/backend/apps/cloud/src/task-manager/plan-usage.spec.ts@@ -0,0 +1,148 @@+jest.mock('../alert/alert.service', () => ({}))+jest.mock('../integrations/telegram/telegram.service', () => ({}))+jest.mock('../user/user.service', () => ({}))+jest.mock('../project/project.service', () => ({}))+jest.mock('../action-tokens/action-tokens.service', () => ({}))+jest.mock('../analytics/analytics.service', () => ({}))+jest.mock('../analytics/salt.service', () => ({}))+jest.mock('../goal/goal.service', () => ({}))+jest.mock('../logger/logger.service', () => ({}))+jest.mock('../integrations/discord/discord.service', () => ({}))+jest.mock('../integrations/slack/slack.service', () => ({}))+jest.mock('../revenue/revenue.service', () => ({}))+jest.mock('../revenue/adapters/paddle.adapter', () => ({}))+jest.mock('../revenue/adapters/stripe.adapter', () => ({}))+jest.mock('../project/proxy-domain.service', () => ({}))+jest.mock(+ '../notification-channel/dispatchers/channel-dispatcher.service',+ () => ({}),+)+jest.mock('../notification-channel/template-renderer.service', () => ({}))+jest.mock('../mailer/mailer.service', () => ({}))+jest.mock('../common/utils', () => ({}))+jest.mock('../common/constants', () => ({}))+jest.mock('../common/integrations/clickhouse', () => ({}))++import { TaskManagerService } from './task-manager.service'+import { DashboardBlockReason, PlanCode } from '../user/entities/user.entity'+import { evaluatePlanUsage } from '../user/plan-usage'++const createService = (warnedAt = '2026-09-11T12:00:00Z') => {+ const user = {+ id: 'owner',+ email: '[email protected]',+ planCode: PlanCode['200k'],+ planExceedContactedAt: new Date(warnedAt),+ dashboardBlockReason: null,+ }+ const dependencies = {+ userService: {+ getUsersForLockDashboards: jest.fn().mockResolvedValue([user]),+ getUsersForPlanUsageCheck: jest.fn().mockResolvedValue([user]),+ updatePlanUsageState: jest.fn().mockResolvedValue(true),+ },+ projectService: {+ getPlanUsage: jest+ .fn()+ .mockResolvedValue(evaluatePlanUsage(200000, 270000, 270000)),+ clearResolvedPlanUsage: jest.fn(),+ clearProjectsRedisCache: jest.fn(),+ },+ mailerService: { sendEmail: jest.fn() },+ logger: { error: jest.fn() },+ }+ const service: TaskManagerService = Object.assign(+ Object.create(TaskManagerService.prototype),+ dependencies,+ )+ return { service, user, ...dependencies }+}++describe('plan usage enforcement', () => {+ beforeEach(() => {+ jest.useFakeTimers().setSystemTime(new Date('2026-09-25T12:00:00Z'))+ })+ afterEach(() => jest.useRealTimers())++ it('sends one notice when both overage rules match', async () => {+ const { service, mailerService, userService } = createService()+ await service.checkPlanUsage()+ expect(mailerService.sendEmail).toHaveBeenCalledTimes(1)+ expect(mailerService.sendEmail.mock.calls[0][2]).toMatchObject({+ hitPercentageLimit: true,+ upgradePeriodDays: 14,+ repeatedPercentageLimit: 10,+ })+ expect(userService.updatePlanUsageState).toHaveBeenCalledTimes(1)+ })++ it('does not record a warning when sending fails', async () => {+ const { service, mailerService, userService } = createService()+ mailerService.sendEmail.mockRejectedValue(new Error('mail unavailable'))+ await service.checkPlanUsage()+ expect(userService.updatePlanUsageState).not.toHaveBeenCalled()+ })++ it('clears a resolved warning instead of locking', async () => {+ const { service, user, projectService, userService, mailerService } =+ createService()+ projectService.getPlanUsage.mockResolvedValue(+ evaluatePlanUsage(200000, 200000, 270000),+ )+ await service.lockDashboards()+ expect(projectService.clearResolvedPlanUsage).toHaveBeenCalledWith(+ user,+ expect.objectContaining({ exceedsLimit: false }),+ )+ expect(userService.updatePlanUsageState).not.toHaveBeenCalled()+ expect(mailerService.sendEmail).not.toHaveBeenCalled()+ })++ it('grants a full 14 days, including previously sent warnings', async () => {+ const { service, userService } = createService('2026-09-11T12:00:01Z')+ await service.lockDashboards()+ expect(userService.updatePlanUsageState).not.toHaveBeenCalled()+ })++ it('locks only after grace when fresh usage still exceeds the rules', async () => {+ const { service, user, userService, projectService, mailerService } =+ createService()+ await service.lockDashboards()+ expect(projectService.getPlanUsage).toHaveBeenCalledTimes(1)+ expect(userService.updatePlanUsageState).toHaveBeenCalledWith(user, {+ dashboardBlockReason: DashboardBlockReason.exceeding_plan_limits,+ })+ expect(projectService.clearProjectsRedisCache).toHaveBeenCalledWith('owner')+ expect(mailerService.sendEmail).toHaveBeenCalledTimes(1)+ })++ it('does not lock or email when the account state changed concurrently', async () => {+ const { service, userService, mailerService } = createService()+ userService.updatePlanUsageState.mockResolvedValue(false)+ await service.lockDashboards()+ expect(mailerService.sendEmail).not.toHaveBeenCalled()+ })++ it('does not lock when fresh usage cannot be read', async () => {+ const { service, projectService, userService, mailerService } =+ createService()+ projectService.getPlanUsage.mockRejectedValue(+ new Error('usage unavailable'),+ )+ await service.lockDashboards()+ expect(userService.updatePlanUsageState).not.toHaveBeenCalled()+ expect(mailerService.sendEmail).not.toHaveBeenCalled()+ })++ it('reviews an existing usage lock for recovery without resending the lock email', async () => {+ const { service, user, projectService, mailerService } = createService()+ user.dashboardBlockReason = DashboardBlockReason.exceeding_plan_limits+ await service.lockDashboards()+ expect(mailerService.sendEmail).not.toHaveBeenCalled()+ projectService.getPlanUsage.mockResolvedValue(+ evaluatePlanUsage(200000, 0, 270000),+ )+ await service.lockDashboards()+ expect(projectService.clearResolvedPlanUsage).toHaveBeenCalledTimes(1)+ })+})diff --git a/backend/apps/cloud/src/task-manager/task-manager.service.ts b/backend/apps/cloud/src/task-manager/task-manager.service.tsindex 3e0f93de1..1f83d2f01 100644--- a/backend/apps/cloud/src/task-manager/task-manager.service.ts+++ b/backend/apps/cloud/src/task-manager/task-manager.service.ts@@ -17,9 +17,6 @@ import _isEmpty from 'lodash/isEmpty'import _isNull from 'lodash/isNull'import _size from 'lodash/size'import _map from 'lodash/map'-import _find from 'lodash/find'-import _includes from 'lodash/includes'-import _toNumber from 'lodash/toNumber'import _reduce from 'lodash/reduce'import _filter from 'lodash/filter'@@ -57,10 +54,13 @@ import {SEND_WARNING_AT_PERC,PROJECT_INVITE_EXPIRE,JWT_REFRESH_TOKEN_LIFETIME,- TRAFFIC_SPIKE_ALLOWED_PERCENTAGE,} from '../common/constants'import { clickhouse } from '../common/integrations/clickhouse'-import { CHPlanUsage } from './interfaces'+import {+ PLAN_USAGE_GRACE_DAYS,+ REPEATED_OVERAGE_ALLOWED_PERCENTAGE,+ TRAFFIC_SPIKE_ALLOWED_PERCENTAGE,+} from '../user/plan-usage'import {getRandomTip,isPrimaryClusterNode,@@ -239,160 +239,6 @@ const formatBillingDateForEmail = (})} UTC`}-const generatePlanUsageQueryForUser = (): string => {- // NOTE: keep all values parameterized to avoid injection and formatting issues.- // Counts every billable event kind (pageview, custom_event, error, captcha)- // in a single scan over the unified events table.- return `- SELECT- {uid:String} AS id,- countIf(type IN ('pageview', 'custom_event', 'error') OR (${CAPTCHA_PASS_CONDITION})) AS "count"- FROM events- WHERE pid IN ({pids:Array(FixedString(12))})- AND type IN ('pageview', 'custom_event', 'error', 'captcha')- AND importID IS NULL- AND created BETWEEN {from:String} AND {to:String}- `-}--const executeChunkedQueries = async (- users: User[],- getFromDate: (user?: User) => string,- getToDate: (user?: User) => string,-): Promise<CHPlanUsage[]> => {- return mapLimit(users, 5, async (user) => {- if (_isEmpty(user.projects)) {- return {- id: user.id,- count: 0,- }- }-- const pids = _map(user.projects, (p) => p.id)- let totalCount = 0- const from = getFromDate(user)- const to = getToDate(user)-- // Process project IDs in chunks- for (let i = 0; i < pids.length; i += CHUNK_SIZE) {- const pidChunk = pids.slice(i, i + CHUNK_SIZE)- const query = generatePlanUsageQueryForUser()-- const { data } = await clickhouse- .query({- query,- query_params: { pids: pidChunk, uid: user.id, from, to },- })- .then((resultSet) => resultSet.json<CHPlanUsage>())-- totalCount += data[0]?.count || 0- }-- return {- id: user.id,- count: totalCount,- }- })-}--const getUsersThatExceedPlanUsage = (- users: User[],- usage: CHPlanUsage[],- allowedExceed = TRAFFIC_SPIKE_ALLOWED_PERCENTAGE,-): (User & { usage: number })[] => {- const usageMap = _reduce(- usage,- (acc, value: CHPlanUsage) => ({- ...acc,- [value.id]: value.count,- }),- {},- )- const exceedingUsers = []-- for (let i = 0; i < _size(users); ++i) {- const user = users[i]- const allowedEvents = ACCOUNT_PLANS[user.planCode].monthlyUsageLimit-- if (usageMap[user.id] > allowedEvents + allowedEvents * allowedExceed) {- exceedingUsers.push({- ...user,- usage: usageMap[user.id],- })- }- }-- return exceedingUsers-}--const getUserIDsThatExceedPlanUsage = (- users: User[],- usage: CHPlanUsage[],- allowedExceed = TRAFFIC_SPIKE_ALLOWED_PERCENTAGE,-): string[] => {- const usageMap = _reduce(- usage,- (acc, value: CHPlanUsage) => ({- ...acc,- [value.id]: value.count,- }),- {},- )- const exceedingUsers = []-- for (let i = 0; i < _size(users); ++i) {- const user = users[i]- const allowedEvents = ACCOUNT_PLANS[user.planCode].monthlyUsageLimit-- if (usageMap[user.id] > allowedEvents + allowedEvents * allowedExceed) {- exceedingUsers.push(user.id)- }- }-- return exceedingUsers-}--const getUsersThatExceedContinuously = (- users: User[],- usage: CHPlanUsage[][],-): (User & { usage: any[] })[] => {- const transformedUsage = _map(usage, (el: CHPlanUsage[]) => {- return _reduce(- el,- (acc, value: CHPlanUsage) => ({- ...acc,- [value.id]: value.count,- }),- {},- )- })-- const exceedingUsers = []-- for (let i = 0; i < _size(users); ++i) {- let exceedingTimes = 0- const user = users[i]- const allowedEvents = ACCOUNT_PLANS[user.planCode].monthlyUsageLimit- const userUsage = []-- for (let x = 0; x < _size(transformedUsage); ++x) {- userUsage.push(transformedUsage[x][user.id])- if (transformedUsage[x][user.id] > allowedEvents) {- exceedingTimes++- }- }-- if (exceedingTimes === _size(usage)) {- exceedingUsers.push({- ...user,- usage: userUsage,- })- }- }-- return exceedingUsers-}-const EMAIL_REPORTS_MAP = {[ReportFrequency.WEEKLY]: {type: 'w',@@ -1040,186 +886,86 @@ export class TaskManagerService {@Cron(CronExpression.EVERY_DAY_AT_5PM)async lockDashboards() {const users = await this.userService.getUsersForLockDashboards()+ const now = dayjs.utc()- if (_isEmpty(users)) {- return- }-- // This stuff is used solely to calculate whether the user has exceeded their limit > 30% or continuously for 2 months- const monthlyUsage = await executeChunkedQueries(- users,- (user) =>- dayjs.utc(user.planExceedContactedAt).format('YYYY-MM-01 00:00:00'),- (user) =>- dayjs- .utc(user.planExceedContactedAt)- .endOf('month')- .format('YYYY-MM-DD 23:59:59'),- )-- const exceedingUserIds = getUserIDsThatExceedPlanUsage(users, monthlyUsage)-- await Promise.allSettled(- _map(users, async (user: User) => {- const { id, email, planCode } = user+ await mapLimit(users, 5, async (user: User) => {+ try {+ const usage = await this.projectService.getPlanUsage(user, now)+ if (!usage.exceedsLimit) {+ await this.projectService.clearResolvedPlanUsage(user, usage)+ return+ }- const suggestedPlanLimit = getNextPlan(planCode)+ if (+ user.dashboardBlockReason ||+ !user.planExceedContactedAt ||+ now.isBefore(+ dayjs+ .utc(user.planExceedContactedAt)+ .add(PLAN_USAGE_GRACE_DAYS, 'days'),+ )+ )+ return- const data = {- user,- hitPercentageLimit: _includes(exceedingUserIds, user.id),- percentageLimit: TRAFFIC_SPIKE_ALLOWED_PERCENTAGE * 100,- billingUrl: 'https://swetrix.com/user-settings?tab=billing',- suggestedPlanLimit: suggestedPlanLimit?.monthlyUsageLimit,- }+ const locked = await this.userService.updatePlanUsageState(user, {+ dashboardBlockReason: DashboardBlockReason.exceeding_plan_limits,+ })+ if (!locked) return+ await this.projectService.clearProjectsRedisCache(user.id)await this.mailerService.sendEmail(- email,+ user.email,LetterTemplate.DashboardLockedExceedingLimits,- data,+ {+ user,+ hitPercentageLimit: usage.hitPercentageLimit,+ percentageLimit: TRAFFIC_SPIKE_ALLOWED_PERCENTAGE * 100,+ repeatedPercentageLimit: REPEATED_OVERAGE_ALLOWED_PERCENTAGE * 100,+ upgradePeriodDays: PLAN_USAGE_GRACE_DAYS,+ billingUrl: 'https://swetrix.com/user-settings?tab=billing',+ suggestedPlanLimit: getNextPlan(user.planCode)?.monthlyUsageLimit,+ },)- await this.userService.update(id, {- dashboardBlockReason: DashboardBlockReason.exceeding_plan_limits,- })- }),- ).catch((reason) => {- this.logger.error(- `[CRON WORKER](lockDashboards) Error occured: ${reason}`,- )+ } catch (reason) {+ this.logger.error(+ `[CRON WORKER](lockDashboards) User ${user.id}: ${reason}`,+ )+ }})}@Cron(CronExpression.EVERY_DAY_AT_4PM)async checkPlanUsage() {const users = await this.userService.getUsersForPlanUsageCheck()+ const now = dayjs.utc()- if (_isEmpty(users)) {- return- }-- const planExceedContactedAt = dayjs.utc().format('YYYY-MM-DD HH:mm:ss')-- const thisMonthStart = dayjs.utc().format('YYYY-MM-01 00:00:00')- const thisMonthEnd = dayjs- .utc()- .endOf('month')- .format('YYYY-MM-DD 23:59:59')-- const thisMonthUsage = await executeChunkedQueries(- users,- () => thisMonthStart,- () => thisMonthEnd,- )-- const exceedingUsers = getUsersThatExceedPlanUsage(users, thisMonthUsage)-- // if there are exceeding users, contact them and let them know that their usage is > than 30% their tier allows- if (!_isEmpty(exceedingUsers)) {- const percExceedingUsagePromises = _map(exceedingUsers, async (user) => {- const { id, email, usage, planCode } = user-- const suggestedPlanLimit = getNextPlan(planCode)-- const data = {- user,- hitPercentageLimit: true,- upgradePeriodDays: 7,- thisMonthUsage: usage,- percentageLimit: TRAFFIC_SPIKE_ALLOWED_PERCENTAGE * 100,- billingUrl: 'https://swetrix.com/user-settings?tab=billing',- suggestedPlanLimit: suggestedPlanLimit?.monthlyUsageLimit,- }+ await mapLimit(users, 5, async (user: User) => {+ try {+ const usage = await this.projectService.getPlanUsage(user, now)+ if (!usage.exceedsLimit) returnawait this.mailerService.sendEmail(- email,+ user.email,LetterTemplate.UsageOverLimit,- data,+ {+ user,+ ...usage,+ upgradePeriodDays: PLAN_USAGE_GRACE_DAYS,+ percentageLimit: TRAFFIC_SPIKE_ALLOWED_PERCENTAGE * 100,+ repeatedPercentageLimit: REPEATED_OVERAGE_ALLOWED_PERCENTAGE * 100,+ billingUrl: 'https://swetrix.com/user-settings?tab=billing',+ suggestedPlanLimit: getNextPlan(user.planCode)?.monthlyUsageLimit,+ },)- await this.userService.update(id, {- planExceedContactedAt,+ await this.userService.updatePlanUsageState(user, {+ planExceedContactedAt: now.toDate(),})- })-- await Promise.allSettled(percExceedingUsagePromises).catch((reason) => {+ } catch (reason) {this.logger.error(- `[CRON WORKER](checkPlanUsage - percExceedingUsagePromises) Error occured: ${reason}`,+ `[CRON WORKER](checkPlanUsage) User ${user.id}: ${reason}`,)- })- }-- const filteredUsers = _filter(- users,- (user) =>- !_find(exceedingUsers, (exceedingUser) => exceedingUser.id === user.id),- )-- if (_isEmpty(filteredUsers)) {- return- }-- const lastMonthStart = dayjs- .utc()- .subtract(1, 'M')- .format('YYYY-MM-01 00:00:00')- const lastMonthEnd = dayjs- .utc()- .subtract(1, 'M')- .endOf('month')- .format('YYYY-MM-DD 23:59:59')-- const lastMonthUsage = await executeChunkedQueries(- users,- () => lastMonthStart,- () => lastMonthEnd,- )-- const continuousExceedingUsers = getUsersThatExceedContinuously(users, [- // the order should be kept like this- thisMonthUsage,- lastMonthUsage,- ])-- // if there are exceeding users, contact them and let them know that their usage more then what their tier allows for two consequetive months- if (!_isEmpty(continuousExceedingUsers)) {- const continuousExceedingUsagePromises = _map(- continuousExceedingUsers,- async (user) => {- const { id, email, usage, planCode } = user-- const [userThisMonthUsage, userLastMonthUsage] = usage || []-- const suggestedPlanLimit = getNextPlan(planCode)-- const data = {- user,- hitPercentageLimit: false,- upgradePeriodDays: 7,- thisMonthUsage: userThisMonthUsage,- lastMonthUsage: userLastMonthUsage,- percentageLimit: TRAFFIC_SPIKE_ALLOWED_PERCENTAGE * 100,- billingUrl: 'https://swetrix.com/user-settings?tab=billing',- suggestedPlanLimit: suggestedPlanLimit?.monthlyUsageLimit,- }-- await this.mailerService.sendEmail(- email,- LetterTemplate.UsageOverLimit,- data,- )- await this.userService.update(id, {- planExceedContactedAt,- })- },- )-- await Promise.allSettled(continuousExceedingUsagePromises).catch(- (reason) => {- this.logger.error(- `[CRON WORKER](checkPlanUsage - continuousExceedingUsagePromises) Error occured: ${reason}`,- )- },- )- }+ }+ })}@Cron(CronExpression.EVERY_DAY_AT_9AM)diff --git a/backend/apps/cloud/src/user/plan-usage-state.spec.ts b/backend/apps/cloud/src/user/plan-usage-state.spec.tsnew file mode 100644index 000000000..4de2c46cd--- /dev/null+++ b/backend/apps/cloud/src/user/plan-usage-state.spec.ts@@ -0,0 +1,62 @@+jest.mock('../common/constants', () => ({ redis: {} }))+jest.mock('../organisation/organisation.service', () => ({+ OrganisationService: class {},+}))++import { UserService } from './user.service'+import { DashboardBlockReason, PlanCode, User } from './entities/user.entity'++describe('guarded plan usage state changes', () => {+ it.each([+ DashboardBlockReason.payment_failed,+ DashboardBlockReason.subscription_cancelled,+ DashboardBlockReason.trial_ended,+ ])('never clears a %s restriction', async (reason) => {+ const update = jest.fn()+ const service: UserService = Object.assign(+ Object.create(UserService.prototype),+ {+ usersRepository: { update },+ },+ )+ expect(+ await service.updatePlanUsageState(+ { dashboardBlockReason: reason } as User,+ {+ dashboardBlockReason: null,+ planExceedContactedAt: null,+ },+ ),+ ).toBe(false)+ expect(update).not.toHaveBeenCalled()+ })++ it('only updates the observed plan, warning and lock state', async () => {+ const update = jest.fn().mockResolvedValue({ affected: 0 })+ const service: UserService = Object.assign(+ Object.create(UserService.prototype),+ {+ usersRepository: { update },+ },+ )+ const warnedAt = new Date('2026-09-01T00:00:00Z')+ expect(+ await service.updatePlanUsageState(+ {+ id: 'owner',+ planCode: PlanCode['200k'],+ planExceedContactedAt: warnedAt,+ dashboardBlockReason: DashboardBlockReason.exceeding_plan_limits,+ } as User,+ { dashboardBlockReason: null, planExceedContactedAt: null },+ ),+ ).toBe(false)+ expect(update.mock.calls[0][0]).toMatchObject({+ id: 'owner',+ planCode: '200k',+ planExceedContactedAt: expect.objectContaining({ _value: warnedAt }),+ dashboardBlockReason: DashboardBlockReason.exceeding_plan_limits,+ isAccountBillingSuspended: false,+ })+ })+})diff --git a/backend/apps/cloud/src/user/plan-usage.spec.ts b/backend/apps/cloud/src/user/plan-usage.spec.tsnew file mode 100644index 000000000..211cdf6f0--- /dev/null+++ b/backend/apps/cloud/src/user/plan-usage.spec.ts@@ -0,0 +1,24 @@+import { evaluatePlanUsage } from './plan-usage'++describe('plan usage tolerance', () => {+ it.each([+ [200000, 200000, false, false],+ [200001, 200001, false, false],+ [220000, 220000, false, false],+ [220001, 220000, false, false],+ [220000, 220001, false, false],+ [220001, 220001, true, false],+ [260000, 0, false, false],+ [260001, 0, true, true],+ [260001, 260001, true, true],+ [0, 300000, false, false],+ ])(+ 'evaluates current %i / previous %i',+ (current, previous, exceedsLimit, hitPercentageLimit) => {+ expect(evaluatePlanUsage(200000, current, previous)).toMatchObject({+ exceedsLimit,+ hitPercentageLimit,+ })+ },+ )+})diff --git a/backend/apps/cloud/src/user/plan-usage.ts b/backend/apps/cloud/src/user/plan-usage.tsnew file mode 100644index 000000000..dc53a9780--- /dev/null+++ b/backend/apps/cloud/src/user/plan-usage.ts@@ -0,0 +1,26 @@+export const TRAFFIC_SPIKE_ALLOWED_PERCENTAGE = 0.3+export const REPEATED_OVERAGE_ALLOWED_PERCENTAGE = 0.1+export const PLAN_USAGE_GRACE_DAYS = 14++export function evaluatePlanUsage(+ limit: number,+ thisMonthUsage: number,+ lastMonthUsage: number,+) {+ const hitPercentageLimit =+ thisMonthUsage > Math.floor(limit * (1 + TRAFFIC_SPIKE_ALLOWED_PERCENTAGE))+ const repeatedLimit = Math.floor(+ limit * (1 + REPEATED_OVERAGE_ALLOWED_PERCENTAGE),+ )+ const repeatedOverage =+ thisMonthUsage > repeatedLimit && lastMonthUsage > repeatedLimit++ return {+ thisMonthUsage,+ lastMonthUsage,+ hitPercentageLimit,+ exceedsLimit: hitPercentageLimit || repeatedOverage,+ }+}++export type PlanUsage = ReturnType<typeof evaluatePlanUsage>diff --git a/backend/apps/cloud/src/user/user.service.ts b/backend/apps/cloud/src/user/user.service.tsindex f53aac651..781c4a9df 100644--- a/backend/apps/cloud/src/user/user.service.ts+++ b/backend/apps/cloud/src/user/user.service.ts@@ -7,6 +7,7 @@ import {import { InjectRepository } from '@nestjs/typeorm'import {EntityManager,+ Equal,FindManyOptions,FindOneOptions,In,@@ -29,6 +30,7 @@ import _toNumber from 'lodash/toNumber'import { Pagination, PaginationOptionsInterface } from '../common/pagination'import {User,+ DashboardBlockReason,ACCOUNT_PLANS,TRIAL_DURATION,BillingFrequency,@@ -331,6 +333,36 @@ export class UserService {return this.usersRepository.update({ id }, update)}+ async updatePlanUsageState(+ user: User,+ update: Partial<+ Pick<User, 'planExceedContactedAt' | 'dashboardBlockReason'>+ >,+ ): Promise<boolean> {+ if (+ user.dashboardBlockReason &&+ user.dashboardBlockReason !== DashboardBlockReason.exceeding_plan_limits+ ) {+ return false+ }++ const result = await this.usersRepository.update(+ {+ id: user.id,+ planCode: user.planCode,+ planExceedContactedAt: user.planExceedContactedAt+ ? Equal(user.planExceedContactedAt)+ : IsNull(),+ dashboardBlockReason: user.dashboardBlockReason || IsNull(),+ isActive: true,+ isAccountBillingSuspended: false,+ cancellationEffectiveDate: IsNull(),+ },+ update,+ )+ return result.affected === 1+ }+async updateByEmail(email: string,update: Record<string, unknown>,@@ -3321,40 +3353,32 @@ export class UserService {}async getUsersForLockDashboards() {- const sevenDaysAgo = dayjs- .utc()- .subtract(7, 'days')- .format('YYYY-MM-DD HH:mm:ss')-- // First get the user IDs that have at least one project- const userIds = await this.usersRepository+ return this.usersRepository.createQueryBuilder('user')- .leftJoin('user.projects', 'p')- .select('user.id')+ .leftJoinAndSelect('user.projects', 'projects')+ .select([+ 'user.id',+ 'user.email',+ 'user.planCode',+ 'user.planExceedContactedAt',+ 'user.dashboardBlockReason',+ 'projects.id',+ ]).where({isActive: true,planCode: Not(In([PlanCode.none, PlanCode.trial])),- planExceedContactedAt: LessThan(sevenDaysAgo),- dashboardBlockReason: IsNull(),isAccountBillingSuspended: false,cancellationEffectiveDate: IsNull(),})- .groupBy('user.id')- .having('COUNT(p.id) > 0')- .getMany()-- if (_isEmpty(userIds)) {- return []- }-- // Then fetch those users with their projects- return this.usersRepository- .createQueryBuilder('user')- .leftJoinAndSelect('user.projects', 'projects')- .select(['user.id', 'user.email', 'user.planCode', 'projects.id'])- .where('user.id IN (:...userIds)', {- userIds: userIds.map((u) => u.id),- })+ .andWhere(+ '(user.dashboardBlockReason IS NULL OR user.dashboardBlockReason = :usageBlock)',+ {+ usageBlock: DashboardBlockReason.exceeding_plan_limits,+ },+ )+ .andWhere(+ '(user.planExceedContactedAt IS NOT NULL OR user.dashboardBlockReason = :usageBlock)',+ ).getMany()}diff --git a/docs/content/docs/billing/exceeding-plan-limits.mdx b/docs/content/docs/billing/exceeding-plan-limits.mdxindex 41341f5ad..16cba1da8 100644--- a/docs/content/docs/billing/exceeding-plan-limits.mdx+++ b/docs/content/docs/billing/exceeding-plan-limits.mdx@@ -9,21 +9,33 @@ description: "Understand what happens when your Swetrix usage exceeds your plantraffic spike. There are no hidden charges and we won't charge your card unexpectedly.</Callout>-If you exceed your subscription plan, we won't automatically upgrade you to the next one because it's unethical.+## Traffic spikes and repeated overages-We may block your dashboard if:+Usage is measured by calendar month in UTC, including for annual subscriptions. We allow occasional traffic spikes of up to 30% above your monthly event allowance at no extra charge.-- You exceed your subscription plan for two consecutive months, or-- You exceed your event quota by more than 30%.+We will ask you to choose a higher event tier if:-If this happens, we will not lock your dashboard immediately. Instead, we will give you 7 days notice that your traffic has exceeded your subscription tier and provide you with information on how to resolve the issue.+- Your usage in the current month is more than 30% above your allowance, or+- Your usage is more than 10% above your allowance in both the current and previous month.-We may also lock your dashboard if you miss a bill. We will lock the dashboard after 5 failed attempts.+For example, on the 200,000-event plan, an occasional month of up to 260,000 events is allowed. The repeated-overage rule applies only when usage exceeds 220,000 events in each of two consecutive months.++## Notice before dashboard restrictions++If either threshold is exceeded, we email you and give you 14 days to choose a suitable tier. We do not automatically upgrade your plan or charge overage fees.++Before restricting dashboard access, we check your usage again against both rules. If your usage no longer meets either condition, we clear the warning. We also review existing usage restrictions daily and restore access when neither condition applies.<Callout>- If your dashboard is locked because of billing or plan limits, new analytics events are not- accepted until the issue is resolved. Existing analytics data is kept. Once you upgrade to an- appropriate tier or resolve the payment issue, dashboard access and collection are restored.+ Exceeding your event allowance does not stop analytics collection. Even if dashboard access is+ restricted for exceeding plan limits, we continue collecting analytics and keep your existing+ data. Upgrading to a suitable event tier restores dashboard access.</Callout>+## Bots and unwanted traffic++Requests blocked by [bot protection](/bot-protection) do not count towards your allowance. Imported historical data is also excluded.++If unwanted events get through, you can delete them in your project settings. Once deletion completes, those events are removed from usage calculations and cached usage totals are cleared. We recheck your allowance and clear any usage warning or usage-related dashboard restriction if neither overage condition still applies. This does not clear restrictions caused by payment issues or cancellation.+If you need a higher event volume, choose a larger event tier from the [Plan and billing](https://swetrix.com/user-settings?tab=billing) page. For very high traffic or custom limits, choose Enterprise or [contact us](https://swetrix.com/contact).diff --git a/docs/content/docs/data-import.mdx b/docs/content/docs/data-import.mdxindex 5ffba3864..0752874d1 100644--- a/docs/content/docs/data-import.mdx+++ b/docs/content/docs/data-import.mdx@@ -7,6 +7,8 @@ description: Import historical analytics data from third-party platforms into SwSwetrix allows you to import historical analytics data from other platforms so you can switch without losing your history. Imported data appears alongside your live-tracked data in dashboards, charts, and reports. It's tagged internally so it can be identified and, if needed, removed later without affecting your live-tracked data.+Imported pageviews and custom events are free and do not count towards your plan's event allowance or billable usage, even when their dates fall within the current billing period.+## Import InstructionsSelect your analytics provider below to see the step-by-step import guide.