@revenium/perplexity 2.0.4 → 2.0.6

package/README.md

@@ -1,271 +1,292 @@
-# 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**
+# 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 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:basic
+npm run example:streaming
+npm run example:chat
+npm run example:metadata
+npm run example:advanced
+npm run example:getting-started
+```
+
+---
+
+## 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**

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this package, please report it to us.
+
+**DO NOT** create a public GitHub issue for security vulnerabilities.
+
+### How to Report
+
+Email: support@revenium.io
+
+Please include:
+- Package name and version
+- Description of the vulnerability
+- Steps to reproduce (if applicable)
+- Potential impact
+- Suggested fix (if available)
+
+We will review and respond to security reports in a timely manner.
+
+## Security Best Practices
+
+When using this middleware:
+
+1. **API Keys**: Never commit API keys to version control
+2. **Environment Variables**: Use environment variables for sensitive configuration
+3. **PII Handling**: Ensure no PII is sent to Revenium unless explicitly configured for billing purposes
+4. **Network Security**: Always use HTTPS connections
+5. **Updates**: Keep the package updated to the latest version
+
+## Additional Resources
+
+- [Revenium Documentation](https://docs.revenium.io)

package/dist/cjs/core/client/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Client module exports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Configure = exports.Reset = exports.IsInitialized = exports.GetClient = exports.Initialize = void 0;
+var manager_js_1 = require("./manager.js");
+Object.defineProperty(exports, "Initialize", { enumerable: true, get: function () { return manager_js_1.Initialize; } });
+Object.defineProperty(exports, "GetClient", { enumerable: true, get: function () { return manager_js_1.GetClient; } });
+Object.defineProperty(exports, "IsInitialized", { enumerable: true, get: function () { return manager_js_1.IsInitialized; } });
+Object.defineProperty(exports, "Reset", { enumerable: true, get: function () { return manager_js_1.Reset; } });
+Object.defineProperty(exports, "Configure", { enumerable: true, get: function () { return manager_js_1.Configure; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/core/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/client/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,2CAAsF;AAA7E,wGAAA,UAAU,OAAA;AAAE,uGAAA,SAAS,OAAA;AAAE,2GAAA,aAAa,OAAA;AAAE,mGAAA,KAAK,OAAA;AAAE,uGAAA,SAAS,OAAA"}