@revenium/perplexity 1.0.25 → 2.0.2

package/README.md

@@ -1,750 +1,625 @@
-# Revenium Middleware for Perplexity AI (Node.js)
+# Revenium Middleware for Perplexity
 
-[![npm version](https://badge.fury.io/js/%40revenium%2Fperplexity.svg)](https://badge.fury.io/js/%40revenium%2Fperplexity)
-[![Node Versions](https://img.shields.io/node/v/@revenium/perplexity.svg)](https://www.npmjs.com/package/@revenium/perplexity)
-[![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://docs.revenium.io)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+A lightweight, production-ready middleware that adds **Revenium metering and tracking** to Perplexity AI API calls.
 
-Automatically track and meter your Perplexity AI API usage with Revenium. This package provides seamless integration with Perplexity AI API using modern Controller architecture, supporting both V1 (compatible) and V2 (enhanced) response formats.
+[![npm version](https://img.shields.io/npm/v/@revenium/perplexity.svg)](https://www.npmjs.com/package/@revenium/perplexity)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
-## 🎯 **New Architecture: V1 & V2 Controllers**
+## 🚀 Features
 
-- **V1 Controller**: Maintains compatibility with existing middleware logic
-- **V2 Controller**: Enhanced response format following [OpenAI Responses API](https://platform.openai.com/docs/guides/migrate-to-responses) guidelines
-- **Service Layer**: Handles API calls, metering, and data transformation
-- **Rich Examples**: TypeScript examples and JavaScript playground files
+- ✅ **Zero Configuration** - Works out of the box with environment variables
+- ✅ **Automatic Metering** - Tracks all API calls with detailed usage metrics
+- ✅ **Streaming Support** - Full support for streaming responses
+- ✅ **TypeScript First** - Built with TypeScript, includes full type definitions
+- ✅ **Multi-Format** - Supports both ESM and CommonJS
+- ✅ **Custom Metadata** - Add custom tracking metadata to any request
+- ✅ **Production Ready** - Battle-tested and optimized for production use
 
-## 🚀 Getting Started
+## 📋 Table of Contents
 
-You have 3 options to start using Revenium Controllers for Perplexity AI:
+- [Installation](https://github.com/revenium/revenium-middleware-perplexity-node#-installation)
+- [Three Ways to Use This Middleware](https://github.com/revenium/revenium-middleware-perplexity-node#-three-ways-to-use-this-middleware)
+  - [Option 1: New Project with npm Package](https://github.com/revenium/revenium-middleware-perplexity-node#option-1-new-project-with-npm-package-recommended)
+  - [Option 2: Clone and Use Locally](https://github.com/revenium/revenium-middleware-perplexity-node#option-2-clone-and-use-locally)
+  - [Option 3: Add to Existing Project](https://github.com/revenium/revenium-middleware-perplexity-node#option-3-add-to-existing-project)
+- [Quick Start](https://github.com/revenium/revenium-middleware-perplexity-node#-quick-start)
+- [API Reference](https://github.com/revenium/revenium-middleware-perplexity-node#-api-reference)
+- [Examples](https://github.com/revenium/revenium-middleware-perplexity-node#-examples)
+- [Environment Variables](https://github.com/revenium/revenium-middleware-perplexity-node#-environment-variables)
 
-| Option                                    | Description                                                                        | Best For                                                             |
-| ----------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| **Option 1: Create Project from Scratch** | Perfect for new projects. We'll guide you step-by-step using V1 or V2 Controllers. | 👉 [Go to Step-by-Step Guide](#option-1-create-project-from-scratch) |
-| **Option 2: Clone Our Repository**        | Quick testing with pre-built V1/V2 examples and playground scripts.                | 👉 [Go to Clone Guide](#option-2-clone-repository)                   |
-| **Option 3: Add to Existing Project**     | Already have a project? Just install and use Controllers.                          | 👉 [Go to Quick Integration](#option-3-existing-project-integration) |
-
----
-
-## Option 1: Create Project from Scratch
-
-### Step 1: Create Project Directory
+## 📦 Installation
 
 ```bash
-# Create and navigate to your project
-mkdir my-perplexity-ai-project
-cd my-perplexity-ai-project
-
-# Initialize Node.js project
-npm init -y
+npm install @revenium/perplexity
 ```
 
-### Step 2: Install Dependencies
+## 🎯 Three Ways to Use This Middleware
 
-```bash
-npm install @revenium/perplexity
-```
+### Option 1: New Project with npm Package (Recommended)
 
-### Step 3: Setup Environment Variables
+**Best for:** Starting a new project or adding Perplexity with Revenium to an existing project.
 
-Create a `.env` file in your project root:
+#### Step 1: Create a new project
 
 ```bash
-# Create .env file
-echo. > .env  # On Windows (CMD TERMINAL)
-touch .env  # On Mac/Linux (CMD TERMINAL)
-# OR
-#PowerShell
-New-Item -Path .env -ItemType File
+mkdir my-perplexity-project
+cd my-perplexity-project
+npm init -y
 ```
 
-Copy and paste the following into `.env`:
+#### Step 2: Install the middleware
 
 ```bash
-# Perplexity AI Configuration
-PERPLEXITY_API_KEY="your_perplexity_api_key_here"
-
-# Revenium Configuration
-REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
-REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
-
+npm install @revenium/perplexity dotenv
 ```
 
-### Step 4: Create Your First Test
+#### Step 3: Create `.env` file
 
-Choose between V1 (compatible) or V2 (enhanced) Controller:
+```env
+# Perplexity API Configuration
+PERPLEXITY_API_KEY=your_perplexity_api_key
 
-#### Option A: V1 Controller (Compatible)
+# Revenium Metering Configuration
+REVENIUM_METERING_API_KEY=your_revenium_api_key
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+```
 
-Create `test-perplexity-v1.js`:
+#### Step 4: Create `index.js`
 
 ```javascript
-// test-perplexity-v1.js
-import { PerplexityV1Controller } from "@revenium/perplexity";
-
-const basicV1Example = async () => {
-  try {
-    const controller = new PerplexityV1Controller();
-
-    const result = await controller.createChat(
-      ["What is the universe?"],
-      "sonar-pro"
-    );
-
-    console.log("*** V1 RESPONSE ***");
-    console.log(result.responses[0].text);
-    console.log(`📊 Tokens: ${result.usageMetadata.totalTokenCount}`);
-    console.log("✅ V1 Controller example successful!");
-  } catch (error) {
-    console.error("❌ V1 Controller example failed:", error);
-    process.exit(1);
-  }
-};
+const {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+} = require("@revenium/perplexity");
+
+async function main() {
+  // Initialize configurations
+  initializeReveniumFromEnv();
+  initializePerplexityFromEnv();
+
+  // Create a chat completion
+  const result = await createChatCompletion({
+    messages: [{ role: "user", content: "What is the capital of France?" }],
+    model: PERPLEXITY_MODELS.SONAR_PRO,
+  });
+
+  console.log("Response:", result.content);
+  console.log("Tokens used:", result.usage.totalTokens);
+}
 
-basicV1Example();
+main().catch(console.error);
 ```
 
-#### Option B: V2 Controller (Enhanced)
+#### Step 5: Run your project
 
-Create `test-perplexity-v2.js`:
+```bash
+node index.js
+```
 
-```javascript
-// test-perplexity-v2.js
-import { PerplexityV2Controller } from "@revenium/perplexity";
-
-const basicV2Example = async () => {
-  try {
-    const controller = new PerplexityV2Controller();
-
-    const result = await controller.createChat(
-      ["What is the universe?"],
-      "sonar-pro"
-    );
-
-    console.log("*** V2 ENHANCED RESPONSE ***");
-    console.log(result.choices[0].message.content);
-    console.log(`📊 Usage: ${result.usage.total_tokens} tokens`);
-    console.log(`⚡ Processing: ${result.metadata.processingTime}ms`);
-    console.log("✅ V2 Enhanced Controller example successful!");
-  } catch (error) {
-    console.error("❌ V2 Controller example failed:", error);
-    process.exit(1);
-  }
-};
+---
 
-basicV2Example();
-```
+### Option 2: Clone and Use Locally
 
-### Step 5: Update package.json
+**Best for:** Development, testing, or contributing to the middleware.
 
-Add test scripts and module type to your `package.json`:
+#### Step 1: Clone the repository
 
-```json
-{
-  "name": "my-perplexity-ai-project",
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "test-v1": "node test-perplexity-v1.js",
-    "test-v2": "node test-perplexity-v2.js"
-  },
-  "dependencies": {
-    "@revenium/perplexity": "^1.0.0"
-  }
-}
+```bash
+git clone https://github.com/revenium/revenium-middleware-perplexity-node.git
+cd revenium-middleware-perplexity-node
 ```
 
-⚠️ **Important**: If you get this error when running tests:
+#### Step 2: Install dependencies
 
-```
-SyntaxError: Cannot use import statement outside a module
+```bash
+npm install
 ```
 
-Make sure your `package.json` includes `"type": "module"` as shown below.
+#### Step 3: Create `.env` file
 
-```json
-{
-  "type": "module"
-}
+```env
+# Perplexity API Configuration
+PERPLEXITY_API_KEY=your_perplexity_api_key
+
+# Revenium Metering Configuration
+REVENIUM_METERING_API_KEY=your_revenium_api_key
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
 ```
 
-### Step 6: Run Your Tests
+#### Step 4: Build the project
 
 ```bash
-# Test V1 Controller (Compatible)
-npm run test-v1
-
-# Test V2 Controller (Enhanced)
-npm run test-v2
+npm run build
 ```
 
-### Step 7: Create Advanced Examples
+#### Step 5: Run examples
 
-Create an examples directory and add these files:
+**TypeScript Examples:**
 
 ```bash
-mkdir examples
+npm run example:basic      # Basic chat completion
+npm run example:streaming  # Streaming response
+npm run example:chat       # Multi-turn conversation
+npm run example:metadata   # Custom metadata
 ```
 
-#### V1 Streaming Example
-
-Create `examples/streaming-v1.js`:
+**JavaScript Playground:**
 
-```javascript
-// examples/streaming-v1.js
-import { PerplexityV1Controller } from "@revenium/perplexity";
-
-const streamingV1Example = async () => {
-  try {
-    const controller = new PerplexityV1Controller();
-
-    const stream = await controller.createStreaming(
-      ["What is artificial intelligence?"],
-      "sonar-pro"
-    );
-
-    console.log("*** V1 STREAMING RESPONSE ***");
-    let fullText = "";
-
-    for await (const chunk of stream) {
-      if (chunk.text) {
-        process.stdout.write(chunk.text);
-        fullText += chunk.text;
-      }
-    }
-
-    console.log("\n✅ V1 Streaming with metering successful!");
-    console.log(`📊 Total response length: ${fullText.length} characters`);
-  } catch (error) {
-    console.error("❌ V1 streaming example failed:", error);
-    process.exit(1);
-  }
-};
-
-streamingV1Example();
+```bash
+npm run playground:basic      # Basic chat completion
+npm run playground:streaming  # Streaming response
+npm run playground:chat       # Multi-turn conversation
+npm run playground:metadata   # Custom metadata
 ```
 
-#### V2 Streaming Example
+#### Step 6: Use in your own code
 
-Create `examples/streaming-v2.js`:
+After building, you can import from the local build:
 
 ```javascript
-// examples/streaming-v2.js
-import { PerplexityV2Controller } from "@revenium/perplexity";
-
-const streamingV2Example = async () => {
-  try {
-    const controller = new PerplexityV2Controller();
-
-    const stream = await controller.createStreaming(
-      ["What is artificial intelligence?"],
-      "sonar-pro"
-    );
-
-    console.log("*** V2 ENHANCED STREAMING RESPONSE ***");
-    let fullText = "";
-
-    for await (const chunk of stream) {
-      const content = chunk.choices?.[0]?.delta?.content;
-      if (content) {
-        process.stdout.write(content);
-        fullText += content;
-      }
-    }
-
-    console.log("\n✅ V2 Enhanced Streaming successful!");
-    console.log(`📊 Total response length: ${fullText.length} characters`);
-  } catch (error) {
-    console.error("❌ V2 streaming example failed:", error);
-    process.exit(1);
-  }
-};
+const {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+} = require("./dist/cjs");
 
-streamingV2Example();
+// Your code here...
 ```
 
-#### Metadata Example
+---
 
-Create `examples/metadata-v1.js`:
+### Option 3: Add to Existing Project
 
-```javascript
-// examples/metadata-v1.js
-import { PerplexityV1Controller } from "@revenium/perplexity";
-
-const metadataV1Example = async () => {
-  try {
-    const controller = new PerplexityV1Controller();
-
-    // Custom metadata for tracking
-    const customMetadata = {
-      traceId: "trace-12345",
-      taskType: "research-query",
-      subscriberEmail: "user@example.com",
-      subscriberId: "user-456",
-      organizationId: "org-789",
-      agent: "perplexity-v1-demo",
-    };
-
-    const result = await controller.createChat(
-      ["What is the capital of France?"],
-      "sonar-pro",
-      customMetadata
-    );
-
-    console.log("*** V1 RESPONSE WITH METADATA ***");
-    console.log(result.responses[0].text);
-    console.log(`📊 Tokens: ${result.usageMetadata.totalTokenCount}`);
-    console.log(`🏷️ Trace ID: ${customMetadata.traceId}`);
-    console.log("✅ V1 Metadata example successful!");
-  } catch (error) {
-    console.error("❌ V1 metadata example failed:", error);
-    process.exit(1);
-  }
-};
+**Best for:** Integrating Perplexity with Revenium into an existing Node.js project.
 
-metadataV1Example();
+#### Step 1: Install the middleware
+
+```bash
+npm install @revenium/perplexity
 ```
 
-Create `examples/metadata-v2.js`:
+#### Step 2: Add environment variables
 
-```javascript
-// examples/metadata-v2.js
-import { PerplexityV2Controller } from "@revenium/perplexity";
-
-const metadataV2Example = async () => {
-  try {
-    const controller = new PerplexityV2Controller();
-
-    // Enhanced metadata for V2
-    const customMetadata = {
-      traceId: "trace-v2-67890",
-      taskType: "enhanced-research",
-      subscriberEmail: "user@example.com",
-      subscriberId: "user-456",
-      organizationId: "org-789",
-      agent: "perplexity-v2-demo",
-    };
-
-    const result = await controller.createChat(
-      ["What is the capital of France?"],
-      "sonar-pro",
-      customMetadata
-    );
-
-    console.log("*** V2 ENHANCED RESPONSE WITH METADATA ***");
-    console.log(result.choices[0].message.content);
-    console.log(`📊 Usage: ${result.usage.total_tokens} tokens`);
-    console.log(`⚡ Processing: ${result.metadata.processingTime}ms`);
-    console.log(`🏷️ Trace ID: ${customMetadata.traceId}`);
-    console.log("✅ V2 Enhanced Metadata example successful!");
-  } catch (error) {
-    console.error("❌ V2 metadata example failed:", error);
-    process.exit(1);
-  }
-};
+Add to your existing `.env` file:
 
-metadataV2Example();
+```env
+# Perplexity API Configuration
+PERPLEXITY_API_KEY=your_perplexity_api_key
+
+# Revenium Metering Configuration
+REVENIUM_METERING_API_KEY=your_revenium_api_key
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
 ```
 
-### Step 8: Update package.json
+#### Step 3: Initialize in your application
 
-```json
-{
-  "name": "my-perplexity-ai-project",
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "test-v1": "node test-perplexity-v1.js",
-    "test-v2": "node test-perplexity-v2.js",
-    "test-v1-stream": "node examples/streaming-v1.js",
-    "test-v2-stream": "node examples/streaming-v2.js",
-    "test-v1-metadata": "node examples/metadata-v1.js",
-    "test-v2-metadata": "node examples/metadata-v2.js"
-  },
-  "dependencies": {
-    "@revenium/perplexity": "^1.0.0"
-  }
+**For CommonJS projects:**
+
+```javascript
+require("dotenv").config();
+const {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+} = require("@revenium/perplexity");
+
+// Initialize once at app startup
+initializeReveniumFromEnv();
+initializePerplexityFromEnv();
+
+// Use anywhere in your app
+async function askPerplexity(question) {
+  const result = await createChatCompletion({
+    messages: [{ role: "user", content: question }],
+    model: PERPLEXITY_MODELS.SONAR_PRO,
+  });
+  return result.content;
 }
 ```
 
-### Step 9: Test Advanced Examples
+**For ES Modules projects:**
 
-```bash
-# Test V1 examples
-npm run test-v1-stream
-npm run test-v1-metadata
+```javascript
+import "dotenv/config";
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+} from "@revenium/perplexity";
+
+// Initialize once at app startup
+initializeReveniumFromEnv();
+initializePerplexityFromEnv();
+
+// Use anywhere in your app
+export async function askPerplexity(question) {
+  const result = await createChatCompletion({
+    messages: [{ role: "user", content: question }],
+    model: PERPLEXITY_MODELS.SONAR_PRO,
+  });
+  return result.content;
+}
+```
 
-# Test V2 examples
-npm run test-v2-stream
-npm run test-v2-metadata
+**For TypeScript projects:**
+
+```typescript
+import "dotenv/config";
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+  type ChatCompletionResult,
+} from "@revenium/perplexity";
+
+// Initialize once at app startup
+initializeReveniumFromEnv();
+initializePerplexityFromEnv();
+
+// Use anywhere in your app
+export async function askPerplexity(question: string): Promise<string> {
+  const result: ChatCompletionResult = await createChatCompletion({
+    messages: [{ role: "user", content: question }],
+    model: PERPLEXITY_MODELS.SONAR_PRO,
+  });
+  return result.content;
+}
 ```
 
 ---
 
-## Option 2: Clone Repository
+## 🔧 Quick Start
 
-Perfect for testing with pre-built examples:
+### 1. Set up environment variables
 
-```bash
-# Clone the repository
-git clone git@github.com:revenium/revenium-middleware-perplexity-node.git
-cd revenium-middleware-perplexity-node
+Create a `.env` file in your project root:
 
-# Install dependencies
-npm install
-npm install @revenium/perplexity
+```env
+# Perplexity API Configuration
+PERPLEXITY_API_KEY=your_perplexity_api_key
 
-# Create your .env file
-cp .env.example .env
-# Edit .env with your API keys
+# Revenium Metering Configuration
+REVENIUM_METERING_API_KEY=your_revenium_api_key
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
 ```
 
-### Configure Environment Variables
+### 2. Initialize and use
 
-Edit your `.env` file:
+```typescript
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+} from "@revenium/perplexity";
 
-```bash
-# For Perplexity AI SDK
-PERPLEXITY_API_KEY="your_perplexity_api_key_here"
-REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
-REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
-```
+// Initialize configurations
+initializeReveniumFromEnv();
+initializePerplexityFromEnv();
 
-### Run V1 & V2 Examples
+// Create a chat completion
+const result = await createChatCompletion({
+  messages: [{ role: "user", content: "What is the capital of France?" }],
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
 
-```bash
-# Build the project first
-npm run build
-
-# V1 Controller Examples (TypeScript)
-npm run e-v1-basic        # V1 Basic chat completion
-npm run e-v1-streaming    # V1 Streaming response
-npm run e-v1-chat         # V1 Multi-turn chat
-npm run e-v1-metadata     # V1 Metadata tracking
-
-# V2 Controller Examples (TypeScript)
-npm run e-v2-basic        # V2 Enhanced chat completion
-npm run e-v2-streaming    # V2 Enhanced streaming
-npm run e-v2-chat         # V2 Enhanced multi-turn chat
-npm run e-v2-metadata     # V2 Enhanced metadata
-
-# V1 Playground Examples (JavaScript)
-npm run p-v1-basic        # V1 Basic (JavaScript)
-npm run p-v1-streaming    # V1 Streaming (JavaScript)
-npm run p-v1-chat         # V1 Chat (JavaScript)
-npm run p-v1-metadata     # V1 Metadata (JavaScript)
-
-# V2 Playground Examples (JavaScript)
-npm run p-v2-basic        # V2 Enhanced (JavaScript)
-npm run p-v2-streaming    # V2 Enhanced Streaming (JavaScript)
-npm run p-v2-chat         # V2 Enhanced Chat (JavaScript)
-npm run p-v2-metadata     # V2 Enhanced Metadata (JavaScript)
-
-# Convenience Scripts
-npm run examples:v1       # Run V1 basic example
-npm run examples:v2       # Run V2 basic example
-npm run examples:all      # Run both V1 and V2 examples
-npm run playground:v1     # Run V1 playground basic
-npm run playground:v2     # Run V2 playground basic
-npm run playground:all    # Run both V1 and V2 playground
-npm run test:v1           # Test all V1 examples
-npm run test:v2           # Test all V2 examples
-npm run test:all          # Test all V1 and V2 examples
+console.log(result.content);
+// Output: "The capital of France is Paris."
 ```
 
----
+## 📚 API Reference
 
-## Option 3: Existing Project Integration
+### Configuration
 
-Already have a project? Just install and replace imports:
+#### `initializeReveniumFromEnv()`
 
-### Step 1. Install the Package
+Initialize Revenium configuration from environment variables.
 
-```bash
-npm install @revenium/perplexity
+```typescript
+const config = initializeReveniumFromEnv();
 ```
 
-### Step 2. Add Environment Variables
+#### `initializePerplexityFromEnv()`
 
-Add to your existing `.env` file:
+Initialize Perplexity configuration from environment variables.
 
-```bash
-PERPLEXITY_API_KEY="your_perplexity_api_key_here"
-REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
-REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
+```typescript
+const config = initializePerplexityFromEnv();
 ```
 
-### Step 3. Replace Your Imports
+#### `initializeRevenium(config)`
 
-**Before:**
+Initialize Revenium with custom configuration.
 
-```javascript
-import { OpenAI } from "openai";
+```typescript
+initializeRevenium({
+  meteringApiKey: "your_api_key",
+  meteringBaseUrl: "https://api.revenium.io/meter",
+  teamId: "your_team_id", // Optional
+});
 ```
 
-**After (V1 Controller):**
-
-```javascript
-import { PerplexityV1Controller } from "@revenium/perplexity";
-```
+#### `initializePerplexity(config)`
 
-**After (V2 Controller):**
+Initialize Perplexity with custom configuration.
 
-```javascript
-import { PerplexityV2Controller } from "@revenium/perplexity";
+```typescript
+initializePerplexity({
+  apiKey: "your_perplexity_api_key",
+  baseUrl: "https://api.perplexity.ai", // Optional
+});
 ```
 
-### Step 4. Update Your Code
-
-#### V1 Controller Example (Compatible)
-
-```javascript
-import { PerplexityV1Controller } from "@revenium/perplexity";
-
-// Initialize V1 Controller
-const controller = new PerplexityV1Controller();
-const result = await controller.createChat(["Hello world"], "sonar-pro");
+### Chat Completions
 
-console.log("[V1 EXAMPLE]", result.responses[0].text);
-console.log(`Tokens: ${result.usageMetadata.totalTokenCount}`);
-```
+#### `createChatCompletion(params)`
 
-#### V2 Controller Example (Enhanced)
+Create a chat completion with automatic metering.
 
-```javascript
-import { PerplexityV2Controller } from "@revenium/perplexity";
-
-// Initialize V2 Controller
-const controller = new PerplexityV2Controller();
-const result = await controller.createChat(["Hello world"], "sonar-pro");
+```typescript
+const result = await createChatCompletion({
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "Hello!" },
+  ],
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+  maxTokens: 100,
+  temperature: 0.7,
+  usageMetadata: {
+    // Optional
+    subscriber: { id: "user-123" },
+    organizationId: "org-456",
+    productId: "product-789",
+  },
+});
 
-console.log("[V2 ENHANCED EXAMPLE]", result.choices[0].message.content);
-console.log(`Usage: ${result.usage.total_tokens} tokens`);
-console.log(`Processing: ${result.metadata.processingTime}ms`);
+console.log(result.content);
+console.log(result.usage);
+console.log(result.transactionId);
 ```
 
----
-
-## 🔧 Advanced Usage
+**Parameters:**
 
-### Streaming Responses
+- `messages` - Array of message objects with `role` and `content`
+- `model` - Perplexity model to use (see [Available Models](https://github.com/revenium/revenium-middleware-perplexity-node#available-models))
+- `maxTokens` - Maximum tokens to generate (optional)
+- `temperature` - Sampling temperature 0-2 (optional)
+- `topP` - Nucleus sampling parameter (optional)
+- `presencePenalty` - Presence penalty -2 to 2 (optional)
+- `frequencyPenalty` - Frequency penalty -2 to 2 (optional)
+- `usageMetadata` - Custom metadata for tracking (optional)
 
-#### V1 Controller Streaming
-
-```javascript
-import { PerplexityV1Controller } from "@revenium/perplexity";
+**Returns:**
 
-const controller = new PerplexityV1Controller();
-const stream = await controller.createStreaming(["Hello world"], "sonar-pro");
-
-for await (const chunk of stream) {
-  if (chunk.text) {
-    process.stdout.write(chunk.text);
+```typescript
+{
+  content: string;
+  role: string;
+  finishReason: string | null;
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
   }
+  model: string;
+  transactionId: string;
+  rawResponse: PerplexityResponse;
 }
 ```
 
-#### V2 Controller Streaming (Enhanced)
+#### `createStreamingChatCompletion(params)`
 
-```javascript
-import { PerplexityV2Controller } from "@revenium/perplexity";
+Create a streaming chat completion.
 
-const controller = new PerplexityV2Controller();
-const stream = await controller.createStreaming(["Hello world"], "sonar-pro");
+```typescript
+const result = await createStreamingChatCompletion({
+  messages: [{ role: "user", content: "Count from 1 to 5" }],
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
 
-for await (const chunk of stream) {
-  const content = chunk.choices?.[0]?.delta?.content;
-  if (content) {
-    process.stdout.write(content);
-  }
+for await (const chunk of result.stream) {
+  const content = chunk.choices[0]?.delta?.content || "";
+  process.stdout.write(content);
 }
 ```
 
-### Custom Metadata Tracking
+**Returns:**
 
-#### V1 Metadata Example
-
-```javascript
-const customMetadata = {
-  traceId: "trace-12345",
-  taskType: "research-query",
-  subscriberEmail: "user@example.com",
-  organizationId: "org-789",
-  agent: "perplexity-v1-demo",
-};
-
-const result = await controller.createChat(
-  ["What is AI?"],
-  "sonar-pro",
-  customMetadata
-);
+```typescript
+{
+  stream: AsyncGenerator<PerplexityStreamChunk>;
+  transactionId: string;
+  model: string;
+}
 ```
 
-#### V2 Enhanced Metadata Example
+### Available Models
 
-```javascript
-const customMetadata = {
-  traceId: "trace-v2-67890",
-  taskType: "enhanced-research",
-  subscriberEmail: "user@example.com",
-  organizationId: "org-789",
-  agent: "perplexity-v2-demo",
-};
+```typescript
+import { PERPLEXITY_MODELS } from "@revenium/perplexity";
 
-const result = await controller.createChat(
-  ["What is AI?"],
-  "sonar-pro",
-  customMetadata
-);
+// Online Models (with internet access)
+PERPLEXITY_MODELS.SONAR; // "sonar"
+PERPLEXITY_MODELS.SONAR_PRO; // "sonar-pro"
+PERPLEXITY_MODELS.SONAR_REASONING; // "sonar-reasoning"
 
-// V2 provides additional metadata
-console.log(`Processing time: ${result.metadata.processingTime}ms`);
-console.log(`Transaction ID: ${result.metadata.transactionId}`);
+// Chat Models (offline)
+PERPLEXITY_MODELS.LLAMA_3_1_SONAR_SMALL_128K_CHAT; // "llama-3.1-sonar-small-128k-chat"
+PERPLEXITY_MODELS.LLAMA_3_1_SONAR_LARGE_128K_CHAT; // "llama-3.1-sonar-large-128k-chat"
+PERPLEXITY_MODELS.LLAMA_3_1_SONAR_HUGE_128K_CHAT; // "llama-3.1-sonar-huge-128k-chat"
 ```
 
-## 📊 What Gets Tracked
-
-### V1 Controller Tracking
+### Utility Functions
 
-- **Token Usage**: Input and output tokens for accurate billing
-- **Request Duration**: Total time for each API call
-- **Model Information**: Which model was used
-- **Operation Type**: Chat completion, streaming
-- **Error Tracking**: Failed requests and error details
-- **Custom Metadata**: Rich business context and user tracking
-- **Transaction ID**: Unique identifier for each request
+#### `disableRevenium()` / `enableRevenium()`
 
-### V2 Enhanced Tracking (Additional)
+Temporarily disable or enable Revenium metering.
 
-- **Processing Time**: Enhanced timing metrics
-- **Enhanced Metadata**: Additional context following OpenAI Responses API
-- **Response Format**: OpenAI-compatible response structure
-- **Model Performance**: Enhanced model capability tracking
-- **Streaming Metrics**: Time to first token for streaming responses
+```typescript
+import { disableRevenium, enableRevenium } from "@revenium/perplexity";
 
----
+disableRevenium(); // Stop sending metering data
+// ... make API calls ...
+enableRevenium(); // Resume sending metering data
+```
 
-## 🔗 Supported Models
+#### `generateTransactionId()`
 
-### Chat Models
+Generate a unique transaction ID.
 
-- **sonar-pro** (Latest and most capable)
-- **sonar-small** (Fast and efficient)
-- **sonar-medium** (Balanced performance)
-- **llama-3.1-sonar-small-128k-online** (Llama-based with online search)
-- **llama-3.1-sonar-large-128k-online** (Large Llama model with online search)
-- **llama-3.1-sonar-huge-128k-online** (Huge Llama model with online search)
+```typescript
+import { generateTransactionId } from "@revenium/perplexity";
 
-### Model Capabilities
+const txnId = generateTransactionId();
+```
 
-Both V1 and V2 Controllers support:
+## 📖 Examples
 
-- **Chat Completions**: All models support chat completions
-- **Streaming**: Real-time response streaming
-- **Online Search**: Models with "online" in the name support web search
-- **Large Context**: 128k context window for Llama models
+### Basic Chat Completion
 
-_Note: Model availability depends on your Perplexity AI account and API access level._
+```typescript
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+} from "@revenium/perplexity";
 
----
+initializeReveniumFromEnv();
+initializePerplexityFromEnv();
 
-## 🛠️ Configuration Options
+const result = await createChatCompletion({
+  messages: [{ role: "user", content: "What is the capital of France?" }],
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
 
-### Environment Variables
+console.log(result.content);
+```
 
-| Variable                     | Required | Description                                                |
-| ---------------------------- | -------- | ---------------------------------------------------------- |
-| `PERPLEXITY_API_KEY`         | ✅       | Your Perplexity API key                                    |
-| `REVENIUM_METERING_API_KEY`  | ✅       | Your Revenium API key                                      |
-| `REVENIUM_METERING_BASE_URL` | ❌       | Revenium base URL (default: https://api.revenium.io/meter) |
+### Streaming Response
 
----
+```typescript
+const result = await createStreamingChatCompletion({
+  messages: [{ role: "user", content: "Write a short poem about AI" }],
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
 
-## 🚨 Troubleshooting
+for await (const chunk of result.stream) {
+  const content = chunk.choices[0]?.delta?.content || "";
+  process.stdout.write(content);
+}
+```
 
-### Common Issues
+### Multi-turn Conversation
 
-**"Missing API Key" Error**
+```typescript
+const messages = [
+  { role: "system", content: "You are a helpful assistant." },
+  { role: "user", content: "What is the capital of France?" },
+];
 
-```bash
-export PERPLEXITY_API_KEY="your-actual-api-key"
-echo $PERPLEXITY_API_KEY  # Verify it's set
-```
+const response1 = await createChatCompletion({
+  messages,
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
 
-**"Requests not being tracked"**
+messages.push({ role: "assistant", content: response1.content });
+messages.push({ role: "user", content: "What is its population?" });
 
-```bash
-export REVENIUM_METERING_API_KEY="your-actual-revenium-key"
+const response2 = await createChatCompletion({
+  messages,
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
 ```
 
-**Module Import Errors**
+### Custom Metadata
 
-```json
-{
-  "type": "module"
-}
+```typescript
+const result = await createChatCompletion({
+  messages: [{ role: "user", content: "Hello!" }],
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+  usageMetadata: {
+    subscriber: {
+      id: "user-123",
+      email: "user@example.com",
+    },
+    organizationId: "org-456",
+    productId: "premium-plan",
+    traceId: "trace-abc-123",
+  },
+});
 ```
 
-This will show:
+## 🏗️ Project Structure
 
-- Request/response details
-- Token counting information
-- Metering data being sent
-- Error details
-- Middleware activation status
-
----
-
-## 📚 Examples Repository
-
-Check out our comprehensive examples organized by version:
-
-### V1 Controller Examples (Compatible)
+```
+revenium-middleware-perplexity-node/
+├── src/
+│   ├── core/
+│   │   ├── config/           # Configuration management
+│   │   ├── tracking/         # Metering and tracking
+│   │   └── wrapper/          # Perplexity API wrapper
+│   ├── types/                # TypeScript type definitions
+│   ├── utils/                # Utility functions
+│   └── index.ts              # Main entry point
+├── examples/                 # TypeScript examples
+├── playground/               # JavaScript examples
+└── dist/
+    ├── cjs/                  # CommonJS build
+    ├── esm/                  # ES Modules build
+    └── types/                # TypeScript definitions
+```
 
-- **Basic Usage**: Simple chat completions with V1 response format
-- **Streaming**: Real-time response streaming with V1 format
-- **Multi-turn Chat**: Conversation handling with V1 controllers
-- **Metadata**: Rich tracking examples with V1 metadata
-- **Model Capabilities**: Check model features and capabilities
+## 🧪 Running Examples
 
-### V2 Controller Examples (Enhanced)
+### TypeScript Examples
 
-- **Enhanced Basic**: Chat completions with OpenAI-compatible responses
-- **Enhanced Streaming**: Streaming with enhanced metadata and timing
-- **Enhanced Chat**: Multi-turn conversations with V2 enhancements
-- **Enhanced Metadata**: Advanced tracking with processing time metrics
-- **Model Performance**: Enhanced model capability and performance tracking
+```bash
+npm run example:basic      # Basic chat completion
+npm run example:streaming  # Streaming response
+npm run example:chat       # Multi-turn conversation
+npm run example:metadata   # Custom metadata
+```
 
-### File Organization
+### JavaScript Playground
 
-- **`/examples/v1/`**: TypeScript examples using V1 Controllers (development)
-- **`/examples/v2/`**: TypeScript examples using V2 Controllers (development)
-- **`/playground/v1/`**: JavaScript examples using V1 Controllers (production)
-- **`/playground/v2/`**: JavaScript examples using V2 Controllers (production)
+```bash
+npm run playground:basic      # Basic chat completion
+npm run playground:streaming  # Streaming response
+npm run playground:chat       # Multi-turn conversation
+npm run playground:metadata   # Custom metadata
+```
 
----
+## 🔒 Environment Variables
 
-## 📋 Requirements
+| Variable                     | Required | Description                                                        |
+| ---------------------------- | -------- | ------------------------------------------------------------------ |
+| `PERPLEXITY_API_KEY`         | Yes      | Your Perplexity API key                                            |
+| `REVENIUM_METERING_API_KEY`  | Yes      | Your Revenium metering API key                                     |
+| `REVENIUM_METERING_BASE_URL` | Yes      | Revenium metering endpoint (e.g., `https://api.revenium.io/meter`) |
 
-- Node.js 18+
-- Perplexity API key
-- Revenium API key
+## 📄 License
 
----
+ISC
 
-## 📄 License
+## 🤝 Contributing
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+Contributions are welcome! Please feel free to submit a Pull Request.
 
----
+## 📞 Support
 
-## 🤝 Support
+For issues and questions:
 
-- 📖 [Documentation](https://docs.revenium.com)
-- 💬 [Community Support](https://community.revenium.com)
-- 📧 [Email Support](mailto:support@revenium.com)
-- 🐛 [Report Issues](https://github.com/revenium/revenium-middleware-perplexity-node/issues)
+- GitHub Issues: [revenium-middleware-perplexity-node/issues](https://github.com/revenium/revenium-middleware-perplexity-node/issues)
+- Documentation: [Revenium Docs](https://docs.revenium.io)
 
----
+## 🔗 Links
 
-**Built with ❤️ by Revenium**
+- [Perplexity AI Documentation](https://docs.perplexity.ai)
+- [Revenium Platform](https://revenium.io)
+- [npm Package](https://www.npmjs.com/package/@revenium/perplexity)