chore(example): add polling/streaming mode toggle and status panel

[duyhungtnn]

This pull request significantly enhances the example application for the Bucketeer JS Client SDK by improving developer experience, documentation, and the demonstration of streaming capabilities. The updates include a more user-friendly and informative UI, better environment variable management, and the introduction of a custom streaming adapter to illustrate advanced SDK usage.

Example app improvements:

• The example app UI (example/index.html) has been redesigned with a new header, clearer controls, and a status panel that displays update mode, stream state, last update, evaluation/heartbeat counts, and inferred connection status. Controls for clearing logs and toggling update modes (polling, built-in streaming, custom event source) have been added, and button states are more accurately managed.
• The app now reads feature flag and goal identifiers from environment variables, allowing configuration via .env files. The default values are provided in example/env.template, and the README has been updated to clarify environment setup for both development and the example app. [1] [2]

Streaming and advanced usage:

• A custom EventSourceAdapter (example/eventSourceAdapter.ts) has been introduced, demonstrating how to satisfy the SDK's EventSourceLike contract using the eventsource-client library. This enables advanced users to swap out the default streaming transport for a custom one if needed.
• The example app's logic (example/index.ts) has been updated to support switching between polling, built-in streaming, and custom event source modes. It uses the new adapter and tracks streaming state, terminal failures, and network events to provide real-time feedback in the UI. [1] [2]

Documentation and configuration:

• The README now clearly distinguishes between the main .env (for development/tests) and the example app's .env, with step-by-step setup instructions for both.
• The new example/env.template documents all demo-related environment variables, including streaming options and demo flag/goal IDs.

[Copilot]

🟡 Changes recommended

Moderate issues remain in SSE lifecycle handling, status accuracy, mode switching, and accessibility.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds runtime-selectable polling/SSE modes and network-derived connection diagnostics to the example app.

Changes:

• Adds mode controls, connection status metrics, and flag-value UI.
• Adds fetch instrumentation and a custom SSE adapter.
• Separates example environment configuration from SDK development settings.

File summaries

File	Description
README.md	Documents standalone example environment setup.
example/vite.config.ts	Loads environment variables from the example directory.
example/types.ts	Defines instrumentation and transport types.
example/package.json	Adds the custom SSE client dependency.
example/loggingFetch.ts	Instruments polling and streaming activity.
example/index.ts	Implements mode selection and status management.
example/index.html	Adds mode controls and status panels.
example/eventSourceAdapter.ts	Adapts eventsource-client to the SDK interface.
example/env.template	Provides example-specific configuration variables.

Review details

• Files reviewed: 9/10 changed files
• Comments generated: 9
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Two moderate error-handling and terminal-stream-state issues remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 9/10 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Multiple moderate SSE parsing, lifecycle, and accessibility issues remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

example/eventSourceAdapter.ts:6

• This React Native example is inaccurate: eventsource-client@1.2.0 itself requires ReadableStream, and its default entry point rejects bodies that are not Web ReadableStream instances. Remove this claimed use case or use an adapter/library that actually supports that runtime without the polyfill.

// the built-in transport can't work (e.g. React Native without a fetch +
// ReadableStream polyfill) or a specific SSE library is required.

example/index.html:24

• This wording implies that the SDK's default polling interval is 60 seconds, but the SDK default is 10 minutes; only this example overrides it to 60 seconds. Distinguish the default mode from the demo-specific interval.

      <label style="display: block;"><input type="radio" name="mode" value="polling"> polling (comparison mode, matches the SDK default: up to 60s to see a change)</label>

• Files reviewed: 9/10 changed files
• Comments generated: 5
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

The new SSE adapter and framing parser lack required automated coverage for critical edge cases.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

example/loggingFetch.ts:52

• This rescans and reallocates the entire unterminated SSE block on every network chunk. Large initial put snapshots split across many chunks therefore make the display-side tee branch quadratic and can stall the page even though the SDK parser avoids this with a retained search offset (src/internal/streaming/FetchEventSource.ts:140-174). Parse completed delimiters incrementally and retain only the unconsumed suffix.

      buffer += chunkText.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
      const blocks = buffer.split('\n\n')
      buffer = blocks.pop() ?? ''

• Files reviewed: 9/10 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🟢 Approval recommended

All reviewed changes are covered with no unresolved approval-blocking issues.

Review details

• Files reviewed: 13/14 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

SSE data parsing incorrectly removes all leading whitespace from payload lines.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 13/14 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Two moderate status-reporting issues must be corrected before approval.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

example/eventSourceAdapter.ts:172

• Report the closure before invoking onerror. For non-terminal statuses outside the fast-retry set (for example 400/413/422), onerror synchronously starts the SDK's polling fallback, whose request sets the panel to polling fallback; the subsequent closed report here overwrites it with disconnected, leaving the custom-mode status incorrect while polling is active.
  example/index.ts:136
• Every streaming initialization still performs the SDK's mandatory bootstrap get_evaluations request (BKTClient.scheduleAndFetch() starts tasks and then calls fetchEvaluations). This branch therefore labels a normally connecting stream as polling fallback before any streaming failure has occurred; with a slow stream handshake, the incorrect state can remain visible until the connection opens or times out. Ignore this bootstrap request while initializing is true, and reserve the fallback label for later polling requests.

• Files reviewed: 13/14 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

The fallback polling status can be incorrectly suppressed during initialization.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 13/14 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟢 Approval recommended

The reviewed changes have no unresolved approval-blocking issues.

Review details

• Files reviewed: 13/14 changed files
• Comments generated: 0 new
• Review effort level: Balanced