@revenium/perplexity 2.0.7 → 2.0.8

package/README.md

@@ -1,376 +1,408 @@
-# 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
-```
-
-**Note:** The `dotenv` package is optional. The middleware automatically loads `.env` files via `Initialize()`.
-
-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 npm project
-npm init -y
-```
-
-#### Step 2: Install Dependencies
-
-```bash
-# Install Revenium middleware
-npm install @revenium/perplexity
-
-# For TypeScript projects (optional)
-npm install -D typescript tsx @types/node
-```
-
-#### Step 3: Setup Environment Variables
-
-Create a `.env` file in your project root with your API keys:
-
-```bash
-# .env
-PERPLEXITY_API_KEY=pplx_your_perplexity_api_key
-REVENIUM_METERING_API_KEY=hak_your_revenium_api_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.ai  # Optional, defaults to https://api.revenium.ai
-REVENIUM_DEBUG=false  # Optional, enables debug logging
-```
-
-**Replace the placeholder values with your actual keys!**
-
-For a complete list of all available environment variables, see the [Configuration Options](#configuration-options) section below.
-
-#### Step 4: Implement in Your Code
-
-Use the examples as reference for implementing the middleware in your project. See [examples/README.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md) for complete implementation examples including:
-
-- How to initialize the middleware with your configuration
-- Making API calls with automatic metering
-- Handling streaming responses
-- Adding custom metadata to track business context
-
----
-
-## Running Examples from Cloned Repository
-
-If you've cloned this repository from GitHub and want to **run the included examples** to see how the middleware works (without modifying the middleware source code):
-
-### Setup
-
-```bash
-# Install dependencies
-npm install
-
-# Build the package
-npm run build
-
-# Configure environment variables
-cp .env.example .env
-# Edit .env with your API keys
-```
-
-### Run Examples
-
-**Using npm scripts:**
-
-```bash
-npm run example:getting-started  # Getting started example
-npm run example:basic            # Basic chat completion
-npm run example:stream           # Streaming response
-npm run example:metadata         # Custom metadata
-npm run example:advanced         # Advanced features
-```
-
-**Or use npx tsx directly:**
-
-```bash
-npx tsx examples/getting_started.ts
-npx tsx examples/basic.ts
-npx tsx examples/stream.ts
-npx tsx examples/metadata.ts
-npx tsx examples/advanced.ts
-```
-
-For detailed information about each example, see [examples/README.md](examples/README.md).
-
-### Want to Modify the Middleware Code?
-
-If you're planning to modify the examples or experiment with the code, the setup above is sufficient. However, if you want to **modify the middleware source code itself** (files in `src/`), you'll need to understand the development workflow.
-
-See [Local Development and Contributing](#local-development-and-contributing) below for the complete development guide.
-
----
-
-## Local Development and Contributing
-
-**Are you planning to modify the middleware source code?** (Not just run examples)
-
-If you want to:
-
-- Fix bugs in the middleware
-- Add new features to @revenium/perplexity
-- Contribute to the project
-- Test changes to the middleware before publishing
-
-Then follow the complete development workflow in [DEVELOPMENT.md](DEVELOPMENT.md), which covers:
-
-### What DEVELOPMENT.md Includes:
-
-- **Development Workflow** - Step-by-step process for making changes
-- **Build System** - Understanding ESM, CJS, and TypeScript compilation
-- **Testing Local Changes** - How to test your modifications properly
-- **When to Rebuild** - Understanding when `npm run build` is needed
-- **Publishing Checklist** - Steps to publish new versions
-- **Architecture Notes** - Understanding the codebase structure
-- **Contributing Guidelines** - How to contribute to the project
-
-### Key Difference:
-
-- **Running Examples** (above): You can modify example files (`.ts` in `examples/`) and run them directly with `npx tsx` - no rebuild needed
-- **Modifying Middleware** (DEVELOPMENT.md): If you modify source files (`.ts` in `src/`), you must run `npm run build` before testing
-
-**Quick Start for Contributors:**
-
-```bash
-# 1. Make changes to source code
-vim src/index.ts
-
-# 2. Rebuild the package
-npm run build
-
-# 3. Test your changes
-npm run example:basic
-
-# 4. See DEVELOPMENT.md for complete workflow
-```
-
----
-
-## What Gets Tracked
-
-The middleware automatically captures comprehensive usage data:
-
-### **Usage Metrics**
-
-- **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
-
-### **Business Context (Optional)**
-
-- **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
-
-### **Technical Details**
-
-- **API Endpoints** - Chat completions
-- **Request Types** - Streaming vs non-streaming
-- **Error Tracking** - Failed requests, error types, retry attempts
-- **Environment Info** - Development vs production usage
-
-## API Overview
-
-- **`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)
-
-**For complete API documentation and usage examples, see [`examples/README.md`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md).**
-
-## Metadata Fields
-
-The middleware supports the following optional metadata fields for tracking:
-
-| 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)      |
-
-**All metadata fields are optional.** For complete metadata documentation and usage examples, see:
-
-- [`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
-
-## Configuration Options
-
-### Environment Variables
-
-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
-
-The package includes comprehensive examples in the [`examples/`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/) directory.
-
-## Project Structure
-
-```
-revenium-middleware-perplexity-node/
-├── src/
-│   ├── core/
-│   │   ├── client/          # Client manager (Initialize/GetClient)
-│   │   ├── config/           # Configuration management
-│   │   ├── middleware/       # Perplexity API middleware wrapper
-│   │   ├── providers/        # Provider detection
-│   │   └── tracking/         # Metering and tracking
-│   ├── types/                # TypeScript type definitions
-│   ├── utils/                # Utility functions
-│   └── index.ts              # Main entry point
-├── examples/                 # TypeScript examples
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-## How It Works
-
-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
-
-The middleware never blocks your application - if Revenium tracking fails, your Perplexity requests continue normally.
-
-**Supported APIs:**
-
-- Chat Completions API (`client.chat().completions().create()`)
-- Streaming API (`client.chat().completions().createStreaming()`)
-
-## Troubleshooting
-
-### Common Issues
-
-**No tracking data appears:**
-
-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
-
-**Client not initialized error:**
-
-- Make sure you call `Initialize()` before `GetClient()`
-- Check that your `.env` file is in the project root
-- Verify `REVENIUM_METERING_API_KEY` is set
-
-**Perplexity API errors:**
-
-- 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 detailed logging by adding to your `.env`:
-
-```env
-REVENIUM_DEBUG=true
-```
-
-### Getting Help
-
-If issues persist:
-
-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
-
-## Supported Models
-
-This middleware works with any Perplexity model. For the complete model list, see the [Perplexity Models Documentation](https://docs.perplexity.ai/getting-started/models).
-
-### API Support Matrix
-
-The following table shows what has been tested and verified with working examples:
-
-| Feature               | Chat Completions | Streaming |
-| --------------------- | ---------------- | --------- |
-| **Basic Usage**       | Yes              | Yes       |
-| **Metadata Tracking** | Yes              | Yes       |
-| **Token Counting**    | Yes              | Yes       |
-
-**Note:** "Yes" = Tested with working examples in [`examples/`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/) directory
-
-## 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
-
----
-
-**Built by Revenium**
+# 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
+
+- **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
+```
+
+**Note:** The `dotenv` package is optional. The middleware automatically loads `.env` files via `Initialize()`.
+
+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 npm project
+npm init -y
+```
+
+#### Step 2: Install Dependencies
+
+```bash
+# Install Revenium middleware
+npm install @revenium/perplexity
+
+# 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
+# Create .env file
+echo. > .env  # On Windows (CMD)
+touch .env    # On Mac/Linux
+# OR
+# PowerShell
+New-Item -Path .env -ItemType File
+```
+
+Copy and paste the following into `.env`:
+
+```env
+# Perplexity Configuration
+PERPLEXITY_API_KEY=pplx_your_perplexity_api_key
+
+# Revenium Configuration
+REVENIUM_METERING_API_KEY=hak_your_revenium_api_key
+
+# Optional: For development/testing (defaults to https://api.revenium.ai)
+# REVENIUM_METERING_BASE_URL=https://api.revenium.ai
+
+# Optional: Perplexity API base URL (defaults to https://api.perplexity.ai)
+# PERPLEXITY_API_BASE_URL=https://api.perplexity.ai
+
+# Optional: Enable debug logging
+# REVENIUM_DEBUG=false
+```
+
+**Replace the placeholder values with your actual keys!**
+
+For a complete list of all available environment variables, see the [Configuration Options](#configuration-options) section below.
+
+#### Step 4: Implement in Your Code
+
+Use the examples as reference for implementing the middleware in your project. See [examples/README.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md) for complete implementation examples including:
+
+- How to initialize the middleware with your configuration
+- Making API calls with automatic metering
+- Handling streaming responses
+- Adding custom metadata to track business context
+
+**Note for ESM projects:** If you get a "Cannot use import statement outside a module" error, make sure your `package.json` includes `"type": "module"`:
+
+```json
+{
+  "name": "my-perplexity-project",
+  "version": "1.0.0",
+  "type": "module",
+  "dependencies": {
+    "@revenium/perplexity": "^2.0.0"
+  }
+}
+```
+
+---
+
+## Running Examples from Cloned Repository
+
+If you've cloned this repository from GitHub and want to **run the included examples** to see how the middleware works (without modifying the middleware source code):
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Configure environment variables
+cp .env.example .env      # On Mac/Linux
+copy .env.example .env    # On Windows (CMD)
+# OR PowerShell
+Copy-Item .env.example .env
+
+# Edit .env with your API keys
+```
+
+### Run Examples
+
+**Using npm scripts:**
+
+```bash
+npm run example:getting-started  # Getting started example
+npm run example:basic            # Basic chat completion
+npm run example:stream           # Streaming response
+npm run example:metadata         # Custom metadata
+npm run example:advanced         # Advanced features
+```
+
+**Or use npx tsx directly:**
+
+```bash
+npx tsx examples/getting_started.ts
+npx tsx examples/basic.ts
+npx tsx examples/stream.ts
+npx tsx examples/metadata.ts
+npx tsx examples/advanced.ts
+```
+
+For detailed information about each example, see [examples/README.md](examples/README.md).
+
+---
+
+## Local Development and Contributing
+
+For information on modifying the middleware source code, development workflow, and contributing to the project, see:
+
+- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Complete development guide, build system, and testing
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines and process
+
+---
+
+## What Gets Tracked
+
+The middleware automatically captures comprehensive usage data:
+
+### **Usage Metrics**
+
+- **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
+
+### **Business Context (Optional)**
+
+- **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
+
+### **Technical Details**
+
+- **API Endpoints** - Chat completions
+- **Request Types** - Streaming vs non-streaming
+- **Error Tracking** - Failed requests, error types, retry attempts
+- **Environment Info** - Development vs production usage
+
+## Metadata Fields
+
+The following table shows all fields this middleware sends to the Revenium API:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| **Core Fields** | | | |
+| `model` | string | Yes | Perplexity model name (e.g., "sonar-pro") |
+| `provider` | string | Yes | Always "Perplexity" |
+| `inputTokenCount` | integer | Yes | Number of input tokens consumed |
+| `outputTokenCount` | integer | Yes | Number of output tokens generated |
+| `totalTokenCount` | integer | Yes | Total tokens (input + output) |
+| `requestDuration` | integer | Yes | Request duration in milliseconds |
+| **Timing** | | | |
+| `requestTime` | string | Auto | ISO 8601 timestamp when request started |
+| `responseTime` | string | Auto | ISO 8601 timestamp when response completed |
+| `completionStartTime` | string | Auto | ISO 8601 timestamp when completion started |
+| `timeToFirstToken` | integer | Streaming | Time to first token in ms (streaming only) |
+| **Request Details** | | | |
+| `transactionId` | string | Auto | Unique transaction identifier |
+| `operationType` | string | Auto | Always "CHAT" for chat completions |
+| `stopReason` | string | Auto | Completion finish reason ("END", "STOP", etc.) |
+| `isStreamed` | boolean | Auto | Whether response was streamed |
+| `costType` | string | Auto | Always "AI" |
+| `modelSource` | string | Auto | Always "PERPLEXITY" |
+| `middlewareSource` | string | Auto | Always "revenium-perplexity-node" |
+| **Cost Information** | | | |
+| `inputTokenCost` | number | Optional | Cost for input tokens (if provided by Perplexity) |
+| `outputTokenCost` | number | Optional | Cost for output tokens (if provided by Perplexity) |
+| `totalCost` | number | Optional | Total cost (if provided by Perplexity) |
+| **Business Context** | | | |
+| `organizationId` | string | Optional | Your organization identifier |
+| `productId` | string | Optional | Your product identifier |
+| `subscriptionId` | string | Optional | Your subscription identifier |
+| `taskType` | string | Optional | Type of AI task (e.g., "chat", "research") |
+| `traceId` | string | Optional | Session or conversation tracking ID |
+| `agent` | string | Optional | AI agent or bot identifier |
+| `responseQualityScore` | number | Optional | Custom quality rating (0.0-1.0) |
+| `subscriber.id` | string | Optional | User identifier |
+| `subscriber.email` | string | Optional | User email address |
+| `subscriber.credential` | object | Optional | Authentication credential (name, value) |
+
+**Notes:**
+- **Required** fields are always sent with every request
+- **Auto** fields are automatically populated by the middleware
+- **Optional** fields are only sent if you provide them via `usageMetadata`
+- **Streaming** fields are only sent for streaming requests
+
+**Reference:**
+- [API Reference](https://revenium.readme.io/reference/meter_ai_completion) - Complete metadata field documentation
+
+## API Overview
+
+- **`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)
+
+**For complete API documentation and usage examples, see [`examples/README.md`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md).**
+
+## Configuration Options
+
+### Environment Variables
+
+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
+
+The package includes comprehensive examples in the [`examples/`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/) directory.
+
+## Project Structure
+
+```
+revenium-middleware-perplexity-node/
+├── src/
+│   ├── core/
+│   │   ├── client/          # Client manager (Initialize/GetClient)
+│   │   ├── config/           # Configuration management
+│   │   ├── middleware/       # Perplexity API middleware wrapper
+│   │   ├── providers/        # Provider detection
+│   │   └── tracking/         # Metering and tracking
+│   ├── types/                # TypeScript type definitions
+│   ├── utils/                # Utility functions
+│   └── index.ts              # Main entry point
+├── examples/                 # TypeScript examples
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## How It Works
+
+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
+
+The middleware never blocks your application - if Revenium tracking fails, your Perplexity requests continue normally.
+
+**Supported APIs:**
+
+- Chat Completions API (`client.chat().completions().create()`)
+- Streaming API (`client.chat().completions().createStreaming()`)
+
+## Troubleshooting
+
+### Common Issues
+
+**No tracking data appears:**
+
+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
+
+**Client not initialized error:**
+
+- Make sure you call `Initialize()` before `GetClient()`
+- Check that your `.env` file is in the project root
+- Verify `REVENIUM_METERING_API_KEY` is set
+
+**Perplexity API errors:**
+
+- Verify `PERPLEXITY_API_KEY` is set correctly
+- Check that your API key starts with `pplx-`
+- Ensure you're using a valid model name
+
+**Windows-specific issues:**
+
+If you're developing on Windows and encounter build errors with `npm run clean`:
+
+- The `clean` script uses `rm -rf` which may not work in Windows CMD
+- Use PowerShell or Git Bash instead
+- Or manually delete the `dist` folder before building
+- Alternatively, install `rimraf` globally: `npm install -g rimraf` and update the script to use `rimraf dist`
+
+### Debug Mode
+
+Enable detailed logging by adding to your `.env`:
+
+```env
+REVENIUM_DEBUG=true
+```
+
+### Getting Help
+
+If issues persist:
+
+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
+
+## Supported Models
+
+This middleware works with any Perplexity model. For the complete model list, see the [Perplexity Models Documentation](https://docs.perplexity.ai/getting-started/models).
+
+### API Support Matrix
+
+The following table shows what has been tested and verified with working examples:
+
+| Feature               | Chat Completions | Streaming |
+| --------------------- | ---------------- | --------- |
+| **Basic Usage**       | Yes              | Yes       |
+| **Metadata Tracking** | Yes              | Yes       |
+| **Token Counting**    | Yes              | Yes       |
+
+**Note:** "Yes" = Tested with working examples in [`examples/`](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/) directory
+
+## 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
+
+---
+
+**Built by Revenium**