@firebase/remote-config 0.6.6 → 0.7.0-canary.cb3bdd812

package/dist/esm/src/api.d.ts

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 import { FirebaseApp } from '@firebase/app';
-import { CustomSignals, LogLevel as RemoteConfigLogLevel, RemoteConfig, Value, RemoteConfigOptions } from './public_types';
+import { CustomSignals, LogLevel as RemoteConfigLogLevel, RemoteConfig, Value, RemoteConfigOptions, ConfigUpdateObserver, Unsubscribe } from './public_types';
 /**
  *
  * @param app - The {@link @firebase/app#FirebaseApp} instance.
@@ -126,3 +126,19 @@ export declare function setLogLevel(remoteConfig: RemoteConfig, logLevel: Remote
  * @public
  */
 export declare function setCustomSignals(remoteConfig: RemoteConfig, customSignals: CustomSignals): Promise<void>;
+/**
+ * Starts listening for real-time config updates from the Remote Config backend and automatically
+ * fetches updates from the Remote Config backend when they are available.
+ *
+ * @remarks
+ * If a connection to the Remote Config backend is not already open, calling this method will
+ * open it. Multiple listeners can be added by calling this method again, but subsequent calls
+ * re-use the same connection to the backend.
+ *
+ * @param remoteConfig - The {@link RemoteConfig} instance.
+ * @param observer - The {@link ConfigUpdateObserver} to be notified of config updates.
+ * @returns An {@link Unsubscribe} function to remove the listener.
+ *
+ * @public
+ */
+export declare function onConfigUpdate(remoteConfig: RemoteConfig, observer: ConfigUpdateObserver): Unsubscribe;

package/dist/esm/src/client/eventEmitter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Base class to be used if you want to emit events. Call the constructor with
+ * the set of allowed event names.
+ */
+export declare abstract class EventEmitter {
+    private allowedEvents_;
+    private listeners_;
+    constructor(allowedEvents_: string[]);
+    /**
+     * To be overridden by derived classes in order to fire an initial event when
+     * somebody subscribes for data.
+     *
+     * @returns {Array.<*>} Array of parameters to trigger initial event with.
+     */
+    abstract getInitialEvent(eventType: string): unknown[];
+    /**
+     * To be called by derived classes to trigger events.
+     */
+    protected trigger(eventType: string, ...varArgs: unknown[]): void;
+    on(eventType: string, callback: (a: unknown) => void, context: unknown): void;
+    off(eventType: string, callback: (a: unknown) => void, context: unknown): void;
+    private validateEventType_;
+}

package/dist/esm/src/client/realtime_handler.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { _FirebaseInstallationsInternal } from '@firebase/installations';
+import { Logger } from '@firebase/logger';
+import { ConfigUpdateObserver } from '../public_types';
+import { Storage } from '../storage/storage';
+import { StorageCache } from '../storage/storage_cache';
+import { CachingClient } from './caching_client';
+export declare class RealtimeHandler {
+    private readonly firebaseInstallations;
+    private readonly storage;
+    private readonly sdkVersion;
+    private readonly namespace;
+    private readonly projectId;
+    private readonly apiKey;
+    private readonly appId;
+    private readonly logger;
+    private readonly storageCache;
+    private readonly cachingClient;
+    constructor(firebaseInstallations: _FirebaseInstallationsInternal, storage: Storage, sdkVersion: string, namespace: string, projectId: string, apiKey: string, appId: string, logger: Logger, storageCache: StorageCache, cachingClient: CachingClient);
+    private observers;
+    private isConnectionActive;
+    private isRealtimeDisabled;
+    private controller?;
+    private reader;
+    private httpRetriesRemaining;
+    private isInBackground;
+    private readonly decoder;
+    private isClosingConnection;
+    private setRetriesRemaining;
+    private propagateError;
+    /**
+     * Increment the number of failed stream attempts, increase the backoff duration, set the backoff
+     * end time to "backoff duration" after `lastFailedStreamTime` and persist the new
+     * values to storage metadata.
+     */
+    private updateBackoffMetadataWithLastFailedStreamConnectionTime;
+    /**
+     * Increase the backoff duration with a new end time based on Retry Interval.
+     */
+    private updateBackoffMetadataWithRetryInterval;
+    /**
+     * HTTP status code that the Realtime client should retry on.
+     */
+    private isStatusCodeRetryable;
+    /**
+     * Closes the realtime HTTP connection.
+     * Note: This method is designed to be called only once at a time.
+     * If a call is already in progress, subsequent calls will be ignored.
+     */
+    private closeRealtimeHttpConnection;
+    private resetRealtimeBackoff;
+    private resetRetryCount;
+    /**
+     * Assembles the request headers and body and executes the fetch request to
+     * establish the real-time streaming connection. This is the "worker" method
+     * that performs the actual network communication.
+     */
+    private establishRealtimeConnection;
+    private getRealtimeUrl;
+    private createRealtimeConnection;
+    /**
+     * Retries HTTP stream connection asyncly in random time intervals.
+     */
+    private retryHttpConnectionWhenBackoffEnds;
+    private setIsHttpConnectionRunning;
+    /**
+     * Combines the check and set operations to prevent multiple asynchronous
+     * calls from redundantly starting an HTTP connection. This ensures that
+     * only one attempt is made at a time.
+     */
+    private checkAndSetHttpConnectionFlagIfNotRunning;
+    private fetchResponseIsUpToDate;
+    private parseAndValidateConfigUpdateMessage;
+    private isEventListenersEmpty;
+    private getRandomInt;
+    private executeAllListenerCallbacks;
+    /**
+     * Compares two configuration objects and returns a set of keys that have changed.
+     * A key is considered changed if it's new, removed, or has a different value.
+     */
+    private getChangedParams;
+    private fetchLatestConfig;
+    private autoFetch;
+    /**
+     * Processes a stream of real-time messages for configuration updates.
+     * This method reassembles fragmented messages, validates and parses the JSON,
+     * and automatically fetches a new config if a newer template version is available.
+     * It also handles server-specified retry intervals and propagates errors for
+     * invalid messages or when real-time updates are disabled.
+     */
+    private handleNotifications;
+    private listenForNotifications;
+    /**
+     * Open the real-time connection, begin listening for updates, and auto-fetch when an update is
+     * received.
+     *
+     * If the connection is successful, this method will block on its thread while it reads the
+     * chunk-encoded HTTP body. When the connection closes, it attempts to reestablish the stream.
+     */
+    private prepareAndBeginRealtimeHttpStream;
+    /**
+     * Checks whether connection can be made or not based on some conditions
+     * @returns booelean
+     */
+    private canEstablishStreamConnection;
+    private makeRealtimeHttpConnection;
+    private beginRealtime;
+    /**
+     * Adds an observer to the realtime updates.
+     * @param observer The observer to add.
+     */
+    addObserver(observer: ConfigUpdateObserver): void;
+    /**
+     * Removes an observer from the realtime updates.
+     * @param observer The observer to remove.
+     */
+    removeObserver(observer: ConfigUpdateObserver): void;
+    /**
+     * Handles changes to the application's visibility state, managing the real-time connection.
+     *
+     * When the application is moved to the background, this method closes the existing
+     * real-time connection to save resources. When the application returns to the
+     * foreground, it attempts to re-establish the connection.
+     */
+    private onVisibilityChange;
+}

package/dist/esm/src/client/remote_config_fetch_client.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { CustomSignals, FetchResponse } from '../public_types';
+import { CustomSignals, FetchResponse, FetchType } from '../public_types';
 /**
  * Defines a client, as in https://en.wikipedia.org/wiki/Client%E2%80%93server_model, for the
  * Remote Config server (https://firebase.google.com/docs/reference/remote-config/rest).
@@ -89,4 +89,16 @@ export interface FetchRequest {
      * <p>Optional in case no custom signals are set for the instance.
      */
     customSignals?: CustomSignals;
+    /**
+     * The type of fetch to perform, such as a regular fetch or a real-time fetch.
+     *
+     * Optional as not all fetch requests need to be distinguished.
+     */
+    fetchType?: FetchType;
+    /**
+     * The number of fetch attempts made so far for this request.
+     *
+     * Optional as not all fetch requests are part of a retry series.
+     */
+    fetchAttempt?: number;
 }

package/dist/esm/src/client/visibility_monitor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { EventEmitter } from './eventEmitter';
+export declare class VisibilityMonitor extends EventEmitter {
+    private visible_;
+    static getInstance(): VisibilityMonitor;
+    constructor();
+    getInitialEvent(eventType: string): boolean[];
+}

package/dist/esm/src/errors.d.ts

@@ -31,7 +31,11 @@ export declare const enum ErrorCode {
     FETCH_PARSE = "fetch-client-parse",
     FETCH_STATUS = "fetch-status",
     INDEXED_DB_UNAVAILABLE = "indexed-db-unavailable",
-    CUSTOM_SIGNAL_MAX_ALLOWED_SIGNALS = "custom-signal-max-allowed-signals"
+    CUSTOM_SIGNAL_MAX_ALLOWED_SIGNALS = "custom-signal-max-allowed-signals",
+    CONFIG_UPDATE_STREAM_ERROR = "stream-error",
+    CONFIG_UPDATE_UNAVAILABLE = "realtime-unavailable",
+    CONFIG_UPDATE_MESSAGE_INVALID = "update-message-invalid",
+    CONFIG_UPDATE_NOT_FETCHED = "update-not-fetched"
 }
 interface ErrorParams {
     [ErrorCode.STORAGE_OPEN]: {
@@ -61,6 +65,18 @@ interface ErrorParams {
     [ErrorCode.CUSTOM_SIGNAL_MAX_ALLOWED_SIGNALS]: {
         maxSignals: number;
     };
+    [ErrorCode.CONFIG_UPDATE_STREAM_ERROR]: {
+        originalErrorMessage: string;
+    };
+    [ErrorCode.CONFIG_UPDATE_UNAVAILABLE]: {
+        originalErrorMessage: string;
+    };
+    [ErrorCode.CONFIG_UPDATE_MESSAGE_INVALID]: {
+        originalErrorMessage: string;
+    };
+    [ErrorCode.CONFIG_UPDATE_NOT_FETCHED]: {
+        originalErrorMessage: string;
+    };
 }
 export declare const ERROR_FACTORY: ErrorFactory<ErrorCode, ErrorParams>;
 export declare function hasErrorCode(e: Error, errorCode: ErrorCode): boolean;

package/dist/esm/src/public_types.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { FirebaseApp } from '@firebase/app';
+import { FirebaseApp, FirebaseError } from '@firebase/app';
 /**
  * The Firebase Remote Config service interface.
  *
@@ -48,6 +48,8 @@ export interface RemoteConfig {
 }
 /**
  * Defines a self-descriptive reference for config key-value pairs.
+ *
+ *  @public
  */
 export interface FirebaseRemoteConfigObject {
     [key: string]: string;
@@ -57,6 +59,8 @@ export interface FirebaseRemoteConfigObject {
  *
  * <p>Modeled after the native `Response` interface, but simplified for Remote Config's
  * use case.
+ *
+ * @public
  */
 export interface FetchResponse {
     /**
@@ -82,6 +86,10 @@ export interface FetchResponse {
      * <p>Only defined for 200 responses.
      */
     config?: FirebaseRemoteConfigObject;
+    /**
+     * The version number of the config template fetched from the server.
+     */
+    templateVersion?: number;
 }
 /**
  * Options for Remote Config initialization.
@@ -189,6 +197,57 @@ export type LogLevel = 'debug' | 'error' | 'silent';
 export interface CustomSignals {
     [key: string]: string | number | null;
 }
+/**
+ * Contains information about which keys have been updated.
+ *
+ * @public
+ */
+export interface ConfigUpdate {
+    /**
+     * Parameter keys whose values have been updated from the currently activated values.
+     * Includes keys that are added, deleted, or whose value, value source, or metadata has changed.
+     */
+    getUpdatedKeys(): Set<string>;
+}
+/**
+ * Observer interface for receiving real-time Remote Config update notifications.
+ *
+ * NOTE: Although an `complete` callback can be provided, it will
+ * never be called because the ConfigUpdate stream is never-ending.
+ *
+ * @public
+ */
+export interface ConfigUpdateObserver {
+    /**
+     * Called when a new ConfigUpdate is available.
+     */
+    next: (configUpdate: ConfigUpdate) => void;
+    /**
+     * Called if an error occurs during the stream.
+     */
+    error: (error: FirebaseError) => void;
+    /**
+     * Called when the stream is gracefully terminated.
+     */
+    complete: () => void;
+}
+/**
+ * A function that unsubscribes from a real-time event stream.
+ *
+ * @public
+ */
+export type Unsubscribe = () => void;
+/**
+ * Indicates the type of fetch request.
+ *
+ * <ul>
+ *   <li>"BASE" indicates a standard fetch request.</li>
+ *   <li>"REALTIME" indicates a fetch request triggered by a real-time update.</li>
+ * </ul>
+ *
+ * @public
+ */
+export type FetchType = 'BASE' | 'REALTIME';
 declare module '@firebase/component' {
     interface NameServiceMapping {
         'remote-config': RemoteConfig;

package/dist/esm/src/remote_config.d.ts

@@ -20,6 +20,7 @@ import { StorageCache } from './storage/storage_cache';
 import { RemoteConfigFetchClient } from './client/remote_config_fetch_client';
 import { Storage } from './storage/storage';
 import { Logger } from '@firebase/logger';
+import { RealtimeHandler } from './client/realtime_handler';
 /**
  * Encapsulates business logic mapping network and storage dependencies to the public SDK API.
  *
@@ -43,6 +44,10 @@ export declare class RemoteConfig implements RemoteConfigType {
      * @internal
      */
     readonly _logger: Logger;
+    /**
+     * @internal
+     */
+    readonly _realtimeHandler: RealtimeHandler;
     /**
      * Tracks completion of initialization promise.
      * @internal
@@ -75,5 +80,9 @@ export declare class RemoteConfig implements RemoteConfigType {
     /**
      * @internal
      */
-    _logger: Logger);
+    _logger: Logger, 
+    /**
+     * @internal
+     */
+    _realtimeHandler: RealtimeHandler);
 }

package/dist/esm/src/storage/storage.d.ts

@@ -34,12 +34,16 @@ export interface ThrottleMetadata {
     backoffCount: number;
     throttleEndTimeMillis: number;
 }
+export interface RealtimeBackoffMetadata {
+    numFailedStreams: number;
+    backoffEndTimeMillis: Date;
+}
 /**
  * Provides type-safety for the "key" field used by {@link APP_NAMESPACE_STORE}.
  *
  * <p>This seems like a small price to avoid potentially subtle bugs caused by a typo.
  */
-type ProjectNamespaceKeyFieldValue = 'active_config' | 'active_config_etag' | 'last_fetch_status' | 'last_successful_fetch_timestamp_millis' | 'last_successful_fetch_response' | 'settings' | 'throttle_metadata' | 'custom_signals';
+type ProjectNamespaceKeyFieldValue = 'active_config' | 'active_config_etag' | 'last_fetch_status' | 'last_successful_fetch_timestamp_millis' | 'last_successful_fetch_response' | 'settings' | 'throttle_metadata' | 'custom_signals' | 'realtime_backoff_metadata' | 'last_known_template_version';
 export declare function openDatabase(): Promise<IDBDatabase>;
 /**
  * Abstracts data persistence.
@@ -63,6 +67,10 @@ export declare abstract class Storage {
     abstract get<T>(key: ProjectNamespaceKeyFieldValue): Promise<T | undefined>;
     abstract set<T>(key: ProjectNamespaceKeyFieldValue, value: T): Promise<void>;
     abstract delete(key: ProjectNamespaceKeyFieldValue): Promise<void>;
+    getRealtimeBackoffMetadata(): Promise<RealtimeBackoffMetadata | undefined>;
+    setRealtimeBackoffMetadata(realtimeMetadata: RealtimeBackoffMetadata): Promise<void>;
+    getActiveConfigTemplateVersion(): Promise<number | undefined>;
+    setActiveConfigTemplateVersion(version: number): Promise<void>;
 }
 export declare class IndexedDbStorage extends Storage {
     private readonly appId;