vibezcheck 0.2.0 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # ⚡ vibezcheck
 
-> **The 1-line Stripe Billing & Token Metering engine for LLMs.**  
-> Track tokens, compute real-time dollar costs, and bill customers with 0ms added latency.
+> **The Declarative 1-Line Stripe Billing & Token Metering Engine for LLMs.**  
+> Track tokens, compute real-time USD costs, and bill customers with 0ms added latency across any LLM provider.
 
 [![npm version](https://img.shields.io/npm/v/vibezcheck.svg)](https://npmjs.org/package/vibezcheck)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -11,11 +11,12 @@
 
 ## 🚀 Why vibezcheck?
 
-* **⚡ 0ms Added Latency**: Streams pass straight through to the browser with zero buffering.
-* **🧠 Reasoning & Thinking Token Aware**: Accurately tracks hidden reasoning tokens in GPT-5, o1/o3, Claude 3.7 Thinking, and Gemini 3.7 Thoughts.
-* **💰 Built-in Cost Engine**: Calculates exact USD inference costs out of the box with prompt caching discounts.
-* **🆓 Zero-Config Local Mode**: Works 100% free in development with no Stripe account needed.
-* **💳 1-Line Stripe Billing**: Turn an AI prototype into a live, revenue-generating SaaS in 1 line of code.
+* **⚡ 0ms Added Latency**: Streams pass straight through to the browser with zero buffering or middleware delay.
+* **🧠 Thinking & Reasoning Token Aware**: Accurately extracts hidden reasoning tokens in GPT-5, o1/o3-mini, Claude 3.7 Thinking, and Gemini 2.0 Flash Thinking.
+* **💰 Built-in Cost Calculation**: Real-time USD inference pricing out of the box with prompt caching discounts.
+* **🆓 Zero-Config Local Mode**: Works 100% free in development with no database or Stripe account required.
+* **💳 1-Line Stripe Billing**: Turn an AI prototype into a revenue-generating SaaS with autonomous customer provisioning and meter events.
+* **⚛️ React & React Native Ready**: Live floating widgets, badges, and checkout paywall modals (`<VibezBillingModal />`).
 
 ---
 
@@ -29,241 +30,184 @@ pnpm add vibezcheck stripe
 
 ---
 
-## 🎯 The 2 Core Features
+## ⚡ 1. Declarative Vercel AI SDK Integration
 
----
-
-### Feature 1: Local Token & Cost Tracking (Free / No Stripe Required)
+`vibezcheck` wraps any model string or provider instance into a fully compliant Vercel AI SDK model:
 
-Use this in development or when you want real-time token and USD cost analytics without billing users:
+### A. Single-Turn Generation (`generateText` & Server Actions)
+```typescript
+import { generateText } from "ai";
+import { vibezcheck } from "vibezcheck";
+
+const { text, usage } = await generateText({
+  model: vibezcheck("openai/gpt-4o-mini", {
+    customer: "alex@example.com", // Auto-creates or matches Stripe customer
+  }),
+  prompt: "What is love?",
+});
+```
 
-#### 💻 Code:
+### B. Streaming AI Route (`streamText`)
 ```typescript
 // app/api/chat/route.ts
-import { createMeter } from 'vibezcheck/meter';
-import OpenAI from 'openai';
-
-const openai = new OpenAI();
-
-// 1. Create a meter (no Stripe key required!)
-const meter = createMeter({
-  onUsage: (event) => {
-    console.log(`[vibezcheck] 📊 Model: ${event.model}`);
-    console.log(`Tokens: ${event.usage.totalTokens} (Input: ${event.usage.inputTokens}, Output: ${event.usage.outputTokens}, Reasoning: ${event.usage.reasoningTokens ?? 0})`);
-    console.log(`Inference Cost: $${event.cost.totalUSD.toFixed(6)} USD\n`);
-  },
-});
+import { streamText } from "ai";
+import { vibezcheck } from "vibezcheck";
 
 export async function POST(req: Request) {
   const { messages } = await req.json();
 
-  const stream = await openai.chat.completions.create({
-    model: 'gpt-4o',
+  return streamText({
+    model: vibezcheck("gpt-4o-mini", { customer: "alex@example.com" }),
     messages,
-    stream: true,
-    stream_options: { include_usage: true },
-  });
-
-  // 2. Wrap stream - passes chunks directly to user with 0ms added delay
-  return new Response(meter.wrapStream(stream));
+  }).toTextStreamResponse();
 }
 ```
 
-#### 🌐 What the Frontend receives:
-```http
-HTTP/1.1 200 OK
-Content-Type: text/plain; charset=utf-8
-Transfer-Encoding: chunked
+### C. Direct `createOpenAI` Connection
+You can pass custom OpenAI / Gateway instances directly into `vibezcheck()`:
+```typescript
+import { createOpenAI } from "@ai-sdk/openai";
+import { streamText } from "ai";
+import { vibezcheck } from "vibezcheck";
 
-Quantum computing uses qubits to perform complex calculations exponentially faster...
-```
+const openai = createOpenAI({
+  apiKey: process.env.AI_GATEWAY_API_KEY,
+  baseURL: "https://ai-gateway.vercel.sh/v1", // Vercel AI Gateway or Cloudflare
+});
 
-#### 🖥️ What your Terminal logs:
-```
-[vibezcheck] 📊 Model: openai/gpt-4o
-Tokens: 1,420 (Input: 800, Output: 620, Reasoning: 0)
-Inference Cost: $0.008200 USD
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  return streamText({
+    model: vibezcheck(openai("gpt-4o-mini"), { customer: "alex@example.com" }),
+    messages,
+  }).toTextStreamResponse();
+}
 ```
 
 ---
 
-### Feature 2: 1-Line Stripe Billing with Vercel AI SDK (`withBilling`)
+## ⚛️ 2. Declarative React UI & Hooks (`vibezcheck/react`)
 
-Use this when you are ready to charge users and protect your margins from heavy reasoning models (GPT-5, Claude 3.7 Thinking):
+### A. 1-Line Streaming Chat Hook (`useVibezChat`)
+Automatically connects to your API route and syncs tokens, reasoning thoughts, and costs with the session widget:
 
-#### 💻 Code:
-```typescript
-// app/api/chat/route.ts
-import { withBilling } from 'vibezcheck';
-import { openai } from '@ai-sdk/openai';
-import { streamText } from 'ai';
+```tsx
+'use client';
+import { useVibezChat, VibezSessionWidget, VibezBillingModal } from 'vibezcheck/react';
 
-export async function POST(req: Request) {
-  const { messages, userEmail } = await req.json();
-
-  // 1-line wrapper: extracts reasoning tokens & logs meter events to Stripe!
-  const result = streamText({
-    model: withBilling(openai('gpt-5.6-sol'), {
-      customer: userEmail, // e.g. "alex@example.com"
-      stripeApiKey: process.env.STRIPE_SECRET_KEY,
-    }),
-    messages,
+export default function ChatPage() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useVibezChat({
+    model: 'gpt-4o-mini',
+    customer: 'alex@example.com',
   });
 
-  return result.toDataStreamResponse();
+  return (
+    <main className="p-6 max-w-3xl mx-auto">
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} placeholder="Ask..." />
+        <button type="submit" disabled={isLoading}>Send</button>
+      </form>
+
+      {/* Live Token & Dollar Tracker Widget */}
+      <VibezSessionWidget theme="light" position="bottom-right" />
+    </main>
+  );
 }
 ```
 
-#### 🌐 What the Frontend receives:
-Compatible with Vercel's `useChat()` React hook:
-```http
-HTTP/1.1 200 OK
-Content-Type: text/event-stream; charset=utf-8
-x-vercel-ai-data-stream: v1
-
-0:"Here is the "
-0:"solution step by step..."
-d:{"finishReason":"stop","usage":{"promptTokens":1200,"completionTokens":450,"reasoningTokens":350}}
-```
+### B. Autonomous Paywall & Top-Up Modal (`<VibezBillingModal />`)
+Pops up an in-app Stripe Checkout modal whenever a customer reaches their credit limit:
 
-#### 💳 What Stripe receives in the background:
-1. **Customer Created/Resolved**: Customer `alex@example.com` is automatically created (`cus_Q871xyz`).
-2. **Meter Event Dispatched to Stripe Billing**:
-```json
-{
-  "event_name": "token-billing-tokens",
-  "timestamp": "2026-08-23T10:12:00.000Z",
-  "payload": {
-    "stripe_customer_id": "cus_Q871xyz",
-    "value": "800",
-    "model": "openai/gpt-5.6-sol",
-    "token_type": "output",
-    "is_reasoning": "true"
-  }
-}
+```tsx
+<VibezBillingModal
+  isOpen={limitReached}
+  onClose={() => setLimitReached(false)}
+  notice={{
+    status: 'limit_reached',
+    tokensUsed: 150000,
+    costUSD: 5.00,
+    message: 'Free credit limit reached. Top up to keep streaming!',
+  }}
+  theme="light"
+  testMode={true} // Supports Stripe Sandbox testing
+/>
 ```
-3. **Invoice Updated**: Stripe increments Alex's monthly usage bill or deducts \$0.016 from their prepaid credit balance.
 
 ---
 
-### Also works with Claude 3.7 Sonnet Extended Thinking
+## 💳 3. Stripe Sandbox & Customer Provisioning
 
+### A. Auto Customer Provisioning in 1 Line:
 ```typescript
-import { createMeter } from 'vibezcheck/meter';
-import Anthropic from '@anthropic-ai/sdk';
-
-const anthropic = new Anthropic();
-const meter = createMeter({ apiKey: process.env.STRIPE_SECRET_KEY });
-
-export async function handleThinkingPrompt(prompt: string, customerId: string) {
-  const stream = await anthropic.messages.create({
-    model: 'claude-3-7-sonnet-20250219',
-    max_tokens: 4000,
-    thinking: { type: 'enabled', budget_tokens: 2000 },
-    messages: [{ role: 'user', content: prompt }],
-    stream: true,
-  });
+import { vibezcheck } from "vibezcheck";
 
-  // Automatically captures Claude 3.7 thinking tokens and sends to Stripe:
-  return meter.wrapStream(stream, { customerId });
-}
-```
+const vz = vibezcheck();
 
-#### 💳 Stripe Meter Event output for Thinking Tokens:
-```json
-{
-  "event_name": "token-billing-tokens",
-  "payload": {
-    "stripe_customer_id": "cus_Q871xyz",
-    "value": "1840",
-    "model": "anthropic/claude-3-7-sonnet",
-    "token_type": "output_thinking"
-  }
-}
+// Automatically finds existing customer by email or creates a new one in Stripe
+const customer = await vz.customers.getOrCreate({
+  email: "alex@company.com",
+  name: "Alex Rivera",
+});
+console.log(customer.id); // "cus_R3K7h9Qv..."
 ```
 
----
-
-## ⚛️ 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>
-  );
-}
+### B. 1-Line Stripe Checkout Session:
+```typescript
+const checkoutUrl = await vz.billing.createCheckoutSession({
+  customerId: customer.id,
+  priceId: "price_metered_tokens", // Your Stripe metered price ID
+  returnUrl: "https://myapp.com/dashboard",
+});
 ```
 
-### 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();
+## 📊 Live Telemetry Payload Structure
 
-  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 });
-    },
-  });
+Every inference event emitted by `onUsage` captures complete token and cost economics:
 
-  return (
-    <div>
-      <header className="flex justify-between items-center">
-        <h2>AI Assistant</h2>
-        <VibezSessionBadge showTokens showCost />
-      </header>
-
-      <MessagesList messages={messages} />
-    </div>
-  );
+```json
+{
+  "timestamp": "2026-08-31T11:00:00.000Z",
+  "model": "openai/gpt-4o-mini",
+  "provider": "openai",
+  "customerId": "cus_R3K7h9Qv",
+  "usage": {
+    "inputTokens": 850,
+    "outputTokens": 420,
+    "totalTokens": 1270,
+    "reasoningTokens": 280,
+    "cachedTokens": 500
+  },
+  "cost": {
+    "inputUSD": 0.000127,
+    "outputUSD": 0.000252,
+    "totalUSD": 0.000379
+  }
 }
 ```
 
 ---
 
-## 💰 Built-in Model Pricing Registry
-
-`vibezcheck` ships with default rates for all active frontier models:
-
-```typescript
-import { calculateCost } from 'vibezcheck/pricing';
-
-const cost = calculateCost({
-  model: 'claude-3-7-sonnet',
-  inputTokens: 2000,
-  outputTokens: 800,
-  reasoningTokens: 1200, // thinking tokens
-});
-
-console.log(cost);
-```
+## 📜 Supported Models (Auto-Priced)
 
-#### 🖥️ Response:
-```json
-{
-  "inputCostUSD": 0.00118,
-  "outputCostUSD": 0.002344,
-  "reasoningCostUSD": 0.003516,
-  "totalCostUSD": 0.007040,
-  "currency": "USD"
-}
-```
+| Model Family | Examples | Reasoning Aware | Caching Discounts |
+| :--- | :--- | :---: | :---: |
+| **OpenAI** | `gpt-4o`, `gpt-4o-mini`, `o1`, `o3-mini`, `gpt-5.6-sol` | ✅ | ✅ |
+| **Anthropic** | `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-5-haiku` | ✅ | ✅ |
+| **Google** | `gemini-2.0-flash`, `gemini-1.5-pro` | ✅ | ✅ |
+| **DeepSeek** | `deepseek-chat`, `deepseek-reasoner` | ✅ | ✅ |
+| **Custom** | Register any custom model with `registerModelPricing()` | ✅ | ✅ |
 
 ---
 
 ## 📄 License
 
-MIT © [vibezcheck.xyz](https://vibezcheck.xyz)
+MIT © [seeyouin2x5x](https://github.com/seeyouin2x5x)

package/bin/vibezcheck.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+// Forward execution to compiled CLI entrypoint
+require('../dist/cli/index.js');

package/dist/ai-sdk/index.d.mts

@@ -1,8 +1,8 @@
-import { C as CustomerParam, U as UsageEvent } from '../types-CSrSmsd1.mjs';
-import { V as VibezMeter } from '../client-MJ3tl7bz.mjs';
+import { b as CircuitBreakerOptions, C as CustomerParam, U as UsageEvent } from '../types-DCuzLVyc.mjs';
+import { V as VibezMeter } from '../client-C67DW_tR.mjs';
 import 'stripe';
 
-interface WithBillingOptions {
+interface WithBillingOptions extends CircuitBreakerOptions {
     /** Customer email, user ID, or Stripe customer ID */
     customer?: CustomerParam;
     /** Direct Stripe customer ID */
@@ -19,16 +19,52 @@ interface WithBillingOptions {
     metadata?: Record<string, string | number | boolean>;
 }
 /**
- * Wraps any Vercel AI SDK LanguageModel (v2 or v3) with automated Stripe billing and token metering.
+ * Wraps any Vercel AI SDK LanguageModel (v2 or v3) with automated Stripe billing, token metering, and agent circuit breakers.
  *
  * @param model - The Vercel AI SDK language model instance (e.g. openai('gpt-5.6-sol'), anthropic('claude-3-7-sonnet'))
  * @param options - Billing & customer configuration
- * @returns Decorated LanguageModel that automatically meters tokens and sends Stripe meter events
+ * @returns Decorated LanguageModel that automatically meters tokens, sends Stripe meter events, and enforces budget guardrails
  */
 declare function withBilling<T extends object>(model: T, options?: WithBillingOptions): T;
 /**
- * Alias for withBilling
+ * Convenient alias for withBilling
  */
 declare const meteredModel: typeof withBilling;
 
-export { type WithBillingOptions, meteredModel, withBilling };
+interface VibezCheckModelOptions extends WithBillingOptions {
+    /** OpenAI / AI Gateway API Key override */
+    apiKey?: string;
+    /** AI Gateway / OpenAI Base URL override */
+    baseURL?: string;
+}
+/**
+ * Creates or resolves an AI SDK compatible LanguageModel with built-in VibezCheck billing & metering.
+ *
+ * @example
+ * ```typescript
+ * import { generateText, streamText } from 'ai';
+ * import { vibezcheck } from 'vibezcheck';
+ *
+ * // 1. Declarative string model identifier:
+ * const { text } = await generateText({
+ *   model: vibezcheck('openai/gpt-4o-mini', { customer: 'alex@example.com' }),
+ *   prompt: 'What is love?',
+ * });
+ *
+ * // 2. Works with all Vercel AI SDK primitives (streamText, generateObject, streamObject):
+ * const result = streamText({
+ *   model: vibezcheck('gpt-4o', { customer: 'alex@example.com' }),
+ *   messages,
+ * });
+ *
+ * // 3. Wrap existing provider instances:
+ * import { openai } from '@ai-sdk/openai';
+ * const result = streamText({
+ *   model: vibezcheck(openai('gpt-4o-mini'), { customer: 'alex@example.com' }),
+ *   messages,
+ * });
+ * ```
+ */
+declare function createVibezModel(modelOrId: any, options?: VibezCheckModelOptions): any;
+
+export { type VibezCheckModelOptions, type WithBillingOptions, createVibezModel, meteredModel, withBilling };

package/dist/ai-sdk/index.d.ts

@@ -1,8 +1,8 @@
-import { C as CustomerParam, U as UsageEvent } from '../types-CSrSmsd1.js';
-import { V as VibezMeter } from '../client-txrE0D_D.js';
+import { b as CircuitBreakerOptions, C as CustomerParam, U as UsageEvent } from '../types-DCuzLVyc.js';
+import { V as VibezMeter } from '../client-S3qmTXTR.js';
 import 'stripe';
 
-interface WithBillingOptions {
+interface WithBillingOptions extends CircuitBreakerOptions {
     /** Customer email, user ID, or Stripe customer ID */
     customer?: CustomerParam;
     /** Direct Stripe customer ID */
@@ -19,16 +19,52 @@ interface WithBillingOptions {
     metadata?: Record<string, string | number | boolean>;
 }
 /**
- * Wraps any Vercel AI SDK LanguageModel (v2 or v3) with automated Stripe billing and token metering.
+ * Wraps any Vercel AI SDK LanguageModel (v2 or v3) with automated Stripe billing, token metering, and agent circuit breakers.
  *
  * @param model - The Vercel AI SDK language model instance (e.g. openai('gpt-5.6-sol'), anthropic('claude-3-7-sonnet'))
  * @param options - Billing & customer configuration
- * @returns Decorated LanguageModel that automatically meters tokens and sends Stripe meter events
+ * @returns Decorated LanguageModel that automatically meters tokens, sends Stripe meter events, and enforces budget guardrails
  */
 declare function withBilling<T extends object>(model: T, options?: WithBillingOptions): T;
 /**
- * Alias for withBilling
+ * Convenient alias for withBilling
  */
 declare const meteredModel: typeof withBilling;
 
-export { type WithBillingOptions, meteredModel, withBilling };
+interface VibezCheckModelOptions extends WithBillingOptions {
+    /** OpenAI / AI Gateway API Key override */
+    apiKey?: string;
+    /** AI Gateway / OpenAI Base URL override */
+    baseURL?: string;
+}
+/**
+ * Creates or resolves an AI SDK compatible LanguageModel with built-in VibezCheck billing & metering.
+ *
+ * @example
+ * ```typescript
+ * import { generateText, streamText } from 'ai';
+ * import { vibezcheck } from 'vibezcheck';
+ *
+ * // 1. Declarative string model identifier:
+ * const { text } = await generateText({
+ *   model: vibezcheck('openai/gpt-4o-mini', { customer: 'alex@example.com' }),
+ *   prompt: 'What is love?',
+ * });
+ *
+ * // 2. Works with all Vercel AI SDK primitives (streamText, generateObject, streamObject):
+ * const result = streamText({
+ *   model: vibezcheck('gpt-4o', { customer: 'alex@example.com' }),
+ *   messages,
+ * });
+ *
+ * // 3. Wrap existing provider instances:
+ * import { openai } from '@ai-sdk/openai';
+ * const result = streamText({
+ *   model: vibezcheck(openai('gpt-4o-mini'), { customer: 'alex@example.com' }),
+ *   messages,
+ * });
+ * ```
+ */
+declare function createVibezModel(modelOrId: any, options?: VibezCheckModelOptions): any;
+
+export { type VibezCheckModelOptions, type WithBillingOptions, createVibezModel, meteredModel, withBilling };