feat(billing): align enterprise reporting periods

[icecrasher321]

Summary

• add explicit monthly/yearly Enterprise reporting periods across usage enforcement, member reporting, and admin APIs
• keep Stripe webhook reconciliation authoritative for applied billing terms and harden stale-event/outbox recovery
• paginate admin organization data and expose complete usage, workspace-move, and historical-actor totals
• add a concurrent covering index for organization reporting-period usage reads

Type of Change

• Feature
• Bug fix

Testing

• bun run lint
• bun run check:audits
• bun run check:migrations origin/staging
• bun run type-check
• 257 focused billing/admin tests

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 19, 2026 10:34pm

[cursor]

PR Summary

High Risk
Changes how Enterprise usage periods are resolved and how limits are enforced across APIs, attribution, and admin flows—core billing behavior with broad surface area.

Overview
Introduces Enterprise reporting periods anchored on contract start dates (monthly or annual), with usage and limits evaluated on those windows instead of Stripe subscription periods when metadata applies. Ledger reads switch to createdAt for reporting periods and skip the legacy userStats baseline; billingPeriod.source is carried through billing attribution, update-cost, and direct-v1 admission so enforcement matches recording.

Org billing and roster APIs paginate members (memberLimit/memberOffset, membersTotal, memberPagination) and compute over/near-limit member counts from the full roster without loading every row into the response. Member usage is centralized via getOrganizationMemberUsageSnapshot across org member routes and admin APIs.

Admin dashboard gains Enterprise issuance preflight, billing-terms preview/update, configuration-update and workspace-move retries, paginated organization detail (members, collaborators, workspaces), ledger-based usage on list/detail, historical actor usage, and invoice/cadence fields (invoiceAmountUsd, reportingPeriodAnchorDate) replacing monthly-only naming. Enterprise Stripe outbox intents can queue immutable price/cadence changes and block overlapping updates until reconciliation.

^{Reviewed by Cursor Bugbot for commit 5338449. Configure here.}

[greptile-apps]

Greptile Summary

This PR introduces explicit monthly and yearly Enterprise reporting periods and propagates them through billing attribution, usage enforcement, member reporting, and administrative APIs. It also strengthens Stripe/outbox reconciliation, paginates organization reporting data, adds complete usage and actor aggregates, and creates a concurrent covering index for reporting-period usage reads.

• Resolves calendar-aligned Enterprise reporting windows from billing interval and anchor metadata.
• Uses reporting-period-aware usage aggregation across billing admission, organization members, and admin reporting.
• Adds administrative billing-term preview/update and failed-operation retry endpoints.
• Moves Enterprise reconciliation work into resumable outbox handlers with delivery-state tracking.
• Adds bounded pagination and independent totals for members, collaborators, workspaces, and historical actors.
• Adds a concurrent database index supporting organization usage queries by reporting-period timestamps.

Confidence Score: 5/5

The PR appears safe to merge because no concrete, changed-code-triggered failure remains after reviewing the billing-period, reporting, reconciliation, pagination, and migration changes.

The changed paths consistently introduce explicit reporting-period metadata, bounded pagination, resumable outbox state, and supporting database indexing without an established reachable contract violation or observable failure.

Important Files Changed

Filename	Overview
apps/sim/lib/billing/core/reporting-period.ts	Adds UTC calendar-aligned monthly and yearly Enterprise reporting windows with month-end and leap-year clamping.
apps/sim/lib/billing/calculations/usage-monitor.ts	Propagates resolved billing contexts into usage enforcement so Enterprise reporting periods can drive ledger reads.
apps/sim/lib/billing/core/organization.ts	Centralizes reporting-period-aware member usage snapshots and complete organization-level usage totals.
apps/sim/lib/billing/enterprise-outbox.ts	Extends Enterprise metadata intents with billing terms, delivery revisions, verification state, and member reconciliation payloads.
apps/sim/lib/billing/enterprise-provisioning.ts	Adds billing-term updates, resumable workspace/member reconciliation, and Stripe delivery verification.
apps/sim/lib/billing/webhooks/enterprise.ts	Makes webhook reconciliation authoritative for applied Enterprise terms and delegates larger reconciliation work to the outbox.
apps/sim/lib/admin/dashboard.ts	Adds paginated organization detail collections, aggregate usage reporting, historical actors, and Enterprise billing-term administration.
apps/sim/lib/core/outbox/service.ts	Adds bounded bulk event enqueueing and payload checkpoint support used by resumable Enterprise operations.
packages/db/migrations/0293_workable_jigsaw.sql	Adds the concurrent covering index needed for organization reporting-period usage aggregation.
packages/db/schema.ts	Aligns the Drizzle usage-log index declaration with the new reporting-period query pattern.

Sequence Diagram

sequenceDiagram
  participant Admin
  participant API as Admin API
  participant DB as Postgres
  participant Outbox
  participant Stripe
  participant Webhook

  Admin->>API: Update Enterprise billing terms
  API->>DB: Lock subscription and enqueue revision
  DB-->>Outbox: Pending metadata-sync event
  Outbox->>Stripe: Apply cadence, price, and metadata
  Stripe-->>Outbox: Provider state
  Outbox->>DB: Checkpoint delivery and verification state
  Stripe->>Webhook: Subscription reconciliation event
  Webhook->>DB: Persist authoritative applied terms
  DB-->>API: Reporting period and usage totals

Loading

_{Reviews (1): Last reviewed commit: "Merge remote-tracking branch 'origin/sta..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5338449. Configure here.}