@revenium/perplexity 2.0.3 → 2.0.5

package/examples/README.md

@@ -1,323 +1,226 @@
-# Revenium Perplexity AI Middleware Examples
+# Revenium Perplexity Middleware - Examples
 
-Comprehensive examples demonstrating how to use the @revenium/perplexity middleware with automatic usage tracking and metering.
+This directory contains examples demonstrating how to use the Revenium Perplexity middleware.
 
-## 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:
+Before running the examples, make sure you have:
 
-- **TypeScript projects**: Run examples directly with `tsx` or `ts-node`
-- **JavaScript projects**: See playground/ directory for JavaScript versions
+1. **Node.js 20 or later** installed
+2. **Revenium API Key** - Get one from [Revenium Dashboard](https://app.revenium.io)
+3. **Perplexity API Key** - Get one from [Perplexity Platform](https://www.perplexity.ai)
 
-**For npm users:** These examples are included in your `node_modules/@revenium/perplexity/examples/` directory after installation.
+## Setup
 
-**For GitHub users:** Clone the repository to run examples directly with the included npm scripts.
+1. **Clone the repository** (if you haven't already):
 
-## 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
-```
+   ```bash
+   npm install
+   ```
 
-### 2. Environment Setup
+3. **Configure environment variables**:
 
-Create a `.env` file in your project root:
+   Copy the `.env.example` file to `.env` and edit it with your API keys:
 
-```env
-# Required: Your Perplexity API key
-PERPLEXITY_API_KEY=pplx_your_perplexity_key
+   ```bash
+   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 all available configuration options.
 
-# Optional: Perplexity base URL (defaults to https://api.perplexity.ai)
-PERPLEXITY_API_BASE_URL=https://api.perplexity.ai
+## Examples
 
-# Optional: Enable debug logging
-DEBUG=true
-```
+### 1. Getting Started
 
-### 3. Run Examples
+**File:** `getting_started.ts`
 
-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
-```
+The simplest example to get you started with Revenium tracking:
+
+- Initialize the middleware
+- Create a basic chat completion
+- Display response and usage metrics
+
+**Run:**
 
-Or run all examples:
 ```bash
-npm test
+npm run example:getting-started
+# or
+npx tsx examples/getting_started.ts
 ```
 
-## Getting Started - Step by Step
+**What it does:**
 
-### Step 1: Create Your First Test
+- Loads configuration from environment variables
+- Creates a simple chat completion request
+- Automatically sends metering data to Revenium API
+- Displays the response
 
-**TypeScript:**
-```typescript
-// test-perplexity.ts
-import { config } from "dotenv";
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-} from "@revenium/perplexity";
+---
 
-config(); // Load .env file
+### 2. Basic Usage
 
-async function test() {
-  // Initialize configurations
-  initializeReveniumFromEnv();
-  initializePerplexityFromEnv();
+**File:** `basic.ts`
 
-  // Create chat completion
-  const result = await createChatCompletion({
-    messages: [{ role: "user", content: "Hello!" }],
-    model: "sonar-pro",
-  });
+Demonstrates standard Perplexity API usage:
 
-  console.log(result.choices[0].message.content);
-}
+- Chat completions with metadata
+- Simple metadata tracking
 
-test();
-```
+**Run:**
 
-**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();
+```bash
+npm run example:basic
+# or
+npx tsx examples/basic.ts
 ```
 
-### Step 2: Update package.json
+**What it does:**
 
-Add scripts to run your tests:
+- Creates chat completions with metadata tracking
+- Demonstrates basic metadata usage
 
-```json
-{
-  "scripts": {
-    "test:perplexity": "tsx test-perplexity.ts"
-  }
-}
-```
+---
 
-Or for JavaScript:
-```json
-{
-  "scripts": {
-    "test:perplexity": "node test-perplexity.js"
-  }
-}
-```
+### 3. Metadata
 
-### Step 3: Run Your Tests
+**File:** `metadata.ts`
+
+Demonstrates all available metadata fields:
+
+- Complete metadata structure
+- All optional fields documented
+- Subscriber information
+
+**Run:**
 
 ```bash
-npm run test:perplexity
+npm run example:metadata
+# or
+npx tsx examples/metadata.ts
 ```
 
-### Step 4: Explore Advanced Features
+**What it does:**
 
-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
+- Shows all available metadata fields
+- Demonstrates subscriber tracking
+- Includes organization and product tracking
 
-### Step 5: Project Structure
+**Metadata fields supported:**
 
-Recommended structure for your Perplexity AI project:
+- `traceId` - Session or conversation tracking identifier
+- `taskType` - Type of AI task being performed
+- `agent` - AI agent or bot identifier
+- `organizationId` - Organization identifier
+- `productId` - Product or service identifier
+- `subscriptionId` - Subscription tier identifier
+- `responseQualityScore` - Quality rating (0.0-1.0)
+- `subscriber` - Nested subscriber object with `id`, `email`, `credential` (with `name` and `value`)
 
-```
-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
+### 4. Streaming
 
-### basic.ts - Start Here
+**File:** `stream.ts`
 
-Simple chat completion with automatic usage tracking.
+Demonstrates streaming responses:
 
-**Features:**
-- Basic configuration initialization
-- Simple chat completion request
-- Automatic metering to Revenium
+- Real-time token streaming
+- Accumulating responses
+- Streaming metrics
 
 **Run:**
+
 ```bash
-npm run example:basic
+npm run example:stream
+# or
+npx tsx examples/stream.ts
 ```
 
-### streaming.ts
+**What it does:**
 
-Real-time streaming responses with usage tracking.
+- Creates a streaming chat completion
+- Displays tokens as they arrive in real-time
+- Tracks streaming metrics
+- Sends metering data after stream completes
 
-**Features:**
-- Streaming chat completions
-- Real-time content delivery
-- Automatic tracking when stream completes
+---
 
-**Run:**
-```bash
-npm run example:streaming
-```
+### 5. Advanced Features
 
-### chat.ts
+**File:** `advanced.ts`
 
-Multi-turn conversations with context.
+Demonstrates advanced Perplexity features:
 
-**Features:**
-- Conversation history management
-- Context-aware responses
-- Multi-message interactions
+- Multi-turn conversations
+- Different temperature settings
+- Multiple Perplexity models
 
 **Run:**
+
 ```bash
-npm run example:chat
+npm run example:advanced
+# or
+npx tsx examples/advanced.ts
 ```
 
-### metadata.ts
+**What it does:**
 
-Custom usage metadata for advanced tracking.
+- Demonstrates multi-turn conversation with system prompt
+- Shows creative responses with higher temperature
+- Uses sonar-reasoning model for complex reasoning tasks
 
-**Features:**
-- Custom subscriber information
-- Organization and product tracking
-- Quality scoring
-- Business analytics integration
+---
 
-**Run:**
-```bash
-npm run example:metadata
-```
+## Common Issues
 
-## TypeScript Integration Patterns
+### "Client not initialized" error
 
-### Pattern A: Direct Import (Recommended)
+**Solution:** Make sure to call `Initialize()` before using `GetClient()`.
 
-```typescript
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion
-} from "@revenium/perplexity";
-```
+### "REVENIUM_METERING_API_KEY is required" error
 
-### Pattern B: Manual Configuration
+**Solution:** Set the `REVENIUM_METERING_API_KEY` environment variable in your `.env` file.
 
-```typescript
-import {
-  initializeRevenium,
-  initializePerplexity,
-  createChatCompletion
-} from "@revenium/perplexity";
+### "invalid Revenium API key format" error
 
-// Manual configuration
-initializeRevenium({
-  apiKey: process.env.REVENIUM_METERING_API_KEY!,
-  baseUrl: "https://api.revenium.io/meter/v2"
-});
+**Solution:** Revenium API keys should start with `hak_`. Check your API key format.
 
-initializePerplexity({
-  apiKey: process.env.PERPLEXITY_API_KEY!
-});
-```
+### Environment variables not loading
 
-### 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"
-  }
-});
-```
-
-## Troubleshooting
+**Solution:** Make sure your `.env` file is in the project root directory and contains the required variables.
 
-### Common Issues
+### Perplexity API errors
 
-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
+**Solution:** Make sure you have set `PERPLEXITY_API_KEY` in your `.env` file and that it starts with `pplx-`.
 
 ### Debug Mode
 
-Enable debug logging to troubleshoot issues:
+Enable detailed logging to troubleshoot issues:
 
 ```bash
-DEBUG=true npm run example:basic
-```
-
-### Expected Output
-
-When running examples successfully:
-```
-Basic Chat Completion Example
-
-Initializing configurations...
-Configurations initialized
-
-Creating chat completion...
-Chat completion created
+# In .env file
+REVENIUM_DEBUG=true
 
-Response: [AI response here]
-Usage: { prompt_tokens: X, completion_tokens: Y, total_tokens: Z }
+# Then run examples
+npm run example:getting-started
 ```
 
-## JavaScript Playground
+## Next Steps
 
-For JavaScript users, see the `playground/` directory for CommonJS versions of all examples:
-
-- `playground/basic.js`
-- `playground/streaming.js`
-- `playground/chat.js`
-- `playground/metadata.js`
+- Check the [main README](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/README.md) for detailed documentation
+- Visit the [Revenium Dashboard](https://app.revenium.io) to view your metering data
+- See [.env.example](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/.env.example) for all configuration options
 
 ## Support
 
+For issues or questions:
+
 - Documentation: https://docs.revenium.io
-- GitHub Issues: https://github.com/revenium/revenium-middleware-perplexity-node/issues
 - Email: support@revenium.io

package/examples/advanced.ts

@@ -0,0 +1,123 @@
+/**
+ * Advanced Example
+ * Demonstrates advanced features like system prompts, conversation history,
+ * and different model parameters with Revenium Perplexity middleware.
+ */
+
+import { Initialize, GetClient, UsageMetadata } from "@revenium/perplexity";
+
+async function main() {
+  // Initialize middleware
+  Initialize();
+
+  // Get client
+  const client = GetClient();
+
+  // Metadata for tracking
+  const metadata: UsageMetadata = {
+    organizationId: "org-advanced-demo",
+    productId: "prod-perplexity-advanced",
+    taskType: "multi-turn-conversation",
+    subscriber: {
+      id: "user-advanced-001",
+      email: "advanced@example.com",
+    },
+  };
+
+  console.log("=== Advanced Perplexity Example ===\n");
+
+  // Example 1: Using system prompt and conversation history
+  console.log("1. Multi-turn conversation with system prompt:\n");
+
+  const response1 = await client
+    .chat()
+    .completions()
+    .create(
+      {
+        model: "sonar-pro",
+        messages: [
+          {
+            role: "system",
+            content:
+              "You are a helpful AI assistant that provides concise, accurate answers.",
+          },
+          {
+            role: "user",
+            content: "What is the capital of France?",
+          },
+          {
+            role: "assistant",
+            content: "The capital of France is Paris.",
+          },
+          {
+            role: "user",
+            content: "What is its population?",
+          },
+        ],
+        max_tokens: 500,
+        temperature: 0.7,
+      },
+      metadata
+    );
+
+  console.log(`Assistant: ${response1.choices[0].message.content}\n`);
+  console.log(`Tokens used: ${response1.usage?.total_tokens}\n`);
+
+  // Example 2: Using different temperature for creative responses
+  console.log("2. Creative response with higher temperature:\n");
+
+  const response2 = await client
+    .chat()
+    .completions()
+    .create(
+      {
+        model: "sonar-pro",
+        messages: [
+          {
+            role: "user",
+            content:
+              "Write a creative tagline for an AI company in 10 words or less.",
+          },
+        ],
+        max_tokens: 100,
+        temperature: 1.0, // Higher temperature for more creativity
+      },
+      {
+        ...metadata,
+        taskType: "creative-generation",
+      }
+    );
+
+  console.log(`Assistant: ${response2.choices[0].message.content}\n`);
+
+  // Example 3: Using sonar-reasoning for complex reasoning tasks
+  console.log("3. Complex reasoning with sonar-reasoning model:\n");
+
+  const response3 = await client
+    .chat()
+    .completions()
+    .create(
+      {
+        model: "sonar-reasoning",
+        messages: [
+          {
+            role: "user",
+            content:
+              "If a train travels 120 km in 2 hours, and then 180 km in 3 hours, what is its average speed for the entire journey?",
+          },
+        ],
+        max_tokens: 500,
+      },
+      {
+        ...metadata,
+        taskType: "reasoning",
+      }
+    );
+
+  console.log(`Assistant: ${response3.choices[0].message.content}\n`);
+  console.log(`Tokens used: ${response3.usage?.total_tokens}\n`);
+
+  console.log("\nAll usage data sent to Revenium! Check your dashboard");
+}
+
+main().catch(console.error);

package/examples/basic.ts

@@ -1,55 +1,45 @@
 /**
- * Basic Chat Completion Example
- * 
- * This example demonstrates how to use the Perplexity middleware
- * to create a simple chat completion with Revenium metering.
+ * Basic Example
+ * Demonstrates basic usage of Revenium Perplexity middleware.
  */
 
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-  PERPLEXITY_MODELS,
-} from "../src";
+import { Initialize, GetClient, UsageMetadata } from "@revenium/perplexity";
 
 async function main() {
-  console.log("Basic Chat Completion Example\n");
-
-  // Initialize configurations from environment variables
-  console.log("Initializing configurations...");
-  initializeReveniumFromEnv();
-  initializePerplexityFromEnv();
-  console.log("Configurations initialized\n");
-
-  // Create a simple chat completion
-  console.log("Creating chat completion...");
-  const result = await createChatCompletion({
-    messages: [
+  // Initialize middleware
+  Initialize();
+
+  // Get client
+  const client = GetClient();
+  const metadata: UsageMetadata = {
+    organizationId: "org-basic-demo",
+    productId: "prod-perplexity-basic",
+  };
+
+  // Create chat completion
+  const response = await client
+    .chat()
+    .completions()
+    .create(
       {
-        role: "user",
-        content: "What is the capital of France? Answer in one sentence.",
+        model: "sonar-pro",
+        messages: [
+          {
+            role: "user",
+            content:
+              "Say hello in Spanish and explain why Spanish is a beautiful language in 2-3 sentences.",
+          },
+        ],
+        max_tokens: 1000,
       },
-    ],
-    model: PERPLEXITY_MODELS.SONAR_PRO,
-    maxTokens: 100,
-  });
-
-  console.log("\nResponse:");
-  console.log("─────────────────────────────────────────");
-  console.log(`Content: ${result.content}`);
-  console.log(`Model: ${result.model}`);
-  console.log(`Transaction ID: ${result.transactionId}`);
-  console.log(`\nToken Usage:`);
-  console.log(`  - Prompt Tokens: ${result.usage.promptTokens}`);
-  console.log(`  - Completion Tokens: ${result.usage.completionTokens}`);
-  console.log(`  - Total Tokens: ${result.usage.totalTokens}`);
-  console.log("─────────────────────────────────────────\n");
-
-  console.log("Example completed successfully!");
+      metadata
+    );
+
+  // Display response
+  if (response.choices.length > 0) {
+    console.log(`Assistant: ${response.choices[0].message.content}`);
+  }
+  console.log("\nUsage data sent to Revenium! Check your dashboard");
 }
 
-main().catch((error) => {
-  console.error("Error:", error.message);
-  process.exit(1);
-});
-
+main().catch(console.error);