fix(usage): resolve custom bounds in the viewer calendar, bound the open period

Third review round.

Custom ranges were anchored on UTC instants. The picker offers calendar days and
sends `YYYY-MM-DD`, which arrives parsed as UTC midnight, so every non-UTC
viewer's selection was shifted by their offset — a range labelled "Aug 1–31"
covered half of Jul 31 and half of Aug 31 twelve hours east — and it contradicted
the series, whose buckets are already the viewer's calendar days. The resolver
now takes the timezone and reinterprets the same civil dates as midnight there,
through `zonedWallClockToUtc`, and counts the span in civil days so a range
containing a DST transition is not measured as 91.96. The timezone is threaded
through the breakdown, events, and export inputs as well; the contract already
carried it but only the summary consumed it, so the four surfaces would have
resolved one range four ways.

A deployment with no subscription resolves to `defaultBillingPeriod()`, the open
pair 1970…9999. Rendered as a period that produced a thousand monthly buckets
ending in 2053, stopped only by the densifier's loop guard — measured, not
inferred. Self-hosted is exactly where it is reachable, since the usage flag
opens the panel on deployments with no plan at all. An unbounded period now shows
a rolling 30-day window, and its predecessor steps back by that window rather
than by a span of eight millennia. Kept as one window rather than clamping only
the chart, so the series still sums to the headline.

The summary's delta used the `previous-period` preset, which must always return
something and therefore approximates a stripe period's predecessor by stepping
back the current period's length. Stripe periods are not equal-length, so the
comparison could be measured against a window that is not the previous period —
contradicting the comment directly above it. It now calls `resolvePreviousPeriod`
and shows no delta when there is no exact predecessor.

Reversed custom bounds measured a negative span, passed the cap, and returned an
inverted range matching nothing — "no usage" rather than a bad request. They now
throw, classified 400 alongside the too-large error.

Admin organization provisioning reported an unqualified success when workspace
attachment failed. It now returns `attachedWorkspaceIds` and records it on the
audit event, so the incomplete state is visible to the caller and durable after
the fact, rather than known only to the logs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: icecrasher321

apps/sim/app/api/organizations/[id]/usage/breakdown/route.ts

@@ -31,6 +31,7 @@ export const GET = defineInternalJsonRoute({
     preset: query.preset,
     startDate: query.startDate ? new Date(query.startDate) : undefined,
     endDate: query.endDate ? new Date(query.endDate) : undefined,
+    timezone: query.timezone,
     limit: query.limit,
   }),
   useCase: getOrganizationUsageBreakdown,

apps/sim/app/api/organizations/[id]/usage/error-policy.ts

@@ -3,10 +3,14 @@ import {
   internalErrorResponse,
   internalOrchestrationErrorPolicy,
 } from '@/lib/api/server/routes'
-import { UsageWindowRangeTooLargeError } from '@/lib/billing/core/usage-analytics'
+import {
+  UsageWindowRangeInvertedError,
+  UsageWindowRangeTooLargeError,
+} from '@/lib/billing/core/usage-analytics'
 
 /**
- * The window resolver throws when a custom range exceeds its cap, which is a
+ * The window resolver throws when a custom range exceeds its cap or ends before it
+begins, both of which are
  * caller-fixable input error rather than a fault. Without this it fell through to
  * the orchestration policy's `unhandled` branch and every over-long range answered
  * `500 Internal server error`, so the client could neither surface the real reason
@@ -17,7 +21,7 @@ import { UsageWindowRangeTooLargeError } from '@/lib/billing/core/usage-analytic
 export const organizationUsageErrorPolicy = extendInternalErrorPolicy(
   internalOrchestrationErrorPolicy,
   (error) =>
-    error instanceof UsageWindowRangeTooLargeError
+    error instanceof UsageWindowRangeTooLargeError || error instanceof UsageWindowRangeInvertedError
       ? internalErrorResponse(400, { error: error.message })
       : null
 )

apps/sim/app/api/organizations/[id]/usage/events/route.ts

@@ -29,6 +29,7 @@ export const GET = defineInternalJsonRoute({
     preset: query.preset,
     startDate: query.startDate ? new Date(query.startDate) : undefined,
     endDate: query.endDate ? new Date(query.endDate) : undefined,
+    timezone: query.timezone,
     source: query.source,
     limit: query.limit,
     cursor: query.cursor,

apps/sim/app/api/organizations/[id]/usage/export/route.ts

@@ -8,7 +8,10 @@ import {
   exportOrganizationUsageEvents,
   type OrganizationUsageExportRow,
 } from '@/lib/billing/application/organization-usage/export-organization-usage-events'
-import { UsageWindowRangeTooLargeError } from '@/lib/billing/core/usage-analytics'
+import {
+  UsageWindowRangeInvertedError,
+  UsageWindowRangeTooLargeError,
+} from '@/lib/billing/core/usage-analytics'
 import { formatCreditsLabel } from '@/lib/billing/credits/conversion'
 import { ForbiddenOperationError } from '@/lib/core/application'
 import { formatCsvValue, toCsvRow } from '@/lib/core/utils/csv'
@@ -59,6 +62,7 @@ export const GET = withRouteHandler(async (request: NextRequest, context) => {
         preset: query.preset,
         startDate: query.startDate ? new Date(query.startDate) : undefined,
         endDate: query.endDate ? new Date(query.endDate) : undefined,
+        timezone: query.timezone,
         source: query.source,
       },
     })
@@ -75,9 +79,12 @@ export const GET = withRouteHandler(async (request: NextRequest, context) => {
     if (error instanceof ForbiddenOperationError) {
       return NextResponse.json({ error: error.message }, { status: 403 })
     }
-    // A range over the cap is the caller's input, not a fault — the same
+    // A range over the cap, or inverted, is the caller's input — the same
     // classification the three JSON routes make through `organizationUsageErrorPolicy`.
-    if (error instanceof UsageWindowRangeTooLargeError) {
+    if (
+      error instanceof UsageWindowRangeTooLargeError ||
+      error instanceof UsageWindowRangeInvertedError
+    ) {
       return NextResponse.json({ error: error.message }, { status: 400 })
     }
     logger.error('Failed to export organization usage', { error: getErrorMessage(error) })

apps/sim/app/api/v1/admin/organizations/route.ts

@@ -18,7 +18,10 @@
  *   - slug: string - Organization slug (optional, auto-generated from name if not provided)
  *   - ownerId: string - User ID of the organization owner (required)
  *
- * Response: AdminSingleResponse<AdminOrganization & { memberId: string }>
+ * Response: AdminSingleResponse<AdminOrganization & { memberId: string; attachedWorkspaceIds: string[] }>
+ *   `attachedWorkspaceIds` reports which of the owner's workspaces moved under the
+ *   organization. Empty means none did — either the owner had none, or attachment
+ *   failed after the organization was already committed.
  */
 
 import { AuditAction, AuditResourceType, recordAudit } from '@sim/audit'
@@ -173,10 +176,16 @@ export const POST = withRouteHandler(
        * So its failure must not be reported as a failure to create: the organization
        * is already committed, and answering 500 for state that exists left the retry
        * blocked by the existing-membership check above, with no way to reach the
-       * organization at all. Log it and return the organization that was created —
-       * attaching a workspace afterwards is a normal, repeatable operation.
+       * organization at all.
+       *
+       * It must not be reported as an unqualified success either. The outcome is
+       * returned as `attachedWorkspaceIds` and recorded on the audit event, so a
+       * caller sees which workspaces moved — an empty array after a failure is the
+       * explicit incomplete state, and attaching afterwards is a normal repeatable
+       * operation rather than something only the logs know is outstanding.
        */
       let attachedWorkspaceIds: string[] = []
+      let workspaceAttachmentFailed = false
       try {
         ;({ attachedWorkspaceIds } = await attachOwnedWorkspacesToOrganization({
           ownerUserId: ownerId,
@@ -185,6 +194,7 @@ export const POST = withRouteHandler(
           includeArchived: true,
         }))
       } catch (attachError) {
+        workspaceAttachmentFailed = true
         logger.error('Admin API: Created organization but could not attach its workspaces', {
           organizationId,
           ownerId,
@@ -214,13 +224,20 @@ export const POST = withRouteHandler(
         resourceId: organizationId,
         resourceName: name,
         description: `Admin API created organization "${name}"`,
-        metadata: { slug, ownerId, memberId },
+        metadata: {
+          slug,
+          ownerId,
+          memberId,
+          attachedWorkspaceIds,
+          ...(workspaceAttachmentFailed ? { workspaceAttachmentFailed: true } : {}),
+        },
         request,
       })
 
       return singleResponse({
         ...toAdminOrganization(createdOrg),
         memberId,
+        attachedWorkspaceIds,
       })
     } catch (error) {
       if (error instanceof OrganizationSlugInvalidError) {

apps/sim/lib/billing/application/organization-usage/export-organization-usage-events.ts

@@ -21,6 +21,8 @@ export interface OrganizationUsageExportInput {
   preset: UsageWindowPreset
   startDate?: Date
   endDate?: Date
+  /** Viewer calendar, so a date-only custom bound means midnight there. */
+  timezone?: string
   source?: InternalUsageLogSource[]
 }
 
@@ -52,6 +54,7 @@ export const exportOrganizationUsageEvents = defineAuthorizedOrganizationUsageUs
       period: context.period,
       customStart: input.startDate,
       customEnd: input.endDate,
+      timezone: input.timezone,
     })
     const bounds = usageWindowBounds(window)
 

apps/sim/lib/billing/application/organization-usage/get-organization-usage-breakdown.ts

@@ -28,6 +28,8 @@ export interface OrganizationUsageBreakdownInput {
   preset: UsageWindowPreset
   startDate?: Date
   endDate?: Date
+  /** Viewer calendar, so a date-only custom bound means midnight there. */
+  timezone?: string
   /** Narrows to one workspace, for the Workspaces drill-down. */
   workspaceId?: string
   limit: number
@@ -81,6 +83,7 @@ export const getOrganizationUsageBreakdown = defineAuthorizedOrganizationUsageUs
       period: context.period,
       customStart: input.startDate,
       customEnd: input.endDate,
+      timezone: input.timezone,
     })
     const scope = buildUsageAnalyticsScope(context.billingEntity, window)
     const raw = await readUsageBreakdown(scope, input.dimension, input.workspaceId)

apps/sim/lib/billing/application/organization-usage/get-organization-usage-summary.ts

@@ -4,6 +4,7 @@ import type { UsagePeriodSource } from '@/lib/billing/core/reporting-period'
 import {
   buildUsageAnalyticsScope,
   densifyUsageSeries,
+  resolvePreviousPeriod,
   resolveUsageAnalyticsWindow,
   resolveUsageBucket,
   type UsageBucket,
@@ -43,19 +44,25 @@ export const getOrganizationUsageSummary = defineAuthorizedOrganizationUsageUseC
       period: context.period,
       customStart: input.startDate,
       customEnd: input.endDate,
+      timezone: input.timezone,
     })
     const bucket = resolveUsageBucket(window)
     const scope = buildUsageAnalyticsScope(context.billingEntity, window)
 
     /**
-     * The comparison window only exists when it is exactly derivable. A stripe period
-     * has no rule for its predecessor, and no delta beats a delta measured against the
-     * wrong window.
+     * The comparison window only exists when it is exactly derivable.
+     *
+     * `resolvePreviousPeriod` directly, not the `previous-period` preset: that preset
+     * must always return *something*, because a user who explicitly asks for the
+     * previous period has to see a window — so for a stripe period it approximates one
+     * by stepping back the current period's length. That approximation is fine as a
+     * destination and wrong as a baseline, since Stripe periods are not equal-length
+     * and the delta would silently compare against a window that is not the previous
+     * period. No delta beats a delta measured against the wrong window.
      */
-    const comparison =
-      input.preset === 'current-period'
-        ? resolveUsageAnalyticsWindow({ preset: 'previous-period', period: context.period })
-        : null
+    const previousPeriod =
+      input.preset === 'current-period' ? resolvePreviousPeriod(context.period) : null
+    const comparison = previousPeriod ? { kind: 'period' as const, period: previousPeriod } : null
 
     const [totals, seriesRows, previous] = await Promise.all([
       readUsageTotals(scope),

apps/sim/lib/billing/application/organization-usage/list-organization-usage-events.ts

@@ -14,6 +14,8 @@ export interface OrganizationUsageEventsInput {
   preset: UsageWindowPreset
   startDate?: Date
   endDate?: Date
+  /** Viewer calendar, so a date-only custom bound means midnight there. */
+  timezone?: string
   source?: InternalUsageLogSource[]
   limit: number
   cursor?: string
@@ -53,6 +55,7 @@ export const listOrganizationUsageEvents = defineAuthorizedOrganizationUsageUseC
       period: context.period,
       customStart: input.startDate,
       customEnd: input.endDate,
+      timezone: input.timezone,
     })
     const bounds = usageWindowBounds(window)
 

apps/sim/lib/billing/core/usage-analytics.test.ts

@@ -12,6 +12,7 @@ import {
   resolvePreviousPeriod,
   resolveUsageAnalyticsWindow,
   resolveUsageBucket,
+  UsageWindowRangeInvertedError,
   UsageWindowRangeTooLargeError,
 } from '@/lib/billing/core/usage-analytics'
 
@@ -162,6 +163,77 @@ describe('resolveUsageAnalyticsWindow', () => {
     const window = resolveUsageAnalyticsWindow({ preset: 'custom', period: period(), now })
     expect(window.kind).toBe('period')
   })
+
+  it('anchors custom bounds on midnight in the viewer calendar, not UTC', () => {
+    // The picker offers calendar days. Anchoring on the UTC instant shifted every
+    // non-UTC viewer's selection by their offset, and disagreed with the chart,
+    // whose buckets are already the viewer's calendar days.
+    const window = resolveUsageAnalyticsWindow({
+      preset: 'custom',
+      period: period(),
+      customStart: new Date('2026-08-01'),
+      customEnd: new Date('2026-08-31'),
+      timezone: 'America/New_York',
+      now,
+    })
+    expect(window.kind).toBe('range')
+    if (window.kind === 'range') {
+      // Midnight on Aug 1 in New York is 04:00 UTC (EDT, UTC-4).
+      expect(window.from.toISOString()).toBe('2026-08-01T04:00:00.000Z')
+      expect(window.to.toISOString()).toBe('2026-09-01T04:00:00.000Z')
+    }
+  })
+
+  it('refuses a range that ends before it starts', () => {
+    // Inverted bounds measured a negative span, passed the cap check, and produced a
+    // range that matched nothing — indistinguishable from "no usage".
+    expect(() =>
+      resolveUsageAnalyticsWindow({
+        preset: 'custom',
+        period: period(),
+        customStart: new Date('2026-08-31'),
+        customEnd: new Date('2026-08-01'),
+        now,
+      })
+    ).toThrow(UsageWindowRangeInvertedError)
+  })
+
+  it('shows a bounded window for a deployment with no subscription', () => {
+    // `defaultBillingPeriod()` is the open pair 1970…9999. Rendered as a period it
+    // produced 1,000 monthly buckets ending in 2053, stopped only by the densifier's
+    // loop guard — reachable on self-hosted, where the panel opens without a plan.
+    const window = resolveUsageAnalyticsWindow({
+      preset: 'current-period',
+      period: period({
+        source: 'default',
+        start: new Date(0),
+        end: new Date(Date.UTC(9999, 11, 31)),
+      }),
+      now,
+    })
+    expect(window.kind).toBe('range')
+    if (window.kind === 'range') {
+      expect(window.to).toEqual(now)
+      expect(Math.round((window.to.getTime() - window.from.getTime()) / 86_400_000)).toBe(30)
+    }
+  })
+
+  it('steps an unbounded period back by the display window, not by its own length', () => {
+    const window = resolveUsageAnalyticsWindow({
+      preset: 'previous-period',
+      period: period({
+        source: 'default',
+        start: new Date(0),
+        end: new Date(Date.UTC(9999, 11, 31)),
+      }),
+      now,
+    })
+    expect(window.kind).toBe('range')
+    if (window.kind === 'range') {
+      // Not 1970-minus-eight-millennia, which is what deriving it from the span gave.
+      expect(window.from.getUTCFullYear()).toBe(2026)
+    }
+  })
 })
 
 describe('resolvePreviousPeriod', () => {