@revenium/perplexity 1.0.14 → 1.0.15

package/README.md

@@ -1,448 +1,447 @@
-# Revenium Middleware for Perplexity AI (Node.js)
-
-[![npm version](https://badge.fury.io/js/%40revenium%2Fperplexity.svg)](https://badge.fury.io/js/%40revenium%2Fperplexity)
-[![Node Versions](https://img.shields.io/node/v/@revenium/perplexity.svg)](https://www.npmjs.com/package/@revenium/perplexity)
-[![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://docs.revenium.io)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-Automatically track and meter your Perplexity AI API usage with Revenium. This middleware provides seamless integration with Perplexity AI SDK, requiring minimal code changes.
-
-## 🚀 Getting Started
-
-You have 3 options to start using Revenium middleware for Perplexity AI:
-
-| Option                                    | Description                                                                         | Best For                                                             |
-| ----------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| **Option 1: Create Project from Scratch** | Perfect for new projects. We'll guide you step-by-step from mkdir to running tests. | 👉 [Go to Step-by-Step Guide](#option-1-create-project-from-scratch) |
-| **Option 2: Clone Our Repository**        | Quick testing with pre-built examples and playground scripts.                       | 👉 [Go to Clone Guide](#option-2-clone-repository)                   |
-| **Option 3: Add to Existing Project**     | Already have a project? Just install and replace imports.                           | 👉 [Go to Quick Integration](#option-3-existing-project-integration) |
-
----
-
-## Option 1: Create Project from Scratch
-
-### Step 1: Create Project Directory
-
-```bash
-# Create and navigate to your project
-mkdir my-perplexity-ai-project
-cd my-perplexity-ai-project
-
-# Initialize Node.js project
-npm init -y
-```
-
-### Step 2: Install Dependencies
-
-```bash
-npm install @revenium/perplexity
-```
-
-### Step 3: Setup Environment Variables
-
-Create a `.env` file in your project root:
-
-```bash
-# Create .env file
-echo. > .env  # On Windows (CMD TERMINAL)
-touch .env  # On Mac/Linux (CMD TERMINAL)
-# OR
-#PowerShell
-New-Item -Path .env -ItemType File
-```
-
-Copy and paste the following into `.env`:
-
-```bash
-# Perplexity AI Configuration
-PERPLEXITY_API_KEY="your_perplexity_api_key_here"
-
-# Revenium Configuration
-REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
-REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
-
-```
-
-### Step 4: Create Your First Test
-
-Create `test-perplexity.js`:
-
-```javascript
-// test-perplexity.js
-import { createPerplexityClient } from "@revenium/perplexity";
-
-const client = createPerplexityClient();
-
-try {
-  const result = await client.createChatCompletion({
-    model: "sonar-pro",
-    messages: [
-      {
-        role: "user",
-        content: "What is the universe?",
-      },
-    ],
-  });
-
-  const text = result.choices[0]?.message?.content;
-  console.log("*** RESPONSE ***");
-  console.log(text);
-  console.log("✅ Basic Perplexity AI example successful!");
-} catch (error) {
-  console.error("❌ Perplexity basic example failed:", error);
-  process.exit(1);
-}
-```
-
-### Step 5: Update package.json
-
-Add test scripts and module type to your `package.json`:
-
-```json
-{
-  "name": "my-perplexity-ai-project",
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "test-perplexity": "node test-perplexity.js"
-  },
-  "dependencies": {
-    "@revenium/perplexity": "^1.0.0"
-  }
-}
-```
-
-⚠️ **Important**: If you get this error when running tests:
-
-```
-SyntaxError: Cannot use import statement outside a module
-```
-
-Make sure your `package.json` includes `"type": "module"` as shown below.
-
-```json
-{
-  "type": "module"
-}
-```
-
-### Step 6: Run Your Tests
-
-```bash
-# Test Perplexity AI SDK
-npm run test-perplexity
-```
-
-### Step 7: Create Advanced Examples
-
-Create an examples directory and add these files:
-
-```bash
-mkdir examples
-```
-
-#### Streaming Example
-
-Create `examples/streaming-perplexity.js`:
-
-```javascript
-// examples/streaming-perplexity.js
-import { createPerplexityClient } from "@revenium/perplexity";
-
-const client = createPerplexityClient();
-
-try {
-  const stream = await client.createStreamingChatCompletion({
-    model: "sonar-pro",
-    messages: [
-      {
-        role: "user",
-        content: "What is artificial intelligence?",
-      },
-    ],
-  });
-
-  console.log("*** STREAMING RESPONSE ***");
-  let fullText = "";
-
-  for await (const chunk of stream) {
-    const content = chunk.choices[0]?.delta?.content;
-    if (content) {
-      process.stdout.write(content);
-      fullText += content;
-    }
-  }
-
-  console.log("\n✅ Streaming with metering successful!");
-  console.log(`📊 Total response length: ${fullText.length} characters`);
-} catch (error) {
-  console.error("❌ Perplexity streaming example failed:", error);
-  process.exit(1);
-}
-```
-
-### Step 8: Update package.json
-
-```json
-{
-  "name": "my-perplexity-ai-project",
-  "version": "1.0.0",
-  "type": "module",
-  "scripts": {
-    "test-perplexity": "node test-perplexity.js",
-    "test-perplexity-stream": "node examples/streaming-perplexity.js"
-  },
-  "dependencies": {
-    "@revenium/perplexity": "^1.0.0"
-  }
-}
-```
-
-### Step 9: Test Advanced Examples
-
-```bash
-# Test streaming
-npm run test-perplexity-stream
-
-```
-
----
-
-## Option 2: Clone Repository
-
-Perfect for testing with pre-built examples:
-
-```bash
-# Clone the repository
-git clone git@github.com:revenium/revenium-middleware-perplexity-node.git
-cd revenium-middleware-perplexity-node
-
-# Install dependencies
-npm install
-npm install @revenium/perplexity
-
-# Create your .env file
-cp .env.example .env
-# Edit .env with your API keys
-```
-
-### Configure Environment Variables
-
-Edit your `.env` file:
-
-```bash
-# For Perplexity AI SDK
-PERPLEXITY_API_KEY="your_perplexity_api_key_here"
-REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
-REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
-```
-
-### Run Perplexity AI Examples
-
-```bash
-# Perplexity AI examples
-
-npm run e-basic        # Basic chat completion
-npm run e-streaming    # Streaming response
-npm run e-enhanced     # Enhanced request
-npm run e-chat-completions     # Chat completions
-
-# Playground examples
-# Required build first
-npm run build
-# Then run any of the following
-npm run p-basic
-npm run p-streaming
-npm run p-enhanced
-```
-
----
-
-## Option 3: Existing Project Integration
-
-Already have a project? Just install and replace imports:
-
-### Step 1. Install the Package
-
-```bash
-npm install @revenium/perplexity
-```
-
-### Step 2. Add Environment Variables
-
-Add to your existing `.env` file:
-
-```bash
-PERPLEXITY_API_KEY="your_perplexity_api_key_here"
-REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
-REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
-```
-
-### Step 3. Replace Your Imports
-
-**Before:**
-
-```javascript
-import { OpenAI } from "openai";
-```
-
-**After:**
-
-```javascript
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
-```
-
-### Step 4. Update Your Code
-
-#### Revenium Client Example
-
-```javascript
-import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
-
-// Initialize (API key from environment variable)
-const middleware = new PerplexityReveniumMiddleware();
-const model = middleware.getGenerativeModel("sonar-pro");
-const result = await model.createChatCompletion({
-  messages: [
-    {
-      role: "user",
-      content: "Hello world",
-    },
-  ],
-});
-console.log("[BASIC EXAMPLE]", result.choices[0].message.content);
-```
-
----
-
-## 🔧 Advanced Usage
-
-### Streaming Responses
-
-#### Revenium Client Streaming
-
-```javascript
-const stream = await model.createChatCompletionStream({
-  messages: [
-    {
-      role: "user",
-      content: "Hello world",
-    },
-  ],
-});
-for await (const chunk of stream) {
-  process.stdout.write(chunk.choices[0]?.delta?.content || "");
-}
-```
-
-## 📊 What Gets Tracked
-
-- **Token Usage**: Input and output tokens for accurate billing
-- **Request Duration**: Total time for each API call
-- **Model Information**: Which model was used
-- **Operation Type**: Chat completion, streaming
-- **Error Tracking**: Failed requests and error details
-- **Streaming Metrics**: Time to first token for streaming responses
-- **Custom Metadata**: Rich business context and user tracking
-
----
-
-## 🔗 Supported Models
-
-### Chat Models
-
-- **sonar-pro** (Latest and most capable)
-- **sonar-small** (Fast and efficient)
-- **sonar-medium** (Balanced performance)
-
-_Note: Model availability depends on your Perplexity AI account and API access level._
-
----
-
-## 🛠️ Configuration Options
-
-### Environment Variables
-
-| Variable                     | Required | Description                                                |
-| ---------------------------- | -------- | ---------------------------------------------------------- |
-| `PERPLEXITY_API_KEY`         | ✅       | Your Perplexity API key                                    |
-| `REVENIUM_METERING_API_KEY`  | ✅       | Your Revenium API key                                      |
-| `REVENIUM_METERING_BASE_URL` | ❌       | Revenium base URL (default: https://api.revenium.io/meter) |
-
----
-
-## 🚨 Troubleshooting
-
-### Common Issues
-
-**"Missing API Key" Error**
-
-```bash
-export PERPLEXITY_API_KEY="your-actual-api-key"
-echo $PERPLEXITY_API_KEY  # Verify it's set
-```
-
-**"Requests not being tracked"**
-
-```bash
-export REVENIUM_METERING_API_KEY="your-actual-revenium-key"
-export REVENIUM_LOG_LEVEL="DEBUG"  # Enable debug logging
-```
-
-**Module Import Errors**
-
-```json
-{
-  "type": "module"
-}
-```
-
-This will show:
-
-- Request/response details
-- Token counting information
-- Metering data being sent
-- Error details
-- Middleware activation status
-
----
-
-## 📚 Examples Repository
-
-Check out our comprehensive examples:
-
-- **Basic Usage**: Simple chat completions
-- **Streaming**: Real-time response streaming
-- **Metadata**: Rich tracking examples
-- **Error Handling**: Robust error management
-- **Advanced Patterns**: Complex use cases
-- **Configuration**: Different setup options
-
-All examples are in the `/examples` and `/playground` directories.
-
----
-
-## 📋 Requirements
-
-- Node.js 18+
-- Perplexity API key
-- Revenium API key
-
----
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
----
-
-## 🤝 Support
-
-- 📖 [Documentation](https://docs.revenium.com)
-- 💬 [Community Support](https://community.revenium.com)
-- 📧 [Email Support](mailto:support@revenium.com)
-- 🐛 [Report Issues](https://github.com/revenium/revenium-middleware-perplexity-node/issues)
-
----
-
-**Built with ❤️ by Revenium**
+# Revenium Middleware for Perplexity AI (Node.js)
+
+[![npm version](https://badge.fury.io/js/%40revenium%2Fperplexity.svg)](https://badge.fury.io/js/%40revenium%2Fperplexity)
+[![Node Versions](https://img.shields.io/node/v/@revenium/perplexity.svg)](https://www.npmjs.com/package/@revenium/perplexity)
+[![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://docs.revenium.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Automatically track and meter your Perplexity AI API usage with Revenium. This middleware provides seamless integration with Perplexity AI SDK, requiring minimal code changes.
+
+## 🚀 Getting Started
+
+You have 3 options to start using Revenium middleware for Perplexity AI:
+
+| Option                                    | Description                                                                         | Best For                                                             |
+| ----------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Option 1: Create Project from Scratch** | Perfect for new projects. We'll guide you step-by-step from mkdir to running tests. | 👉 [Go to Step-by-Step Guide](#option-1-create-project-from-scratch) |
+| **Option 2: Clone Our Repository**        | Quick testing with pre-built examples and playground scripts.                       | 👉 [Go to Clone Guide](#option-2-clone-repository)                   |
+| **Option 3: Add to Existing Project**     | Already have a project? Just install and replace imports.                           | 👉 [Go to Quick Integration](#option-3-existing-project-integration) |
+
+---
+
+## Option 1: Create Project from Scratch
+
+### Step 1: Create Project Directory
+
+```bash
+# Create and navigate to your project
+mkdir my-perplexity-ai-project
+cd my-perplexity-ai-project
+
+# Initialize Node.js project
+npm init -y
+```
+
+### Step 2: Install Dependencies
+
+```bash
+npm install @revenium/perplexity
+```
+
+### Step 3: Setup Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+# Create .env file
+echo. > .env  # On Windows (CMD TERMINAL)
+touch .env  # On Mac/Linux (CMD TERMINAL)
+# OR
+#PowerShell
+New-Item -Path .env -ItemType File
+```
+
+Copy and paste the following into `.env`:
+
+```bash
+# Perplexity AI Configuration
+PERPLEXITY_API_KEY="your_perplexity_api_key_here"
+
+# Revenium Configuration
+REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
+REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
+
+```
+
+### Step 4: Create Your First Test
+
+Create `test-perplexity.js`:
+
+```javascript
+// test-perplexity.js
+import { createPerplexityClient } from "@revenium/perplexity";
+
+const client = createPerplexityClient();
+
+try {
+  const result = await client.createChatCompletion({
+    model: "sonar-pro",
+    messages: [
+      {
+        role: "user",
+        content: "What is the universe?",
+      },
+    ],
+  });
+
+  const text = result.choices[0]?.message?.content;
+  console.log("*** RESPONSE ***");
+  console.log(text);
+  console.log("✅ Basic Perplexity AI example successful!");
+} catch (error) {
+  console.error("❌ Perplexity basic example failed:", error);
+  process.exit(1);
+}
+```
+
+### Step 5: Update package.json
+
+Add test scripts and module type to your `package.json`:
+
+```json
+{
+  "name": "my-perplexity-ai-project",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "test-perplexity": "node test-perplexity.js"
+  },
+  "dependencies": {
+    "@revenium/perplexity": "^1.0.0"
+  }
+}
+```
+
+⚠️ **Important**: If you get this error when running tests:
+
+```
+SyntaxError: Cannot use import statement outside a module
+```
+
+Make sure your `package.json` includes `"type": "module"` as shown below.
+
+```json
+{
+  "type": "module"
+}
+```
+
+### Step 6: Run Your Tests
+
+```bash
+# Test Perplexity AI SDK
+npm run test-perplexity
+```
+
+### Step 7: Create Advanced Examples
+
+Create an examples directory and add these files:
+
+```bash
+mkdir examples
+```
+
+#### Streaming Example
+
+Create `examples/streaming-perplexity.js`:
+
+```javascript
+// examples/streaming-perplexity.js
+import { createPerplexityClient } from "@revenium/perplexity";
+
+const client = createPerplexityClient();
+
+try {
+  const stream = await client.createStreamingChatCompletion({
+    model: "sonar-pro",
+    messages: [
+      {
+        role: "user",
+        content: "What is artificial intelligence?",
+      },
+    ],
+  });
+
+  console.log("*** STREAMING RESPONSE ***");
+  let fullText = "";
+
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content;
+    if (content) {
+      process.stdout.write(content);
+      fullText += content;
+    }
+  }
+
+  console.log("\n✅ Streaming with metering successful!");
+  console.log(`📊 Total response length: ${fullText.length} characters`);
+} catch (error) {
+  console.error("❌ Perplexity streaming example failed:", error);
+  process.exit(1);
+}
+```
+
+### Step 8: Update package.json
+
+```json
+{
+  "name": "my-perplexity-ai-project",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "test-perplexity": "node test-perplexity.js",
+    "test-perplexity-stream": "node examples/streaming-perplexity.js"
+  },
+  "dependencies": {
+    "@revenium/perplexity": "^1.0.0"
+  }
+}
+```
+
+### Step 9: Test Advanced Examples
+
+```bash
+# Test streaming
+npm run test-perplexity-stream
+
+```
+
+---
+
+## Option 2: Clone Repository
+
+Perfect for testing with pre-built examples:
+
+```bash
+# Clone the repository
+git clone git@github.com:revenium/revenium-middleware-perplexity-node.git
+cd revenium-middleware-perplexity-node
+
+# Install dependencies
+npm install
+npm install @revenium/perplexity
+
+# Create your .env file
+cp .env.example .env
+# Edit .env with your API keys
+```
+
+### Configure Environment Variables
+
+Edit your `.env` file:
+
+```bash
+# For Perplexity AI SDK
+PERPLEXITY_API_KEY="your_perplexity_api_key_here"
+REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
+REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
+```
+
+### Run Perplexity AI Examples
+
+```bash
+# Perplexity AI examples
+
+npm run e-basic        # Basic chat completion
+npm run e-streaming    # Streaming response
+npm run e-enhanced     # Enhanced request
+npm run e-chat-completions     # Chat completions
+
+# Playground examples
+# Required build first
+npm run build
+# Then run any of the following
+npm run p-basic
+npm run p-streaming
+npm run p-enhanced
+```
+
+---
+
+## Option 3: Existing Project Integration
+
+Already have a project? Just install and replace imports:
+
+### Step 1. Install the Package
+
+```bash
+npm install @revenium/perplexity
+```
+
+### Step 2. Add Environment Variables
+
+Add to your existing `.env` file:
+
+```bash
+PERPLEXITY_API_KEY="your_perplexity_api_key_here"
+REVENIUM_METERING_API_KEY="your_revenium_api_key_here"
+REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
+```
+
+### Step 3. Replace Your Imports
+
+**Before:**
+
+```javascript
+import { OpenAI } from "openai";
+```
+
+**After:**
+
+```javascript
+import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
+```
+
+### Step 4. Update Your Code
+
+#### Revenium Client Example
+
+```javascript
+import { PerplexityReveniumMiddleware } from "@revenium/perplexity";
+
+// Initialize (API key from environment variable)
+const middleware = new PerplexityReveniumMiddleware();
+const model = middleware.getGenerativeModel("sonar-pro");
+const result = await model.createChatCompletion({
+  messages: [
+    {
+      role: "user",
+      content: "Hello world",
+    },
+  ],
+});
+console.log("[BASIC EXAMPLE]", result.choices[0].message.content);
+```
+
+---
+
+## 🔧 Advanced Usage
+
+### Streaming Responses
+
+#### Revenium Client Streaming
+
+```javascript
+const stream = await model.createChatCompletionStream({
+  messages: [
+    {
+      role: "user",
+      content: "Hello world",
+    },
+  ],
+});
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || "");
+}
+```
+
+## 📊 What Gets Tracked
+
+- **Token Usage**: Input and output tokens for accurate billing
+- **Request Duration**: Total time for each API call
+- **Model Information**: Which model was used
+- **Operation Type**: Chat completion, streaming
+- **Error Tracking**: Failed requests and error details
+- **Streaming Metrics**: Time to first token for streaming responses
+- **Custom Metadata**: Rich business context and user tracking
+
+---
+
+## 🔗 Supported Models
+
+### Chat Models
+
+- **sonar-pro** (Latest and most capable)
+- **sonar-small** (Fast and efficient)
+- **sonar-medium** (Balanced performance)
+
+_Note: Model availability depends on your Perplexity AI account and API access level._
+
+---
+
+## 🛠️ Configuration Options
+
+### Environment Variables
+
+| Variable                     | Required | Description                                                |
+| ---------------------------- | -------- | ---------------------------------------------------------- |
+| `PERPLEXITY_API_KEY`         | ✅       | Your Perplexity API key                                    |
+| `REVENIUM_METERING_API_KEY`  | ✅       | Your Revenium API key                                      |
+| `REVENIUM_METERING_BASE_URL` | ❌       | Revenium base URL (default: https://api.revenium.io/meter) |
+
+---
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**"Missing API Key" Error**
+
+```bash
+export PERPLEXITY_API_KEY="your-actual-api-key"
+echo $PERPLEXITY_API_KEY  # Verify it's set
+```
+
+**"Requests not being tracked"**
+
+```bash
+export REVENIUM_METERING_API_KEY="your-actual-revenium-key"
+```
+
+**Module Import Errors**
+
+```json
+{
+  "type": "module"
+}
+```
+
+This will show:
+
+- Request/response details
+- Token counting information
+- Metering data being sent
+- Error details
+- Middleware activation status
+
+---
+
+## 📚 Examples Repository
+
+Check out our comprehensive examples:
+
+- **Basic Usage**: Simple chat completions
+- **Streaming**: Real-time response streaming
+- **Metadata**: Rich tracking examples
+- **Error Handling**: Robust error management
+- **Advanced Patterns**: Complex use cases
+- **Configuration**: Different setup options
+
+All examples are in the `/examples` and `/playground` directories.
+
+---
+
+## 📋 Requirements
+
+- Node.js 18+
+- Perplexity API key
+- Revenium API key
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🤝 Support
+
+- 📖 [Documentation](https://docs.revenium.com)
+- 💬 [Community Support](https://community.revenium.com)
+- 📧 [Email Support](mailto:support@revenium.com)
+- 🐛 [Report Issues](https://github.com/revenium/revenium-middleware-perplexity-node/issues)
+
+---
+
+**Built with ❤️ by Revenium**