@revenium/perplexity 2.0.3 → 2.0.4

package/README.md

@@ -3,586 +3,91 @@
 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)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![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
+- **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
 
-## Package Migration
+## Getting Started
 
-This package has been renamed from `revenium-middleware-perplexity-node` to `@revenium/perplexity` for better organization and simpler naming.
-
-### Migration Steps
-
-If you're upgrading from the old package:
-
-```bash
-# Uninstall the old package
-npm uninstall revenium-middleware-perplexity-node
-
-# Install the new package
-npm install @revenium/perplexity
-```
-
-**Update your imports:**
-
-```typescript
-// Old import
-import "revenium-middleware-perplexity-node";
-
-// New import
-import "@revenium/perplexity";
-```
-
-All functionality remains exactly the same - only the package name has changed.
-
-## Table of Contents
-
-- [Installation](https://github.com/revenium/revenium-middleware-perplexity-node#-installation)
-- [Three Ways to Use This Middleware](https://github.com/revenium/revenium-middleware-perplexity-node#-three-ways-to-use-this-middleware)
-  - [Option 1: New Project with npm Package](https://github.com/revenium/revenium-middleware-perplexity-node#option-1-new-project-with-npm-package-recommended)
-  - [Option 2: Clone and Use Locally](https://github.com/revenium/revenium-middleware-perplexity-node#option-2-clone-and-use-locally)
-  - [Option 3: Add to Existing Project](https://github.com/revenium/revenium-middleware-perplexity-node#option-3-add-to-existing-project)
-- [Quick Start](https://github.com/revenium/revenium-middleware-perplexity-node#-quick-start)
-- [API Reference](https://github.com/revenium/revenium-middleware-perplexity-node#-api-reference)
-- [Examples](https://github.com/revenium/revenium-middleware-perplexity-node#-examples)
-- [Environment Variables](https://github.com/revenium/revenium-middleware-perplexity-node#-environment-variables)
-
-## Installation
+### Quick Start
 
 ```bash
-npm install @revenium/perplexity
+npm install @revenium/perplexity dotenv
 ```
 
-## Three Ways to Use This Middleware
+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).
 
-### Option 1: New Project with npm Package (Recommended)
+### Step-by-Step Guide
 
-**Best for:** Starting a new project or adding Perplexity with Revenium to an existing project.
+The following guide walks you through creating a new project from scratch:
 
-#### Step 1: Create a new project
+#### 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 the middleware
+#### Step 2: Install Dependencies
 
 ```bash
+# Install Revenium middleware and Perplexity dependencies
 npm install @revenium/perplexity dotenv
-```
-
-#### Step 3: Create `.env` file
-
-```env
-# Perplexity API Configuration
-PERPLEXITY_API_KEY=your_perplexity_api_key
-
-# Revenium Metering Configuration
-REVENIUM_METERING_API_KEY=your_revenium_api_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-```
-
-#### Step 4: Create `index.js`
-
-```javascript
-const {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-  PERPLEXITY_MODELS,
-} = require("@revenium/perplexity");
-
-async function main() {
-  // Initialize configurations
-  initializeReveniumFromEnv();
-  initializePerplexityFromEnv();
-
-  // Create a chat completion
-  const result = await createChatCompletion({
-    messages: [{ role: "user", content: "What is the capital of France?" }],
-    model: PERPLEXITY_MODELS.SONAR_PRO,
-  });
-
-  console.log("Response:", result.content);
-  console.log("Tokens used:", result.usage.totalTokens);
-}
-
-main().catch(console.error);
-```
-
-#### Step 5: Run your project
-
-```bash
-node index.js
-```
-
----
-
-### Option 2: Clone and Use Locally
-
-**Best for:** Development, testing, or contributing to the middleware.
-
-#### Step 1: Clone the repository
-
-```bash
-git clone https://github.com/revenium/revenium-middleware-perplexity-node.git
-cd revenium-middleware-perplexity-node
-```
-
-#### Step 2: Install dependencies
-
-```bash
-npm install
-```
-
-#### Step 3: Create `.env` file
 
-```env
-# Perplexity API Configuration
-PERPLEXITY_API_KEY=your_perplexity_api_key
-
-# Revenium Metering Configuration
-REVENIUM_METERING_API_KEY=your_revenium_api_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+# For TypeScript projects (optional)
+npm install -D typescript tsx @types/node
 ```
 
-#### Step 4: Build the project
+#### Step 3: Setup Environment Variables
 
-```bash
-npm run build
-```
-
-#### Step 5: Run examples
-
-**TypeScript Examples:**
+Create a `.env` file in your project root:
 
 ```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   # Custom metadata
-```
+# Copy the example file
+cp .env.example .env
 
-**JavaScript Playground:**
-
-```bash
-npm run playground:basic      # Basic chat completion
-npm run playground:streaming  # Streaming response
-npm run playground:chat       # Multi-turn conversation
-npm run playground:metadata   # Custom metadata
+# Then edit .env with your actual API keys
 ```
 
-#### Step 6: Use in your own code
-
-After building, you can import from the local build:
+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.
 
-```javascript
-const {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-} = require("./dist/cjs");
+**Replace the placeholder values with your actual keys!**
 
-// Your code here...
-```
-
----
+#### Step 4: Follow the Examples
 
-### Option 3: Add to Existing Project
+See [examples/README.md](https://github.com/revenium/revenium-middleware-perplexity-node/blob/HEAD/examples/README.md) for complete examples and setup instructions.
 
-**Best for:** Integrating Perplexity with Revenium into an existing Node.js project.
-
-#### Step 1: Install the middleware
+**Cloned from GitHub?** Run examples with:
 
 ```bash
-npm install @revenium/perplexity
-```
-
-#### Step 2: Add environment variables
-
-Add to your existing `.env` file:
-
-```env
-# Perplexity API Configuration
-PERPLEXITY_API_KEY=your_perplexity_api_key
-
-# Revenium Metering Configuration
-REVENIUM_METERING_API_KEY=your_revenium_api_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-```
-
-#### Step 3: Initialize in your application
-
-**For CommonJS projects:**
-
-```javascript
-require("dotenv").config();
-const {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-  PERPLEXITY_MODELS,
-} = require("@revenium/perplexity");
-
-// Initialize once at app startup
-initializeReveniumFromEnv();
-initializePerplexityFromEnv();
-
-// Use anywhere in your app
-async function askPerplexity(question) {
-  const result = await createChatCompletion({
-    messages: [{ role: "user", content: question }],
-    model: PERPLEXITY_MODELS.SONAR_PRO,
-  });
-  return result.content;
-}
+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
 ```
 
-**For ES Modules projects:**
-
-```javascript
-import "dotenv/config";
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-  PERPLEXITY_MODELS,
-} from "@revenium/perplexity";
-
-// Initialize once at app startup
-initializeReveniumFromEnv();
-initializePerplexityFromEnv();
-
-// Use anywhere in your app
-export async function askPerplexity(question) {
-  const result = await createChatCompletion({
-    messages: [{ role: "user", content: question }],
-    model: PERPLEXITY_MODELS.SONAR_PRO,
-  });
-  return result.content;
-}
-```
-
-**For TypeScript projects:**
-
-```typescript
-import "dotenv/config";
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-  PERPLEXITY_MODELS,
-  type ChatCompletionResult,
-} from "@revenium/perplexity";
-
-// Initialize once at app startup
-initializeReveniumFromEnv();
-initializePerplexityFromEnv();
-
-// Use anywhere in your app
-export async function askPerplexity(question: string): Promise<string> {
-  const result: ChatCompletionResult = await createChatCompletion({
-    messages: [{ role: "user", content: question }],
-    model: PERPLEXITY_MODELS.SONAR_PRO,
-  });
-  return result.content;
-}
-```
+**Browse online:** [`examples/` directory](https://github.com/revenium/revenium-middleware-perplexity-node/tree/HEAD/examples)
 
 ---
 
-## Quick Start
-
-### 1. Set up environment variables
-
-Create a `.env` file in your project root:
-
-```env
-# Perplexity API Configuration
-PERPLEXITY_API_KEY=your_perplexity_api_key
-
-# Revenium Metering Configuration
-REVENIUM_METERING_API_KEY=your_revenium_api_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-```
-
-### 2. Initialize and use
-
-```typescript
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-  PERPLEXITY_MODELS,
-} from "@revenium/perplexity";
-
-// Initialize configurations
-initializeReveniumFromEnv();
-initializePerplexityFromEnv();
-
-// Create a chat completion
-const result = await createChatCompletion({
-  messages: [{ role: "user", content: "What is the capital of France?" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-});
-
-console.log(result.content);
-// Output: "The capital of France is Paris."
-```
-
-## API Reference
-
-### Configuration
-
-#### `initializeReveniumFromEnv()`
-
-Initialize Revenium configuration from environment variables.
-
-```typescript
-const config = initializeReveniumFromEnv();
-```
-
-#### `initializePerplexityFromEnv()`
-
-Initialize Perplexity configuration from environment variables.
-
-```typescript
-const config = initializePerplexityFromEnv();
-```
-
-#### `initializeRevenium(config)`
-
-Initialize Revenium with custom configuration.
-
-```typescript
-initializeRevenium({
-  meteringApiKey: "your_api_key",
-  meteringBaseUrl: "https://api.revenium.io/meter",
-  teamId: "your_team_id", // Optional
-});
-```
-
-#### `initializePerplexity(config)`
-
-Initialize Perplexity with custom configuration.
-
-```typescript
-initializePerplexity({
-  apiKey: "your_perplexity_api_key",
-  baseUrl: "https://api.perplexity.ai", // Optional
-});
-```
-
-### Chat Completions
-
-#### `createChatCompletion(params)`
-
-Create a chat completion with automatic metering.
-
-```typescript
-const result = await createChatCompletion({
-  messages: [
-    { role: "system", content: "You are a helpful assistant." },
-    { role: "user", content: "Hello!" },
-  ],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-  maxTokens: 100,
-  temperature: 0.7,
-  usageMetadata: {
-    // Optional
-    subscriber: { id: "user-123" },
-    organizationId: "org-456",
-    productId: "product-789",
-  },
-});
-
-console.log(result.content);
-console.log(result.usage);
-console.log(result.transactionId);
-```
-
-**Parameters:**
-
-- `messages` - Array of message objects with `role` and `content`
-- `model` - Perplexity model to use (see [Available Models](https://github.com/revenium/revenium-middleware-perplexity-node#available-models))
-- `maxTokens` - Maximum tokens to generate (optional)
-- `temperature` - Sampling temperature 0-2 (optional)
-- `topP` - Nucleus sampling parameter (optional)
-- `presencePenalty` - Presence penalty -2 to 2 (optional)
-- `frequencyPenalty` - Frequency penalty -2 to 2 (optional)
-- `usageMetadata` - Custom metadata for tracking (optional)
-
-**Returns:**
-
-```typescript
-{
-  content: string;
-  role: string;
-  finishReason: string | null;
-  usage: {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-  }
-  model: string;
-  transactionId: string;
-  rawResponse: PerplexityResponse;
-}
-```
-
-#### `createStreamingChatCompletion(params)`
-
-Create a streaming chat completion.
-
-```typescript
-const result = await createStreamingChatCompletion({
-  messages: [{ role: "user", content: "Count from 1 to 5" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-});
-
-for await (const chunk of result.stream) {
-  const content = chunk.choices[0]?.delta?.content || "";
-  process.stdout.write(content);
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  stream: AsyncGenerator<PerplexityStreamChunk>;
-  transactionId: string;
-  model: string;
-}
-```
-
-### Available Models
-
-```typescript
-import { PERPLEXITY_MODELS } from "@revenium/perplexity";
-
-// Online Models (with internet access)
-PERPLEXITY_MODELS.SONAR; // "sonar"
-PERPLEXITY_MODELS.SONAR_PRO; // "sonar-pro"
-PERPLEXITY_MODELS.SONAR_REASONING; // "sonar-reasoning"
-
-// Chat Models (offline)
-PERPLEXITY_MODELS.LLAMA_3_1_SONAR_SMALL_128K_CHAT; // "llama-3.1-sonar-small-128k-chat"
-PERPLEXITY_MODELS.LLAMA_3_1_SONAR_LARGE_128K_CHAT; // "llama-3.1-sonar-large-128k-chat"
-PERPLEXITY_MODELS.LLAMA_3_1_SONAR_HUGE_128K_CHAT; // "llama-3.1-sonar-huge-128k-chat"
-```
-
-### Utility Functions
-
-#### `disableRevenium()` / `enableRevenium()`
-
-Temporarily disable or enable Revenium metering.
-
-```typescript
-import { disableRevenium, enableRevenium } from "@revenium/perplexity";
-
-disableRevenium(); // Stop sending metering data
-// ... make API calls ...
-enableRevenium(); // Resume sending metering data
-```
-
-#### `generateTransactionId()`
-
-Generate a unique transaction ID.
-
-```typescript
-import { generateTransactionId } from "@revenium/perplexity";
-
-const txnId = generateTransactionId();
-```
-
-## Examples
-
-### Basic Chat Completion
-
-```typescript
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createChatCompletion,
-  PERPLEXITY_MODELS,
-} from "@revenium/perplexity";
-
-initializeReveniumFromEnv();
-initializePerplexityFromEnv();
-
-const result = await createChatCompletion({
-  messages: [{ role: "user", content: "What is the capital of France?" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-});
-
-console.log(result.content);
-```
-
-### Streaming Response
-
-```typescript
-const result = await createStreamingChatCompletion({
-  messages: [{ role: "user", content: "Write a short poem about AI" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-});
-
-for await (const chunk of result.stream) {
-  const content = chunk.choices[0]?.delta?.content || "";
-  process.stdout.write(content);
-}
-```
-
-### Multi-turn Conversation
-
-```typescript
-const messages = [
-  { role: "system", content: "You are a helpful assistant." },
-  { role: "user", content: "What is the capital of France?" },
-];
-
-const response1 = await createChatCompletion({
-  messages,
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-});
-
-messages.push({ role: "assistant", content: response1.content });
-messages.push({ role: "user", content: "What is its population?" });
-
-const response2 = await createChatCompletion({
-  messages,
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-});
-```
-
-### Custom Metadata
-
-```typescript
-const result = await createChatCompletion({
-  messages: [{ role: "user", content: "Hello!" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-  usageMetadata: {
-    subscriber: {
-      id: "user-123",
-      email: "user@example.com",
-    },
-    organizationId: "org-456",
-    productId: "premium-plan",
-    traceId: "trace-abc-123",
-  },
-});
-```
-
 ## What Gets Tracked
 
 The middleware automatically captures:
@@ -597,119 +102,34 @@ The middleware automatically captures:
 
 ## Advanced Usage
 
-### Streaming Responses
-
-```typescript
-import {
-  initializeReveniumFromEnv,
-  initializePerplexityFromEnv,
-  createStreamingChatCompletion,
-  PERPLEXITY_MODELS,
-} from "@revenium/perplexity";
-
-initializeReveniumFromEnv();
-initializePerplexityFromEnv();
-
-const result = await createStreamingChatCompletion({
-  messages: [{ role: "user", content: "Count from 1 to 5" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-  usageMetadata: {
-    subscriber: { id: "user-123" },
-    taskType: "counting-demo",
-  },
-});
-
-for await (const chunk of result.stream) {
-  const content = chunk.choices[0]?.delta?.content || "";
-  process.stdout.write(content);
-}
-```
+For advanced features including:
 
-### Custom Metadata Tracking
-
-Add business context to your AI usage:
-
-```typescript
-const customMetadata = {
-  subscriber: {
-    id: "user-789",
-    email: "user@company.com",
-    credential: {
-      name: "premium-user",
-      value: "tier-1",
-    },
-  },
-  organizationId: "org-456",
-  productId: "premium-plan",
-  taskType: "RESEARCH",
-  agent: "ResearchBot",
-  traceId: "session-123",
-  responseQualityScore: 9.2,
-};
-
-const result = await createChatCompletion({
-  messages: [{ role: "user", content: "Research AI trends" }],
-  model: PERPLEXITY_MODELS.SONAR_PRO,
-  usageMetadata: customMetadata,
-});
-```
+- **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
 
-### Usage Metadata Interface
-
-All metadata fields are optional:
-
-```typescript
-interface UsageMetadata {
-  traceId?: string; // Session or conversation ID
-  taskType?: string; // Type of AI task
-  organizationId?: string; // Organization/company ID
-  subscriptionId?: string; // Billing plan ID
-  productId?: string; // Your product/feature ID
-  agent?: string; // AI agent identifier
-  responseQualityScore?: number; // Quality score (0-1)
-  subscriber?: {
-    id?: string; // User ID from your system
-    email?: string; // User's email address
-    credential?: {
-      name?: string; // Credential name
-      value?: string; // Credential value
-    };
-  };
-}
-```
+See the **[Examples Guide](./examples/README.md)** for detailed documentation and working code examples.
 
-## Configuration Options
-
-### Environment Variables
-
-| Variable                     | Required | Default                         | Description                       |
-| ---------------------------- | -------- | ------------------------------- | --------------------------------- |
-| `PERPLEXITY_API_KEY`         | Yes      | -                               | Your Perplexity API key           |
-| `REVENIUM_METERING_API_KEY`  | Yes      | -                               | Your Revenium API key             |
-| `REVENIUM_METERING_BASE_URL` | Yes      | -                               | Revenium metering API base URL    |
-| `PERPLEXITY_API_BASE_URL`    | No       | `https://api.perplexity.ai`     | Perplexity API base URL           |
-| `DEBUG`                      | No       | `false`                         | Enable debug logging              |
-
-### Manual Configuration
-
-```typescript
-import {
-  initializeRevenium,
-  initializePerplexity,
-  createChatCompletion,
-} from "@revenium/perplexity";
-
-// Manual configuration
-initializeRevenium({
-  meteringApiKey: "hak_your_revenium_key",
-  meteringBaseUrl: "https://api.revenium.io/meter/v2",
-});
-
-initializePerplexity({
-  apiKey: "pplx_your_perplexity_key",
-  baseUrl: "https://api.perplexity.ai",
-});
-```
+### 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
 
@@ -718,24 +138,24 @@ initializePerplexity({
 #### "Missing API Key" Error
 
 ```bash
-# Make sure you've set the API keys
-export PERPLEXITY_API_KEY="pplx_your_actual_api_key"
-export REVENIUM_METERING_API_KEY="hak_your_actual_revenium_key"
+# Verify your .env file exists and has the required keys
+cat .env
 
-# Verify they're set
-echo $PERPLEXITY_API_KEY
-echo $REVENIUM_METERING_API_KEY
+# Or use .env.example as a template
+cp .env.example .env
+# Then edit .env with your actual keys
 ```
 
 #### "Requests not being tracked"
 
 ```bash
-# Verify Revenium configuration
-export REVENIUM_METERING_API_KEY="hak_your_actual_revenium_key"
-export REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter/v2"
-
 # 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
@@ -757,6 +177,10 @@ 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
@@ -768,9 +192,11 @@ This will show:
 
 - Initialization details
 - Configuration loading
-- API call information
+- API call information (with PII/credentials redacted)
 - Error details
 
+**Production environments must NEVER set DEBUG=true.**
+
 ## Project Structure
 
 ```
@@ -784,33 +210,12 @@ revenium-middleware-perplexity-node/
 │   ├── utils/                # Utility functions
 │   └── index.ts              # Main entry point
 ├── examples/                 # TypeScript examples
-├── playground/               # JavaScript examples
 └── dist/
     ├── cjs/                  # CommonJS build
     ├── esm/                  # ES Modules build
     └── types/                # TypeScript definitions
 ```
 
-## Running Examples
-
-### TypeScript Examples
-
-```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   # Custom metadata
-```
-
-### JavaScript Playground
-
-```bash
-npm run playground:basic      # Basic chat completion
-npm run playground:streaming  # Streaming response
-npm run playground:chat       # Multi-turn conversation
-npm run playground:metadata   # Custom metadata
-```
-
 ## How It Works
 
 1. **Initialization**: When you call `initializePerplexityFromEnv()` and `initializeReveniumFromEnv()`, the middleware sets up configurations
@@ -823,7 +228,7 @@ The middleware never blocks your application - if Revenium tracking fails, your
 
 ## Requirements
 
-- Node.js 16+
+- Node.js 20+
 - TypeScript 5.0+ (for TypeScript projects)
 - Revenium API key
 - Perplexity API key