feat(billing): enforce free-plan student cap across the app (#733)

* feat(billing): enforce free-plan student cap across the app Free (BASIC) plan orgs were able to exceed the advertised 20-student limit because the cap existed only as dashboard cosmetic copy with no server-side enforcement. Add a single source of truth (getStudentLimit / STUDENT_LIMITS) and a central guard (assertStudentCapacityOrThrow) wired into every path that creates a new student-role org member: self-enrolment, course-invite acceptance, bulk audience import, and org-invite acceptance. The guard throws UPGRADE_REQUIRED (403) and notifies org admins by email (throttled to once per org per day) when the limit is hit. Surface the limit in the UI: disable the audience import button and the course new-student invite section with upgrade banners for admins, and show a "contact your administrator" message on the public enrol page for students (who cannot upgrade). Expose a studentLimitReached flag from the public course endpoint so the enrol button can be disabled proactively. Add a one-time (manual, non-cron) db script, db:notify-students-over-limit, to email admins of orgs already over the limit at rollout. * feat(billing): guard remaining student-creating paths against the cap The initial cap enforcement missed several service entry points that also create a new student-role org member. Add the capacity guard to: - autoEnrollStudent (public org self-join on a tenant site) - cohort enrollment (bulk group enrollment and single member accept) - ensureProgramCourseAccess (program/cohort-granted course access) For the cohort and program paths, only genuinely new members are counted (existing org members are skipped) so re-enrolling current students is never falsely blocked. The core path enforces via the shared limit check; it throws UPGRADE_REQUIRED without the admin email since the queue lives in the api layer. * fix(billing): don't show cap block to existing org members on enroll page The public course-by-slug endpoint is unauthenticated, so the enroll page's studentLimitReached flag is org-wide and can't tell whether the current viewer is already an org member. An existing student of a full BASIC org would see Join disabled even though the backend correctly lets existing members enroll without consuming a new seat. Only pre-block anonymous visitors (would-be new joiners). Logged-in users are governed by the membership-aware backend, which allows existing members and returns UPGRADE_REQUIRED (surfaced via the enroll onError mapping) for genuinely new students. * feat(billing): deliver org plan-limits via /account with an extensible registry Replace the ad-hoc, per-surface audience fetches (each calling getOrgAudience just to read a count) with a single, future-proof delivery of org usage + limits on the /account payload, gated to admin/tutor members (students never receive limit data; a plain COUNT, no student rows). Model it generically so future org limits (courses, etc.) drop in without reshaping the payload or re-plumbing the frontend: - New packages/utils plan-limits registry: PLAN_LIMIT_RESOURCES, PLAN_LIMITS (reuses STUDENT_LIMITS), getPlanLimit, and a JSON-safe ResourceUsage / OrgUsageLimits shape with isResourceLimitReached / resourceLimitRemaining. - getAccountData attaches a per-org `limits` map for admin/tutor orgs. - Store selectors currentOrgLimits / studentUsage / isStudentLimitReached; sidebars, upgrade card, People pages, and invite modals read these instead of fetching audience rows. Bring cohort surfaces to parity with course: cohort People page banner and cohort sidebar People upgrade icon, matching the course equivalents. Also: close the upgrade modal that opened over the invite modal (drop the `add` param via openUpgradeModalOver), redesign the sidebar upgrade card (progress toward the student limit), add a Progress `variant`, and document the no-complex-expressions-in-object-literals rule in AGENTS.md. * refactor(billing): address PR review on the limits work - Dedupe new student profile IDs before the cohort seat check so duplicate batch entries can't overcount against the cap (Greptile P1). - Drive the org-sidebar upgrade indicator from a dynamic nav-item `upgrade` flag (audience config declares `upgradeResource: 'students'`; groups set it from a `limitsReached` map) instead of a hardcoded path check. - Collapse the audience Import button into a single button with ternary `disabled`/`href`. - Simplify the notify-students-over-limit upgrade link to app.classroomio.com. - Drop the comment on the org `limits` field. - Add .greptile/rules.md documenting the manual one-time db/src/scripts convention (operator-controlled reruns) so idempotency isn't reflagged. * fix(billing): name the org in the enroll capacity message Change the enroll-page student-limit message from "This course has reached its student capacity" to "{orgName} has reached its student capacity", since the cap is org-wide, not course-specific. Pass orgName from the loaded org on the page and from the currentOrg store in the enroll onError snackbar. * style(billing): use PremiumIcon for the Authentication upgrade indicator Replace the RocketIcon on paid settings sub-items (e.g. Authentication) with the PremiumIcon used on the Audience item, right-aligned (ml-auto) to match.
2026-07-12 11:33:04 +01:00
parent 0b5247bed3
commit fd8bec3e70
50 changed files with 740 additions and 109 deletions
@@ -0,0 +1,70 @@
+/**
+ * One-time (manual, not cron) backfill: email admins of every free-plan org
+ * that already exceeds the student limit, so they know new enrolments/invites
+ * are now blocked. Dry-run by default; pass --execute to actually send.
+ *
+ * Usage:
+ *   pnpm db:notify-students-over-limit             # dry run (default)
+ *   pnpm db:notify-students-over-limit -- --execute # send emails
+ */
+import 'dotenv/config';
+
+import { buildEmailBranding, sendEmail } from '@cio/email';
+import { PLAN, getStudentLimit, isOrgOnFreePlan } from '@cio/utils/plans';
+
+import {
+  countActiveStudents,
+  getOrganizationAdminEmails,
+  getOrganizations
+} from '../queries/organization/organization';
+
+async function main() {
+  const execute = process.argv.includes('--execute');
+  const orgs = await getOrganizations();
+  const limit = getStudentLimit(PLAN.BASIC);
+
+  let notified = 0;
+
+  for (const org of orgs) {
+    const isFree = isOrgOnFreePlan({ plans: org.plans, isSelfHosted: false, orgId: org.id });
+    if (!isFree) continue;
+
+    const studentCount = await countActiveStudents(org.id);
+    if (studentCount <= limit) continue;
+
+    const admins = await getOrganizationAdminEmails(org.id);
+    if (!admins.length) {
+      console.log(`Skipping ${org.name} (${org.id}): ${studentCount}/${limit} but no admin emails`);
+      continue;
+    }
+
+    console.log(
+      `${execute ? 'Notifying' : '[dry-run] Would notify'} ${org.name} (${org.id}): ${studentCount}/${limit} students → ${admins.length} admin(s)`
+    );
+
+    if (execute) {
+      const branding = buildEmailBranding({ name: org.name, avatarUrl: org.avatarUrl, theme: org.theme });
+      const upgradeUrl = `https://app.classroomio.com/org/${org.siteName ?? ''}?upgrade=true`;
+
+      await Promise.all(
+        admins.map((admin) =>
+          sendEmail('studentLimitReached', {
+            to: admin.email,
+            fields: { orgName: org.name, studentCount, studentLimit: limit, upgradeUrl, branding }
+          })
+        )
+      );
+
+      notified++;
+    }
+  }
+
+  console.log(execute ? `Done. Notified ${notified} org(s).` : 'Dry run complete — re-run with --execute to send.');
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });