feat: add type-safe overloads for sendGAEvent with GA4 recommended event types

[hjick]

What?

Add TypeScript overload signatures to the sendGAEvent function in @next/third-parties/google and define GA4 recommended event types for autocomplete support.

Why?

The current sendGAEvent function accepts ...args: Object[], which is too ambiguous — it provides no autocomplete or type checking for GA4 event parameters. This makes it easy to pass incorrect arguments without any IDE feedback.

Related: #63226, #62065

According to the GA4 gtag.js event reference, events should follow the pattern:

gtag('event', '<event_name>', { <event_parameters> })

How?

TypeScript overloads (no runtime changes):

1. Recommended event overload — provides autocomplete for 37 GA4 recommended events (purchase, add_to_cart, login, etc.) with their exact parameter types
2. Custom event overload — typed signature for custom events: sendGAEvent('event', 'my_event', { key: 'value' })
3. Legacy overload — sendGAEvent(...args: Object[]) preserved for full backward compatibility

The runtime implementation remains unchanged (window[dataLayer].push(arguments)), so existing code continues to work without modification.

GA4 recommended event types include:

• Online Sales: add_payment_info, add_shipping_info, add_to_cart, add_to_wishlist, begin_checkout, purchase, refund, remove_from_cart, select_item, select_promotion, view_cart, view_item, view_item_list, view_promotion
• Lead Generation: close_convert_lead, close_unconvert_lead, disqualify_lead, generate_lead, qualify_lead, working_lead
• Games: level_end, level_start, level_up, post_score, unlock_achievement
• All Properties: earn_virtual_currency, exception, join_group, login, page_view, search, select_content, share, sign_up, spend_virtual_currency, tutorial_begin, tutorial_complete, view_search_results

Usage example:

// Recommended event — full autocomplete for event name and parameters
sendGAEvent('event', 'purchase', {
  currency: 'USD',
  value: 99.99,
  transaction_id: 'T12345',
  items: [{ item_id: 'SKU1', item_name: 'Product' }],
})

// Custom event — typed but flexible
sendGAEvent('event', 'newsletter_signup', { method: 'popup' })

// Legacy usage — still works
sendGAEvent({ event: 'buttonClicked', value: 'xyz' })

For Contributors

Adding a feature

• Related issues/discussions are linked using fixes #number
• No runtime behavior changes — type-only enhancement
• Existing e2e tests continue to pass (legacy overload preserves backward compatibility)

[nextjs-bot]

Allow CI Workflow Run

• approve CI run for commit: 94a5641

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

[vercel]

Suggested change

Trailing space character on line 77 of ga.tsx causes prettier formatting check to fail.