docs(billing): move limit-notification rationale to TSDoc, correct tables warn-once behavior

Author: waleedlatif1

apps/sim/lib/billing/core/limit-notifications.ts

@@ -152,15 +152,22 @@ async function resolveRecipients(
  * Send a usage-limit threshold email (80% warning / 100% reached) for a
  * non-credit category, edge-triggered on the mutation that changed usage.
  *
- * Dedup + re-arm: the highest threshold already emailed is persisted per
- * category on `user_stats` / `organization`. The send is gated on an atomic
- * {@link claimThreshold}, so a threshold emails exactly once per crossing even
- * under concurrent calls; it re-arms once usage drops below {@link REARM_BELOW}.
- * Best-effort — callers fire-and-forget; failures never block the mutation.
+ * Flow: bail when billing is off or the limit is non-positive; re-arm the
+ * persisted threshold when current usage is back in the low band; then (for
+ * increases) resolve eligible recipients and atomically claim the threshold
+ * before sending. Re-arm and claim are mutually exclusive per call — re-arm only
+ * fires when `desired === 0` — so the dedup stays a single atomic
+ * {@link claimThreshold} with no re-arm/claim interleaving race. Recipients are
+ * resolved with opt-outs applied BEFORE the claim, so an opted-out recipient
+ * never burns the threshold (which would suppress a later email once
+ * notifications are re-enabled). Per-recipient send failures are isolated.
  *
- * Mirrors the credits path in `maybeSendUsageThresholdEmail`: skips when billing
- * is disabled, respects the per-user notifications toggle and unsubscribe
- * preferences, and emails org admins for organization-scoped limits.
+ * The highest threshold already emailed is persisted per category on
+ * `user_stats` / `organization`; it re-arms once usage drops below
+ * {@link REARM_BELOW}. Best-effort — callers fire-and-forget; failures never
+ * block the mutation. Mirrors the credits path in `maybeSendUsageThresholdEmail`:
+ * respects the per-user notifications toggle and unsubscribe preferences, and
+ * emails org admins for organization-scoped limits.
  */
 export async function maybeSendLimitThresholdEmail(params: {
   category: LimitCategory
@@ -185,8 +192,6 @@ export async function maybeSendLimitThresholdEmail(params: {
 }): Promise<void> {
   try {
     if (!isBillingEnabled) return
-    // A non-positive limit can't yield a percentage; a zero/negative `currentUsage`
-    // still needs to re-arm below, so it is handled by the `desired === 0` return.
     if (params.limit <= 0) return
 
     const { category, scope } = params
@@ -196,20 +201,12 @@ export async function maybeSendLimitThresholdEmail(params: {
     const stateId = scope === 'user' ? params.userId : params.organizationId
     if (!stateId) return
 
-    // Re-arm when current usage is back in the low band, so a fresh climb re-notifies.
-    // Re-arm and claim are mutually exclusive (re-arm only when desired === 0), which
-    // keeps the dedup a single atomic claim with no re-arm/claim interleaving race.
     if (percent < REARM_BELOW) {
       await rearmThreshold(scope, stateId, category)
     }
 
-    // Usage-decrease callers re-arm only — a drop is never a fresh crossing to email.
     if (params.rearmOnly || desired === 0) return
 
-    // Resolve eligible recipients (opt-outs filtered) BEFORE claiming, so the
-    // dedup state only advances when an email will actually be sent — otherwise
-    // an opted-out recipient would silently burn the threshold and suppress a
-    // later email after notifications are re-enabled.
     const recipients = await resolveRecipients(scope, params)
     if (recipients.length === 0) return
 
@@ -221,7 +218,6 @@ export async function maybeSendLimitThresholdEmail(params: {
 
     let sent = 0
     for (const r of recipients) {
-      // Isolate per-recipient failures so one bad send doesn't skip the rest.
       try {
         const html = await renderLimitThresholdEmail({
           kind,

apps/sim/lib/billing/core/usage.ts

@@ -841,8 +841,6 @@ export async function maybeSendUsageThresholdEmail(params: {
     const baseUrl = getBaseUrl()
     const isFreeUser = params.planName === 'Free'
 
-    // Live deep-links. Without a workspaceId, fall back to `/workspace` (resolves
-    // to the user's default workspace) rather than a dropped query param.
     const upgradeCreditsLink = params.workspaceId
       ? `${baseUrl}${buildUpgradeHref(params.workspaceId, 'credits')}`
       : `${baseUrl}/workspace`

apps/sim/lib/billing/storage/tracking.ts

@@ -100,7 +100,6 @@ export async function incrementStorageUsage(
     throw error
   }
 
-  // Fire-and-forget (errors swallowed internally) so the email never adds upload latency.
   if (workspaceId) {
     void maybeNotifyStorageLimit(userId, workspaceId)
   }
@@ -153,7 +152,6 @@ export async function decrementStorageUsage(
     throw error
   }
 
-  // Re-arm only: usage dropped, so this never sends.
   if (workspaceId) {
     void maybeNotifyStorageLimit(userId, workspaceId, true)
   }

apps/sim/lib/table/billing.ts

@@ -46,16 +46,18 @@ async function maybeNotifyTableRowLimit(
 
 /**
  * Fire-and-forget the table row-limit threshold email for an accepted insert,
- * gated so only near-limit writes pay the cost. Shared by every insert path
- * ({@link assertRowCapacity} and the transactional upsert/import branches that
- * check capacity with {@link wouldExceedRowLimit} instead). Pass the pre-insert
- * `currentRowCount` and `addedRows` so the projected count drives the notify gate.
+ * gated (>= {@link TABLE_ROW_NOTIFY_PERCENT}) so only near-limit writes pay the
+ * cost. Shared by every insert path ({@link assertRowCapacity} and the
+ * transactional upsert/import branches that check capacity with
+ * {@link wouldExceedRowLimit} instead). Pass the pre-insert `currentRowCount` and
+ * `addedRows` so the projected count drives the gate.
  *
- * Re-arm (allowing a fresh warning) happens on any insert that lands the table
- * back below the re-arm band. Deleting straight below the band and then jumping
- * back over a threshold in a single insert (with no intermediate write) is a
- * best-effort gap — the 100% reached email and first-time crossings are
- * unaffected. This keeps the dedup a single atomic claim with no re-arm/claim race.
+ * Because the gate only fires at/above the warn band, tables warn once per
+ * threshold and do not re-arm: a table that hit a threshold then dropped (via
+ * deletes, which have no notify hook) won't re-warn on a later climb. This is a
+ * deliberate trade-off — re-arm is storage-only (via its decrement hook), which
+ * avoids per-delete billing-table reads. The 100% reached and first-time
+ * crossings are unaffected, and the dedup stays a single atomic claim (no race).
  */
 export function notifyTableRowUsage(params: {
   workspaceId: string

apps/sim/lib/table/import-data.ts

@@ -179,7 +179,6 @@ export async function importAppendRows(
     }
     return { inserted, table: working }
   })
-  // Post-commit: a pre-commit notify would email/burn the claim for a rolled-back import.
   notifyTableRowUsage({
     workspaceId: ctx.workspaceId,
     currentRowCount: table.rowCount,
@@ -219,7 +218,6 @@ export async function importReplaceRows(
       requestId
     )
   })
-  // Post-commit: footprint is the new set (prior rows deleted → prior count 0).
   notifyTableRowUsage({
     workspaceId: data.workspaceId,
     currentRowCount: 0,

apps/sim/lib/table/import-runner.ts

@@ -217,7 +217,6 @@ export async function runTableImport(payload: TableImportPayload): Promise<void>
         { ...table, schema },
         requestId
       )
-      // Post-commit (per batch): pre-batch count as prior, actual inserted as the delta.
       notifyTableRowUsage({
         workspaceId,
         currentRowCount: existingRowCount + inserted,

apps/sim/lib/table/rows/service.ts

@@ -144,7 +144,6 @@ export async function insertRow(
     now,
   })
 
-  // Post-commit: a pre-commit notify would email/burn the dedup claim for a rolled-back insert.
   notifyTableRowUsage({
     workspaceId: table.workspaceId,
     currentRowCount: table.rowCount,
@@ -209,7 +208,6 @@ export async function batchInsertRows(
   })
 
   const result = await db.transaction((trx) => batchInsertRowsWithTx(trx, data, table, requestId))
-  // Post-commit: notify with the actual inserted count, so a rolled-back batch never emails.
   notifyTableRowUsage({
     workspaceId: table.workspaceId,
     currentRowCount: table.rowCount,
@@ -370,7 +368,6 @@ export async function replaceTableRows(
     addedRows: data.rows.length,
   })
   const result = await db.transaction((trx) => replaceTableRowsWithTx(trx, data, table, requestId))
-  // Post-commit: footprint is the new set (prior rows deleted → prior count 0).
   notifyTableRowUsage({
     workspaceId: table.workspaceId,
     currentRowCount: 0,
@@ -697,7 +694,6 @@ export async function upsertRow(
   )
 
   if (result.operation === 'insert') {
-    // assertRowCapacity can't run inside the upsert tx, so notify here post-commit.
     notifyTableRowUsage({
       workspaceId: data.workspaceId,
       currentRowCount: table.rowCount,

apps/sim/lib/table/service.ts

@@ -370,7 +370,6 @@ export async function createTable(
     throw error
   }
 
-  // Post-commit: starter rows landed, so notify here (a rolled-back create never emails).
   if (initialRowCount > 0 && rowLimit !== undefined) {
     notifyTableRowUsage({
       workspaceId: data.workspaceId,