conviva: preserve startup session across early sourcechange

[balazStefan]

conviva: avoid ending session on early startup sourcechange

Add optional startup-preservation config:

• preserveSessionOnStartupSourceChange (default false)
• startupGraceMs (default 10000)

When enabled, sourcechange events during startup (play -> playing)
within the grace window no longer end the Conviva session;
source metadata is refreshed instead.

Summary

Add optional startup source-change preservation to prevent premature Conviva session endings during startup transitions, while keeping default behavior unchanged.

What changed

API / Configuration

• Added preserveSessionOnStartupSourceChange?: boolean (default false)
• Added startupGraceMs?: number (default 10000)

Handler behavior

• Added DEFAULT_STARTUP_GRACE_MS = 10_000
• Normalized config defaults in constructor
• Added startup tracking with startupAt: number | null
• onPlay: marks startup start time
• onPlaying: clears startup marker
• onSourceChange:
  • if preservation is enabled and within grace window, keep session and refresh metadata
  • otherwise end session and keep existing source-change flow
• maybeReportPlaybackEnded: clears startup marker

Tests

Added unit coverage via public ConvivaConnector API and event-driven scenarios:

1. Preserve enabled + early sourcechange within grace -> session is preserved
2. Preserve enabled + grace elapsed -> session ends
3. Preserve disabled/default -> session ends (backward-compatible behavior)
4. Preserve enabled + after playing -> session ends on sourcechange

Documentation

• Updated README with new config options and defaults
• Added changelog entry under Unreleased

[changeset-bot]

⚠️ No Changeset found

Latest commit: f238687

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR