diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index 4f8b8df736..7025ff8da5 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -28,6 +28,7 @@ const repoPath = path.resolve(`${__dirname}/..`); const defaultSources = [ `${repoPath}/lib/firebase-namespace.d.ts`, `${repoPath}/lib/firebase-namespace-api.d.ts`, + `${repoPath}/lib/core.d.ts`, `${repoPath}/lib/**/*.d.ts`, ]; diff --git a/etc/firebase-admin.api.md b/etc/firebase-admin.api.md index b5b810a5e6..a89b4359c8 100644 --- a/etc/firebase-admin.api.md +++ b/etc/firebase-admin.api.md @@ -9,17 +9,23 @@ import { Bucket } from '@google-cloud/storage'; import * as _firestore from '@google-cloud/firestore'; import * as rtdb from '@firebase/database-types'; +// @public (undocumented) +export interface App { + delete(): Promise; + name: string; + options: AppOptions; +} + // @public (undocumented) export function app(name?: string): app.App; // @public (undocumented) export namespace app { - export interface App { + export interface App extends App { // (undocumented) auth(): auth.Auth; // (undocumented) database(url?: string): database.Database; - delete(): Promise; // (undocumented) firestore(): firestore.Firestore; // (undocumented) @@ -28,8 +34,6 @@ export namespace app { machineLearning(): machineLearning.MachineLearning; // (undocumented) messaging(): messaging.Messaging; - name: string; - options: AppOptions; // (undocumented) projectManagement(): projectManagement.ProjectManagement; // (undocumented) diff --git a/gulpfile.js b/gulpfile.js index 9ca1aeb941..3776404b3e 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -86,6 +86,7 @@ gulp.task('compile', function() { 'lib/**/*.js', 'lib/**/index.d.ts', 'lib/firebase-namespace-api.d.ts', + 'lib/core.d.ts', '!lib/utils/index.d.ts', ]; diff --git a/src/core.ts b/src/core.ts new file mode 100644 index 0000000000..b36cc4bb1d --- /dev/null +++ b/src/core.ts @@ -0,0 +1,143 @@ +/*! + * Copyright 2021 Google Inc. + * + * 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 { Agent } from 'http'; + +import { credential } from './credential/index'; + +/** + * Available options to pass to [`initializeApp()`](admin#.initializeApp). + */ +export interface AppOptions { + + /** + * A {@link credential.Credential `Credential`} object used to + * authenticate the Admin SDK. + * + * See [Initialize the SDK](/docs/admin/setup#initialize_the_sdk) for detailed + * documentation and code samples. + */ + credential?: credential.Credential; + + /** + * The object to use as the [`auth`](/docs/reference/security/database/#auth) + * variable in your Realtime Database Rules when the Admin SDK reads from or + * writes to the Realtime Database. This allows you to downscope the Admin SDK + * from its default full read and write privileges. + * + * You can pass `null` to act as an unauthenticated client. + * + * See + * [Authenticate with limited privileges](/docs/database/admin/start#authenticate-with-limited-privileges) + * for detailed documentation and code samples. + */ + databaseAuthVariableOverride?: object | null; + + /** + * The URL of the Realtime Database from which to read and write data. + */ + databaseURL?: string; + + /** + * The ID of the service account to be used for signing custom tokens. This + * can be found in the `client_email` field of a service account JSON file. + */ + serviceAccountId?: string; + + /** + * The name of the Google Cloud Storage bucket used for storing application data. + * Use only the bucket name without any prefixes or additions (do *not* prefix + * the name with "gs://"). + */ + storageBucket?: string; + + /** + * The ID of the Google Cloud project associated with the App. + */ + projectId?: string; + + /** + * An [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * to be used when making outgoing HTTP calls. This Agent instance is used + * by all services that make REST calls (e.g. `auth`, `messaging`, + * `projectManagement`). + * + * Realtime Database and Firestore use other means of communicating with + * the backend servers, so they do not use this HTTP Agent. `Credential` + * instances also do not use this HTTP Agent, but instead support + * specifying an HTTP Agent in the corresponding factory methods. + */ + httpAgent?: Agent; +} + +export interface App { + + /** + * The (read-only) name for this app. + * + * The default app's name is `"[DEFAULT]"`. + * + * @example + * ```javascript + * // The default app's name is "[DEFAULT]" + * admin.initializeApp(defaultAppConfig); + * console.log(admin.app().name); // "[DEFAULT]" + * ``` + * + * @example + * ```javascript + * // A named app's name is what you provide to initializeApp() + * var otherApp = admin.initializeApp(otherAppConfig, "other"); + * console.log(otherApp.name); // "other" + * ``` + */ + name: string; + + /** + * The (read-only) configuration options for this app. These are the original + * parameters given in + * {@link + * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp + * `admin.initializeApp()`}. + * + * @example + * ```javascript + * var app = admin.initializeApp(config); + * console.log(app.options.credential === config.credential); // true + * console.log(app.options.databaseURL === config.databaseURL); // true + * ``` + */ + options: AppOptions; + + /** + * Renders this local `FirebaseApp` unusable and frees the resources of + * all associated services (though it does *not* clean up any backend + * resources). When running the SDK locally, this method + * must be called to ensure graceful termination of the process. + * + * @example + * ```javascript + * app.delete() + * .then(function() { + * console.log("App deleted successfully"); + * }) + * .catch(function(error) { + * console.log("Error deleting app:", error); + * }); + * ``` + */ + delete(): Promise; +} diff --git a/src/firebase-namespace-api.ts b/src/firebase-namespace-api.ts index 36df1b778d..da78a8c393 100644 --- a/src/firebase-namespace-api.ts +++ b/src/firebase-namespace-api.ts @@ -14,9 +14,7 @@ * limitations under the License. */ -import { Agent } from 'http'; import { auth } from './auth/index'; -import { credential } from './credential/index'; import { database } from './database/index'; import { firestore } from './firestore/index'; import { instanceId } from './instance-id/index'; @@ -27,6 +25,10 @@ import { remoteConfig } from './remote-config/index'; import { securityRules } from './security-rules/index'; import { storage } from './storage/index'; +import { App as AppCore, AppOptions } from './core'; + +export * from './core'; + /** * `FirebaseError` is a subclass of the standard JavaScript `Error` object. In * addition to a message string and stack trace, it contains a string code. @@ -106,71 +108,6 @@ export interface FirebaseArrayIndexError { error: FirebaseError; } -/** - * Available options to pass to [`initializeApp()`](admin#.initializeApp). - */ -export interface AppOptions { - - /** - * A {@link credential.Credential `Credential`} object used to - * authenticate the Admin SDK. - * - * See [Initialize the SDK](/docs/admin/setup#initialize_the_sdk) for detailed - * documentation and code samples. - */ - credential?: credential.Credential; - - /** - * The object to use as the [`auth`](/docs/reference/security/database/#auth) - * variable in your Realtime Database Rules when the Admin SDK reads from or - * writes to the Realtime Database. This allows you to downscope the Admin SDK - * from its default full read and write privileges. - * - * You can pass `null` to act as an unauthenticated client. - * - * See - * [Authenticate with limited privileges](/docs/database/admin/start#authenticate-with-limited-privileges) - * for detailed documentation and code samples. - */ - databaseAuthVariableOverride?: object | null; - - /** - * The URL of the Realtime Database from which to read and write data. - */ - databaseURL?: string; - - /** - * The ID of the service account to be used for signing custom tokens. This - * can be found in the `client_email` field of a service account JSON file. - */ - serviceAccountId?: string; - - /** - * The name of the Google Cloud Storage bucket used for storing application data. - * Use only the bucket name without any prefixes or additions (do *not* prefix - * the name with "gs://"). - */ - storageBucket?: string; - - /** - * The ID of the Google Cloud project associated with the App. - */ - projectId?: string; - - /** - * An [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) - * to be used when making outgoing HTTP calls. This Agent instance is used - * by all services that make REST calls (e.g. `auth`, `messaging`, - * `projectManagement`). - * - * Realtime Database and Firestore use other means of communicating with - * the backend servers, so they do not use this HTTP Agent. `Credential` - * instances also do not use this HTTP Agent, but instead support - * specifying an HTTP Agent in the corresponding factory methods. - */ - httpAgent?: Agent; -} - // eslint-disable-next-line @typescript-eslint/no-namespace export namespace app { /** @@ -183,45 +120,7 @@ export namespace app { * `admin.initializeApp()`} * to create an app. */ - export interface App { - - /** - * The (read-only) name for this app. - * - * The default app's name is `"[DEFAULT]"`. - * - * @example - * ```javascript - * // The default app's name is "[DEFAULT]" - * admin.initializeApp(defaultAppConfig); - * console.log(admin.app().name); // "[DEFAULT]" - * ``` - * - * @example - * ```javascript - * // A named app's name is what you provide to initializeApp() - * var otherApp = admin.initializeApp(otherAppConfig, "other"); - * console.log(otherApp.name); // "other" - * ``` - */ - name: string; - - /** - * The (read-only) configuration options for this app. These are the original - * parameters given in - * {@link - * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp - * `admin.initializeApp()`}. - * - * @example - * ```javascript - * var app = admin.initializeApp(config); - * console.log(app.options.credential === config.credential); // true - * console.log(app.options.databaseURL === config.databaseURL); // true - * ``` - */ - options: AppOptions; - + export interface App extends AppCore { auth(): auth.Auth; database(url?: string): database.Database; firestore(): firestore.Firestore; @@ -232,25 +131,6 @@ export namespace app { remoteConfig(): remoteConfig.RemoteConfig; securityRules(): securityRules.SecurityRules; storage(): storage.Storage; - - /** - * Renders this local `FirebaseApp` unusable and frees the resources of - * all associated services (though it does *not* clean up any backend - * resources). When running the SDK locally, this method - * must be called to ensure graceful termination of the process. - * - * @example - * ```javascript - * app.delete() - * .then(function() { - * console.log("App deleted successfully"); - * }) - * .catch(function(error) { - * console.log("Error deleting app:", error); - * }); - * ``` - */ - delete(): Promise; } }