diff --git a/etc/firebase-admin.api.md b/etc/firebase-admin.api.md index 1340ad4fca..00fe991142 100644 --- a/etc/firebase-admin.api.md +++ b/etc/firebase-admin.api.md @@ -10,7 +10,7 @@ import { FirebaseDatabase } from '@firebase/database-types'; import * as _firestore from '@google-cloud/firestore'; import * as rtdb from '@firebase/database-types'; -// @public (undocumented) +// @public export interface App { name: string; options: AppOptions; @@ -46,7 +46,7 @@ export namespace app { } } -// @public (undocumented) +// @public export function applicationDefault(httpAgent?: Agent): Credential; // @public @@ -274,10 +274,10 @@ export namespace auth { export type UserRecord = UserRecord; } -// @public (undocumented) +// @public export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential; -// @public (undocumented) +// @public export interface Credential { getAccessToken(): Promise; } @@ -316,7 +316,7 @@ export namespace database { const ServerValue: rtdb.ServerValue; } -// @public (undocumented) +// @public export function deleteApp(app: App): Promise; // @public @@ -618,7 +618,7 @@ export namespace projectManagement { export type ShaCertificate = ShaCertificate; } -// @public (undocumented) +// @public export function refreshToken(refreshTokenPathOrObject: string | object, httpAgent?: Agent): Credential; // @public diff --git a/etc/firebase-admin.app.api.md b/etc/firebase-admin.app.api.md index 08d145df0c..1614e2acb3 100644 --- a/etc/firebase-admin.app.api.md +++ b/etc/firebase-admin.app.api.md @@ -6,13 +6,13 @@ import { Agent } from 'http'; -// @public (undocumented) +// @public export interface App { name: string; options: AppOptions; } -// @public (undocumented) +// @public export function applicationDefault(httpAgent?: Agent): Credential; // @public @@ -26,15 +26,15 @@ export interface AppOptions { storageBucket?: string; } -// @public (undocumented) +// @public export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential; -// @public (undocumented) +// @public export interface Credential { getAccessToken(): Promise; } -// @public (undocumented) +// @public export function deleteApp(app: App): Promise; // @public @@ -68,7 +68,7 @@ export interface GoogleOAuthAccessToken { // @public (undocumented) export function initializeApp(options?: AppOptions, name?: string): App; -// @public (undocumented) +// @public export function refreshToken(refreshTokenPathOrObject: string | object, httpAgent?: Agent): Credential; // @public (undocumented) diff --git a/etc/firebase-admin.instance-id.api.md b/etc/firebase-admin.instance-id.api.md index f5929e7efc..a391fbacc7 100644 --- a/etc/firebase-admin.instance-id.api.md +++ b/etc/firebase-admin.instance-id.api.md @@ -8,7 +8,7 @@ import { Agent } from 'http'; // Warning: (ae-forgotten-export) The symbol "App" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function getInstanceId(app?: App): InstanceId; // @public diff --git a/src/app/core.ts b/src/app/core.ts index c234b2875f..a946e8ab41 100644 --- a/src/app/core.ts +++ b/src/app/core.ts @@ -84,6 +84,16 @@ export interface AppOptions { httpAgent?: Agent; } +/** + * A Firebase app holds the initialization information for a collection of + * services. + * + * Do not call this constructor directly. Instead, use + * {@link + * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp + * `admin.initializeApp()`} + * to create an app. + */ export interface App { /** @@ -94,14 +104,14 @@ export interface App { * @example * ```javascript * // The default app's name is "[DEFAULT]" - * admin.initializeApp(defaultAppConfig); + * 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"); + * const otherApp = initializeApp(otherAppConfig, "other"); * console.log(otherApp.name); // "other" * ``` */ @@ -116,7 +126,7 @@ export interface App { * * @example * ```javascript - * var app = admin.initializeApp(config); + * const app = initializeApp(config); * console.log(app.options.credential === config.credential); // true * console.log(app.options.databaseURL === config.databaseURL); // true * ``` diff --git a/src/app/credential-factory.ts b/src/app/credential-factory.ts index a0fdcc37e1..96f92821f8 100644 --- a/src/app/credential-factory.ts +++ b/src/app/credential-factory.ts @@ -26,6 +26,40 @@ let globalAppDefaultCred: Credential | undefined; const globalCertCreds: { [key: string]: ServiceAccountCredential } = {}; const globalRefreshTokenCreds: { [key: string]: RefreshTokenCredential } = {}; +/** + * Returns a credential created from the + * {@link + * https://developers.google.com/identity/protocols/application-default-credentials + * Google Application Default Credentials} + * that grants admin access to Firebase services. This credential can be used + * in the call to + * {@link + * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp + * `admin.initializeApp()`}. + * + * Google Application Default Credentials are available on any Google + * infrastructure, such as Google App Engine and Google Compute Engine. + * + * See + * {@link + * https://firebase.google.com/docs/admin/setup#initialize_the_sdk + * Initialize the SDK} + * for more details. + * + * @example + * ```javascript + * initializeApp({ + * credential: applicationDefault(), + * databaseURL: "https://.firebaseio.com" + * }); + * ``` + * + * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * to be used when retrieving access tokens from Google token servers. + * + * @return A credential authenticated via Google + * Application Default Credentials that can be used to initialize an app. + */ export function applicationDefault(httpAgent?: Agent): Credential { if (typeof globalAppDefaultCred === 'undefined') { globalAppDefaultCred = getApplicationDefault(httpAgent); @@ -33,6 +67,51 @@ export function applicationDefault(httpAgent?: Agent): Credential { return globalAppDefaultCred; } +/** + * Returns a credential created from the provided service account that grants + * admin access to Firebase services. This credential can be used in the call + * to + * {@link + * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp + * `admin.initializeApp()`}. + * + * See + * {@link + * https://firebase.google.com/docs/admin/setup#initialize_the_sdk + * Initialize the SDK} + * for more details. + * + * @example + * ```javascript + * // Providing a path to a service account key JSON file + * const serviceAccount = require("path/to/serviceAccountKey.json"); + * initializeApp({ + * credential: cert(serviceAccount), + * databaseURL: "https://.firebaseio.com" + * }); + * ``` + * + * @example + * ```javascript + * // Providing a service account object inline + * initializeApp({ + * credential: cert({ + * projectId: "", + * clientEmail: "foo@.iam.gserviceaccount.com", + * privateKey: "-----BEGIN PRIVATE KEY----------END PRIVATE KEY-----\n" + * }), + * databaseURL: "https://.firebaseio.com" + * }); + * ``` + * + * @param serviceAccountPathOrObject The path to a service + * account key JSON file or an object representing a service account key. + * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * to be used when retrieving access tokens from Google token servers. + * + * @return A credential authenticated via the + * provided service account that can be used to initialize an app. + */ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential { const stringifiedServiceAccount = JSON.stringify(serviceAccountPathOrObject); if (!(stringifiedServiceAccount in globalCertCreds)) { @@ -42,6 +121,39 @@ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAg return globalCertCreds[stringifiedServiceAccount]; } +/** + * Returns a credential created from the provided refresh token that grants + * admin access to Firebase services. This credential can be used in the call + * to + * {@link + * https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp + * `admin.initializeApp()`}. + * + * See + * {@link + * https://firebase.google.com/docs/admin/setup#initialize_the_sdk + * Initialize the SDK} + * for more details. + * + * @example + * ```javascript + * // Providing a path to a refresh token JSON file + * const refreshToken = require("path/to/refreshToken.json"); + * initializeApp({ + * credential: refreshToken(refreshToken), + * databaseURL: "https://.firebaseio.com" + * }); + * ``` + * + * @param refreshTokenPathOrObject The path to a Google + * OAuth2 refresh token JSON file or an object representing a Google OAuth2 + * refresh token. + * @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent) + * to be used when retrieving access tokens from Google token servers. + * + * @return A credential authenticated via the + * provided service account that can be used to initialize an app. + */ export function refreshToken(refreshTokenPathOrObject: string | object, httpAgent?: Agent): Credential { const stringifiedRefreshToken = JSON.stringify(refreshTokenPathOrObject); if (!(stringifiedRefreshToken in globalRefreshTokenCreds)) { diff --git a/src/app/credential.ts b/src/app/credential.ts index ef4a020494..82e3e1ccc1 100644 --- a/src/app/credential.ts +++ b/src/app/credential.ts @@ -29,6 +29,14 @@ export interface GoogleOAuthAccessToken { expires_in: number; } +/** + * Interface that provides Google OAuth2 access tokens used to authenticate + * with Firebase services. + * + * In most cases, you will not need to implement this yourself and can instead + * use the default implementations provided by + * {@link credential `admin.credential`}. + */ export interface Credential { /** * Returns a Google OAuth2 access token object used to authenticate with diff --git a/src/app/lifecycle.ts b/src/app/lifecycle.ts index 8fc03b6119..ed999e6650 100644 --- a/src/app/lifecycle.ts +++ b/src/app/lifecycle.ts @@ -41,6 +41,23 @@ export function getApps(): App[] { return defaultNamespace.apps; } +/** + * Renders this given `App` 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 + * deleteApp(app) + * .then(function() { + * console.log("App deleted successfully"); + * }) + * .catch(function(error) { + * console.log("Error deleting app:", error); + * }); + * ``` + */ export function deleteApp(app: App): Promise { if (typeof app !== 'object' || app === null || !('options' in app)) { throw new FirebaseAppError(AppErrorCodes.INVALID_ARGUMENT, 'Invalid app argument.'); diff --git a/src/instance-id/index.ts b/src/instance-id/index.ts index 6f40351e7c..ef7a56b997 100644 --- a/src/instance-id/index.ts +++ b/src/instance-id/index.ts @@ -20,6 +20,36 @@ import { InstanceId } from './instance-id'; export { InstanceId }; +/** + * Gets the {@link InstanceId `InstanceId`} service for the + * default app or a given app. + * + * `getInstanceId()` can be called with no arguments to access the default + * app's {@link InstanceId `InstanceId`} service or as + * `getInstanceId(app)` to access the + * {@link InstanceId `InstanceId`} service associated with a + * specific app. + * + * @example + * ```javascript + * // Get the Instance ID service for the default app + * const defaultInstanceId = getInstanceId(); + * ``` + * + * @example + * ```javascript + * // Get the Instance ID service for a given app + * const otherInstanceId = getInstanceId(otherApp); + *``` + * + * @param app Optional app whose `InstanceId` service to + * return. If not provided, the default `InstanceId` service will be + * returned. + * + * @return The default `InstanceId` service if + * no app is provided or the `InstanceId` service associated with the + * provided app. + */ export function getInstanceId(app?: App): InstanceId { if (typeof app === 'undefined') { app = getApp(); diff --git a/src/instance-id/instance-id.ts b/src/instance-id/instance-id.ts index 1af8bdb151..0e7bd0a66a 100644 --- a/src/instance-id/instance-id.ts +++ b/src/instance-id/instance-id.ts @@ -20,18 +20,8 @@ import { FirebaseInstanceIdRequestHandler } from './instance-id-request-internal import * as validator from '../utils/validator'; /** - * Gets the {@link InstanceId `InstanceId`} service for the - * current app. - * - * @example - * ```javascript - * var instanceId = app.instanceId(); - * // The above is shorthand for: - * // var instanceId = admin.instanceId(app); - * ``` - * - * @return The `InstanceId` service for the - * current app. + * The `InstanceId` service enables deleting the Firebase instance IDs + * associated with Firebase client app instances. */ export class InstanceId {