@revenium/perplexity 2.0.3 → 2.0.5

package/README.md

@@ -3,827 +3,251 @@
 A lightweight, production-ready middleware that adds **Revenium metering and tracking** to Perplexity AI API calls.
 
 [![npm version](https://img.shields.io/npm/v/@revenium/perplexity.svg)](https://www.npmjs.com/package/@revenium/perplexity)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green)](https://nodejs.org/)
+[![Documentation](https://img.shields.io/badge/docs-revenium.io-blue)](https://docs.revenium.io)
+[![Website](https://img.shields.io/badge/website-revenium.ai-blue)](https://www.revenium.ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- ✅ **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
+- **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
 
-## Package Migration
+## Getting Started
 
-This package has been renamed from `revenium-middleware-perplexity-node` to `@revenium/perplexity` for better organization and simpler naming.
-
-### Migration Steps
-
-If you're upgrading from the old package:
-
-```bash
-# Uninstall the old package
-npm uninstall revenium-middleware-perplexity-node
-
-# Install the new package
-npm install @revenium/perplexity
-```
-
-**Update your imports:**
-
-```typescript
-// Old import
-import "revenium-middleware-perplexity-node";
-
-// New import
-import "@revenium/perplexity";
-```
-
-All functionality remains exactly the same - only the package name has changed.
-
-## Table of Contents
-
-- [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)
-
-## Installation
+### Quick Start
 
 ```bash
-npm install @revenium/perplexity
+npm install @revenium/perplexity dotenv
 ```
 
-## Three Ways to Use This Middleware
+For complete setup instructions, TypeScript patterns, and usage examples, see [examples/README.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md).
 
-### Option 1: New Project with npm Package (Recommended)
+### Step-by-Step Guide
 
-**Best for:** Starting a new project or adding Perplexity with Revenium to an existing project.
+The following guide walks you through creating a new project from scratch:
 
-#### Step 1: Create a new project
+#### Step 1: Create Your Project
 
 ```bash
+# Create project directory
 mkdir my-perplexity-project
 cd my-perplexity-project
+
+# Initialize npm project
 npm init -y
 ```
 
-#### Step 2: Install the middleware
+#### Step 2: Install Dependencies
 
 ```bash
+# Install Revenium middleware and Perplexity dependencies
 npm install @revenium/perplexity dotenv
-```
-
-#### Step 3: Create `.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 4: Create `index.js`
-
-```javascript
-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);
-}
-
-main().catch(console.error);
-```
-
-#### Step 5: Run your project
-
-```bash
-node index.js
+# For TypeScript projects (optional)
+npm install -D typescript tsx @types/node
 ```
 
----
-
-### 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
-```
+#### Step 3: Setup Environment Variables
 
-#### Step 2: Install dependencies
+Create a `.env` file in your project root.
 
 ```bash
-npm install
-```
-
-#### Step 3: Create `.env` file
-
-```env
-# Perplexity API Configuration
-PERPLEXITY_API_KEY=your_perplexity_api_key
+# Copy the example file
+cp .env.example .env
 
-# Revenium Metering Configuration
-REVENIUM_METERING_API_KEY=your_revenium_api_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+# Then edit .env with your actual API keys
 ```
 
-#### Step 4: Build the project
-
-```bash
-npm run build
-```
+See [`.env.example`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/.env.example) for the complete list of environment variables and where to get your API keys.
 
-#### Step 5: Run examples
+**Replace the placeholder values with your actual keys!**
 
-**TypeScript Examples:**
+#### Step 4: Follow the Examples
 
-```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
-```
+**For complete examples and usage patterns, see [examples/README.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md) for complete examples and setup instructions.
 
-**JavaScript Playground:**
+**Cloned from GitHub?** Run examples with:
 
 ```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
-```
-
-#### Step 6: Use in your own code
-
-After building, you can import from the local build:
-
-```javascript
-const {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-} = require("./dist/cjs");
-
-// Your code here...
-```
-
----
-
-### Option 3: Add to Existing Project
-
-**Best for:** Integrating Perplexity with Revenium into an existing Node.js project.
-
-#### Step 1: Install the middleware
-
-```bash
-npm install @revenium/perplexity
-```
-
-#### Step 2: Add environment variables
-
-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 3: Initialize in your application
-
-**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;
-}
-```
-
-**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;
-}
+npm install
+npm run example:getting-started  # Start here!
+npm run example:basic
+npm run example:stream
+npm run example:metadata
+npm run example:advanced
 ```
 
 ---
 
-## Quick Start
-
-### 1. Set up environment variables
-
-Create a `.env` file in your project root:
-
-```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
-```
-
-### 2. Initialize and use
-
-```typescript
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-  PERPLEXITY_MODELS,
-} from "@revenium/perplexity";
-
-// 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(result.content);
-// Output: "The capital of France is Paris."
-```
-
-## API Reference
-
-### Configuration
-
-#### `initializeReveniumFromEnv()`
-
-Initialize Revenium configuration from environment variables.
-
-```typescript
-const config = initializeReveniumFromEnv();
-```
-
-#### `initializePerplexityFromEnv()`
-
-Initialize Perplexity configuration from environment variables.
-
-```typescript
-const config = initializePerplexityFromEnv();
-```
-
-#### `initializeRevenium(config)`
-
-Initialize Revenium with custom configuration.
-
-```typescript
-initializeRevenium({
-  meteringApiKey: "your_api_key",
-  meteringBaseUrl: "https://api.revenium.io/meter",
-  teamId: "your_team_id", // Optional
-});
-```
-
-#### `initializePerplexity(config)`
-
-Initialize Perplexity with custom configuration.
-
-```typescript
-initializePerplexity({
-  apiKey: "your_perplexity_api_key",
-  baseUrl: "https://api.perplexity.ai", // Optional
-});
-```
-
-### Chat Completions
-
-#### `createChatCompletion(params)`
-
-Create a chat completion with automatic metering.
-
-```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(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](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)
-
-**Returns:**
-
-```typescript
-{
-  content: string;
-  role: string;
-  finishReason: string | null;
-  usage: {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-  }
-  model: string;
-  transactionId: string;
-  rawResponse: PerplexityResponse;
-}
-```
+## What Gets Tracked
 
-#### `createStreamingChatCompletion(params)`
+The middleware automatically captures comprehensive usage data:
 
-Create a streaming chat completion.
+### **Usage Metrics**
 
-```typescript
-const result = await createStreamingChatCompletion({
-  messages: [{ role: "user", content: "Count from 1 to 5" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-});
+- **Token Counts** - Input tokens, output tokens, total tokens
+- **Model Information** - Model name, provider (Perplexity)
+- **Request Timing** - Request duration, response time
+- **Cost Calculation** - Estimated costs based on current pricing
 
-for await (const chunk of result.stream) {
-  const content = chunk.choices[0]?.delta?.content || "";
-  process.stdout.write(content);
-}
-```
+### **Business Context (Optional)**
 
-**Returns:**
+- **User Tracking** - Subscriber ID, email, credentials
+- **Organization Data** - Organization ID, subscription ID, product ID
+- **Task Classification** - Task type, agent identifier, trace ID
+- **Quality Metrics** - Response quality scores, task identifiers
 
-```typescript
-{
-  stream: AsyncGenerator<PerplexityStreamChunk>;
-  transactionId: string;
-  model: string;
-}
-```
+### **Technical Details**
 
-### Available Models
+- **API Endpoints** - Chat completions
+- **Request Types** - Streaming vs non-streaming
+- **Error Tracking** - Failed requests, error types, retry attempts
+- **Environment Info** - Development vs production usage
 
-```typescript
-import { PERPLEXITY_MODELS } from "@revenium/perplexity";
+## API Overview
 
-// Online Models (with internet access)
-PERPLEXITY_MODELS.SONAR; // "sonar"
-PERPLEXITY_MODELS.SONAR_PRO; // "sonar-pro"
-PERPLEXITY_MODELS.SONAR_REASONING; // "sonar-reasoning"
+The middleware provides a Go-aligned API with the following main functions:
 
-// 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"
-```
+- **`Initialize(config?)`** - Initialize the middleware (from environment or explicit config)
+- **`GetClient()`** - Get the global Revenium client instance
+- **`Configure(config)`** - Alias for `Initialize()` for programmatic configuration
+- **`IsInitialized()`** - Check if the middleware is initialized
+- **`Reset()`** - Reset the global client (useful for testing)
 
-### Utility Functions
+**For complete API documentation and usage examples, see [`examples/README.md`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md).**
 
-#### `disableRevenium()` / `enableRevenium()`
+## Metadata Fields
 
-Temporarily disable or enable Revenium metering.
+The middleware supports the following optional metadata fields for tracking:
 
-```typescript
-import { disableRevenium, enableRevenium } from "@revenium/perplexity";
+| Field                   | Type   | Description                                                |
+| ----------------------- | ------ | ---------------------------------------------------------- |
+| `traceId`               | string | Unique identifier for session or conversation tracking     |
+| `taskType`              | string | Type of AI task being performed (e.g., "chat", "research") |
+| `agent`                 | string | AI agent or bot identifier                                 |
+| `organizationId`        | string | Organization or company identifier                         |
+| `productId`             | string | Your product or feature identifier                         |
+| `subscriptionId`        | string | Subscription plan identifier                               |
+| `responseQualityScore`  | number | Custom quality rating (0.0-1.0)                            |
+| `subscriber.id`         | string | Unique user identifier                                     |
+| `subscriber.email`      | string | User email address                                         |
+| `subscriber.credential` | object | Authentication credential (`name` and `value` fields)      |
 
-disableRevenium(); // Stop sending metering data
-// ... make API calls ...
-enableRevenium(); // Resume sending metering data
-```
+**All metadata fields are optional.** For complete metadata documentation and usage examples, see:
 
-#### `generateTransactionId()`
+- [`examples/README.md`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md) - All usage examples
+- [Revenium API Reference](https://revenium.readme.io/reference/meter_ai_completion) - Complete API documentation
 
-Generate a unique transaction ID.
+## Configuration Options
 
-```typescript
-import { generateTransactionId } from "@revenium/perplexity";
+### Environment Variables
 
-const txnId = generateTransactionId();
-```
+For a complete list of all available environment variables with examples, see [`.env.example`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/.env.example).
 
 ## Examples
 
-### Basic Chat Completion
+The package includes comprehensive examples in the [`examples/`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/) directory.
 
-```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);
-```
-
-### Streaming Response
-
-```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);
-}
-```
-
-### 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,
-});
-```
+## Project Structure
 
-### Custom Metadata
-
-```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",
-  },
-});
 ```
-
-## What Gets Tracked
-
-The middleware automatically captures:
-
-- **Token Usage**: Prompt and completion tokens for accurate billing
-- **Request Duration**: Total time for each API call
-- **Model Information**: Which Perplexity model was used
-- **Operation Type**: Chat completion, streaming, etc.
-- **Error Tracking**: Failed requests and error details
-- **Streaming Metrics**: Time to first token for streaming responses
-- **Custom Metadata**: Business context you provide
-
-## Advanced Usage
-
-### Streaming Responses
-
-```typescript
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createStreamingChatCompletion,
-  PERPLEXITY_MODELS,
-} from "@revenium/perplexity";
-
-initializeReveniumFromEnv();
-initializePerplexityFromEnv();
-
-const result = await createStreamingChatCompletion({
-  messages: [{ role: "user", content: "Count from 1 to 5" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-  usageMetadata: {
-    subscriber: { id: "user-123" },
-    taskType: "counting-demo",
-  },
-});
-
-for await (const chunk of result.stream) {
-  const content = chunk.choices[0]?.delta?.content || "";
-  process.stdout.write(content);
-}
+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
+├── .env.example              # Example environment variables
+├── package.json
+├── tsconfig.json
+└── README.md
 ```
 
-### Custom Metadata Tracking
-
-Add business context to your AI usage:
-
-```typescript
-const customMetadata = {
-  subscriber: {
-    id: "user-789",
-    email: "user@company.com",
-    credential: {
-      name: "premium-user",
-      value: "tier-1",
-    },
-  },
-  organizationId: "org-456",
-  productId: "premium-plan",
-  taskType: "RESEARCH",
-  agent: "ResearchBot",
-  traceId: "session-123",
-  responseQualityScore: 9.2,
-};
-
-const result = await createChatCompletion({
-  messages: [{ role: "user", content: "Research AI trends" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-  usageMetadata: customMetadata,
-});
-```
+## How It Works
 
-### Usage Metadata Interface
-
-All metadata fields are optional:
-
-```typescript
-interface UsageMetadata {
-  traceId?: string; // Session or conversation ID
-  taskType?: string; // Type of AI task
-  organizationId?: string; // Organization/company ID
-  subscriptionId?: string; // Billing plan ID
-  productId?: string; // Your product/feature ID
-  agent?: string; // AI agent identifier
-  responseQualityScore?: number; // Quality score (0-1)
-  subscriber?: {
-    id?: string; // User ID from your system
-    email?: string; // User's email address
-    credential?: {
-      name?: string; // Credential name
-      value?: string; // Credential value
-    };
-  };
-}
-```
+1. **Initialize**: Call `Initialize()` to set up the middleware with your configuration
+2. **Get Client**: Call `GetClient()` to get a wrapped Perplexity client instance
+3. **Make Requests**: Use the client normally - all requests are automatically tracked
+4. **Async Tracking**: Usage data is sent to Revenium in the background (fire-and-forget)
+5. **Transparent Response**: Original Perplexity responses are returned unchanged
 
-## Configuration Options
+The middleware never blocks your application - if Revenium tracking fails, your Perplexity requests continue normally.
 
-### Environment Variables
+**Supported APIs:**
 
-| Variable                     | Required | Default                         | Description                       |
-| ---------------------------- | -------- | ------------------------------- | --------------------------------- |
-| `PERPLEXITY_API_KEY`         | Yes      | -                               | Your Perplexity API key           |
-| `REVENIUM_METERING_API_KEY`  | Yes      | -                               | Your Revenium API key             |
-| `REVENIUM_METERING_BASE_URL` | Yes      | -                               | Revenium metering API base URL    |
-| `PERPLEXITY_API_BASE_URL`    | No       | `https://api.perplexity.ai`     | Perplexity API base URL           |
-| `DEBUG`                      | No       | `false`                         | Enable debug logging              |
-
-### Manual Configuration
-
-```typescript
-import {
-  initializeRevenium,
-  initializePerplexity,
-  createChatCompletion,
-} from "@revenium/perplexity";
-
-// Manual configuration
-initializeRevenium({
-  meteringApiKey: "hak_your_revenium_key",
-  meteringBaseUrl: "https://api.revenium.io/meter/v2",
-});
-
-initializePerplexity({
-  apiKey: "pplx_your_perplexity_key",
-  baseUrl: "https://api.perplexity.ai",
-});
-```
+- Chat Completions API (`client.chat().completions().create()`)
+- Streaming API (`client.chat().completions().createStreaming()`)
 
 ## Troubleshooting
 
 ### Common Issues
 
-#### "Missing API Key" Error
-
-```bash
-# Make sure you've set the API keys
-export PERPLEXITY_API_KEY="pplx_your_actual_api_key"
-export REVENIUM_METERING_API_KEY="hak_your_actual_revenium_key"
-
-# Verify they're set
-echo $PERPLEXITY_API_KEY
-echo $REVENIUM_METERING_API_KEY
-```
-
-#### "Requests not being tracked"
-
-```bash
-# Verify Revenium configuration
-export REVENIUM_METERING_API_KEY="hak_your_actual_revenium_key"
-export REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter/v2"
-
-# Enable debug logging to see what's happening
-export DEBUG="true"
-```
+**No tracking data appears:**
 
-#### TypeScript errors with usageMetadata
+1. Verify environment variables are set correctly in `.env`
+2. Enable debug logging by setting `REVENIUM_DEBUG=true` in `.env`
+3. Check console for `[Revenium]` log messages
+4. Verify your `REVENIUM_METERING_API_KEY` is valid
 
-- Ensure you're importing from `@revenium/perplexity`
-- Check that your TypeScript version is 5.0+
-- Verify you're using the latest version: `npm update @revenium/perplexity`
+**Client not initialized error:**
 
-#### Build/Import Errors
+- Make sure you call `Initialize()` before `GetClient()`
+- Check that your `.env` file is in the project root
+- Verify `REVENIUM_METERING_API_KEY` is set
 
-```bash
-# Clean and reinstall
-rm -rf node_modules
-npm install
+**Perplexity API errors:**
 
-# For TypeScript projects
-npm run build
-```
+- Verify `PERPLEXITY_API_KEY` is set correctly
+- Check that your API key starts with `pplx-`
+- Ensure you're using a valid model name
 
 ### Debug Mode
 
-Enable debug logging to troubleshoot issues:
+Enable detailed logging by adding to your `.env`:
 
-```bash
-export DEBUG="true"
-node your-script.js
+```env
+REVENIUM_DEBUG=true
 ```
 
-This will show:
+### Getting Help
 
-- Initialization details
-- Configuration loading
-- API call information
-- Error details
+If issues persist:
 
-## Project Structure
+1. Enable debug logging (`REVENIUM_DEBUG=true`)
+2. Check the [`examples/`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/) directory for working examples
+3. Review [`examples/README.md`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md) for detailed setup instructions
+4. Contact support@revenium.io with debug logs
 
-```
-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
-```
+## Supported Models
 
-## Running Examples
+This middleware works with any Perplexity model. For the complete model list, see the [Perplexity Models Documentation](https://docs.perplexity.ai/getting-started/models).
 
-### TypeScript Examples
+### API Support Matrix
 
-```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
-```
+The following table shows what has been tested and verified with working examples:
 
-### JavaScript Playground
+| Feature               | Chat Completions | Streaming |
+| --------------------- | ---------------- | --------- |
+| **Basic Usage**       | Yes              | Yes       |
+| **Metadata Tracking** | Yes              | Yes       |
+| **Token Counting**    | Yes              | Yes       |
 
-```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
-```
+**Note:** "Yes" = Tested with working examples in [`examples/`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/) directory
 
-## How It Works
-
-1. **Initialization**: When you call `initializePerplexityFromEnv()` and `initializeReveniumFromEnv()`, the middleware sets up configurations
-2. **Request Wrapping**: All Perplexity API calls go through the middleware wrapper
-3. **Usage Extraction**: Token counts, model info, and timing data are captured from responses
-4. **Async Tracking**: Usage data is sent to Revenium in the background (fire-and-forget)
-5. **Transparent Response**: Original Perplexity responses are returned unchanged
-
-The middleware never blocks your application - if Revenium tracking fails, your Perplexity requests continue normally.
 
 ## Requirements
 
-- Node.js 16+
+- Node.js 20+
 - TypeScript 5.0+ (for TypeScript projects)
 - Revenium API key
 - Perplexity API key