fix(insights): preserve sub-credit activity in the usage heatmap

Author: waleedlatif1

apps/docs/content/docs/platform/enterprise/usage-tracking.mdx

@@ -16,7 +16,9 @@ Organization owners and admins open **Settings → Organization → Insights**.
 | **Last 7 days** / **Last 30 days** | Rolling window ending now. |
 | **Custom range** | Selected dates, up to 92 days. |
 
-The period applies to every tab. Daily bars use your browser's timezone, while billing periods begin at a fixed UTC instant. The first and last bars can be partial. Different timezones can split the same total differently across days.
+The period applies to every tab's charts and breakdowns. The **Usage heatmap** below the credit chart in Overview and workspace details always shows the last 365 days, including today's partial day. Hover, select, or use the arrow keys to inspect a day. A positive charge below one displayed credit reads **<1 credit** and remains colored.
+
+Daily bars and heatmap cells use your browser's timezone, while billing periods begin at a fixed UTC instant. The first and last bars can be partial. Different timezones can split the same total differently across days.
 
 Spend is in **credits**, where 1 credit = $0.005; the UI rounds displayed credits. [Logs](/logs-debugging/logging) and Logs API costs are in USD, while Billing and run-resource API amounts use their documented credit units. Check the endpoint contract before comparing amounts. See [cost calculation](/platform/costs).
 
@@ -67,7 +69,7 @@ Each charge has one source. The exact **Agent block** label in Insights refers t
 
 An ordinary Agent block's hosted model calls remain under Workflow. The Workflow base charge applies even without model calls. To assess a workflow using the Sim Chat block, read its Workflow charges and the separately metered Agent block source; neither charge is counted twice.
 
-A hosted-key tool called inside a workflow belongs to Workflow; the same tool called directly belongs to API tool call. Chat panel, API agent, and Inbox charges cannot be separated by source. Dedicated workspace attribution can distinguish them when those surfaces actually name different workspaces. Usage without a workspace appears under **No workspace** and remains part of the organization total.
+A hosted-key tool called inside a workflow belongs to Workflow; the same tool called directly belongs to API tool call. Chat panel, API agent, and Inbox charges cannot be separated by source. Dedicated workspace attribution can distinguish them when those surfaces actually name different workspaces. Usage without a workspace link appears under **Unassigned usage** and remains part of the organization total. This includes organization-level activity and retained charges from permanently deleted workspaces; the row cannot distinguish between them.
 
 ### Reconcile totals
 

apps/sim/ee/organization-usage/components/usage-heatmap.tsx

@@ -3,7 +3,7 @@
 import { useRef, useState } from 'react'
 import { cn, scrollFadeAttributes, scrollFadeXClass, Tooltip, useScrollEdges } from '@sim/emcn'
 import type { OrganizationUsageCalendar } from '@/lib/api/contracts/organization-usage'
-import { formatCreditsLabel } from '@/lib/billing/credits/conversion'
+import { formatApportionedCreditCost } from '@/lib/billing/credits/conversion'
 import { USAGE_PALETTE_CLASS } from '@/ee/organization-usage/constants'
 
 const LEVEL_CLASSES = [
@@ -34,7 +34,7 @@ interface UsageHeatmapProps {
 }
 
 function formatDayUsage(day: OrganizationUsageCalendar['days'][number]) {
-  return `${formatCreditsLabel(day.credits)} on ${DAY_FORMAT.format(new Date(`${day.date}T00:00:00Z`))}`
+  return `${formatApportionedCreditCost(day.credits, day.hasCost)} on ${DAY_FORMAT.format(new Date(`${day.date}T00:00:00Z`))}`
 }
 
 /** Calendar dates stay in UTC for layout; they already describe the viewer's local days. */
@@ -52,6 +52,7 @@ export function UsageHeatmap({ days }: UsageHeatmapProps) {
   const weeks = Math.ceil((offset + days.length) / 7)
   const peak = Math.max(...days.map((day) => day.credits), 1)
   const total = days.reduce((sum, day) => sum + day.credits, 0)
+  const hasCost = days.some((day) => day.hasCost)
   const months = days.flatMap((day, index) => {
     const date = new Date(`${day.date}T00:00:00Z`)
     if (date.getUTCDate() !== 1) return []
@@ -99,8 +100,9 @@ export function UsageHeatmap({ days }: UsageHeatmapProps) {
             >
               {days.map((day, index) => {
                 const position = index + offset
-                const level =
-                  day.credits === 0 ? 0 : Math.min(4, Math.ceil(Math.sqrt(day.credits / peak) * 4))
+                const level = day.hasCost
+                  ? Math.max(1, Math.min(4, Math.ceil(Math.sqrt(day.credits / peak) * 4)))
+                  : 0
                 const label = formatDayUsage(day)
                 return (
                   <Tooltip.Root key={day.date}>
@@ -160,7 +162,7 @@ export function UsageHeatmap({ days }: UsageHeatmapProps) {
         <span aria-live='polite'>
           {selectedDay
             ? formatDayUsage(selectedDay)
-            : `${formatCreditsLabel(total)} in the last 365 days`}
+            : `${formatApportionedCreditCost(total, hasCost)} in the last 365 days`}
         </span>
         <div
           className='flex items-center gap-1'

apps/sim/lib/api/contracts/organization-usage.ts

@@ -310,7 +310,13 @@ export type OrganizationUsageEventPage = z.output<typeof organizationUsageEvents
 
 const organizationUsageCalendarResponseSchema = z.object({
   days: z
-    .array(z.object({ date: z.iso.date(), credits: z.number().int().nonnegative() }))
+    .array(
+      z.object({
+        date: z.iso.date(),
+        credits: z.number().int().nonnegative(),
+        hasCost: z.boolean(),
+      })
+    )
     .length(365),
 })
 export type OrganizationUsageCalendar = z.output<typeof organizationUsageCalendarResponseSchema>

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

@@ -38,6 +38,12 @@ export const getOrganizationUsageCalendar = defineAuthorizedOrganizationUsageUse
     const credits = apportionCredits(
       days.map((day) => ({ key: day, dollars: dollars.get(day) ?? 0 }))
     )
-    return { days: days.map((date) => ({ date, credits: credits[date] ?? 0 })) }
+    return {
+      days: days.map((date) => ({
+        date,
+        credits: credits[date] ?? 0,
+        hasCost: (dollars.get(date) ?? 0) > 0,
+      })),
+    }
   },
 })

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

@@ -114,6 +114,25 @@ describe('getOrganizationUsageOverview', () => {
     expect(result.days.filter((entry) => entry.credits === 0)).toHaveLength(364)
   })
 
+  it('distinguishes paid calendar days from empty days when credits round to zero', async () => {
+    const previousDay = new Date(NOW.getTime() - 86_400_000).toISOString().slice(0, 10)
+    mocks.readUsageDays.mockResolvedValue([
+      [previousDay, [{ key: 'workflow', cost: 0.002, events: 1 }]],
+      [day, [{ key: 'workflow', cost: 0.002, events: 1 }]],
+    ])
+    const result = await getOrganizationUsageCalendar.execute({
+      principal: session,
+      input: { organizationId: 'org-1', timezone: 'UTC' },
+    })
+    expect(result.days.find((entry) => entry.date === day)).toEqual({
+      date: day,
+      credits: 0,
+      hasCost: true,
+    })
+    expect(result.days[0]).toMatchObject({ credits: 0, hasCost: false })
+    expect(result.days.reduce((sum, entry) => sum + entry.credits, 0)).toBe(1)
+  })
+
   it('reads names only for the kept rows, however large a tie at the cutoff', async () => {
     mocks.readUsageGroups.mockResolvedValue(
       Array.from({ length: 12 }, (_, index) => ({

packages/emcn/src/components/charts/bar-chart.tsx

@@ -127,7 +127,7 @@ function BarChartComponent(props: BarChartProps) {
   const tickValues = resolveBarTickValues(Math.max(...totals, 0))
   const maxValue = tickValues[tickValues.length - 1]
   const tickLabels = tickValues.map((value) =>
-    unit ? formatBarValue(value, unit) : formatChartCompactNumber(value)
+    value === 0 ? '0' : unit ? formatBarValue(value, unit) : formatChartCompactNumber(value)
   )
   const padding = resolveChartPadding(tickLabels)
   const chartWidth = width - padding.left - padding.right