vibezcheck 0.5.6 → 0.5.8

package/README.md

@@ -1,246 +1,238 @@
 # ✦ VibezCheck
 
-> **The 1-Line Token Meter & Real-Time Billing Engine for AI.**  
-> Track tokens, compute real-time dollar costs, set profit margins, and bill customers with **0ms added latency**.
+> **Track AI token spend and bill users in real time. Setup in 1 line.**  
+> No database needed. No added latency.
 
-[![npm version](https://img.shields.io/npm/v/vibezcheck.svg)](https://npmjs.org/package/vibezcheck)
+[![npm version](https://img.shields.io/npm/v/vibezcheck.svg?color=cb3837)](https://npmjs.org/package/vibezcheck)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/Tests-62%20Passed-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/Tests-95%20Passed-brightgreen.svg)]()
+[![Latency](https://img.shields.io/badge/Latency-0ms%20Added-orange.svg)]()
 
 ---
 
-### The 2-Line Promise
+### The 1-Line Setup
 
+**1. On your server:** wrap your model to track spending and set a profit margin
 ```typescript
-// 1. Server: Wrap your model with automated billing
-const model = vibezcheck('openai/gpt-4o', { customer: 'cus_alex' });
+const model = vibezcheck(openai('gpt-4o-mini'), { pricing: { margin: 1.3 } });
+```
 
-// 2. Client: Drop in the financial HUD
+**2. On your frontend:** drop in the component to see spendings in real time
+```tsx
 <VibezCheck messages={messages} />
 ```
 
+That’s it. You get real-time token tracking, live dollar costs, runaway loop protection, and a sleek spending HUD.
+
 ---
 
-## 🚀 Features
+## What VibezCheck does for you
+
+When you build an AI app, chatbot, or agent:
 
-* **⚡ 0ms Added Latency**: Direct transparent proxy stream; no external server redirects or buffering.
-* **🛡️ Built-in $0.50 Circuit Breaker**: Prevents infinite loops and runaway bills automatically.
-* **🛟 In-Flight Abort Trapper**: Catches and bills tokens even if the customer closes their tab mid-stream.
-* **🪙 BigInt Nano-USD Precision**: Sub-cent financial math ($1 = $10^9$ Nano-USD) eliminating IEEE 754 float drift.
-* **💰 1-Line Profit Margins**: Turn wholesale API costs into retail profits with `pricing: { margin: 1.5 }` (+50% profit).
-* **🆓 Zero-DB Dev Mode**: Run locally on `localhost:3000` with NO database and NO Stripe keys required.
-* **💳 Pluggable SaaS Billing**: Top-ups, checkout sessions, customer portal, and user API keys (`vz_live_...`).
-* **🤖 Multi-Tool Agent Sessions**: Cumulative session budgets across models, Python sandboxes, and web scrapers.
-* **🔄 100% Drop-In Polyfills**: Direct replacement for `@stripe/ai-sdk/meter`, `@stripe/ai-sdk/provider`, and `@stripe/token-meter`.
+* **👀 See spending in real time**: You and your users can see the exact cost (e.g. `$0.0014`) and token count for every turn as it streams in.
+* **🛡️ Never get a surprise $500 bill**: A built-in `$0.50` circuit breaker stops runaway prompts or infinite agent loops automatically before they drain your credit card.
+* **💰 Turn costs into profit**: Add `pricing: { margin: 1.3 }` to mark up wholesale API prices by 30%. You make money on every message without writing custom billing code.
+* **🤖 Works with multiple models**: If a conversation uses GPT-4o-mini, Claude 3.5, or Gemini, VibezCheck automatically breaks down the spending per model.
+* **🆓 Zero database required**: Test locally on `localhost:3000` with zero database tables and zero Stripe keys. It runs straight in memory.
+* **⚡ 0ms added latency**: Streaming is direct and transparent. Spending telemetry attaches cleanly at the very end of the stream without delaying first-token response time.
+* **🧹 Clean context window**: Telemetry stays out of your prompts. When messages get sent back to the model on the next turn, telemetry is automatically stripped so you never waste tokens.
 
 ---
 
-## 📦 Installation
+## 🚀 End-to-End Chatbot Example (Next.js App Router)
+
+Here is a complete, copy-paste ready AI chatbot with live per-message spending receipts and the floating financial HUD:
+
+### 1. Install Dependencies
 
 ```bash
 npm install vibezcheck ai @ai-sdk/openai @ai-sdk/react stripe
 ```
 
----
-
-## ⚡ Quickstart: Zero-DB Dev Mode to Production
-
-### 1. Next.js 15 API Route (`app/api/chat/route.ts`)
+### 2. Server Route (`app/api/chat/route.ts`)
 
 ```typescript
-import { streamText } from 'ai';
+import { convertToModelMessages, streamText, UIMessage } from 'ai';
 import { openai } from '@ai-sdk/openai';
 import { vibezcheck } from 'vibezcheck';
 
+export const maxDuration = 30;
+
 export async function POST(req: Request) {
-  const { messages } = await req.json();
+  const { messages }: { messages: UIMessage[] } = await req.json();
 
   const result = streamText({
-    // Wrap any AI SDK model or use string identifier
+    // ✦ 1 Line: track costs, add 30% profit margin, and set $0.50 runaway safety fuse
     model: vibezcheck(openai('gpt-4o-mini'), {
-      customer: 'user_alex@example.com', // Stripe customer ID or user email
+      customer: 'user_alex@example.com', // User email or Stripe customer ID
       pricing: { margin: 1.3 },         // +30% profit margin
-      maxCostPerCallUSD: 0.50,          // Safety fuse box
+      maxCostPerCallUSD: 0.50,          // Auto-stops if call exceeds $0.50
     }),
-    messages,
+    instructions: 'You are a helpful AI assistant.',
+    messages: await convertToModelMessages(messages),
   });
 
-  return result.toDataStreamResponse();
+  // ✦ Transmits stream with verified spending telemetry attached
+  return vibezcheck.toResponse(result);
 }
 ```
 
-### 2. Frontend React Client (`app/page.tsx`)
+### 3. Frontend Client (`app/page.tsx`)
 
 ```tsx
 'use client';
 
 import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
 import { useState } from 'react';
-import { VibezCheck } from 'vibezcheck/ui';
+import { VibezReceipt, VibezCheck } from 'vibezcheck/ui';
 
-export default function Chat() {
+export default function ChatPage() {
   const [input, setInput] = useState('');
-  const { messages, sendMessage } = useChat();
+  const { messages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  });
 
   return (
-    <div className="flex flex-col w-full max-w-md py-24 mx-auto stretch">
-      {messages.map(message => (
-        <div key={message.id} className="whitespace-pre-wrap">
-          {message.role === 'user' ? 'User: ' : 'AI: '}
-          {message.parts.map((part, i) => {
-            switch (part.type) {
-              case 'text':
-                return <div key={`${message.id}-${i}`}>{part.text}</div>;
-            }
-          })}
-        </div>
-      ))}
-
+    <div className="flex flex-col w-full max-w-lg py-20 mx-auto px-4 min-h-screen">
+      {/* Messages Stream */}
+      <div className="flex-1 space-y-4 mb-28">
+        {messages.map((message) => (
+          <div
+            key={message.id}
+            className={`p-4 rounded-2xl border ${
+              message.role === 'user'
+                ? 'bg-zinc-100 dark:bg-zinc-800 border-zinc-200 dark:border-zinc-700 ml-10'
+                : 'bg-white dark:bg-zinc-900 border-zinc-200 dark:border-zinc-800 mr-10 shadow-sm'
+            }`}
+          >
+            <div className="text-xs font-semibold uppercase tracking-wider text-zinc-400 mb-1.5">
+              {message.role === 'user' ? 'You' : 'Assistant'}
+            </div>
+
+            {/* Message Text */}
+            <div className="text-sm whitespace-pre-wrap leading-relaxed">
+              {message.parts
+                ? message.parts.map((part, index) => {
+                    switch (part.type) {
+                      case 'text':
+                        return <span key={index}>{part.text}</span>;
+                      default:
+                        return null;
+                    }
+                  })
+                : message.content}
+            </div>
+
+            {/* ✦ 1 Line: Micro-Receipt showing tokens, micro-cost, model, and latency */}
+            {message.role === 'assistant' && (
+              <div className="mt-3 flex justify-end">
+                <VibezReceipt message={message} />
+              </div>
+            )}
+          </div>
+        ))}
+
+        {status === 'streaming' && (
+          <div className="text-xs text-zinc-400 italic">Assistant is typing...</div>
+        )}
+      </div>
+
+      {/* Input Form */}
       <form
-        onSubmit={e => {
+        onSubmit={(e) => {
           e.preventDefault();
+          if (!input.trim()) return;
           sendMessage({ text: input });
           setInput('');
         }}
+        className="fixed bottom-0 left-0 right-0 p-4 bg-white/80 dark:bg-zinc-950/80 backdrop-blur-md border-t border-zinc-200 dark:border-zinc-800"
       >
-        <input
-          className="fixed dark:bg-zinc-900 bottom-0 w-full max-w-md p-2 mb-8 border border-zinc-300 dark:border-zinc-800 rounded shadow-xl"
-          value={input}
-          placeholder="Say something..."
-          onChange={e => setInput(e.currentTarget.value)}
-        />
+        <div className="max-w-lg mx-auto flex gap-2">
+          <input
+            className="flex-1 p-3 text-sm rounded-xl border border-zinc-300 dark:border-zinc-700 bg-white dark:bg-zinc-900 shadow-sm focus:outline-none focus:ring-2 focus:ring-zinc-900 dark:focus:ring-zinc-100"
+            value={input}
+            placeholder="Type your prompt..."
+            onChange={(e) => setInput(e.target.value)}
+          />
+          <button
+            type="submit"
+            disabled={status === 'streaming' || !input.trim()}
+            className="px-5 py-3 bg-zinc-900 dark:bg-zinc-100 text-white dark:text-zinc-900 text-sm font-semibold rounded-xl hover:opacity-90 disabled:opacity-50 transition"
+          >
+            Send
+          </button>
+        </div>
       </form>
 
-      {/* ✦ 1-Line Token Meter & Financial HUD: Works with zero database & zero Stripe in Dev Mode */}
+      {/* ✦ 1 Line: Floating HUD showing real-time spending and tokens */}
       <VibezCheck messages={messages} />
     </div>
   );
 }
 ```
 
----
-
-## 💳 Commercial SaaS Use Cases
-
-### 1. Credit Wallet Top-Ups & Checkout (`BillingHelper`)
-
-```typescript
-import { BillingHelper } from 'vibezcheck';
+### 4. Environment Variables (`.env.local`)
 
-const billing = new BillingHelper({ apiKey: process.env.STRIPE_SECRET_KEY });
-
-// Customer purchases $20 in AI usage credits
-export async function POST(req: Request) {
-  const { customerId } = await req.json();
-
-  const checkoutUrl = await billing.createTopUpSession({
-    customerId,
-    amountCents: 2000, // $20.00
-    returnUrl: 'https://myapp.com/dashboard',
-  });
-
-  return Response.json({ url: checkoutUrl });
-}
+```env
+OPENAI_API_KEY=sk-...
 ```
 
-### 2. Customer API Keys (`ApiKeyAuth`)
-
-Issue customer API keys (`vz_live_...`) backed by Stripe customer metadata—zero database required:
-
-```typescript
-import { ApiKeyAuth } from 'vibezcheck';
-import Stripe from 'stripe';
+---
 
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
-const auth = new ApiKeyAuth(stripe);
+## The UI Components (Zero Props Needed)
 
-// 1. Generate key for customer
-const { apiKey } = await auth.createKey({
-  customerId: 'cus_123',
-  name: 'Production Worker Key',
-});
-// => "vz_live_9f83b2..."
+Import from `vibezcheck/ui` or `vibezcheck/react`:
 
-// 2. Authenticate API requests in middleware
-export async function middleware(req: Request) {
-  const token = req.headers.get('Authorization')?.replace('Bearer ', '');
-  const verification = await auth.verifyKey(token);
+### 1. `<VibezCheck messages={messages} />`
 
-  if (!verification.valid) {
-    return new Response('Unauthorized', { status: 401 });
-  }
+A floating financial HUD and expandable card:
+* **⇅ Unit Swap**: Click the `⇅` icon to switch between **Dollar Cost** (`$0.0028`) and **Tokens** (`1,420 tok`).
+* **Session vs Turn**: Switch between `[Session]` (total conversation spend) and `[Latest Turn]` (last reply).
+* **Multi-Model Breakdown**: If you use multiple models in one chat, it shows the exact split for each model.
+* **Customer Privacy by Default**: End-users only see their billed cost. Your wholesale costs and profit margins are hidden by default.
 
-  // verification.customerId is verified against Stripe!
-}
+```tsx
+<VibezCheck
+  messages={messages}
+  remainingBalanceUSD={10.00}
+  onTopUp={(amount) => console.log('User wants to top up credits:', amount)}
+/>
 ```
 
-### 3. Multi-Tool Agent Sessions (`AgentSession`)
-
-Set a hard $1.00 session budget across multiple LLM steps and external tools:
+### 2. `<VibezReceipt message={message} />`
 
-```typescript
-import { AgentSession, wrapTool } from 'vibezcheck';
-import { openai } from '@ai-sdk/openai';
-
-const session = new AgentSession({
-  customer: 'cus_agent_user',
-  sessionBudgetUSD: 1.00, // Hard ceiling for entire session
-});
-
-// Wrap external tools with financial tracking
-const webSearchTool = wrapTool({
-  name: 'web_search',
-  costUSD: 0.01,
-  execute: async ({ query }) => fetchSearch(query),
-});
-
-// Run LLM model bound to this session
-const sessionModel = session.model(openai('gpt-4o'));
+A small, elegant badge under each assistant message:
+```tsx
+<VibezReceipt message={message} />
+// Renders: ✦ $0.0001 · 31 tok · gpt-4o-mini
 ```
 
 ---
 
-## 🔄 100% Drop-In Compatibility with `@stripe/ai-sdk`
+## Multi-Model Sessions (Automatic Breakdown)
 
-If you are migrating from `@stripe/ai-sdk` or `@stripe/token-meter`, swap your imports:
+If your app routes between different models (e.g. `gpt-4o-mini` for quick chat and `claude-3-5-sonnet` for coding):
 
-```typescript
-// Replace: import { meteredModel } from '@stripe/ai-sdk/meter';
-import { meteredModel } from 'vibezcheck/stripe/meter';
-
-// Replace: import { stripe } from '@stripe/ai-sdk/provider';
-import { stripe } from 'vibezcheck/stripe/provider';
+VibezCheck automatically detects every model used and lists them in the HUD:
+* `gpt-4o-mini (1 turn)`: 31 tok · $0.0001
+* `claude-3-5-sonnet (1 turn)`: 420 tok · $0.0068
 
-// Replace: import { createTokenMeter } from '@stripe/token-meter';
-import { createTokenMeter } from 'vibezcheck/stripe/token-meter';
-```
+Click any model to see its specific spending.
 
 ---
 
-## 🛡️ Route Auditor CLI
-
-Audit your codebase to detect unmetered AI endpoints before shipping to production:
-
-```bash
-npx vibezcheck audit
-```
-
-### CI/CD Mode
-Fail the build if unmetered AI routes are detected:
-```bash
-npx vibezcheck audit --ci
-```
-
----
+## Need Stripe Billing? (Optional)
 
-## 📂 Examples
+When you want to charge real money, VibezCheck has built-in Stripe helpers:
 
-* **[Next.js App Router + OpenAI](examples/nextjs-app-router-openai)**: Direct implementation of the official [AI SDK Next.js App Router Tutorial](https://ai-sdk.dev/docs/getting-started/nextjs-app-router) with 1-line VibezCheck token metering.
-* **[Next.js 15 AI SaaS Starter](examples/nextjs-saas-starter)**: Complete SaaS template with Stripe Checkout, Top-Up Modal, and `<VibezReceipt />`.
-* **[Local Cost Meter](examples/01-local-cost-meter.ts)**: Offline micro-transaction calculations with BigInt Nano-USD precision.
-* **[Native OpenAI Streaming](examples/03-native-openai-stream.ts)**: Zero-latency stream wrapper for the official `openai` Node SDK.
-* **[Claude 3.7 Reasoning Tokens](examples/04-claude-thinking.ts)**: Tracking hidden thought tokens with Anthropic SDK.
+* **Prepaid Credits**: Let users buy credit balance with Stripe Checkout (`BillingHelper.createTopUpSession`).
+* **Customer API Keys**: Issue `vz_live_...` keys saved in Stripe customer metadata (`ApiKeyAuth`).
+* **Agent Session Ceilings**: Limit a multi-step agent to a hard $1.00 budget with `AgentSession`.
 
 ---
 

package/dist/react/index.d.mts

@@ -236,6 +236,19 @@ interface VibezBillingModalProps {
  */
 declare const VibezBillingModal: React__default.FC<VibezBillingModalProps>;
 
+interface ModelUsageDetail {
+    model: string;
+    displayName: string;
+    tokens: number;
+    promptTokens: number;
+    completionTokens: number;
+    reasoningTokens: number;
+    cachedTokens: number;
+    billedUSD: number;
+    wholesaleUSD: number;
+    profitUSD: number;
+    turns: number;
+}
 interface VibezCheckProps {
     /** Messages array from AI SDK useChat() — automatically aggregates tokens & costs */
     messages?: any[];
@@ -245,22 +258,34 @@ interface VibezCheckProps {
     model?: string;
     /** Developer profit margin multiplier (default: 1.25 for +25% margin) */
     margin?: number;
+    /**
+     * Whether to display developer wholesale API costs.
+     * Default: false (hidden from end-users)
+     */
+    showWholesale?: boolean;
+    /**
+     * Whether to display developer profit margin percentage and net profit.
+     * Default: false (hidden from end-users)
+     */
+    showMargin?: boolean;
     /** Manual total cost override in USD */
     totalCostUSD?: number;
     /** Manual total tokens override */
     totalTokens?: number;
     /** Remaining customer credit balance in USD */
     remainingBalanceUSD?: number;
-    /** Screen position (default: 'bottom-center') */
-    position?: 'bottom-center' | 'bottom-right' | 'bottom-left' | 'top-center';
+    /** Screen position (default: 'bottom-left') */
+    position?: 'bottom-center' | 'bottom-right' | 'bottom-left' | 'top-center' | 'top-right' | 'top-left';
     /** Color theme (default: 'auto') */
     theme?: 'dark' | 'light' | 'auto';
     /** Force dev mode banner on/off (defaults to auto-detect) */
     devMode?: boolean;
     /** Additional CSS class names */
     className?: string;
-    /** Callback triggered when user clicks '+ Top Up Credits' */
-    onTopUp?: () => void;
+    /** Custom header title (default: 'Session Usage') */
+    title?: string;
+    /** Callback triggered when user clicks 'Top Up' button or preset amount pills */
+    onTopUp?: (amount?: number) => void;
     /** Callback fired whenever cost or token counts update */
     onCostUpdate?: (summary: {
         totalCostUSD: number;
@@ -268,6 +293,7 @@ interface VibezCheckProps {
         profitUSD: number;
         totalTokens: number;
         isDevMode: boolean;
+        byModel?: Record<string, ModelUsageDetail>;
     }) => void;
     /** Whether popover is initially open (default: false) */
     defaultOpen?: boolean;
@@ -275,11 +301,17 @@ interface VibezCheckProps {
 /**
  * ✦ <VibezCheck /> (from 'vibezcheck/ui' or 'vibezcheck/react')
  *
- * The 1-Line Financial Meter HUD & Floating Badge.
- * Works 100% out of the box in local dev mode with ZERO database and ZERO Stripe setup.
- * Dynamically adapts to Light and Dark mode, with clean typography and zero odd colors.
+ * An ultra-modern, interactive fintech AI financial HUD inspired by Aztec Web3 design.
+ * Features:
+ * - Precise token accounting with zero double counting (server telemetry is authoritative)
+ * - Multi-model session breakdown (details and distributions across models)
+ * - Huge hero typography with interactive USD ⇄ Token unit toggle (⇅)
+ * - Segmented Session ⇄ Latest Turn pill switcher
+ * - Interactive preset pills ([$5] [$10] [$25] [Max])
+ * - Hidden wholesale pricing and margin by default (controlled via showWholesale & showMargin props)
+ * - Soft creamy ivory card with rounded-3xl corners and vibrant orchid action buttons
  */
-declare function VibezCheck({ messages, events, model, margin, totalCostUSD: manualCost, totalTokens: manualTokens, remainingBalanceUSD, position, theme, devMode, className, onTopUp, onCostUpdate, defaultOpen, }: VibezCheckProps): React__default.JSX.Element;
+declare function VibezCheck({ messages, events, model, margin, showWholesale, showMargin, totalCostUSD: manualCost, totalTokens: manualTokens, remainingBalanceUSD, position, theme, devMode, className, title, onTopUp, onCostUpdate, defaultOpen, }: VibezCheckProps): React__default.JSX.Element;
 declare const VibezPill: typeof VibezCheck;
 
-export { type CustomStorageAdapter, type SessionPersistenceMode, type SessionState, type SessionTurnRecord, type UseVibezChatOptions, VibezBillingModal, type VibezBillingModalProps, type VibezBillingNotice, type VibezChatMessage, VibezCheck, type VibezCheckProps, VibezPill, VibezReceipt, type VibezReceiptProps, VibezSessionBadge, type VibezSessionBadgeProps, VibezSessionContext, type VibezSessionContextValue, VibezSessionProvider, type VibezSessionProviderProps, VibezSessionWidget, type VibezSessionWidgetProps, useVibez, useVibezChat, useVibezSession };
+export { type CustomStorageAdapter, type ModelUsageDetail, type SessionPersistenceMode, type SessionState, type SessionTurnRecord, type UseVibezChatOptions, VibezBillingModal, type VibezBillingModalProps, type VibezBillingNotice, type VibezChatMessage, VibezCheck, type VibezCheckProps, VibezPill, VibezReceipt, type VibezReceiptProps, VibezSessionBadge, type VibezSessionBadgeProps, VibezSessionContext, type VibezSessionContextValue, VibezSessionProvider, type VibezSessionProviderProps, VibezSessionWidget, type VibezSessionWidgetProps, useVibez, useVibezChat, useVibezSession };

package/dist/react/index.d.ts

@@ -236,6 +236,19 @@ interface VibezBillingModalProps {
  */
 declare const VibezBillingModal: React__default.FC<VibezBillingModalProps>;
 
+interface ModelUsageDetail {
+    model: string;
+    displayName: string;
+    tokens: number;
+    promptTokens: number;
+    completionTokens: number;
+    reasoningTokens: number;
+    cachedTokens: number;
+    billedUSD: number;
+    wholesaleUSD: number;
+    profitUSD: number;
+    turns: number;
+}
 interface VibezCheckProps {
     /** Messages array from AI SDK useChat() — automatically aggregates tokens & costs */
     messages?: any[];
@@ -245,22 +258,34 @@ interface VibezCheckProps {
     model?: string;
     /** Developer profit margin multiplier (default: 1.25 for +25% margin) */
     margin?: number;
+    /**
+     * Whether to display developer wholesale API costs.
+     * Default: false (hidden from end-users)
+     */
+    showWholesale?: boolean;
+    /**
+     * Whether to display developer profit margin percentage and net profit.
+     * Default: false (hidden from end-users)
+     */
+    showMargin?: boolean;
     /** Manual total cost override in USD */
     totalCostUSD?: number;
     /** Manual total tokens override */
     totalTokens?: number;
     /** Remaining customer credit balance in USD */
     remainingBalanceUSD?: number;
-    /** Screen position (default: 'bottom-center') */
-    position?: 'bottom-center' | 'bottom-right' | 'bottom-left' | 'top-center';
+    /** Screen position (default: 'bottom-left') */
+    position?: 'bottom-center' | 'bottom-right' | 'bottom-left' | 'top-center' | 'top-right' | 'top-left';
     /** Color theme (default: 'auto') */
     theme?: 'dark' | 'light' | 'auto';
     /** Force dev mode banner on/off (defaults to auto-detect) */
     devMode?: boolean;
     /** Additional CSS class names */
     className?: string;
-    /** Callback triggered when user clicks '+ Top Up Credits' */
-    onTopUp?: () => void;
+    /** Custom header title (default: 'Session Usage') */
+    title?: string;
+    /** Callback triggered when user clicks 'Top Up' button or preset amount pills */
+    onTopUp?: (amount?: number) => void;
     /** Callback fired whenever cost or token counts update */
     onCostUpdate?: (summary: {
         totalCostUSD: number;
@@ -268,6 +293,7 @@ interface VibezCheckProps {
         profitUSD: number;
         totalTokens: number;
         isDevMode: boolean;
+        byModel?: Record<string, ModelUsageDetail>;
     }) => void;
     /** Whether popover is initially open (default: false) */
     defaultOpen?: boolean;
@@ -275,11 +301,17 @@ interface VibezCheckProps {
 /**
  * ✦ <VibezCheck /> (from 'vibezcheck/ui' or 'vibezcheck/react')
  *
- * The 1-Line Financial Meter HUD & Floating Badge.
- * Works 100% out of the box in local dev mode with ZERO database and ZERO Stripe setup.
- * Dynamically adapts to Light and Dark mode, with clean typography and zero odd colors.
+ * An ultra-modern, interactive fintech AI financial HUD inspired by Aztec Web3 design.
+ * Features:
+ * - Precise token accounting with zero double counting (server telemetry is authoritative)
+ * - Multi-model session breakdown (details and distributions across models)
+ * - Huge hero typography with interactive USD ⇄ Token unit toggle (⇅)
+ * - Segmented Session ⇄ Latest Turn pill switcher
+ * - Interactive preset pills ([$5] [$10] [$25] [Max])
+ * - Hidden wholesale pricing and margin by default (controlled via showWholesale & showMargin props)
+ * - Soft creamy ivory card with rounded-3xl corners and vibrant orchid action buttons
  */
-declare function VibezCheck({ messages, events, model, margin, totalCostUSD: manualCost, totalTokens: manualTokens, remainingBalanceUSD, position, theme, devMode, className, onTopUp, onCostUpdate, defaultOpen, }: VibezCheckProps): React__default.JSX.Element;
+declare function VibezCheck({ messages, events, model, margin, showWholesale, showMargin, totalCostUSD: manualCost, totalTokens: manualTokens, remainingBalanceUSD, position, theme, devMode, className, title, onTopUp, onCostUpdate, defaultOpen, }: VibezCheckProps): React__default.JSX.Element;
 declare const VibezPill: typeof VibezCheck;
 
-export { type CustomStorageAdapter, type SessionPersistenceMode, type SessionState, type SessionTurnRecord, type UseVibezChatOptions, VibezBillingModal, type VibezBillingModalProps, type VibezBillingNotice, type VibezChatMessage, VibezCheck, type VibezCheckProps, VibezPill, VibezReceipt, type VibezReceiptProps, VibezSessionBadge, type VibezSessionBadgeProps, VibezSessionContext, type VibezSessionContextValue, VibezSessionProvider, type VibezSessionProviderProps, VibezSessionWidget, type VibezSessionWidgetProps, useVibez, useVibezChat, useVibezSession };
+export { type CustomStorageAdapter, type ModelUsageDetail, type SessionPersistenceMode, type SessionState, type SessionTurnRecord, type UseVibezChatOptions, VibezBillingModal, type VibezBillingModalProps, type VibezBillingNotice, type VibezChatMessage, VibezCheck, type VibezCheckProps, VibezPill, VibezReceipt, type VibezReceiptProps, VibezSessionBadge, type VibezSessionBadgeProps, VibezSessionContext, type VibezSessionContextValue, VibezSessionProvider, type VibezSessionProviderProps, VibezSessionWidget, type VibezSessionWidgetProps, useVibez, useVibezChat, useVibezSession };