@revenium/perplexity 1.0.23 → 2.0.1

package/README.md

@@ -1,521 +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 middleware provides seamless integration with Perplexity AI SDK, requiring minimal code changes.
+[![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)
 
-## 🚀 Getting Started
+## 🚀 Features
 
-You have 3 options to start using Revenium middleware for Perplexity AI:
+- ✅ **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
 
-| 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) |
+## 📋 Table of Contents
 
----
-
-## Option 1: Create Project from Scratch
+- [Installation](#-installation)
+- [Three Ways to Use This Middleware](#-three-ways-to-use-this-middleware)
+  - [Option 1: New Project with npm Package](#option-1-new-project-with-npm-package-recommended)
+  - [Option 2: Clone and Use Locally](#option-2-clone-and-use-locally)
+  - [Option 3: Add to Existing Project](#option-3-add-to-existing-project)
+- [Quick Start](#-quick-start)
+- [API Reference](#-api-reference)
+- [Examples](#-examples)
+- [Environment Variables](#-environment-variables)
 
-### 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"
+npm install @revenium/perplexity dotenv
+```
 
-# Revenium Configuration
-REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
-REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
+#### Step 3: Create `.env` file
 
-```
+```env
+# Perplexity API Configuration
+PERPLEXITY_API_KEY=your_perplexity_api_key
 
-### Step 4: Create Your First Test
+# Revenium Metering Configuration
+REVENIUM_METERING_API_KEY=your_revenium_api_key
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+```
 
-Create `test-perplexity.js`:
+#### Step 4: Create `index.js`
 
 ```javascript
-// test-perplexity.js
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
-
-const basicExample = async () => {
-  try {
-    const middleware = new PerplexityReveniumMiddleware();
-    const model = middleware.getGenerativeModel("sonar-pro");
-    const result = await model.createChatCompletion({
-      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);
-  }
-};
+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);
+}
 
-basicExample();
+main().catch(console.error);
 ```
 
-### Step 5: Update package.json
-
-Add test scripts and module type to your `package.json`:
+#### Step 5: Run your project
 
-```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"
-  }
-}
+```bash
+node index.js
 ```
 
-⚠️ **Important**: If you get this error when running tests:
+---
+
+### Option 2: Clone and Use Locally
 
+**Best for:** Development, testing, or contributing to the middleware.
+
+#### Step 1: Clone the repository
+
+```bash
+git clone https://github.com/revenium/revenium-middleware-perplexity-node.git
+cd revenium-middleware-perplexity-node
 ```
-SyntaxError: Cannot use import statement outside a module
+
+#### Step 2: Install dependencies
+
+```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 Perplexity AI SDK
-npm run test-perplexity
+npm run build
 ```
 
-### Step 7: Create Advanced Examples
+#### Step 5: Run examples
+
+**TypeScript Examples:**
 
-Create an examples directory and add these files:
+```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
+```
+
+**JavaScript Playground:**
 
 ```bash
-mkdir examples
+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
 ```
 
-#### Streaming Example
+#### Step 6: Use in your own code
 
-Create `examples/streaming-perplexity.js`:
+After building, you can import from the local build:
 
 ```javascript
-// examples/streaming-perplexity.js
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
-
-const streamingExample = async () => {
-  try {
-    const middleware = new PerplexityReveniumMiddleware();
-    const model = middleware.getGenerativeModel("sonar-pro");
-    const stream = await model.createChatCompletionStream({
-      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);
-  }
-};
+const {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+} = require("./dist/cjs");
 
-streamingExample();
+// Your code here...
 ```
 
-#### METADATA Example
+---
 
-Create `examples/metadata-perplexity.js`:
+### Option 3: Add to Existing Project
 
-```javascript
-// examples/metadata-perplexity.js
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
-
-const metadataExample = async () => {
-  try {
-    const middleware = new PerplexityReveniumMiddleware();
-    const model = middleware.getGenerativeModel("sonar-pro");
-    const result = await model.createChatCompletion({
-      model: "sonar-pro",
-      messages: [{ role: "user", content: "What is the capital of France?" }],
-      usageMetadata: {
-        taskType: "test",
-        subscriberEmail: "test@revenium.ai",
-        subscriberId: "123456",
-        subscriberCredentialName: "apiKey",
-        subscriberCredential: "keyValue",
-        organizationId: "123456",
-        subscriptionId: "123456",
-        productId: "free-trial",
-        agent: "perplexity",
-        responseQualityScore: 100,
-        transactionId: "123456",
-        timeToFirstToken: 1000,
-        requestTime: new Date(),
-        completionStartTime: new Date(),
-        operationType: "CHAT",
-        inputTokenCount: 10,
-        outputTokenCount: 10,
-        reasoningTokenCount: 20,
-        cacheCreationTokenCount: 0,
-        cacheReadTokenCount: 0,
-        totalTokenCount: 40,
-        responseTime: new Date(),
-        requestDuration: 1000,
-        stopReason: "END",
-      },
-    });
-    console.log("[BASIC REQUEST]", result.choices[0].message);
-  } catch (error) {
-    console.error("❌ Perplexity streaming example failed:", error);
-    process.exit(1);
-  }
-};
+**Best for:** Integrating Perplexity with Revenium into an existing Node.js project.
 
-metadataExample();
+#### Step 1: Install the middleware
+
+```bash
+npm install @revenium/perplexity
 ```
 
-### Step 8: Update package.json
+#### Step 2: Add environment variables
 
-```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"
-  }
-}
+Add to your existing `.env` file:
+
+```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 9: Test Advanced Examples
+#### Step 3: Initialize in your application
 
-```bash
-# Test streaming
-npm run test-perplexity-stream
+**For CommonJS projects:**
 
-# Test metadata
-npm run test-perplexity-metadata
+```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;
+}
+```
 
+**For ES Modules projects:**
+
+```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;
+}
+```
+
+**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 Perplexity AI 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
-# Perplexity AI examples
-## Change type to commonjs in package.json
-"type": "commonjs",
-# Then run any of the following
-npm run e-basic        # Basic chat completion
-npm run e-streaming    # Streaming response
-npm run e-enhanced     # Enhanced request
-npm run e-chat-completions     # Chat completions
-npm run e-metadata     # Metadata request
-
-# Playground examples
-# Required build first
-npm run build
-## Change type to module in package.json
-"type": "module",
-# Then run any of the following
-npm run p-basic
-npm run p-streaming
-npm run p-enhanced
-npm run p-metadata
+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:**
+#### `initializePerplexity(config)`
 
-```javascript
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
+Initialize Perplexity with custom configuration.
+
+```typescript
+initializePerplexity({
+  apiKey: "your_perplexity_api_key",
+  baseUrl: "https://api.perplexity.ai", // Optional
+});
 ```
 
-### Step 4. Update Your Code
+### Chat Completions
 
-#### Revenium Client Example
+#### `createChatCompletion(params)`
 
-```javascript
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
+Create a chat completion with automatic metering.
 
-// Initialize (API key from environment variable)
-const middleware = new PerplexityReveniumMiddleware();
-const model = middleware.getGenerativeModel("sonar-pro");
-const result = await model.createChatCompletion({
+```typescript
+const result = await createChatCompletion({
   messages: [
-    {
-      role: "user",
-      content: "Hello world",
-    },
+    { 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("[BASIC EXAMPLE]", result.choices[0].message.content);
+
+console.log(result.content);
+console.log(result.usage);
+console.log(result.transactionId);
 ```
 
----
+**Parameters:**
+
+- `messages` - Array of message objects with `role` and `content`
+- `model` - Perplexity model to use (see [Available Models](#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)
+
+**Returns:**
 
-## 🔧 Advanced Usage
+```typescript
+{
+  content: string;
+  role: string;
+  finishReason: string | null;
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  }
+  model: string;
+  transactionId: string;
+  rawResponse: PerplexityResponse;
+}
+```
 
-### Streaming Responses
+#### `createStreamingChatCompletion(params)`
 
-#### Revenium Client Streaming
+Create a streaming chat completion.
 
-```javascript
-const stream = await model.createChatCompletionStream({
-  messages: [
-    {
-      role: "user",
-      content: "Hello world",
-    },
-  ],
+```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) {
-  process.stdout.write(chunk.choices[0]?.delta?.content || "");
+
+for await (const chunk of result.stream) {
+  const content = chunk.choices[0]?.delta?.content || "";
+  process.stdout.write(content);
 }
 ```
 
-## 📊 What Gets Tracked
+**Returns:**
 
-- **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
-
----
+```typescript
+{
+  stream: AsyncGenerator<PerplexityStreamChunk>;
+  transactionId: string;
+  model: string;
+}
+```
 
-## 🔗 Supported Models
+### Available Models
 
-### Chat Models
+```typescript
+import { PERPLEXITY_MODELS } from "@revenium/perplexity";
 
-- **sonar-pro** (Latest and most capable)
-- **sonar-small** (Fast and efficient)
-- **sonar-medium** (Balanced performance)
+// Online Models (with internet access)
+PERPLEXITY_MODELS.SONAR; // "sonar"
+PERPLEXITY_MODELS.SONAR_PRO; // "sonar-pro"
+PERPLEXITY_MODELS.SONAR_REASONING; // "sonar-reasoning"
 
-_Note: Model availability depends on your Perplexity AI account and API access level._
+// 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"
+```
 
----
+### Utility Functions
 
-## 🛠️ Configuration Options
+#### `disableRevenium()` / `enableRevenium()`
 
-### Environment Variables
+Temporarily disable or enable Revenium metering.
 
-| 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) |
+```typescript
+import { disableRevenium, enableRevenium } from "@revenium/perplexity";
 
----
+disableRevenium(); // Stop sending metering data
+// ... make API calls ...
+enableRevenium(); // Resume sending metering data
+```
 
-## 🚨 Troubleshooting
+#### `generateTransactionId()`
 
-### Common Issues
+Generate a unique transaction ID.
 
-**"Missing API Key" Error**
+```typescript
+import { generateTransactionId } from "@revenium/perplexity";
 
-```bash
-export PERPLEXITY_API_KEY="your-actual-api-key"
-echo $PERPLEXITY_API_KEY  # Verify it's set
+const txnId = generateTransactionId();
 ```
 
-**"Requests not being tracked"**
+## 📖 Examples
 
-```bash
-export REVENIUM_METERING_API_KEY="your-actual-revenium-key"
+### Basic Chat Completion
+
+```typescript
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+} from "@revenium/perplexity";
+
+initializeReveniumFromEnv();
+initializePerplexityFromEnv();
+
+const result = await createChatCompletion({
+  messages: [{ role: "user", content: "What is the capital of France?" }],
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
+
+console.log(result.content);
 ```
 
-**Module Import Errors**
+### Streaming Response
 
-```json
-{
-  "type": "module"
+```typescript
+const result = await createStreamingChatCompletion({
+  messages: [{ role: "user", content: "Write a short poem about AI" }],
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
+
+for await (const chunk of result.stream) {
+  const content = chunk.choices[0]?.delta?.content || "";
+  process.stdout.write(content);
 }
 ```
 
-```json
-{
-  "type": "commonjs"
-}
+### Multi-turn Conversation
+
+```typescript
+const messages = [
+  { role: "system", content: "You are a helpful assistant." },
+  { role: "user", content: "What is the capital of France?" },
+];
+
+const response1 = await createChatCompletion({
+  messages,
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
+
+messages.push({ role: "assistant", content: response1.content });
+messages.push({ role: "user", content: "What is its population?" });
+
+const response2 = await createChatCompletion({
+  messages,
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
 ```
 
-This will show:
+### Custom Metadata
 
-- Request/response details
-- Token counting information
-- Metering data being sent
-- Error details
-- Middleware activation status
+```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",
+  },
+});
+```
 
----
+## 🏗️ Project Structure
 
-## 📚 Examples Repository
+```
+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
+```
 
-Check out our comprehensive examples:
+## 🧪 Running 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
+### TypeScript Examples
 
-All examples are in the `/examples` and `/playground` directories.
+```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
+```
 
----
+### JavaScript Playground
 
-## 📋 Requirements
+```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
+```
 
-- Node.js 18+
-- Perplexity API key
-- Revenium API key
+## 🔒 Environment Variables
 
----
+| 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`) |
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+ISC
 
----
+## 🤝 Contributing
 
-## 🤝 Support
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-- 📖 [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)
+## 📞 Support
 
----
+For issues and questions:
+
+- 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)