@firebase/data-connect 0.5.0 → 0.6.0-20260409172004

package/dist/internal.d.ts

@@ -15,6 +15,47 @@ import { FirebaseError } from '@firebase/util';
 import { LogLevelString } from '@firebase/logger';
 import { Provider } from '@firebase/component';
 
+/**
+ * The base class for all DataConnectTransportInterface implementations. Handles common logic such as
+ * URL construction, auth token management, and emulator usage. Concrete transport implementations
+ * should extend this class and implement the abstract {@link DataConnectTransportInterface} methods.
+ * @internal
+ */
+export declare abstract class AbstractDataConnectTransport implements DataConnectTransportInterface {
+    protected apiKey?: string | undefined;
+    protected appId?: (string | null) | undefined;
+    protected authProvider?: AuthTokenProvider | undefined;
+    protected appCheckProvider?: AppCheckTokenProvider | undefined;
+    protected _isUsingGen: boolean;
+    protected _callerSdkType: CallerSdkType;
+    protected _host: string;
+    protected _port: number | undefined;
+    protected _location: string;
+    protected _connectorName: string;
+    /** The resource path for requests from this Data Connect instance. */
+    protected _connectorResourcePath: string;
+    protected _secure: boolean;
+    protected _project: string;
+    protected _serviceName: string;
+    protected _authToken: string | null;
+    protected _appCheckToken: string | null | undefined;
+    protected _lastToken: string | null;
+    protected _isUsingEmulator: boolean;
+    constructor(options: DataConnectOptions, apiKey?: string | undefined, appId?: (string | null) | undefined, authProvider?: AuthTokenProvider | undefined, appCheckProvider?: AppCheckTokenProvider | undefined, transportOptions?: TransportOptions | undefined, _isUsingGen?: boolean, _callerSdkType?: CallerSdkType);
+    /** Get the endpoint URL this transport should use to communicate with the backend. */
+    abstract get endpointUrl(): string;
+    useEmulator(host: string, port?: number, isSecure?: boolean): void;
+    getWithAuth(forceToken?: boolean): Promise<string | null>;
+    withRetry<T>(promiseFactory: () => Promise<DataConnectResponse<T>>, retry?: boolean): Promise<DataConnectResponse<T>>;
+    _setLastToken(lastToken: string | null): void;
+    abstract invokeQuery<Data, Variables>(queryName: string, body?: Variables): Promise<DataConnectResponseWithMaxAge<Data>>;
+    abstract invokeMutation<Data, Variables>(queryName: string, body?: Variables): Promise<DataConnectResponse<Data>>;
+    abstract invokeSubscribe<Data, Variables>(observer: SubscribeObserver<Data>, queryName: string, body?: Variables): void;
+    abstract invokeUnsubscribe<Variables>(queryName: string, variables: Variables): void;
+    abstract onAuthTokenChanged(newToken: string | null): void;
+    _setCallerSdkType(callerSdkType: CallerSdkType): void;
+}
+
 /**
  * @internal
  * Abstraction around AppCheck's token fetching capabilities.
@@ -181,12 +222,12 @@ export declare type DataConnectExtension = {
 } & (DataConnectEntityArray | DataConnectSingleEntity);
 
 /** @internal */
-declare type DataConnectExtensionWithMaxAge = {
+export declare type DataConnectExtensionWithMaxAge = {
     path: Array<string | number>;
 } & (DataConnectEntityArray | DataConnectSingleEntity | DataConnectMaxAge);
 
 /** @internal */
-declare interface DataConnectMaxAge {
+export declare interface DataConnectMaxAge {
     maxAge: string;
 }
 
@@ -217,14 +258,15 @@ export declare interface DataConnectOptions extends ConnectorConfig {
     projectId: string;
 }
 
-declare interface DataConnectResponse<T> {
+/** @internal */
+export declare interface DataConnectResponse<T> {
     data: T;
     errors: Error[];
     extensions: Extensions;
 }
 
 /** @internal */
-declare interface DataConnectResponseWithMaxAge<T> {
+export declare interface DataConnectResponseWithMaxAge<T> {
     data: T;
     errors: Error[];
     extensions: ExtensionsWithMaxAge;
@@ -252,13 +294,55 @@ export declare interface DataConnectSubscription<Data, Variables> {
 }
 
 /**
+ * Interface defining the external API of the transport layer.
  * @internal
  */
-export declare interface DataConnectTransport {
-    invokeQuery<T, U>(queryName: string, body?: U): Promise<DataConnectResponseWithMaxAge<T>>;
-    invokeMutation<T, U>(queryName: string, body?: U): Promise<DataConnectResponse<T>>;
+export declare interface DataConnectTransportInterface {
+    /**
+     * Invoke a query execution request.
+     * @param queryName The name of the query to execute.
+     * @param body The variables associated with the query.
+     * @returns A promise resolving to the DataConnectResponse.
+     */
+    invokeQuery<Data, Variables>(queryName: string, body?: Variables): Promise<DataConnectResponseWithMaxAge<Data>>;
+    /**
+     * Invoke a mutation execution request.
+     * @param queryName The name of the mutation to execute.
+     * @param body The variables associated with the mutation.
+     * @returns A promise resolving to the DataConnectResponse.
+     */
+    invokeMutation<Data, Variables>(queryName: string, body?: Variables): Promise<DataConnectResponse<Data>>;
+    /**
+     * Subscribes to a query to receive push notifications of updates.
+     * @param observer the observer passed to the transport layer to notify the query layer of events.
+     * @param queryName The name of the query to subscribe to.
+     * @param body The variables associated with the subscription.
+     */
+    invokeSubscribe<Data, Variables>(observer: SubscribeObserver<Data>, queryName: string, body?: Variables): void;
+    /**
+     * Unsubscribes from an active subscription.
+     * @param queryName The name of the query to unsubscribe from.
+     * @param body The variables associated with the subscription.
+     */
+    invokeUnsubscribe<Variables>(queryName: string, body?: Variables): void;
+    /**
+     * Configures the transport to use a local Data Connect emulator.
+     * @param host The host address of the emulator (e.g., '127.0.0.1').
+     * @param port The port number the emulator is listening on.
+     * @param sslEnabled Whether to use SSL (HTTPS/WSS) for the emulator connection.
+     */
     useEmulator(host: string, port?: number, sslEnabled?: boolean): void;
-    onTokenChanged: (token: string | null) => void;
+    /**
+     * Callback invoked when the Firebase Auth token is refreshed or changed. Note that this callback
+     * is called immediately asynchronously when the Auth Provider is initialized to provide
+     * the initial auth state.
+     * @param token The new access token or null if signed out.
+     */
+    onAuthTokenChanged: (token: string | null) => void;
+    /**
+     * Internal method to set the SDK type for metrics and logging purposes.
+     * @param callerSdkType The type of SDK making the call (e.g., generated vs base).
+     */
     _setCallerSdkType(callerSdkType: CallerSdkType): void;
 }
 
@@ -354,7 +438,7 @@ export declare interface Extensions {
 }
 
 /** @internal */
-declare interface ExtensionsWithMaxAge {
+export declare interface ExtensionsWithMaxAge {
     dataConnect?: DataConnectExtensionWithMaxAge[];
 }
 
@@ -398,6 +482,12 @@ export declare function getDataConnect(app: FirebaseApp, connectorConfig: Connec
  */
 export declare function getDataConnect(app: FirebaseApp, connectorConfig: ConnectorConfig, settings: DataConnectSettings): DataConnect;
 
+/**
+ * Constructs the value for the X-Goog-Api-Client header
+ * @internal
+ */
+export declare function getGoogApiClientValue(isUsingGen: boolean, callerSdkType: CallerSdkType): string;
+
 /**
  * @license
  * Copyright 2025 Google LLC
@@ -447,7 +537,7 @@ export declare const MUTATION_STR = "mutation";
 export declare class MutationManager {
     private _transport;
     private _inflight;
-    constructor(_transport: DataConnectTransport);
+    constructor(_transport: DataConnectTransportInterface);
     executeMutation<Data, Variables>(mutationRef: MutationRef<Data, Variables>): MutationPromise<Data, Variables>;
 }
 
@@ -558,8 +648,12 @@ declare class QueryManager {
     private cache?;
     preferCacheResults<Data, Variables>(queryRef: QueryRef<Data, Variables>, allowStale?: boolean): Promise<QueryResult<Data, Variables>>;
     private callbacks;
+    /**
+     * Map of serialized query keys to most recent Query Result. Used as a simple fallback cache
+     * for subsciptions if caching is not enabled.
+     */
     private subscriptionCache;
-    constructor(transport: DataConnectTransport, dc: DataConnect, cache?: DataConnectCache | undefined);
+    constructor(transport: DataConnectTransportInterface, dc: DataConnect, cache?: DataConnectCache | undefined);
     private queue;
     waitForQueuedWrites(): Promise<void>;
     updateSSR<Data, Variables>(updatedData: QueryResult<Data, Variables>): void;
@@ -570,9 +664,25 @@ declare class QueryManager {
     publishErrorToSubscribers(key: string, err: unknown): void;
     getFromResultTreeCache<Data, Variables>(queryRef: QueryRef<Data, Variables>, allowStale?: boolean): Promise<QueryResult<Data, Variables> | null>;
     getFromSubscriberCache<Data, Variables>(queryRef: QueryRef<Data, Variables>): Promise<QueryResult<Data, Variables> | undefined>;
+    /** Call the registered onNext callbacks for the given key */
     publishDataToSubscribers(key: string, queryResult: QueryResult<unknown, unknown>): void;
     publishCacheResultsToSubscribers(impactedQueries: string[], fetchTime: string): Promise<void>;
     enableEmulator(host: string, port: number): void;
+    /**
+     * Create a new {@link SubscribeObserver} for the given QueryRef. This will be passed to
+     * {@link DataConnectTransportInterface.invokeSubscribe | invokeSubscribe()} to notify the query
+     * layer of data update notifications or if the stream disconnected.
+     */
+    private makeSubscribeObserver;
+    /**
+     * Handle a data update notification from the stream. Notify subscribers of results/errors, and
+     * update the cache.
+     */
+    private handleStreamNotification;
+    /**
+     * Handle a disconnect from the stream. Unsubscribe all callbacks for the given key.
+     */
+    private handleStreamDisconnect;
 }
 
 /**
@@ -692,6 +802,16 @@ export declare function subscribe<Data, Variables>(queryRefOrSerializedResult: Q
  */
 export declare function subscribe<Data, Variables>(queryRefOrSerializedResult: QueryRef<Data, Variables> | SerializedRef<Data, Variables>, onNext: OnResultSubscription<Data, Variables>, onError?: OnErrorSubscription, onComplete?: OnCompleteSubscription): QueryUnsubscribe;
 
+/**
+ * Observer defined by the Query Layer for receiving notifications from the Transport Layer.
+ * @internal
+ */
+export declare interface SubscribeObserver<Data> {
+    onData(response: DataConnectResponse<Data>): Promise<void> | void;
+    onDisconnect(code: string, reason: string): void;
+    onError(error: Error): void;
+}
+
 /**
  * Representation of full observer options in `subscribe`
  */
@@ -716,9 +836,10 @@ export declare function terminate(dataConnect: DataConnect): Promise<void>;
 export declare function toQueryRef<Data, Variables>(serializedRef: SerializedRef<Data, Variables>): QueryRef<Data, Variables>;
 
 /**
+ * Type signature of a transport class constructor.
  * @internal
  */
-export declare type TransportClass = new (options: DataConnectOptions, apiKey?: string, appId?: string, authProvider?: AuthTokenProvider, appCheckProvider?: AppCheckTokenProvider, transportOptions?: TransportOptions, _isUsingGen?: boolean, _callerSdkType?: CallerSdkType) => DataConnectTransport;
+export declare type TransportClass = new (options: DataConnectOptions, apiKey?: string, appId?: string, authProvider?: AuthTokenProvider, appCheckProvider?: AppCheckTokenProvider, transportOptions?: TransportOptions, _isUsingGen?: boolean, _callerSdkType?: CallerSdkType) => DataConnectTransportInterface;
 
 /**
  * Options to connect to emulator