@firebase/functions 0.11.10 → 0.12.0-20241210191049

package/dist/esm/src/public-types.d.ts

@@ -26,11 +26,22 @@ export interface HttpsCallableResult<ResponseData = unknown> {
     readonly data: ResponseData;
 }
 /**
- * A reference to a "callable" HTTP trigger in Google Cloud Functions.
+ * An `HttpsCallableStreamResult` wraps a single streaming result from a function call.
+ * @public
+ */
+export interface HttpsCallableStreamResult<ResponseData = unknown, StreamData = unknown> {
+    readonly data: Promise<ResponseData>;
+    readonly stream: AsyncIterable<StreamData>;
+}
+/**
+ * A reference to a "callable" HTTP trigger in Cloud Functions.
  * @param data - Data to be passed to callable function.
  * @public
  */
-export type HttpsCallable<RequestData = unknown, ResponseData = unknown> = (data?: RequestData | null) => Promise<HttpsCallableResult<ResponseData>>;
+export interface HttpsCallable<RequestData = unknown, ResponseData = unknown, StreamData = unknown> {
+    (data?: RequestData | null): Promise<HttpsCallableResult<ResponseData>>;
+    stream: (data?: RequestData | null, options?: HttpsCallableStreamOptions) => Promise<HttpsCallableStreamResult<ResponseData, StreamData>>;
+}
 /**
  * An interface for metadata about how calls should be executed.
  * @public
@@ -42,7 +53,24 @@ export interface HttpsCallableOptions {
      */
     timeout?: number;
     /**
-     * If set to true, uses limited-use App Check token for callable function requests from this
+     * If set to true, uses a limited-use App Check token for callable function requests from this
+     * instance of {@link Functions}. You must use limited-use tokens to call functions with
+     * replay protection enabled. By default, this is false.
+     */
+    limitedUseAppCheckTokens?: boolean;
+}
+/**
+ * An interface for metadata about how a stream call should be executed.
+ * @public
+ */
+export interface HttpsCallableStreamOptions {
+    /**
+     * An `AbortSignal` that can be used to cancel the streaming response. When the signal is aborted,
+     * the underlying HTTP connection will be terminated.
+     */
+    signal?: AbortSignal;
+    /**
+     * If set to true, uses a limited-use App Check token for callable function requests from this
      * instance of {@link Functions}. You must use limited-use tokens to call functions with
      * replay protection enabled. By default, this is false.
      */

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

@@ -42,6 +42,7 @@ export interface HttpResponseBody {
  */
 export declare class FunctionsService implements _FirebaseService {
     readonly app: FirebaseApp;
+    readonly fetchImpl: typeof fetch;
     readonly contextProvider: ContextProvider;
     emulatorOrigin: string | null;
     cancelAllRequests: Promise<void>;
@@ -52,7 +53,7 @@ export declare class FunctionsService implements _FirebaseService {
      * Creates a new Functions service for the given app.
      * @param app - The FirebaseApp to use.
      */
-    constructor(app: FirebaseApp, authProvider: Provider<FirebaseAuthInternalName>, messagingProvider: Provider<MessagingInternalComponentName>, appCheckProvider: Provider<AppCheckInternalComponentName>, regionOrCustomDomain?: string);
+    constructor(app: FirebaseApp, authProvider: Provider<FirebaseAuthInternalName>, messagingProvider: Provider<MessagingInternalComponentName>, appCheckProvider: Provider<AppCheckInternalComponentName>, regionOrCustomDomain?: string, fetchImpl?: typeof fetch);
     _delete(): Promise<void>;
     /**
      * Returns the URL for a callable with the given name.
@@ -76,10 +77,10 @@ export declare function connectFunctionsEmulator(functionsInstance: FunctionsSer
  * @param name - The name of the trigger.
  * @public
  */
-export declare function httpsCallable<RequestData, ResponseData>(functionsInstance: FunctionsService, name: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData>;
+export declare function httpsCallable<RequestData, ResponseData, StreamData = unknown>(functionsInstance: FunctionsService, name: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData, StreamData>;
 /**
  * Returns a reference to the callable https trigger with the given url.
  * @param url - The url of the trigger.
  * @public
  */
-export declare function httpsCallableFromURL<RequestData, ResponseData>(functionsInstance: FunctionsService, url: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData>;
+export declare function httpsCallableFromURL<RequestData, ResponseData, StreamData = unknown>(functionsInstance: FunctionsService, url: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData, StreamData>;

package/dist/functions-public.d.ts

@@ -126,25 +126,28 @@ export declare type FunctionsErrorCodeCore = 'ok' | 'cancelled' | 'unknown' | 'i
 export declare function getFunctions(app?: FirebaseApp, regionOrCustomDomain?: string): Functions;
 
 /**
- * A reference to a "callable" HTTP trigger in Google Cloud Functions.
+ * A reference to a "callable" HTTP trigger in Cloud Functions.
  * @param data - Data to be passed to callable function.
  * @public
  */
-export declare type HttpsCallable<RequestData = unknown, ResponseData = unknown> = (data?: RequestData | null) => Promise<HttpsCallableResult<ResponseData>>;
+export declare interface HttpsCallable<RequestData = unknown, ResponseData = unknown, StreamData = unknown> {
+    (data?: RequestData | null): Promise<HttpsCallableResult<ResponseData>>;
+    stream: (data?: RequestData | null, options?: HttpsCallableStreamOptions) => Promise<HttpsCallableStreamResult<ResponseData, StreamData>>;
+}
 
 /**
  * Returns a reference to the callable HTTPS trigger with the given name.
  * @param name - The name of the trigger.
  * @public
  */
-export declare function httpsCallable<RequestData = unknown, ResponseData = unknown>(functionsInstance: Functions, name: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData>;
+export declare function httpsCallable<RequestData = unknown, ResponseData = unknown, StreamData = unknown>(functionsInstance: Functions, name: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData, StreamData>;
 
 /**
  * Returns a reference to the callable HTTPS trigger with the specified url.
  * @param url - The url of the trigger.
  * @public
  */
-export declare function httpsCallableFromURL<RequestData = unknown, ResponseData = unknown>(functionsInstance: Functions, url: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData>;
+export declare function httpsCallableFromURL<RequestData = unknown, ResponseData = unknown, StreamData = unknown>(functionsInstance: Functions, url: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData, StreamData>;
 
 /**
  * An interface for metadata about how calls should be executed.
@@ -157,7 +160,7 @@ export declare interface HttpsCallableOptions {
      */
     timeout?: number;
     /**
-     * If set to true, uses limited-use App Check token for callable function requests from this
+     * If set to true, uses a limited-use App Check token for callable function requests from this
      * instance of {@link Functions}. You must use limited-use tokens to call functions with
      * replay protection enabled. By default, this is false.
      */
@@ -175,4 +178,31 @@ export declare interface HttpsCallableResult<ResponseData = unknown> {
     readonly data: ResponseData;
 }
 
+/**
+ * An interface for metadata about how a stream call should be executed.
+ * @public
+ */
+export declare interface HttpsCallableStreamOptions {
+    /**
+     * An `AbortSignal` that can be used to cancel the streaming response. When the signal is aborted,
+     * the underlying HTTP connection will be terminated.
+     */
+    signal?: AbortSignal;
+    /**
+     * If set to true, uses a limited-use App Check token for callable function requests from this
+     * instance of {@link Functions}. You must use limited-use tokens to call functions with
+     * replay protection enabled. By default, this is false.
+     */
+    limitedUseAppCheckTokens?: boolean;
+}
+
+/**
+ * An `HttpsCallableStreamResult` wraps a single streaming result from a function call.
+ * @public
+ */
+export declare interface HttpsCallableStreamResult<ResponseData = unknown, StreamData = unknown> {
+    readonly data: Promise<ResponseData>;
+    readonly stream: AsyncIterable<StreamData>;
+}
+
 export { }

package/dist/functions.d.ts

@@ -126,25 +126,28 @@ export declare type FunctionsErrorCodeCore = 'ok' | 'cancelled' | 'unknown' | 'i
 export declare function getFunctions(app?: FirebaseApp, regionOrCustomDomain?: string): Functions;
 
 /**
- * A reference to a "callable" HTTP trigger in Google Cloud Functions.
+ * A reference to a "callable" HTTP trigger in Cloud Functions.
  * @param data - Data to be passed to callable function.
  * @public
  */
-export declare type HttpsCallable<RequestData = unknown, ResponseData = unknown> = (data?: RequestData | null) => Promise<HttpsCallableResult<ResponseData>>;
+export declare interface HttpsCallable<RequestData = unknown, ResponseData = unknown, StreamData = unknown> {
+    (data?: RequestData | null): Promise<HttpsCallableResult<ResponseData>>;
+    stream: (data?: RequestData | null, options?: HttpsCallableStreamOptions) => Promise<HttpsCallableStreamResult<ResponseData, StreamData>>;
+}
 
 /**
  * Returns a reference to the callable HTTPS trigger with the given name.
  * @param name - The name of the trigger.
  * @public
  */
-export declare function httpsCallable<RequestData = unknown, ResponseData = unknown>(functionsInstance: Functions, name: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData>;
+export declare function httpsCallable<RequestData = unknown, ResponseData = unknown, StreamData = unknown>(functionsInstance: Functions, name: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData, StreamData>;
 
 /**
  * Returns a reference to the callable HTTPS trigger with the specified url.
  * @param url - The url of the trigger.
  * @public
  */
-export declare function httpsCallableFromURL<RequestData = unknown, ResponseData = unknown>(functionsInstance: Functions, url: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData>;
+export declare function httpsCallableFromURL<RequestData = unknown, ResponseData = unknown, StreamData = unknown>(functionsInstance: Functions, url: string, options?: HttpsCallableOptions): HttpsCallable<RequestData, ResponseData, StreamData>;
 
 /**
  * An interface for metadata about how calls should be executed.
@@ -157,7 +160,7 @@ export declare interface HttpsCallableOptions {
      */
     timeout?: number;
     /**
-     * If set to true, uses limited-use App Check token for callable function requests from this
+     * If set to true, uses a limited-use App Check token for callable function requests from this
      * instance of {@link Functions}. You must use limited-use tokens to call functions with
      * replay protection enabled. By default, this is false.
      */
@@ -175,4 +178,31 @@ export declare interface HttpsCallableResult<ResponseData = unknown> {
     readonly data: ResponseData;
 }
 
+/**
+ * An interface for metadata about how a stream call should be executed.
+ * @public
+ */
+export declare interface HttpsCallableStreamOptions {
+    /**
+     * An `AbortSignal` that can be used to cancel the streaming response. When the signal is aborted,
+     * the underlying HTTP connection will be terminated.
+     */
+    signal?: AbortSignal;
+    /**
+     * If set to true, uses a limited-use App Check token for callable function requests from this
+     * instance of {@link Functions}. You must use limited-use tokens to call functions with
+     * replay protection enabled. By default, this is false.
+     */
+    limitedUseAppCheckTokens?: boolean;
+}
+
+/**
+ * An `HttpsCallableStreamResult` wraps a single streaming result from a function call.
+ * @public
+ */
+export declare interface HttpsCallableStreamResult<ResponseData = unknown, StreamData = unknown> {
+    readonly data: Promise<ResponseData>;
+    readonly stream: AsyncIterable<StreamData>;
+}
+
 export { }

package/dist/index.cjs.js

@@ -403,6 +403,7 @@ class ContextProvider {
  * limitations under the License.
  */
 const DEFAULT_REGION = 'us-central1';
+const responseLineRE = /^data: (.*?)(?:\n|$)/;
 /**
  * Returns a Promise that will be rejected after the given duration.
  * The error will be of type FunctionsError.
@@ -436,8 +437,9 @@ class FunctionsService {
      * Creates a new Functions service for the given app.
      * @param app - The FirebaseApp to use.
      */
-    constructor(app, authProvider, messagingProvider, appCheckProvider, regionOrCustomDomain = DEFAULT_REGION) {
+    constructor(app, authProvider, messagingProvider, appCheckProvider, regionOrCustomDomain = DEFAULT_REGION, fetchImpl = (...args) => fetch(...args)) {
         this.app = app;
+        this.fetchImpl = fetchImpl;
         this.emulatorOrigin = null;
         this.contextProvider = new ContextProvider(authProvider, messagingProvider, appCheckProvider);
         // Cancels all ongoing requests when resolved.
@@ -496,9 +498,13 @@ function connectFunctionsEmulator$1(functionsInstance, host, port) {
  * @public
  */
 function httpsCallable$1(functionsInstance, name, options) {
-    return (data => {
+    const callable = (data) => {
         return call(functionsInstance, name, data, options || {});
-    });
+    };
+    callable.stream = (data, options) => {
+        return stream(functionsInstance, name, data, options);
+    };
+    return callable;
 }
 /**
  * Returns a reference to the callable https trigger with the given url.
@@ -506,9 +512,13 @@ function httpsCallable$1(functionsInstance, name, options) {
  * @public
  */
 function httpsCallableFromURL$1(functionsInstance, url, options) {
-    return (data => {
+    const callable = (data) => {
         return callAtURL(functionsInstance, url, data, options || {});
-    });
+    };
+    callable.stream = (data, options) => {
+        return streamAtURL(functionsInstance, url, data, options || {});
+    };
+    return callable;
 }
 /**
  * Does an HTTP POST and returns the completed response.
@@ -517,11 +527,11 @@ function httpsCallableFromURL$1(functionsInstance, url, options) {
  * @param headers The HTTP headers to include in the request.
  * @return A Promise that will succeed when the request finishes.
  */
-async function postJSON(url, body, headers) {
+async function postJSON(url, body, headers, fetchImpl) {
     headers['Content-Type'] = 'application/json';
     let response;
     try {
-        response = await fetch(url, {
+        response = await fetchImpl(url, {
             method: 'POST',
             body: JSON.stringify(body),
             headers
@@ -549,10 +559,30 @@ async function postJSON(url, body, headers) {
         json
     };
 }
+/**
+ * Creates authorization headers for Firebase Functions requests.
+ * @param functionsInstance The Firebase Functions service instance.
+ * @param options Options for the callable function, including AppCheck token settings.
+ * @return A Promise that resolves a headers map to include in outgoing fetch request.
+ */
+async function makeAuthHeaders(functionsInstance, options) {
+    const headers = {};
+    const context = await functionsInstance.contextProvider.getContext(options.limitedUseAppCheckTokens);
+    if (context.authToken) {
+        headers['Authorization'] = 'Bearer ' + context.authToken;
+    }
+    if (context.messagingToken) {
+        headers['Firebase-Instance-ID-Token'] = context.messagingToken;
+    }
+    if (context.appCheckToken !== null) {
+        headers['X-Firebase-AppCheck'] = context.appCheckToken;
+    }
+    return headers;
+}
 /**
  * Calls a callable function asynchronously and returns the result.
  * @param name The name of the callable trigger.
- * @param data The data to pass as params to the function.s
+ * @param data The data to pass as params to the function.
  */
 function call(functionsInstance, name, data, options) {
     const url = functionsInstance._url(name);
@@ -561,29 +591,19 @@ function call(functionsInstance, name, data, options) {
 /**
  * Calls a callable function asynchronously and returns the result.
  * @param url The url of the callable trigger.
- * @param data The data to pass as params to the function.s
+ * @param data The data to pass as params to the function.
  */
 async function callAtURL(functionsInstance, url, data, options) {
     // Encode any special types, such as dates, in the input data.
     data = encode(data);
     const body = { data };
     // Add a header for the authToken.
-    const headers = {};
-    const context = await functionsInstance.contextProvider.getContext(options.limitedUseAppCheckTokens);
-    if (context.authToken) {
-        headers['Authorization'] = 'Bearer ' + context.authToken;
-    }
-    if (context.messagingToken) {
-        headers['Firebase-Instance-ID-Token'] = context.messagingToken;
-    }
-    if (context.appCheckToken !== null) {
-        headers['X-Firebase-AppCheck'] = context.appCheckToken;
-    }
+    const headers = await makeAuthHeaders(functionsInstance, options);
     // Default timeout to 70s, but let the options override it.
     const timeout = options.timeout || 70000;
     const failAfterHandle = failAfter(timeout);
     const response = await Promise.race([
-        postJSON(url, body, headers),
+        postJSON(url, body, headers, functionsInstance.fetchImpl),
         failAfterHandle.promise,
         functionsInstance.cancelAllRequests
     ]);
@@ -615,9 +635,211 @@ async function callAtURL(functionsInstance, url, data, options) {
     const decodedData = decode(responseData);
     return { data: decodedData };
 }
+/**
+ * Calls a callable function asynchronously and returns a streaming result.
+ * @param name The name of the callable trigger.
+ * @param data The data to pass as params to the function.
+ * @param options Streaming request options.
+ */
+function stream(functionsInstance, name, data, options) {
+    const url = functionsInstance._url(name);
+    return streamAtURL(functionsInstance, url, data, options || {});
+}
+/**
+ * Calls a callable function asynchronously and return a streaming result.
+ * @param url The url of the callable trigger.
+ * @param data The data to pass as params to the function.
+ * @param options Streaming request options.
+ */
+async function streamAtURL(functionsInstance, url, data, options) {
+    var _a;
+    // Encode any special types, such as dates, in the input data.
+    data = encode(data);
+    const body = { data };
+    //
+    // Add a header for the authToken.
+    const headers = await makeAuthHeaders(functionsInstance, options);
+    headers['Content-Type'] = 'application/json';
+    headers['Accept'] = 'text/event-stream';
+    let response;
+    try {
+        response = await functionsInstance.fetchImpl(url, {
+            method: 'POST',
+            body: JSON.stringify(body),
+            headers,
+            signal: options === null || options === void 0 ? void 0 : options.signal
+        });
+    }
+    catch (e) {
+        if (e instanceof Error && e.name === 'AbortError') {
+            const error = new FunctionsError('cancelled', 'Request was cancelled.');
+            return {
+                data: Promise.reject(error),
+                stream: {
+                    [Symbol.asyncIterator]() {
+                        return {
+                            next() {
+                                return Promise.reject(error);
+                            }
+                        };
+                    }
+                }
+            };
+        }
+        // This could be an unhandled error on the backend, or it could be a
+        // network error. There's no way to know, since an unhandled error on the
+        // backend will fail to set the proper CORS header, and thus will be
+        // treated as a network error by fetch.
+        const error = _errorForResponse(0, null);
+        return {
+            data: Promise.reject(error),
+            // Return an empty async iterator
+            stream: {
+                [Symbol.asyncIterator]() {
+                    return {
+                        next() {
+                            return Promise.reject(error);
+                        }
+                    };
+                }
+            }
+        };
+    }
+    let resultResolver;
+    let resultRejecter;
+    const resultPromise = new Promise((resolve, reject) => {
+        resultResolver = resolve;
+        resultRejecter = reject;
+    });
+    (_a = options === null || options === void 0 ? void 0 : options.signal) === null || _a === void 0 ? void 0 : _a.addEventListener('abort', () => {
+        const error = new FunctionsError('cancelled', 'Request was cancelled.');
+        resultRejecter(error);
+    });
+    const reader = response.body.getReader();
+    const rstream = createResponseStream(reader, resultResolver, resultRejecter, options === null || options === void 0 ? void 0 : options.signal);
+    return {
+        stream: {
+            [Symbol.asyncIterator]() {
+                const rreader = rstream.getReader();
+                return {
+                    async next() {
+                        const { value, done } = await rreader.read();
+                        return { value: value, done };
+                    },
+                    async return() {
+                        await rreader.cancel();
+                        return { done: true, value: undefined };
+                    }
+                };
+            }
+        },
+        data: resultPromise
+    };
+}
+/**
+ * Creates a ReadableStream that processes a streaming response from a streaming
+ * callable function that returns data in server-sent event format.
+ *
+ * @param reader The underlying reader providing raw response data
+ * @param resultResolver Callback to resolve the final result when received
+ * @param resultRejecter Callback to reject with an error if encountered
+ * @param signal Optional AbortSignal to cancel the stream processing
+ * @returns A ReadableStream that emits decoded messages from the response
+ *
+ * The returned ReadableStream:
+ *   1. Emits individual messages when "message" data is received
+ *   2. Resolves with the final result when a "result" message is received
+ *   3. Rejects with an error if an "error" message is received
+ */
+function createResponseStream(reader, resultResolver, resultRejecter, signal) {
+    const processLine = (line, controller) => {
+        const match = line.match(responseLineRE);
+        // ignore all other lines (newline, comments, etc.)
+        if (!match) {
+            return;
+        }
+        const data = match[1];
+        try {
+            const jsonData = JSON.parse(data);
+            if ('result' in jsonData) {
+                resultResolver(decode(jsonData.result));
+                return;
+            }
+            if ('message' in jsonData) {
+                controller.enqueue(decode(jsonData.message));
+                return;
+            }
+            if ('error' in jsonData) {
+                const error = _errorForResponse(0, jsonData);
+                controller.error(error);
+                resultRejecter(error);
+                return;
+            }
+        }
+        catch (error) {
+            if (error instanceof FunctionsError) {
+                controller.error(error);
+                resultRejecter(error);
+                return;
+            }
+            // ignore other parsing errors
+        }
+    };
+    const decoder = new TextDecoder();
+    return new ReadableStream({
+        start(controller) {
+            let currentText = '';
+            return pump();
+            async function pump() {
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                    const error = new FunctionsError('cancelled', 'Request was cancelled');
+                    controller.error(error);
+                    resultRejecter(error);
+                    return Promise.resolve();
+                }
+                try {
+                    const { value, done } = await reader.read();
+                    if (done) {
+                        if (currentText.trim()) {
+                            processLine(currentText.trim(), controller);
+                        }
+                        controller.close();
+                        return;
+                    }
+                    if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                        const error = new FunctionsError('cancelled', 'Request was cancelled');
+                        controller.error(error);
+                        resultRejecter(error);
+                        await reader.cancel();
+                        return;
+                    }
+                    currentText += decoder.decode(value, { stream: true });
+                    const lines = currentText.split('\n');
+                    currentText = lines.pop() || '';
+                    for (const line of lines) {
+                        if (line.trim()) {
+                            processLine(line.trim(), controller);
+                        }
+                    }
+                    return pump();
+                }
+                catch (error) {
+                    const functionsError = error instanceof FunctionsError
+                        ? error
+                        : _errorForResponse(0, null);
+                    controller.error(functionsError);
+                    resultRejecter(functionsError);
+                }
+            }
+        },
+        cancel() {
+            return reader.cancel();
+        }
+    });
+}
 
 const name = "@firebase/functions";
-const version = "0.11.10";
+const version = "0.12.0-20241210191049";
 
 /**
  * @license