@revenium/perplexity 2.0.5 → 2.0.7

package/README.md

@@ -1,290 +1,376 @@
-# 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 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 npm 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
-
-**For complete examples and usage patterns, see [examples/README.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md) for complete examples and setup instructions.
-
-**Cloned from GitHub?** Run examples with:
-
-```bash
-npm install
-npm run example:getting-started  # Start here!
-npm run example:basic
-npm run example:stream
-npm run example:metadata
-npm run example:advanced
-```
-
----
-
-## 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
-
-The middleware provides a Go-aligned API with the following main functions:
-
-- **`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/
-│   │   ├── config/           # Configuration management
-│   │   ├── tracking/         # Metering and tracking
-│   │   └── wrapper/          # Perplexity API wrapper
-│   ├── types/                # TypeScript type definitions
-│   ├── utils/                # Utility functions
-│   └── index.ts              # Main entry point
-├── examples/                 # TypeScript examples
-├── .env.example              # Example environment variables
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-## 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
-
-## Development
-
-For development and testing instructions, see [DEVELOPMENT.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/DEVELOPMENT.md).
-
----
-
-**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
+
+- **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**