admesh-ui-sdk/CHANGELOG.md

Beautiful, modern React components for displaying AI-powered product recommendations with citation-based conversation ads, auto-triggered widgets, floating chat, conversational interfaces, persistent sidebar, and built-in tracking. Includes zero-code SDK

# Changelog

All notable changes to the AdMesh UI SDK 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.19] - 2025-01-XX

### Changed
- **Format configuration**: `allowed_formats` are now automatically fetched from platform configuration (set during onboarding). Platforms no longer need to specify formats in API requests or component props.
- **Backend integration**: The SDK now relies on the backend to automatically fetch and validate `allowed_formats` from the platform's database configuration, simplifying integration.

### Documentation
- Updated documentation to clarify that `allowed_formats` are automatically fetched from platform configuration
- Added notes about automatic format selection for Vibe Coding Platforms during onboarding

## [1.0.16] - 2025-01-XX

## [1.0.15] - 2025-01-XX

## [1.0.14] - 2025-01-XX

### Added
- **latencyBudgetMs support in AdMeshRecommendations component**: Added `latencyBudgetMs` prop to `AdMeshRecommendations` component to allow platforms to specify their latency budget for ad responses. This ensures the backend uses the provided latency budget instead of defaulting to 2200ms.

### Fixed
- **Missing latency_budget_ms in requests**: Fixed issue where `AdMeshRecommendations` component was not passing `latencyBudgetMs` to the SDK, causing the backend to use default values and emit warnings.

## [1.0.10] - 2025-11-18

### Added
- **Inline exposure tracker for Weave links**: new utility monitors detected AdMesh anchors (50% visible for 1s) before firing their signed `exposure_url`, preventing premature pixels in organic/inline responses.

### Fixed
- **WeaveAdFormatContainer & useWeaveAdFormat** now fire exposure pixels only when in-view, leveraging the inline tracker and properly passing `sessionId` for deduplication.
- TypeScript build now emits declarations for the new tracker and tightened callback types.

### Breaking
- `WeaveResponseProcessor.scanAndProcessLinks` now invokes the `onExposurePixel` callback with an object `{ exposureUrl, adId, linkElement }` so consumers have access to the DOM node required for viewability tracking. Update custom integrations accordingly.

## [1.0.9] - 2025-11-17

### Fixed
- **🚨 CRITICAL: Fixed exposure tracking system** - Exposure pixels now fire correctly when ads meet MRC viewability standards
  - Added exposure pixel firing to `AdMeshViewabilityTracker` component
  - Exposure pixels fire when ads are 50% visible for 1 continuous second (MRC-compliant)
  - Removed legacy immediate exposure firing from `AdMeshSDK` (non-MRC compliant)
  - Added `exposureUrl`, `sessionId`, and `recommendationId` props to `AdMeshViewabilityTracker`
  - Added `sessionId` prop threading through component tree (`AdMeshProductCard` → `AdMeshSummaryLayout` → `AdMeshLayout` → `AdMeshRenderer`)
  - Prevents duplicate exposure tracking with `exposureFired` ref
  - Uses `fetch()` with `keepalive: true` for reliable pixel firing even during page unload

### Changed
- **Exposure tracking lifecycle**: Recommendations now transition from `generated` → `exposed` only when MRC viewability threshold is met
- **CPX billing**: Exposure pixels fire on viewability, not on recommendation fetch
- **Analytics**: More accurate exposure tracking aligned with industry standards (MRC viewability)

### Technical Details
- Exposure pixel fires via `fetch(exposureUrl, { method: 'GET', keepalive: true })`
- Viewability threshold: 50% of ad pixels visible for 1 continuous second
- Backend `/exposure` endpoint receives pixel and updates recommendation status atomically
- CPX budget reservation happens when exposure pixel fires, not when recommendations are generated

### Migration Notes
- **No breaking changes** - This is a bug fix release
- Existing integrations will automatically benefit from MRC-compliant exposure tracking
- No code changes required in your integration
- Exposure tracking will be more accurate and aligned with industry standards

## [1.0.0] - 2025-10-27

### BREAKING CHANGES
- **Removed deprecated Weave format support from AdMeshRecommendations component**
  - Removed `format="weave"` option from AdMeshRecommendations
  - Removed `llmOutputContainerId` prop from ShowRecommendationsOptions
  - Removed `timeoutMs` prop from AdMeshRecommendations
  - Removed `fallbackFormat` prop from AdMeshRecommendations
  - Removed `handleWeaveFormat()` method from SDK (deprecated)

### Migration Guide
If you were using the deprecated Weave format pattern:

**Before (Deprecated):**
```typescript
<AdMeshRecommendations
  messages={messages}
  format="weave"
  timeoutMs={1500}
  fallbackFormat="citation"
/>
```

**After (Recommended):**
```typescript
<WeaveAdFormatContainer
  messageId={msg.id}
  fallbackUI={
    <AdMeshRecommendations
      messages={[msg]}
      format="citation"
    />
  }
>
  {msg.content}
</WeaveAdFormatContainer>
```

### Added
- **WeaveAdFormatContainer component** - Recommended pattern for Weave Ad Format
  - Automatically detects AdMesh links in LLM responses
  - Fires exposure tracking for detected links
  - Adds [Ad] labels to links
  - Shows "Why this ad?" tooltip on hover
  - Conditionally renders fallback UI only when no links detected

- **useWeaveAdFormat hook** - Automatic Weave Ad Format handling
  - Scans for AdMesh links in container
  - Fires exposure tracking
  - Manages fallback UI rendering
  - Supports streaming responses with MutationObserver

### Improved
- **Better separation of concerns** - Each component has single responsibility
- **Loose coupling** - Components are independent and reusable
- **Explicit control** - Developers explicitly provide fallbackUI prop
- **Cleaner architecture** - Single pattern for all cases

### Documentation
- Updated WEAVE_AD_FORMAT_EXAMPLES.md with new pattern
- Updated WEAVE_AD_FORMAT_INTEGRATION.md with recommended approach
- Added migration guides for existing users
- Created comprehensive integration documentation

## [0.19.22] - 2025-10-27

### Added
- **TEMPORARY: Global analytics disable flag** - `disableViewabilityAnalytics()`
  - Allows temporary disabling of all viewability analytics sending
  - Prevents any API calls to backend while keeping tracking logic intact
  - Useful for development, testing, and debugging
  - Easy to toggle on/off without code changes
  - Fails silently with optional debug logging

### Usage
```typescript
import { disableViewabilityAnalytics } from 'admesh-ui-sdk';

// Disable all analytics
disableViewabilityAnalytics(true);

// Re-enable analytics
disableViewabilityAnalytics(false);
```

### Implementation
- Added global `ANALYTICS_DISABLED` flag
- Check in `sendEvent()` to skip event sending
- Check in `flushBatch()` to clear queued events
- Console warnings when toggled
- No breaking changes, fully backward compatible

## [0.19.21] - 2025-10-27

### Changed
- **MAJOR: Viewability Analytics Cost Optimization** - 85-95% storage reduction
  - Only sends critical events (`ad_viewable`, `ad_click`) to backend
  - Backend converts events to optimized `viewability_summary` format
  - Stores context snapshot once per recommendation instead of per event
  - Reduces per-recommendation storage from 8-40 KB to ~700 bytes
  - Maintains full MRC compliance and reporting capabilities

### Backend Changes
- New `/api/recommendations/viewability/batch` endpoint with event-to-summary conversion
- Stores `viewability_summary` object with aggregated metrics
- Stores `context_snapshot` once per recommendation
- Backward compatible with old `viewability_analytics` array format

### Build
- ESM: 103.12 KB (24.68 KB gzipped)
- CommonJS: 75.87 KB (19.70 KB gzipped)

## [0.19.20] - 2025-10-27

### Fixed
- **Viewability Analytics Batch Submission**: Fixed HTTP 422 errors in batch endpoint
  - Updated viewability tracker to use new `/api/recommendations/viewability/batch` endpoint
  - Backend now properly converts camelCase SDK field names to snake_case for Pydantic validation
  - Improved batch event processing with proper error handling and per-event error tracking
  - Enhanced logging for debugging batch submission issues

### Changed
- Viewability analytics endpoint changed from `/api/recommendations/viewability` to `/api/recommendations/viewability/batch`
- SDK now sends batches with proper format that backend can parse and convert
- Enhanced error reporting in batch processing

### Build
- ESM: 102.94 KB (24.61 KB gzipped)
- CommonJS: 75.72 KB (19.63 KB gzipped)

## [0.19.19] - 2025-10-27

### Fixed
- **Weave Format Rendering Issue**: Fixed bug where both woven ads and fallback UI were displayed simultaneously
  - Improved `scanLLMOutputForAdMeshLinks` method with better polling and MutationObserver coordination
  - Added Promise.race() to handle both polling and real-time detection
  - Removed duplicate observer setup that was causing race conditions
  - Added proper cleanup of MutationObserver in finally block
  - Improved logging for debugging link detection

- **Link Detection Reliability**: Enhanced detection of AdMesh links in LLM output
  - Combined polling with MutationObserver for more reliable detection
  - Prevents multiple observers from being created during polling
  - Better handling of streaming responses

### Changed
- Refactored `scanAndLabelAds` to only scan for links, not set up observers
- Improved error handling and logging in link detection flow
- Better resource cleanup with proper observer disconnection

### Build
- ESM: 102.88 KB (24.58 KB gzipped)
- CommonJS: 75.72 KB (19.63 KB gzipped)

## [0.19.18] - 2025-10-27

### Added
- **Viewability Analytics Endpoint Integration**: New endpoint for storing MRC viewability analytics in recommendations collection
  - Added `recommendation_id` field to viewability analytics events
  - Updated `useViewabilityTracker` hook to accept and track `recommendationId` prop
  - New backend endpoint: `POST /api/recommendations/viewability`
  - Viewability events now stored in `recommendations.viewability_analytics` array
  - Each event includes recommendation document ID for proper linking

- **Enhanced Analytics Payload**:
  - Added `recommendation_id` to ViewabilityAnalyticsEvent type
  - Improved error reporting with detailed error messages
  - Added `keepalive: true` to fetch requests for better reliability

### Changed
- Updated default API endpoint to `https://api.useadmesh.com/api/recommendations/viewability`
- Enhanced error handling with detailed error text logging
- Improved fetch request reliability with keepalive flag
- Updated ViewabilityAnalyticsEvent interface to include recommendationId

### Build
- ESM: 101.58 KB (24.18 KB gzipped)
- CommonJS: 75.25 KB (19.50 KB gzipped)

## [0.19.17] - 2025-10-27

### Fixed
- **Weave Format Rendering Issue**: Fixed bug where both woven ads and fallback UI were displayed simultaneously
  - Added proper error handling in `handleWeaveFormat` method
  - Ensured early return when AdMesh links are detected in LLM output
  - Added debug logging for troubleshooting
  - Prevents duplicate rendering of recommendations

- **HTTP 422 Viewability Tracking Errors**: Resolved backend compatibility issues
  - Disabled problematic viewability tracking endpoint by default (empty apiEndpoint)
  - Updated `sendAnalyticsEvent` and `sendAnalyticsBatch` to gracefully handle empty endpoints
  - Analytics are still collected locally but not sent to backend by default
  - Consuming applications can configure the endpoint if needed via `setViewabilityTrackerConfig`

### Changed
- **Viewability Tracking**: Made endpoint configuration optional and disabled by default
  - Prevents HTTP 422 errors from being sent to non-existent or incompatible endpoints
  - Maintains local analytics collection for future backend integration
  - Provides better developer experience with no console errors

### Performance
- Reduced unnecessary network requests by disabling default endpoint
- Improved error handling to prevent retry loops on missing endpoints

## [0.19.16] - 2025-10-26

### Added
- **MRC Viewability Compliance**: Implemented Media Rating Council (MRC) viewability standards for all ad formats
- **Intersection Observer API**: Advanced visibility tracking with 10 threshold levels (0%, 10%, 20%, ..., 100%)
- **AdMeshViewabilityTracker Component**: React wrapper component for MRC-compliant exposure tracking
- **fireExposureWithMRCCompliance() Method**: New tracker method enforcing 50% visibility for 1 second threshold
- **Comprehensive MRC Documentation**: Added MRC_COMPLIANCE.md with implementation details and testing guidelines

### Changed
- **Exposure Tracking Architecture**: Refactored to use component-based viewability tracking instead of immediate firing
- **AdMeshProductCard**: Wrapped with AdMeshViewabilityTracker for both simple and default variations
- **AdMeshSummaryUnit**: Wrapped with AdMeshViewabilityTracker for citation units
- **AdMeshEcommerceCards**: Each card individually wrapped with AdMeshViewabilityTracker

### Fixed
- Fixed all TypeScript compilation errors (removed `any` types, unused imports, unused variables)
- Improved type safety across all components
- Fixed ref type compatibility issues in AdMeshViewabilityTracker

### Performance
- Efficient Intersection Observer implementation with passive event listeners
- Asynchronous exposure pixel firing with `keepalive: true`
- Batched analytics events to reduce network requests
- Lazy initialization of tracker and renderer components

### Documentation
- Added MRC_COMPLIANCE.md with detailed implementation guide
- Documented MRC viewability standards (50% visible for 1 second)
- Added configuration options and testing guidelines
- Included browser support information

## [0.19.12] - 2025-10-24

### Added
- **Weave Mode**: Automatic link detection and enhancement for organic LLM responses
- **WeaveResponseProcessor**: New utility for scanning and processing AdMesh links in HTML/markdown content
- **Multi-Domain Support**: Support for both `api.useadmesh.com` and `*.useadmesh.com` domains
- **Automatic Label Enhancement**: Adds `[Ad]` labels to detected AdMesh links
- **Exposure Tracking**: Automatic pixel firing for detected links
- **Streaming Response Support**: MutationObserver integration for detecting links in streaming responses
- **npm Publication**: Package fully prepared for npm registry publication

### Changed
- **Performance Optimization**: 97% faster link detection using optimized CSS selectors
- Updated domain references from `api.admesh.com` to `api.useadmesh.com`
- Enhanced README with npm badges and registry link
- Improved package.json with npm best practices (author, bugs, homepage, engines)

### Fixed
- Improved link detection accuracy with fallback mechanism
- Better handling of edge cases in link processing

### Documentation
- Added comprehensive npm publication guide
- Created pre-publish checklist with 50+ verification items
- Updated Mintlify documentation with Weave mode details
- Added supported domains documentation

### Build & Quality
- ✅ ESM Build: 106 KB (25.31 KB gzipped)
- ✅ CommonJS Build: 82 KB (21.34 KB gzipped)
- ✅ Type Definitions: Complete and valid
- ✅ Source Maps: Generated for debugging
- ✅ Security: No vulnerabilities, no sensitive data
- ✅ 100% Backward Compatible

## [0.13.0] - 2025-01-10

### Added
- **Unified JSON Schema**: Implemented comprehensive unified schema that works across all recommendation sources (Walmart, AdMesh, Amazon, etc.)
- Enhanced shipping information structure with detailed options (`free_shipping_over_35`, `standard_rate`, `two_day_rate`, `ship_to_store`, `free_ship_to_store`)
- New required fields for better data consistency:
  - `ad_id`: Unique advertisement identifier
  - `external_id`: External source identifier (e.g., Walmart item ID)
  - `pricing`: Formatted price string (e.g., "$99.48")
  - `recommendation_title`: Marketing-optimized title
  - `recommendation_description`: Marketing-optimized description
  - `brand_trust_score` and `offer_trust_score`: Trust scoring metrics
  - `is_fallback`: Indicates if recommendation is a fallback option
  - `feature_sections`: Structured feature information
- Content variations support for different presentation formats
- Comprehensive example component demonstrating unified schema usage

### Changed
- **BREAKING**: Updated `AdMeshRecommendation` interface to use unified schema structure
- **BREAKING**: Updated `EcommerceProduct` interface to align with unified schema
- Removed deprecated Walmart-specific fields in favor of standardized fields
- Enhanced `AdMeshEcommerceCards` component to work with unified schema
- Updated documentation to reflect unified schema structure
- Improved type safety with required vs optional field distinctions

### Removed
- Deprecated Walmart-specific fields (`walmart_item_id`, `walmart_price`, etc.) - now handled through unified schema
- Legacy field mappings that are no longer needed

### Migration Guide
If you're upgrading from a previous version:

1. **Update your data structure** to match the new unified schema
2. **Replace Walmart-specific fields** with standardized equivalents:
   - `walmart_item_id` → `external_id`
   - `walmart_sale_price` → `price`
   - `walmart_price` → `original_price`
   - `walmart_images.large` → `image_url`
   - `walmart_brand` → `brand`
3. **Ensure required fields** are present in your recommendation data
4. **Update shipping_info structure** to use new detailed format

## [0.12.3] - 2025-01-09

### Fixed
- Minor bug fixes and improvements

## [0.11.0] - 2025-01-09

### Added
- **AdMeshEcommerceCards** - New horizontal scrolling product cards component for ecommerce recommendations
- **Google-style Product Display** - Product cards similar to Google product search results with images, pricing, ratings
- **Mixed Source Support** - Display both AdMesh affiliate offers and external ecommerce products (Walmart, Amazon, etc.)
- **Intelligent Product Ranking** - Physical products ranked higher for ecommerce queries, software for software queries
- **Responsive Design** - Mobile-optimized horizontal scrolling with touch support
- **Rich Product Information** - Pricing, discounts, ratings, reviews, shipping info, availability status
- **Customizable Display** - Configurable card sizes, themes, shadows, border radius
- **Source Badges** - Optional badges showing product source (Walmart, AdMesh, etc.)
- **Discount Indicators** - Visual discount percentage badges on product images
- **Star Ratings** - Visual star rating display with review counts
- **Free Shipping Indicators** - Shipping information display
- **Brand Display** - Product brand information
- **Availability Status** - In stock/out of stock indicators
- **Click Tracking** - Built-in click tracking for affiliate links
- **Dark Mode Support** - Full dark theme compatibility
- **TypeScript Support** - Complete type definitions for EcommerceProduct interface
- **Storybook Stories** - Comprehensive component documentation and examples

### Enhanced
- Updated package version to 0.11.0
- Added EcommerceProduct and AdMeshEcommerceCardsProps type exports
- Enhanced README.md with AdMeshEcommerceCards documentation
- Added component to comparison table in documentation
- Created example usage file with real API response data conversion

### Technical
- Built with Vite and TypeScript
- CSS modules for styling isolation
- Responsive design with mobile-first approach
- Accessibility features (WCAG 2.1 AA compliant)
- Performance optimized with lazy loading images

## [0.8.0] - 2024-12-30

### Added
- **Citation-Based Conversation Ads** - New citation format for displaying recommendations as numbered references within conversational text
- `AdMeshCitationUnit` component - Main citation component with automatic product name detection and citation insertion
- `AdMeshCitationReference` component - Individual citation references for inline use
- **Clickable Product Names** - Product names in conversational text are now styled as clickable hyperlinks
- **Multiple Citation Styles** - Support for numbered (1), bracketed [1], and superscript¹ citation formats
- **Interactive Tooltips** - Hover over citations to see product details with match scores
- **Reference Lists** - Optional citation reference list at the bottom of conversational content
- **Smart Text Processing** - Automatic detection of product mentions in conversational text
- Citation mode support in `AdMeshConversationalUnit` component
- Comprehensive Storybook stories for all citation components
- Citation-specific TypeScript interfaces and types

### Enhanced
- Updated `AdMeshConversationalUnit` to support `'citation'` display mode
- Enhanced `AdMeshInlineRecommendation` with clickable product title styling
- Improved `AdMeshLinkTracker` integration for citation components
- Added citation-related keywords to package.json for better discoverability

### Documentation
- Updated README.md with comprehensive citation documentation
- Added citation usage examples and integration guides
- Created interactive HTML demos for citation functionality
- Updated conversational guide with citation mode examples

### Technical
- Enhanced TypeScript types for citation components
- Improved build process for citation component exports
- Added comprehensive test coverage for citation functionality
- Updated Storybook configuration for citation component stories

## [0.7.0] - 2024-12-29

### Added
- Sidebar components (`AdMeshSidebar`, `AdMeshSidebarHeader`, `AdMeshSidebarContent`)
- Chat components (`AdMeshFloatingChat`, `AdMeshChatInterface`, `AdMeshChatMessage`, `AdMeshChatInput`)
- Auto-recommendation widget (`AdMeshAutoRecommendationWidget`)
- Conversational ad units (`AdMeshConversationalUnit`, `AdMeshConversationSummary`, `AdMeshInlineRecommendation`)
- Multiple display modes for conversational components
- Comprehensive theming system
- Built-in tracking and analytics
- Responsive design improvements
- Accessibility enhancements

### Enhanced
- Improved component architecture
- Better TypeScript support
- Enhanced documentation
- Storybook integration

## [0.6.0] - 2024-12-28

### Added
- Initial release of core components
- `AdMeshLayout`, `AdMeshProductCard`, `AdMeshCompareTable` components
- Basic theming support
- TypeScript definitions
- Initial documentation

### Technical
- React 18+ support
- Vite build system
- Tailwind CSS integration
- ESLint and TypeScript configuration