@revenium/perplexity 2.0.4 → 2.0.5

package/dist/types/utils/stop-reason-mapper.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stop Reason Mapper Utilities
+ *
+ * Centralized stop reason mapping logic using lookup tables
+ * instead of nested conditionals. Based on the good example
+ * from the anthropic-node middleware.
+ */
+/**
+ * Map provider stop reasons to Revenium stop reasons
+ *
+ * This replaces the nested if/switch logic with a clean lookup table approach.
+ * Based on the good example from the anthropic-node middleware.
+ *
+ * @param providerStopReason - Stop reason from the AI provider
+ * @param logger - Optional logger for warnings about unknown reasons
+ * @returns Standardized Revenium stop reason
+ */
+export declare function mapStopReason(providerStopReason: string | null | undefined, logger?: {
+    warn: (message: string, ...args: any[]) => void;
+}): string;
+/**
+ * Get all supported stop reasons for documentation/testing
+ */
+export declare function getSupportedStopReasons(): string[];
+/**
+ * Check if a stop reason is supported
+ */
+export declare function isStopReasonSupported(reason: string): boolean;
+//# sourceMappingURL=stop-reason-mapper.d.ts.map

package/dist/types/utils/stop-reason-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-reason-mapper.d.ts","sourceRoot":"","sources":["../../../src/utils/stop-reason-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgCH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC7C,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CAAE,GAC3D,MAAM,CAYR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAElD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/types/utils/transaction-id.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Transaction ID Generator
+ *
+ * Generates unique transaction IDs for tracking requests.
+ * Format: txn_{timestamp}_{random}
+ */
+/**
+ * Generate a unique transaction ID
+ *
+ * @returns A unique transaction ID in format: txn_{timestamp}_{random}
+ *
+ */
+export declare function generateTransactionId(): string;
+//# sourceMappingURL=transaction-id.d.ts.map

package/dist/types/utils/transaction-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-id.d.ts","sourceRoot":"","sources":["../../../src/utils/transaction-id.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C"}

package/dist/types/utils/url-builder.d.ts

@@ -0,0 +1,22 @@
+/**
+ * URL Builder Utilities
+ *
+ * Centralized URL construction logic to eliminate nested conditionals.
+ * Replaces the complex URL building logic from tracking.ts.
+ */
+/**
+ * Build Revenium API URL with proper path handling
+ *
+ * @param baseUrl - The base URL from configuration (may include /meter or /meter/v2)
+ * @param endpoint - The API endpoint to append (e.g., '/ai/completions')
+ * @returns Complete URL for the API call
+ */
+export declare function buildReveniumUrl(baseUrl: string, endpoint: string): string;
+/**
+ * Validate URL format
+ *
+ * @param url - URL to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidUrl(url: string): boolean;
+//# sourceMappingURL=url-builder.d.ts.map

package/dist/types/utils/url-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-builder.d.ts","sourceRoot":"","sources":["../../../src/utils/url-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA2B1E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C"}

package/examples/README.md

@@ -1,322 +1,226 @@
-# Running Examples - Revenium Middleware for Perplexity (Node.js)
+# Revenium Perplexity Middleware - Examples
 
-This guide shows you how to run the Node.js/TypeScript examples in this repository.
+This directory contains examples demonstrating how to use the Revenium Perplexity middleware.
 
 ## Prerequisites
 
-- Node.js 20+ installed
-- Perplexity API key
-- Revenium API key
+Before running the examples, make sure you have:
 
-## Setup
-
-### 1. Clone the Repository
-
-```bash
-git clone https://github.com/revenium/revenium-middleware-perplexity-node.git
-cd revenium-middleware-perplexity-node
-```
-
-### 2. Install Dependencies
-
-```bash
-npm install
-```
+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)
 
-### 3. Configure Environment Variables
-
-Create a `.env` file in the root directory:
+## Setup
 
-```bash
-# Create .env file
-cp .env.example .env
-```
+1. **Clone the repository** (if you haven't already):
 
-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.
+   ```bash
+   git clone https://github.com/revenium/revenium-middleware-perplexity-node.git
+   cd revenium-middleware-perplexity-node
+   ```
 
-**Replace the placeholder values with your actual keys!**
+2. **Install dependencies**:
 
-## Running Examples
+   ```bash
+   npm install
+   ```
 
-### Available Examples
+3. **Configure environment variables**:
 
-```bash
-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
-```
+   Copy the `.env.example` file to `.env` and edit it with your API keys:
 
-## Example Structure
+   ```bash
+   cp .env.example .env
+   ```
 
-```
-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
-```
+   See [.env.example](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/.env.example) for all available configuration options.
 
-## Examples Included
+## Examples
 
-### 1. Basic Usage
+### 1. Getting Started
 
-**Location**: `examples/basic.ts`
+**File:** `getting_started.ts`
 
-**What it demonstrates:**
+The simplest example to get you started with Revenium tracking:
 
-- Simple chat completion
-- Automatic metering
-- Basic error handling
+- Initialize the middleware
+- Create a basic chat completion
+- Display response and usage metrics
 
-**Run it:**
+**Run:**
 
 ```bash
-npm run example:basic
+npm run example:getting-started
+# or
+npx tsx examples/getting_started.ts
 ```
 
-**Expected output:**
+**What it does:**
 
-```
-✓ Chat Completion Successful
-Response: [AI response here]
-Model: sonar-pro
-Tokens Used: 50 (prompt: 10, completion: 40)
-```
+- Loads configuration from environment variables
+- Creates a simple chat completion request
+- Automatically sends metering data to Revenium API
+- Displays the response
 
 ---
 
-### 2. Streaming
+### 2. Basic Usage
 
-**Location**: `examples/streaming.ts`
+**File:** `basic.ts`
 
-**What it demonstrates:**
+Demonstrates standard Perplexity API usage:
 
-- Real-time streaming responses
-- Token tracking for streamed content
-- Automatic usage tracking when stream completes
+- Chat completions with metadata
+- Simple metadata tracking
 
-**Run it:**
+**Run:**
 
 ```bash
-npm run example:streaming
-```
-
-**Expected output:**
-
+npm run example:basic
+# or
+npx tsx examples/basic.ts
 ```
-Model: sonar-pro
-Streaming response:
 
-[Streaming text appears here in real-time]
+**What it does:**
 
-✓ Streaming completed
-```
+- Creates chat completions with metadata tracking
+- Demonstrates basic metadata usage
 
 ---
 
-### 3. Multi-turn Chat
+### 3. Metadata
 
-**Location**: `examples/chat.ts`
+**File:** `metadata.ts`
 
-**What it demonstrates:**
+Demonstrates all available metadata fields:
 
-- Conversation history management
-- Context-aware responses
-- Multi-message interactions
+- Complete metadata structure
+- All optional fields documented
+- Subscriber information
 
-**Run it:**
+**Run:**
 
 ```bash
-npm run example:chat
+npm run example:metadata
+# or
+npx tsx examples/metadata.ts
 ```
 
-**Expected output:**
+**What it does:**
 
-```
---- Turn 1 ---
-User: What is the capital of France?
-Assistant: [Response]
+- Shows all available metadata fields
+- Demonstrates subscriber tracking
+- Includes organization and product tracking
 
---- Turn 2 ---
-User: What is its population?
-Assistant: [Response]
+**Metadata fields supported:**
 
-✓ Chat completed - Total tokens used: 120
-```
+- `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`)
 
 ---
 
-### 4. Custom Metadata
+### 4. Streaming
 
-**Location**: `examples/metadata.ts`
+**File:** `stream.ts`
 
-**What it demonstrates:**
+Demonstrates streaming responses:
 
-- Custom metadata tracking
-- Business context in metering
-- Subscriber and organization tracking
+- Real-time token streaming
+- Accumulating responses
+- Streaming metrics
 
-**Run it:**
+**Run:**
 
 ```bash
-npm run example:metadata
+npm run example:stream
+# or
+npx tsx examples/stream.ts
 ```
 
-**Expected output:**
+**What it does:**
 
-```
-✓ Chat Completion Successful
-Response: [AI response]
-Model: sonar-pro
-Tokens Used: 50 (prompt: 10, completion: 40)
-Metadata tracked: subscriber, organization, product, agent, trace
-```
-
-**Note:** Custom metadata (subscriber, organizationId, productId, agent, traceId) is automatically sent to Revenium in the background.
+- Creates a streaming chat completion
+- Displays tokens as they arrive in real-time
+- Tracks streaming metrics
+- Sends metering data after stream completes
 
 ---
 
-// Manual configuration
-initializeRevenium({
-meteringApiKey: process.env.REVENIUM_METERING_API_KEY!,
-meteringBaseUrl:
-process.env.REVENIUM_METERING_BASE_URL || "https://api.revenium.ai",
-});
+### 5. Advanced Features
 
-**Location**: `examples/advanced-features.ts`
+**File:** `advanced.ts`
 
-**What it demonstrates:**
+Demonstrates advanced Perplexity features:
 
-- Streaming with metadata
-- Multiple model comparisons
-- Advanced configuration
+- Multi-turn conversations
+- Different temperature settings
+- Multiple Perplexity models
 
-**Run it:**
+**Run:**
 
 ```bash
 npm run example:advanced
+# or
+npx tsx examples/advanced.ts
 ```
 
-**Expected output:**
+**What it does:**
 
-```
-=== 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 ===
-```
+- Demonstrates multi-turn conversation with system prompt
+- Shows creative responses with higher temperature
+- Uses sonar-reasoning model for complex reasoning tasks
 
 ---
 
-### 6. Getting Started
+## Common Issues
 
-**Location**: `examples/getting_started.ts`
+### "Client not initialized" error
 
-**What it demonstrates:**
+**Solution:** Make sure to call `Initialize()` before using `GetClient()`.
 
-- Quick start example
-- Minimal configuration
-- Basic usage pattern
+### "REVENIUM_METERING_API_KEY is required" error
 
-**Run it:**
+**Solution:** Set the `REVENIUM_METERING_API_KEY` environment variable in your `.env` file.
 
-```bash
-npm run example:getting-started
-```
-
----
+### "invalid Revenium API key format" error
 
-## Troubleshooting
+**Solution:** Revenium API keys should start with `hak_`. Check your API key format.
 
-### "Missing API Key" Error
+### Environment variables not loading
 
-Make sure you've created a `.env` file with your API keys:
+**Solution:** Make sure your `.env` file is in the project root directory and contains the required variables.
 
-```bash
-# Check if .env exists
-ls .env
+### Perplexity API errors
 
-# Verify it has the required keys
-cat .env
-```
+**Solution:** Make sure you have set `PERPLEXITY_API_KEY` in your `.env` file and that it starts with `pplx-`.
 
-### "Module not found" Error
+### Debug Mode
 
-Install dependencies first:
+Enable detailed logging to troubleshoot issues:
 
 ```bash
-npm install
-```
-
-### "Requests not being tracked"
-
-1. Check your `.env` file has correct values:
+# In .env file
+REVENIUM_DEBUG=true
 
-   - `PERPLEXITY_API_KEY` is set
-   - `REVENIUM_METERING_API_KEY` is set
-   - `REVENIUM_METERING_BASE_URL` is set to `https://api.revenium.ai`
-
-2. Enable debug logging:
-
-```bash
-DEBUG=true npm run example:basic
-```
-
-### TypeScript Errors
-
-Ensure you have TypeScript and tsx installed:
-
-```bash
-npm install -D typescript tsx @types/node
+# Then run examples
+npm run example:getting-started
 ```
 
----
-
-## Getting Your API Keys
-
-### Perplexity API Key
+## Next Steps
 
-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`
-
----
+- 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:
 
-- [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
+- Documentation: https://docs.revenium.io
+- 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);