@revenium/openai 1.0.13 → 1.0.15

package/.env.example

@@ -1,20 +1,15 @@
-# Revenium OpenAI Middleware Configuration
-# Copy this file to .env and fill in your actual values
-
-# Required: Your Revenium API key (starts with hak_)
+# Revenium Configuration (Required)
 REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
+REVENIUM_METERING_BASE_URL=https://api.revenium.ai
 
-# Optional: Revenium API base URL (defaults to https://api.revenium.ai)
-#REVENIUM_METERING_BASE_URL=https://api.revenium.ai
+# OpenAI Configuration (Required for OpenAI native API)
+OPENAI_API_KEY=sk-your_openai_api_key_here
 
-# Required: Your OpenAI API key (starts with sk-)
-OPENAI_API_KEY=sk_your_openai_api_key_here
+# Azure OpenAI Configuration (Optional - for Azure OpenAI support)
+AZURE_OPENAI_API_KEY=your_azure_openai_api_key
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
+AZURE_OPENAI_API_VERSION=your_azure_openai_api_version
 
-# Optional: Azure OpenAI configuration (uncomment if using Azure)
-#AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
-#AZURE_OPENAI_API_KEY=your-azure-openai-api-key-here
-#AZURE_OPENAI_DEPLOYMENT=your-deployment-name-here
-#AZURE_OPENAI_API_VERSION=2024-12-01-preview
+# Debug Configuration (Optional)
+REVENIUM_DEBUG=false                        # Set to true to enable debug logging
 
-# Optional: Enable debug logging
-#REVENIUM_DEBUG=true

package/CHANGELOG.md

@@ -5,66 +5,120 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.15] - 2025-12-09
+
+### Added
+
+- Comprehensive tracing support with 10 new trace visualization fields
+- environment field with fallback chain (REVENIUM_ENVIRONMENT → NODE_ENV → DEPLOYMENT_ENV)
+- operationSubtype field with auto-detection for function_call when tools are present
+- retryNumber field for tracking retry attempts
+- parentTransactionId field for distributed tracing support
+- transactionName field for human-readable operation labels
+- region field with AWS/Azure/GCP environment variable detection and metadata service fallback
+- credentialAlias field for credential identification
+- traceType field with format validation
+- traceName field with length validation and truncation
+- Region detection caching with 1-second timeout for metadata service calls
+
+### Changed
+
+- Enhanced trace field validation with format checking and length limits
+- Improved documentation with comprehensive trace field examples
+
+## [1.0.14] - 2025-11-14
+
+### Changed
+
+- Updated Node.js requirement from >=16.0.0 to >=18.0.0 (LTS standard)
+- Improved package distribution to exclude source files, include only compiled artifacts
+- Enhanced README with governance file references (Contributing, Code of Conduct, Security)
+
+### Fixed
+
+- Updated dashboard URLs from app.revenium.io to app.revenium.ai in examples documentation
+
 ## [1.0.13] - 2025-11-06
 
 ### Added
-- configure() function for manual configuration (simpler alias for initializeRevenium)
-- Support for COST_LIMIT and COMPLETION_LIMIT stop reasons
+
+- Configure() function for manual configuration
+- COST_LIMIT and COMPLETION_LIMIT stop reasons to mapper (per API spec)
 - Support for all 7 operationType enum values (CHAT, GENERATE, EMBED, CLASSIFY, SUMMARIZE, TRANSLATE, OTHER)
 
 ### Changed
+
 - **BREAKING:** responseQualityScore now uses 0.0-1.0 scale (was 0-100) per updated API specification
-- API endpoint updated from api.revenium.io to api.revenium.ai (new production domain)
-- Improved API compliance with proper enum values and field casing
-- Enhanced token counting accuracy for cache operations
+- **API URL:** All references updated from api.revenium.io to api.revenium.ai (new production domain)
+- **API Compliance:** provider value changed from 'OPENAI' to 'OpenAI' (proper casing per spec)
+- **API Compliance:** modelSource changed to 'OPENAI' for direct OpenAI, 'AZURE_OPENAI' for Azure
+- **API Compliance:** middlewareSource changed from 'nodejs' to 'revenium-openai-node' per spec format
+- **API Compliance:** cacheCreationTokenCount now undefined (not 0) when provider doesn't report
+- **API Compliance:** cacheReadTokenCount now uses ?? operator (not ||) to preserve 0 values
+- **API Compliance:** timeToFirstToken now undefined (not hardcoded) until real TTFB tracking implemented
+- Simplified main README from 675 to 386 lines
+- Standardized Azure API versions to 2024-12-01-preview across all files
 - Email addresses now masked in debug logs for PII protection
 - All examples updated to use 0.0-1.0 scale for responseQualityScore
 
 ### Fixed
-- Improved documentation accuracy and removed deprecated configuration options
+
+- Removed broken file references from examples documentation
+- Removed non-existent config options from documentation (apiTimeout, failSilent, maxRetries)
+- Removed misleading "custom fields" claim from Features section
 - config.debug property now properly enables debug logging
-- Manual configuration example now includes required patchOpenAIInstance call
 - Updated OpenAI version requirement to match peer dependency (v5.0.0+)
-- Enhanced metadata validation for responseQualityScore scale
-- Improved provider detection fallback handling
-- Fixed cache token reporting for embeddings API
-- reasoningTokenCount now correctly optional based on provider support
+- Removed overpromised time-to-first-token metric claim
+- Removed taskId field from all files (field does not exist in API spec per code review feedback)
+- Added CANCELLED stop reason to mapper for completeness
+- validateMetadata now checks 0.0-1.0 scale for responseQualityScore
+- Fallback provider detection now uses 'OpenAI' not 'OPENAI' (proper casing)
+- Embeddings now send undefined for cache tokens (was incorrectly sending 0)
+- reasoningTokenCount now optional (undefined when not reported, per spec)
 
 ## [1.0.12] - 2025-10-30
 
 ### Changed
+
 - Improved documentation structure and Getting Started tutorial
 - Enhanced package distribution to include TypeScript source files
 
 ### Fixed
+
 - Repository configuration updates
 
 ## [1.0.11] - 2025-10-21
 
 ### Added
+
 - Examples now included in npm package
 - Comprehensive examples documentation
 
 ### Changed
+
 - Updated API endpoint configuration
 - Improved documentation structure
 
 ## [1.0.10] - 2025-10-17
 
 ### Added
+
 - Support for OpenAI Responses API
 
 ### Changed
+
 - Enhanced documentation and examples
 
 ## [1.0.9] - 2025-10-16
 
 ### Changed
+
 - Bug fixes and stability improvements
 
 ## [1.0.8] - 2025-10-15
 
 ### Added
+
 - Initial release with OpenAI usage tracking
 - Support for streaming responses and function calling
 - Azure OpenAI support

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,57 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+Examples of behavior that contributes to a positive environment include:
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by mistakes
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior include:
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action.
+
+## Scope
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the project in public spaces.
+
+## Enforcement
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at **support@revenium.io**.
+All complaints will be reviewed and investigated promptly and fairly.
+
+The project team is obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+Community leaders will follow these guidelines in determining the consequences:
+1. **Correction** – Private, written warning.
+2. **Warning** – Clear and public warning of violation.
+3. **Temporary Ban** – Temporary ban from community interaction.
+4. **Permanent Ban** – Permanent removal from community interaction.
+
+## Attribution
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org

package/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Thank you for your interest in contributing to this project!
+
+## Getting Started
+
+1. Fork the repository and create a feature branch
+2. Make your changes following existing code patterns  
+3. Test your changes
+4. Submit a pull request with a clear description
+
+## What to Contribute
+
+- Bug fixes and improvements
+- Documentation updates
+- Test coverage improvements
+- Performance optimizations
+
+## Guidelines
+
+- Follow the existing code style
+- Include tests for new functionality when applicable
+- Update documentation if needed
+- Keep changes focused and atomic
+
+## Questions?
+
+- Check existing issues first
+- For bugs: Create an issue with reproduction steps
+- For questions: Email support@revenium.io
+
+## Security
+
+For security vulnerabilities, please follow our [Security Policy](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/SECURITY.md) - do not create public issues.
+
+## License
+
+By contributing, you agree your contributions will be licensed under the same license as this project.