@revenium/perplexity 2.0.2 → 2.0.3

package/examples/README.md

@@ -0,0 +1,323 @@
+# Revenium Perplexity AI Middleware Examples
+
+Comprehensive examples demonstrating how to use the @revenium/perplexity middleware with automatic usage tracking and metering.
+
+## TypeScript-First Approach
+
+These examples are written in TypeScript to showcase type-safe development patterns. You can use them in both TypeScript and JavaScript projects:
+
+- **TypeScript projects**: Run examples directly with `tsx` or `ts-node`
+- **JavaScript projects**: See playground/ directory for JavaScript versions
+
+**For npm users:** These examples are included in your `node_modules/@revenium/perplexity/examples/` directory after installation.
+
+**For GitHub users:** Clone the repository to run examples directly with the included npm scripts.
+
+## Quick Start
+
+### 1. Installation
+
+```bash
+npm install @revenium/perplexity dotenv
+npm install --save-dev tsx  # For TypeScript projects
+```
+
+### 2. Environment Setup
+
+Create a `.env` file in your project root:
+
+```env
+# Required: Your Perplexity API key
+PERPLEXITY_API_KEY=pplx_your_perplexity_key
+
+# Required: Revenium metering API key
+REVENIUM_METERING_API_KEY=hak_your_revenium_key
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter/v2
+
+# Optional: Perplexity base URL (defaults to https://api.perplexity.ai)
+PERPLEXITY_API_BASE_URL=https://api.perplexity.ai
+
+# Optional: Enable debug logging
+DEBUG=true
+```
+
+### 3. Run 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
+```
+
+Or run all examples:
+```bash
+npm test
+```
+
+## Getting Started - Step by Step
+
+### Step 1: Create Your First Test
+
+**TypeScript:**
+```typescript
+// test-perplexity.ts
+import { config } from "dotenv";
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+} from "@revenium/perplexity";
+
+config(); // Load .env file
+
+async function test() {
+  // Initialize configurations
+  initializeReveniumFromEnv();
+  initializePerplexityFromEnv();
+
+  // Create chat completion
+  const result = await createChatCompletion({
+    messages: [{ role: "user", content: "Hello!" }],
+    model: "sonar-pro",
+  });
+
+  console.log(result.choices[0].message.content);
+}
+
+test();
+```
+
+**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();
+```
+
+### Step 2: Update package.json
+
+Add scripts to run your tests:
+
+```json
+{
+  "scripts": {
+    "test:perplexity": "tsx test-perplexity.ts"
+  }
+}
+```
+
+Or for JavaScript:
+```json
+{
+  "scripts": {
+    "test:perplexity": "node test-perplexity.js"
+  }
+}
+```
+
+### Step 3: Run Your Tests
+
+```bash
+npm run test:perplexity
+```
+
+### Step 4: Explore Advanced Features
+
+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
+
+Recommended structure for your Perplexity AI project:
+
+```
+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
+
+### basic.ts - Start Here
+
+Simple chat completion with automatic usage tracking.
+
+**Features:**
+- Basic configuration initialization
+- Simple chat completion request
+- Automatic metering to Revenium
+
+**Run:**
+```bash
+npm run example:basic
+```
+
+### streaming.ts
+
+Real-time streaming responses with usage tracking.
+
+**Features:**
+- Streaming chat completions
+- Real-time content delivery
+- Automatic tracking when stream completes
+
+**Run:**
+```bash
+npm run example:streaming
+```
+
+### chat.ts
+
+Multi-turn conversations with context.
+
+**Features:**
+- Conversation history management
+- Context-aware responses
+- Multi-message interactions
+
+**Run:**
+```bash
+npm run example:chat
+```
+
+### metadata.ts
+
+Custom usage metadata for advanced tracking.
+
+**Features:**
+- Custom subscriber information
+- Organization and product tracking
+- Quality scoring
+- Business analytics integration
+
+**Run:**
+```bash
+npm run example:metadata
+```
+
+## TypeScript Integration Patterns
+
+### Pattern A: Direct Import (Recommended)
+
+```typescript
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion
+} from "@revenium/perplexity";
+```
+
+### Pattern B: Manual Configuration
+
+```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"
+});
+
+initializePerplexity({
+  apiKey: process.env.PERPLEXITY_API_KEY!
+});
+```
+
+### 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
+
+### Common Issues
+
+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
+
+### Debug Mode
+
+Enable debug 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
+
+Response: [AI response here]
+Usage: { prompt_tokens: X, completion_tokens: Y, total_tokens: Z }
+```
+
+## JavaScript Playground
+
+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`
+
+## Support
+
+- Documentation: https://docs.revenium.io
+- GitHub Issues: https://github.com/revenium/revenium-middleware-perplexity-node/issues
+- Email: support@revenium.io

package/examples/basic.ts

@@ -0,0 +1,55 @@
+/**
+ * Basic Chat Completion Example
+ * 
+ * This example demonstrates how to use the Perplexity middleware
+ * to create a simple chat completion with Revenium metering.
+ */
+
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+} from "../src";
+
+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: [
+      {
+        role: "user",
+        content: "What is the capital of France? Answer in one sentence.",
+      },
+    ],
+    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!");
+}
+
+main().catch((error) => {
+  console.error("Error:", error.message);
+  process.exit(1);
+});
+

package/examples/chat.ts

@@ -0,0 +1,87 @@
+/**
+ * Multi-turn Chat Example
+ * 
+ * This example demonstrates how to have a multi-turn conversation
+ * with the Perplexity middleware.
+ */
+
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+  type PerplexityMessage,
+} from "../src";
+
+async function main() {
+  console.log("Multi-turn Chat Example\n");
+
+  // Initialize configurations from environment variables
+  console.log("Initializing configurations...");
+  initializeReveniumFromEnv();
+  initializePerplexityFromEnv();
+  console.log("Configurations initialized\n");
+
+  // Start a conversation
+  const messages: PerplexityMessage[] = [
+    {
+      role: "system",
+      content: "You are a helpful assistant that provides concise answers.",
+    },
+    {
+      role: "user",
+      content: "What is the capital of France?",
+    },
+  ];
+
+  console.log("Turn 1:");
+  console.log("User: What is the capital of France?");
+
+  const response1 = await createChatCompletion({
+    messages,
+    model: PERPLEXITY_MODELS.SONAR_PRO,
+    maxTokens: 100,
+  });
+
+  console.log(`Assistant: ${response1.content}\n`);
+
+  // Continue the conversation
+  messages.push({
+    role: "assistant",
+    content: response1.content,
+  });
+
+  messages.push({
+    role: "user",
+    content: "What is its population?",
+  });
+
+  console.log("Turn 2:");
+  console.log("User: What is its population?");
+
+  const response2 = await createChatCompletion({
+    messages,
+    model: PERPLEXITY_MODELS.SONAR_PRO,
+    maxTokens: 100,
+  });
+
+  console.log(`Assistant: ${response2.content}\n`);
+
+  console.log("Summary:");
+  console.log("─────────────────────────────────────────");
+  console.log(`Total turns: 2`);
+  console.log(`Transaction ID 1: ${response1.transactionId}`);
+  console.log(`Transaction ID 2: ${response2.transactionId}`);
+  console.log(
+    `Total tokens used: ${response1.usage.totalTokens + response2.usage.totalTokens}`
+  );
+  console.log("─────────────────────────────────────────\n");
+
+  console.log("Chat completed successfully!");
+}
+
+main().catch((error) => {
+  console.error("Error:", error.message);
+  process.exit(1);
+});
+

package/examples/metadata.ts

@@ -0,0 +1,72 @@
+/**
+ * Custom Metadata Example
+ * 
+ * This example demonstrates how to pass custom metadata
+ * for tracking and metering purposes.
+ */
+
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createChatCompletion,
+  PERPLEXITY_MODELS,
+} from "../src";
+
+async function main() {
+  console.log("Custom Metadata Example\n");
+
+  // Initialize configurations from environment variables
+  console.log("Initializing configurations...");
+  const reveniumConfig = initializeReveniumFromEnv();
+  initializePerplexityFromEnv();
+  console.log("Configurations initialized\n");
+
+  // Create a chat completion with custom metadata
+  console.log("Creating chat completion with custom metadata...");
+  const result = await createChatCompletion({
+    messages: [
+      {
+        role: "user",
+        content: "What is 2 + 2?",
+      },
+    ],
+    model: PERPLEXITY_MODELS.SONAR_PRO,
+    maxTokens: 50,
+    usageMetadata: {
+      subscriber: {
+        id: "user-123",
+        email: "user@example.com",
+      },
+      organizationId: "org-example",
+      productId: "product-premium",
+      traceId: "trace-abc-123",
+    },
+  });
+
+  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("\nCustom Metadata:");
+  console.log(`  - Subscriber ID: user-123`);
+  console.log(`  - Organization ID: org-example`);
+  console.log(`  - Product ID: product-premium`);
+  console.log(`  - Trace ID: trace-abc-123`);
+  console.log("─────────────────────────────────────────\n");
+
+  console.log("Example completed successfully!");
+  console.log(
+    "Check your Revenium dashboard to see the metering data with custom metadata."
+  );
+}
+
+main().catch((error) => {
+  console.error("Error:", error.message);
+  process.exit(1);
+});
+

package/examples/streaming.ts

@@ -0,0 +1,61 @@
+/**
+ * Streaming Chat Completion Example
+ * 
+ * This example demonstrates how to use streaming responses
+ * with the Perplexity middleware and Revenium metering.
+ */
+
+import {
+  initializeReveniumFromEnv,
+  initializePerplexityFromEnv,
+  createStreamingChatCompletion,
+  PERPLEXITY_MODELS,
+} from "../src";
+
+async function main() {
+  console.log("Streaming Chat Completion Example\n");
+
+  // Initialize configurations from environment variables
+  console.log("Initializing configurations...");
+  initializeReveniumFromEnv();
+  initializePerplexityFromEnv();
+  console.log("Configurations initialized\n");
+
+  // Create a streaming chat completion
+  console.log("Creating streaming chat completion...");
+  const result = await createStreamingChatCompletion({
+    messages: [
+      {
+        role: "user",
+        content: "Count from 1 to 5 slowly, one number per line.",
+      },
+    ],
+    model: PERPLEXITY_MODELS.SONAR_PRO,
+    maxTokens: 100,
+  });
+
+  console.log("\nStreaming Response:");
+  console.log("─────────────────────────────────────────");
+  console.log(`Transaction ID: ${result.transactionId}`);
+  console.log(`Model: ${result.model}\n`);
+
+  // Process the stream
+  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─────────────────────────────────────────");
+  console.log(`\nFull Response: ${fullContent}`);
+  console.log("\nStreaming completed successfully!");
+}
+
+main().catch((error) => {
+  console.error("Error:", error.message);
+  process.exit(1);
+});
+