@revenium/perplexity 1.0.10 → 1.0.11

package/README.md

@@ -1,566 +1,603 @@
-# Revenium Middleware for Perplexity AI (Node.js)
-
-[![npm version](https://img.shields.io/npm/v/@revenium/perplexity.svg)](https://www.npmjs.com/package/@revenium/perplexity)
-[![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-revenium.io-blue)](https://docs.revenium.io)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-Automatically track and meter your Perplexity AI API usage with Revenium. This middleware provides seamless integration with Perplexity AI SDK, requiring minimal code changes.
-
-## 🚀 Getting Started
-
-You have **3 options** to start using Revenium middleware for Perplexity AI:
-
-### Option 1: Create Project from Scratch
-
-Perfect for new projects. We'll guide you step-by-step from `mkdir` to running tests.
-[👉 Go to Step-by-Step Guide](#option-1-create-project-from-scratch)
-
-### Option 2: Clone Our Repository
-
-Quick testing with pre-built 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 replace imports.
-[👉 Go to Quick Integration](#option-3-existing-project-integration)
-
----
-
-## Option 1: Create Project from Scratch
-
-### Step 1: Create Project Directory
-
-```bash
-# Create and navigate to your project
-mkdir my-perplexity-ai-project
-cd my-perplexity-ai-project
-
-# Initialize Node.js project
-npm init -y
-```
-
-### Step 2: Install Dependencies
-
-```bash
-npm install @revenium/perplexity
-```
-
-### Step 3: Setup Environment Variables
-
-Create a `.env` file in your project root:
-
-```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
-```
-
-Copy and paste the following into `.env`:
-
-```env
-# 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
-
-# Optional: Enable debug logging
-REVENIUM_LOG_LEVEL=INFO
-```
-
-### Step 4: Create Your First Test
-
-Create `test-perplexity.js`:
-
-```javascript
-// test-perplexity.js
-import { createPerplexityClient } from "@revenium/perplexity";
-
-const client = createPerplexityClient();
-
-try {
-  const result = await client.createChatCompletion({
-    model: "sonar-pro",
-    messages: [
-      {
-        role: "user",
-        content: "What is the universe?",
-      },
-    ],
-  });
-
-  const text = result.choices[0]?.message?.content;
-  console.log("*** RESPONSE ***");
-  console.log(text);
-  console.log("✅ Basic Perplexity AI example successful!");
-} catch (error) {
-  console.error("❌ Perplexity basic example failed:", error);
-  process.exit(1);
-}
-```
-
-### Step 5: Update package.json
-
-Add test scripts and module type to your `package.json`:
-
-```json
-{
-  "name": "my-perplexity-ai-project",
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "test-perplexity": "node test-perplexity.js"
-  },
-  "dependencies": {
-    "@revenium/perplexity": "^1.0.0"
-  }
-}
-```
-
-**⚠️ Important**: If you get this error when running tests:
-
-```
-SyntaxError: Cannot use import statement outside a module
-```
-
-Make sure your `package.json` includes `"type": "module"` as shown below.
-
-```json
-{
-  "type": "module"
-}
-```
-
-### Step 6: Run Your Tests
-
-```bash
-# Test Perplexity AI SDK
-npm run test-perplexity
-```
-
-### Step 7: Create Advanced Examples
-
-Create an `examples` directory and add these files:
-
-```bash
-mkdir examples
-```
-
-#### Streaming Example
-
-Create `examples/streaming-perplexity.js`:
-
-```javascript
-// examples/streaming-perplexity.js
-import { createPerplexityClient } from "@revenium/perplexity";
-
-const client = createPerplexityClient();
-
-try {
-  const stream = await client.createStreamingChatCompletion({
-    model: "sonar-pro",
-    messages: [
-      {
-        role: "user",
-        content: "What is artificial intelligence?",
-      },
-    ],
-  });
-
-  console.log("*** 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✅ Streaming with metering successful!");
-  console.log(`📊 Total response length: ${fullText.length} characters`);
-} catch (error) {
-  console.error("❌ Perplexity streaming example failed:", error);
-  process.exit(1);
-}
-```
-
-#### Metadata Example
-
-Create `examples/metadata-perplexity.js`:
-
-```javascript
-// examples/metadata-perplexity.js
-import { createPerplexityClient } from "@revenium/perplexity";
-
-const client = createPerplexityClient();
-
-try {
-  const result = await client.createChatCompletion({
-    model: "sonar-pro",
-    messages: [
-      {
-        role: "user",
-        content: "Analyze this quarterly report",
-      },
-    ],
-    usageMetadata: {
-      // User tracking
-      traceId: "conv-28a7e9d4",
-      taskType: "document-analysis",
-      subscriberEmail: "user@example.com",
-      subscriberId: "user-123",
-      subscriberCredentialName: "api-key-1",
-
-      // Business context
-      organizationId: "acme-corp",
-      subscriptionId: "premium-plan",
-      productId: "business-intelligence",
-      agent: "analysis-assistant",
-      responseQualityScore: 0.95,
-    },
-  });
-
-  console.log("*** METADATA RESPONSE ***");
-  console.log("Response:", result.choices[0]?.message?.content);
-  console.log("✅ Metadata tracking with metering successful!");
-} catch (error) {
-  console.error("❌ Perplexity metadata example failed:", error);
-  process.exit(1);
-}
-```
-
-### Step 8: Update package.json
-
-```json
-{
-  "name": "my-perplexity-ai-project",
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "test-perplexity": "node test-perplexity.js",
-    "test-perplexity-stream": "node examples/streaming-perplexity.js",
-    "test-perplexity-metadata": "node examples/metadata-perplexity.js"
-  },
-  "dependencies": {
-    "@revenium/perplexity": "^1.0.0"
-  }
-}
-```
-
-### Step 9: Test Advanced Examples
-
-```bash
-# Test streaming
-npm run test-perplexity-stream
-
-# Test metadata
-npm run test-perplexity-metadata
-```
-
----
-
-## Option 2: Clone Repository
-
-Perfect for testing with pre-built examples:
-
-```bash
-# Clone the repository
-git clone git@github.com:revenium/revenium-middleware-perplexity-node.git
-cd revenium-middleware-perplexity-node
-
-# Install dependencies
-npm install
-
-# Create your .env file
-cp .env.example .env
-# Edit .env with your API keys
-```
-
-### Configure Environment Variables
-
-Edit your `.env` file:
-
-```env
-# 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
-
-```
-
-### Run Perplexity AI Examples
-
-```bash
-# Perplexity AI examples
-npm run p-basic        # Basic chat completion
-npm run p-streaming    # Streaming response
-npm run p-metadata     # Rich metadata tracking
-
-# Playground examples
-# Required build first
-npm run build
-# Then run any of the following
-npm run p-perplexity-basic
-npm run p-perplexity-streaming
-npm run p-perplexity-metadata
-```
-
----
-
-## Option 3: Existing Project Integration
-
-Already have a project? Just install and replace imports:
-
-### Step 1. Install the Package
-
-```bash
-npm install @revenium/perplexity
-```
-
-### Step 2. Add Environment Variables
-
-Add to your existing `.env` file:
-
-```env
-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
-# Optional: Enable debug logging
-REVENIUM_LOG_LEVEL=INFO
-```
-
-### Step 3. Replace Your Imports
-
-**Before:**
-
-```javascript
-import { OpenAI } from "openai";
-```
-
-**After:**
-
-```javascript
-import { createPerplexityClient } from "@revenium/perplexity";
-```
-
-**Or Use OpenAI Client (Alternative):**
-
-```javascript
-import { OpenAI } from "openai";
-import "@revenium/perplexity"; // Import middleware to activate tracking
-```
-
-### Step 4. Update Your Code
-
-**Revenium Client Example**
-
-```javascript
-import { createPerplexityClient } from "@revenium/perplexity";
-
-// Initialize (API key from environment variable)
-const client = createPerplexityClient();
-
-// Make your request - metering happens automatically!
-const result = await client.createChatCompletion({
-  model: "sonar-pro",
-  messages: [{ role: "user", content: "What is artificial intelligence?" }],
-});
-console.log(result.choices[0]?.message?.content);
-```
-
-**OpenAI Client Example**
-
-```javascript
-import { OpenAI } from "openai";
-import "@revenium/perplexity"; // Import middleware for automatic tracking
-
-// Initialize OpenAI client for Perplexity
-const client = new OpenAI({
-  apiKey: process.env.PERPLEXITY_API_KEY,
-  baseURL: "https://api.perplexity.ai",
-});
-
-// Make your request - metering happens automatically!
-const result = await client.chat.completions.create({
-  model: "sonar-pro",
-  messages: [{ role: "user", content: "What is artificial intelligence?" }],
-});
-console.log(result.choices[0]?.message?.content);
-```
-
-## 🔧 Advanced Usage
-
-### Streaming Responses
-
-**Revenium Client Streaming**
-
-```javascript
-const stream = await client.createStreamingChatCompletion({
-  model: "sonar-pro",
-  messages: [{ role: "user", content: "Write a story about AI" }],
-});
-
-for await (const chunk of stream) {
-  const content = chunk.choices[0]?.delta?.content;
-  if (content) process.stdout.write(content);
-}
-```
-
-**OpenAI Client Streaming**
-
-```javascript
-import { OpenAI } from "openai";
-import "@revenium/perplexity";
-
-const client = new OpenAI({
-  apiKey: process.env.PERPLEXITY_API_KEY,
-  baseURL: "https://api.perplexity.ai",
-});
-
-const stream = await client.chat.completions.create({
-  model: "sonar-pro",
-  messages: [{ role: "user", content: "Write a story about AI" }],
-  stream: true,
-});
-
-for await (const chunk of stream) {
-  const content = chunk.choices[0]?.delta?.content;
-  if (content) process.stdout.write(content);
-}
-```
-
-### Rich Metadata Tracking
-
-```javascript
-import { createPerplexityClient } from "@revenium/perplexity";
-
-const client = createPerplexityClient();
-
-const response = await client.createChatCompletion({
-  model: "sonar-pro",
-  messages: [
-    {
-      role: "user",
-      content: "Analyze this quarterly report",
-    },
-  ],
-  usageMetadata: {
-    // User tracking
-    traceId: "conv-28a7e9d4",
-    taskType: "document-analysis",
-    subscriberEmail: "user@example.com",
-    subscriberId: "user-123",
-    subscriberCredentialName: "api-key-1",
-
-    // Business context
-    organizationId: "acme-corp",
-    subscriptionId: "premium-plan",
-    productId: "business-intelligence",
-    agent: "analysis-assistant",
-    responseQualityScore: 0.95,
-  },
-});
-```
-
-## 📊 What Gets Tracked
-
-- **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
-- **Streaming Metrics**: Time to first token for streaming responses
-- **Custom Metadata**: Rich business context and user tracking
-
-## 🔗 Supported Models
-
-### Chat Models
-
-- **sonar-pro** (Latest and most capable)
-- **sonar-small** (Fast and efficient)
-- **sonar-medium** (Balanced performance)
-
-_Note: Model availability depends on your Perplexity AI account and API access level._
-
-## 🛠️ Configuration Options
-
-### Environment Variables
-
-| Variable                     | Required | Description                                                     |
-| ---------------------------- | -------- | --------------------------------------------------------------- |
-| `PERPLEXITY_API_KEY`         | ✅       | Your Perplexity API key                                         |
-| `REVENIUM_METERING_API_KEY`  | ✅       | Your Revenium API key                                           |
-| `PERPLEXITY_BASE_URL`        | ❌       | Custom Perplexity base URL (default: https://api.perplexity.ai) |
-| `REVENIUM_METERING_BASE_URL` | ❌       | Revenium base URL (default: https://api.revenium.io/meter/v2)   |
-| `REVENIUM_LOG_LEVEL`         | ❌       | Log level: DEBUG, INFO, WARNING, ERROR                          |
-
-### Manual Configuration
-
-```javascript
-// Revenium client with custom configuration
-const client = createPerplexityClient(
-  "your-api-key",
-  "https://api.perplexity.ai"
-);
-
-// OpenAI client with custom base URL
-const openaiClient = new OpenAI({
-  apiKey: "your-api-key",
-  baseURL: "https://custom-perplexity-endpoint.com",
-});
-```
-
-## 🚨 Troubleshooting
-
-### Common Issues
-
-**"Missing API Key" Error**
-
-```bash
-export PERPLEXITY_API_KEY="your-actual-api-key"
-echo $PERPLEXITY_API_KEY  # Verify it's set
-```
-
-**"Requests not being tracked"**
-
-```bash
-export REVENIUM_METERING_API_KEY="your-actual-revenium-key"
-export REVENIUM_LOG_LEVEL="DEBUG"  # Enable debug logging
-```
-
-**Module Import Errors**
-
-```json
-{
-  "type": "module"
-}
-```
-
-## 📋 Requirements
-
-- Node.js 18+
-- Perplexity API key
-- Revenium API key
-
-## 📄 License
-
-MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🤝 Support
-
-- 📖 [Documentation](https://docs.revenium.io)
-- 💬 [Community Support](https://community.revenium.io)
-- 📧 [Email Support](mailto:support@revenium.io)
-- 🐛 [Report Issues](https://github.com/revenium/revenium-middleware-perplexity-node/issues)
-
----
-
-**Built with ❤️ by Revenium**
+# Revenium Middleware for Perplexity AI (Node.js)
+
+[![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)
+
+Automatically track and meter your Perplexity AI API usage with Revenium. This middleware provides seamless integration with Perplexity AI SDK, requiring minimal code changes.
+
+## 🚀 Getting Started
+
+You have 3 options to start using Revenium middleware for Perplexity AI:
+
+| Option                                    | Description                                                                         | Best For                                                             |
+| ----------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Option 1: Create Project from Scratch** | Perfect for new projects. We'll guide you step-by-step from mkdir to running tests. | 👉 [Go to Step-by-Step Guide](#option-1-create-project-from-scratch) |
+| **Option 2: Clone Our Repository**        | Quick testing with pre-built 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 replace imports.                           | 👉 [Go to Quick Integration](#option-3-existing-project-integration) |
+
+---
+
+## Option 1: Create Project from Scratch
+
+### Step 1: Create Project Directory
+
+```bash
+# Create and navigate to your project
+mkdir my-perplexity-ai-project
+cd my-perplexity-ai-project
+
+# Initialize Node.js project
+npm init -y
+```
+
+### Step 2: Install Dependencies
+
+```bash
+npm install @revenium/perplexity
+```
+
+### Step 3: Setup Environment Variables
+
+Create a `.env` file in your project root:
+
+```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
+```
+
+Copy and paste the following into `.env`:
+
+```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
+
+```
+
+### Step 4: Create Your First Test
+
+Create `test-perplexity.js`:
+
+```javascript
+// test-perplexity.js
+import { createPerplexityClient } from "@revenium/perplexity";
+
+const client = createPerplexityClient();
+
+try {
+  const result = await client.createChatCompletion({
+    model: "sonar-pro",
+    messages: [
+      {
+        role: "user",
+        content: "What is the universe?",
+      },
+    ],
+  });
+
+  const text = result.choices[0]?.message?.content;
+  console.log("*** RESPONSE ***");
+  console.log(text);
+  console.log("✅ Basic Perplexity AI example successful!");
+} catch (error) {
+  console.error("❌ Perplexity basic example failed:", error);
+  process.exit(1);
+}
+```
+
+### Step 5: Update package.json
+
+Add test scripts and module type to your `package.json`:
+
+```json
+{
+  "name": "my-perplexity-ai-project",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "test-perplexity": "node test-perplexity.js"
+  },
+  "dependencies": {
+    "@revenium/perplexity": "^1.0.0"
+  }
+}
+```
+
+⚠️ **Important**: If you get this error when running tests:
+
+```
+SyntaxError: Cannot use import statement outside a module
+```
+
+Make sure your `package.json` includes `"type": "module"` as shown below.
+
+```json
+{
+  "type": "module"
+}
+```
+
+### Step 6: Run Your Tests
+
+```bash
+# Test Perplexity AI SDK
+npm run test-perplexity
+```
+
+### Step 7: Create Advanced Examples
+
+Create an examples directory and add these files:
+
+```bash
+mkdir examples
+```
+
+#### Streaming Example
+
+Create `examples/streaming-perplexity.js`:
+
+```javascript
+// examples/streaming-perplexity.js
+import { createPerplexityClient } from "@revenium/perplexity";
+
+const client = createPerplexityClient();
+
+try {
+  const stream = await client.createStreamingChatCompletion({
+    model: "sonar-pro",
+    messages: [
+      {
+        role: "user",
+        content: "What is artificial intelligence?",
+      },
+    ],
+  });
+
+  console.log("*** 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✅ Streaming with metering successful!");
+  console.log(`📊 Total response length: ${fullText.length} characters`);
+} catch (error) {
+  console.error("❌ Perplexity streaming example failed:", error);
+  process.exit(1);
+}
+```
+
+#### Metadata Example
+
+Create `examples/metadata-perplexity.js`:
+
+```javascript
+// examples/metadata-perplexity.js
+import { createPerplexityClient } from "@revenium/perplexity";
+
+const client = createPerplexityClient();
+
+try {
+  const result = await client.createChatCompletion({
+    model: "sonar-pro",
+    messages: [
+      {
+        role: "user",
+        content: "Analyze this quarterly report",
+      },
+    ],
+    usageMetadata: {
+      // User tracking
+      traceId: "conv-28a7e9d4",
+      taskType: "document-analysis",
+      subscriberEmail: "user@example.com",
+      subscriberId: "user-123",
+      subscriberCredentialName: "api-key-1",
+
+      // Business context
+      organizationId: "acme-corp",
+      subscriptionId: "premium-plan",
+      productId: "business-intelligence",
+      agent: "analysis-assistant",
+      responseQualityScore: 0.95,
+    },
+  });
+
+  console.log("*** METADATA RESPONSE ***");
+  console.log("Response:", result.choices[0]?.message?.content);
+  console.log("✅ Metadata tracking with metering successful!");
+} catch (error) {
+  console.error("❌ Perplexity metadata example failed:", error);
+  process.exit(1);
+}
+```
+
+### Step 8: Update package.json
+
+```json
+{
+  "name": "my-perplexity-ai-project",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "test-perplexity": "node test-perplexity.js",
+    "test-perplexity-stream": "node examples/streaming-perplexity.js",
+    "test-perplexity-metadata": "node examples/metadata-perplexity.js"
+  },
+  "dependencies": {
+    "@revenium/perplexity": "^1.0.0"
+  }
+}
+```
+
+### Step 9: Test Advanced Examples
+
+```bash
+# Test streaming
+npm run test-perplexity-stream
+
+# Test metadata
+npm run test-perplexity-metadata
+```
+
+---
+
+## Option 2: Clone Repository
+
+Perfect for testing with pre-built examples:
+
+```bash
+# Clone the repository
+git clone git@github.com:revenium/revenium-middleware-perplexity-node.git
+cd revenium-middleware-perplexity-node
+
+# Install dependencies
+npm install
+
+# Create your .env file
+cp .env.example .env
+# Edit .env with your API keys
+```
+
+### Configure Environment Variables
+
+Edit your `.env` file:
+
+```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
+```
+
+### Run Perplexity AI Examples
+
+```bash
+# Perplexity AI examples
+npm run p-basic        # Basic chat completion
+npm run p-streaming    # Streaming response
+npm run p-metadata     # Rich metadata tracking
+
+# Playground examples
+# Required build first
+npm run build
+# Then run any of the following
+npm run p-perplexity-basic
+npm run p-perplexity-streaming
+npm run p-perplexity-metadata
+```
+
+---
+
+## Option 3: Existing Project Integration
+
+Already have a project? Just install and replace imports:
+
+### Step 1. Install the Package
+
+```bash
+npm install @revenium/perplexity
+```
+
+### Step 2. Add Environment Variables
+
+Add to your existing `.env` file:
+
+```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
+# Optional: Enable debug logging
+REVENIUM_LOG_LEVEL=INFO
+```
+
+### Step 3. Replace Your Imports
+
+**Before:**
+
+```javascript
+import { OpenAI } from "openai";
+```
+
+**After:**
+
+```javascript
+import { createPerplexityClient } from "@revenium/perplexity";
+```
+
+**Or Use OpenAI Client (Alternative):**
+
+```javascript
+import { OpenAI } from "openai";
+import "@revenium/perplexity"; // Import middleware to activate tracking
+```
+
+### Step 4. Update Your Code
+
+#### Revenium Client Example
+
+```javascript
+import { createPerplexityClient } from "@revenium/perplexity";
+
+// Initialize (API key from environment variable)
+const client = createPerplexityClient();
+
+// Make your request - metering happens automatically!
+const result = await client.createChatCompletion({
+  model: "sonar-pro",
+  messages: [{ role: "user", content: "What is artificial intelligence?" }],
+});
+console.log(result.choices[0]?.message?.content);
+```
+
+#### OpenAI Client Example
+
+```javascript
+import { OpenAI } from "openai";
+import "@revenium/perplexity"; // Import middleware for automatic tracking
+
+// Initialize OpenAI client for Perplexity
+const client = new OpenAI({
+  apiKey: process.env.PERPLEXITY_API_KEY,
+  baseURL: "https://api.perplexity.ai",
+});
+
+// Make your request - metering happens automatically!
+const result = await client.chat.completions.create({
+  model: "sonar-pro",
+  messages: [{ role: "user", content: "What is artificial intelligence?" }],
+});
+console.log(result.choices[0]?.message?.content);
+```
+
+---
+
+## 🔧 Advanced Usage
+
+### Streaming Responses
+
+#### Revenium Client Streaming
+
+```javascript
+const stream = await client.createStreamingChatCompletion({
+  model: "sonar-pro",
+  messages: [{ role: "user", content: "Write a story about AI" }],
+});
+
+for await (const chunk of stream) {
+  const content = chunk.choices[0]?.delta?.content;
+  if (content) process.stdout.write(content);
+}
+```
+
+#### OpenAI Client Streaming
+
+```javascript
+import { OpenAI } from "openai";
+import "@revenium/perplexity";
+
+const client = new OpenAI({
+  apiKey: process.env.PERPLEXITY_API_KEY,
+  baseURL: "https://api.perplexity.ai",
+});
+
+const stream = await client.chat.completions.create({
+  model: "sonar-pro",
+  messages: [{ role: "user", content: "Write a story about AI" }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  const content = chunk.choices[0]?.delta?.content;
+  if (content) process.stdout.write(content);
+}
+```
+
+### Rich Metadata Tracking
+
+```javascript
+import { createPerplexityClient } from "@revenium/perplexity";
+
+const client = createPerplexityClient();
+
+const response = await client.createChatCompletion({
+  model: "sonar-pro",
+  messages: [
+    {
+      role: "user",
+      content: "Analyze this quarterly report",
+    },
+  ],
+  usageMetadata: {
+    // User tracking
+    traceId: "conv-28a7e9d4",
+    taskType: "document-analysis",
+    subscriberEmail: "user@example.com",
+    subscriberId: "user-123",
+    subscriberCredentialName: "api-key-1",
+
+    // Business context
+    organizationId: "acme-corp",
+    subscriptionId: "premium-plan",
+    productId: "business-intelligence",
+    agent: "analysis-assistant",
+    responseQualityScore: 0.95,
+  },
+});
+```
+
+---
+
+## 📊 What Gets Tracked
+
+- **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
+- **Streaming Metrics**: Time to first token for streaming responses
+- **Custom Metadata**: Rich business context and user tracking
+
+---
+
+## 🔗 Supported Models
+
+### Chat Models
+
+- **sonar-pro** (Latest and most capable)
+- **sonar-small** (Fast and efficient)
+- **sonar-medium** (Balanced performance)
+
+_Note: Model availability depends on your Perplexity AI account and API access level._
+
+---
+
+## 🛠️ Configuration Options
+
+### Environment Variables
+
+| Variable                     | Required | Description                                                     |
+| ---------------------------- | -------- | --------------------------------------------------------------- |
+| `PERPLEXITY_API_KEY`         | ✅       | Your Perplexity API key                                         |
+| `REVENIUM_METERING_API_KEY`  | ✅       | Your Revenium API key                                           |
+| `PERPLEXITY_BASE_URL`        | ❌       | Custom Perplexity base URL (default: https://api.perplexity.ai) |
+| `REVENIUM_METERING_BASE_URL` | ❌       | Revenium base URL (default: https://api.revenium.io/meter/v2)   |
+| `REVENIUM_LOG_LEVEL`         | ❌       | Log level: DEBUG, INFO, WARNING, ERROR                          |
+
+### Manual Configuration
+
+```javascript
+// Revenium client with custom configuration
+const client = createPerplexityClient(
+  "your-api-key",
+  "https://api.perplexity.ai"
+);
+
+// OpenAI client with custom base URL
+const openaiClient = new OpenAI({
+  apiKey: "your-api-key",
+  baseURL: "https://custom-perplexity-endpoint.com",
+});
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**"Missing API Key" Error**
+
+```bash
+export PERPLEXITY_API_KEY="your-actual-api-key"
+echo $PERPLEXITY_API_KEY  # Verify it's set
+```
+
+**"Requests not being tracked"**
+
+```bash
+export REVENIUM_METERING_API_KEY="your-actual-revenium-key"
+export REVENIUM_LOG_LEVEL="DEBUG"  # Enable debug logging
+```
+
+**Module Import Errors**
+
+```json
+{
+  "type": "module"
+}
+```
+
+### Debug Mode
+
+Enable detailed logging to troubleshoot issues:
+
+```bash
+export REVENIUM_LOG_LEVEL="DEBUG"
+export REVENIUM_VERBOSE_STARTUP="true"
+node your-script.js
+```
+
+This will show:
+
+- Request/response details
+- Token counting information
+- Metering data being sent
+- Error details
+- Middleware activation status
+
+---
+
+## 📚 Examples Repository
+
+Check out our comprehensive examples:
+
+- **Basic Usage**: Simple chat completions
+- **Streaming**: Real-time response streaming
+- **Metadata**: Rich tracking examples
+- **Error Handling**: Robust error management
+- **Advanced Patterns**: Complex use cases
+- **Configuration**: Different setup options
+
+All examples are in the `/examples` and `/playground` directories.
+
+---
+
+## 📋 Requirements
+
+- Node.js 18+
+- Perplexity API key
+- Revenium API key
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🤝 Support
+
+- 📖 [Documentation](https://docs.revenium.io)
+- 💬 [Community Support](https://community.revenium.io)
+- 📧 [Email Support](mailto:support@revenium.io)
+- 🐛 [Report Issues](https://github.com/revenium/revenium-middleware-perplexity-node/issues)
+
+---
+
+**Built with ❤️ by Revenium**