vibezcheck 0.1.0 → 0.2.0

package/README.md

@@ -184,6 +184,56 @@ export async function handleThinkingPrompt(prompt: string, customerId: string) {
 
 ---
 
+## ⚛️ React & React Native Session Tracking (`vibezcheck/react`)
+
+Track live session tokens and dollar costs directly on the client side with **zero database required**:
+
+### 1. Wrap your chat app with `<VibezSessionProvider>`:
+```tsx
+import { VibezSessionProvider, VibezSessionWidget } from 'vibezcheck/react';
+
+export default function App() {
+  return (
+    <VibezSessionProvider persist="sessionStorage">
+      <ChatInterface />
+
+      {/* Drop-in floating pill widget showing live session tokens & cost */}
+      <VibezSessionWidget position="bottom-right" showReasoning theme="dark" />
+    </VibezSessionProvider>
+  );
+}
+```
+
+### 2. Auto-hook into Vercel AI SDK (`useChat`):
+```tsx
+import { useChat } from 'ai/react';
+import { useVibezSession, VibezSessionBadge } from 'vibezcheck/react';
+
+export function ChatInterface() {
+  const { recordTurn, sessionUsage, sessionCost } = useVibezSession();
+
+  const { messages, input, handleSubmit } = useChat({
+    onFinish: (message, { usage }) => {
+      // 1 line: accumulates tokens & calculates real-time USD costs in React state
+      recordTurn({ model: 'gpt-5.6-sol', usage });
+    },
+  });
+
+  return (
+    <div>
+      <header className="flex justify-between items-center">
+        <h2>AI Assistant</h2>
+        <VibezSessionBadge showTokens showCost />
+      </header>
+
+      <MessagesList messages={messages} />
+    </div>
+  );
+}
+```
+
+---
+
 ## 💰 Built-in Model Pricing Registry
 
 `vibezcheck` ships with default rates for all active frontier models:

package/dist/react/index.d.mts

@@ -0,0 +1,154 @@
+import { T as TokenUsage, I as InferenceCost } from '../types-CSrSmsd1.mjs';
+import React$1 from 'react';
+import 'stripe';
+
+/**
+ * Record of a single message/completion turn in an active chat session
+ */
+interface SessionTurnRecord {
+    id: string;
+    timestamp: string;
+    model: string;
+    usage: TokenUsage;
+    cost: InferenceCost;
+    metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * Aggregated live session state
+ */
+interface SessionState {
+    /** Unique session ID (e.g. chat conversation ID) */
+    sessionId: string;
+    /** Total number of interaction turns in this session */
+    turnCount: number;
+    /** Total tokens accumulated across all turns in this session */
+    sessionUsage: TokenUsage;
+    /** Total cost accumulated in this session */
+    sessionCost: InferenceCost;
+    /** Model-by-model breakdown of tokens and costs in this session */
+    byModel: Record<string, {
+        turns: number;
+        usage: TokenUsage;
+        cost: InferenceCost;
+    }>;
+    /** Complete turn history for this session */
+    history: SessionTurnRecord[];
+}
+/**
+ * Storage adapter options for client-side persistence
+ */
+type SessionPersistenceMode = 'memory' | 'sessionStorage' | 'localStorage' | 'custom';
+interface CustomStorageAdapter {
+    getItem: (key: string) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+    removeItem: (key: string) => void | Promise<void>;
+}
+/**
+ * Configuration options for VibezSessionProvider
+ */
+interface VibezSessionProviderProps {
+    children: React.ReactNode;
+    /** Session ID (defaults to auto-generated UUID/timestamp) */
+    sessionId?: string;
+    /** Client-side persistence mode (default: 'memory') */
+    persist?: SessionPersistenceMode;
+    /** Custom storage adapter (e.g. AsyncStorage for React Native) */
+    storage?: CustomStorageAdapter;
+    /** Storage key prefix (default: 'vibez_session_') */
+    storageKey?: string;
+    /** Markup multiplier for client retail cost displays (e.g. 1.3 for 30% margin) */
+    markupMultiplier?: number;
+    /** Callback fired whenever a turn is recorded */
+    onTurnRecorded?: (turn: SessionTurnRecord, sessionState: SessionState) => void;
+}
+/**
+ * Interface returned by useVibezSession hook
+ */
+interface VibezSessionContextValue extends SessionState {
+    /** Record a completed turn from useChat, streamText, or native API */
+    recordTurn: (params: {
+        model: string;
+        usage: {
+            promptTokens?: number;
+            completionTokens?: number;
+            inputTokens?: number;
+            outputTokens?: number;
+            totalTokens?: number;
+            reasoningTokens?: number;
+            cachedTokens?: number;
+            cacheWriteTokens?: number;
+            completionTokensDetails?: {
+                reasoning_tokens?: number;
+            };
+            promptTokensDetails?: {
+                cached_tokens?: number;
+            };
+        };
+        metadata?: Record<string, string | number | boolean>;
+    }) => SessionTurnRecord;
+    /** Reset session state (e.g. when user clicks "New Chat") */
+    resetSession: (newSessionId?: string) => void;
+}
+/**
+ * Props for the drop-in <VibezSessionWidget />
+ */
+interface VibezSessionWidgetProps {
+    /** Screen position for floating placement */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'inline';
+    /** Show USD dollar cost (default: true) */
+    showCost?: boolean;
+    /** Show token counts (default: true) */
+    showTokens?: boolean;
+    /** Show reasoning/thinking tokens breakdown (default: true) */
+    showReasoning?: boolean;
+    /** Color theme (default: 'auto') */
+    theme?: 'dark' | 'light' | 'auto';
+    /** Custom container CSS class (for Web) */
+    className?: string;
+    /** Custom inline styles */
+    style?: React.CSSProperties;
+}
+/**
+ * Props for the compact <VibezSessionBadge />
+ */
+interface VibezSessionBadgeProps {
+    /** Show USD dollar cost (default: true) */
+    showCost?: boolean;
+    /** Show token count (default: true) */
+    showTokens?: boolean;
+    /** Custom CSS class */
+    className?: string;
+    /** Custom inline styles */
+    style?: React.CSSProperties;
+}
+
+declare const VibezSessionContext: React$1.Context<VibezSessionContextValue | null>;
+declare const VibezSessionProvider: React$1.FC<VibezSessionProviderProps>;
+
+/**
+ * Hook to access live session usage, cost totals, and turn recorder
+ *
+ * @example
+ * ```tsx
+ * const { sessionUsage, sessionCost, recordTurn, resetSession } = useVibezSession();
+ *
+ * // Inside useChat onFinish:
+ * onFinish: (message, { usage }) => {
+ *   recordTurn({ model: 'gpt-5.6-sol', usage });
+ * }
+ * ```
+ */
+declare function useVibezSession(): VibezSessionContextValue;
+/**
+ * Convenient alias
+ */
+declare const useVibez: typeof useVibezSession;
+
+declare const VibezSessionWidget: React$1.FC<VibezSessionWidgetProps>;
+
+/**
+ * Compact inline badge for chat input bars, headers, or navbars
+ */
+declare const VibezSessionBadge: React$1.FC<VibezSessionBadgeProps>;
+
+export { type CustomStorageAdapter, type SessionPersistenceMode, type SessionState, type SessionTurnRecord, VibezSessionBadge, type VibezSessionBadgeProps, VibezSessionContext, type VibezSessionContextValue, VibezSessionProvider, type VibezSessionProviderProps, VibezSessionWidget, type VibezSessionWidgetProps, useVibez, useVibezSession };

package/dist/react/index.d.ts

@@ -0,0 +1,154 @@
+import { T as TokenUsage, I as InferenceCost } from '../types-CSrSmsd1.js';
+import React$1 from 'react';
+import 'stripe';
+
+/**
+ * Record of a single message/completion turn in an active chat session
+ */
+interface SessionTurnRecord {
+    id: string;
+    timestamp: string;
+    model: string;
+    usage: TokenUsage;
+    cost: InferenceCost;
+    metadata?: Record<string, string | number | boolean>;
+}
+/**
+ * Aggregated live session state
+ */
+interface SessionState {
+    /** Unique session ID (e.g. chat conversation ID) */
+    sessionId: string;
+    /** Total number of interaction turns in this session */
+    turnCount: number;
+    /** Total tokens accumulated across all turns in this session */
+    sessionUsage: TokenUsage;
+    /** Total cost accumulated in this session */
+    sessionCost: InferenceCost;
+    /** Model-by-model breakdown of tokens and costs in this session */
+    byModel: Record<string, {
+        turns: number;
+        usage: TokenUsage;
+        cost: InferenceCost;
+    }>;
+    /** Complete turn history for this session */
+    history: SessionTurnRecord[];
+}
+/**
+ * Storage adapter options for client-side persistence
+ */
+type SessionPersistenceMode = 'memory' | 'sessionStorage' | 'localStorage' | 'custom';
+interface CustomStorageAdapter {
+    getItem: (key: string) => string | null | Promise<string | null>;
+    setItem: (key: string, value: string) => void | Promise<void>;
+    removeItem: (key: string) => void | Promise<void>;
+}
+/**
+ * Configuration options for VibezSessionProvider
+ */
+interface VibezSessionProviderProps {
+    children: React.ReactNode;
+    /** Session ID (defaults to auto-generated UUID/timestamp) */
+    sessionId?: string;
+    /** Client-side persistence mode (default: 'memory') */
+    persist?: SessionPersistenceMode;
+    /** Custom storage adapter (e.g. AsyncStorage for React Native) */
+    storage?: CustomStorageAdapter;
+    /** Storage key prefix (default: 'vibez_session_') */
+    storageKey?: string;
+    /** Markup multiplier for client retail cost displays (e.g. 1.3 for 30% margin) */
+    markupMultiplier?: number;
+    /** Callback fired whenever a turn is recorded */
+    onTurnRecorded?: (turn: SessionTurnRecord, sessionState: SessionState) => void;
+}
+/**
+ * Interface returned by useVibezSession hook
+ */
+interface VibezSessionContextValue extends SessionState {
+    /** Record a completed turn from useChat, streamText, or native API */
+    recordTurn: (params: {
+        model: string;
+        usage: {
+            promptTokens?: number;
+            completionTokens?: number;
+            inputTokens?: number;
+            outputTokens?: number;
+            totalTokens?: number;
+            reasoningTokens?: number;
+            cachedTokens?: number;
+            cacheWriteTokens?: number;
+            completionTokensDetails?: {
+                reasoning_tokens?: number;
+            };
+            promptTokensDetails?: {
+                cached_tokens?: number;
+            };
+        };
+        metadata?: Record<string, string | number | boolean>;
+    }) => SessionTurnRecord;
+    /** Reset session state (e.g. when user clicks "New Chat") */
+    resetSession: (newSessionId?: string) => void;
+}
+/**
+ * Props for the drop-in <VibezSessionWidget />
+ */
+interface VibezSessionWidgetProps {
+    /** Screen position for floating placement */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'inline';
+    /** Show USD dollar cost (default: true) */
+    showCost?: boolean;
+    /** Show token counts (default: true) */
+    showTokens?: boolean;
+    /** Show reasoning/thinking tokens breakdown (default: true) */
+    showReasoning?: boolean;
+    /** Color theme (default: 'auto') */
+    theme?: 'dark' | 'light' | 'auto';
+    /** Custom container CSS class (for Web) */
+    className?: string;
+    /** Custom inline styles */
+    style?: React.CSSProperties;
+}
+/**
+ * Props for the compact <VibezSessionBadge />
+ */
+interface VibezSessionBadgeProps {
+    /** Show USD dollar cost (default: true) */
+    showCost?: boolean;
+    /** Show token count (default: true) */
+    showTokens?: boolean;
+    /** Custom CSS class */
+    className?: string;
+    /** Custom inline styles */
+    style?: React.CSSProperties;
+}
+
+declare const VibezSessionContext: React$1.Context<VibezSessionContextValue | null>;
+declare const VibezSessionProvider: React$1.FC<VibezSessionProviderProps>;
+
+/**
+ * Hook to access live session usage, cost totals, and turn recorder
+ *
+ * @example
+ * ```tsx
+ * const { sessionUsage, sessionCost, recordTurn, resetSession } = useVibezSession();
+ *
+ * // Inside useChat onFinish:
+ * onFinish: (message, { usage }) => {
+ *   recordTurn({ model: 'gpt-5.6-sol', usage });
+ * }
+ * ```
+ */
+declare function useVibezSession(): VibezSessionContextValue;
+/**
+ * Convenient alias
+ */
+declare const useVibez: typeof useVibezSession;
+
+declare const VibezSessionWidget: React$1.FC<VibezSessionWidgetProps>;
+
+/**
+ * Compact inline badge for chat input bars, headers, or navbars
+ */
+declare const VibezSessionBadge: React$1.FC<VibezSessionBadgeProps>;
+
+export { type CustomStorageAdapter, type SessionPersistenceMode, type SessionState, type SessionTurnRecord, VibezSessionBadge, type VibezSessionBadgeProps, VibezSessionContext, type VibezSessionContextValue, VibezSessionProvider, type VibezSessionProviderProps, VibezSessionWidget, type VibezSessionWidgetProps, useVibez, useVibezSession };