The Open Source DocuSign Alternative.
TypeScript digital-signaturedocument-signingdocusign-alternativee-signatureesignesignaturenext-authnextjsopen-sourcepades-standardpdfpdf-signpdf-signaturepostgresqlprismaself-hostedsigningtypescript
fix: add early quota warning (#2986)
David Nguyen15549a675895
diff --git a/apps/remix/app/components/general/organisations/organisation-quota-banner.tsx b/apps/remix/app/components/general/organisations/organisation-quota-banner.tsxindex c25f23bb3..b2a5e1a93 100644--- a/apps/remix/app/components/general/organisations/organisation-quota-banner.tsx+++ b/apps/remix/app/components/general/organisations/organisation-quota-banner.tsx@@ -3,6 +3,7 @@ import { SUPPORT_EMAIL } from '@documenso/lib/constants/app';import { DO_NOT_INVALIDATE_QUERY_ON_MUTATION, SKIP_QUERY_BATCH_META } from '@documenso/lib/constants/trpc';import { INTERNAL_CLAIM_ID } from '@documenso/lib/types/subscription';import { trpc } from '@documenso/trpc/react';+import { cn } from '@documenso/ui/lib/utils';import { Alert, AlertDescription } from '@documenso/ui/primitives/alert';import { Button } from '@documenso/ui/primitives/button';import {@@ -38,12 +39,18 @@ export const OrganisationQuotaBanner = () => {quotaFlags?.isDocumentQuotaExceeded || quotaFlags?.isEmailQuotaExceeded || quotaFlags?.isApiQuotaExceeded,);- // Every member of the organisation sees the banner when a quota is exhausted.+ const isAnyQuotaNearing = Boolean(+ quotaFlags?.isDocumentQuotaNearing || quotaFlags?.isEmailQuotaNearing || quotaFlags?.isApiQuotaNearing,+ );++ // Every member of the organisation sees the banner when a quota is exhausted or+ // nearing its limit. When both states apply, "exceeded" wins for the banner copy+ // and the dialog lists both exceeded and nearing items.// Note: Skipping free plan banner for now because their quota can incorrectly show as exceeded.if (!organisation ||!quotaFlags ||- !isAnyQuotaExceeded ||+ (!isAnyQuotaExceeded && !isAnyQuotaNearing) ||organisation.organisationClaim.originalSubscriptionClaimId === INTERNAL_CLAIM_ID.FREE) {return null;@@ -51,17 +58,29 @@ export const OrganisationQuotaBanner = () => {return (<>- <div className="bg-yellow-200 text-yellow-900 dark:bg-yellow-400">+ <div+ className={cn({+ 'bg-yellow-200 text-yellow-900 dark:bg-yellow-400': !isAnyQuotaExceeded,+ 'bg-destructive text-destructive-foreground': isAnyQuotaExceeded,+ })}+ ><div className="mx-auto flex max-w-screen-xl items-center justify-center gap-x-4 px-4 py-2 font-medium text-sm"><div className="flex items-center"><AlertTriangle className="mr-2.5 h-5 w-5" />- <Trans>Your organisation has exceeded a fair use limit</Trans>+ {isAnyQuotaExceeded ? (+ <Trans>Your organisation has exceeded a fair use limit</Trans>+ ) : (+ <Trans>Your organisation is approaching a fair use limit</Trans>+ )}</div><Buttonvariant="outline"- className="text-yellow-900 hover:bg-yellow-100 dark:hover:bg-yellow-500"+ className={cn({+ 'text-yellow-900 hover:bg-yellow-100 dark:hover:bg-yellow-500': !isAnyQuotaExceeded,+ 'text-destructive-foreground hover:bg-destructive hover:text-white': isAnyQuotaExceeded,+ })}onClick={() => setIsOpen(true)}size="sm">@@ -74,17 +93,27 @@ export const OrganisationQuotaBanner = () => {<DialogContent><DialogHeader><DialogTitle>- <Trans>Fair use limit exceeded</Trans>+ {isAnyQuotaExceeded ? <Trans>Fair use limit exceeded</Trans> : <Trans>Approaching fair use limit</Trans>}</DialogTitle><DialogDescription>- <Trans>- Your organisation has exceeded a fair use limit. Please contact{' '}- <a className="text-primary" href={`mailto:${SUPPORT_EMAIL}`}>- support- </a>{' '}- to review your plan's limits.- </Trans>+ {isAnyQuotaExceeded ? (+ <Trans>+ Your organisation has exceeded a fair use limit. Please contact{' '}+ <a className="text-primary" href={`mailto:${SUPPORT_EMAIL}`}>+ support+ </a>{' '}+ to review your plan's limits.+ </Trans>+ ) : (+ <Trans>+ Your organisation is approaching a fair use limit. If you expect to need higher limits, please contact{' '}+ <a className="text-primary" href={`mailto:${SUPPORT_EMAIL}`}>+ support+ </a>{' '}+ to review your plan's limits.+ </Trans>+ )}</DialogDescription></DialogHeader>@@ -106,6 +135,21 @@ export const OrganisationQuotaBanner = () => {<Trans>API requests have been temporarily paused</Trans></li>)}+ {quotaFlags.isDocumentQuotaNearing && (+ <li className="list-disc">+ <Trans>Document usage is approaching fair use limits</Trans>+ </li>+ )}+ {quotaFlags.isEmailQuotaNearing && (+ <li className="list-disc">+ <Trans>Email usage is approaching fair use limits</Trans>+ </li>+ )}+ {quotaFlags.isApiQuotaNearing && (+ <li className="list-disc">+ <Trans>API usage is approaching fair use limits</Trans>+ </li>+ )}</ul></AlertDescription></Alert>diff --git a/packages/app-tests/e2e/organisations/organisation-quota-banner.spec.ts b/packages/app-tests/e2e/organisations/organisation-quota-banner.spec.tsnew file mode 100644index 000000000..205bc437e--- /dev/null+++ b/packages/app-tests/e2e/organisations/organisation-quota-banner.spec.ts@@ -0,0 +1,169 @@+import { INTERNAL_CLAIM_ID } from '@documenso/lib/types/subscription';+import { generateDatabaseId } from '@documenso/lib/universal/id';+import { currentMonthlyPeriod } from '@documenso/lib/universal/monthly-period';+import { prisma } from '@documenso/prisma';+import { seedUser } from '@documenso/prisma/seed/users';+import { expect, test } from '@playwright/test';++import { apiSignin } from '../fixtures/authentication';++const BANNER_EXCEEDED_TEXT = 'Your organisation has exceeded a fair use limit';+const BANNER_NEARING_TEXT = 'Your organisation is approaching a fair use limit';++type SeedQuotaStateOptions = {+ organisationId: string;+ organisationClaimId: string;+ /**+ * The `originalSubscriptionClaimId` to set on the claim. The banner is suppressed+ * for `INTERNAL_CLAIM_ID.FREE`, so use a non-free value to make it render.+ */+ subscriptionClaimId: string;+ documentQuota: number | null;+ documentCount: number;+};++/**+ * Point the organisation's document quota and current-period usage at a known+ * state. Only the document counter is touched; email/api quotas stay `null`+ * (unlimited) so the document counter is the sole driver of the banner.+ */+const seedQuotaState = async ({+ organisationId,+ organisationClaimId,+ subscriptionClaimId,+ documentQuota,+ documentCount,+}: SeedQuotaStateOptions) => {+ await prisma.organisationClaim.update({+ where: {+ id: organisationClaimId,+ },+ data: {+ originalSubscriptionClaimId: subscriptionClaimId,+ documentQuota,+ },+ });++ const period = currentMonthlyPeriod();++ await prisma.organisationMonthlyStat.upsert({+ where: {+ organisationId_period: {+ organisationId,+ period,+ },+ },+ update: {+ documentCount,+ },+ create: {+ id: generateDatabaseId('org_monthly_stat'),+ organisationId,+ period,+ documentCount,+ },+ });+};++test('[QUOTA BANNER]: shows the approaching state when a quota is nearing', async ({ page }) => {+ const { user, organisation } = await seedUser({+ isPersonalOrganisation: false,+ });++ // ceil(10 * 0.8) = 8 → nearing, but not yet exceeded.+ await seedQuotaState({+ organisationId: organisation.id,+ organisationClaimId: organisation.organisationClaim.id,+ subscriptionClaimId: INTERNAL_CLAIM_ID.TEAM,+ documentQuota: 10,+ documentCount: 8,+ });++ await apiSignin({+ page,+ email: user.email,+ redirectPath: `/o/${organisation.url}/settings/general`,+ });++ await expect(page.getByText(BANNER_NEARING_TEXT)).toBeVisible();+ await expect(page.getByText(BANNER_EXCEEDED_TEXT)).toBeHidden();+});++test('[QUOTA BANNER]: shows the exceeded state when a quota is reached', async ({ page }) => {+ const { user, organisation } = await seedUser({+ isPersonalOrganisation: false,+ });++ // usage >= quota → exceeded.+ await seedQuotaState({+ organisationId: organisation.id,+ organisationClaimId: organisation.organisationClaim.id,+ subscriptionClaimId: INTERNAL_CLAIM_ID.TEAM,+ documentQuota: 10,+ documentCount: 10,+ });++ await apiSignin({+ page,+ email: user.email,+ redirectPath: `/o/${organisation.url}/settings/general`,+ });++ await expect(page.getByText(BANNER_EXCEEDED_TEXT)).toBeVisible();+ await expect(page.getByText(BANNER_NEARING_TEXT)).toBeHidden();+});++test('[QUOTA BANNER]: learn more dialog lists the affected counter', async ({ page }) => {+ const { user, organisation } = await seedUser({+ isPersonalOrganisation: false,+ });++ await seedQuotaState({+ organisationId: organisation.id,+ organisationClaimId: organisation.organisationClaim.id,+ subscriptionClaimId: INTERNAL_CLAIM_ID.TEAM,+ documentQuota: 10,+ documentCount: 10,+ });++ await apiSignin({+ page,+ email: user.email,+ redirectPath: `/o/${organisation.url}/settings/general`,+ });++ await page.getByRole('button', { name: 'Learn more' }).click();++ const dialog = page.getByRole('dialog');++ await expect(dialog.getByText('Fair use limit exceeded')).toBeVisible();+ await expect(dialog.getByText('Document creation has been temporarily paused')).toBeVisible();+ await expect(dialog.getByRole('link', { name: 'support' })).toHaveAttribute('href', /^mailto:/);+});++test('[QUOTA BANNER]: is hidden for free-claim organisations', async ({ page }) => {+ const { user, organisation } = await seedUser({+ isPersonalOrganisation: false,+ });++ // Usage is exceeded, but a free-claim organisation must never see the banner.+ await seedQuotaState({+ organisationId: organisation.id,+ organisationClaimId: organisation.organisationClaim.id,+ subscriptionClaimId: INTERNAL_CLAIM_ID.FREE,+ documentQuota: 10,+ documentCount: 10,+ });++ await apiSignin({+ page,+ email: user.email,+ redirectPath: `/o/${organisation.url}/settings/general`,+ });++ // Anchor on a stable element so banner-absence is meaningful (page fully loaded).+ await expect(page.getByLabel('Organisation Name*')).toBeVisible();++ await expect(page.getByText(BANNER_EXCEEDED_TEXT)).toBeHidden();+ await expect(page.getByRole('button', { name: 'Learn more' })).toBeHidden();+});diff --git a/packages/email/templates/organisation-limit-alert.tsx b/packages/email/templates/organisation-limit-alert.tsxnew file mode 100644index 000000000..087155b45--- /dev/null+++ b/packages/email/templates/organisation-limit-alert.tsx@@ -0,0 +1,152 @@+import { SUPPORT_EMAIL } from '@documenso/lib/constants/app';+import { msg } from '@lingui/core/macro';+import { useLingui } from '@lingui/react';+import { Trans } from '@lingui/react/macro';+import { match } from 'ts-pattern';+import { Body, Container, Head, Hr, Html, Preview, Section, Text } from '../components';+import { TemplateBrandingLogo } from '../template-components/template-branding-logo';+import { TemplateFooter } from '../template-components/template-footer';++export type OrganisationLimitAlertEmailProps = {+ assetBaseUrl: string;+ organisationName: string;+ counter: 'document' | 'email' | 'api';+ kind: 'rateLimit' | 'quota' | 'quotaNearing';+ period: string;+};++export const OrganisationLimitAlertEmailTemplate = ({+ assetBaseUrl = 'http://localhost:3002',+ organisationName = 'Organisation Name',+ counter = 'email',+ kind = 'quota',+ period = '2026-05',+}: OrganisationLimitAlertEmailProps) => {+ const { _ } = useLingui();++ const previewText = kind === 'quotaNearing' ? msg`Approaching Your Plan Limits` : msg`Organisation Review Required`;++ return (+ <Html>+ <Head />+ <Preview>{_(previewText)}</Preview>++ <Body className="mx-auto my-auto font-sans">+ <Section className="bg-white text-slate-500">+ <Container className="mx-auto mt-8 mb-2 max-w-xl rounded-lg border border-slate-200 border-solid p-2 backdrop-blur-sm">+ <TemplateBrandingLogo assetBaseUrl={assetBaseUrl} className="mb-4 h-6 p-2" />++ <Section className="p-2 text-slate-500">+ <Text className="text-center font-medium text-black text-lg">+ {kind === 'quotaNearing' ? (+ <Trans>Approaching Your Plan Limits</Trans>+ ) : (+ <Trans>Organisation Review Required</Trans>+ )}+ </Text>++ <div className="mx-auto my-2 w-fit rounded-lg bg-gray-50 px-4 py-2 font-medium text-base text-slate-600">+ {organisationName}+ </div>++ {match(kind)+ .with('quota', () => (+ <Text className="text-center text-base">+ {match(counter)+ .with('document', () => (+ <Trans>+ We've noticed document activity on your account that exceeds the fair use limits of your+ current plan. As a precaution, new document activity has been temporarily paused pending+ review.+ </Trans>+ ))+ .with('email', () => (+ <Trans>+ We've noticed email sending activity on your account that exceeds the fair use limits of your+ current plan. As a precaution, new email activity has been temporarily paused pending review.+ </Trans>+ ))+ .with('api', () => (+ <Trans>+ We've noticed API activity on your account that exceeds the fair use limits of your current+ plan. As a precaution, new API activity has been temporarily paused pending review.+ </Trans>+ ))+ .exhaustive()}+ </Text>+ ))+ .with('rateLimit', () => (+ <Text className="text-center text-base">+ {match(counter)+ .with('document', () => (+ <Trans>+ Your organisation is generating documents faster than normal, so some requests are being+ temporarily throttled.+ </Trans>+ ))+ .with('email', () => (+ <Trans>+ Your organisation is generating emails faster than normal, so some requests are being+ temporarily throttled.+ </Trans>+ ))+ .with('api', () => (+ <Trans>+ Your organisation is generating API requests faster than normal, so some requests are being+ temporarily throttled.+ </Trans>+ ))+ .exhaustive()}+ </Text>+ ))+ .with('quotaNearing', () => (+ <Text className="text-center text-base">+ {match(counter)+ .with('document', () => (+ <Trans>+ Your organisation is nearing its fair use limits for creating documents on your current plan.+ Once the limit is reached, new document activity will be temporarily paused.+ </Trans>+ ))+ .with('email', () => (+ <Trans>+ Your organisation is nearing its fair use limits for sending email on your current plan. Once+ the limit is reached, new email activity will be temporarily paused.+ </Trans>+ ))+ .with('api', () => (+ <Trans>+ Your organisation is nearing its fair use limits for making API requests on your current plan.+ Once the limit is reached, new API activity will be temporarily paused.+ </Trans>+ ))+ .exhaustive()}+ </Text>+ ))+ .exhaustive()}++ <Text className="text-center text-base">+ {kind === 'quotaNearing' ? (+ <Trans>+ If you expect to need higher limits, please contact support at {SUPPORT_EMAIL} and we will review+ your account.+ </Trans>+ ) : (+ <Trans>Please contact support at {SUPPORT_EMAIL} and we will review your account.</Trans>+ )}+ </Text>+ </Section>+ </Container>++ <Hr className="mx-auto mt-12 max-w-xl" />++ <Container className="mx-auto max-w-xl">+ <TemplateFooter isDocument={false} />+ </Container>+ </Section>+ </Body>+ </Html>+ );+};++export default OrganisationLimitAlertEmailTemplate;diff --git a/packages/email/templates/organisation-limit-exceeded.tsx b/packages/email/templates/organisation-limit-exceeded.tsxdeleted file mode 100644index 3740bb1f3..000000000--- a/packages/email/templates/organisation-limit-exceeded.tsx+++ /dev/null@@ -1,109 +0,0 @@-import { SUPPORT_EMAIL } from '@documenso/lib/constants/app';-import { msg } from '@lingui/core/macro';-import { useLingui } from '@lingui/react';-import { Trans } from '@lingui/react/macro';-import { match } from 'ts-pattern';-import { Body, Container, Head, Hr, Html, Preview, Section, Text } from '../components';-import { TemplateBrandingLogo } from '../template-components/template-branding-logo';-import { TemplateFooter } from '../template-components/template-footer';--export type OrganisationLimitExceededEmailProps = {- assetBaseUrl: string;- organisationName: string;- counter: 'document' | 'email' | 'api';- kind: 'rateLimit' | 'quota';- period: string;-};--export const OrganisationLimitExceededEmailTemplate = ({- assetBaseUrl = 'http://localhost:3002',- organisationName = 'Organisation Name',- counter = 'email',- kind = 'quota',- period = '2026-05',-}: OrganisationLimitExceededEmailProps) => {- const { _ } = useLingui();-- const previewText = msg`Organisation Review Required`;-- return (- <Html>- <Head />- <Preview>{_(previewText)}</Preview>-- <Body className="mx-auto my-auto font-sans">- <Section className="bg-white text-slate-500">- <Container className="mx-auto mt-8 mb-2 max-w-xl rounded-lg border border-slate-200 border-solid p-2 backdrop-blur-sm">- <TemplateBrandingLogo assetBaseUrl={assetBaseUrl} className="mb-4 h-6 p-2" />-- <Section className="p-2 text-slate-500">- <Text className="text-center font-medium text-black text-lg">- <Trans>Organisation Review Required</Trans>- </Text>-- {kind === 'quota' ? (- <Text className="text-center text-base">- {match(counter)- .with('document', () => (- <Trans>- We've noticed document activity on your account that exceeds the fair use limits of your current- plan. As a precaution, new document activity has been temporarily paused pending review.- </Trans>- ))- .with('email', () => (- <Trans>- We've noticed email sending activity on your account that exceeds the fair use limits of your- current plan. As a precaution, new email activity has been temporarily paused pending review.- </Trans>- ))- .with('api', () => (- <Trans>- We've noticed API activity on your account that exceeds the fair use limits of your current- plan. As a precaution, new API activity has been temporarily paused pending review.- </Trans>- ))- .exhaustive()}- </Text>- ) : (- <Text className="text-center text-base">- {match(counter)- .with('document', () => (- <Trans>- Your organisation is generating documents faster than normal, so some requests are being- temporarily throttled.- </Trans>- ))- .with('email', () => (- <Trans>- Your organisation is generating emails faster than normal, so some requests are being- temporarily throttled.- </Trans>- ))- .with('api', () => (- <Trans>- Your organisation is generating API requests faster than normal, so some requests are being- temporarily throttled.- </Trans>- ))- .exhaustive()}- </Text>- )}-- <Text className="text-center text-base">- <Trans>Please contact support at {SUPPORT_EMAIL} and we will review your account.</Trans>- </Text>- </Section>- </Container>-- <Hr className="mx-auto mt-12 max-w-xl" />-- <Container className="mx-auto max-w-xl">- <TemplateFooter isDocument={false} />- </Container>- </Section>- </Body>- </Html>- );-};--export default OrganisationLimitExceededEmailTemplate;diff --git a/packages/lib/jobs/client.ts b/packages/lib/jobs/client.tsindex 083c28424..ae23cb092 100644--- a/packages/lib/jobs/client.ts+++ b/packages/lib/jobs/client.ts@@ -4,7 +4,7 @@ import { SEND_CONFIRMATION_EMAIL_JOB_DEFINITION } from './definitions/emails/senimport { SEND_DOCUMENT_CANCELLED_EMAILS_JOB_DEFINITION } from './definitions/emails/send-document-cancelled-emails';import { SEND_DOCUMENT_COMPLETED_EMAILS_JOB_DEFINITION } from './definitions/emails/send-document-completed-emails';import { SEND_DOCUMENT_CREATED_FROM_DIRECT_TEMPLATE_EMAIL_JOB_DEFINITION } from './definitions/emails/send-document-created-from-direct-template-email';-import { SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION } from './definitions/emails/send-organisation-limit-exceeded-email';+import { SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION } from './definitions/emails/send-organisation-limit-alert-email';import { SEND_ORGANISATION_MEMBER_JOINED_EMAIL_JOB_DEFINITION } from './definitions/emails/send-organisation-member-joined-email';import { SEND_ORGANISATION_MEMBER_LEFT_EMAIL_JOB_DEFINITION } from './definitions/emails/send-organisation-member-left-email';import { SEND_OWNER_RECIPIENT_EXPIRED_EMAIL_JOB_DEFINITION } from './definitions/emails/send-owner-recipient-expired-email';@@ -37,7 +37,7 @@ export const jobsClient = new JobClient([SEND_CONFIRMATION_EMAIL_JOB_DEFINITION,SEND_ORGANISATION_MEMBER_JOINED_EMAIL_JOB_DEFINITION,SEND_ORGANISATION_MEMBER_LEFT_EMAIL_JOB_DEFINITION,- SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION,+ SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION,SEND_TEAM_DELETED_EMAIL_JOB_DEFINITION,SEAL_DOCUMENT_JOB_DEFINITION,SEAL_DOCUMENT_SWEEP_JOB_DEFINITION,diff --git a/packages/lib/jobs/definitions/emails/send-organisation-limit-exceeded-email.handler.ts b/packages/lib/jobs/definitions/emails/send-organisation-limit-alert-email.handler.tssimilarity index 51%rename from packages/lib/jobs/definitions/emails/send-organisation-limit-exceeded-email.handler.tsrename to packages/lib/jobs/definitions/emails/send-organisation-limit-alert-email.handler.tsindex ea4ebe36b..d43a661b1 100644--- a/packages/lib/jobs/definitions/emails/send-organisation-limit-exceeded-email.handler.ts+++ b/packages/lib/jobs/definitions/emails/send-organisation-limit-alert-email.handler.ts@@ -1,21 +1,25 @@-import OrganisationLimitExceededEmailTemplate from '@documenso/email/templates/organisation-limit-exceeded';+import { mailer } from '@documenso/email/mailer';+import OrganisationLimitAlertEmailTemplate from '@documenso/email/templates/organisation-limit-alert';+import { SUPPORT_EMAIL } from '@documenso/lib/constants/app';+import { prisma } from '@documenso/prisma';import { msg } from '@lingui/core/macro';import { createElement } from 'react';import { getI18nInstance } from '../../../client-only/providers/i18n-server';import { NEXT_PUBLIC_WEBAPP_URL } from '../../../constants/app';+import { DOCUMENSO_INTERNAL_EMAIL } from '../../../constants/email';import { ORGANISATION_MEMBER_ROLE_PERMISSIONS_MAP } from '../../../constants/organisations';import { getEmailContext } from '../../../server-only/email/get-email-context';import { INTERNAL_CLAIM_ID } from '../../../types/subscription';import { renderEmailWithI18N } from '../../../utils/render-email-with-i18n';import type { JobRunIO } from '../../client/_internal/job';-import type { TSendOrganisationLimitExceededEmailJobDefinition } from './send-organisation-limit-exceeded-email';+import type { TSendOrganisationLimitAlertEmailJobDefinition } from './send-organisation-limit-alert-email';export const run = async ({payload,io,}: {- payload: TSendOrganisationLimitExceededEmailJobDefinition;+ payload: TSendOrganisationLimitAlertEmailJobDefinition;io: JobRunIO;}) => {const organisation = await prisma.organisation.findFirstOrThrow({@@ -24,6 +28,16 @@ export const run = async ({},include: {organisationClaim: true,+ monthlyStats: {+ where: {+ period: payload.period,+ },+ select: {+ documentCount: true,+ emailCount: true,+ apiCount: true,+ },+ },members: {where: {organisationGroupMembers: {@@ -60,16 +74,19 @@ export const run = async ({// Do not send emails for "free" claims.if (organisation.organisationClaim.originalSubscriptionClaimId === INTERNAL_CLAIM_ID.FREE) {io.logger.info({- msg: 'Skipping organisation limit exceeded email for "free" claim',+ msg: 'Skipping organisation limit alert email for "free" claim',organisationId: organisation.id,});return;}+ const memberSubject =+ payload.kind === 'quotaNearing' ? msg`Approaching Your Plan Limits` : msg`Organisation Review Required`;+for (const member of organisation.members) {- await io.runTask(`send-organisation-limit-exceeded-email-${member.id}`, async () => {- const emailContent = createElement(OrganisationLimitExceededEmailTemplate, {+ await io.runTask(`send-organisation-limit-alert-email-${member.id}`, async () => {+ const emailContent = createElement(OrganisationLimitAlertEmailTemplate, {assetBaseUrl: NEXT_PUBLIC_WEBAPP_URL(),organisationName: organisation.name,counter: payload.counter,@@ -87,7 +104,7 @@ export const run = async ({await emailTransport.sendMail({to: member.user.email,from: senderEmail,- subject: i18n._(msg`Organisation Review Required`),+ subject: i18n._(memberSubject),html,text,});@@ -95,20 +112,31 @@ export const run = async ({}// Todo: Logging- // Todo: Decide if we want to send an email or alert via another software.- // const i18n = await getI18nInstance('en');+ const i18n = await getI18nInstance('en');++ const supportSubject =+ payload.kind === 'quotaNearing'+ ? msg`An organisation is nearing their fair use limits`+ : msg`An organisation has exceeded their fair use limits`;- // // Email our support team.- // await mailer.sendMail({- // to: SUPPORT_EMAIL,- // from: senderEmail,- // subject: i18n._(msg`An organisation has exceeded their fair use limits`),- // text: `- // Organisation: ${organisation.name}- // Organisation ID: ${organisation.id}- // Counter: ${payload.counter}- // Kind: ${payload.kind}- // Period: ${payload.period}- // `,- // });+ // Email our support team. Purposefully sent from the internal email since the+ // global mailer is not authorized to send from custom per-plan transport addresses.+ await io.runTask('send-organisation-limit-alert-support-email', async () => {+ await mailer.sendMail({+ to: SUPPORT_EMAIL,+ from: DOCUMENSO_INTERNAL_EMAIL,+ subject: i18n._(supportSubject),+ text: `+ Organisation: ${organisation.name}+ Organisation ID: ${organisation.id}+ Organisation Claim Original ID: ${organisation.organisationClaim.originalSubscriptionClaimId}+ Email Quota: ${organisation.monthlyStats[0]?.emailCount || 0}/${organisation.organisationClaim.emailQuota ?? 'Unlimited'}+ API Quota: ${organisation.monthlyStats[0]?.apiCount || 0}/${organisation.organisationClaim.apiQuota ?? 'Unlimited'}+ Document Quota: ${organisation.monthlyStats[0]?.documentCount || 0}/${organisation.organisationClaim.documentQuota ?? 'Unlimited'}+ Counter: ${payload.counter}+ Kind: ${payload.kind}+ Period: ${payload.period}+ `,+ });+ });};diff --git a/packages/lib/jobs/definitions/emails/send-organisation-limit-alert-email.ts b/packages/lib/jobs/definitions/emails/send-organisation-limit-alert-email.tsnew file mode 100644index 000000000..e4b14f1ef--- /dev/null+++ b/packages/lib/jobs/definitions/emails/send-organisation-limit-alert-email.ts@@ -0,0 +1,34 @@+import { z } from 'zod';++import type { JobDefinition } from '../../client/_internal/job';++const SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION_ID = 'send.organisation-limit-alert.email';++const SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION_SCHEMA = z.object({+ organisationId: z.string(),+ counter: z.enum(['document', 'email', 'api']),+ kind: z.enum(['rateLimit', 'quota', 'quotaNearing']),+ period: z.string(),+});++export type TSendOrganisationLimitAlertEmailJobDefinition = z.infer<+ typeof SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION_SCHEMA+>;++export const SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION = {+ id: SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION_ID,+ name: 'Send Organisation Limit Alert Email',+ version: '1.0.0',+ trigger: {+ name: SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION_ID,+ schema: SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION_SCHEMA,+ },+ handler: async ({ payload, io }) => {+ const handler = await import('./send-organisation-limit-alert-email.handler');++ await handler.run({ payload, io });+ },+} as const satisfies JobDefinition<+ typeof SEND_ORGANISATION_LIMIT_ALERT_EMAIL_JOB_DEFINITION_ID,+ TSendOrganisationLimitAlertEmailJobDefinition+>;diff --git a/packages/lib/jobs/definitions/emails/send-organisation-limit-exceeded-email.ts b/packages/lib/jobs/definitions/emails/send-organisation-limit-exceeded-email.tsdeleted file mode 100644index 06595c8b5..000000000--- a/packages/lib/jobs/definitions/emails/send-organisation-limit-exceeded-email.ts+++ /dev/null@@ -1,34 +0,0 @@-import { z } from 'zod';--import type { JobDefinition } from '../../client/_internal/job';--const SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION_ID = 'send.organisation-limit-exceeded.email';--const SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION_SCHEMA = z.object({- organisationId: z.string(),- counter: z.enum(['document', 'email', 'api']),- kind: z.enum(['rateLimit', 'quota']),- period: z.string(),-});--export type TSendOrganisationLimitExceededEmailJobDefinition = z.infer<- typeof SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION_SCHEMA->;--export const SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION = {- id: SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION_ID,- name: 'Send Organisation Limit Exceeded Email',- version: '1.0.0',- trigger: {- name: SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION_ID,- schema: SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION_SCHEMA,- },- handler: async ({ payload, io }) => {- const handler = await import('./send-organisation-limit-exceeded-email.handler');-- await handler.run({ payload, io });- },-} as const satisfies JobDefinition<- typeof SEND_ORGANISATION_LIMIT_EXCEEDED_EMAIL_JOB_DEFINITION_ID,- TSendOrganisationLimitExceededEmailJobDefinition->;diff --git a/packages/lib/server-only/rate-limit/check-monthly-quota.ts b/packages/lib/server-only/rate-limit/check-monthly-quota.tsindex 26dd70774..9066a2c95 100644--- a/packages/lib/server-only/rate-limit/check-monthly-quota.ts+++ b/packages/lib/server-only/rate-limit/check-monthly-quota.ts@@ -3,6 +3,7 @@ import { AppError, AppErrorCode } from '../../errors/app-error';import { jobsClient } from '../../jobs/client';import { generateDatabaseId } from '../../universal/id';import { currentMonthlyPeriod } from '../../universal/monthly-period';+import { getQuotaAlertKind } from './get-quota-alert-kind';import type { LimitCounter } from './types';type CheckMonthlyQuotaOptions = {@@ -56,29 +57,33 @@ export const checkMonthlyQuota = async (opts: CheckMonthlyQuotaOptions): Promiseconst newCount = latestMonthlyStat[column];const previousCount = newCount - opts.count;- const isOverQuota = newCount > opts.quota;-- // Only notify on the single request that crossed the threshold: the count was- // at/under quota before this request and over it after. Because the DB- // serializes the atomic increment, the post-increment values are distinct and- // monotonic, so exactly one request's (previousCount, newCount] interval- // contains the quota boundary — guaranteeing the notification fires once.- const didCrossQuota = isOverQuota && previousCount <= opts.quota;+ // Returns 'quota' on the single request that reached (or jumped past) the quota,+ // 'quotaNearing' on the single request that reached the warning threshold,+ // otherwise null. See getQuotaAlertKind for the exactly-once guarantee.+ const alertKind = getQuotaAlertKind({+ previousCount,+ newCount,+ quota: opts.quota,+ });- if (didCrossQuota) {+ // Trigger the alert before the over-quota check — the 'quota' alert usually fires+ // on the successful request that consumes the last unit of allowance, but when a+ // batch jumps past the boundary it fires on this rejected request. Either way it+ // will never fire again this period, so it must be enqueued before any throw.+ if (alertKind) {await jobsClient.triggerJob({- name: 'send.organisation-limit-exceeded.email',+ name: 'send.organisation-limit-alert.email',payload: {organisationId: opts.organisationId,counter: opts.counter,- kind: 'quota',+ kind: alertKind,period,},}).catch((error) => {console.error({- msg: 'Failed to send organisation limit exceeded email',+ msg: 'Failed to send organisation limit alert email',error,});@@ -86,7 +91,7 @@ export const checkMonthlyQuota = async (opts: CheckMonthlyQuotaOptions): Promise});}- if (isOverQuota) {+ if (newCount > opts.quota) {throw new AppError(AppErrorCode.TOO_MANY_REQUESTS, {message:'Your request could not be completed at this time due to your account exceeding the fair use limits of your current plan. Please contact support.',diff --git a/packages/lib/server-only/rate-limit/compute-quota-flags.ts b/packages/lib/server-only/rate-limit/compute-quota-flags.tsindex c53256606..ea463cf69 100644--- a/packages/lib/server-only/rate-limit/compute-quota-flags.ts+++ b/packages/lib/server-only/rate-limit/compute-quota-flags.ts@@ -1,7 +1,12 @@+import { QUOTA_WARNING_THRESHOLD } from './get-quota-alert-kind';+export type QuotaFlags = {isDocumentQuotaExceeded: boolean;isEmailQuotaExceeded: boolean;isApiQuotaExceeded: boolean;+ isDocumentQuotaNearing: boolean;+ isEmailQuotaNearing: boolean;+ isApiQuotaNearing: boolean;};type ComputeQuotaFlagsOptions = {@@ -20,11 +25,6 @@ type ComputeQuotaFlagsOptions = {/*** A quota of `null` means unlimited (never exceeded). A quota of `0` means* blocked (always exceeded). Otherwise usage `>=` quota is exceeded.- *- * Note: this `>=` is intentionally the "reached" signal for the banner and is- * distinct from enforcement in `check-monthly-quota.ts`, which blocks the- * action that crosses the boundary using a strict `>` on the post-increment- * count. Do not "align" them — they answer different questions.*/const isQuotaExceeded = (quota: number | null, usage: number): boolean => {if (quota === null) {@@ -38,10 +38,30 @@ const isQuotaExceeded = (quota: number | null, usage: number): boolean => {return usage >= quota;};+/**+ * A counter is "nearing" its quota once usage reaches the warning threshold+ * (80% of the quota, rounded up) but has not yet been exceeded. Nearing and+ * exceeded are mutually exclusive per counter.+ */+const isQuotaNearing = (quota: number | null, usage: number): boolean => {+ if (quota === null || quota === 0) {+ return false;+ }++ if (isQuotaExceeded(quota, usage)) {+ return false;+ }++ return usage >= Math.ceil(quota * QUOTA_WARNING_THRESHOLD);+};+export const computeQuotaFlags = ({ quotas, usage }: ComputeQuotaFlagsOptions): QuotaFlags => {return {isDocumentQuotaExceeded: isQuotaExceeded(quotas.documentQuota, usage?.documentCount ?? 0),isEmailQuotaExceeded: isQuotaExceeded(quotas.emailQuota, usage?.emailCount ?? 0),isApiQuotaExceeded: isQuotaExceeded(quotas.apiQuota, usage?.apiCount ?? 0),+ isDocumentQuotaNearing: isQuotaNearing(quotas.documentQuota, usage?.documentCount ?? 0),+ isEmailQuotaNearing: isQuotaNearing(quotas.emailQuota, usage?.emailCount ?? 0),+ isApiQuotaNearing: isQuotaNearing(quotas.apiQuota, usage?.apiCount ?? 0),};};diff --git a/packages/lib/server-only/rate-limit/get-quota-alert-kind.ts b/packages/lib/server-only/rate-limit/get-quota-alert-kind.tsnew file mode 100644index 000000000..afaaeaa14--- /dev/null+++ b/packages/lib/server-only/rate-limit/get-quota-alert-kind.ts@@ -0,0 +1,40 @@+export const QUOTA_WARNING_THRESHOLD = 0.8;++export type QuotaAlertKind = 'quota' | 'quotaNearing';++type GetQuotaAlertKindOptions = {+ previousCount: number;+ newCount: number;+ quota: number;+};++/**+ * Determines whether the request that moved the counter from `previousCount` to+ * `newCount` crossed an alert threshold.+ *+ * - 'quota': this request reached (or jumped past) the monthly quota.+ * - 'quotaNearing': this request reached the warning threshold (80% of quota).+ * - null: no threshold crossed by this request.+ *+ * Precondition: callers must handle `quota === null` (unlimited) and `quota === 0`+ * (blocked) before calling — this function assumes a positive quota.+ */+export const getQuotaAlertKind = (opts: GetQuotaAlertKindOptions): QuotaAlertKind | null => {+ const { previousCount, newCount, quota } = opts;++ if (newCount >= quota) {+ // Only the single request that reached the quota boundary should alert. If the+ // same request also skipped past the warning threshold, the quota alert+ // supersedes the warning.+ return previousCount < quota ? 'quota' : null;+ }++ // From here newCount < quota, so for tiny quotas (1-4) where the rounded-up+ // warning threshold equals the quota itself, the warning can never fire — the+ // exhausting request is handled by the quota branch above.+ const warningCount = Math.ceil(quota * QUOTA_WARNING_THRESHOLD);++ const didCrossWarning = newCount >= warningCount && previousCount < warningCount;++ return didCrossWarning ? 'quotaNearing' : null;+};diff --git a/packages/trpc/server/organisation-router/get-organisation-quota-flags.types.ts b/packages/trpc/server/organisation-router/get-organisation-quota-flags.types.tsindex e7713aeec..3dea662a4 100644--- a/packages/trpc/server/organisation-router/get-organisation-quota-flags.types.ts+++ b/packages/trpc/server/organisation-router/get-organisation-quota-flags.types.ts@@ -12,6 +12,9 @@ export const ZGetOrganisationQuotaFlagsResponseSchema = z.object({isDocumentQuotaExceeded: z.boolean(),isEmailQuotaExceeded: z.boolean(),isApiQuotaExceeded: z.boolean(),+ isDocumentQuotaNearing: z.boolean(),+ isEmailQuotaNearing: z.boolean(),+ isApiQuotaNearing: z.boolean(),});export type TGetOrganisationQuotaFlagsResponse = z.infer<typeof ZGetOrganisationQuotaFlagsResponseSchema>;