@launchdarkly/js-client-sdk 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.3.2](https://github.com/launchdarkly/js-core/compare/js-client-sdk-v0.3.1...js-client-sdk-v0.3.2) (2024-11-13)
+
+
+### Bug Fixes
+
+* Export correct options for compat. ([#678](https://github.com/launchdarkly/js-core/issues/678)) ([8d8250c](https://github.com/launchdarkly/js-core/commit/8d8250cafb20b60e45ac3661fd8b079cb62fb83e))
+
+## [0.3.1](https://github.com/launchdarkly/js-core/compare/js-client-sdk-v0.3.0...js-client-sdk-v0.3.1) (2024-11-08)
+
+
+### Bug Fixes
+
+* Consolidate common exports between base package and compat package. ([#674](https://github.com/launchdarkly/js-core/issues/674)) ([f692050](https://github.com/launchdarkly/js-core/commit/f69205082d83318e2772d027d6ea533de3ce5eb1))
+
 ## [0.3.0](https://github.com/launchdarkly/js-core/compare/js-client-sdk-v0.2.0...js-client-sdk-v0.3.0) (2024-11-04)
 
 

package/README.md

@@ -1,12 +1,12 @@
 # LaunchDarkly JavaScript SDK for Browsers
 
-<!--
+
 [![NPM][browser-sdk-npm-badge]][browser-sdk-npm-link]
 [![Actions Status][browser-sdk-ci-badge]][browser-sdk-ci]
 [![Documentation][browser-sdk-ghp-badge]][browser-sdk-ghp-link]
 [![NPM][browser-sdk-dm-badge]][browser-sdk-npm-link]
 [![NPM][browser-sdk-dt-badge]][browser-sdk-npm-link]
--->
+
 
 # ⛔️⛔️⛔️⛔️
 

package/dist/common-DPjctgS7.d.cts

@@ -0,0 +1,174 @@
+import { LDIdentifyOptions, LDOptions, LDClient as LDClient$1, LDContext, BasicLoggerOptions, LDLogger } from '@launchdarkly/js-client-sdk-common';
+
+interface BrowserIdentifyOptions extends Omit<LDIdentifyOptions, 'waitForNetworkResults'> {
+    /**
+     * The signed context key if you are using [Secure Mode]
+     * (https://docs.launchdarkly.com/sdk/features/secure-mode#configuring-secure-mode-in-the-javascript-client-side-sdk).
+     */
+    hash?: string;
+    /**
+     * The initial set of flags to use until the remote set is retrieved.
+     *
+     * Bootstrap data can be generated by server SDKs. When bootstrap data is provided the SDK the
+     * identification operation will complete without waiting for any values from LaunchDarkly and
+     * the variation calls can be used immediately.
+     *
+     * If streaming is activated, either it is configured to always be used, or is activated
+     * via setStreaming, or via the addition of change handlers, then a streaming connection will
+     * subsequently be established.
+     *
+     * For more information, see the [SDK Reference Guide](https://docs.launchdarkly.com/sdk/features/bootstrapping#javascript).
+     */
+    bootstrap?: unknown;
+}
+
+/**
+ * Initialization options for the LaunchDarkly browser SDK.
+ */
+interface BrowserOptions extends Omit<LDOptions, 'initialConnectionMode'> {
+    /**
+     * Whether the client should make a request to LaunchDarkly for Experimentation metrics (goals).
+     *
+     * This is true by default, meaning that this request will be made on every page load.
+     * Set it to false if you are not using Experimentation and want to skip the request.
+     */
+    fetchGoals?: boolean;
+    /**
+     * A function which, if present, can change the URL in analytics events to something other
+     * than the actual browser URL. It will be called with the current browser URL as a parameter,
+     * and returns the value that should be stored in the event's `url` property.
+     *
+     * It may be useful to customize the `url` to provide specific meaning, incorporate
+     * client-side routing concerns, or redact tokens or other info.
+     */
+    eventUrlTransformer?: (url: string) => string;
+    /**
+     * Whether or not to open a streaming connection to LaunchDarkly for live flag updates.
+     *
+     * If this is true, the client will always attempt to maintain a streaming connection; if false,
+     * it never will. If you leave the value undefined (the default), the client will open a streaming
+     * connection if you subscribe to `"change"` or `"change:flag-key"` events.
+     *
+     * This is equivalent to calling `client.setStreaming()` with the same value.
+     */
+    streaming?: boolean;
+    /**
+     * Determines if the SDK responds to entering different visibility states, such as foreground and background.
+     * An example is flushing buffered events when going to the background.
+     *
+     * This is true by default. Generally speaking the SDK will be able to most reliably deliver
+     * events with this setting on.
+     *
+     * It may be useful to disable for environments where not all window/document objects are
+     * available, such as when running the SDK in a browser extension.
+     */
+    automaticBackgroundHandling?: boolean;
+}
+
+/**
+ *
+ * The LaunchDarkly SDK client object.
+ *
+ * Applications should configure the client at page load time and reuse the same instance.
+ *
+ * For more information, see the [SDK Reference Guide](https://docs.launchdarkly.com/sdk/client-side/javascript).
+ */
+type LDClient = Omit<LDClient$1, 'setConnectionMode' | 'getConnectionMode' | 'getOffline' | 'identify'> & {
+    /**
+     * @ignore
+     * Implementation Note: We are not supporting dynamically setting the connection mode on the LDClient.
+     * Implementation Note: The SDK does not support offline mode. Instead bootstrap data can be used.
+     * Implementation Note: The browser SDK has different identify options, so omits the base implementation
+     * from the interface.
+     */
+    /**
+     * Specifies whether or not to open a streaming connection to LaunchDarkly for live flag updates.
+     *
+     * If this is true, the client will always attempt to maintain a streaming connection; if false,
+     * it never will. If you leave the value undefined (the default), the client will open a streaming
+     * connection if you subscribe to `"change"` or `"change:flag-key"` events (see {@link LDClient.on}).
+     *
+     * This can also be set as the `streaming` property of {@link LDOptions}.
+     */
+    setStreaming(streaming?: boolean): void;
+    /**
+     * Identifies a context to LaunchDarkly.
+     *
+     * Unlike the server-side SDKs, the client-side JavaScript SDKs maintain a current context state,
+     * which is set when you call `identify()`.
+     *
+     * Changing the current context also causes all feature flag values to be reloaded. Until that has
+     * finished, calls to {@link variation} will still return flag values for the previous context. You can
+     * await the Promise to determine when the new flag values are available.
+     *
+     * @param context
+     *    The LDContext object.
+     * @param identifyOptions
+     *    Optional configuration. Please see {@link LDIdentifyOptions}.
+     * @returns
+     *    A Promise which resolves when the flag values for the specified
+     * context are available. It rejects when:
+     *
+     * 1. The context is unspecified or has no key.
+     *
+     * 2. The identify timeout is exceeded. In client SDKs this defaults to 5s.
+     * You can customize this timeout with {@link LDIdentifyOptions | identifyOptions}.
+     *
+     * 3. A network error is encountered during initialization.
+     *
+     * @ignore Implementation Note: Browser implementation has different options.
+     */
+    identify(context: LDContext, identifyOptions?: BrowserIdentifyOptions): Promise<void>;
+};
+
+/**
+ * Provides a basic {@link LDLogger} implementation.
+ *
+ * This logging implementation uses a basic format that includes only the log level
+ * and the message text. By default this uses log level 'info' and the output is
+ * written to `console.error`.
+ *
+ * To use the logger created by this function, put it into {@link LDOptions.logger}. If
+ * you do not set {@link LDOptions.logger} to anything, the SDK uses a default logger
+ * that will log "info" level and higher priorty messages and it will log messages to
+ * console.info, console.warn, and console.error.
+ *
+ * @param options Configuration for the logger. If no options are specified, the
+ *   logger uses `{ level: 'info' }`.
+ *
+ * @example
+ * This example shows how to use `basicLogger` in your SDK options to enable console
+ * logging only at `warn` and `error` levels.
+ * ```javascript
+ *   const ldOptions = {
+ *     logger: basicLogger({ level: 'warn' }),
+ *   };
+ * ```
+ *
+ * @example
+ * This example shows how to use `basicLogger` in your SDK options to cause all
+ * log output to go to `console.log`
+ * ```javascript
+ *   const ldOptions = {
+ *     logger: basicLogger({ destination: console.log }),
+ *   };
+ * ```
+ *
+ *  * @example
+ * The configuration also allows you to control the destination for each log level.
+ * ```javascript
+ *   const ldOptions = {
+ *     logger: basicLogger({
+ *       destination: {
+ *         debug: console.debug,
+ *         info: console.info,
+ *         warn: console.warn,
+ *         error:console.error
+ *       }
+ *     }),
+ *   };
+ * ```
+ */
+declare function basicLogger(options: BasicLoggerOptions): LDLogger;
+
+export { type BrowserOptions as B, type LDClient as L, type BrowserIdentifyOptions as a, basicLogger as b };

package/dist/common-DPjctgS7.d.ts

@@ -0,0 +1,174 @@
+import { LDIdentifyOptions, LDOptions, LDClient as LDClient$1, LDContext, BasicLoggerOptions, LDLogger } from '@launchdarkly/js-client-sdk-common';
+
+interface BrowserIdentifyOptions extends Omit<LDIdentifyOptions, 'waitForNetworkResults'> {
+    /**
+     * The signed context key if you are using [Secure Mode]
+     * (https://docs.launchdarkly.com/sdk/features/secure-mode#configuring-secure-mode-in-the-javascript-client-side-sdk).
+     */
+    hash?: string;
+    /**
+     * The initial set of flags to use until the remote set is retrieved.
+     *
+     * Bootstrap data can be generated by server SDKs. When bootstrap data is provided the SDK the
+     * identification operation will complete without waiting for any values from LaunchDarkly and
+     * the variation calls can be used immediately.
+     *
+     * If streaming is activated, either it is configured to always be used, or is activated
+     * via setStreaming, or via the addition of change handlers, then a streaming connection will
+     * subsequently be established.
+     *
+     * For more information, see the [SDK Reference Guide](https://docs.launchdarkly.com/sdk/features/bootstrapping#javascript).
+     */
+    bootstrap?: unknown;
+}
+
+/**
+ * Initialization options for the LaunchDarkly browser SDK.
+ */
+interface BrowserOptions extends Omit<LDOptions, 'initialConnectionMode'> {
+    /**
+     * Whether the client should make a request to LaunchDarkly for Experimentation metrics (goals).
+     *
+     * This is true by default, meaning that this request will be made on every page load.
+     * Set it to false if you are not using Experimentation and want to skip the request.
+     */
+    fetchGoals?: boolean;
+    /**
+     * A function which, if present, can change the URL in analytics events to something other
+     * than the actual browser URL. It will be called with the current browser URL as a parameter,
+     * and returns the value that should be stored in the event's `url` property.
+     *
+     * It may be useful to customize the `url` to provide specific meaning, incorporate
+     * client-side routing concerns, or redact tokens or other info.
+     */
+    eventUrlTransformer?: (url: string) => string;
+    /**
+     * Whether or not to open a streaming connection to LaunchDarkly for live flag updates.
+     *
+     * If this is true, the client will always attempt to maintain a streaming connection; if false,
+     * it never will. If you leave the value undefined (the default), the client will open a streaming
+     * connection if you subscribe to `"change"` or `"change:flag-key"` events.
+     *
+     * This is equivalent to calling `client.setStreaming()` with the same value.
+     */
+    streaming?: boolean;
+    /**
+     * Determines if the SDK responds to entering different visibility states, such as foreground and background.
+     * An example is flushing buffered events when going to the background.
+     *
+     * This is true by default. Generally speaking the SDK will be able to most reliably deliver
+     * events with this setting on.
+     *
+     * It may be useful to disable for environments where not all window/document objects are
+     * available, such as when running the SDK in a browser extension.
+     */
+    automaticBackgroundHandling?: boolean;
+}
+
+/**
+ *
+ * The LaunchDarkly SDK client object.
+ *
+ * Applications should configure the client at page load time and reuse the same instance.
+ *
+ * For more information, see the [SDK Reference Guide](https://docs.launchdarkly.com/sdk/client-side/javascript).
+ */
+type LDClient = Omit<LDClient$1, 'setConnectionMode' | 'getConnectionMode' | 'getOffline' | 'identify'> & {
+    /**
+     * @ignore
+     * Implementation Note: We are not supporting dynamically setting the connection mode on the LDClient.
+     * Implementation Note: The SDK does not support offline mode. Instead bootstrap data can be used.
+     * Implementation Note: The browser SDK has different identify options, so omits the base implementation
+     * from the interface.
+     */
+    /**
+     * Specifies whether or not to open a streaming connection to LaunchDarkly for live flag updates.
+     *
+     * If this is true, the client will always attempt to maintain a streaming connection; if false,
+     * it never will. If you leave the value undefined (the default), the client will open a streaming
+     * connection if you subscribe to `"change"` or `"change:flag-key"` events (see {@link LDClient.on}).
+     *
+     * This can also be set as the `streaming` property of {@link LDOptions}.
+     */
+    setStreaming(streaming?: boolean): void;
+    /**
+     * Identifies a context to LaunchDarkly.
+     *
+     * Unlike the server-side SDKs, the client-side JavaScript SDKs maintain a current context state,
+     * which is set when you call `identify()`.
+     *
+     * Changing the current context also causes all feature flag values to be reloaded. Until that has
+     * finished, calls to {@link variation} will still return flag values for the previous context. You can
+     * await the Promise to determine when the new flag values are available.
+     *
+     * @param context
+     *    The LDContext object.
+     * @param identifyOptions
+     *    Optional configuration. Please see {@link LDIdentifyOptions}.
+     * @returns
+     *    A Promise which resolves when the flag values for the specified
+     * context are available. It rejects when:
+     *
+     * 1. The context is unspecified or has no key.
+     *
+     * 2. The identify timeout is exceeded. In client SDKs this defaults to 5s.
+     * You can customize this timeout with {@link LDIdentifyOptions | identifyOptions}.
+     *
+     * 3. A network error is encountered during initialization.
+     *
+     * @ignore Implementation Note: Browser implementation has different options.
+     */
+    identify(context: LDContext, identifyOptions?: BrowserIdentifyOptions): Promise<void>;
+};
+
+/**
+ * Provides a basic {@link LDLogger} implementation.
+ *
+ * This logging implementation uses a basic format that includes only the log level
+ * and the message text. By default this uses log level 'info' and the output is
+ * written to `console.error`.
+ *
+ * To use the logger created by this function, put it into {@link LDOptions.logger}. If
+ * you do not set {@link LDOptions.logger} to anything, the SDK uses a default logger
+ * that will log "info" level and higher priorty messages and it will log messages to
+ * console.info, console.warn, and console.error.
+ *
+ * @param options Configuration for the logger. If no options are specified, the
+ *   logger uses `{ level: 'info' }`.
+ *
+ * @example
+ * This example shows how to use `basicLogger` in your SDK options to enable console
+ * logging only at `warn` and `error` levels.
+ * ```javascript
+ *   const ldOptions = {
+ *     logger: basicLogger({ level: 'warn' }),
+ *   };
+ * ```
+ *
+ * @example
+ * This example shows how to use `basicLogger` in your SDK options to cause all
+ * log output to go to `console.log`
+ * ```javascript
+ *   const ldOptions = {
+ *     logger: basicLogger({ destination: console.log }),
+ *   };
+ * ```
+ *
+ *  * @example
+ * The configuration also allows you to control the destination for each log level.
+ * ```javascript
+ *   const ldOptions = {
+ *     logger: basicLogger({
+ *       destination: {
+ *         debug: console.debug,
+ *         info: console.info,
+ *         warn: console.warn,
+ *         error:console.error
+ *       }
+ *     }),
+ *   };
+ * ```
+ */
+declare function basicLogger(options: BasicLoggerOptions): LDLogger;
+
+export { type BrowserOptions as B, type LDClient as L, type BrowserIdentifyOptions as a, basicLogger as b };