feat: Add an opt-in fetch-based EventSource entry to the browser SDK

[joker23]

Summary

Adds an opt-in fetch()-based EventSource to the browser SDK behind its own @launchdarkly/js-client-sdk/fetch-eventsource entry point, so neither the implementation nor its dependency reaches the default bundle. The native browser EventSource remains the default. Includes the eventSource factory option plumbing and an example app.

The browser contract-test entity can be opened with ?eventsource=fetch, which makes every client use the fetch-based EventSource and advertise the client-use-post and client-event-source-http-errors capabilities. CI runs the fetch entity against both harnesses with no skip list: the v2 run covers the FDv1 path, including REPORT streaming and the tags header tests, and the v3 run covers the FDv2 path, including the usePost POST streaming variants.

The transport does not send the x-launchdarkly-tags header. The streaming service's CORS allow-list does not include it, and the browser preflight would fail.

Replaces #2034 and #2048, which GitHub auto-marked merged during a stack reorder; their bot-review history lives there.

---

Note

Overview
Adds an opt-in fetch()-based streaming transport for the browser SDK via a separate @launchdarkly/js-client-sdk/fetch-eventsource export (optional @launchdarkly/eventsource dependency), keeping the native EventSource as the default bundle.

Introduces the eventSource factory option: validated in browser options, wired through BrowserPlatform / BrowserRequests, and used to advertise transport capabilities (e.g. POST streaming when customMethod is true). fetchBrowserEventSource forwards stream init options but drops x-launchdarkly-tags because CORS preflight would fail.

Contract tests and CI gain a ?eventsource=fetch entity mode (injects the fetch factory, enables usePost, advertises client-use-post / client-event-source-http-errors), extra harness runs (native + fetch for FDv1/FDv2), updated suppression lists, and a small custom EventSource example app.

In shared FDv2 streaming, StreamingFDv2Base avoids duplicate interrupted results when transports invoke both the error filter and onerror for the same failure.

^{Reviewed by Cursor Bugbot for commit 5b13155. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 31343 bytes
Compressed size limit: 31500
Uncompressed size: 148858 bytes

[github-actions]

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 26046 bytes
Compressed size limit: 44000
Uncompressed size: 168246 bytes

[github-actions]

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 34246 bytes
Compressed size limit: 35000
Uncompressed size: 122308 bytes

[devin-ai-integration]

Devin Review found 1 potential issue.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[devin-ai-integration]

🟡 Network failures reported as HTTP errors

For a status-less fetch failure, alreadyReported suppresses the network error after handleError queues an HTTP error with status 0. Clients receive ERROR_RESPONSE instead of NETWORK_ERROR, losing the failure message.

Learn more

The fetch-based EventSource calls the error filter before dispatching its error event. For a status-less failure, handleError currently builds errorInfoFromHttpError(0). The new guard discards the subsequent onerror result, which previously carried errorInfoFromNetworkError(err.message). The orchestrator passes the remaining error kind, message, and status code into reportStatusError, so consumers now see an HTTP response that never occurred.

Example: If fetch() rejects with network unreachable, the stream reports ERROR_RESPONSE, Unexpected status code: 0, and status code 0 instead of NETWORK_ERROR and network unreachable.

Recommended fix: Classify status-less failures as network errors in handleError, using the provided message, while retaining the single-result suppression in onerror. Add an assertion for the error kind and message in the status-less failure test.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Optional EventSource pin is unpublished

High Severity

The browser SDK pins optional @launchdarkly/eventsource to 0.2.1, but the workspace package, changelog, and release-please manifest are still at 0.2.0. Installs skip the missing optional package, so importing @launchdarkly/js-client-sdk/fetch-eventsource fails to resolve createEventSource.

 

^{Reviewed by Cursor Bugbot for commit 4577f29. Configure here.}

[joker23]

I think this is false

[cursor]

Example pins a nonexistent SDK version

Medium Severity

The new example depends on @launchdarkly/js-client-sdk 4.13.0, but the workspace package is still 4.12.0 (as is example/package.json). Yarn will not link the local SDK for an unsatisfied exact range, so the example cannot install or import the new fetch-eventsource entry until that version exists.

 

^{Reviewed by Cursor Bugbot for commit 4577f29. Configure here.}

[joker23]

I also think this is false

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5b13155. Configure here.}

[cursor]

Network errors misclassified as HTTP errors

Medium Severity

The new filterHandledFailure mark stops onerror from reporting a status-less failure after the error filter already ran, which is the fetch EventSource path. handleError still always builds errorInfoFromHttpError(err.status ?? 0), so a network drop is recorded as ErrorResponse with status 0 ("Unexpected status code: 0") instead of NETWORK_ERROR. Data source status, inspectors, and diagnostics then show the wrong error kind for every offline or connection-drop on the opt-in transport.

Additional Locations (1)

• packages/shared/sdk-client/src/datasource/fdv2/StreamingFDv2Base.ts#L417-L420

 

^{Reviewed by Cursor Bugbot for commit 5b13155. Configure here.}