{t('whatNowBody')}
{t('since', { - date: new Date(cutoffAt).toLocaleDateString(undefined, { dateStyle: 'long' }), + // Explicit locale — `undefined` on the server resolves to the + // Node process locale, not the request's (#517). + date: new Date(cutoffAt).toLocaleDateString(locale, { dateStyle: 'long' }), })}
diff --git a/app/api/cron/enforce-plan-limits/route.ts b/app/api/cron/enforce-plan-limits/route.ts index 734de874..98b26249 100644 --- a/app/api/cron/enforce-plan-limits/route.ts +++ b/app/api/cron/enforce-plan-limits/route.ts @@ -16,6 +16,17 @@ export const runtime = 'nodejs' * `tenants.access_cutoff_at` against its current plan/usage, regardless of * plan (a free-plan tenant needs this as much as a paid one). * + * It is also the only thing that runs repeatedly while a cutoff is pending, + * which makes it the right home for the #517 reminder ladder: `notifyDueStages` + * tells the reconciler to send whichever rung (T-7, T-1, or the day access + * actually stops) is due and not yet in the `access_cutoff_notifications` + * ledger. That is why no separate cron entry was added — the sweep that + * already visits every tenant daily is exactly the cadence the ladder needs. + * + * `notified` / `notifyFailures` in the response make send health visible: + * before #517 a failing mail provider left the schedule in place and said + * nothing, so the school's first signal was students losing access. + * * Secured by CRON_SECRET env var (set the same value in the cron scheduler). */ @@ -37,14 +48,28 @@ export async function GET(req: NextRequest) { const { data: tenants } = await supabase.from('tenants').select('id') - const result = { scheduled: 0, cleared: 0, none: 0, errors: 0 } + const result = { + scheduled: 0, + cleared: 0, + none: 0, + errors: 0, + /** Reminder-ladder rungs delivered this run, keyed by stage (#517). */ + notified: {} as Record+ + {notice.active + ? t('activeTitle') + : notice.daysRemaining <= 1 + ? t('scheduledTitleImminent') + : t('scheduledTitle', { days: notice.daysRemaining })} + {' '} + {notice.active ? t('activeBody', { date: cutoffDate }) : t('scheduledBody', { date: cutoffDate })} +
+ + + {notice.active ? t('restoreAccess') : t('manageBilling')} + +Hi,
-${data.schoolName} is on the ${data.planName} plan and currently exceeds its limits:
+${copy.lead}
If this isn't resolved by ${data.cutoffDate}, every student at your school will lose access to all courses — lessons, exams, exercises, and certificates — until usage is brought back within the plan's limits or you upgrade.
-To keep access uninterrupted, upgrade your plan or reduce usage (archive courses / remove students) before the date above.
+${copy.consequence}
+${copy.callToAction}
- Manage Billing + ${buttonLabel}
If you believe this is an error, please contact support.
diff --git a/messages/en.json b/messages/en.json index 43e05a1c..98e30f13 100644 --- a/messages/en.json +++ b/messages/en.json @@ -3700,6 +3700,15 @@ "resendSuccess": "Confirmation email sent. Check your inbox.", "dismiss": "Dismiss" }, + "accessCutoffBanner": { + "activeTitle": "Course access is paused for your whole school.", + "scheduledTitle": "Course access stops for your whole school in {days} days.", + "scheduledTitleImminent": "Course access stops for your whole school tomorrow.", + "activeBody": "Since {date}, every student has lost access to all courses because the school is over its plan limits. Enrollments and purchases are intact — access returns for everyone as soon as you upgrade or reduce usage.", + "scheduledBody": "On {date}, every student will lose access to all courses unless usage is back within your plan's limits. Nothing is deleted, but no student will be able to open a course.", + "manageBilling": "Manage billing", + "restoreAccess": "Restore access" + }, "connectClaude": { "title": "Connect Claude", "description": "Add the LMS as a custom connector — no token needed, you sign in with your LMS account.", diff --git a/messages/es.json b/messages/es.json index 9eecc0f4..05e2fd80 100644 --- a/messages/es.json +++ b/messages/es.json @@ -3545,6 +3545,15 @@ "resendSuccess": "Correo de confirmación enviado. Revisa tu bandeja.", "dismiss": "Descartar" }, + "accessCutoffBanner": { + "activeTitle": "El acceso a los cursos está pausado para toda tu escuela.", + "scheduledTitle": "El acceso a los cursos se detiene para toda tu escuela en {days} días.", + "scheduledTitleImminent": "El acceso a los cursos se detiene para toda tu escuela mañana.", + "activeBody": "Desde el {date}, todos los estudiantes perdieron el acceso a los cursos porque la escuela superó los límites de su plan. Las inscripciones y las compras están intactas: el acceso vuelve para todos en cuanto mejores el plan o reduzcas el uso.", + "scheduledBody": "El {date}, todos los estudiantes perderán el acceso a los cursos si el uso no vuelve a estar dentro de los límites de tu plan. No se elimina nada, pero ningún estudiante podrá abrir un curso.", + "manageBilling": "Gestionar facturación", + "restoreAccess": "Restaurar acceso" + }, "connectClaude": { "title": "Conectar Claude", "description": "Agrega el LMS como conector personalizado — sin tokens, inicias sesión con tu cuenta del LMS.", diff --git a/supabase/migrations/20260725100000_access_cutoff_notifications.sql b/supabase/migrations/20260725100000_access_cutoff_notifications.sql new file mode 100644 index 00000000..7cfafe98 --- /dev/null +++ b/supabase/migrations/20260725100000_access_cutoff_notifications.sql @@ -0,0 +1,48 @@ +-- Issue #517 — a send ledger for access-cutoff notifications. +-- +-- #494 shipped exactly one email per cutoff, sent from the single 'schedule' +-- transition in reconcileAccessCutoff(). Nothing ran at T-7, T-1 or when the +-- cutoff actually took effect, and a failed send was swallowed with no retry. +-- +-- This table is what makes a reminder ladder possible: it records which stage +-- of the ladder has already been delivered for a given cutoff, so the daily +-- enforce-plan-limits sweep can send whatever is due without ever repeating +-- itself. The unique constraint — not application logic — is what guarantees +-- that, since the sweep runs unattended and may overlap with an event-driven +-- reconcile. +-- +-- Keyed on cutoff_at as well as tenant_id on purpose: a cutoff that is cleared +-- (usage back under limit) and later rescheduled is a genuinely new 14-day +-- deadline and deserves a fresh ladder, not silence because the old one was +-- already notified. +-- +-- A row is written ONLY after at least one recipient send succeeded. A stage +-- whose sends all failed stays unrecorded, which is exactly what makes the +-- next daily sweep retry it. + +CREATE TABLE IF NOT EXISTS public.access_cutoff_notifications ( + id uuid PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE, + -- The tenants.access_cutoff_at value this notification was about. Scopes the + -- ladder to one specific deadline. + cutoff_at timestamptz NOT NULL, + -- 'scheduled' (immediate, at scheduling time) | 'reminder_7d' | 'reminder_1d' + -- | 'enforced' (first sweep after the cutoff took effect). + stage text NOT NULL CHECK (stage IN ('scheduled', 'reminder_7d', 'reminder_1d', 'enforced')), + sent_at timestamptz NOT NULL DEFAULT now(), + -- How many admin addresses actually received it; > 0 by construction. + recipient_count integer NOT NULL DEFAULT 0, + CONSTRAINT access_cutoff_notifications_unique_stage UNIQUE (tenant_id, cutoff_at, stage) +); + +CREATE INDEX IF NOT EXISTS idx_access_cutoff_notifications_tenant + ON public.access_cutoff_notifications (tenant_id, cutoff_at); + +-- Service-role only. Every writer is the cron sweep or a server-side +-- reconciler running with the service key; no authenticated user has any +-- reason to read or write the ledger, so RLS is enabled with no policy at all +-- (deny-by-default for anon/authenticated, service_role bypasses). +ALTER TABLE public.access_cutoff_notifications ENABLE ROW LEVEL SECURITY; + +COMMENT ON TABLE public.access_cutoff_notifications IS + 'Issue #517: per-cutoff notification send ledger. One row per (tenant, cutoff_at, stage), written only on a successful send so failed stages are retried by the next daily sweep.'; diff --git a/tests/unit/access-cutoff-notifications.test.ts b/tests/unit/access-cutoff-notifications.test.ts new file mode 100644 index 00000000..28a26e92 --- /dev/null +++ b/tests/unit/access-cutoff-notifications.test.ts @@ -0,0 +1,223 @@ +/** + * Issue #517 — the access-cutoff notification ladder. + * + * #494 shipped one email per cutoff and no retry. These tests pin the two + * pure decisions that replace it: which rung of the ladder is due + * (`dueCutoffNotificationStage`) and what an admin should be told in-app + * (`describeAccessCutoff`). + */ +import { describe, it, expect } from 'vitest' +import { dueCutoffNotificationStage } from '@/lib/billing/access-cutoff' +import { describeAccessCutoff } from '@/lib/billing/access-cutoff-notice' +import { accessCutoffWarningTemplate } from '@/lib/email/templates/access-cutoff-warning' + +const CUTOFF = '2026-08-07T00:00:00.000Z' +const at = (iso: string) => new Date(iso) + +describe('dueCutoffNotificationStage', () => { + it('sends the scheduling notice immediately when the ledger is empty', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: [], + now: at('2026-07-24T00:00:00.000Z'), // T-14 + }) + ).toBe('scheduled') + }) + + it('stays quiet mid-window once the scheduling notice is recorded', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: ['scheduled'], + now: at('2026-07-28T00:00:00.000Z'), // T-10 + }) + ).toBeNull() + }) + + it('sends the 7-day reminder at T-7', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: ['scheduled'], + now: at('2026-07-31T00:00:00.000Z'), + }) + ).toBe('reminder_7d') + }) + + it('does not repeat the 7-day reminder once recorded', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: ['scheduled', 'reminder_7d'], + now: at('2026-08-02T00:00:00.000Z'), // T-5 + }) + ).toBeNull() + }) + + it('sends the final reminder at T-1', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: ['scheduled', 'reminder_7d'], + now: at('2026-08-06T00:00:00.000Z'), + }) + ).toBe('reminder_1d') + }) + + it('sends the enforced notice once the cutoff has passed', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: ['scheduled', 'reminder_7d', 'reminder_1d'], + now: at('2026-08-07T00:00:01.000Z'), + }) + ).toBe('enforced') + }) + + it('goes silent after the enforced notice — no daily nagging', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: ['scheduled', 'reminder_7d', 'reminder_1d', 'enforced'], + now: at('2026-08-20T00:00:00.000Z'), + }) + ).toBeNull() + }) + + // The retry the issue asks for: a send that threw is never written to the + // ledger, so the stage is still unsent on the next daily sweep. + it('retries a scheduling notice whose sends all failed', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: [], + now: at('2026-07-25T00:00:00.000Z'), // next sweep after a failed T-14 send + }) + ).toBe('scheduled') + }) + + it('retries a failed 7-day reminder on the following sweep', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: ['scheduled'], + now: at('2026-08-01T00:00:00.000Z'), // T-6, reminder_7d still unsent + }) + ).toBe('reminder_7d') + }) + + // A stale rung must never overtake an urgent one: two contradictory + // messages in one inbox is worse than one missing message. + it('supersedes an undelivered early rung once a more urgent one is reached', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: [], + now: at('2026-08-06T12:00:00.000Z'), // T-12h, nothing ever sent + }) + ).toBe('reminder_1d') + }) + + it('only ever sends the enforced notice after the cutoff, never a warning', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: CUTOFF, + sentStages: [], // every earlier rung failed + now: at('2026-08-08T00:00:00.000Z'), + }) + ).toBe('enforced') + }) + + // A cleared-then-rescheduled cutoff is a new deadline: the ledger is keyed + // on cutoff_at, so the new window starts with an empty sentStages list. + it('starts a fresh ladder for a rescheduled cutoff', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: '2026-09-15T00:00:00.000Z', + sentStages: [], + now: at('2026-09-01T00:00:00.000Z'), + }) + ).toBe('scheduled') + }) + + it('returns null for an unparseable cutoff rather than mailing garbage', () => { + expect( + dueCutoffNotificationStage({ + cutoffAt: 'not-a-date', + sentStages: [], + now: at('2026-08-01T00:00:00.000Z'), + }) + ).toBeNull() + }) +}) + +describe('describeAccessCutoff', () => { + it('returns null when no cutoff is scheduled', () => { + expect(describeAccessCutoff({ cutoffAt: null, now: at('2026-07-24T00:00:00.000Z') })).toBeNull() + }) + + it('reports days remaining while the cutoff is still in the future', () => { + expect(describeAccessCutoff({ cutoffAt: CUTOFF, now: at('2026-07-24T00:00:00.000Z') })).toEqual({ + cutoffAt: CUTOFF, + active: false, + daysRemaining: 14, + }) + }) + + it('rounds a partial day up so "tomorrow" never reads as 0 days', () => { + const notice = describeAccessCutoff({ cutoffAt: CUTOFF, now: at('2026-08-06T06:00:00.000Z') }) + expect(notice).toEqual({ cutoffAt: CUTOFF, active: false, daysRemaining: 1 }) + }) + + it('flags the cutoff as active once it has passed', () => { + expect(describeAccessCutoff({ cutoffAt: CUTOFF, now: at('2026-08-07T00:00:01.000Z') })).toEqual({ + cutoffAt: CUTOFF, + active: true, + daysRemaining: 0, + }) + }) + + it('returns null for an unparseable cutoff rather than rendering NaN days', () => { + expect(describeAccessCutoff({ cutoffAt: 'not-a-date', now: at('2026-08-01T00:00:00.000Z') })).toBeNull() + }) +}) + +describe('accessCutoffWarningTemplate stages', () => { + const base = { + schoolName: 'Code Academy', + planName: 'Free', + reasons: ['51 active students exceed the Free plan’s limit of 50'], + cutoffDate: 'August 7, 2026', + billingUrl: 'https://code-academy.example.com/dashboard/admin/billing', + } + + it('defaults to the #494 scheduling copy when no stage is given', () => { + const { subject } = accessCutoffWarningTemplate(base) + expect(subject).toBe( + 'Action required: student access to Code Academy will be cut off on August 7, 2026' + ) + }) + + it('gives each rung a distinct subject so reminders are not threaded as duplicates', () => { + const subjects = (['scheduled', 'reminder_7d', 'reminder_1d', 'enforced'] as const).map( + (stage) => accessCutoffWarningTemplate({ ...base, stage }).subject + ) + expect(new Set(subjects).size).toBe(4) + }) + + it('writes the enforced notice in the past tense — access is already gone', () => { + const { subject, html } = accessCutoffWarningTemplate({ ...base, stage: 'enforced' }) + expect(subject).toBe('Student access to Code Academy is now paused') + expect(html).toContain('has lost access') + expect(html).not.toContain('will lose access') + }) + + it('states the school-wide blast radius on every rung', () => { + for (const stage of ['scheduled', 'reminder_7d', 'reminder_1d', 'enforced'] as const) { + expect(accessCutoffWarningTemplate({ ...base, stage }).html).toMatch( + /every student at your school/i + ) + } + }) +})