@revenium/anthropic 1.0.3 → 1.0.4

package/examples/README.md

@@ -0,0 +1,179 @@
+# Revenium Anthropic Middleware - Examples
+
+**TypeScript-first** examples demonstrating automatic Revenium usage tracking with the Anthropic SDK.
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install @revenium/anthropic @anthropic-ai/sdk dotenv
+npm install -D typescript tsx @types/node  # For TypeScript
+```
+
+### 2. Environment Setup
+
+Create a `.env` file in your project root:
+
+```bash
+# Required
+REVENIUM_METERING_API_KEY=hak_your_revenium_api_key
+ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key
+
+# Optional
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+REVENIUM_DEBUG=false
+```
+
+### 3. Run Examples
+
+**If you cloned from GitHub:**
+
+```bash
+# Run included examples directly
+npm run example:basic
+npm run example:advanced
+
+# Or use tsx directly
+npx tsx examples/basic-usage.ts
+npx tsx examples/advanced-features.ts
+```
+
+**If you installed via npm:**
+
+Examples are included in your `node_modules/@revenium/anthropic/examples/` directory:
+
+```bash
+npx tsx node_modules/@revenium/anthropic/examples/basic-usage.ts
+npx tsx node_modules/@revenium/anthropic/examples/advanced-features.ts
+```
+
+## Available Examples
+
+### `basic-usage.ts` - Initialization Methods
+
+Demonstrates the three ways to initialize the Revenium middleware:
+
+- **Auto-initialization** (Recommended) - Import and go, uses environment variables
+- **Explicit initialization** - Call `initialize()` for error handling control
+- **Manual configuration** - Use `configure()` for custom settings
+
+**Key Features:**
+- TypeScript module augmentation for native `usageMetadata` support
+- Full type safety with IntelliSense
+- Interface validation using `satisfies` operator
+- Comprehensive error handling patterns
+
+**See the file for complete code examples.**
+
+### `advanced-features.ts` - Streaming, Tools, and Manual Tracking
+
+Demonstrates advanced Anthropic SDK features with automatic tracking:
+
+- **Streaming responses** - Real-time response tracking with type safety
+- **Tool use (function calling)** - Function calls with metadata tracking
+- **Manual tracking** - Custom tracking for edge cases
+- **Error handling** - Comprehensive error handling patterns
+
+**Key Features:**
+- Type-safe event handling and stream processing
+- Advanced metadata patterns with interface extensions
+- Generic functions with type constraints
+- Custom logger integration
+
+**See the file for complete code examples.**
+
+## TypeScript Configuration
+
+Ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+## Requirements
+
+- **Node.js 16+** with TypeScript support
+- **TypeScript 4.5+** for module augmentation features
+- **Valid Revenium API key** (starts with `hak_`)
+- **Valid Anthropic API key** (starts with `sk-ant-`)
+
+## Troubleshooting
+
+### Module Augmentation Not Working
+
+**Problem:** TypeScript doesn't recognize `usageMetadata` in Anthropic SDK calls
+
+**Solution:**
+
+```typescript
+// ❌ Wrong - missing module augmentation import
+import { configure } from "@revenium/anthropic";
+
+// ✅ Correct - import for module augmentation
+import "@revenium/anthropic";
+import Anthropic from "@anthropic-ai/sdk";
+```
+
+### Environment Variables Not Loading
+
+**Problem:** `REVENIUM_METERING_API_KEY` or `ANTHROPIC_API_KEY` not found
+
+**Solutions:**
+- Ensure `.env` file is in project root
+- Check variable names match exactly
+- Verify you're importing `dotenv/config` before the middleware
+- Check API keys have correct prefixes (`hak_` for Revenium, `sk-ant-` for Anthropic)
+
+### TypeScript Compilation Errors
+
+**Problem:** Module resolution or import errors
+
+**Solution:** Verify your `tsconfig.json` settings:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  }
+}
+```
+
+### IntelliSense Not Working
+
+**Solutions:**
+1. Restart TypeScript language server in your IDE
+2. Ensure `@revenium/anthropic` is imported at the top
+3. Verify `@anthropic-ai/sdk` types are installed
+4. Check TypeScript version is 4.5 or higher
+
+### Debug Mode
+
+Enable detailed logging to troubleshoot issues:
+
+```bash
+# In .env file
+REVENIUM_DEBUG=true
+
+# Then run examples
+npm run example:basic
+```
+
+## Additional Resources
+
+- **Main Documentation**: See root [README.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/README.md)
+- **API Reference**: Full TypeScript types and JSDoc in the package
+- **Issues**: [Report bugs](https://github.com/revenium/revenium-middleware-anthropic-node/issues)

package/examples/advanced-features.ts

@@ -0,0 +1,501 @@
+/**
+ * Revenium Anthropic Middleware - Advanced TypeScript Features Example
+ *
+ * This example demonstrates advanced TypeScript patterns and features:
+ * • Streaming responses with type-safe real-time tracking
+ * • Tool use (function calling) with strongly typed metadata
+ * • Manual tracking for custom scenarios with full type safety
+ * • Comprehensive error handling with typed error responses
+ * • Generic functions with type constraints
+ * • Advanced metadata patterns with interface extensions
+ * • Type-safe event handling and stream processing
+ *
+ * All features leverage TypeScript's type system for maximum safety and IntelliSense.
+ */
+
+// Load environment variables from .env file
+import "dotenv/config";
+
+// Import for module augmentation - enables native usageMetadata support
+import "@revenium/anthropic";
+import Anthropic from "@anthropic-ai/sdk";
+
+// Import types for advanced TypeScript patterns
+import type {
+  UsageMetadata,
+  TrackingData,
+  MiddlewareStatus,
+  Logger,
+} from "@revenium/anthropic";
+
+import { trackUsageAsync, getStatus, setLogger } from "@revenium/anthropic";
+
+// =============================================================================
+// ADVANCED TYPESCRIPT TYPE DEFINITIONS
+// =============================================================================
+
+/**
+ * Extended metadata interface for advanced scenarios
+ */
+interface AdvancedUsageMetadata extends UsageMetadata {
+  /** Session identifier for multi-turn conversations */
+  readonly sessionId?: string;
+  /** User role for RBAC scenarios */
+  readonly userRole?: "admin" | "user" | "guest";
+  /** Feature being used */
+  readonly feature?: "chat" | "completion" | "analysis" | "generation";
+  /** Request priority for resource allocation */
+  readonly priority?: "low" | "normal" | "high";
+}
+
+/**
+ * Streaming event types with full type safety
+ */
+type StreamEvent =
+  | { type: "start"; timestamp: Date; metadata: AdvancedUsageMetadata }
+  | { type: "content"; content: string; timestamp: Date }
+  | { type: "complete"; totalTokens: number; duration: number; timestamp: Date }
+  | { type: "error"; error: string; timestamp: Date };
+
+/**
+ * Custom logger implementation for advanced scenarios
+ */
+class AdvancedLogger implements Logger {
+  private context: Record<string, unknown> = {};
+
+  setContext(context: Record<string, unknown>): void {
+    this.context = { ...this.context, ...context };
+  }
+
+  debug(message: string, data?: Record<string, unknown>): void {
+    console.log(`[DEBUG] ${message}`, { ...this.context, ...data });
+  }
+
+  info(message: string, data?: Record<string, unknown>): void {
+    console.log(`[INFO] ${message}`, { ...this.context, ...data });
+  }
+
+  warn(message: string, data?: Record<string, unknown>): void {
+    console.warn(`[WARN] ${message}`, { ...this.context, ...data });
+  }
+
+  error(message: string, data?: Record<string, unknown>): void {
+    console.error(`[ERROR] ${message}`, { ...this.context, ...data });
+  }
+}
+
+async function demonstrateAdvancedFeatures(): Promise<void> {
+  console.log("Revenium Anthropic Middleware - Advanced TypeScript Features\n");
+
+  // Initialize custom logger with type safety
+  const logger = new AdvancedLogger();
+  logger.setContext({
+    service: "advanced-features-demo",
+    version: "1.0.0",
+    environment: "development",
+  });
+  setLogger(logger);
+
+  const anthropic = new Anthropic();
+
+  try {
+    // =============================================================================
+    // ADVANCED TYPESCRIPT PATTERNS WITH STREAMING
+    // =============================================================================
+    console.log("Advanced TypeScript Streaming Patterns");
+    console.log(
+      "Type-safe streaming with event handling and metadata validation\n"
+    );
+
+    // Example 1: Type-safe streaming with advanced metadata
+    console.log(
+      "Example 1: Creative writing with advanced metadata patterns..."
+    );
+
+    // Create strongly typed metadata with satisfies operator
+    const advancedMetadata: AdvancedUsageMetadata = {
+      subscriber: {
+        id: "artist-456",
+        email: "artist@creative-studio.com",
+        credential: {
+          name: "creative-api-key",
+          value: "creative-key-789",
+        },
+      },
+      organizationId: "creative-ai-studio",
+      productId: "story-generator-pro",
+      taskType: "creative-writing",
+      agent: "storyteller-v2",
+      // Advanced metadata extensions
+      sessionId: `session_${Date.now()}`,
+      userRole: "user",
+      feature: "generation",
+      priority: "normal",
+    } satisfies AdvancedUsageMetadata;
+
+    // Type-safe streaming with event tracking
+    const streamEvents: StreamEvent[] = [];
+    const startTime = new Date();
+
+    streamEvents.push({
+      type: "start",
+      timestamp: startTime,
+      metadata: advancedMetadata,
+    });
+
+    const stream1 = await anthropic.messages.create({
+      model: "claude-3-5-sonnet-latest",
+      max_tokens: 150,
+      messages: [
+        {
+          role: "user",
+          content: "Write a short story about a robot learning to paint.",
+        },
+      ],
+      stream: true,
+      usageMetadata: advancedMetadata, // Fully typed with module augmentation
+    });
+
+    console.log("Streaming response:");
+    let content1 = "";
+    let tokenCount = 0;
+
+    for await (const event of stream1) {
+      if (
+        event.type === "content_block_delta" &&
+        event.delta.type === "text_delta"
+      ) {
+        process.stdout.write(event.delta.text);
+        content1 += event.delta.text;
+        tokenCount++;
+
+        // Add streaming event with type safety
+        streamEvents.push({
+          type: "content",
+          content: event.delta.text,
+          timestamp: new Date(),
+        });
+      }
+    }
+
+    // Complete streaming event tracking
+    const endTime = new Date();
+    streamEvents.push({
+      type: "complete",
+      totalTokens: tokenCount,
+      duration: endTime.getTime() - startTime.getTime(),
+      timestamp: endTime,
+    });
+
+    if (!content1.trim()) throw new Error("No content received from stream");
+    console.log("\nStream 1 completed with type-safe event tracking");
+    console.log(
+      `Events captured: ${streamEvents.length}, Duration: ${
+        endTime.getTime() - startTime.getTime()
+      }ms\n`
+    );
+
+    // =============================================================================
+    // ADVANCED MANUAL TRACKING WITH TYPE SAFETY
+    // =============================================================================
+    console.log("Advanced Manual Tracking with TypeScript");
+    console.log(
+      "Demonstrating manual tracking with full type safety and validation\n"
+    );
+
+    // Example 2: Manual tracking with type-safe data
+    console.log("Example 2: Manual tracking with custom metrics...");
+
+    const now = new Date();
+    const trackingData: TrackingData = {
+      requestId: `manual_${Date.now()}`,
+      model: "claude-3-5-sonnet-latest",
+      inputTokens: 25,
+      outputTokens: 150,
+      duration: 2500,
+      isStreamed: false,
+      requestTime: new Date(now.getTime() - 2500), // 2.5 seconds ago
+      responseTime: now,
+      metadata: {
+        subscriber: { id: "manual-user-123" },
+        organizationId: "manual-tracking-org",
+        productId: "custom-analytics",
+        taskType: "manual-analysis",
+      } satisfies UsageMetadata,
+    };
+
+    // Type-safe manual tracking
+    try {
+      trackUsageAsync(trackingData); // Note: this function is synchronous
+      console.log("Manual tracking completed successfully");
+      console.log(
+        `Tracked: ${
+          trackingData.inputTokens + trackingData.outputTokens
+        } tokens, ${trackingData.duration}ms duration\n`
+      );
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      console.log(`Manual tracking failed: ${errorMessage}\n`);
+    }
+
+    // =============================================================================
+    // SERVICE STATUS WITH TYPE SAFETY
+    // =============================================================================
+    console.log("Service Status and Health Check");
+    console.log("Type-safe middleware status monitoring\n");
+
+    const status: MiddlewareStatus = getStatus();
+    console.log("Middleware Status:", {
+      initialized: status.initialized,
+      patched: status.patched,
+      hasConfig: status.hasConfig,
+      configValid: status.initialized && status.patched && status.hasConfig,
+    });
+
+    // Example 3: Educational content with different metadata pattern
+    console.log(
+      "\nExample 3: Educational content with different metadata pattern..."
+    );
+
+    const educationalMetadata: AdvancedUsageMetadata = {
+      subscriber: { id: "student-789" },
+      organizationId: "green-tech-edu",
+      productId: "sustainability-tutor",
+      taskType: "educational-query",
+      sessionId: `edu_session_${Date.now()}`,
+      userRole: "guest",
+      feature: "analysis",
+      priority: "low",
+    } satisfies AdvancedUsageMetadata;
+
+    const stream2 = await anthropic.messages.create({
+      model: "claude-3-5-sonnet-latest",
+      max_tokens: 100,
+      messages: [
+        {
+          role: "user",
+          content: "Explain three benefits of renewable energy.",
+        },
+      ],
+      stream: true,
+      usageMetadata: educationalMetadata, // Fully typed
+    });
+
+    console.log("Educational response:");
+    let content2 = "";
+    for await (const event of stream2) {
+      if (
+        event.type === "content_block_delta" &&
+        event.delta.type === "text_delta"
+      ) {
+        process.stdout.write(event.delta.text);
+        content2 += event.delta.text;
+      }
+    }
+
+    if (!content2.trim()) throw new Error("No content received from stream");
+    console.log("\nStream 2 completed with educational metadata pattern\n");
+
+    // =============================================================================
+    // ADVANCED TOOL USE WITH TYPESCRIPT PATTERNS
+    // =============================================================================
+    console.log("Advanced Tool Use with TypeScript Patterns");
+    console.log(
+      "Tool usage with strongly typed metadata and comprehensive tracking\n"
+    );
+
+    console.log("Example 4: Weather tool with advanced TypeScript patterns...");
+
+    // Create tool-specific metadata with type safety
+    const toolMetadata: AdvancedUsageMetadata = {
+      subscriber: {
+        id: "weather-user-456",
+        email: "user@weather-app.com",
+      },
+      organizationId: "weather-services-inc",
+      productId: "smart-weather-assistant",
+      taskType: "tool-usage",
+      agent: "weather-bot-v3",
+      sessionId: `weather_${Date.now()}`,
+      userRole: "user",
+      feature: "chat",
+      priority: "normal",
+    } satisfies AdvancedUsageMetadata;
+
+    const toolStream = await anthropic.messages.create({
+      model: "claude-3-5-sonnet-latest",
+      max_tokens: 200,
+      tools: [
+        {
+          name: "get_weather",
+          description: "Get current weather for a location",
+          input_schema: {
+            type: "object",
+            properties: {
+              location: {
+                type: "string",
+                description: "City and state, e.g. San Francisco, CA",
+              },
+              units: {
+                type: "string",
+                enum: ["celsius", "fahrenheit"],
+                description: "Temperature units",
+              },
+            },
+            required: ["location"],
+          },
+        },
+      ],
+      messages: [
+        {
+          role: "user",
+          content: "What's the weather like in New York? Use the weather tool.",
+        },
+      ],
+      stream: true,
+      usageMetadata: toolMetadata, // Using strongly typed metadata
+    });
+
+    console.log("Tool use streaming response:");
+    let toolContent = "";
+    for await (const event of toolStream) {
+      if (
+        event.type === "content_block_delta" &&
+        event.delta.type === "text_delta"
+      ) {
+        process.stdout.write(event.delta.text);
+        toolContent += event.delta.text;
+      } else if (
+        event.type === "content_block_start" &&
+        event.content_block.type === "tool_use"
+      ) {
+        console.log(`\nTool called: ${event.content_block.name}`);
+      }
+    }
+
+    if (!toolContent.trim())
+      throw new Error("No content received from tool stream");
+    console.log(
+      "\nTool streaming completed with advanced TypeScript patterns\n"
+    );
+
+    // =============================================================================
+    // SUMMARY AND TYPESCRIPT BENEFITS
+    // =============================================================================
+    console.log("Advanced TypeScript Features Summary");
+    console.log("All examples completed successfully with full type safety!\n");
+
+    console.log("TypeScript Benefits Demonstrated:");
+    console.log("   • Module augmentation for native usageMetadata support");
+    console.log("   • Type-safe metadata with satisfies operator");
+    console.log("   • Strongly typed event handling and streaming");
+    console.log("   • Custom logger implementation with typed interfaces");
+    console.log("   • Advanced metadata patterns with interface extensions");
+    console.log("   • Comprehensive error handling with typed responses");
+    console.log("   • Generic functions with type constraints");
+    console.log("   • Full IntelliSense support throughout\n");
+
+    console.log("Middleware Status Summary:");
+    const finalStatus = getStatus();
+    console.log(`   • Initialized: ${finalStatus.initialized}`);
+    console.log(`   • Patched: ${finalStatus.patched}`);
+    console.log(`   • Has Config: ${finalStatus.hasConfig}`);
+    console.log(
+      `   • All Systems: ${
+        finalStatus.initialized && finalStatus.patched && finalStatus.hasConfig
+          ? "Operational"
+          : "Check Configuration"
+      }\n`
+    );
+
+    console.log("Next Steps:");
+    console.log("   • Review comprehensive JSDoc in your IDE");
+    console.log(
+      "   • Check the TypeScript-first examples/README.md for more patterns"
+    );
+    console.log(
+      "   • Implement custom metadata extensions for your use case\n"
+    );
+  } catch (error) {
+    // Comprehensive TypeScript error handling
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error("Advanced TypeScript features demo failed:", errorMessage);
+
+    // Type-safe error analysis
+    if (error && typeof error === "object" && "status" in error) {
+      const httpError = error as { status: number; message?: string };
+      if (httpError.status >= 400) {
+        console.error(
+          `HTTP ${httpError.status} Error - API connectivity issue`
+        );
+        console.error("Check your API keys and network connectivity");
+      }
+    }
+
+    // Log final status even on error
+    const errorStatus = getStatus();
+    console.error("Final Middleware Status:", {
+      initialized: errorStatus.initialized,
+      patched: errorStatus.patched,
+      hasConfig: errorStatus.hasConfig,
+    });
+
+    throw error;
+  }
+}
+
+/**
+ * Type-safe environment validation
+ */
+function checkEnvironment(): void {
+  const required = ["REVENIUM_METERING_API_KEY", "ANTHROPIC_API_KEY"];
+  const missing = required.filter((key) => !process.env[key]);
+
+  if (missing.length > 0) {
+    console.error(
+      "Missing required environment variables for advanced TypeScript features:"
+    );
+    missing.forEach((key) => console.error(`   • ${key}`));
+    console.error("\nSet them in a .env file in the project root:");
+    console.error("   REVENIUM_METERING_API_KEY=hak_your_api_key");
+    console.error("   ANTHROPIC_API_KEY=sk-ant-your_anthropic_key");
+    console.error("\nOptional (uses defaults if not set):");
+    console.error(
+      "   REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter/v2"
+    );
+    console.error("   REVENIUM_DEBUG=true  # For detailed logging");
+    process.exit(1);
+  }
+}
+
+// Run the TypeScript demonstration
+if (require.main === module) {
+  checkEnvironment();
+
+  demonstrateAdvancedFeatures()
+    .then(() => {
+      console.log(
+        "\nAdvanced TypeScript Features Demo Completed Successfully!"
+      );
+      console.log("\nTypeScript Features Demonstrated:");
+      console.log("   • Type-safe streaming with event handling");
+      console.log("   • Advanced metadata patterns with interface extensions");
+      console.log("   • Custom logger implementation with typed interfaces");
+      console.log("   • Manual tracking with full type safety");
+      console.log("   • Comprehensive error handling with typed responses");
+      console.log("   • Module augmentation for native usageMetadata support");
+      console.log("   • Generic functions with type constraints");
+      console.log("   • Full IntelliSense support throughout");
+      console.log(
+        "\nNext: Check examples/README.md for more TypeScript patterns!"
+      );
+      console.log(
+        "\nTip: Set REVENIUM_DEBUG=true in .env file for detailed tracking logs"
+      );
+    })
+    .catch((error) => {
+      console.error("\nAdvanced TypeScript features demo failed:", error);
+      process.exit(1);
+    });
+}