Improve billing clarity and add usage analytics by instance

Author: albertsalgueda

src/app/(dashboard)/[orgSlug]/billing/page.tsx

@@ -1,51 +1,107 @@
 'use client'
 
+import { useInstances } from '@/hooks/use-instances'
 import { useUsage } from '@/hooks/use-usage'
 import { useCredits } from '@/hooks/use-credits'
 import { CurrentSpend } from '@/components/billing/current-spend'
 import { PlanCard } from '@/components/billing/plan-card'
-import { UsageChart } from '@/components/billing/usage-chart'
 import { UsageByModelTable } from '@/components/billing/usage-by-model'
 import { BillingPortalButton } from '@/components/billing/billing-portal-button'
 import { AddCreditsButton } from '@/components/billing/add-credits-button'
 import { AutoTopupSettings } from '@/components/billing/auto-topup-settings'
+import { CreditActivity } from '@/components/billing/credit-activity'
+import { UsageAnalytics } from '@/components/billing/usage-analytics'
 import { Loading } from '@/components/shared/loading'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import { ArrowDownToLine, CreditCard, Sparkles } from 'lucide-react'
 
 export default function BillingPage() {
   const { usage, isLoading: usageLoading } = useUsage()
   const { credits, isLoading: creditsLoading, mutate } = useCredits()
+  const { instances, isLoading: instancesLoading } = useInstances()
 
-  if (usageLoading || creditsLoading) return <Loading />
+  if (usageLoading || creditsLoading || instancesLoading) return <Loading />
+
+  const topUpNowLabel = credits
+    ? `Top Up €${credits.auto_topup_amount_eur} Now`
+    : 'Top Up Now'
 
   return (
     <div className="space-y-6">
-      <div className="flex items-center justify-between">
-        <h1 className="text-2xl font-bold">Billing</h1>
+      <div className="flex flex-col gap-4 lg:flex-row lg:items-center lg:justify-between">
+        <div className="space-y-1">
+          <h1 className="text-2xl font-bold">Billing</h1>
+          <p className="max-w-3xl text-sm text-muted-foreground">
+            Keep an eye on your AI credit balance, monthly usage, and the automatic refill setup that buys more credits when your balance gets low.
+          </p>
+        </div>
         <div className="flex items-center gap-2">
-          <AddCreditsButton onSuccess={() => mutate()} />
+          <AddCreditsButton
+            amountEur={credits?.auto_topup_amount_eur ?? 20}
+            label={topUpNowLabel}
+            onSuccess={() => mutate()}
+          />
           <BillingPortalButton />
         </div>
       </div>
-      <div className="grid gap-4 sm:grid-cols-2">
+
+      <Card className="border border-border/70 bg-gradient-to-br from-muted/40 via-background to-background">
+        <CardHeader>
+          <CardTitle>How billing works</CardTitle>
+        </CardHeader>
+        <CardContent className="grid gap-4 lg:grid-cols-3">
+          <div className="rounded-xl border border-border/70 bg-background/80 p-4">
+            <Sparkles className="h-5 w-5 text-muted-foreground" />
+            <p className="mt-3 font-medium">AI usage spends credits</p>
+            <p className="mt-1 text-sm text-muted-foreground">
+              Every model request deducts from your credit balance, so the balance card tells you how much AI usage you can still run.
+            </p>
+          </div>
+          <div className="rounded-xl border border-border/70 bg-background/80 p-4">
+            <ArrowDownToLine className="h-5 w-5 text-muted-foreground" />
+            <p className="mt-3 font-medium">Auto top-up refills low balances</p>
+            <p className="mt-1 text-sm text-muted-foreground">
+              Choose a refill amount and a threshold. When the balance drops below that threshold, we charge your default card and add more credits automatically.
+            </p>
+          </div>
+          <div className="rounded-xl border border-border/70 bg-background/80 p-4">
+            <CreditCard className="h-5 w-5 text-muted-foreground" />
+            <p className="mt-3 font-medium">Cards and invoices live in Stripe</p>
+            <p className="mt-1 text-sm text-muted-foreground">
+              Use the billing portal to update payment methods, recover from failed top-ups, and review invoices in one place.
+            </p>
+          </div>
+        </CardContent>
+      </Card>
+
+      <div className="grid gap-4 xl:grid-cols-[1.15fr_0.85fr]">
         <CurrentSpend
           baseCost={usage?.base_cost ?? 0}
           tokenCost={usage?.token_cost ?? 0}
           totalCost={usage?.total_cost ?? 0}
           creditBalance={credits?.credit_balance_eur}
+          autoTopupEnabled={credits?.auto_topup_enabled}
+          autoTopupAmountEur={credits?.auto_topup_amount_eur}
+          autoTopupThresholdEur={credits?.auto_topup_threshold_eur}
           autoTopupFailed={credits?.auto_topup_failed}
         />
         <PlanCard currentPlan="starter" />
       </div>
-      {credits && (
-        <AutoTopupSettings
-          enabled={credits.auto_topup_enabled}
-          amountEur={credits.auto_topup_amount_eur}
-          thresholdEur={credits.auto_topup_threshold_eur}
-          failed={credits.auto_topup_failed}
-          onUpdate={() => mutate()}
-        />
-      )}
-      <UsageChart data={usage?.daily ?? []} />
+
+      <div className="grid gap-4 xl:grid-cols-[1.15fr_0.85fr]">
+        {credits && (
+          <AutoTopupSettings
+            enabled={credits.auto_topup_enabled}
+            amountEur={credits.auto_topup_amount_eur}
+            thresholdEur={credits.auto_topup_threshold_eur}
+            failed={credits.auto_topup_failed}
+            onUpdate={() => mutate()}
+          />
+        )}
+        <CreditActivity transactions={credits?.recent_transactions ?? []} />
+      </div>
+
+      <UsageAnalytics instances={instances} />
       <UsageByModelTable data={usage?.by_model ?? []} />
     </div>
   )

src/app/api/billing/credits/route.ts

@@ -79,6 +79,14 @@ export async function PATCH(req: Request) {
   if (parsed.data.auto_topup_threshold_eur !== undefined) {
     updates.auto_topup_threshold_eur = String(parsed.data.auto_topup_threshold_eur)
   }
+  if (
+    parsed.data.auto_topup_enabled !== undefined ||
+    parsed.data.auto_topup_amount_eur !== undefined ||
+    parsed.data.auto_topup_threshold_eur !== undefined
+  ) {
+    // Let the org retry auto top-up after they update settings or fix their card in Stripe.
+    updates.auto_topup_failed = false
+  }
 
   if (Object.keys(updates).length > 0) {
     await supabaseAdmin

src/app/api/billing/usage/route.ts

@@ -2,6 +2,32 @@ import { NextResponse } from 'next/server'
 import { requireAuth } from '@/lib/auth'
 import { getOrgUsageSummary } from '@/lib/stripe/usage'
 
+function getPresetPeriod(period: string): { start: Date; end: Date } | null {
+  const now = new Date()
+
+  if (period === 'current') {
+    return {
+      start: new Date(now.getFullYear(), now.getMonth(), 1),
+      end: new Date(now),
+    }
+  }
+
+  const match = period.match(/^(\d+)d$/)
+  if (!match) return null
+
+  const days = Number(match[1])
+  if (!Number.isFinite(days) || days <= 0) return null
+
+  const start = new Date(now)
+  start.setDate(now.getDate() - (days - 1))
+  start.setHours(0, 0, 0, 0)
+
+  return {
+    start,
+    end: now,
+  }
+}
+
 export async function GET(req: Request) {
   const { org } = await requireAuth()
   const { searchParams } = new URL(req.url)
@@ -11,12 +37,16 @@ export async function GET(req: Request) {
   let periodStart: Date
   let periodEnd: Date
 
-  if (period === 'current') {
-    const now = new Date()
-    periodStart = new Date(now.getFullYear(), now.getMonth(), 1)
-    periodEnd = new Date(now.getFullYear(), now.getMonth() + 1, 0, 23, 59, 59)
+  const presetPeriod = getPresetPeriod(period)
+
+  if (presetPeriod) {
+    periodStart = presetPeriod.start
+    periodEnd = presetPeriod.end
   } else {
     const [year, month] = period.split('-').map(Number)
+    if (!year || !month) {
+      return NextResponse.json({ error: 'Invalid period' }, { status: 400 })
+    }
     periodStart = new Date(year, month - 1, 1)
     periodEnd = new Date(year, month, 0, 23, 59, 59)
   }

src/components/billing/add-credits-button.tsx

@@ -1,15 +1,27 @@
 'use client'
 
-import { useState } from 'react'
+import { useState, type ComponentProps } from 'react'
 import { Button } from '@/components/ui/button'
 import { toast } from 'sonner'
 import { Plus, Loader2 } from 'lucide-react'
 
 interface AddCreditsButtonProps {
   onSuccess?: () => void
+  amountEur?: number
+  label?: string
+  variant?: ComponentProps<typeof Button>['variant']
+  size?: ComponentProps<typeof Button>['size']
+  className?: string
 }
 
-export function AddCreditsButton({ onSuccess }: AddCreditsButtonProps) {
+export function AddCreditsButton({
+  onSuccess,
+  amountEur = 20,
+  label,
+  variant = 'outline',
+  size = 'sm',
+  className,
+}: AddCreditsButtonProps) {
   const [loading, setLoading] = useState(false)
 
   async function handleClick() {
@@ -18,7 +30,7 @@ export function AddCreditsButton({ onSuccess }: AddCreditsButtonProps) {
       const res = await fetch('/api/billing/credits', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ amount_eur: 20 }),
+        body: JSON.stringify({ amount_eur: amountEur }),
       })
       const data = await res.json()
       if (!res.ok) {
@@ -27,7 +39,7 @@ export function AddCreditsButton({ onSuccess }: AddCreditsButtonProps) {
       }
       // For now, show success toast. In production, use Stripe Elements
       // with the clientSecret to confirm the PaymentIntent.
-      toast.success('Top-up initiated. Credits will be added once payment confirms.')
+      toast.success(`Top-up started for €${amountEur}. Credits will be added once payment confirms.`)
       onSuccess?.()
     } catch {
       toast.error('Failed to add credits')
@@ -37,9 +49,15 @@ export function AddCreditsButton({ onSuccess }: AddCreditsButtonProps) {
   }
 
   return (
-    <Button variant="outline" size="sm" onClick={handleClick} disabled={loading}>
+    <Button
+      variant={variant}
+      size={size}
+      className={className}
+      onClick={handleClick}
+      disabled={loading}
+    >
       {loading ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : <Plus className="mr-2 h-4 w-4" />}
-      Add Credits
+      {label ?? `Top Up €${amountEur}`}
     </Button>
   )
 }