@revenium/perplexity 2.0.1 → 2.0.3

package/README.md

@@ -1,625 +1,866 @@
-# Revenium Middleware for Perplexity
-
-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: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
-
-## 🚀 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
-
-## 📋 Table of Contents
-
-- [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)
-
-## 📦 Installation
-
-```bash
-npm install @revenium/perplexity
-```
-
-## 🎯 Three Ways to Use This Middleware
-
-### Option 1: New Project with npm Package (Recommended)
-
-**Best for:** Starting a new project or adding Perplexity with Revenium to an existing project.
-
-#### Step 1: Create a new project
-
-```bash
-mkdir my-perplexity-project
-cd my-perplexity-project
-npm init -y
-```
-
-#### Step 2: Install the middleware
-
-```bash
-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
-```
-
----
-
-### 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 2: Install dependencies
-
-```bash
-npm install
-```
-
-#### 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: Build the project
-
-```bash
-npm run build
-```
-
-#### Step 5: Run examples
-
-**TypeScript 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
-```
-
-**JavaScript Playground:**
-
-```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;
-}
-```
-
----
-
-## 🔧 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](#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;
-}
-```
-
-#### `createStreamingChatCompletion(params)`
-
-Create a streaming chat completion.
-
-```typescript
-const result = await createStreamingChatCompletion({
-  messages: [{ role: "user", content: "Count from 1 to 5" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-});
-
-for await (const chunk of result.stream) {
-  const content = chunk.choices[0]?.delta?.content || "";
-  process.stdout.write(content);
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  stream: AsyncGenerator<PerplexityStreamChunk>;
-  transactionId: string;
-  model: string;
-}
-```
-
-### Available Models
-
-```typescript
-import { PERPLEXITY_MODELS } from "@revenium/perplexity";
-
-// Online Models (with internet access)
-PERPLEXITY_MODELS.SONAR; // "sonar"
-PERPLEXITY_MODELS.SONAR_PRO; // "sonar-pro"
-PERPLEXITY_MODELS.SONAR_REASONING; // "sonar-reasoning"
-
-// 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
-
-#### `disableRevenium()` / `enableRevenium()`
-
-Temporarily disable or enable Revenium metering.
-
-```typescript
-import { disableRevenium, enableRevenium } from "@revenium/perplexity";
-
-disableRevenium(); // Stop sending metering data
-// ... make API calls ...
-enableRevenium(); // Resume sending metering data
-```
-
-#### `generateTransactionId()`
-
-Generate a unique transaction ID.
-
-```typescript
-import { generateTransactionId } from "@revenium/perplexity";
-
-const txnId = generateTransactionId();
-```
-
-## 📖 Examples
-
-### 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);
-```
-
-### 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,
-});
-```
-
-### 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",
-  },
-});
-```
-
-## 🏗️ Project Structure
-
-```
-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
-```
-
-## 🧪 Running Examples
-
-### TypeScript 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
-```
-
-### JavaScript Playground
-
-```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
-
-| 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
-
-ISC
-
-## 🤝 Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## 📞 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
-
-- [Perplexity AI Documentation](https://docs.perplexity.ai)
-- [Revenium Platform](https://revenium.io)
-- [npm Package](https://www.npmjs.com/package/@revenium/perplexity)
+# Revenium Middleware for Perplexity
+
+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)
+
+## 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
+
+## Package Migration
+
+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
+
+```bash
+npm install @revenium/perplexity
+```
+
+## Three Ways to Use This Middleware
+
+### Option 1: New Project with npm Package (Recommended)
+
+**Best for:** Starting a new project or adding Perplexity with Revenium to an existing project.
+
+#### Step 1: Create a new project
+
+```bash
+mkdir my-perplexity-project
+cd my-perplexity-project
+npm init -y
+```
+
+#### Step 2: Install the middleware
+
+```bash
+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
+```
+
+---
+
+### 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 2: Install dependencies
+
+```bash
+npm install
+```
+
+#### 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: Build the project
+
+```bash
+npm run build
+```
+
+#### Step 5: Run examples
+
+**TypeScript 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
+```
+
+**JavaScript Playground:**
+
+```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;
+}
+```
+
+---
+
+## 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;
+}
+```
+
+#### `createStreamingChatCompletion(params)`
+
+Create a streaming chat completion.
+
+```typescript
+const result = await createStreamingChatCompletion({
+  messages: [{ role: "user", content: "Count from 1 to 5" }],
+  model: PERPLEXITY_MODELS.SONAR_PRO,
+});
+
+for await (const chunk of result.stream) {
+  const content = chunk.choices[0]?.delta?.content || "";
+  process.stdout.write(content);
+}
+```
+
+**Returns:**
+
+```typescript
+{
+  stream: AsyncGenerator<PerplexityStreamChunk>;
+  transactionId: string;
+  model: string;
+}
+```
+
+### Available Models
+
+```typescript
+import { PERPLEXITY_MODELS } from "@revenium/perplexity";
+
+// Online Models (with internet access)
+PERPLEXITY_MODELS.SONAR; // "sonar"
+PERPLEXITY_MODELS.SONAR_PRO; // "sonar-pro"
+PERPLEXITY_MODELS.SONAR_REASONING; // "sonar-reasoning"
+
+// 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
+
+#### `disableRevenium()` / `enableRevenium()`
+
+Temporarily disable or enable Revenium metering.
+
+```typescript
+import { disableRevenium, enableRevenium } from "@revenium/perplexity";
+
+disableRevenium(); // Stop sending metering data
+// ... make API calls ...
+enableRevenium(); // Resume sending metering data
+```
+
+#### `generateTransactionId()`
+
+Generate a unique transaction ID.
+
+```typescript
+import { generateTransactionId } from "@revenium/perplexity";
+
+const txnId = generateTransactionId();
+```
+
+## Examples
+
+### 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);
+```
+
+### 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,
+});
+```
+
+### 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);
+}
+```
+
+### 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,
+});
+```
+
+### 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
+    };
+  };
+}
+```
+
+## Configuration Options
+
+### Environment Variables
+
+| 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",
+});
+```
+
+## 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"
+```
+
+#### TypeScript errors with usageMetadata
+
+- 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`
+
+#### Build/Import Errors
+
+```bash
+# Clean and reinstall
+rm -rf node_modules
+npm install
+
+# For TypeScript projects
+npm run build
+```
+
+### Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```bash
+export DEBUG="true"
+node your-script.js
+```
+
+This will show:
+
+- Initialization details
+- Configuration loading
+- API call information
+- Error details
+
+## Project Structure
+
+```
+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
+```
+
+## Running Examples
+
+### TypeScript 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
+```
+
+### JavaScript Playground
+
+```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
+```
+
+## 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+
+- TypeScript 5.0+ (for TypeScript projects)
+- Revenium API key
+- Perplexity API key
+
+## Documentation
+
+For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/CONTRIBUTING.md)
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/CODE_OF_CONDUCT.md)
+
+## Security
+
+See [SECURITY.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/SECURITY.md)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/LICENSE) file for details.
+
+## Support
+
+For issues, feature requests, or contributions:
+
+- **GitHub Repository**: [revenium/revenium-middleware-perplexity-node](https://github.com/revenium/revenium-middleware-perplexity-node)
+- **Issues**: [Report bugs or request features](https://github.com/revenium/revenium-middleware-perplexity-node/issues)
+- **Documentation**: [docs.revenium.io](https://docs.revenium.io)
+- **Contact**: Reach out to the Revenium team for additional support
+
+## Development
+
+For development and testing instructions, see [DEVELOPMENT.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/DEVELOPMENT.md).
+
+---
+
+**Built by Revenium**