fix(email): restore billing_period_stats cron and fix period calculation

[riderx]

Summary (AI generated)

• Root cause: process_billing_period_stats_email() existed but was never registered in cron_tasks after the cron refactor, so org:billing_period_stats was never queued (matches “not sent in last 30 days”).
• Re-register daily job at 12:00 UTC and restore service_role execute grant.
• Simplify anniversary detection to match get_cycle_info_org anchor-day logic.
• Fix period math in the email handler: billing cycles are half-open [start, end); metrics now use inclusive end end - 1 day (previously included the first day of the next cycle).
• Sum credits via new get_org_credits_used_in_period RPC (avoids PostgREST 1000-row undercount).
• Include build time in email metadata/percentages.
• Add pgTAP + unit coverage for cron registration and date helpers.

Motivation (AI generated)

Billing anniversary stats emails stopped firing after the move to table-driven cron tasks. Customers and Capgo lost the renewal-day usage/upgrade email, and the period bounds used for metrics/credits were inconsistent.

Business Impact (AI generated)

Restores a billed-org engagement/upsell email on each renewal day with more accurate usage numbers, so plan recommendations are based on the completed cycle instead of leaking the next cycle’s first day or truncating credit sums.

Test Plan (AI generated)

• Unit tests for date/period helpers (tests/billing-period-stats.unit.test.ts)
• Lint clean on changed TS
• CI pgTAP supabase/tests/63_test_billing_period_stats_email.sql (cron registration, anniversary queue, non-anniversary skip, grants)
• After deploy: confirm cron_tasks has billing_period_stats_email enabled at hour 12
• On an org whose Stripe anchor day is today, confirm a cron_email message with type=billing_period_stats and correct cycleStart/cycleEnd
• Confirm Bento receives org:billing_period_stats with expected metadata

Generated with AI

  

Summary by CodeRabbit

• New Features

  • Billing-period statistics now enrich billing email payloads with additional timing fields and correct period start/end values.
  • Added an RPC to compute organization credits used within a billing period.
  • Added a helper to determine billing-cycle anniversary windows and scheduled the billing-period stats email job for 12:00 UTC.

• Bug Fixes

  • Improved UTC billing-cycle boundary handling using consistent half-open windows, with validation to prevent invalid ranges.
  • Updated credits calculations to use the new period-scoped RPC.

• Tests

  • Added unit tests for UTC date helpers and metrics-range conversion.
  • Added an end-to-end SQL regression test for cron scheduling and queued email payloads, including month-end cases.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 5 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f3dc885b-1136-454f-8146-ea98b5cfd025

📥 Commits

Reviewing files that changed from the base of the PR and between f8e53da and ae5d90f.

📒 Files selected for processing (4)

• supabase/functions/_backend/triggers/cron_email.ts
• supabase/migrations/20260725112951_register_billing_period_stats_email_cron.sql
• supabase/tests/63_test_billing_period_stats_email.sql
• tests/billing-period-stats.backtest.unit.test.ts

📝 Walkthrough

Walkthrough

The billing-period statistics email flow now uses UTC-safe date boundaries, half-open billing windows, an RPC for credit aggregation, updated metadata, anniversary-based cron scheduling, and end-to-end and unit test coverage.

Changes

Billing period statistics email

Layer / File(s)	Summary
Database RPC and cron scheduling supabase/migrations/20260725112951_register_billing_period_stats_email_cron.sql	Adds the credits aggregation RPC, anniversary cycle helper, queue processor, privileges, and enabled hourly cron task.
Billing period computation and email metrics supabase/functions/_backend/triggers/cron_email.ts, */supabase.types.ts	Adds UTC date helpers, derives billing ranges, calls metric and credit RPCs, validates ranges, updates email metadata, and adds RPC typings.
Billing period scheduling and utility tests supabase/tests/63_test_billing_period_stats_email.sql, tests/billing-period-stats.unit.test.ts	Validates cron registration, anniversary queue behavior, non-anniversary suppression, month-end handling, RPC half-open semantics, and UTC date calculations.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CronTask
  participant process_billing_period_stats_email
  participant cron_email
  participant handleBillingPeriodStats
  participant get_total_metrics
  participant get_org_credits_used_in_period

  CronTask->>process_billing_period_stats_email: run billing anniversary check
  process_billing_period_stats_email->>cron_email: enqueue billing_period_stats job
  cron_email->>handleBillingPeriodStats: process cycle dates
  handleBillingPeriodStats->>get_total_metrics: fetch period metrics
  handleBillingPeriodStats->>get_org_credits_used_in_period: fetch credits in half-open window

Loading

Suggested labels: codex

Suggested reviewers: dalanir, wcaleniewolny

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: restoring the billing cron and correcting billing-period calculations.
Description check	✅ Passed	The description covers summary, motivation, impact, and test plan; the missing screenshots and checklist are non-critical for this backend change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[codspeed-hq]

Merging this PR will not alter performance

✅ 43 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing cursor/fix-billing-period-stats-email-6444 (ae5d90f) with main (c4b31f0)²}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (0e3cfe3) during the generation of this report, so c4b31f0 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_a28f4540-5afc-4bda-9756-011a3c66853c)

[cursor]

Stale comment

Risk: medium. Cursor Bugbot did not complete (usage limit reached), so automated review is incomplete. Human review is needed for this billing/cron migration change; reviewers assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver External}

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit) so automated review did not complete. Human review needed for billing-period cron migration and email trigger changes. Reviewer assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@supabase/functions/_backend/triggers/cron_email.ts`:
- Around line 483-497: Regenerate the Supabase types with bun types so
get_org_credits_used_in_period is available in the generated Database
definitions, then remove the (supabase.rpc as any) cast and use the typed RPC
call. In the credits lookup branch, do not continue with creditsUsed set to zero
when creditsError occurs; propagate or otherwise abort the billing-email flow so
failed credit retrieval cannot produce a misleading zero-credit report.

In
`@supabase/migrations/20260725112951_register_billing_period_stats_email_cron.sql`:
- Around line 44-63: Update the billing anniversary and previous-cycle
calculations around v_anniversary, v_prev_cycle_start, and v_prev_cycle_end to
handle anchors on the 29th–31st when the current or previous month is shorter,
clamping to that month’s final valid day or restoring the prior CASE rollover
behavior. Ensure February month-end anniversaries are recognized without
shifting the cycle by a month, and add a test covering this case.

In `@supabase/tests/63_test_billing_period_stats_email.sql`:
- Around line 12-15: The test currently verifies only that
get_org_credits_used_in_period exists. Add a functional case that seeds
usage_credit_consumptions at p_start, just before p_end, and exactly at p_end,
then assert the function’s expected sum includes the first two rows and excludes
the p_end row.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 49f8fbc8-ed5b-401b-b4ee-c1579486d637

📥 Commits

Reviewing files that changed from the base of the PR and between 0e3cfe3 and 7403144.

📒 Files selected for processing (4)

• supabase/functions/_backend/triggers/cron_email.ts
• supabase/migrations/20260725112951_register_billing_period_stats_email_cron.sql
• supabase/tests/63_test_billing_period_stats_email.sql
• tests/billing-period-stats.unit.test.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• Cap-go/capacitor-updater (manual)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_6c382b26-5f72-4005-b0d2-b4717469318b)

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is still needed for this billing/cron migration; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped so automated review did not complete, and this billing/cron migration exceeds the low-risk approval threshold. Human review still needed; reviewers already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver External}

[cubic-dev-ai]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_17d75838-a9d1-457c-a25e-759e7ea4905b)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_e5d26530-a242-43ea-b57b-64fa8927bab4)

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is still needed for this billing/cron migration; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver External}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_37837399-67c1-4b6c-9889-057f68f38b2c)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_d918e308-32a8-4e02-bc9a-159632bb98b7)

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is still needed for this billing/cron migration; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete, and this billing/cron migration exceeds the low-risk approval threshold. Human review is still needed; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver External}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_e9fb4913-0f43-4cae-99d5-529032236235)

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is still needed for this billing/cron migration; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete, and this billing/cron migration exceeds the low-risk approval threshold. Human review is still needed; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver External}

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_bcaaeb52-08c4-426b-955a-166f291ee417)

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is still needed for this billing/cron migration; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete, and this billing/cron migration exceeds the low-risk approval threshold. Human review is still needed; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver External}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_9aa43fc5-28d0-4743-b15a-9954dc4af563)

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete, and this billing/cron migration exceeds the low-risk approval threshold. Human review is still needed; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver External}

[cursor]

Stale comment

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is still needed for this billing/cron migration; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_c5a4350c-7587-4478-a89f-9dda8c185f70)

[cursor]

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete, and this billing/cron migration exceeds the low-risk approval threshold. Human review is still needed; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver External}

[cursor]

Risk: medium. Not approving: Cursor Bugbot skipped (usage limit reached), so automated review did not complete. Human review is still needed for this billing/cron migration; reviewers are already assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud