valenceai 1.0.2 → 1.0.5

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.3] - 2025-01-28
+
+### Added
+
+- **`getEmotionCounts()` method**: Returns an object of emotion occurrence counts for the entire audio file (e.g., `{happy: 10, sad: 3, angry: 8, neutral: 9}`)
+- **`majorityEmotion()` method**: Alias for `getDominantEmotion()`, returns the most frequently occurring emotion as a string
+
+### Technical Improvements
+
+- **Refactored `getDominantEmotion()`**: Now uses `getEmotionCounts()` internally to avoid code duplication
+
+### Usage Example
+
+```javascript
+import { ValenceClient } from 'valenceai';
+
+const client = new ValenceClient({ apiKey: 'your_api_key' });
+const requestId = await client.asynch.upload('audio.wav');
+const result = await client.asynch.emotions(requestId);
+
+// Get emotion counts
+const counts = await client.asynch.getEmotionCounts(requestId);
+// Returns: { happy: 10, sad: 3, angry: 8, neutral: 9 }
+
+// Get majority emotion
+const majority = await client.asynch.majorityEmotion(requestId);
+// Returns: "happy"
+```
+
 ## [1.0.1] - 2025-12-29
 
 ### Fixed

package/README.md

@@ -1,67 +1,109 @@
 # Valence SDK for Emotion Detection
 
-**valenceai** is a Node.js SDK for interacting with the [Valence AI](https://getvalenceai.com) Pulse API for emotion detection. It provides a convenient interface to upload audio files, stream real-time audio, and retrieve detected emotional states.
+**valenceai** is a Node.js SDK for interacting with the [Valence AI](https://getvalenceai.com) API for emotion analysis. It provides a convenient interface to upload audio files, stream real-time audio, and retrieve detected emotional states.
 
 ## Features
 
-- **Discrete audio processing** - Real-time analysis for short audio clips (4-10s)
-- **Async audio processing** - Multipart streaming for long files with timeline data
+- **Discrete audio processing** - Real-time analysis for short audio clips
+- **Asynch audio processing** - Multipart parallel upload for long audio files with temporal emotion analysis
 - **Streaming API** - Real-time WebSocket streaming for live audio
 - **Rate limiting** - Monitor API usage and limits
-- **Model selection** - Choose between 4emotions and 7emotions models
-- **Timeline analysis** - Get emotion changes over time with timestamps
 - **Environment configuration** - Built-in support for .env files
 - **Enhanced logging** - Configurable log levels with timestamps
-- **Robust error handling** - Comprehensive validation and error recovery
 - **TypeScript ready** - Full JSDoc documentation for all functions
-- **100% tested** - Comprehensive test suite with high coverage
-- **Security focused** - Input validation and secure error handling
 
-The emotional classification model used in our APIs is optimized for North American English conversational data.
+The emotional classification model used in our APIs is optimized for North American English conversational data. The included model detects four emotions: angry, happy, neutral, and sad. _New models coming soon_.
 
-## Emotion Models
+## API Overview
 
-The SDK supports two emotion detection models:
+| API | Best For | Input | Output |
+|-----|----------|-------|--------|
+| **Discrete** | Real-time analysis | Short audio (4-10s) | Single emotion prediction |
+| **Asynch** | Pre-recorded files | Long audio (up to 1GB) | Timeline with emotion changes |
+| **Streaming** | Live audio streams | Audio chunks via WebSocket | Real-time emotion updates |
 
-- **4emotions** (default): angry, happy, neutral, sad
-- **7emotions**: happy, sad, angry, neutral, surprised, disgusted, calm
+The **DiscreteAPI** is built for real-time analysis of emotions in audio data. Small snippets of audio are sent to the API to receive feedback in real-time of what emotions are detected based on tone of voice. This API operates on an approximate per-sentence basis, and audio must be cut to the appropriate size.
 
-The number of emotions, emotional buckets, and language support can be customized. If you are interested in a custom model, please [contact us](https://www.getvalenceai.com/contact).
+The **AsynchAPI** is built for emotion analysis of pre-recorded audio files. Files of any length, up to 1 GB in size, can be sent to the API to receive a timeline of emotions throughout the file. 
 
-## API Overview
+The **StreamingAPI** is built for real-time audio analysis via WebSocket connections. The audio stream is analyzed in real-time and emotions are returned in reference to 5-second chunks of streamed audio.
+
+## Audio Input Requirements
+
+### Format Specifications
+
+- **Format**: WAV only
+- **Recommended sampling rate**: 44.1 kHz (44100 Hz)
+- **Minimum sampling rate**: 8 kHz
+- **Channel**: Mono (single channel)
+
+### API-Specific Requirements
+
+- **Discrete API**: Minimum 4.5 seconds per file, maximum 15 seconds. 5-10 seconds recommended.
+- **Asynch API**: Minimum 5 seconds, maximum 1 GB
+- **Streaming API**: Real-time audio chunks (Buffer or ArrayBuffer)
+
+For inquiries about custom microphone specifications or stereo/multi-channel support, please [contact us](https://www.getvalenceai.com/contact).
+
+## Installation
+
+```bash
+npm install valenceai
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+VALENCE_API_KEY=your_api_key                       # Required
+VALENCE_API_BASE_URL=https://api.getvalenceai.com  # Optional
+VALENCE_WEBSOCKET_URL=wss://api.getvalenceai.com   # Optional
+VALENCE_LOG_LEVEL=info                             # Optional: debug, info, warn, error
+```
+
+### Client Configuration
 
-| API | Best For | Input | Output | Response Time |
-|-----|----------|-------|--------|---------------|
-| **Discrete** | Real-time analysis | Short audio (4-10s) | Single emotion prediction | 100-500ms |
-| **Async** | Pre-recorded files | Long audio (up to 1GB) | Timeline with emotion changes | Depends on file size |
-| **Streaming** | Live audio streams | Audio chunks via WebSocket | Real-time emotion updates | Near real-time |
+```javascript
+const client = new ValenceClient({
+  apiKey: 'your_api_key',           // API key (required)
+  baseUrl: 'https://custom.api',    // Custom API endpoint (optional)
+  websocketUrl: 'wss://custom.api', // Custom WebSocket endpoint (optional)
+  partSize: 5 * 1024 * 1024,        // Upload chunk size (default: 5MB)
+  maxRetries: 3,                    // Max retry attempts (default: 3)
+  comprehensiveOutput: false        // When false: asynch API returns timestamp, main_emotion, confidence only.
+                                    // When true: also includes all_predictions with all emotion confidences (default: false)
+});
+```
 
-## Async API Processing Workflow
+## Asynch API Processing Workflow
 
-The Async API uses a multi-step process to handle long audio files. Understanding this workflow is crucial for proper implementation:
+The Asynch API uses a multi-step process to handle long audio files. Understanding this workflow is crucial for proper implementation:
 
 ### 1. Upload Phase (Client-Side)
 
 When you call `client.asynch.upload(filePath)`:
 
 - SDK splits your file into parts (5MB chunks by default)
-- Uploads parts to S3 using presigned URLs
-- **Returns a `requestId`** - This is a tracking identifier, NOT a completion signal
-- At this point: File is uploaded to S3, but **NOT processed yet**
+- Uploads parts in parallel
+- **Returns a `requestId`** - This is a tracking identifier, not a completion signal.
+- At this point: File is uploaded to our server, but _NOT processed yet_.
 
 ### 2. Background Processing (Server-Side)
 
 After upload completes, the server automatically:
 
-- Background processor checks for new uploads every 10 seconds
-- Downloads audio from S3 when detected
+- Checks for new uploads
+- Downloads audio when a new File is detected
 - Splits audio into 5-second segments
-- Extracts audio features (MFCC) from each segment
+- Processes audio file
 - Invokes machine learning model for emotion detection
 - Stores results in database
 - Updates status to `completed`
 
-**Processing Time**: Typically 1-2 minutes for a 60-minute audio file. The exact time depends on file length and current server load.
+**Processing Time**: Varies based on file length and server load. Typically 1-5 seconds per minute of audio. Upload time varies based on your network speed.
 
 ### 3. Results Retrieval (Client-Side)
 
@@ -70,7 +112,7 @@ When you call `client.asynch.emotions(requestId)`:
 - Polls the status endpoint at regular intervals
 - Waits for status progression:
   - `initiated` → Upload started
-  - `upload_completed` → File uploaded to S3 (processing not started)
+  - `upload_completed` → File uploaded (processing not started)
   - `processing` → Background processing in progress
   - `completed` → Results ready
 - Returns emotion timeline when status is `completed`
@@ -79,47 +121,44 @@ When you call `client.asynch.emotions(requestId)`:
 
 | Status | Meaning | What's Happening |
 |--------|---------|------------------|
-| `initiated` | Upload started | SDK is uploading file parts to S3 |
-| `upload_completed` | Upload finished | File is in S3, waiting for background processor |
-| `processing` | Processing active | Server is analyzing audio with ML model |
+| `initiated` | Upload started | SDK is uploading file in parts |
+| `upload_completed` | Upload finished | File is waiting for background processor |
+| `processing` | Processing active | Server is analyzing audio |
 | `completed` | Results ready | Emotion timeline is available |
 
 ### Important Notes
 
-- **The `requestId` is NOT a completion indicator** - It's just a tracking ID
-- **`upload()` completing does NOT mean results are ready** - It only means the file is in S3
-- **Background processing takes time** - Plan for 1-2 minutes per hour of audio
-- **You can check status anytime** - The `requestId` remains valid for retrieving results
-
-## Installation
-
-```bash
-npm install valenceai
-```
+- The `requestId` is NOT a completion indicator. It's a request tracking ID.
+- `upload()` completing does not mean results are ready. It means the file is uploaded.
+- Background processing takes time. Processing time varies based on file length and server load.
+- You can check status anytime. The `requestId` remains valid for retrieving results until databases are cleared (see: [DPA](https://getvalenceai.com/legal/data-processing) for more information on data retention policies).
 
 ## Quick Start
 
 ```javascript
 import { ValenceClient } from 'valenceai';
 
-// Initialize client (uses VALENCE_API_KEY environment variable)
+// Initialize client
 const client = new ValenceClient({ apiKey: 'your_api_key' });
 
 // Discrete API - Quick emotion detection
-const result = await client.discrete.emotions('short_audio.wav', '4emotions');
-console.log(`Emotion: ${result.dominant_emotion}`);
+const result = await client.discrete.emotions('short_audio.wav');
+console.log(`Emotion: ${result.main_emotion}`);
 
-// Async API - Long audio with timeline
-// Step 1: Upload file to S3 (returns tracking ID, NOT results)
+// Asynch API - Long audio with timeline
+// Step 1: Upload file (returns tracking ID)
 const requestId = await client.asynch.upload('long_audio.wav');
 // Step 2: Wait for server processing and get results (polls until complete)
 const emotions = await client.asynch.emotions(requestId, 30, 10000);
-// Step 3: Access timeline and dominant emotion from results
-const timeline = await client.asynch.getTimeline(requestId);
-const dominant = await client.asynch.getDominantEmotion(requestId);
+// Step 3: Access emotion data from results
+const emotionList = emotions.emotions;  // List of emotion predictions with timestamps
+
+// Get summary statistics
+const majority = await client.asynch.majorityEmotion(requestId);  // Most frequent emotion
+const counts = await client.asynch.emotionCounts(requestId);  // { happy: 10, sad: 3, ... }
 
 // Streaming API - Real-time audio
-const stream = client.streaming.connect('4emotions');
+const stream = client.streaming.connect();
 stream.on('prediction', (data) => console.log(data.main_emotion));
 stream.connect();
 stream.sendAudio(audioBuffer);
@@ -130,31 +169,6 @@ const status = await client.rateLimit.getStatus();
 const health = await client.rateLimit.getHealth();
 ```
 
-## Configuration
-
-### Environment Variables
-
-Create a `.env` file in your project root:
-
-```env
-VALENCE_API_KEY=your_api_key                       # Required
-VALENCE_API_BASE_URL=https://api.getvalenceai.com  # Optional
-VALENCE_WEBSOCKET_URL=wss://api.getvalenceai.com   # Optional
-VALENCE_LOG_LEVEL=info                             # Optional: debug, info, warn, error
-```
-
-### Client Configuration
-
-```javascript
-const client = new ValenceClient({
-  apiKey: 'your_api_key',           // API key (required)
-  baseUrl: 'https://custom.api',    // Custom API endpoint (optional)
-  websocketUrl: 'wss://custom.api', // Custom WebSocket endpoint (optional)
-  partSize: 5 * 1024 * 1024,        // Upload chunk size (default: 5MB)
-  maxRetries: 3                     // Max retry attempts (default: 3)
-});
-```
-
 ## API Reference
 
 ### Discrete API
@@ -162,17 +176,11 @@ const client = new ValenceClient({
 For short audio files requiring immediate emotion detection.
 
 ```javascript
-// File upload
-const result = await client.discrete.emotions(
-  'audio.wav',
-  '4emotions'  // or '7emotions'
-);
+// Direct file upload
+const result = await client.discrete.emotions('audio.wav');
 
-// In-memory audio array
-const result = await client.discrete.emotions(
-  [0.1, 0.2, 0.3, ...],
-  '4emotions'
-);
+// Upload via in-memory audio array
+const result = await client.discrete.emotions([0.17278, 0.23738, 0.37912, ...]);
 ```
 
 **Response:**
@@ -181,36 +189,28 @@ const result = await client.discrete.emotions(
   emotions: {
     happy: 0.78,
     sad: 0.12,
-    angry: 0.05,
-    neutral: 0.05
+    angry: 0.08,
+    neutral: 0.15
   },
-  dominant_emotion: 'happy'
+  main_emotion: 'happy'
 }
 ```
 
-### Async API
+### Asynch API
 
 For long audio files with timeline analysis.
 
-**Workflow**: The Async API uses a 3-step process:
-
-1. **Upload** (`upload()`) - Multipart upload to S3, returns `requestId` (tracking ID)
-2. **Background Processing** (automatic) - Server processes audio in 5-second chunks
-3. **Results Retrieval** (`emotions()`) - Polls status endpoint until processing completes
-
-**Processing Time**: Typically 1-2 minutes per hour of audio.
-
 **Status Progression**: `initiated` → `upload_completed` → `processing` → `completed`
 
 #### Upload Audio
 
 ```javascript
-// Upload file to S3 (multipart upload)
+// Upload file (multipart upload, automatically validates file size)
 const requestId = await client.asynch.upload('long_audio.wav');
-// Returns: requestId (tracking ID, NOT completion signal)
-// File is uploaded to S3 but NOT processed yet
 ```
 
+**Note**: The SDK automatically validates file size against your rate limit policy before upload. If the file exceeds the maximum allowed size, a `FileSizeLimitExceededError` is thrown without attempting the upload. Default maximum is 1GB when no rate limit policy is configured.
+
 #### Get Emotion Results
 
 ```javascript
@@ -249,17 +249,18 @@ const result = await client.asynch.emotions(
 }
 ```
 
-#### Timeline Analysis
+Note: The `all_predictions` field is only included when `comprehensiveOutput: true` is set in the client constructor.
 
-```javascript
-// Get full timeline
-const timeline = await client.asynch.getTimeline(requestId);
+#### Helper Methods
 
-// Get emotion at specific time
-const emotion = await client.asynch.getEmotionAtTime(requestId, 5.2);
+```javascript
+// Get the most frequently occurring emotion across the entire file
+const majority = await client.asynch.majorityEmotion(requestId);
+// Returns: "happy"
 
-// Get dominant emotion across entire audio
-const dominant = await client.asynch.getDominantEmotion(requestId);
+// Get emotion occurrence counts for the entire file
+const counts = await client.asynch.emotionCounts(requestId);
+// Returns: { happy: 10, sad: 3, angry: 8, neutral: 9 }
 ```
 
 ### Streaming API
@@ -268,7 +269,7 @@ For real-time emotion detection on live audio streams.
 
 ```javascript
 // Create streaming connection
-const stream = client.streaming.connect('4emotions');
+const stream = client.streaming.connect();
 
 // Register event handlers
 stream.on('prediction', (data) => {
@@ -307,12 +308,14 @@ stream.disconnect();
     happy: 0.87,
     sad: 0.05,
     angry: 0.03,
-    neutral: 0.05
+    neutral: 0.15
   },
-  timestamp: 1234567890
+  timestamp: 1706486400000 // Unix timestamp (UTC) in milliseconds
 }
 ```
 
+The `timestamp` is a Unix timestamp (UTC) in milliseconds representing when the server generated the prediction.
+
 ### Rate Limit API
 
 Monitor your API usage and limits.
@@ -322,76 +325,105 @@ Monitor your API usage and limits.
 const status = await client.rateLimit.getStatus();
 console.log(status);
 // {
+//   policy_name: 'standard_policy',
 //   limits: {
-//     second: { limit: 10, remaining: 8, reset: 1234567890 },
-//     minute: { limit: 100, remaining: 95, reset: 1234567890 },
-//     hour: { limit: 1000, remaining: 950, reset: 1234567890 },
-//     day: { limit: 10000, remaining: 9500, reset: 1234567890 }
+//     requests_per_second: 10,
+//     requests_per_minute: 100,
+//     requests_per_hour: 1000,
+//     requests_per_day: 10000,
+//     burst_limit: 20,
+//     max_audio_size_mb: 50,           // Maximum file size in MB
+//     max_audio_duration_seconds: 300, // Maximum audio duration
+//     max_concurrent_requests: 5
 //   },
 //   current_usage: {
-//     second: 2,
-//     minute: 5,
-//     hour: 50,
-//     day: 500
+//     requests_per_second: 2,
+//     rejected_per_second: 0,
+//     total_audio_size_bytes_per_second: 1048576,
+//     requests_per_minute: 15,
+//     rejected_per_minute: 0,
+//     total_audio_size_bytes_per_minute: 15728640
+//     // ... usage for hour and day
 //   }
 // }
 
 // Check API health
 const health = await client.rateLimit.getHealth();
 console.log(health);
-// { status: 'healthy', timestamp: 1234567890 }
+// { status: 'healthy', timestamp: 1738684800 }
 ```
 
-## Audio Input Requirements
+The `reset` and `timestamp` values are Unix timestamps (UTC) in seconds.
 
-### Format Specifications
+## Error Responses
 
-- **Format**: WAV (mono)
-- **Recommended sampling rate**: 44.1 kHz (44100 Hz)
-- **Minimum sampling rate**: 8 kHz
-- **Channel**: Mono (single channel)
-
-### API-Specific Requirements
+### Discrete API Errors
 
-- **Discrete API**: 4-10 seconds per file
-- **Async API**: Minimum 5 seconds, maximum 1 GB
-- **Streaming API**: Real-time audio chunks (Buffer or ArrayBuffer)
+| HTTP Status | Error Code | Description |
+|-------------|------------|-------------|
+| 400 | `AUDIO_TOO_SHORT` | Audio duration below minimum (4.5 seconds). Response includes `min_duration_seconds` and `actual_duration_seconds` |
+| 400 | `AUDIO_TOO_LONG` | Audio duration above maximum (15 seconds). Response includes `max_duration_seconds` and `actual_duration_seconds` |
+| 400 | Bad Request | Invalid request format or parameters |
+| 401 | Unauthorized | Invalid or missing API key |
+| 500 | Server Error | Internal server error |
 
-For custom microphone specifications or stereo/multi-channel support, please [contact us](https://www.getvalenceai.com/contact).
+### Asynch API Errors
 
-## Examples
+| HTTP Status | Error Code | Description |
+|-------------|------------|-------------|
+| 400 | `AUDIO_TOO_SHORT` | Audio duration below minimum (5 seconds) |
+| 400 | `FILE_SIZE_LIMIT_EXCEEDED` | File size exceeds rate limit policy maximum. Raised before upload attempt |
+| 400 | `FILE_TOO_LARGE` | File exceeds maximum upload size (1 GB). Response includes `max_file_size_bytes` and `actual_file_size_bytes` |
+| 400 | Bad Request | Invalid request format or parameters |
+| 401 | Unauthorized | Invalid or missing API key |
+| 404 | Not Found | Request ID not found |
+| 500 | Server Error | Internal server error |
 
-Example scripts are available in the [`examples/`](./examples) directory:
+**Asynch Status Values:**
 
-```bash
-# Install dependencies
-npm install
+| Status | Meaning |
+|--------|---------|
+| `initiated` | Upload in progress |
+| `upload_completed` | Upload finished, awaiting processing |
+| `processing` | Server analyzing audio |
+| `completed` | Results ready |
+| `failed` | Processing failed |
 
-# Run discrete audio example
-npm run example:discrete
+### Streaming API Errors
 
-# Run async audio example
-npm run example:asynch
+| Event | Description |
+|-------|-------------|
+| `error` | Server-side error during streaming |
+| `warning` | Non-fatal warning from server |
+| `connect_error` | WebSocket connection failed |
+| `disconnect` | Connection closed |
 
-# Run streaming example
-npm run example:streaming
+### Rate Limit API Errors
 
-# Or run directly
-node examples/uploadShort.js
-node examples/uploadLong.js
-node examples/streamingAudio.js
-```
+| HTTP Status | Description |
+|-------------|-------------|
+| 401 | Unauthorized - Invalid API key |
+| 429 | Too Many Requests - Rate limit exceeded |
+| 500 | Server Error |
 
 ## Error Handling
 
 ```javascript
-import { ValenceClient } from 'valenceai';
+import {
+  ValenceClient,
+  AudioTooShortError,
+  FileSizeLimitExceededError
+} from 'valenceai';
 
 try {
   const client = new ValenceClient({ apiKey: 'your_key' });
   const result = await client.discrete.emotions('audio.wav');
 } catch (error) {
-  if (error.message.includes('API key')) {
+  if (error instanceof AudioTooShortError) {
+    console.error(`Audio too short: ${error.actualDuration}s (min: ${error.minDuration}s)`);
+  } else if (error instanceof FileSizeLimitExceededError) {
+    console.error(`File too large: ${error.actualSizeMb.toFixed(2)} MB (max: ${error.maxSizeMb} MB)`);
+  } else if (error.message.includes('API key')) {
     console.error('Authentication error:', error.message);
   } else if (error.message.includes('File not found')) {
     console.error('File error:', error.message);
@@ -403,45 +435,16 @@ try {
 }
 ```
 
-## Development
-
-### Testing
-
-```bash
-# Run all tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Watch mode for development
-npm run test:watch
-
-# Run specific test file
-npm test -- discrete.test.js
-```
-
-### Building and Publishing
-
-```bash
-# Validate configuration and run tests
-npm test
-
-# Publish to npm
-npm login
-npm publish --access public
-```
-
 ## Migration from v0.x
 
-### Key Changes in v1.0.0
+### Key Changes in v1.0.5
 
-1. **Environment Variable**: `VALENCE_API_KEY` is now the standard (consistent naming)
+1. **Environment Variable**: `VALENCE_API_KEY` is now the standard (consistent naming across SDKs)
 2. **Unified Client**: Single `ValenceClient` class with nested APIs
 3. **Streaming API**: New WebSocket-based real-time emotion detection
 4. **Rate Limiting**: New API for monitoring usage
-5. **Timeline Data**: Async API now returns detailed timestamp information
-6. **Model Selection**: Explicit model parameter for 4emotions or 7emotions
+5. **Timeline Data**: Asynch API now returns detailed timestamp information
+6. **Helper Methods**: Asynch API now includes functions for baseline analysis of emotion timeline
 
 ### Updating Your Code
 
@@ -453,10 +456,10 @@ const result = await predictDiscreteAudioEmotion('file.wav');
 // New (v1.0.0)
 import { ValenceClient } from 'valenceai';
 const client = new ValenceClient({ apiKey: 'your_key' });
-const result = await client.discrete.emotions('file.wav', '4emotions');
+const result = await client.discrete.emotions('file.wav');
 
 // New streaming capability
-const stream = client.streaming.connect('4emotions');
+const stream = client.streaming.connect();
 stream.on('prediction', callback);
 await stream.connect();
 ```
@@ -467,7 +470,6 @@ await stream.connect();
 - `uploadAsyncAudio()` → `client.asynch.upload()`
 - `getEmotions()` → `client.asynch.emotions()`
 - All methods now require creating a `ValenceClient` instance first
-- Model parameter is now required and explicit
 
 See [CHANGELOG.md](./CHANGELOG.md) for complete migration guide.
 
@@ -481,26 +483,16 @@ import { ValenceClient } from 'valenceai';
 const client: ValenceClient = new ValenceClient({ apiKey: 'your_key' });
 
 // Full type inference and autocomplete
-const result = await client.discrete.emotions('audio.wav', '4emotions');
-// result.dominant_emotion is typed
+const result = await client.discrete.emotions('audio.wav');
+// result.main_emotion is typed
 ```
 
-## Contributing
-
-We welcome contributions! Please:
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Make your changes with tests
-4. Ensure all tests pass: `npm test`
-5. Submit a pull request
-
 ## Support
 
-- **Documentation**: [API Documentation](https://docs.getvalenceai.com)
-- **Issues**: [GitHub Issues](https://github.com/valencevibrations/valence-sdk-js/issues)
-- **Questions**: [Valence AI Support](https://www.getvalenceai.com/contact)
+- **Additional Documentation**: [API Documentation](https://docs.getvalenceai.com)
+- **Detailed Usage Examples**: [SDK Examples](https://docs.getvalenceai.com/examples)
+- **Contact**: [Valence AI Support](https://www.getvalenceai.com/contact)
 
 ## License
 
-Private License © 2025 [Valence Vibrations, Inc](https://getvalenceai.com), a Delaware public benefit corporation.
+Private License © 2026 [Valence Vibrations, Inc](https://getvalenceai.com), a Delaware public benefit corporation.

package/package.json

@@ -1,20 +1,18 @@
 {
     "name": "valenceai",
-    "version": "1.0.2",
+    "version": "1.0.5",
     "type": "module",
     "main": "src/index.js",
     "description": "Node.js SDK for Valence AI Emotion Detection API - Real-time, Async, and Streaming Support",
     "keywords": ["valence", "emotion", "detection", "ai", "audio", "streaming", "websocket", "real-time"],
     "author": "julian.olarte",
-    "license": "ISC",
+    "license": "Private License",
     "repository": {
         "type": "git",
         "url": "https://github.com/valenceai/sdk"
     },
     "scripts": {
         "start": "node examples/uploadShort.js",
-        "example:discrete": "node examples/uploadShort.js",
-        "example:async": "node examples/uploadLong.js",
         "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
         "test:coverage": "c8 jest",
         "test:watch": "jest --watch"
@@ -32,8 +30,5 @@
     },
     "engines": {
         "node": ">=14.0.0"
-    },
-    "directories": {
-        "example": "examples"
     }
 }

package/src/config.js

@@ -2,11 +2,11 @@ import dotenv from 'dotenv';
 dotenv.config();
 
 /**
- * Default URLs point to staging environment (demo.getvalenceai.com)
+ * Default URLs point to production environment (api.getvalenceai.com)
  * These can be overridden by environment variables or constructor parameters
  */
-const DEFAULT_BASE_URL = 'https://demo.getvalenceai.com';
-const DEFAULT_WEBSOCKET_URL = 'wss://demo.getvalenceai.com';
+const DEFAULT_BASE_URL = 'https://api.getvalenceai.com';
+const DEFAULT_WEBSOCKET_URL = 'wss://api.getvalenceai.com';
 
 /**
  * Configuration object for the Valence SDK

package/src/errors.js

@@ -24,3 +24,37 @@ export class AudioTooShortError extends ValenceSDKError {
     this.actualDuration = actualDuration;
   }
 }
+
+/**
+ * Error thrown when the audio file exceeds the maximum allowed duration.
+ */
+export class AudioTooLongError extends ValenceSDKError {
+  /**
+   * @param {string} message - Error message
+   * @param {number|null} maxDuration - Maximum allowed duration in seconds
+   * @param {number|null} actualDuration - Actual duration of the provided audio in seconds
+   */
+  constructor(message, maxDuration = null, actualDuration = null) {
+    super(message);
+    this.name = 'AudioTooLongError';
+    this.maxDuration = maxDuration;
+    this.actualDuration = actualDuration;
+  }
+}
+
+/**
+ * Error thrown when the audio file size exceeds the rate limit policy maximum.
+ */
+export class FileSizeLimitExceededError extends ValenceSDKError {
+  /**
+   * @param {string} message - Error message
+   * @param {number|null} maxSizeMb - Maximum allowed file size in MB
+   * @param {number|null} actualSizeMb - Actual file size in MB
+   */
+  constructor(message, maxSizeMb = null, actualSizeMb = null) {
+    super(message);
+    this.name = 'FileSizeLimitExceededError';
+    this.maxSizeMb = maxSizeMb;
+    this.actualSizeMb = actualSizeMb;
+  }
+}

package/src/index.js

@@ -1,3 +1,8 @@
 export { ValenceClient } from './valenceClient.js';
 export { validateConfig } from './config.js';
-export { ValenceSDKError, AudioTooShortError } from './errors.js';
+export {
+  ValenceSDKError,
+  AudioTooShortError,
+  AudioTooLongError,
+  FileSizeLimitExceededError
+} from './errors.js';

package/src/valenceClient.js

@@ -6,7 +6,7 @@ import { getHeaders } from './client.js';
 import { log } from './utils/logger.js';
 import { RateLimitAPI } from './rateLimit.js';
 import { StreamingAPI } from './streaming.js';
-import { AudioTooShortError } from './errors.js';
+import { AudioTooShortError, AudioTooLongError, FileSizeLimitExceededError } from './errors.js';
 
 /**
  * Client for discrete (short) audio processing
@@ -23,6 +23,7 @@ class DiscreteClient {
    * @param {string} model - Model type ('4emotions' or '7emotions')
    * @returns {Promise<Object>} Emotion prediction results
    * @throws {Error} If validation fails, API key missing, or request fails
+   * @throws {FileSizeLimitExceededError} If file size exceeds 6MB limit
    */
   async emotions(filePath = null, audioArray = null, model = '4emotions') {
     // Validation
@@ -51,6 +52,17 @@ class DiscreteClient {
           throw new Error(`File not found: ${filePath}`);
         }
 
+        // Validate file size (6MB limit for discrete API)
+        const fileSizeBytes = fs.statSync(filePath).size;
+        const fileSizeMb = fileSizeBytes / (1024 * 1024);
+        const maxSizeMb = 6.0;
+
+        if (fileSizeMb > maxSizeMb) {
+          const errorMsg = `File size (${fileSizeMb.toFixed(2)} MB) exceeds discrete API maximum (${maxSizeMb} MB)`;
+          log(errorMsg, 'error');
+          throw new FileSizeLimitExceededError(errorMsg, maxSizeMb, fileSizeMb);
+        }
+
         log(`Getting emotions for discrete audio: ${filePath} using ${model} model`, 'info');
 
         const formData = new FormData();
@@ -87,6 +99,13 @@ class DiscreteClient {
     } catch (error) {
       log(`Error getting discrete emotions: ${error.message}`, 'error');
 
+      // Re-throw custom SDK errors without wrapping
+      if (error instanceof FileSizeLimitExceededError ||
+          error instanceof AudioTooShortError ||
+          error instanceof AudioTooLongError) {
+        throw error;
+      }
+
       if (error.response) {
         // Check for AUDIO_TOO_SHORT error
         if (error.response.status === 400 && error.response.data?.error_code === 'AUDIO_TOO_SHORT') {
@@ -96,6 +115,14 @@ class DiscreteClient {
             error.response.data.actual_duration_seconds
           );
         }
+        // Check for AUDIO_TOO_LONG or FILE_TOO_LARGE error
+        if (error.response.status === 400 && ['AUDIO_TOO_LONG', 'FILE_TOO_LARGE'].includes(error.response.data?.error_code)) {
+          throw new AudioTooLongError(
+            error.response.data.error || 'Audio file exceeds maximum allowed duration',
+            error.response.data.max_duration_seconds,
+            error.response.data.actual_duration_seconds
+          );
+        }
         throw new Error(`API error (${error.response.status}): ${error.response.data?.message || error.response.statusText}`);
       } else if (error.request) {
         throw new Error('Network error: Unable to reach the API');
@@ -115,6 +142,61 @@ class AsyncClient {
     this.partSize = partSize;
     this.maxRetries = maxRetries;
     this.comprehensiveOutput = comprehensiveOutput;
+    this._rateLimitApi = null;
+  }
+
+  /**
+   * Lazy initialization of RateLimitAPI
+   * @private
+   * @returns {RateLimitAPI} Rate limit API instance
+   */
+  _getRateLimitApi() {
+    if (!this._rateLimitApi) {
+      this._rateLimitApi = new RateLimitAPI(this.config);
+    }
+    return this._rateLimitApi;
+  }
+
+  /**
+   * Validate file size against rate limit policy
+   * @private
+   * @param {string} filePath - Path to the audio file
+   * @throws {FileSizeLimitExceededError} If file size exceeds the rate limit policy maximum
+   */
+  async _validateFileSize(filePath) {
+    const fileSizeBytes = fs.statSync(filePath).size;
+    const fileSizeMb = fileSizeBytes / (1024 * 1024);
+
+    try {
+      // Get rate limit status to check max_audio_size_mb
+      const rateLimitStatus = await this._getRateLimitApi().getStatus();
+      const limits = rateLimitStatus.limits || {};
+      let maxSizeMb = limits.max_audio_size_mb;
+
+      // If no policy is set, default to 1GB (1024 MB)
+      if (maxSizeMb === undefined || maxSizeMb === null) {
+        maxSizeMb = 1024;
+        log('No rate limit policy found, using default maximum of 1GB', 'debug');
+      }
+
+      if (fileSizeMb > maxSizeMb) {
+        const errorMsg = `File size (${fileSizeMb.toFixed(2)} MB) exceeds rate limit maximum (${maxSizeMb} MB)`;
+        log(errorMsg, 'error');
+        throw new FileSizeLimitExceededError(errorMsg, maxSizeMb, fileSizeMb);
+      }
+
+      log(`File size validation passed: ${fileSizeMb.toFixed(2)} MB / ${maxSizeMb} MB`, 'info');
+
+    } catch (error) {
+      // Re-throw FileSizeLimitExceededError
+      if (error instanceof FileSizeLimitExceededError) {
+        throw error;
+      }
+      // If rate limit check fails, log warning but don't block upload
+      // This ensures backward compatibility if rate limit API is unavailable
+      log(`Could not validate file size against rate limits: ${error.message}`, 'warn');
+      log('Proceeding with upload without rate limit validation', 'info');
+    }
   }
 
   /**
@@ -122,6 +204,7 @@ class AsyncClient {
    * @param {string} filePath - Path to the audio file
    * @returns {Promise<string>} Request ID for tracking the upload
    * @throws {Error} If file doesn't exist, API key missing, or upload fails
+   * @throws {FileSizeLimitExceededError} If file size exceeds rate limit maximum
    */
   async upload(filePath) {
     // Validation
@@ -141,6 +224,9 @@ class AsyncClient {
       throw new Error('partSize must be between 1MB and 100MB');
     }
 
+    // Validate file size against rate limit policy before upload
+    await this._validateFileSize(filePath);
+
     log(`Starting async audio upload for ${filePath}`, 'info');
 
     try {
@@ -210,6 +296,14 @@ class AsyncClient {
             error.response.data.actual_duration_seconds
           );
         }
+        // Check for AUDIO_TOO_LONG or FILE_TOO_LARGE error
+        if (error.response.status === 400 && ['AUDIO_TOO_LONG', 'FILE_TOO_LARGE'].includes(error.response.data?.error_code)) {
+          throw new AudioTooLongError(
+            error.response.data.error || 'Audio file exceeds maximum allowed duration',
+            error.response.data.max_duration_seconds,
+            error.response.data.actual_duration_seconds
+          );
+        }
         throw new Error(`API error (${error.response.status}): ${error.response.data?.message || error.response.statusText}`);
       } else if (error.request) {
         throw new Error('Network error: Unable to reach the API');
@@ -324,20 +418,44 @@ class AsyncClient {
    * @returns {Promise<string|null>} The dominant emotion across the timeline
    */
   async getDominantEmotion(requestId) {
+    const counts = await this.getEmotionCounts(requestId);
+    if (!counts || Object.keys(counts).length === 0) {
+      return null;
+    }
+
+    return Object.keys(counts).reduce((a, b) =>
+      counts[a] > counts[b] ? a : b
+    );
+  }
+
+  /**
+   * Alias for getDominantEmotion. Get the most frequently occurring emotion.
+   * @param {string} requestId - Request ID from upload method
+   * @returns {Promise<string|null>} The dominant emotion across the timeline
+   */
+  async majorityEmotion(requestId) {
+    return this.getDominantEmotion(requestId);
+  }
+
+  /**
+   * Get counts of each emotion in the timeline
+   * @param {string} requestId - Request ID from upload method
+   * @returns {Promise<Object>} Object mapping emotion names to their occurrence counts
+   *                           (e.g., {happy: 10, sad: 3, angry: 8, neutral: 9})
+   */
+  async getEmotionCounts(requestId) {
     const timeline = await this.getTimeline(requestId);
     if (!timeline || timeline.length === 0) {
-      return null;
+      return {};
     }
 
-    const emotionCounts = {};
+    const counts = {};
     for (const emotionData of timeline) {
       const emotion = emotionData.emotion;
-      emotionCounts[emotion] = (emotionCounts[emotion] || 0) + 1;
+      counts[emotion] = (counts[emotion] || 0) + 1;
     }
 
-    return Object.keys(emotionCounts).reduce((a, b) =>
-      emotionCounts[a] > emotionCounts[b] ? a : b
-    );
+    return counts;
   }
 }
 

package/tests/asyncAudio.test.js

@@ -2,7 +2,7 @@ import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globa
 import nock from 'nock';
 import fs from 'fs';
 import { ValenceClient } from '../src/valenceClient.js';
-import { AudioTooShortError } from '../src/errors.js';
+import { AudioTooShortError, AudioTooLongError } from '../src/errors.js';
 
 describe('AsyncAudio', () => {
   const originalEnv = process.env;
@@ -205,6 +205,34 @@ describe('AsyncAudio', () => {
         expect(error.message).toContain('too short');
       }
     });
+
+    test('should throw AudioTooLongError when audio is too long', async () => {
+      fsMock.mockReturnValue(true);
+      statMock.mockReturnValue({ size: 2000000000 }); // Large file
+
+      nock('https://test-api.com')
+        .post('/v1/asynch/emotion/upload/initiate')
+        .query(true)
+        .reply(400, {
+          error: 'Audio file exceeds maximum duration. Maximum: 3600 seconds, provided: 5000 seconds',
+          error_code: 'AUDIO_TOO_LONG',
+          max_duration_seconds: 3600,
+          actual_duration_seconds: 5000
+        });
+
+      const client = new ValenceClient({ apiKey: 'test-api-key' });
+
+      try {
+        await client.asynch.upload('long_audio.wav');
+        expect.fail('Should have thrown AudioTooLongError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(AudioTooLongError);
+        expect(error.name).toBe('AudioTooLongError');
+        expect(error.maxDuration).toBe(3600);
+        expect(error.actualDuration).toBe(5000);
+        expect(error.message).toContain('exceeds maximum');
+      }
+    });
   });
 
   describe('getEmotions', () => {

package/tests/discreteAudio.test.js

@@ -2,7 +2,7 @@ import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globa
 import nock from 'nock';
 import fs from 'fs';
 import { ValenceClient } from '../src/valenceClient.js';
-import { AudioTooShortError } from '../src/errors.js';
+import { AudioTooShortError, FileSizeLimitExceededError } from '../src/errors.js';
 
 describe('DiscreteAudio', () => {
   const originalEnv = process.env;
@@ -11,12 +11,24 @@ describe('DiscreteAudio', () => {
   beforeEach(() => {
     process.env = { ...originalEnv };
     process.env.VALENCE_API_KEY = 'test-api-key';
+    process.env.VALENCE_API_BASE_URL = 'https://test-api.com';
     process.env.VALENCE_DISCRETE_URL = 'https://test-api.com/predict';
-    
+
     fsMock = jest.spyOn(fs, 'existsSync');
-    jest.spyOn(fs, 'createReadStream').mockReturnValue({
+
+    // Default mock for createReadStream
+    const mockStream = {
       pipe: jest.fn(),
-      on: jest.fn()
+      on: jest.fn(),
+      pause: jest.fn(),
+      resume: jest.fn(),
+      destroy: jest.fn()
+    };
+    jest.spyOn(fs, 'createReadStream').mockReturnValue(mockStream);
+
+    // Default mock for statSync (1MB file)
+    jest.spyOn(fs, 'statSync').mockReturnValue({
+      size: 1 * 1024 * 1024
     });
   });
 
@@ -205,5 +217,48 @@ describe('DiscreteAudio', () => {
         'API error (400): Invalid file format'
       );
     });
+
+    test('should throw FileSizeLimitExceededError when file exceeds 6MB', async () => {
+      fsMock.mockReturnValue(true);
+
+      // Mock file size to be 7MB (7 * 1024 * 1024 bytes)
+      jest.spyOn(fs, 'statSync').mockReturnValue({
+        size: 7 * 1024 * 1024
+      });
+
+      const client = new ValenceClient();
+
+      try {
+        await client.discrete.emotions('large_audio.wav');
+        expect.fail('Should have thrown FileSizeLimitExceededError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(FileSizeLimitExceededError);
+        expect(error.name).toBe('FileSizeLimitExceededError');
+        expect(error.maxSizeMb).toBe(6.0);
+        expect(error.actualSizeMb).toBe(7.0);
+        expect(error.message).toContain('exceeds discrete API maximum');
+      }
+    });
+
+
+    test('should throw FileSizeLimitExceededError when file is exactly 6.1MB', async () => {
+      fsMock.mockReturnValue(true);
+
+      // Mock file size to be 6.1MB
+      jest.spyOn(fs, 'statSync').mockReturnValue({
+        size: 6.1 * 1024 * 1024
+      });
+
+      const client = new ValenceClient();
+
+      try {
+        await client.discrete.emotions('large_audio.wav');
+        expect.fail('Should have thrown FileSizeLimitExceededError');
+      } catch (error) {
+        expect(error).toBeInstanceOf(FileSizeLimitExceededError);
+        expect(error.maxSizeMb).toBe(6.0);
+        expect(error.actualSizeMb).toBeCloseTo(6.1, 1);
+      }
+    });
   });
 });

package/examples/uploadLong.js

@@ -1,10 +0,0 @@
-import { ValenceClient } from 'valenceai';
-
-(async () => {
-  const client = new ValenceClient();
-  const requestId = await client.asynch.upload('long_audio.wav');
-  console.log('Request ID:', requestId);
-
-  const result = await client.asynch.emotions(requestId);
-  console.log('Emotion:', result);
-})();

package/examples/uploadShort.js

@@ -1,7 +0,0 @@
-import { ValenceClient } from 'valenceai';
-
-(async () => {
-  const client = new ValenceClient();
-  const result = await client.discrete.emotions('sample.wav', '7emotions');
-  console.log(result);
-})();