docs: addressing PR comments

Author: joker23

packages/sdk/browser/src/index.ts

@@ -13,11 +13,11 @@
 import { AutoEnvAttributes, LDContext } from '@launchdarkly/js-client-sdk-common';
 
 import { makeClient } from './BrowserClient';
-import { LDClient } from './LDClient';
+import { LDClient, LDStartOptions } from './LDClient';
 import { BrowserOptions as LDOptions } from './options';
 
 export * from './common';
-export type { LDClient, LDOptions };
+export type { LDClient, LDOptions, LDStartOptions };
 export type { LDPlugin } from './LDPlugin';
 
 /**

packages/sdk/browser/upgrade/v4.md

@@ -13,10 +13,12 @@ successfully upgrade.
 
 ## Key changes
 
-### Client creation
+### Client initialization
 
 **Key differences:**
 - Initialization is now split into 2 parts `createClient` and `start`
+- We split the original `LDOptions` that was passed into the `initialize()` function into
+  2 types `LDStartOptions` and `LDOptions`. [more here](#ldoptions)
 - Removed the use of `initialize` method
 
 **Before (v3.x):**
@@ -43,6 +45,21 @@ perform any necessary setup before the client begins connecting to LaunchDarkly.
 This eliminates race conditions where events might be missed if listeners were
 registered after the client had already started initializing.
 
+### LDOptions
+
+We moved a few things around in `LDOptions` to support the changes that are discussed in
+other parts of this doc. Please visit the following docs to see how to interact with our SDK:
+- [LDOptions](https://launchdarkly.github.io/js-core/packages/sdk/browser/docs/interfaces/LDOptions.html) that is passed into `createClient()`
+- [LDStartOptions](https://launchdarkly.github.io/js-core/packages/sdk/browser/docs/interfaces/LDStartOptions.html) that is passed into `start()`
+- [LDIdentifyOptions](https://launchdarkly.github.io/js-core/packages/sdk/browser/docs/interfaces/LDIdentifyOptions.html) that is passed into `identify()`
+
+**Key differences:**
+- `bootstrap` option is moved from `LDOptions` to `LDStartOptions` and `Identify`. The reason for this is that bootstrapping data is
+  now part of the initialization of a client instance.
+  > NOTE: that `identify` is a key part of the client initialization process required to associate the instance with an initial context.
+- The SDK now defaults to use local storage based caching.
+  > Previously, in order enable local storage caching, you will need to set this as a special value for the `bootstrap` property.
+
 ### Client initialization flow
 
 The new SDK uses `waitForInitialization()` which returns a result object instead of rejecting promises.
@@ -111,11 +128,15 @@ The `identify()` method now always returns a result object and never throws erro
 This provides more predictable error handling.
 
 **Key differences:**
-- `identify()` now takes an options object as the second parameter: `{ hash: '...' }` instead of a direct hash string
+- `identify()` now takes an options object as the second parameter: `LDIdentifyOptions` instead of a direct hash string
 - The method always returns a promise that resolves to a result object (never rejects)
 - You must check the `status` field to determine success or failure
 - The `hash` parameter is now part of the options object
+- `IdentifyOptions` now have a `sheddable` property that is `true` by default. Which means the default behavior for
+  multiple identify calls is different
+  [more info here](https://launchdarkly.github.io/js-core/packages/sdk/browser/docs/interfaces/LDIdentifyOptions.html#sheddable)
 - Callback support has been removed - use async/await or `.then()` instead
+> See [options section](#ldoptions) for more information about changes to the options.
 
 **Before (v3.x):**
 ```javascript
@@ -154,7 +175,7 @@ if (result.status === 'completed') {
 }
 ```
 
-### Flag change event
+### Flag change event payload
 
 The `change` event now receives the context and an array of changed flag keys as parameters.
 > NOTE: we will no longer return the flag value object along with this event
@@ -192,3 +213,28 @@ client.on('change:my-flag', (context) => {
   const flagValue = client.variation('my-flag', false);
 });
 ```
+
+### Error event handling changes
+
+The new SDK has changed how errors are logged when error event listeners are present.
+
+**Key difference:**
+
+**Before (v3.x):**
+In the old SDK, the `maybeReportError` function would check if there was an error listener:
+- If an error listener was registered: the error event was emitted but **not logged** to the console
+- If no error listener was registered: the error was logged to the console
+
+> This meant that if you wanted to handle errors yourself, you wouldn't get duplicate error logs.
+
+**After (v4.x):**
+In the new SDK, the client always registers a default error listener that logs errors via the logger. This means:
+- Errors are **always logged** via the logger, even if you have your own error listeners
+- Your error listeners will still receive the error events
+- You may see duplicate error logs if you're also logging errors in your error handler
+
+**Why this change?**
+The new error handling process allows for more robust control over what errors are ignored. The specific case
+that we want to avoid is not logging/informing end users when an unhandled error happens.
+
+Our recommendation is to implement `LDLogger` for your client to suppress errors that are handled