Skip to content

The Open Source DocuSign Alternative.

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.tsx
index 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>
<Button
variant="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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
deleted file mode 100644
index 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.ts
index 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/sen
import { 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.ts
similarity index 51%
rename from packages/lib/jobs/definitions/emails/send-organisation-limit-exceeded-email.handler.ts
rename to packages/lib/jobs/definitions/emails/send-organisation-limit-alert-email.handler.ts
index 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.ts
new file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
index 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): Promise
const 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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>;