@revenium/perplexity 1.0.6 → 1.0.7

package/README.md

@@ -31,9 +31,15 @@ import { createPerplexityClient } from "@revenium/perplexity";
 config();
 
 async function example() {
-  // Create client instance
+  // Create client instance (uses environment variables by default)
   const client = createPerplexityClient();
 
+  // Or create with custom API key and base URL
+  const customClient = createPerplexityClient(
+    "your-api-key",
+    "https://api.perplexity.ai"
+  );
+
   // Make a chat completion
   const response = await client.createChatCompletion({
     model: "sonar-pro",
@@ -97,8 +103,11 @@ REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter/v2
 # Optional: Perplexity base URL (defaults to https://api.perplexity.ai)
 PERPLEXITY_BASE_URL=https://api.perplexity.ai
 
-# Optional: Enable verbose logging
+# Optional: Enable verbose logging for debugging
 REVENIUM_VERBOSE_STARTUP=true
+
+# Optional: Set log level (DEBUG, INFO, WARNING, ERROR)
+REVENIUM_LOG_LEVEL=INFO
 ```
 
 ## 📚 Examples
@@ -152,14 +161,22 @@ const stream = await client.createStreamingChatCompletion({
       content: "Write a creative story about AI",
     },
   ],
+  // Optional: Include usage metadata for tracking
+  usageMetadata: {
+    traceId: "story-generation-001",
+    taskType: "creative-writing",
+    subscriberEmail: "user@example.com",
+  },
 });
 
+console.log("📝 Streaming response:");
 for await (const chunk of stream) {
   const content = chunk.choices[0]?.delta?.content;
   if (content) {
     process.stdout.write(content);
   }
 }
+console.log("\n✅ Streaming completed!");
 ```
 
 ## 📊 Usage Metadata
@@ -247,14 +264,33 @@ npm run run-all-examples
 
 ### PerplexityClient
 
-#### `createPerplexityClient(apiKey?: string)`
+#### `createPerplexityClient(apiKey?: string, baseUrl?: string)`
 
 Creates a new Perplexity client instance.
 
+**Parameters:**
+
+- `apiKey` (optional): Your Perplexity API key. If not provided, uses `PERPLEXITY_API_KEY` environment variable.
+- `baseUrl` (optional): Custom base URL for Perplexity API. If not provided, uses `PERPLEXITY_BASE_URL` environment variable or defaults to `https://api.perplexity.ai`.
+
 ```typescript
+// Using environment variables
 const client = createPerplexityClient();
-// or
+
+// With custom API key
 const client = createPerplexityClient("your-api-key");
+
+// With custom API key and base URL
+const client = createPerplexityClient(
+  "your-api-key",
+  "https://api.perplexity.ai"
+);
+
+// With custom base URL only (uses env var for API key)
+const client = createPerplexityClient(
+  undefined,
+  "https://custom-perplexity-endpoint.com"
+);
 ```
 
 #### `client.createChatCompletion(params)`
@@ -310,16 +346,74 @@ interface UsageMetadata {
 }
 ```
 
+## 🔧 Configuration Options
+
+### Client Configuration
+
+The `createPerplexityClient` function accepts two optional parameters:
+
+```typescript
+// All default configuration (uses environment variables)
+const client = createPerplexityClient();
+
+// Custom API key only
+const client = createPerplexityClient("your-custom-api-key");
+
+// Custom API key and base URL
+const client = createPerplexityClient(
+  "your-custom-api-key",
+  "https://custom-perplexity-endpoint.com"
+);
+
+// Custom base URL only (API key from environment)
+const client = createPerplexityClient(
+  undefined,
+  "https://custom-perplexity-endpoint.com"
+);
+```
+
+### Environment Variable Priority
+
+The client follows this priority order for configuration:
+
+1. **API Key**: Function parameter → `PERPLEXITY_API_KEY` environment variable
+2. **Base URL**: Function parameter → `PERPLEXITY_BASE_URL` environment variable → Default (`https://api.perplexity.ai`)
+
 ## 🔧 Integration Tips
 
 ### Express.js
 
 Load environment variables first, create a separate Perplexity module, and use the patched instance everywhere.
 
+```typescript
+// perplexity.js
+import { config } from "dotenv";
+import { createPerplexityClient } from "@revenium/perplexity";
+
+config();
+export const perplexityClient = createPerplexityClient();
+```
+
 ### Next.js
 
 Use global variables to prevent re-initialization, works with both Pages and App Router.
 
+```typescript
+// lib/perplexity.ts
+import { createPerplexityClient } from "@revenium/perplexity";
+
+declare global {
+  var perplexityClient: ReturnType<typeof createPerplexityClient> | undefined;
+}
+
+export const perplexityClient =
+  globalThis.perplexityClient ?? createPerplexityClient();
+
+if (process.env.NODE_ENV !== "production") {
+  globalThis.perplexityClient = perplexityClient;
+}
+```
+
 ### Serverless
 
 Implement singleton pattern for cold starts, handle CORS for browser clients.
@@ -335,6 +429,8 @@ Validate environment variables at startup, add health checks for orchestration.
 1. **Middleware not activating**: Ensure you're importing the package before creating client instances
 2. **Environment variables**: Verify all required environment variables are set
 3. **API keys**: Check that both Perplexity and Revenium API keys are valid
+4. **Custom base URL**: If using a custom base URL, ensure it's accessible and compatible with Perplexity API
+5. **Module imports**: Make sure you're using the correct import: `import { createPerplexityClient } from "@revenium/perplexity"`
 
 ### Debug Mode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenium/perplexity",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "NodeJS middleware for perplexity's AI API",
   "homepage": "https://github.com/revenium/revenium-middleware-perplexity-node#readme",
   "bugs": {

package/playground/basic.js

@@ -1,6 +1,6 @@
 import { createPerplexityClient } from "@revenium/perplexity";
 
-const basicExampl = async () => {
+const basicExample = async () => {
   console.log("\n🤖 Perplexity AI - Basic Client Example");
   console.log("=".repeat(50));
 
@@ -28,4 +28,4 @@ const basicExampl = async () => {
   }
 };
 
-basicExampl();
+basicExample();

package/playground/custom-config.js

@@ -0,0 +1,82 @@
+import { createPerplexityClient } from "@revenium/perplexity";
+
+async function customConfigExample() {
+  console.log("\n⚙️ Perplexity AI - Custom Configuration Example");
+  console.log("=".repeat(50));
+
+  try {
+    // Example 1: Using environment variables (default)
+    console.log("\n1️⃣ Using environment variables:");
+    const defaultClient = createPerplexityClient();
+    
+    const response1 = await defaultClient.createChatCompletion({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "Hello from default configuration!",
+        },
+      ],
+    });
+    console.log("✅ Default config response:", response1.choices[0]?.message?.content?.substring(0, 50) + "...");
+
+    // Example 2: Custom API key only
+    console.log("\n2️⃣ Using custom API key:");
+    const customKeyClient = createPerplexityClient(process.env.PERPLEXITY_API_KEY);
+    
+    const response2 = await customKeyClient.createChatCompletion({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "Hello from custom API key configuration!",
+        },
+      ],
+    });
+    console.log("✅ Custom key response:", response2.choices[0]?.message?.content?.substring(0, 50) + "...");
+
+    // Example 3: Custom API key and base URL
+    console.log("\n3️⃣ Using custom API key and base URL:");
+    const fullCustomClient = createPerplexityClient(
+      process.env.PERPLEXITY_API_KEY,
+      "https://api.perplexity.ai"
+    );
+    
+    const response3 = await fullCustomClient.createChatCompletion({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "Hello from fully custom configuration!",
+        },
+      ],
+    });
+    console.log("✅ Full custom response:", response3.choices[0]?.message?.content?.substring(0, 50) + "...");
+
+    // Example 4: Custom base URL only (API key from env)
+    console.log("\n4️⃣ Using custom base URL only:");
+    const customUrlClient = createPerplexityClient(
+      undefined,
+      "https://api.perplexity.ai"
+    );
+    
+    const response4 = await customUrlClient.createChatCompletion({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "Hello from custom URL configuration!",
+        },
+      ],
+    });
+    console.log("✅ Custom URL response:", response4.choices[0]?.message?.content?.substring(0, 50) + "...");
+
+    console.log("\n🎉 All configuration examples completed successfully!");
+    console.log("📊 All requests tracked by middleware regardless of configuration");
+
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+customConfigExample();

package/playground/metadata.js

@@ -0,0 +1,94 @@
+import { createPerplexityClient } from "@revenium/perplexity";
+
+async function metadataExample() {
+  console.log("\n📊 Perplexity AI - Metadata Tracking Example");
+  console.log("=".repeat(50));
+
+  try {
+    // Create client instance
+    const client = createPerplexityClient();
+
+    // Example 1: Basic metadata
+    console.log("\n1️⃣ Basic metadata tracking:");
+    const basicResponse = await client.createChatCompletion({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "Analyze this quarterly report for key insights",
+        },
+      ],
+      usageMetadata: {
+        traceId: "conv-28a7e9d4",
+        taskType: "document-analysis",
+        subscriberEmail: "user@example.com",
+        organizationId: "acme-corp",
+        subscriptionId: "premium-plan",
+      },
+    });
+
+    console.log(
+      "✅ Response:",
+      basicResponse.choices[0]?.message?.content?.substring(0, 100) + "..."
+    );
+
+    // Example 2: Advanced metadata
+    console.log("\n2️⃣ Advanced metadata tracking:");
+    const advancedResponse = await client.createChatCompletion({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "What are the latest developments in AI?",
+        },
+      ],
+      usageMetadata: {
+        traceId: "conv-advanced-123",
+        taskType: "research",
+        subscriberId: "user-12345",
+        subscriberCredentialName: "api-key-1",
+        productId: "business-intelligence",
+        agent: "research-assistant-v2",
+        responseQualityScore: 0.95,
+      },
+    });
+
+    console.log(
+      "✅ Response:",
+      advancedResponse.choices[0]?.message?.content?.substring(0, 100) + "..."
+    );
+
+    // Example 3: Streaming with metadata
+    console.log("\n3️⃣ Streaming with metadata:");
+    const stream = await client.createStreamingChatCompletion({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "Write a creative story about AI",
+        },
+      ],
+      usageMetadata: {
+        traceId: "conv-streaming-456",
+        taskType: "creative-writing",
+        organizationId: "creative-studio",
+        agent: "story-generator",
+      },
+    });
+
+    console.log("📝 Streaming response with metadata:");
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        process.stdout.write(content);
+      }
+    }
+
+    console.log("\n\n🎉 All metadata examples completed successfully!");
+    console.log("📊 All usage tracked with custom metadata");
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+metadataExample();

package/playground/multiple-models.js

@@ -0,0 +1,62 @@
+import { createPerplexityClient } from "@revenium/perplexity";
+
+async function multipleModelsExample() {
+  console.log("\n🔧 Perplexity AI - Multiple Models Example");
+  console.log("=".repeat(50));
+
+  try {
+    // Create client instance
+    const client = createPerplexityClient();
+
+    // Test different prompts with the same model
+    const testCases = [
+      {
+        name: "sonar-pro (Quantum Computing)",
+        description: "Latest and most capable model",
+        prompt: "Explain quantum computing in simple terms",
+      },
+      {
+        name: "sonar-pro (AI Developments)",
+        description: "Latest and most capable model",
+        prompt: "What are the latest developments in AI?",
+      },
+      {
+        name: "sonar-pro (Weather)",
+        description: "Latest and most capable model",
+        prompt: "What is the weather like today?",
+      },
+    ];
+
+    for (const testCase of testCases) {
+      console.log(`\n🤖 Testing: ${testCase.name}`);
+      console.log(`📝 Description: ${testCase.description}`);
+      console.log("-".repeat(40));
+
+      try {
+        const response = await client.createChatCompletion({
+          model: "sonar-pro",
+          messages: [
+            {
+              role: "user",
+              content: testCase.prompt,
+            },
+          ],
+        });
+
+        console.log("✅ Response:");
+        console.log(response.choices[0]?.message?.content?.substring(0, 200) + "...");
+        console.log("📊 Usage tracked by middleware");
+
+      } catch (error) {
+        console.log(`❌ Error with ${testCase.name}:`, error);
+      }
+    }
+
+    console.log("\n🎉 Multiple models example completed!");
+
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+multipleModelsExample();

package/playground/openai-client.js

@@ -0,0 +1,73 @@
+import { OpenAI } from "openai";
+
+// Import middleware to activate automatic tracking
+import "@revenium/perplexity";
+
+async function openaiClientExample() {
+  console.log("\n🤖 Perplexity AI - OpenAI Client Example");
+  console.log("=".repeat(50));
+
+  try {
+    // Create OpenAI client configured for Perplexity (like in basic example)
+    const client = new OpenAI({
+      apiKey: process.env.PERPLEXITY_API_KEY,
+      baseURL: "https://api.perplexity.ai",
+    });
+
+    console.log("✅ OpenAI client configured for Perplexity AI");
+    console.log("📊 Middleware automatically tracking all requests");
+
+    // Test different types of requests
+    console.log("\n1️⃣ Basic chat completion:");
+    const basicResponse = await client.chat.completions.create({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "What is the meaning of life, the universe and everything?",
+        },
+      ],
+    });
+    console.log("✅ Response:", basicResponse.choices[0]?.message?.content?.substring(0, 100) + "...");
+
+    console.log("\n2️⃣ Streaming chat completion:");
+    const stream = await client.chat.completions.create({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "Write a short poem about AI",
+        },
+      ],
+      stream: true,
+    });
+
+    console.log("📝 Streaming response:");
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        process.stdout.write(content);
+      }
+    }
+
+    console.log("\n\n3️⃣ Different prompt:");
+    const differentResponse = await client.chat.completions.create({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "Explain machine learning in one sentence",
+        },
+      ],
+    });
+    console.log("✅ Response:", differentResponse.choices[0]?.message?.content);
+
+    console.log("\n🎉 All examples completed successfully!");
+    console.log("📊 All usage automatically tracked by middleware");
+
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+openaiClientExample();

package/playground/streaming.js

@@ -0,0 +1,40 @@
+import { createPerplexityClient } from "@revenium/perplexity";
+
+async function streamingExample() {
+  console.log("\n📊 Perplexity AI - Streaming Example");
+  console.log("=".repeat(50));
+
+  try {
+    const client = createPerplexityClient();
+    console.log("\n3️⃣ Streaming with metadata:");
+    const stream = await client.createStreamingChatCompletion({
+      model: "sonar-pro",
+      messages: [
+        {
+          role: "user",
+          content: "Write a creative story about AI",
+        },
+      ],
+      usageMetadata: {
+        traceId: "conv-streaming-456",
+        taskType: "creative-writing",
+        organizationId: "creative-studio",
+        agent: "story-generator",
+      },
+    });
+
+    console.log("📝 Streaming response with metadata:");
+    for await (const chunk of stream) {
+      const content = chunk.choices[0]?.delta?.content;
+      if (content) {
+        process.stdout.write(content);
+      }
+    }
+
+    console.log("\n\n🎉 Streaming completed!");
+  } catch (error) {
+    console.error("❌ Error:", error);
+  }
+}
+
+streamingExample();