@revenium/perplexity 2.0.2 → 2.0.4

package/README.md

@@ -1,625 +1,271 @@
-# 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](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",
-  },
-});
-```
-
-## 🏗️ 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)
+[![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
+
+## Getting Started
+
+### Quick Start
+
+```bash
+npm install @revenium/perplexity dotenv
+```
+
+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).
+
+### Step-by-Step Guide
+
+The following guide walks you through creating a new project from scratch:
+
+#### Step 1: Create Your Project
+
+```bash
+# Create project directory
+mkdir my-perplexity-project
+cd my-perplexity-project
+
+# Initialize Node.js project
+npm init -y
+```
+
+#### Step 2: Install Dependencies
+
+```bash
+# Install Revenium middleware and Perplexity dependencies
+npm install @revenium/perplexity dotenv
+
+# For TypeScript projects (optional)
+npm install -D typescript tsx @types/node
+```
+
+#### Step 3: Setup Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Then edit .env with your actual API keys
+```
+
+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.
+
+**Replace the placeholder values with your actual keys!**
+
+#### Step 4: Follow the Examples
+
+See [examples/README.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md) for complete examples and setup instructions.
+
+**Cloned from GitHub?** Run examples with:
+
+```bash
+npm install
+npm run example:basic
+npm run example:streaming
+npm run example:chat
+npm run example:metadata
+npm run example:advanced
+npm run example:getting-started
+```
+
+**Browse online:** [`examples/` directory](https://github.com/revenium/revenium-middleware-perplexity-node/tree/HEAD/examples)
+
+---
+
+## 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
+
+For advanced features including:
+
+- **Initialization Options** - Environment variables vs manual configuration
+- **Streaming Responses** - Real-time streaming with usage tracking
+- **Custom Metadata Tracking** - Add business context to your API calls
+
+See the **[Examples Guide](./examples/README.md)** for detailed documentation and working code examples.
+
+### Metadata Fields Reference
+
+The `usageMetadata` parameter supports the following fields for detailed tracking:
+
+| Field                         | Description                                            | Use Case                                                                                                       |
+| ----------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `traceId`                     | Unique identifier for session or conversation tracking | Link multiple API calls together for debugging, user session analytics, or distributed tracing across services |
+| `taskType`                    | Type of AI task being performed                        | Categorize usage by workload (e.g., "search", "research", "qa") for cost analysis and optimization             |
+| `subscriber.id`               | Unique user identifier                                 | Track individual user consumption for billing, rate limiting, or user analytics                                |
+| `subscriber.email`            | User's email address                                   | Associate usage with specific users for reporting and communication                                            |
+| `subscriber.credential`       | Object containing credential information               | Track usage by API keys and credentials                                                                        |
+| `subscriber.credential.name`  | Authentication credential name                         | Track which API key or service account made the request                                                        |
+| `subscriber.credential.value` | Authentication credential value                        | Associate usage with specific credentials for security auditing                                                |
+| `organizationId`              | Organization or company identifier                     | Multi-tenant cost allocation, usage quotas per organization                                                    |
+| `subscriptionId`              | Subscription plan identifier                           | Track usage against subscription limits, identify plan upgrade opportunities                                   |
+| `productId`                   | Your product or feature identifier                     | Attribute AI costs to specific features in your application (e.g., "search-bot", "research-assistant")         |
+| `agent`                       | AI agent or bot identifier                             | Distinguish between multiple AI agents or automation workflows in your system                                  |
+| `responseQualityScore`        | Custom quality rating (0.0-1.0)                        | Track user satisfaction or automated quality metrics for model performance analysis                            |
+
+For complete API documentation and additional details, see the [Revenium API Reference](https://revenium.readme.io/reference/meter_ai_completion).
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Missing API Key" Error
+
+```bash
+# Verify your .env file exists and has the required keys
+cat .env
+
+# Or use .env.example as a template
+cp .env.example .env
+# Then edit .env with your actual keys
+```
+
+#### "Requests not being tracked"
+
+```bash
+# Enable debug logging to see what's happening
+export DEBUG="true"
+
+# Check your .env file has correct values
+cat .env | grep REVENIUM
+
+# Verify initialization is called before making requests
+```
+
+#### 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
+
+**SECURITY WARNING: Never enable DEBUG mode in production!**
+
+Debug mode is intended for local development only. While sensitive fields (PII, credentials) are automatically redacted from debug logs, debug mode should only be enabled in development environments with test data.
+
+Enable debug logging to troubleshoot issues:
+
+```bash
+export DEBUG="true"
+node your-script.js
+```
+
+This will show:
+
+- Initialization details
+- Configuration loading
+- API call information (with PII/credentials redacted)
+- Error details
+
+**Production environments must NEVER set DEBUG=true.**
+
+## 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
+└── dist/
+    ├── cjs/                  # CommonJS build
+    ├── esm/                  # ES Modules build
+    └── types/                # TypeScript definitions
+```
+
+## 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 20+
+- 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**