Create new Snap Conversions API v3 destination with intelligent event mapping and batching

[Copilot]

This PR creates a new separate destination called snap-conversions-v3 with enhanced functionality for Snapchat Conversions API integration, while preserving the existing snap-conversions-api destination unchanged for backward compatibility.

New Destination: Snap Conversions API v3

The new destination provides four specialized actions with intelligent defaults and enhanced functionality:

1. Track Event (trackEvent)

• Subscription: type = "track"
• Purpose: Standard event tracking with intelligent event name mapping
• Features: Automatically maps common Segment events to appropriate Snapchat event names

2. Track App Event (trackAppEvent)

• Subscription: type = "track" and context.device.type != null
• Purpose: App-specific event tracking optimized for mobile conversion tracking
• Features: Enhanced app data and device information handling

3. Track Purchase (trackPurchase)

• Subscription: type = "track" and event = "Order Completed"
• Purpose: Purchase/conversion events with enhanced ecommerce data
• Features: Optimized for Order Completed events with detailed product information

4. Sync User Data (syncUserData)

• Subscription: type = "identify"
• Purpose: User data synchronization without event tracking
• Features: Updates user profiles for better ad targeting

Key Features

Intelligent Event Mapping

The trackEvent action automatically maps Segment event names to Snapchat event names:

// Segment Event → Snapchat Event Name
'Product Added' → 'ADD_CART'
'Product Viewed' → 'VIEW_CONTENT'
'Order Completed' → 'PURCHASE'
'Checkout Started' → 'START_CHECKOUT'
// ... and 10 more mappings

Batching Support

All new actions support batching up to 2,000 events per request (Snapchat API limit):

// Validates batch size and processes multiple events efficiently
export const performSnapCAPIv3Batch = async (
  request: RequestClient,
  data: ExecuteInput<Settings, Payload[]>
): Promise<ModifiedResponse<unknown>> => {
  if (payload.length > 2000) {
    throw new IntegrationError('Batch size cannot exceed 2,000 events', 'Invalid Input', 400)
  }
  // ... batch processing logic
}

Enhanced Default Mappings

Each action includes optimized default field mappings:

• trackEvent: action_source: 'website', standard field mappings
• trackAppEvent: action_source: 'app', app-specific mappings
• trackPurchase: event_name: 'PURCHASE', ecommerce mappings
• syncUserData: event_name: 'UPDATE_PROFILE', user profile mappings

Technical Implementation

• Separate destination: New snap-conversions-v3 destination preserves existing integrations
• Reuses enhanced field definitions for consistency and maintainability
• Leverages existing PII hashing with SHA-256 using processHashing utility
• Maintains original destination unchanged for full backward compatibility
• Comprehensive error handling with proper validation for all scenarios
• Full test coverage including unit tests, batch scenarios, and event mapping validation

Benefits

1. Better Developer Experience: Specific actions for different use cases with intelligent defaults
2. Improved Performance: Batching support for high-volume event processing
3. Automatic Event Mapping: No manual event name configuration needed for common events
4. Enhanced Targeting: Specialized actions for app events and user data synchronization
5. Backward Compatibility: Existing integrations remain unchanged
6. Production Ready: Comprehensive testing and error handling

This implementation provides a more intuitive and powerful interface for sending conversion data to Snapchat while maintaining full compatibility with existing integrations.

Fixes #3191.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.