@revenium/perplexity 2.0.3 → 2.0.4

package/examples/README.md

@@ -1,323 +1,322 @@
-# Revenium Perplexity AI Middleware Examples
+# Running Examples - Revenium Middleware for Perplexity (Node.js)
 
-Comprehensive examples demonstrating how to use the @revenium/perplexity middleware with automatic usage tracking and metering.
+This guide shows you how to run the Node.js/TypeScript examples in this repository.
 
-## TypeScript-First Approach
+## Prerequisites
 
-These examples are written in TypeScript to showcase type-safe development patterns. You can use them in both TypeScript and JavaScript projects:
+- Node.js 20+ installed
+- Perplexity API key
+- Revenium API key
 
-- **TypeScript projects**: Run examples directly with `tsx` or `ts-node`
-- **JavaScript projects**: See playground/ directory for JavaScript versions
+## Setup
 
-**For npm users:** These examples are included in your `node_modules/@revenium/perplexity/examples/` directory after installation.
+### 1. Clone the Repository
 
-**For GitHub users:** Clone the repository to run examples directly with the included npm scripts.
-
-## Quick Start
+```bash
+git clone https://github.com/revenium/revenium-middleware-perplexity-node.git
+cd revenium-middleware-perplexity-node
+```
 
-### 1. Installation
+### 2. Install Dependencies
 
 ```bash
-npm install @revenium/perplexity dotenv
-npm install --save-dev tsx  # For TypeScript projects
+npm install
 ```
 
-### 2. Environment Setup
+### 3. Configure Environment Variables
 
-Create a `.env` file in your project root:
+Create a `.env` file in the root directory:
 
-```env
-# Required: Your Perplexity API key
-PERPLEXITY_API_KEY=pplx_your_perplexity_key
+```bash
+# Create .env file
+cp .env.example .env
+```
 
-# Required: Revenium metering API key
-REVENIUM_METERING_API_KEY=hak_your_revenium_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter/v2
+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.
 
-# Optional: Perplexity base URL (defaults to https://api.perplexity.ai)
-PERPLEXITY_API_BASE_URL=https://api.perplexity.ai
+**Replace the placeholder values with your actual keys!**
 
-# Optional: Enable debug logging
-DEBUG=true
-```
+## Running Examples
 
-### 3. Run Examples
+### Available Examples
 
-From the repository:
 ```bash
-npm run example:basic      # Basic chat completion
-npm run example:streaming  # Streaming responses
-npm run example:chat       # Multi-turn conversations
-npm run example:metadata   # Custom usage metadata
+npm run example:basic            # Basic chat completion
+npm run example:streaming        # Streaming response
+npm run example:chat             # Multi-turn conversation
+npm run example:metadata         # With custom metadata
+npm run example:advanced         # Advanced features
+npm run example:getting-started  # Quick start example
+npm test                         # Run all examples
 ```
 
-Or run all examples:
-```bash
-npm test
-```
+## Example Structure
 
-## Getting Started - Step by Step
+```
+examples/
+├── basic.ts                 # Basic chat completion
+├── streaming.ts             # Streaming response
+├── chat.ts                  # Multi-turn conversation
+├── metadata.ts              # With custom metadata
+├── advanced-features.ts     # Advanced features
+├── getting_started.ts       # Quick start example
+└── README.md                # This file
+```
 
-### Step 1: Create Your First Test
+## Examples Included
 
-**TypeScript:**
-```typescript
-// test-perplexity.ts
-import { config } from "dotenv";
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-} from "@revenium/perplexity";
+### 1. Basic Usage
 
-config(); // Load .env file
+**Location**: `examples/basic.ts`
 
-async function test() {
-  // Initialize configurations
-  initializeReveniumFromEnv();
-  initializePerplexityFromEnv();
+**What it demonstrates:**
 
-  // Create chat completion
-  const result = await createChatCompletion({
-    messages: [{ role: "user", content: "Hello!" }],
-    model: "sonar-pro",
-  });
+- Simple chat completion
+- Automatic metering
+- Basic error handling
 
-  console.log(result.choices[0].message.content);
-}
+**Run it:**
 
-test();
+```bash
+npm run example:basic
 ```
 
-**JavaScript (CommonJS):**
-```javascript
-// test-perplexity.js
-require("dotenv").config();
-const {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion
-} = require("@revenium/perplexity");
-
-async function test() {
-  initializeReveniumFromEnv();
-  initializePerplexityFromEnv();
-
-  const result = await createChatCompletion({
-    messages: [{ role: "user", content: "Hello!" }],
-    model: "sonar-pro",
-  });
-
-  console.log(result.choices[0].message.content);
-}
-
-test();
+**Expected output:**
+
+```
+✓ Chat Completion Successful
+Response: [AI response here]
+Model: sonar-pro
+Tokens Used: 50 (prompt: 10, completion: 40)
 ```
 
-### Step 2: Update package.json
+---
 
-Add scripts to run your tests:
+### 2. Streaming
 
-```json
-{
-  "scripts": {
-    "test:perplexity": "tsx test-perplexity.ts"
-  }
-}
-```
+**Location**: `examples/streaming.ts`
 
-Or for JavaScript:
-```json
-{
-  "scripts": {
-    "test:perplexity": "node test-perplexity.js"
-  }
-}
-```
+**What it demonstrates:**
+
+- Real-time streaming responses
+- Token tracking for streamed content
+- Automatic usage tracking when stream completes
 
-### Step 3: Run Your Tests
+**Run it:**
 
 ```bash
-npm run test:perplexity
+npm run example:streaming
 ```
 
-### Step 4: Explore Advanced Features
+**Expected output:**
 
-Once basic integration works, explore the included examples:
-- `basic.ts` - Simple chat completions
-- `streaming.ts` - Real-time streaming responses
-- `chat.ts` - Multi-turn conversations with context
-- `metadata.ts` - Custom usage tracking and analytics
-
-### Step 5: Project Structure
+```
+Model: sonar-pro
+Streaming response:
 
-Recommended structure for your Perplexity AI project:
+[Streaming text appears here in real-time]
 
+✓ Streaming completed
 ```
-your-project/
-├── .env                    # Your API keys (DON'T COMMIT!)
-├── .env.example           # Template for others
-├── .gitignore            # Include .env
-├── package.json
-├── src/
-│   ├── perplexity/
-│   │   ├── client.ts     # Perplexity client setup
-│   │   └── prompts.ts    # Your prompts
-│   └── index.ts
-└── tests/
-    └── perplexity.test.ts
-```
 
-## Available Examples
+---
+
+### 3. Multi-turn Chat
+
+**Location**: `examples/chat.ts`
 
-### basic.ts - Start Here
+**What it demonstrates:**
 
-Simple chat completion with automatic usage tracking.
+- Conversation history management
+- Context-aware responses
+- Multi-message interactions
 
-**Features:**
-- Basic configuration initialization
-- Simple chat completion request
-- Automatic metering to Revenium
+**Run it:**
 
-**Run:**
 ```bash
-npm run example:basic
+npm run example:chat
 ```
 
-### streaming.ts
+**Expected output:**
 
-Real-time streaming responses with usage tracking.
+```
+--- Turn 1 ---
+User: What is the capital of France?
+Assistant: [Response]
 
-**Features:**
-- Streaming chat completions
-- Real-time content delivery
-- Automatic tracking when stream completes
+--- Turn 2 ---
+User: What is its population?
+Assistant: [Response]
 
-**Run:**
-```bash
-npm run example:streaming
+✓ Chat completed - Total tokens used: 120
 ```
 
-### chat.ts
+---
 
-Multi-turn conversations with context.
+### 4. Custom Metadata
 
-**Features:**
-- Conversation history management
-- Context-aware responses
-- Multi-message interactions
-
-**Run:**
-```bash
-npm run example:chat
-```
+**Location**: `examples/metadata.ts`
 
-### metadata.ts
+**What it demonstrates:**
 
-Custom usage metadata for advanced tracking.
+- Custom metadata tracking
+- Business context in metering
+- Subscriber and organization tracking
 
-**Features:**
-- Custom subscriber information
-- Organization and product tracking
-- Quality scoring
-- Business analytics integration
+**Run it:**
 
-**Run:**
 ```bash
 npm run example:metadata
 ```
 
-## TypeScript Integration Patterns
-
-### Pattern A: Direct Import (Recommended)
+**Expected output:**
 
-```typescript
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion
-} from "@revenium/perplexity";
+```
+✓ Chat Completion Successful
+Response: [AI response]
+Model: sonar-pro
+Tokens Used: 50 (prompt: 10, completion: 40)
+Metadata tracked: subscriber, organization, product, agent, trace
 ```
 
-### Pattern B: Manual Configuration
+**Note:** Custom metadata (subscriber, organizationId, productId, agent, traceId) is automatically sent to Revenium in the background.
 
-```typescript
-import {
-  initializeRevenium,
-  initializePerplexity,
-  createChatCompletion
-} from "@revenium/perplexity";
+---
 
 // Manual configuration
 initializeRevenium({
-  apiKey: process.env.REVENIUM_METERING_API_KEY!,
-  baseUrl: "https://api.revenium.io/meter/v2"
+meteringApiKey: process.env.REVENIUM_METERING_API_KEY!,
+meteringBaseUrl:
+process.env.REVENIUM_METERING_BASE_URL || "https://api.revenium.ai",
 });
 
-initializePerplexity({
-  apiKey: process.env.PERPLEXITY_API_KEY!
-});
+**Location**: `examples/advanced-features.ts`
+
+**What it demonstrates:**
+
+- Streaming with metadata
+- Multiple model comparisons
+- Advanced configuration
+
+**Run it:**
+
+```bash
+npm run example:advanced
 ```
 
-### Pattern C: With Custom Metadata
-
-```typescript
-const result = await createChatCompletion({
-  messages: [{ role: "user", content: "Hello" }],
-  model: "sonar-pro",
-  usageMetadata: {
-    subscriberId: "user-123",
-    subscriberEmail: "user@example.com",
-    organizationId: "acme-corp",
-    productId: "chat-app"
-  }
-});
+**Expected output:**
+
 ```
+=== Advanced Features Example ===
+
+--- Streaming Responses ---
+Model: sonar-pro
+Response:
+[Streaming text appears here in real-time]
+✓ Streaming completed
+
+--- Comprehensive Metadata Tracking ---
+Response: [First 100 characters]...
+✓ Metadata tracked successfully
+
+--- Multiple Model Types ---
+Using sonar (lightweight search)...
+Response: [First 80 characters]...
+
+Using sonar-reasoning (real-time reasoning)...
+Response: [First 80 characters]...
+
+✓ Multiple models demonstrated
+
+=== All Advanced Features Demonstrated ===
+```
+
+---
+
+### 6. Getting Started
+
+**Location**: `examples/getting_started.ts`
+
+**What it demonstrates:**
+
+- Quick start example
+- Minimal configuration
+- Basic usage pattern
+
+**Run it:**
+
+```bash
+npm run example:getting-started
+```
+
+---
 
 ## Troubleshooting
 
-### Common Issues
+### "Missing API Key" Error
+
+Make sure you've created a `.env` file with your API keys:
+
+```bash
+# Check if .env exists
+ls .env
 
-1. **Module not found**: Ensure you've run `npm install @revenium/perplexity`
-2. **Environment variables not loading**: Verify your `.env` file exists and `dotenv` is configured
-3. **API key errors**: Check both Perplexity and Revenium API keys are valid
-4. **TypeScript errors**: Ensure you have `tsx` or `ts-node` installed for TypeScript projects
+# Verify it has the required keys
+cat .env
+```
 
-### Debug Mode
+### "Module not found" Error
 
-Enable debug logging to troubleshoot issues:
+Install dependencies first:
 
 ```bash
-DEBUG=true npm run example:basic
+npm install
 ```
 
-### Expected Output
+### "Requests not being tracked"
+
+1. Check your `.env` file has correct values:
+
+   - `PERPLEXITY_API_KEY` is set
+   - `REVENIUM_METERING_API_KEY` is set
+   - `REVENIUM_METERING_BASE_URL` is set to `https://api.revenium.ai`
 
-When running examples successfully:
+2. Enable debug logging:
+
+```bash
+DEBUG=true npm run example:basic
 ```
-Basic Chat Completion Example
 
-Initializing configurations...
-Configurations initialized
+### TypeScript Errors
 
-Creating chat completion...
-Chat completion created
+Ensure you have TypeScript and tsx installed:
 
-Response: [AI response here]
-Usage: { prompt_tokens: X, completion_tokens: Y, total_tokens: Z }
+```bash
+npm install -D typescript tsx @types/node
 ```
 
-## JavaScript Playground
+---
 
-For JavaScript users, see the `playground/` directory for CommonJS versions of all examples:
+## Getting Your API Keys
 
-- `playground/basic.js`
-- `playground/streaming.js`
-- `playground/chat.js`
-- `playground/metadata.js`
+### Perplexity API Key
+
+1. Go to [Perplexity AI Settings](https://www.perplexity.ai/settings/api)
+2. Create a new API key
+3. Add to `.env` as `PERPLEXITY_API_KEY`
+
+### Revenium API Key
+
+1. Sign up at [Revenium](https://ai.revenium.io)
+2. Create a new API key in your dashboard
+3. Add to `.env` as `REVENIUM_METERING_API_KEY`
+
+---
 
 ## Support
 
-- Documentation: https://docs.revenium.io
-- GitHub Issues: https://github.com/revenium/revenium-middleware-perplexity-node/issues
-- Email: support@revenium.io
+For issues or questions:
+
+- [GitHub Issues](https://github.com/revenium/revenium-middleware-perplexity-node/issues)
+- [Documentation](https://docs.revenium.io)
+- Contact: Reach out to the Revenium team for additional support

package/examples/advanced-features.ts

@@ -0,0 +1,148 @@
+/**
+ * Advanced Features Example
+ *
+ * This example demonstrates advanced middleware features:
+ * - Streaming responses with real-time content
+ * - Comprehensive metadata for analytics
+ * - Multiple model types (search, reasoning, research)
+ * - Session and quality tracking
+ *
+ * For complete documentation, see:
+ * https://revenium.readme.io/reference/meter_ai_completion
+ */
+
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  createStreamingChatCompletion,
+  UsageMetadata,
+} from "../src";
+
+async function demonstrateStreaming() {
+  console.log("\n--- Streaming Responses ---");
+  const usageMetadata: UsageMetadata = {
+    subscriber: { id: "user-streaming-demo" },
+    traceId: "streaming-session-" + Date.now(),
+    taskType: "list-generation",
+  };
+
+  const result = await createStreamingChatCompletion({
+    messages: [
+      {
+        role: "user",
+        content: "List the first 3 planets in our solar system.",
+      },
+    ],
+    model: "sonar-pro",
+    maxTokens: 400,
+    usageMetadata,
+  });
+
+  console.log(`Model: ${result.model}`);
+  console.log("Response: ");
+
+  let fullContent = "";
+  for await (const chunk of result.stream) {
+    const content = chunk.choices[0]?.delta?.content || "";
+    if (content) {
+      process.stdout.write(content);
+      fullContent += content;
+    }
+  }
+
+  console.log("\n✓ Streaming completed\n");
+}
+
+async function demonstrateComprehensiveMetadata() {
+  console.log("\n--- Comprehensive Metadata Tracking ---");
+
+  const usageMetadata: UsageMetadata = {
+    traceId: "session-advanced-demo-" + Date.now(),
+    taskType: "educational-query",
+    subscriber: {
+      id: "user-456",
+      email: "advanced-user@example.com",
+      credential: {
+        name: "premium-api-key",
+        value: "key-premium-abc123",
+      },
+    },
+    organizationId: "org-enterprise-789",
+    subscriptionId: "sub-enterprise-2024",
+    productId: "learning-platform",
+    agent: "educational-assistant-v2",
+    responseQualityScore: 0.92,
+  };
+
+  const result = await createChatCompletion({
+    messages: [
+      {
+        role: "user",
+        content: "What is machine learning?",
+      },
+    ],
+    model: "sonar-pro",
+    maxTokens: 400,
+    usageMetadata,
+  });
+
+  console.log(`Response: ${result.content.substring(0, 100)}...`);
+  console.log(`✓ Metadata tracked successfully\n`);
+}
+
+async function demonstrateMultipleModels() {
+  console.log("\n--- Multiple Model Types ---");
+
+  const usageMetadata: UsageMetadata = {
+    subscriber: { id: "model-comparison-user" },
+    taskType: "weather-search",
+  };
+
+  // Search model
+  console.log("Using sonar (lightweight search)...");
+  const searchResult = await createChatCompletion({
+    messages: [{ role: "user", content: "Current weather in Tokyo" }],
+    model: "sonar-pro",
+    maxTokens: 400,
+    usageMetadata,
+  });
+  console.log(`Response: ${searchResult.content.substring(0, 80)}...`);
+
+  // Reasoning model
+  console.log("\nUsing sonar-reasoning (real-time reasoning)...");
+  const reasoningResult = await createChatCompletion({
+    messages: [
+      { role: "user", content: "Why is the sky blue? Explain briefly." },
+    ],
+    model: "sonar-reasoning",
+    maxTokens: 400,
+    usageMetadata: {
+      ...usageMetadata,
+      taskType: "reasoning-query",
+    },
+  });
+  console.log(`Response: ${reasoningResult.content.substring(0, 80)}...`);
+
+  console.log("\n✓ Multiple models demonstrated\n");
+}
+
+async function main() {
+  console.log("\n=== Advanced Features Example ===");
+
+  // Initialize configurations
+  initializeReveniumFromEnv();
+  initializePerplexityFromEnv();
+
+  // Demonstrate features
+  await demonstrateStreaming();
+  await demonstrateComprehensiveMetadata();
+  await demonstrateMultipleModels();
+
+  console.log("=== All Advanced Features Demonstrated ===\n");
+}
+
+main().catch((error) => {
+  console.error("\nError:", error.message);
+  process.exit(1);
+});