From 1b250dda3acd1bff9ec81a84d1e2fb1938693820 Mon Sep 17 00:00:00 2001 From: Hiranya Jayathilaka Date: Mon, 6 Jan 2020 13:54:56 -0800 Subject: [PATCH 1/2] Splitting the index.d.ts file into smaller files --- docgen/generate-docs.js | 4 +- gulpfile.js | 2 +- src/auth.d.ts | 1581 +++++ src/database.d.ts | 1636 +++++ src/index.d.ts | 5552 +---------------- src/instance-id.d.ts | 36 + src/messaging.d.ts | 1331 ++++ src/project-management.d.ts | 360 ++ src/security-rules.d.ts | 191 + .../typescript/src/example.test.ts | 24 +- 10 files changed, 5426 insertions(+), 5291 deletions(-) create mode 100644 src/auth.d.ts create mode 100644 src/database.d.ts create mode 100644 src/instance-id.d.ts create mode 100644 src/messaging.d.ts create mode 100644 src/project-management.d.ts create mode 100644 src/security-rules.d.ts diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index b0abb98c9d..bc04538bfb 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -28,7 +28,7 @@ const repoPath = path.resolve(`${__dirname}/..`); // Command-line options. const { source: sourceFile } = yargs .option('source', { - default: `${repoPath}/src/index.d.ts`, + default: `${repoPath}/src/*.d.ts`, describe: 'Typescript source file(s)', type: 'string' }) @@ -283,7 +283,7 @@ function addFirestoreTypeAliases() { let contentBlock = firestoreHeader; lineReader.on('line', (line) => { line = line.trim(); - if (line.startsWith('export import') && line.indexOf('_firestore.')) { + if (line.startsWith('export import') && line.indexOf('_firestore.') >= 0) { const typeName = line.split(' ')[2]; if (firestoreExcludes.indexOf(typeName) === -1) { contentBlock += ` diff --git a/gulpfile.js b/gulpfile.js index 82c10c774c..959cf46c05 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -107,7 +107,7 @@ gulp.task('copyDatabase', function() { }); gulp.task('copyTypings', function() { - return gulp.src('src/index.d.ts') + return gulp.src('src/*.d.ts') // Add header .pipe(header(banner)) diff --git a/src/auth.d.ts b/src/auth.d.ts new file mode 100644 index 0000000000..db645de81e --- /dev/null +++ b/src/auth.d.ts @@ -0,0 +1,1581 @@ +import * as _admin from './index.d'; + +export namespace admin.auth { + + /** + * Interface representing a user's metadata. + */ + interface UserMetadata { + + /** + * The date the user last signed in, formatted as a UTC string. + */ + lastSignInTime: string; + + /** + * The date the user was created, formatted as a UTC string. + * + */ + creationTime: string; + + /** + * @return A JSON-serializable representation of this object. + */ + toJSON(): Object; + } + + /** + * Interface representing a user's info from a third-party identity provider + * such as Google or Facebook. + */ + interface UserInfo { + + /** + * The user identifier for the linked provider. + */ + uid: string; + + /** + * The display name for the linked provider. + */ + displayName: string; + + /** + * The email for the linked provider. + */ + email: string; + + /** + * The phone number for the linked provider. + */ + phoneNumber: string; + + /** + * The photo URL for the linked provider. + */ + photoURL: string; + + /** + * The linked provider ID (for example, "google.com" for the Google provider). + */ + providerId: string; + + /** + * @return A JSON-serializable representation of this object. + */ + toJSON(): Object; + } + + /** + * Interface representing a user. + */ + interface UserRecord { + + /** + * The user's `uid`. + */ + uid: string; + + /** + * The user's primary email, if set. + */ + email?: string; + + /** + * Whether or not the user's primary email is verified. + */ + emailVerified: boolean; + + /** + * The user's display name. + */ + displayName?: string; + + /** + * The user's primary phone number, if set. + */ + phoneNumber?: string; + + /** + * The user's photo URL. + */ + photoURL?: string; + + /** + * Whether or not the user is disabled: `true` for disabled; `false` for + * enabled. + */ + disabled: boolean; + + /** + * Additional metadata about the user. + */ + metadata: admin.auth.UserMetadata; + + /** + * An array of providers (for example, Google, Facebook) linked to the user. + */ + providerData: admin.auth.UserInfo[]; + + /** + * The user's hashed password (base64-encoded), only if Firebase Auth hashing + * algorithm (SCRYPT) is used. If a different hashing algorithm had been used + * when uploading this user, as is typical when migrating from another Auth + * system, this will be an empty string. If no password is set, this is + * null. This is only available when the user is obtained from + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listUsers `listUsers()`}. + * + */ + passwordHash?: string; + + /** + * The user's password salt (base64-encoded), only if Firebase Auth hashing + * algorithm (SCRYPT) is used. If a different hashing algorithm had been used to + * upload this user, typical when migrating from another Auth system, this will + * be an empty string. If no password is set, this is null. This is only + * available when the user is obtained from + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listUsers `listUsers()`}. + * + */ + passwordSalt?: string; + + /** + * The user's custom claims object if available, typically used to define + * user roles and propagated to an authenticated user's ID token. + * This is set via + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#setCustomUserClaims `setCustomUserClaims()`} + */ + customClaims?: Object; + + /** + * The date the user's tokens are valid after, formatted as a UTC string. + * This is updated every time the user's refresh token are revoked either + * from the {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#revokeRefreshTokens `revokeRefreshTokens()`} + * API or from the Firebase Auth backend on big account changes (password + * resets, password or email updates, etc). + */ + tokensValidAfterTime?: string; + + /** + * The ID of the tenant the user belongs to, if available. + */ + tenantId?: string | null; + + /** + * @return A JSON-serializable representation of this object. + */ + toJSON(): Object; + } + + /** + * Interface representing the properties to update on the provided user. + */ + interface UpdateRequest { + + /** + * Whether or not the user is disabled: `true` for disabled; + * `false` for enabled. + */ + disabled?: boolean; + + /** + * The user's display name. + */ + displayName?: string | null; + + /** + * The user's primary email. + */ + email?: string; + + /** + * Whether or not the user's primary email is verified. + */ + emailVerified?: boolean; + + /** + * The user's unhashed password. + */ + password?: string; + + /** + * The user's primary phone number. + */ + phoneNumber?: string | null; + + /** + * The user's photo URL. + */ + photoURL?: string | null; + } + + /** + * Interface representing the properties to set on a new user record to be + * created. + */ + interface CreateRequest extends UpdateRequest { + + /** + * The user's `uid`. + */ + uid?: string; + } + + /** + * Interface representing a decoded Firebase ID token, returned from the + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#verifyIdToken `verifyIdToken()`} method. + * + * Firebase ID tokens are OpenID Connect spec-compliant JSON Web Tokens (JWTs). + * See the + * [ID Token section of the OpenID Connect spec](http://openid.net/specs/openid-connect-core-1_0.html#IDToken) + * for more information about the specific properties below. + */ + interface DecodedIdToken { + + /** + * The audience for which this token is intended. + * + * This value is a string equal to your Firebase project ID, the unique + * identifier for your Firebase project, which can be found in [your project's + * settings](https://console.firebase.google.com/project/_/settings/general/android:com.random.android). + */ + aud: string; + + /** + * Time, in seconds since the Unix epoch, when the end-user authentication + * occurred. + * + * This value is not set when this particular ID token was created, but when the + * user initially logged in to this session. In a single session, the Firebase + * SDKs will refresh a user's ID tokens every hour. Each ID token will have a + * different [`iat`](#iat) value, but the same `auth_time` value. + */ + auth_time: number; + + /** + * The ID token's expiration time, in seconds since the Unix epoch. That is, the + * time at which this ID token expires and should no longer be considered valid. + * + * The Firebase SDKs transparently refresh ID tokens every hour, issuing a new + * ID token with up to a one hour expiration. + */ + exp: number; + + /** + * Information about the sign in event, including which sign in provider was + * used and provider-specific identity details. + * + * This data is provided by the Firebase Authentication service and is a + * reserved claim in the ID token. + */ + firebase: { + + /** + * Provider-specific identity details corresponding + * to the provider used to sign in the user. + */ + identities: { + [key: string]: any; + }; + + /** + * The ID of the provider used to sign in the user. + * One of `"anonymous"`, `"password"`, `"facebook.com"`, `"github.com"`, + * `"google.com"`, `"twitter.com"`, or `"custom"`. + */ + sign_in_provider: string; + + /** + * The ID of the tenant the user belongs to, if available. + */ + tenant?: string; + [key: string]: any; + }; + + /** + * The ID token's issued-at time, in seconds since the Unix epoch. That is, the + * time at which this ID token was issued and should start to be considered + * valid. + * + * The Firebase SDKs transparently refresh ID tokens every hour, issuing a new + * ID token with a new issued-at time. If you want to get the time at which the + * user session corresponding to the ID token initially occurred, see the + * [`auth_time`](#auth_time) property. + */ + iat: number; + + /** + * The issuer identifier for the issuer of the response. + * + * This value is a URL with the format + * `https://securetoken.google.com/`, where `` is the + * same project ID specified in the [`aud`](#aud) property. + */ + iss: string; + + /** + * The `uid` corresponding to the user who the ID token belonged to. + * + * As a convenience, this value is copied over to the [`uid`](#uid) property. + */ + sub: string; + + /** + * The `uid` corresponding to the user who the ID token belonged to. + * + * This value is not actually in the JWT token claims itself. It is added as a + * convenience, and is set as the value of the [`sub`](#sub) property. + */ + uid: string; + [key: string]: any; + } + + /** + * Interface representing the object returned from a + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listUsers `listUsers()`} operation. Contains the list + * of users for the current batch and the next page token if available. + */ + interface ListUsersResult { + + /** + * The list of {@link admin.auth.UserRecord `UserRecord`} objects for the + * current downloaded batch. + */ + users: admin.auth.UserRecord[]; + + /** + * The next page token if available. This is needed for the next batch download. + */ + pageToken?: string; + } + + type HashAlgorithmType = 'SCRYPT' | 'STANDARD_SCRYPT' | 'HMAC_SHA512' | + 'HMAC_SHA256' | 'HMAC_SHA1' | 'HMAC_MD5' | 'MD5' | 'PBKDF_SHA1' | 'BCRYPT' | + 'PBKDF2_SHA256' | 'SHA512' | 'SHA256' | 'SHA1'; + + /** + * Interface representing the user import options needed for + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#importUsers `importUsers()`} method. This is used to + * provide the password hashing algorithm information. + */ + interface UserImportOptions { + + /** + * The password hashing information. + */ + hash: { + + /** + * The password hashing algorithm identifier. The following algorithm + * identifiers are supported: + * `SCRYPT`, `STANDARD_SCRYPT`, `HMAC_SHA512`, `HMAC_SHA256`, `HMAC_SHA1`, + * `HMAC_MD5`, `MD5`, `PBKDF_SHA1`, `BCRYPT`, `PBKDF2_SHA256`, `SHA512`, + * `SHA256` and `SHA1`. + */ + algorithm: HashAlgorithmType; + + /** + * The signing key used in the hash algorithm in buffer bytes. + * Required by hashing algorithms `SCRYPT`, `HMAC_SHA512`, `HMAC_SHA256`, + * `HAMC_SHA1` and `HMAC_MD5`. + */ + key?: Buffer; + + /** + * The salt separator in buffer bytes which is appended to salt when + * verifying a password. This is only used by the `SCRYPT` algorithm. + */ + saltSeparator?: Buffer; + + /** + * The number of rounds for hashing calculation. + * Required for `SCRYPT`, `MD5`, `SHA512`, `SHA256`, `SHA1`, `PBKDF_SHA1` and + * `PBKDF2_SHA256`. + */ + rounds?: number; + + /** + * The memory cost required for `SCRYPT` algorithm, or the CPU/memory cost. + * Required for `STANDARD_SCRYPT` algorithm. + */ + memoryCost?: number; + + /** + * The parallelization of the hashing algorithm. Required for the + * `STANDARD_SCRYPT` algorithm. + */ + parallelization?: number; + + /** + * The block size (normally 8) of the hashing algorithm. Required for the + * `STANDARD_SCRYPT` algorithm. + */ + blockSize?: number; + /** + * The derived key length of the hashing algorithm. Required for the + * `STANDARD_SCRYPT` algorithm. + */ + derivedKeyLength?: number; + }; + } + + /** + * Interface representing the response from the + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#importUsers `importUsers()`} method for batch + * importing users to Firebase Auth. + */ + interface UserImportResult { + + /** + * The number of user records that failed to import to Firebase Auth. + */ + failureCount: number; + + /** + * The number of user records that successfully imported to Firebase Auth. + */ + successCount: number; + + /** + * An array of errors corresponding to the provided users to import. The + * length of this array is equal to [`failureCount`](#failureCount). + */ + errors: _admin.FirebaseArrayIndexError[]; + } + + /** + * Interface representing a user to import to Firebase Auth via the + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#importUsers `importUsers()`} method. + */ + interface UserImportRecord { + + /** + * The user's `uid`. + */ + uid: string; + + /** + * The user's primary email, if set. + */ + email?: string; + + /** + * Whether or not the user's primary email is verified. + */ + emailVerified: boolean; + + /** + * The user's display name. + */ + displayName?: string; + + /** + * The user's primary phone number, if set. + */ + phoneNumber?: string; + + /** + * The user's photo URL. + */ + photoURL?: string; + + /** + * Whether or not the user is disabled: `true` for disabled; `false` for + * enabled. + */ + disabled: boolean; + + /** + * Additional metadata about the user. + */ + metadata: admin.auth.UserMetadata; + + /** + * An array of providers (for example, Google, Facebook) linked to the user. + */ + providerData?: admin.auth.UserInfo[]; + + /** + * The user's custom claims object if available, typically used to define + * user roles and propagated to an authenticated user's ID token. + */ + customClaims?: Object; + + /** + * The buffer of bytes representing the user's hashed password. + * When a user is to be imported with a password hash, + * {@link admin.auth.UserImportOptions `UserImportOptions`} are required to be + * specified to identify the hashing algorithm used to generate this hash. + */ + passwordHash?: Buffer; + + /** + * The buffer of bytes representing the user's password salt. + */ + passwordSalt?: Buffer; + + /** + * The identifier of the tenant where user is to be imported to. + * When not provided in an `admin.auth.Auth` context, the user is uploaded to + * the default parent project. + * When not provided in an `admin.auth.TenantAwareAuth` context, the user is uploaded + * to the tenant corresponding to that `TenantAwareAuth` instance's tenant ID. + */ + tenantId?: string | null; + } + + /** + * Interface representing the session cookie options needed for the + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createSessionCookie `createSessionCookie()`} method. + */ + interface SessionCookieOptions { + + /** + * The session cookie custom expiration in milliseconds. The minimum allowed is + * 5 minutes and the maxium allowed is 2 weeks. + */ + expiresIn: number; + } + + /** + * This is the interface that defines the required continue/state URL with + * optional Android and iOS bundle identifiers. + */ + interface ActionCodeSettings { + + /** + * Defines the link continue/state URL, which has different meanings in + * different contexts: + *
    + *
  • When the link is handled in the web action widgets, this is the deep + * link in the `continueUrl` query parameter.
    • + *
  • When the link is handled in the app directly, this is the `continueUrl` + * query parameter in the deep link of the Dynamic Link.
    • + *
+ */ + url: string; + + /** + * Whether to open the link via a mobile app or a browser. + * The default is false. When set to true, the action code link is sent + * as a Universal Link or Android App Link and is opened by the app if + * installed. In the false case, the code is sent to the web widget first + * and then redirects to the app if installed. + */ + handleCodeInApp?: boolean; + + /** + * Defines the iOS bundle ID. This will try to open the link in an iOS app if it + * is installed. + */ + iOS?: { + + /** + * Defines the required iOS bundle ID of the app where the link should be + * handled if the application is already installed on the device. + */ + bundleId: string; + }; + + /** + * Defines the Android package name. This will try to open the link in an + * android app if it is installed. If `installApp` is passed, it specifies + * whether to install the Android app if the device supports it and the app is + * not already installed. If this field is provided without a `packageName`, an + * error is thrown explaining that the `packageName` must be provided in + * conjunction with this field. If `minimumVersion` is specified, and an older + * version of the app is installed, the user is taken to the Play Store to + * upgrade the app. + */ + android?: { + + /** + * Defines the required Android package name of the app where the link should be + * handled if the Android app is installed. + */ + packageName: string; + + /** + * Whether to install the Android app if the device supports it and the app is + * not already installed. + */ + installApp?: boolean; + + /** + * The Android minimum version if available. If the installed app is an older + * version, the user is taken to the GOogle Play Store to upgrade the app. + */ + minimumVersion?: string; + }; + + /** + * Defines the dynamic link domain to use for the current link if it is to be + * opened using Firebase Dynamic Links, as multiple dynamic link domains can be + * configured per project. This field provides the ability to explicitly choose + * configured per project. This fields provides the ability explicitly choose + * one. If none is provided, the oldest domain is used by default. + */ + dynamicLinkDomain?: string; + } + + /** + * Interface representing a tenant configuration. + * + * Multi-tenancy support requires Google Cloud's Identity Platform + * (GCIP). To learn more about GCIP, including pricing and features, + * see the [GCIP documentation](https://cloud.google.com/identity-platform) + * + * Before multi-tenancy can be used on a Google Cloud Identity Platform project, + * tenants must be allowed on that project via the Cloud Console UI. + * + * A tenant configuration provides information such as the display name, tenant + * identifier and email authentication configuration. + * For OIDC/SAML provider configuration management, `TenantAwareAuth` instances should + * be used instead of a `Tenant` to retrieve the list of configured IdPs on a tenant. + * When configuring these providers, note that tenants will inherit + * whitelisted domains and authenticated redirect URIs of their parent project. + * + * All other settings of a tenant will also be inherited. These will need to be managed + * from the Cloud Console UI. + */ + interface Tenant { + + /** + * The tenant identifier. + */ + tenantId: string; + + /** + * The tenant display name. + */ + displayName?: string; + + /** + * The email sign in provider configuration. + */ + emailSignInConfig?: { + + /** + * Whether email provider is enabled. + */ + enabled: boolean; + + /** + * Whether password is required for email sign-in. When not required, + * email sign-in can be performed with password or via email link sign-in. + */ + passwordRequired?: boolean + }; + + /** + * @return A JSON-serializable representation of this object. + */ + toJSON(): Object; + } + + /** + * Interface representing the properties to update on the provided tenant. + */ + interface UpdateTenantRequest { + + /** + * The tenant display name. + */ + displayName?: string; + + /** + * The email sign in configuration. + */ + emailSignInConfig?: { + + /** + * Whether email provider is enabled. + */ + enabled: boolean; + + /** + * Whether password is required for email sign-in. When not required, + * email sign-in can be performed with password or via email link sign-in. + */ + passwordRequired?: boolean; + }; + } + + /** + * Interface representing the properties to set on a new tenant. + */ + interface CreateTenantRequest extends UpdateTenantRequest { + } + + /** + * Interface representing the object returned from a + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listTenants `listTenants()`} + * operation. + * Contains the list of tenants for the current batch and the next page token if available. + */ + interface ListTenantsResult { + + /** + * The list of {@link admin.auth.Tenant `Tenant`} objects for the downloaded batch. + */ + tenants: admin.auth.Tenant[]; + + /** + * The next page token if available. This is needed for the next batch download. + */ + pageToken?: string; + } + + /** + * The filter interface used for listing provider configurations. This is used + * when specifying how to list configured identity providers via + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listProviderConfigs `listProviderConfigs()`}. + */ + interface AuthProviderConfigFilter { + + /** + * The Auth provider configuration filter. This can be either `saml` or `oidc`. + * The former is used to look up SAML providers only, while the latter is used + * for OIDC providers. + */ + type: 'saml' | 'oidc'; + + /** + * The maximum number of results to return per page. The default and maximum is + * 100. + */ + maxResults?: number; + + /** + * The next page token. When not specified, the lookup starts from the beginning + * of the list. + */ + pageToken?: string; + } + + /** + * The base Auth provider configuration interface. + */ + interface AuthProviderConfig { + + /** + * The provider ID defined by the developer. + * For a SAML provider, this is always prefixed by `saml.`. + * For an OIDC provider, this is always prefixed by `oidc.`. + */ + providerId: string; + + /** + * The user-friendly display name to the current configuration. This name is + * also used as the provider label in the Cloud Console. + */ + displayName: string; + + /** + * Whether the provider configuration is enabled or disabled. A user + * cannot sign in using a disabled provider. + */ + enabled: boolean; + } + + /** + * The + * [SAML](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html) + * Auth provider configuration interface. A SAML provider can be created via + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createProviderConfig `createProviderConfig()`}. + */ + interface SAMLAuthProviderConfig extends admin.auth.AuthProviderConfig { + + /** + * The SAML IdP entity identifier. + */ + idpEntityId: string; + + /** + * The SAML IdP SSO URL. This must be a valid URL. + */ + ssoURL: string; + + /** + * The list of SAML IdP X.509 certificates issued by CA for this provider. + * Multiple certificates are accepted to prevent outages during + * IdP key rotation (for example ADFS rotates every 10 days). When the Auth + * server receives a SAML response, it will match the SAML response with the + * certificate on record. Otherwise the response is rejected. + * Developers are expected to manage the certificate updates as keys are + * rotated. + */ + x509Certificates: string[]; + + /** + * The SAML relying party (service provider) entity ID. + * This is defined by the developer but needs to be provided to the SAML IdP. + */ + rpEntityId: string; + + /** + * This is fixed and must always be the same as the OAuth redirect URL + * provisioned by Firebase Auth, + * `https://project-id.firebaseapp.com/__/auth/handler` unless a custom + * `authDomain` is used. + * The callback URL should also be provided to the SAML IdP during + * configuration. + */ + callbackURL?: string; + } + + /** + * The [OIDC](https://openid.net/specs/openid-connect-core-1_0-final.html) Auth + * provider configuration interface. An OIDC provider can be created via + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createProviderConfig `createProviderConfig()`}. + */ + interface OIDCAuthProviderConfig extends admin.auth.AuthProviderConfig { + + /** + * This is the required client ID used to confirm the audience of an OIDC + * provider's + * [ID token](https://openid.net/specs/openid-connect-core-1_0-final.html#IDToken). + */ + clientId: string; + + /** + * This is the required provider issuer used to match the provider issuer of + * the ID token and to determine the corresponding OIDC discovery document, eg. + * [`/.well-known/openid-configuration`](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). + * This is needed for the following: + *
    + *
  • To verify the provided issuer.
    • + *
  • Determine the authentication/authorization endpoint during the OAuth + * `id_token` authentication flow.
    • + *
  • To retrieve the public signing keys via `jwks_uri` to verify the OIDC + * provider's ID token's signature.
    • + *
  • To determine the claims_supported to construct the user attributes to be + * returned in the additional user info response.
    • + *
+ * ID token validation will be performed as defined in the + * [spec](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation). + */ + issuer: string; + } + + /** + * The request interface for updating a SAML Auth provider. This is used + * when updating a SAML provider's configuration via + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#updateProviderConfig `updateProviderConfig()`}. + */ + interface SAMLUpdateAuthProviderRequest { + + /** + * The SAML provider's updated display name. If not provided, the existing + * configuration's value is not modified. + */ + displayName?: string; + + /** + * Whether the SAML provider is enabled or not. If not provided, the existing + * configuration's setting is not modified. + */ + enabled?: boolean; + + /** + * The SAML provider's updated IdP entity ID. If not provided, the existing + * configuration's value is not modified. + */ + idpEntityId?: string; + + /** + * The SAML provider's updated SSO URL. If not provided, the existing + * configuration's value is not modified. + */ + ssoURL?: string; + + /** + * The SAML provider's updated list of X.509 certificated. If not provided, the + * existing configuration list is not modified. + */ + x509Certificates?: string[]; + + /** + * The SAML provider's updated RP entity ID. If not provided, the existing + * configuration's value is not modified. + */ + rpEntityId?: string; + + /** + * The SAML provider's callback URL. If not provided, the existing + * configuration's value is not modified. + */ + callbackURL?: string; + } + + /** + * The request interface for updating an OIDC Auth provider. This is used + * when updating an OIDC provider's configuration via + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#updateProviderConfig `updateProviderConfig()`}. + */ + interface OIDCUpdateAuthProviderRequest { + + /** + * The OIDC provider's updated display name. If not provided, the existing + * configuration's value is not modified. + */ + displayName?: string; + + /** + * Whether the OIDC provider is enabled or not. If not provided, the existing + * configuration's setting is not modified. + */ + enabled?: boolean; + + /** + * The OIDC provider's updated client ID. If not provided, the existing + * configuration's value is not modified. + */ + clientId?: string; + + /** + * The OIDC provider's updated issuer. If not provided, the existing + * configuration's value is not modified. + */ + issuer?: string; + } + + /** + * The response interface for listing provider configs. This is only available + * when listing all identity providers' configurations via + * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listProviderConfigs `listProviderConfigs()`}. + */ + interface ListProviderConfigResults { + + /** + * The list of providers for the specified type in the current page. + */ + providerConfigs: admin.auth.AuthProviderConfig[]; + + /** + * The next page token, if available. + */ + pageToken?: string; + } + + + type UpdateAuthProviderRequest = + admin.auth.SAMLUpdateAuthProviderRequest | admin.auth.OIDCUpdateAuthProviderRequest; + + interface BaseAuth { + + /** + * Creates a new Firebase custom token (JWT) that can be sent back to a client + * device to use to sign in with the client SDKs' `signInWithCustomToken()` + * methods. (Tenant-aware instances will also embed the tenant ID in the + * token.) + * + * See [Create Custom Tokens](/docs/auth/admin/create-custom-tokens) for code + * samples and detailed documentation. + * + * @param uid The `uid` to use as the custom token's subject. + * @param developerClaims Optional additional claims to include + * in the custom token's payload. + * + * @return A promise fulfilled with a custom token for the + * provided `uid` and payload. + */ + createCustomToken(uid: string, developerClaims?: Object): Promise; + + /** + * Creates a new user. + * + * See [Create a user](/docs/auth/admin/manage-users#create_a_user) for code + * samples and detailed documentation. + * + * @param properties The properties to set on the + * new user record to be created. + * + * @return A promise fulfilled with the user + * data corresponding to the newly created user. + */ + createUser(properties: admin.auth.CreateRequest): Promise; + + /** + * Deletes an existing user. + * + * See [Delete a user](/docs/auth/admin/manage-users#delete_a_user) for code + * samples and detailed documentation. + * + * @param uid The `uid` corresponding to the user to delete. + * + * @return An empty promise fulfilled once the user has been + * deleted. + */ + deleteUser(uid: string): Promise; + + /** + * Gets the user data for the user corresponding to a given `uid`. + * + * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) + * for code samples and detailed documentation. + * + * @param uid The `uid` corresponding to the user whose data to fetch. + * + * @return A promise fulfilled with the user + * data corresponding to the provided `uid`. + */ + getUser(uid: string): Promise; + + /** + * Gets the user data for the user corresponding to a given email. + * + * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) + * for code samples and detailed documentation. + * + * @param email The email corresponding to the user whose data to + * fetch. + * + * @return A promise fulfilled with the user + * data corresponding to the provided email. + */ + getUserByEmail(email: string): Promise; + + /** + * Gets the user data for the user corresponding to a given phone number. The + * phone number has to conform to the E.164 specification. + * + * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) + * for code samples and detailed documentation. + * + * @param phoneNumber The phone number corresponding to the user whose + * data to fetch. + * + * @return A promise fulfilled with the user + * data corresponding to the provided phone number. + */ + getUserByPhoneNumber(phoneNumber: string): Promise; + + /** + * Retrieves a list of users (single batch only) with a size of `maxResults` + * starting from the offset as specified by `pageToken`. This is used to + * retrieve all the users of a specified project in batches. + * + * See [List all users](/docs/auth/admin/manage-users#list_all_users) + * for code samples and detailed documentation. + * + * @param maxResults The page size, 1000 if undefined. This is also + * the maximum allowed limit. + * @param pageToken The next page token. If not specified, returns + * users starting without any offset. + * @return A promise that resolves with + * the current batch of downloaded users and the next page token. + */ + listUsers(maxResults?: number, pageToken?: string): Promise; + + /** + * Updates an existing user. + * + * See [Update a user](/docs/auth/admin/manage-users#update_a_user) for code + * samples and detailed documentation. + * + * @param uid The `uid` corresponding to the user to delete. + * @param properties The properties to update on + * the provided user. + * + * @return A promise fulfilled with the + * updated user data. + */ + updateUser(uid: string, properties: admin.auth.UpdateRequest): Promise; + + /** + * Verifies a Firebase ID token (JWT). If the token is valid, the promise is + * fulfilled with the token's decoded claims; otherwise, the promise is + * rejected. + * An optional flag can be passed to additionally check whether the ID token + * was revoked. + * + * See [Verify ID Tokens](/docs/auth/admin/verify-id-tokens) for code samples + * and detailed documentation. + * + * @param idToken The ID token to verify. + * @param checkRevoked Whether to check if the ID token was revoked. + * This requires an extra request to the Firebase Auth backend to check + * the `tokensValidAfterTime` time for the corresponding user. + * When not specified, this additional check is not applied. + * + * @return A promise fulfilled with the + * token's decoded claims if the ID token is valid; otherwise, a rejected + * promise. + */ + verifyIdToken(idToken: string, checkRevoked?: boolean): Promise; + + /** + * Sets additional developer claims on an existing user identified by the + * provided `uid`, typically used to define user roles and levels of + * access. These claims should propagate to all devices where the user is + * already signed in (after token expiration or when token refresh is forced) + * and the next time the user signs in. If a reserved OIDC claim name + * is used (sub, iat, iss, etc), an error is thrown. They are set on the + * authenticated user's ID token JWT. + * + * See + * [Defining user roles and access levels](/docs/auth/admin/custom-claims) + * for code samples and detailed documentation. + * + * @param uid The `uid` of the user to edit. + * @param customUserClaims The developer claims to set. If null is + * passed, existing custom claims are deleted. Passing a custom claims payload + * larger than 1000 bytes will throw an error. Custom claims are added to the + * user's ID token which is transmitted on every authenticated request. + * For profile non-access related user attributes, use database or other + * separate storage systems. + * @return A promise that resolves when the operation completes + * successfully. + */ + setCustomUserClaims(uid: string, customUserClaims: Object | null): Promise; + + /** + * Revokes all refresh tokens for an existing user. + * + * This API will update the user's + * {@link admin.auth.UserRecord#tokensValidAfterTime `tokensValidAfterTime`} to + * the current UTC. It is important that the server on which this is called has + * its clock set correctly and synchronized. + * + * While this will revoke all sessions for a specified user and disable any + * new ID tokens for existing sessions from getting minted, existing ID tokens + * may remain active until their natural expiration (one hour). To verify that + * ID tokens are revoked, use + * {@link admin.auth.Auth#verifyIdToken `verifyIdToken(idToken, true)`} + * where `checkRevoked` is set to true. + * + * @param uid The `uid` corresponding to the user whose refresh tokens + * are to be revoked. + * + * @return An empty promise fulfilled once the user's refresh + * tokens have been revoked. + */ + revokeRefreshTokens(uid: string): Promise; + + /** + * Imports the provided list of users into Firebase Auth. + * A maximum of 1000 users are allowed to be imported one at a time. + * When importing users with passwords, + * {@link admin.auth.UserImportOptions `UserImportOptions`} are required to be + * specified. + * This operation is optimized for bulk imports and will ignore checks on `uid`, + * `email` and other identifier uniqueness which could result in duplications. + * + * @param users The list of user records to import to Firebase Auth. + * @param options The user import options, required when the users provided include + * password credentials. + * @return A promise that resolves when + * the operation completes with the result of the import. This includes the + * number of successful imports, the number of failed imports and their + * corresponding errors. + */ + importUsers( + users: admin.auth.UserImportRecord[], + options?: admin.auth.UserImportOptions, + ): Promise + + /** + * Creates a new Firebase session cookie with the specified options. The created + * JWT string can be set as a server-side session cookie with a custom cookie + * policy, and be used for session management. The session cookie JWT will have + * the same payload claims as the provided ID token. + * + * See [Manage Session Cookies](/docs/auth/admin/manage-cookies) for code + * samples and detailed documentation. + * + * @param idToken The Firebase ID token to exchange for a session + * cookie. + * @param sessionCookieOptions The session + * cookie options which includes custom session duration. + * + * @return A promise that resolves on success with the + * created session cookie. + */ + createSessionCookie( + idToken: string, + sessionCookieOptions: admin.auth.SessionCookieOptions, + ): Promise; + + /** + * Verifies a Firebase session cookie. Returns a Promise with the cookie claims. + * Rejects the promise if the cookie could not be verified. If `checkRevoked` is + * set to true, verifies if the session corresponding to the session cookie was + * revoked. If the corresponding user's session was revoked, an + * `auth/session-cookie-revoked` error is thrown. If not specified the check is + * not performed. + * + * See [Verify Session Cookies](/docs/auth/admin/manage-cookies#verify_session_cookie_and_check_permissions) + * for code samples and detailed documentation + * + * @param sessionCookie The session cookie to verify. + * @param checkForRevocation Whether to check if the session cookie was + * revoked. This requires an extra request to the Firebase Auth backend to + * check the `tokensValidAfterTime` time for the corresponding user. + * When not specified, this additional check is not performed. + * + * @return A promise fulfilled with the + * session cookie's decoded claims if the session cookie is valid; otherwise, + * a rejected promise. + */ + verifySessionCookie( + sessionCookie: string, + checkForRevocation?: boolean, + ): Promise; + + /** + * Generates the out of band email action link to reset a user's password. + * The link is generated for the user with the specified email address. The + * optional {@link admin.auth.ActionCodeSettings `ActionCodeSettings`} object + * defines whether the link is to be handled by a mobile app or browser and the + * additional state information to be passed in the deep link, etc. + * + * @example + * ```javascript + * var actionCodeSettings = { + * url: 'https://www.example.com/?email=user@example.com', + * iOS: { + * bundleId: 'com.example.ios' + * }, + * android: { + * packageName: 'com.example.android', + * installApp: true, + * minimumVersion: '12' + * }, + * handleCodeInApp: true, + * dynamicLinkDomain: 'custom.page.link' + * }; + * admin.auth() + * .generatePasswordResetLink('user@example.com', actionCodeSettings) + * .then(function(link) { + * // The link was successfully generated. + * }) + * .catch(function(error) { + * // Some error occurred, you can inspect the code: error.code + * }); + * ``` + * + * @param email The email address of the user whose password is to be + * reset. + * @param actionCodeSettings The action + * code settings. If specified, the state/continue URL is set as the + * "continueUrl" parameter in the password reset link. The default password + * reset landing page will use this to display a link to go back to the app + * if it is installed. + * If the actionCodeSettings is not specified, no URL is appended to the + * action URL. + * The state URL provided must belong to a domain that is whitelisted by the + * developer in the console. Otherwise an error is thrown. + * Mobile app redirects are only applicable if the developer configures + * and accepts the Firebase Dynamic Links terms of service. + * The Android package name and iOS bundle ID are respected only if they + * are configured in the same Firebase Auth project. + * @return A promise that resolves with the generated link. + */ + generatePasswordResetLink( + email: string, + actionCodeSettings?: admin.auth.ActionCodeSettings, + ): Promise; + + /** + * Generates the out of band email action link to verify the user's ownership + * of the specified email. The + * {@link admin.auth.ActionCodeSettings `ActionCodeSettings`} object provided + * as an argument to this method defines whether the link is to be handled by a + * mobile app or browser along with additional state information to be passed in + * the deep link, etc. + * + * @example + * ```javascript + * var actionCodeSettings = { + * url: 'https://www.example.com/cart?email=user@example.com&cartId=123', + * iOS: { + * bundleId: 'com.example.ios' + * }, + * android: { + * packageName: 'com.example.android', + * installApp: true, + * minimumVersion: '12' + * }, + * handleCodeInApp: true, + * dynamicLinkDomain: 'custom.page.link' + * }; + * admin.auth() + * .generateEmailVerificationLink('user@example.com', actionCodeSettings) + * .then(function(link) { + * // The link was successfully generated. + * }) + * .catch(function(error) { + * // Some error occurred, you can inspect the code: error.code + * }); + * ``` + * + * @param email The email account to verify. + * @param actionCodeSettings The action + * code settings. If specified, the state/continue URL is set as the + * "continueUrl" parameter in the email verification link. The default email + * verification landing page will use this to display a link to go back to + * the app if it is installed. + * If the actionCodeSettings is not specified, no URL is appended to the + * action URL. + * The state URL provided must belong to a domain that is whitelisted by the + * developer in the console. Otherwise an error is thrown. + * Mobile app redirects are only applicable if the developer configures + * and accepts the Firebase Dynamic Links terms of service. + * The Android package name and iOS bundle ID are respected only if they + * are configured in the same Firebase Auth project. + * @return A promise that resolves with the generated link. + */ + generateEmailVerificationLink( + email: string, + actionCodeSettings?: admin.auth.ActionCodeSettings, + ): Promise; + + /** + * Generates the out of band email action link to sign in or sign up the owner + * of the specified email. The + * {@link admin.auth.ActionCodeSettings `ActionCodeSettings`} object provided + * as an argument to this method defines whether the link is to be handled by a + * mobile app or browser along with additional state information to be passed in + * the deep link, etc. + * + * @example + * ```javascript + * var actionCodeSettings = { + * // The URL to redirect to for sign-in completion. This is also the deep + * // link for mobile redirects. The domain (www.example.com) for this URL + * // must be whitelisted in the Firebase Console. + * url: 'https://www.example.com/finishSignUp?cartId=1234', + * iOS: { + * bundleId: 'com.example.ios' + * }, + * android: { + * packageName: 'com.example.android', + * installApp: true, + * minimumVersion: '12' + * }, + * // This must be true. + * handleCodeInApp: true, + * dynamicLinkDomain: 'custom.page.link' + * }; + * admin.auth() + * .generateSignInWithEmailLink('user@example.com', actionCodeSettings) + * .then(function(link) { + * // The link was successfully generated. + * }) + * .catch(function(error) { + * // Some error occurred, you can inspect the code: error.code + * }); + * ``` + * + * @param email The email account to sign in with. + * @param actionCodeSettings The action + * code settings. These settings provide Firebase with instructions on how + * to construct the email link. This includes the sign in completion URL or + * the deep link for redirects and the mobile apps to use when the + * sign-in link is opened on an Android or iOS device. + * Mobile app redirects are only applicable if the developer configures + * and accepts the Firebase Dynamic Links terms of service. + * The Android package name and iOS bundle ID are respected only if they + * are configured in the same Firebase Auth project. + * @return A promise that resolves with the generated link. + */ + generateSignInWithEmailLink( + email: string, + actionCodeSettings: admin.auth.ActionCodeSettings, + ): Promise; + + /** + * Returns the list of existing provider configurations matching the filter + * provided. At most, 100 provider configs can be listed at a time. + * + * SAML and OIDC provider support requires Google Cloud's Identity Platform + * (GCIP). To learn more about GCIP, including pricing and features, + * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * + * @param options The provider config filter to apply. + * @return A promise that resolves with the list of provider configs meeting the + * filter requirements. + */ + listProviderConfigs( + options: admin.auth.AuthProviderConfigFilter + ): Promise; + + /** + * Looks up an Auth provider configuration by the provided ID. + * Returns a promise that resolves with the provider configuration + * corresponding to the provider ID specified. If the specified ID does not + * exist, an `auth/configuration-not-found` error is thrown. + * + * SAML and OIDC provider support requires Google Cloud's Identity Platform + * (GCIP). To learn more about GCIP, including pricing and features, + * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * + * @param providerId The provider ID corresponding to the provider + * config to return. + * @return A promise that resolves + * with the configuration corresponding to the provided ID. + */ + getProviderConfig(providerId: string): Promise; + + /** + * Deletes the provider configuration corresponding to the provider ID passed. + * If the specified ID does not exist, an `auth/configuration-not-found` error + * is thrown. + * + * SAML and OIDC provider support requires Google Cloud's Identity Platform + * (GCIP). To learn more about GCIP, including pricing and features, + * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * + * @param providerId The provider ID corresponding to the provider + * config to delete. + * @return A promise that resolves on completion. + */ + deleteProviderConfig(providerId: string): Promise; + + /** + * Returns a promise that resolves with the updated `AuthProviderConfig` + * corresponding to the provider ID specified. + * If the specified ID does not exist, an `auth/configuration-not-found` error + * is thrown. + * + * SAML and OIDC provider support requires Google Cloud's Identity Platform + * (GCIP). To learn more about GCIP, including pricing and features, + * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * + * @param providerId The provider ID corresponding to the provider + * config to update. + * @param updatedConfig The updated configuration. + * @return A promise that resolves with the updated provider configuration. + */ + updateProviderConfig( + providerId: string, updatedConfig: admin.auth.UpdateAuthProviderRequest + ): Promise; + + /** + * Returns a promise that resolves with the newly created `AuthProviderConfig` + * when the new provider configuration is created. + * + * SAML and OIDC provider support requires Google Cloud's Identity Platform + * (GCIP). To learn more about GCIP, including pricing and features, + * see the [GCIP documentation](https://cloud.google.com/identity-platform). + * + * @param config The provider configuration to create. + * @return A promise that resolves with the created provider configuration. + */ + createProviderConfig( + config: admin.auth.AuthProviderConfig + ): Promise; + } + + /** + * Tenant-aware `Auth` interface used for managing users, configuring SAML/OIDC providers, + * generating email links for password reset, email verification, etc for specific tenants. + * + * Multi-tenancy support requires Google Cloud's Identity Platform + * (GCIP). To learn more about GCIP, including pricing and features, + * see the [GCIP documentation](https://cloud.google.com/identity-platform) + * + * Each tenant contains its own identity providers, settings and sets of users. + * Using `TenantAwareAuth`, users for a specific tenant and corresponding OIDC/SAML + * configurations can also be managed, ID tokens for users signed in to a specific tenant + * can be verified, and email action links can also be generated for users belonging to the + * tenant. + * + * `TenantAwareAuth` instances for a specific `tenantId` can be instantiated by calling + * `auth.tenantManager().authForTenant(tenantId)`. + */ + interface TenantAwareAuth extends BaseAuth { + + /** + * The tenant identifier corresponding to this `TenantAwareAuth` instance. + * All calls to the user management APIs, OIDC/SAML provider management APIs, email link + * generation APIs, etc will only be applied within the scope of this tenant. + */ + tenantId: string; + } + + interface Auth extends admin.auth.BaseAuth { + app: _admin.app.App; + + /** + * @return The tenant manager instance associated with the current project. + */ + tenantManager(): admin.auth.TenantManager; + } + + /** + * Defines the tenant manager used to help manage tenant related operations. + * This includes: + *
    + *
  • The ability to create, update, list, get and delete tenants for the underlying + * project.
    • + *
  • Getting a `TenantAwareAuth` instance for running Auth related operations + * (user management, provider configuration management, token verification, + * email link generation, etc) in the context of a specified tenant.
    • + *
+ */ + interface TenantManager { + /** + * @param tenantId The tenant ID whose `TenantAwareAuth` instance is to be returned. + * + * @return The `TenantAwareAuth` instance corresponding to this tenant identifier. + */ + authForTenant(tenantId: string): admin.auth.TenantAwareAuth; + + /** + * Gets the tenant configuration for the tenant corresponding to a given `tenantId`. + * + * @param tenantId The tenant identifier corresponding to the tenant whose data to fetch. + * + * @return A promise fulfilled with the tenant configuration to the provided `tenantId`. + */ + getTenant(tenantId: string): Promise; + + /** + * Retrieves a list of tenants (single batch only) with a size of `maxResults` + * starting from the offset as specified by `pageToken`. This is used to + * retrieve all the tenants of a specified project in batches. + * + * @param maxResults The page size, 1000 if undefined. This is also + * the maximum allowed limit. + * @param pageToken The next page token. If not specified, returns + * tenants starting without any offset. + * + * @return A promise that resolves with + * a batch of downloaded tenants and the next page token. + */ + listTenants(maxResults?: number, pageToken?: string): Promise; + + /** + * Deletes an existing tenant. + * + * @param tenantId The `tenantId` corresponding to the tenant to delete. + * + * @return An empty promise fulfilled once the tenant has been deleted. + */ + deleteTenant(tenantId: string): Promise; + + /** + * Creates a new tenant. + * When creating new tenants, tenants that use separate billing and quota will require their + * own project and must be defined as `full_service`. + * + * @param tenantOptions The properties to set on the new tenant configuration to be created. + * + * @return A promise fulfilled with the tenant configuration corresponding to the newly + * created tenant. + */ + createTenant(tenantOptions: admin.auth.CreateTenantRequest): Promise; + + /** + * Updates an existing tenant configuration. + * + * @param tenantId The `tenantId` corresponding to the tenant to delete. + * @param tenantOptions The properties to update on the provided tenant. + * + * @return A promise fulfilled with the update tenant data. + */ + updateTenant(tenantId: string, tenantOptions: admin.auth.UpdateTenantRequest): Promise; + } +} diff --git a/src/database.d.ts b/src/database.d.ts new file mode 100644 index 0000000000..1026a97b3a --- /dev/null +++ b/src/database.d.ts @@ -0,0 +1,1636 @@ +import * as _admin from './index.d'; + +export namespace admin.database { + + /** + * The Firebase Realtime Database service interface. + * + * Do not call this constructor directly. Instead, use + * [`admin.database()`](admin.database#database). + * + * See + * {@link + * https://firebase.google.com/docs/database/admin/start/ + * Introduction to the Admin Database API} + * for a full guide on how to use the Firebase Realtime Database service. + */ + interface Database { + app: _admin.app.App; + + /** + * Disconnects from the server (all Database operations will be completed + * offline). + * + * The client automatically maintains a persistent connection to the Database + * server, which will remain active indefinitely and reconnect when + * disconnected. However, the `goOffline()` and `goOnline()` methods may be used + * to control the client connection in cases where a persistent connection is + * undesirable. + * + * While offline, the client will no longer receive data updates from the + * Database. However, all Database operations performed locally will continue to + * immediately fire events, allowing your application to continue behaving + * normally. Additionally, each operation performed locally will automatically + * be queued and retried upon reconnection to the Database server. + * + * To reconnect to the Database and begin receiving remote events, see + * `goOnline()`. + * + * @example + * ```javascript + * admin.database().goOffline(); + * ``` + */ + goOffline(): void; + + /** + * Reconnects to the server and synchronizes the offline Database state + * with the server state. + * + * This method should be used after disabling the active connection with + * `goOffline()`. Once reconnected, the client will transmit the proper data + * and fire the appropriate events so that your client "catches up" + * automatically. + * + * @example + * ```javascript + * admin.database().goOnline(); + * ``` + */ + goOnline(): void; + + /** + * Returns a `Reference` representing the location in the Database + * corresponding to the provided path. Also can be invoked with an existing + * `Reference` as the argument. In that case returns a new `Reference` + * pointing to the same location. If no path argument is + * provided, returns a `Reference` that represents the root of the Database. + * + * @example + * ```javascript + * // Get a reference to the root of the Database + * var rootRef = admin.database.ref(); + * ``` + * + * @example + * ```javascript + * // Get a reference to the /users/ada node + * var adaRef = admin.database().ref("users/ada"); + * // The above is shorthand for the following operations: + * //var rootRef = admin.database().ref(); + * //var adaRef = rootRef.child("users/ada"); + * ``` + * + * @example + * ```javascript + * var adaRef = admin.database().ref("users/ada"); + * // Get a new reference pointing to the same location. + * var anotherAdaRef = admin.database().ref(adaRef); + * ``` + * + * + * @param path Optional path representing + * the location the returned `Reference` will point. Alternatively, a + * `Reference` object to copy. If not provided, the returned `Reference` will + * point to the root of the Database. + * @return If a path is provided, a `Reference` + * pointing to the provided path. Otherwise, a `Reference` pointing to the + * root of the Database. + */ + ref(path?: string | admin.database.Reference): admin.database.Reference; + + /** + * Returns a `Reference` representing the location in the Database + * corresponding to the provided Firebase URL. + * + * An exception is thrown if the URL is not a valid Firebase Database URL or it + * has a different domain than the current `Database` instance. + * + * Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored + * and are not applied to the returned `Reference`. + * + * @example + * ```javascript + * // Get a reference to the root of the Database + * var rootRef = admin.database().ref("https://.firebaseio.com"); + * ``` + * + * @example + * ```javascript + * // Get a reference to the /users/ada node + * var adaRef = admin.database().ref("https://.firebaseio.com/users/ada"); + * ``` + * + * @param url The Firebase URL at which the returned `Reference` will + * point. + * @return A `Reference` pointing to the provided Firebase URL. + */ + refFromURL(url: string): admin.database.Reference; + + /** + * Gets the currently applied security rules as a string. The return value consists of + * the rules source including comments. + * + * @return A promise fulfilled with the rules as a raw string. + */ + getRules(): Promise; + + /** + * Gets the currently applied security rules as a parsed JSON object. Any comments in + * the original source are stripped away. + * + * @return A promise fulfilled with the parsed rules object. + */ + getRulesJSON(): Promise; + + /** + * Sets the specified rules on the Firebase Realtime Database instance. If the rules source is + * specified as a string or a Buffer, it may include comments. + * + * @param source Source of the rules to apply. Must not be `null` or empty. + * @return Resolves when the rules are set on the Realtime Database. + */ + setRules(source: string | Buffer | object): Promise; + } + + /** + * A `DataSnapshot` contains data from a Database location. + * + * Any time you read data from the Database, you receive the data as a + * `DataSnapshot`. A `DataSnapshot` is passed to the event callbacks you attach + * with `on()` or `once()`. You can extract the contents of the snapshot as a + * JavaScript object by calling the `val()` method. Alternatively, you can + * traverse into the snapshot by calling `child()` to return child snapshots + * (which you could then call `val()` on). + * + * A `DataSnapshot` is an efficiently generated, immutable copy of the data at + * a Database location. It cannot be modified and will never change (to modify + * data, you always call the `set()` method on a `Reference` directly). + */ + interface DataSnapshot { + key: string | null; + ref: admin.database.Reference; + + /** + * Gets another `DataSnapshot` for the location at the specified relative path. + * + * Passing a relative path to the `child()` method of a DataSnapshot returns + * another `DataSnapshot` for the location at the specified relative path. The + * relative path can either be a simple child name (for example, "ada") or a + * deeper, slash-separated path (for example, "ada/name/first"). If the child + * location has no data, an empty `DataSnapshot` (that is, a `DataSnapshot` + * whose value is `null`) is returned. + * + * @example + * ```javascript + * // Assume we have the following data in the Database: + * { + * "name": { + * "first": "Ada", + * "last": "Lovelace" + * } + * } + * + * // Test for the existence of certain keys within a DataSnapshot + * var ref = admin.database().ref("users/ada"); + * ref.once("value") + * .then(function(snapshot) { + * var name = snapshot.child("name").val(); // {first:"Ada",last:"Lovelace"} + * var firstName = snapshot.child("name/first").val(); // "Ada" + * var lastName = snapshot.child("name").child("last").val(); // "Lovelace" + * var age = snapshot.child("age").val(); // null + * }); + * ``` + * + * @param path A relative path to the location of child data. + * @return `DataSnapshot` for the location at the specified relative path. + */ + child(path: string): admin.database.DataSnapshot; + + /** + * Returns true if this `DataSnapshot` contains any data. It is slightly more + * efficient than using `snapshot.val() !== null`. + * + * @example + * ```javascript + * // Assume we have the following data in the Database: + * { + * "name": { + * "first": "Ada", + * "last": "Lovelace" + * } + * } + * + * // Test for the existence of certain keys within a DataSnapshot + * var ref = admin.database().ref("users/ada"); + * ref.once("value") + * .then(function(snapshot) { + * var a = snapshot.exists(); // true + * var b = snapshot.child("name").exists(); // true + * var c = snapshot.child("name/first").exists(); // true + * var d = snapshot.child("name/middle").exists(); // false + * }); + * ``` + * + * @return Whether this `DataSnapshot` contains any data. + */ + exists(): boolean; + + /** + * Exports the entire contents of the DataSnapshot as a JavaScript object. + * + * The `exportVal()` method is similar to `val()`, except priority information + * is included (if available), making it suitable for backing up your data. + * + * @return The DataSnapshot's contents as a JavaScript value (Object, + * Array, string, number, boolean, or `null`). + */ + exportVal(): any; + + /** + * Enumerates the top-level children in the `DataSnapshot`. + * + * Because of the way JavaScript objects work, the ordering of data in the + * JavaScript object returned by `val()` is not guaranteed to match the ordering + * on the server nor the ordering of `child_added` events. That is where + * `forEach()` comes in handy. It guarantees the children of a `DataSnapshot` + * will be iterated in their query order. + * + * If no explicit `orderBy*()` method is used, results are returned + * ordered by key (unless priorities are used, in which case, results are + * returned by priority). + * + * @example + * ```javascript + * + * // Assume we have the following data in the Database: + * { + * "users": { + * "ada": { + * "first": "Ada", + * "last": "Lovelace" + * }, + * "alan": { + * "first": "Alan", + * "last": "Turing" + * } + * } + * } + * + * // Loop through users in order with the forEach() method. The callback + * // provided to forEach() will be called synchronously with a DataSnapshot + * // for each child: + * var query = admin.database().ref("users").orderByKey(); + * query.once("value") + * .then(function(snapshot) { + * snapshot.forEach(function(childSnapshot) { + * // key will be "ada" the first time and "alan" the second time + * var key = childSnapshot.key; + * // childData will be the actual contents of the child + * var childData = childSnapshot.val(); + * }); + * }); + * ``` + * + * @example + * ```javascript + * // You can cancel the enumeration at any point by having your callback + * // function return true. For example, the following code sample will only + * // fire the callback function one time: + * var query = admin.database().ref("users").orderByKey(); + * query.once("value") + * .then(function(snapshot) { + * snapshot.forEach(function(childSnapshot) { + * var key = childSnapshot.key; // "ada" + * + * // Cancel enumeration + * return true; + * }); + * }); + * ``` + * + * @param action A function + * that will be called for each child `DataSnapshot`. The callback can return + * true to cancel further enumeration. + * @return True if enumeration was canceled due to your callback + * returning true. + */ + forEach(action: (a: admin.database.DataSnapshot) => boolean | void): boolean; + + /** + * Gets the priority value of the data in this `DataSnapshot`. + * + * Applications need not use priority but can order collections by + * ordinary properties (see + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data + * Sorting and filtering data}). + * + * @return The the priority value of the data in this `DataSnapshot`. + */ + getPriority(): string | number | null; + + /** + * Returns true if the specified child path has (non-null) data. + * + * @example + * ```javascript + * // Assume we have the following data in the Database: + * { + * "name": { + * "first": "Ada", + * "last": "Lovelace" + * } + * } + * + * // Determine which child keys in DataSnapshot have data. + * var ref = admin.database().ref("users/ada"); + * ref.once("value") + * .then(function(snapshot) { + * var hasName = snapshot.hasChild("name"); // true + * var hasAge = snapshot.hasChild("age"); // false + * }); + * ``` + * + * @param path A relative path to the location of a potential child. + * @return `true` if data exists at the specified child path; else + * `false`. + */ + hasChild(path: string): boolean; + + /** + * Returns whether or not the `DataSnapshot` has any non-`null` child + * properties. + * + * You can use `hasChildren()` to determine if a `DataSnapshot` has any + * children. If it does, you can enumerate them using `forEach()`. If it + * doesn't, then either this snapshot contains a primitive value (which can be + * retrieved with `val()`) or it is empty (in which case, `val()` will return + * `null`). + * + * @example + * ```javascript + * // Assume we have the following data in the Database: + * { + * "name": { + * "first": "Ada", + * "last": "Lovelace" + * } + * } + * + * var ref = admin.database().ref("users/ada"); + * ref.once("value") + * .then(function(snapshot) { + * var a = snapshot.hasChildren(); // true + * var b = snapshot.child("name").hasChildren(); // true + * var c = snapshot.child("name/first").hasChildren(); // false + * }); + * ``` + * + * @return True if this snapshot has any children; else false. + */ + hasChildren(): boolean; + + /** + * Returns the number of child properties of this `DataSnapshot`. + * + * @example + * ```javascript + * // Assume we have the following data in the Database: + * { + * "name": { + * "first": "Ada", + * "last": "Lovelace" + * } + * } + * + * var ref = admin.database().ref("users/ada"); + * ref.once("value") + * .then(function(snapshot) { + * var a = snapshot.numChildren(); // 1 ("name") + * var b = snapshot.child("name").numChildren(); // 2 ("first", "last") + * var c = snapshot.child("name/first").numChildren(); // 0 + * }); + * ``` + * + * @return The number of child properties of this `DataSnapshot`. + */ + numChildren(): number; + + /** + * @return A JSON-serializable representation of this object. + */ + toJSON(): Object | null; + + /** + * Extracts a JavaScript value from a `DataSnapshot`. + * + * Depending on the data in a `DataSnapshot`, the `val()` method may return a + * scalar type (string, number, or boolean), an array, or an object. It may also + * return null, indicating that the `DataSnapshot` is empty (contains no data). + * + * @example + * ```javascript + * // Write and then read back a string from the Database. + * ref.set("hello") + * .then(function() { + * return ref.once("value"); + * }) + * .then(function(snapshot) { + * var data = snapshot.val(); // data === "hello" + * }); + * ``` + * + * @example + * ```javascript + * // Write and then read back a JavaScript object from the Database. + * ref.set({ name: "Ada", age: 36 }) + * .then(function() { + * return ref.once("value"); + * }) + * .then(function(snapshot) { + * var data = snapshot.val(); + * // data is { "name": "Ada", "age": 36 } + * // data.name === "Ada" + * // data.age === 36 + * }); + * ``` + * + * @return The DataSnapshot's contents as a JavaScript value (Object, + * Array, string, number, boolean, or `null`). + */ + val(): any; + } + + /** + * The `onDisconnect` class allows you to write or clear data when your client + * disconnects from the Database server. These updates occur whether your + * client disconnects cleanly or not, so you can rely on them to clean up data + * even if a connection is dropped or a client crashes. + * + * The `onDisconnect` class is most commonly used to manage presence in + * applications where it is useful to detect how many clients are connected and + * when other clients disconnect. See + * {@link + * https://firebase.google.com/docs/database/web/offline-capabilities + * Enabling Offline Capabilities in JavaScript} for more information. + * + * To avoid problems when a connection is dropped before the requests can be + * transferred to the Database server, these functions should be called before + * any data is written. + * + * Note that `onDisconnect` operations are only triggered once. If you want an + * operation to occur each time a disconnect occurs, you'll need to re-establish + * the `onDisconnect` operations each time you reconnect. + */ + interface OnDisconnect { + + /** + * Cancels all previously queued `onDisconnect()` set or update events for this + * location and all children. + * + * If a write has been queued for this location via a `set()` or `update()` at a + * parent location, the write at this location will be canceled, though all + * other siblings will still be written. + * + * @example + * ```javascript + * var ref = admin.database().ref("onlineState"); + * ref.onDisconnect().set(false); + * // ... sometime later + * ref.onDisconnect().cancel(); + * ``` + * + * @param onComplete An optional callback function that is + * called when synchronization to the server has completed. The callback + * will be passed a single parameter: null for success, or an Error object + * indicating a failure. + * @return Resolves when synchronization to the server is complete. + */ + cancel(onComplete?: (a: Error | null) => any): Promise; + + /** + * Ensures the data at this location is deleted when the client is disconnected + * (due to closing the browser, navigating to a new page, or network issues). + * + * @param onComplete An optional callback function that is + * called when synchronization to the server has completed. The callback + * will be passed a single parameter: null for success, or an Error object + * indicating a failure. + * @return Resolves when synchronization to the server is complete. + */ + remove(onComplete?: (a: Error | null) => any): Promise; + + /** + * Ensures the data at this location is set to the specified value when the + * client is disconnected (due to closing the browser, navigating to a new page, + * or network issues). + * + * `set()` is especially useful for implementing "presence" systems, where a + * value should be changed or cleared when a user disconnects so that they + * appear "offline" to other users. See + * {@link + * https://firebase.google.com/docs/database/web/offline-capabilities + * Enabling Offline Capabilities in JavaScript} for more information. + * + * Note that `onDisconnect` operations are only triggered once. If you want an + * operation to occur each time a disconnect occurs, you'll need to re-establish + * the `onDisconnect` operations each time. + * + * @example + * ```javascript + * var ref = admin.database().ref("users/ada/status"); + * ref.onDisconnect().set("I disconnected!"); + * ``` + * + * @param value The value to be written to this location on + * disconnect (can be an object, array, string, number, boolean, or null). + * @param onComplete An optional callback function that + * will be called when synchronization to the database server has completed. + * The callback will be passed a single parameter: null for success, or an + * `Error` object indicating a failure. + * @return A promise that resolves when synchronization to the database is complete. + */ + set(value: any, onComplete?: (a: Error | null) => any): Promise; + + /** + * Ensures the data at this location is set to the specified value and priority + * when the client is disconnected (due to closing the browser, navigating to a + * new page, or network issues). + * + * @param value The value to be written to this location on + * disconnect (can be an object, array, string, number, boolean, or null). + * @param priority + * @param onComplete An optional callback function that is + * called when synchronization to the server has completed. The callback + * will be passed a single parameter: null for success, or an Error object + * indicating a failure. + * @return A promise that resolves when synchronization to the database is complete. + */ + setWithPriority( + value: any, + priority: number | string | null, + onComplete?: (a: Error | null) => any + ): Promise; + + /** + * Writes multiple values at this location when the client is disconnected (due + * to closing the browser, navigating to a new page, or network issues). + * + * The `values` argument contains multiple property-value pairs that will be + * written to the Database together. Each child property can either be a simple + * property (for example, "name") or a relative path (for example, "name/first") + * from the current location to the data to update. + * + * As opposed to the `set()` method, `update()` can be use to selectively update + * only the referenced properties at the current location (instead of replacing + * all the child properties at the current location). + * + * See {@link https://firebase.google.com/docs/reference/admin/node/admin.database.Reference#update} + * for examples of using the connected version of `update`. + * + * @example + * ```javascript + * var ref = admin.database().ref("users/ada"); + * ref.update({ + * onlineState: true, + * status: "I'm online." + * }); + * ref.onDisconnect().update({ + * onlineState: false, + * status: "I'm offline." + * }); + * ``` + * + * @param values Object containing multiple values. + * @param onComplete An optional callback function that will + * be called when synchronization to the server has completed. The + * callback will be passed a single parameter: null for success, or an Error + * object indicating a failure. + * @return Resolves when synchronization to the + * Database is complete. + */ + update(values: Object, onComplete?: (a: Error | null) => any): Promise; + } + + type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed'; + + /** + * A `Query` sorts and filters the data at a Database location so only a subset + * of the child data is included. This can be used to order a collection of + * data by some attribute (for example, height of dinosaurs) as well as to + * restrict a large list of items (for example, chat messages) down to a number + * suitable for synchronizing to the client. Queries are created by chaining + * together one or more of the filter methods defined here. + * + * Just as with a `Reference`, you can receive data from a `Query` by using the + * `on()` method. You will only receive events and `DataSnapshot`s for the + * subset of the data that matches your query. + * + * See + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data + * Sorting and filtering data} for more information. + */ + interface Query { + ref: admin.database.Reference; + + /** + * Creates a `Query` with the specified ending point. + * + * Using `startAt()`, `endAt()`, and `equalTo()` allows you to choose arbitrary + * starting and ending points for your queries. + * + * The ending point is inclusive, so children with exactly the specified value + * will be included in the query. The optional key argument can be used to + * further limit the range of the query. If it is specified, then children that + * have exactly the specified value must also have a key name less than or equal + * to the specified key. + * + * You can read more about `endAt()` in + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @example + * ```javascript + * // Find all dinosaurs whose names come before Pterodactyl lexicographically. + * var ref = admin.database().ref("dinosaurs"); + * ref.orderByKey().endAt("pterodactyl").on("child_added", function(snapshot) { + * console.log(snapshot.key); + * }); + * ``` + * + * @param value The value to end at. The argument + * type depends on which `orderBy*()` function was used in this query. + * Specify a value that matches the `orderBy*()` type. When used in + * combination with `orderByKey()`, the value must be a string. + * @param key The child key to end at, among the children with the + * previously specified priority. This argument is only allowed if ordering by + * priority. + * @return A new `Query` object. + */ + endAt(value: number | string | boolean | null, key?: string): admin.database.Query; + + /** + * Creates a `Query` that includes children that match the specified value. + * + * Using `startAt()`, `endAt()`, and `equalTo()` allows us to choose arbitrary + * starting and ending points for our queries. + * + * The optional key argument can be used to further limit the range of the + * query. If it is specified, then children that have exactly the specified + * value must also have exactly the specified key as their key name. This can be + * used to filter result sets with many matches for the same value. + * + * You can read more about `equalTo()` in + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @example + * // Find all dinosaurs whose height is exactly 25 meters. + * var ref = admin.database().ref("dinosaurs"); + * ref.orderByChild("height").equalTo(25).on("child_added", function(snapshot) { + * console.log(snapshot.key); + * }); + * + * @param value The value to match for. The + * argument type depends on which `orderBy*()` function was used in this + * query. Specify a value that matches the `orderBy*()` type. When used in + * combination with `orderByKey()`, the value must be a string. + * @param key The child key to start at, among the children with the + * previously specified priority. This argument is only allowed if ordering by + * priority. + * @return A new `Query` object. + */ + equalTo(value: number | string | boolean | null, key?: string): admin.database.Query; + + /** + * Returns whether or not the current and provided queries represent the same + * location, have the same query parameters, and are from the same instance of + * `admin.app.App`. + * + * Two `Reference` objects are equivalent if they represent the same location + * and are from the same instance of `admin.app.App`. + * + * Two `Query` objects are equivalent if they represent the same location, have + * the same query parameters, and are from the same instance of `admin.app.App`. + * Equivalent queries share the same sort order, limits, and starting and + * ending points. + * + * @example + * ```javascript + * var rootRef = admin.database().ref(); + * var usersRef = rootRef.child("users"); + * + * usersRef.isEqual(rootRef); // false + * usersRef.isEqual(rootRef.child("users")); // true + * usersRef.parent.isEqual(rootRef); // true + * ``` + * + * @example + * ```javascript + * var rootRef = admin.database().ref(); + * var usersRef = rootRef.child("users"); + * var usersQuery = usersRef.limitToLast(10); + * + * usersQuery.isEqual(usersRef); // false + * usersQuery.isEqual(usersRef.limitToLast(10)); // true + * usersQuery.isEqual(rootRef.limitToLast(10)); // false + * usersQuery.isEqual(usersRef.orderByKey().limitToLast(10)); // false + * ``` + * + * @param other The query to compare against. + * @return Whether or not the current and provided queries are + * equivalent. + */ + isEqual(other: admin.database.Query | null): boolean; + + /** + * Generates a new `Query` limited to the first specific number of children. + * + * The `limitToFirst()` method is used to set a maximum number of children to be + * synced for a given callback. If we set a limit of 100, we will initially only + * receive up to 100 `child_added` events. If we have fewer than 100 messages + * stored in our Database, a `child_added` event will fire for each message. + * However, if we have over 100 messages, we will only receive a `child_added` + * event for the first 100 ordered messages. As items change, we will receive + * `child_removed` events for each item that drops out of the active list so + * that the total number stays at 100. + * + * You can read more about `limitToFirst()` in + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @example + * ```javascript + * // Find the two shortest dinosaurs. + * var ref = admin.database().ref("dinosaurs"); + * ref.orderByChild("height").limitToFirst(2).on("child_added", function(snapshot) { + * // This will be called exactly two times (unless there are less than two + * // dinosaurs in the Database). + * + * // It will also get fired again if one of the first two dinosaurs is + * // removed from the data set, as a new dinosaur will now be the second + * // shortest. + * console.log(snapshot.key); + * }); + * ``` + * + * @param limit The maximum number of nodes to include in this query. + * @return A `Query` object. + */ + limitToFirst(limit: number): admin.database.Query; + + /** + * Generates a new `Query` object limited to the last specific number of + * children. + * + * The `limitToLast()` method is used to set a maximum number of children to be + * synced for a given callback. If we set a limit of 100, we will initially only + * receive up to 100 `child_added` events. If we have fewer than 100 messages + * stored in our Database, a `child_added` event will fire for each message. + * However, if we have over 100 messages, we will only receive a `child_added` + * event for the last 100 ordered messages. As items change, we will receive + * `child_removed` events for each item that drops out of the active list so + * that the total number stays at 100. + * + * You can read more about `limitToLast()` in + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @example + * ```javascript + * // Find the two heaviest dinosaurs. + * var ref = admin.database().ref("dinosaurs"); + * ref.orderByChild("weight").limitToLast(2).on("child_added", function(snapshot) { + * // This callback will be triggered exactly two times, unless there are + * // fewer than two dinosaurs stored in the Database. It will also get fired + * // for every new, heavier dinosaur that gets added to the data set. + * console.log(snapshot.key); + * }); + * ``` + * + * @param limit The maximum number of nodes to include in this query. + * @return A `Query` object. + */ + limitToLast(limit: number): admin.database.Query; + + /** + * Detaches a callback previously attached with `on()`. + * + * Detach a callback previously attached with `on()`. Note that if `on()` was + * called multiple times with the same eventType and callback, the callback + * will be called multiple times for each event, and `off()` must be called + * multiple times to remove the callback. Calling `off()` on a parent listener + * will not automatically remove listeners registered on child nodes, `off()` + * must also be called on any child listeners to remove the callback. + * + * If a callback is not specified, all callbacks for the specified eventType + * will be removed. Similarly, if no eventType or callback is specified, all + * callbacks for the `Reference` will be removed. + * + * @example + * ```javascript + * var onValueChange = function(dataSnapshot) { ... }; + * ref.on('value', onValueChange); + * ref.child('meta-data').on('child_added', onChildAdded); + * // Sometime later... + * ref.off('value', onValueChange); + * + * // You must also call off() for any child listeners on ref + * // to cancel those callbacks + * ref.child('meta-data').off('child_added', onValueAdded); + * ``` + * + * @example + * ```javascript + * // Or you can save a line of code by using an inline function + * // and on()'s return value. + * var onValueChange = ref.on('value', function(dataSnapshot) { ... }); + * // Sometime later... + * ref.off('value', onValueChange); + * ``` + * + * @param eventType One of the following strings: "value", + * "child_added", "child_changed", "child_removed", or "child_moved." + * @param callback The callback function that was passed to `on()`. + * @param context The context that was passed to `on()`. + */ + off( + eventType?: admin.database.EventType, + callback?: (a: admin.database.DataSnapshot, b?: string | null) => any, + context?: Object | null + ): void; + + /** + * Listens for data changes at a particular location. + * + * This is the primary way to read data from a Database. Your callback + * will be triggered for the initial data and again whenever the data changes. + * Use `off( )` to stop receiving updates. See + * {@link https://firebase.google.com/docs/database/web/retrieve-data + * Retrieve Data on the Web} + * for more details. + * + *

value event

+ * + * This event will trigger once with the initial data stored at this location, + * and then trigger again each time the data changes. The `DataSnapshot` passed + * to the callback will be for the location at which `on()` was called. It + * won't trigger until the entire contents has been synchronized. If the + * location has no data, it will be triggered with an empty `DataSnapshot` + * (`val()` will return `null`). + * + *

child_added event

+ * + * This event will be triggered once for each initial child at this location, + * and it will be triggered again every time a new child is added. The + * `DataSnapshot` passed into the callback will reflect the data for the + * relevant child. For ordering purposes, it is passed a second argument which + * is a string containing the key of the previous sibling child by sort order + * (or `null` if it is the first child). + * + *

child_removed event

+ * + * This event will be triggered once every time a child is removed. The + * `DataSnapshot` passed into the callback will be the old data for the child + * that was removed. A child will get removed when either: + * + * - a client explicitly calls `remove()` on that child or one of its ancestors + * - a client calls `set(null)` on that child or one of its ancestors + * - that child has all of its children removed + * - there is a query in effect which now filters out the child (because it's + * sort order changed or the max limit was hit) + * + *

child_changed event

+ * + * This event will be triggered when the data stored in a child (or any of its + * descendants) changes. Note that a single `child_changed` event may represent + * multiple changes to the child. The `DataSnapshot` passed to the callback will + * contain the new child contents. For ordering purposes, the callback is also + * passed a second argument which is a string containing the key of the previous + * sibling child by sort order (or `null` if it is the first child). + * + *

child_moved event

+ * + * This event will be triggered when a child's sort order changes such that its + * position relative to its siblings changes. The `DataSnapshot` passed to the + * callback will be for the data of the child that has moved. It is also passed + * a second argument which is a string containing the key of the previous + * sibling child by sort order (or `null` if it is the first child). + * + * @example + * ```javascript + * // Handle a new value. + * ref.on('value', function(dataSnapshot) { + * ... + * }); + * ``` + * + * @example + * ```javascript + * // Handle a new child. + * ref.on('child_added', function(childSnapshot, prevChildKey) { + * ... + * }); + * ``` + * + * @example + * ```javascript + * // Handle child removal. + * ref.on('child_removed', function(oldChildSnapshot) { + * ... + * }); + * ``` + * + * @example + * ```javascript + * // Handle child data changes. + * ref.on('child_changed', function(childSnapshot, prevChildKey) { + * ... + * }); + * ``` + * + * @example + * ```javascript + * // Handle child ordering changes. + * ref.on('child_moved', function(childSnapshot, prevChildKey) { + * ... + * }); + * ``` + * + * @param eventType One of the following strings: "value", + * "child_added", "child_changed", "child_removed", or "child_moved." + * @param callback A callback that fires when the specified event occurs. The callback is + * passed a DataSnapshot. For ordering purposes, "child_added", + * "child_changed", and "child_moved" will also be passed a string containing + * the key of the previous child, by sort order (or `null` if it is the + * first child). + * @param cancelCallbackOrContext An optional + * callback that will be notified if your event subscription is ever canceled + * because your client does not have permission to read this data (or it had + * permission but has now lost it). This callback will be passed an `Error` + * object indicating why the failure occurred. + * @param context If provided, this object will be used as `this` + * when calling your callback(s). + * @return The provided + * callback function is returned unmodified. This is just for convenience if + * you want to pass an inline function to `on()`, but store the callback + * function for later passing to `off()`. + */ + on( + eventType: admin.database.EventType, + callback: (a: admin.database.DataSnapshot | null, b?: string) => any, + cancelCallbackOrContext?: Object | null, + context?: Object | null + ): (a: admin.database.DataSnapshot | null, b?: string) => any; + + /** + * Listens for exactly one event of the specified event type, and then stops + * listening. + * + * This is equivalent to calling `on()`, and then calling `off()` inside the + * callback function. See `on()` for details on the event types. + * + * @example + * ```javascript + * // Basic usage of .once() to read the data located at ref. + * ref.once('value') + * .then(function(dataSnapshot) { + * // handle read data. + * }); + * ``` + * + * @param eventType One of the following strings: "value", + * "child_added", "child_changed", "child_removed", or "child_moved." + * @param successCallback A callback that fires when the specified event occurs. The callback is + * passed a `DataSnapshot`. For ordering purposes, "child_added", + * "child_changed", and "child_moved" will also be passed a string containing + * the key of the previous child by sort order (or `null` if it is the + * first child). + * @param failureCallbackOrContext An optional + * callback that will be notified if your client does not have permission to + * read the data. This callback will be passed an `Error` object indicating + * why the failure occurred. + * @param context If provided, this object will be used as `this` + * when calling your callback(s). + * @return {!Promise} + */ + once( + eventType: admin.database.EventType, + successCallback?: (a: admin.database.DataSnapshot, b?: string) => any, + failureCallbackOrContext?: Object | null, + context?: Object | null + ): Promise; + + /** + * Generates a new `Query` object ordered by the specified child key. + * + * Queries can only order by one key at a time. Calling `orderByChild()` + * multiple times on the same query is an error. + * + * Firebase queries allow you to order your data by any child key on the fly. + * However, if you know in advance what your indexes will be, you can define + * them via the .indexOn rule in your Security Rules for better performance. See + * the {@link https://firebase.google.com/docs/database/security/indexing-data + * .indexOn} rule for more information. + * + * You can read more about `orderByChild()` in + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sort_data + * Sort data}. + * + * @example + * ```javascript + * var ref = admin.database().ref("dinosaurs"); + * ref.orderByChild("height").on("child_added", function(snapshot) { + * console.log(snapshot.key + " was " + snapshot.val().height + " m tall"); + * }); + * ``` + * + * @param path + * @return A new `Query` object. + */ + orderByChild(path: string): admin.database.Query; + + /** + * Generates a new `Query` object ordered by key. + * + * Sorts the results of a query by their (ascending) key values. + * + * You can read more about `orderByKey()` in + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sort_data + * Sort data}. + * + * @example + * ```javascript + * var ref = admin.database().ref("dinosaurs"); + * ref.orderByKey().on("child_added", function(snapshot) { + * console.log(snapshot.key); + * }); + * ``` + * + * @return A new `Query` object. + */ + orderByKey(): admin.database.Query; + + /** + * Generates a new `Query` object ordered by priority. + * + * Applications need not use priority but can order collections by + * ordinary properties (see + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sort_data + * Sort data} for alternatives to priority. + * + * @return A new `Query` object. + */ + orderByPriority(): admin.database.Query; + + /** + * Generates a new `Query` object ordered by value. + * + * If the children of a query are all scalar values (string, number, or + * boolean), you can order the results by their (ascending) values. + * + * You can read more about `orderByValue()` in + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sort_data + * Sort data}. + * + * @example + * ```javascript + * var scoresRef = admin.database().ref("scores"); + * scoresRef.orderByValue().limitToLast(3).on("value", function(snapshot) { + * snapshot.forEach(function(data) { + * console.log("The " + data.key + " score is " + data.val()); + * }); + * }); + * ``` + * + * @return A new `Query` object. + */ + orderByValue(): admin.database.Query; + + /** + * Creates a `Query` with the specified starting point. + * + * Using `startAt()`, `endAt()`, and `equalTo()` allows you to choose arbitrary + * starting and ending points for your queries. + * + * The starting point is inclusive, so children with exactly the specified value + * will be included in the query. The optional key argument can be used to + * further limit the range of the query. If it is specified, then children that + * have exactly the specified value must also have a key name greater than or + * equal to the specified key. + * + * You can read more about `startAt()` in + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data + * Filtering data}. + * + * @example + * ```javascript + * // Find all dinosaurs that are at least three meters tall. + * var ref = admin.database().ref("dinosaurs"); + * ref.orderByChild("height").startAt(3).on("child_added", function(snapshot) { + * console.log(snapshot.key) + * }); + * ``` + * + * @param value The value to start at. The argument + * type depends on which `orderBy*()` function was used in this query. + * Specify a value that matches the `orderBy*()` type. When used in + * combination with `orderByKey()`, the value must be a string. + * @param key The child key to start at. This argument is allowed if + * ordering by child, value, or priority. + * @return A new `Query` object. + */ + startAt(value: number | string | boolean | null, key?: string): admin.database.Query; + + /** + * @return A JSON-serializable representation of this object. + */ + toJSON(): Object; + + /** + * Gets the absolute URL for this location. + * + * The `toString()` method returns a URL that is ready to be put into a browser, + * curl command, or a `admin.database().refFromURL()` call. Since all of those + * expect the URL to be url-encoded, `toString()` returns an encoded URL. + * + * Append '.json' to the returned URL when typed into a browser to download + * JSON-formatted data. If the location is secured (that is, not publicly + * readable), you will get a permission-denied error. + * + * @example + * ```javascript + * // Calling toString() on a root Firebase reference returns the URL where its + * // data is stored within the Database: + * var rootRef = admin.database().ref(); + * var rootUrl = rootRef.toString(); + * // rootUrl === "https://sample-app.firebaseio.com/". + * + * // Calling toString() at a deeper Firebase reference returns the URL of that + * // deep path within the Database: + * var adaRef = rootRef.child('users/ada'); + * var adaURL = adaRef.toString(); + * // adaURL === "https://sample-app.firebaseio.com/users/ada". + * ``` + * + * @return The absolute URL for this location. + * @override + */ + toString(): string; + } + + /** + * A `Reference` represents a specific location in your Database and can be used + * for reading or writing data to that Database location. + * + * You can reference the root or child location in your Database by calling + * `admin.database().ref()` or `admin.database().ref("child/path")`. + * + * Writing is done with the `set()` method and reading can be done with the + * `on()` method. See + * {@link + * https://firebase.google.com/docs/database/web/read-and-write + * Read and Write Data on the Web} + */ + interface Reference extends admin.database.Query { + + /** + * The last part of the `Reference`'s path. + * + * For example, `"ada"` is the key for + * `https://.firebaseio.com/users/ada`. + * + * The key of a root `Reference` is `null`. + * + * @example + * ```javascript + * // The key of a root reference is null + * var rootRef = admin.database().ref(); + * var key = rootRef.key; // key === null + * ``` + * + * @example + * ```javascript + * // The key of any non-root reference is the last token in the path + * var adaRef = admin.database().ref("users/ada"); + * var key = adaRef.key; // key === "ada" + * key = adaRef.child("name/last").key; // key === "last" + * ``` + */ + key: string | null; + + /** + * The parent location of a `Reference`. + * + * The parent of a root `Reference` is `null`. + * + * @example + * ```javascript + * // The parent of a root reference is null + * var rootRef = admin.database().ref(); + * parent = rootRef.parent; // parent === null + * ``` + * + * @example + * ```javascript + * // The parent of any non-root reference is the parent location + * var usersRef = admin.database().ref("users"); + * var adaRef = admin.database().ref("users/ada"); + * // usersRef and adaRef.parent represent the same location + * ``` + */ + parent: admin.database.Reference | null; + + /** + * The root `Reference` of the Database. + * + * @example + * ```javascript + * // The root of a root reference is itself + * var rootRef = admin.database().ref(); + * // rootRef and rootRef.root represent the same location + * ``` + * + * @example + * ```javascript + * // The root of any non-root reference is the root location + * var adaRef = admin.database().ref("users/ada"); + * // rootRef and adaRef.root represent the same location + * ``` + */ + root: admin.database.Reference; + path: string; + + /** + * Gets a `Reference` for the location at the specified relative path. + * + * The relative path can either be a simple child name (for example, "ada") or + * a deeper slash-separated path (for example, "ada/name/first"). + * + * @example + * ```javascript + * var usersRef = admin.database().ref('users'); + * var adaRef = usersRef.child('ada'); + * var adaFirstNameRef = adaRef.child('name/first'); + * var path = adaFirstNameRef.toString(); + * // path is now 'https://sample-app.firebaseio.com/users/ada/name/first' + * ``` + * + * @param path A relative path from this location to the desired child + * location. + * @return The specified child location. + */ + child(path: string): admin.database.Reference; + + /** + * Returns an `OnDisconnect` object - see + * {@link + * https://firebase.google.com/docs/database/web/offline-capabilities + * Enabling Offline Capabilities in JavaScript} for more information on how + * to use it. + * + * @return An `OnDisconnect` object . + */ + onDisconnect(): admin.database.OnDisconnect; + + /** + * Generates a new child location using a unique key and returns its + * `Reference`. + * + * This is the most common pattern for adding data to a collection of items. + * + * If you provide a value to `push()`, the value will be written to the + * generated location. If you don't pass a value, nothing will be written to the + * Database and the child will remain empty (but you can use the `Reference` + * elsewhere). + * + * The unique key generated by `push()` are ordered by the current time, so the + * resulting list of items will be chronologically sorted. The keys are also + * designed to be unguessable (they contain 72 random bits of entropy). + * + * + * See + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data + * Append to a list of data} + *
See + * {@link + * https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html + * The 2^120 Ways to Ensure Unique Identifiers} + * + * @example + * ```javascript + * var messageListRef = admin.database().ref('message_list'); + * var newMessageRef = messageListRef.push(); + * newMessageRef.set({ + * user_id: 'ada', + * text: 'The Analytical Engine weaves algebraical patterns just as the Jacquard loom weaves flowers and leaves.' + * }); + * // We've appended a new message to the message_list location. + * var path = newMessageRef.toString(); + * // path will be something like + * // 'https://sample-app.firebaseio.com/message_list/-IKo28nwJLH0Nc5XeFmj' + * ``` + * + * @param value Optional value to be written at the generated location. + * @param onComplete Callback called when write to server is + * complete. + * @return Combined `Promise` and + * `Reference`; resolves when write is complete, but can be used immediately + * as the `Reference` to the child location. + */ + push(value?: any, onComplete?: (a: Error | null) => any): admin.database.ThenableReference; + + /** + * Removes the data at this Database location. + * + * Any data at child locations will also be deleted. + * + * The effect of the remove will be visible immediately and the corresponding + * event 'value' will be triggered. Synchronization of the remove to the + * Firebase servers will also be started, and the returned Promise will resolve + * when complete. If provided, the onComplete callback will be called + * asynchronously after synchronization has finished. + * + * @example + * ```javascript + * var adaRef = admin.database().ref('users/ada'); + * adaRef.remove() + * .then(function() { + * console.log("Remove succeeded.") + * }) + * .catch(function(error) { + * console.log("Remove failed: " + error.message) + * }); + * ``` + * + * @param onComplete Callback called when write to server is + * complete. + * @return Resolves when remove on server is complete. + */ + remove(onComplete?: (a: Error | null) => any): Promise; + + /** + * Writes data to this Database location. + * + * This will overwrite any data at this location and all child locations. + * + * The effect of the write will be visible immediately, and the corresponding + * events ("value", "child_added", etc.) will be triggered. Synchronization of + * the data to the Firebase servers will also be started, and the returned + * Promise will resolve when complete. If provided, the `onComplete` callback + * will be called asynchronously after synchronization has finished. + * + * Passing `null` for the new value is equivalent to calling `remove()`; namely, + * all data at this location and all child locations will be deleted. + * + * `set()` will remove any priority stored at this location, so if priority is + * meant to be preserved, you need to use `setWithPriority()` instead. + * + * Note that modifying data with `set()` will cancel any pending transactions + * at that location, so extreme care should be taken if mixing `set()` and + * `transaction()` to modify the same data. + * + * A single `set()` will generate a single "value" event at the location where + * the `set()` was performed. + * + * @example + * ```javascript + * var adaNameRef = admin.database().ref('users/ada/name'); + * adaNameRef.child('first').set('Ada'); + * adaNameRef.child('last').set('Lovelace'); + * // We've written 'Ada' to the Database location storing Ada's first name, + * // and 'Lovelace' to the location storing her last name. + * ``` + * + * @example + * ```javascript + * adaNameRef.set({ first: 'Ada', last: 'Lovelace' }); + * // Exact same effect as the previous example, except we've written + * // Ada's first and last name simultaneously. + * ``` + * + * @example + * ```javascript + * adaNameRef.set({ first: 'Ada', last: 'Lovelace' }) + * .then(function() { + * console.log('Synchronization succeeded'); + * }) + * .catch(function(error) { + * console.log('Synchronization failed'); + * }); + * // Same as the previous example, except we will also log a message + * // when the data has finished synchronizing. + * ``` + * + * @param value The value to be written (string, number, boolean, object, + * array, or null). + * @param onComplete Callback called when write to server is + * complete. + * @return Resolves when write to server is complete. + */ + set(value: any, onComplete?: (a: Error | null) => any): Promise; + + /** + * Sets a priority for the data at this Database location. + * + * Applications need not use priority but can order collections by + * ordinary properties (see + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data + * Sorting and filtering data}). + * + * @param priority + * @param onComplete + * @return + */ + setPriority( + priority: string | number | null, + onComplete: (a: Error | null) => any + ): Promise; + + /** + * Writes data the Database location. Like `set()` but also specifies the + * priority for that data. + * + * Applications need not use priority but can order collections by + * ordinary properties (see + * {@link + * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data + * Sorting and filtering data}). + * + * @param newVal + * @param newPriority + * @param onComplete + * @return + */ + setWithPriority( + newVal: any, newPriority: string | number | null, + onComplete?: (a: Error | null) => any + ): Promise; + + /** + * Atomically modifies the data at this location. + * + * Atomically modify the data at this location. Unlike a normal `set()`, which + * just overwrites the data regardless of its previous value, `transaction()` is + * used to modify the existing value to a new value, ensuring there are no + * conflicts with other clients writing to the same location at the same time. + * + * To accomplish this, you pass `transaction()` an update function which is used + * to transform the current value into a new value. If another client writes to + * the location before your new value is successfully written, your update + * function will be called again with the new current value, and the write will + * be retried. This will happen repeatedly until your write succeeds without + * conflict or you abort the transaction by not returning a value from your + * update function. + * + * Note: Modifying data with `set()` will cancel any pending transactions at + * that location, so extreme care should be taken if mixing `set()` and + * `transaction()` to update the same data. + * + * Note: When using transactions with Security and Firebase Rules in place, be + * aware that a client needs `.read` access in addition to `.write` access in + * order to perform a transaction. This is because the client-side nature of + * transactions requires the client to read the data in order to transactionally + * update it. + * + * @example + * ```javascript + * // Increment Ada's rank by 1. + * var adaRankRef = admin.database().ref('users/ada/rank'); + * adaRankRef.transaction(function(currentRank) { + * // If users/ada/rank has never been set, currentRank will be `null`. + * return currentRank + 1; + * }); + * ``` + * + * @example + * ```javascript + * // Try to create a user for ada, but only if the user id 'ada' isn't + * // already taken + * var adaRef = admin.database().ref('users/ada'); + * adaRef.transaction(function(currentData) { + * if (currentData === null) { + * return { name: { first: 'Ada', last: 'Lovelace' } }; + * } else { + * console.log('User ada already exists.'); + * return; // Abort the transaction. + * } + * }, function(error, committed, snapshot) { + * if (error) { + * console.log('Transaction failed abnormally!', error); + * } else if (!committed) { + * console.log('We aborted the transaction (because ada already exists).'); + * } else { + * console.log('User ada added!'); + * } + * console.log("Ada's data: ", snapshot.val()); + * }); + * ``` + * + * @param transactionUpdate A developer-supplied function which + * will be passed the current data stored at this location (as a JavaScript + * object). The function should return the new value it would like written (as + * a JavaScript object). If `undefined` is returned (i.e. you return with no + * arguments) the transaction will be aborted and the data at this location + * will not be modified. + * @param onComplete A callback + * function that will be called when the transaction completes. The callback + * is passed three arguments: a possibly-null `Error`, a `boolean` indicating + * whether the transaction was committed, and a `DataSnapshot` indicating the + * final result. If the transaction failed abnormally, the first argument will + * be an `Error` object indicating the failure cause. If the transaction + * finished normally, but no data was committed because no data was returned + * from `transactionUpdate`, then second argument will be false. If the + * transaction completed and committed data to Firebase, the second argument + * will be true. Regardless, the third argument will be a `DataSnapshot` + * containing the resulting data in this location. + * @param applyLocally By default, events are raised each time the + * transaction update function runs. So if it is run multiple times, you may + * see intermediate states. You can set this to false to suppress these + * intermediate states and instead wait until the transaction has completed + * before events are raised. + * @return Returns a Promise that can optionally be used instead of the `onComplete` + * callback to handle success and failure. + */ + transaction( + transactionUpdate: (a: any) => any, + onComplete?: (a: Error | null, b: boolean, c: admin.database.DataSnapshot | null) => any, + applyLocally?: boolean + ): Promise<{ + committed: boolean, + snapshot: admin.database.DataSnapshot | null + }>; + + /** + * Writes multiple values to the Database at once. + * + * The `values` argument contains multiple property-value pairs that will be + * written to the Database together. Each child property can either be a simple + * property (for example, "name") or a relative path (for example, + * "name/first") from the current location to the data to update. + * + * As opposed to the `set()` method, `update()` can be use to selectively update + * only the referenced properties at the current location (instead of replacing + * all the child properties at the current location). + * + * The effect of the write will be visible immediately, and the corresponding + * events ('value', 'child_added', etc.) will be triggered. Synchronization of + * the data to the Firebase servers will also be started, and the returned + * Promise will resolve when complete. If provided, the `onComplete` callback + * will be called asynchronously after synchronization has finished. + * + * A single `update()` will generate a single "value" event at the location + * where the `update()` was performed, regardless of how many children were + * modified. + * + * Note that modifying data with `update()` will cancel any pending + * transactions at that location, so extreme care should be taken if mixing + * `update()` and `transaction()` to modify the same data. + * + * Passing `null` to `update()` will remove the data at this location. + * + * See + * {@link + * https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html + * Introducing multi-location updates and more}. + * + * @example + * ```javascript + * var adaNameRef = admin.database().ref('users/ada/name'); + * // Modify the 'first' and 'last' properties, but leave other data at + * // adaNameRef unchanged. + * adaNameRef.update({ first: 'Ada', last: 'Lovelace' }); + * ``` + * + * @param values Object containing multiple values. + * @param onComplete Callback called when write to server is + * complete. + * @return Resolves when update on server is complete. + */ + update(values: Object, onComplete?: (a: Error | null) => any): Promise; + } + + /** + * @extends {Reference} + */ + interface ThenableReference extends admin.database.Reference, Promise { } + + function enableLogging(logger?: boolean | ((message: string) => any), persistent?: boolean): any; +} + +export namespace admin.database.ServerValue { + var TIMESTAMP: number; +} diff --git a/src/index.d.ts b/src/index.d.ts index 5bce24b49b..a16d704b50 100755 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -18,6 +18,13 @@ import { Bucket } from '@google-cloud/storage'; import * as _firestore from '@google-cloud/firestore'; import { Agent } from 'http'; +import * as _auth from './auth'; +import * as _database from './database'; +import * as _messaging from './messaging'; +import * as _instanceId from './instance-id'; +import * as _projectManagement from './project-management'; +import * as _securityRules from './security-rules'; + /** * `admin` is a global namespace from which all Firebase Admin * services are accessed. @@ -449,7 +456,7 @@ declare namespace admin.app { auth(): admin.auth.Auth; - database(url?: string): admin.database.Database; + database(url?: string): _database.admin.database.Database; firestore(): admin.firestore.Firestore; instanceId(): admin.instanceId.InstanceId; messaging(): admin.messaging.Messaging; @@ -479,5322 +486,295 @@ declare namespace admin.app { } declare namespace admin.auth { + export import UserMetadata = _auth.admin.auth.UserMetadata; + export import UserInfo = _auth.admin.auth.UserInfo; + export import UserRecord = _auth.admin.auth.UserRecord; + export import UpdateRequest = _auth.admin.auth.UpdateRequest; + export import CreateRequest = _auth.admin.auth.CreateRequest; + export import DecodedIdToken = _auth.admin.auth.DecodedIdToken; + export import ListUsersResult = _auth.admin.auth.ListUsersResult; + export import HashAlgorithmType = _auth.admin.auth.HashAlgorithmType; + export import UserImportOptions = _auth.admin.auth.UserImportOptions; + export import UserImportResult = _auth.admin.auth.UserImportResult; + export import UserImportRecord = _auth.admin.auth.UserImportRecord; + export import SessionCookieOptions = _auth.admin.auth.SessionCookieOptions; + export import ActionCodeSettings = _auth.admin.auth.ActionCodeSettings; + export import Tenant = _auth.admin.auth.Tenant; + export import UpdateTenantRequest = _auth.admin.auth.UpdateTenantRequest; + export import CreateTenantRequest = _auth.admin.auth.CreateTenantRequest; + export import ListTenantsResult = _auth.admin.auth.ListTenantsResult; + export import AuthProviderConfigFilter = _auth.admin.auth.AuthProviderConfigFilter; + export import AuthProviderConfig = _auth.admin.auth.AuthProviderConfig; + export import SAMLAuthProviderConfig = _auth.admin.auth.SAMLAuthProviderConfig; + export import OIDCAuthProviderConfig = _auth.admin.auth.OIDCAuthProviderConfig; + export import SAMLUpdateAuthProviderRequest = _auth.admin.auth.SAMLUpdateAuthProviderRequest; + export import OIDCUpdateAuthProviderRequest = _auth.admin.auth.OIDCUpdateAuthProviderRequest; + export import ListProviderConfigResults = _auth.admin.auth.ListProviderConfigResults; + export import UpdateAuthProviderRequest = _auth.admin.auth.UpdateAuthProviderRequest; + export import BaseAuth = _auth.admin.auth.BaseAuth; + export import TenantAwareAuth = _auth.admin.auth.TenantAwareAuth; + export import Auth = _auth.admin.auth.Auth; + export import TenantManager = _auth.admin.auth.TenantManager; +} - /** - * Interface representing a user's metadata. - */ - interface UserMetadata { +declare namespace admin.credential { - /** - * The date the user last signed in, formatted as a UTC string. - */ - lastSignInTime: string; + /** + * 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 admin.credential `admin.credential`}. + */ + interface Credential { /** - * The date the user was created, formatted as a UTC string. + * Returns a Google OAuth2 access token object used to authenticate with + * Firebase services. * + * This object contains the following properties: + * * `access_token` (`string`): The actual Google OAuth2 access token. + * * `expires_in` (`number`): The number of seconds from when the token was + * issued that it expires. + * + * @return A Google OAuth2 access token object. */ - creationTime: string; - - /** - * @return A JSON-serializable representation of this object. - */ - toJSON(): Object; + getAccessToken(): Promise; } + /** - * Interface representing a user's info from a third-party identity provider - * such as Google or Facebook. + * 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 + * admin.initializeApp({ + * credential: admin.credential.applicationDefault(), + * databaseURL: "https://.firebaseio.com" + * }); + * ``` + * + * @param {!Object=} 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 {!admin.credential.Credential} A credential authenticated via Google + * Application Default Credentials that can be used to initialize an app. */ - interface UserInfo { - - /** - * The user identifier for the linked provider. - */ - uid: string; - - /** - * The display name for the linked provider. - */ - displayName: string; - - /** - * The email for the linked provider. - */ - email: string; - - /** - * The phone number for the linked provider. - */ - phoneNumber: string; - - /** - * The photo URL for the linked provider. - */ - photoURL: string; - - /** - * The linked provider ID (for example, "google.com" for the Google provider). - */ - providerId: string; - - /** - * @return A JSON-serializable representation of this object. - */ - toJSON(): Object; - } + function applicationDefault(httpAgent?: Agent): admin.credential.Credential; /** - * Interface representing a user. + * 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 + * var serviceAccount = require("path/to/serviceAccountKey.json"); + * admin.initializeApp({ + * credential: admin.credential.cert(serviceAccount), + * databaseURL: "https://.firebaseio.com" + * }); + * ``` + * + * @example + * ```javascript + * // Providing a service account object inline + * admin.initializeApp({ + * credential: admin.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. */ - interface UserRecord { - - /** - * The user's `uid`. - */ - uid: string; - - /** - * The user's primary email, if set. - */ - email?: string; - - /** - * Whether or not the user's primary email is verified. - */ - emailVerified: boolean; - - /** - * The user's display name. - */ - displayName?: string; - - /** - * The user's primary phone number, if set. - */ - phoneNumber?: string; - - /** - * The user's photo URL. - */ - photoURL?: string; - - /** - * Whether or not the user is disabled: `true` for disabled; `false` for - * enabled. - */ - disabled: boolean; - - /** - * Additional metadata about the user. - */ - metadata: admin.auth.UserMetadata; - - /** - * An array of providers (for example, Google, Facebook) linked to the user. - */ - providerData: admin.auth.UserInfo[]; + function cert(serviceAccountPathOrObject: string | admin.ServiceAccount, httpAgent?: Agent): admin.credential.Credential; - /** - * The user's hashed password (base64-encoded), only if Firebase Auth hashing - * algorithm (SCRYPT) is used. If a different hashing algorithm had been used - * when uploading this user, as is typical when migrating from another Auth - * system, this will be an empty string. If no password is set, this is - * null. This is only available when the user is obtained from - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listUsers `listUsers()`}. - * - */ - passwordHash?: string; + /** + * 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 + * var refreshToken = require("path/to/refreshToken.json"); + * admin.initializeApp({ + * credential: admin.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. + */ + function refreshToken(refreshTokenPathOrObject: string | Object, httpAgent?: Agent): admin.credential.Credential; +} - /** - * The user's password salt (base64-encoded), only if Firebase Auth hashing - * algorithm (SCRYPT) is used. If a different hashing algorithm had been used to - * upload this user, typical when migrating from another Auth system, this will - * be an empty string. If no password is set, this is null. This is only - * available when the user is obtained from - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listUsers `listUsers()`}. - * - */ - passwordSalt?: string; +declare namespace admin.database { + export import Database = _database.admin.database.Database; + export import DataSnapshot = _database.admin.database.DataSnapshot; + export import OnDisconnect = _database.admin.database.OnDisconnect; + export import EventType = _database.admin.database.EventType; + export import Query = _database.admin.database.Query; + export import Reference = _database.admin.database.Reference; + export import ThenableReference = _database.admin.database.ThenableReference; + export import enableLogging = _database.admin.database.enableLogging; + export import ServerValue = _database.admin.database.ServerValue; +} - /** - * The user's custom claims object if available, typically used to define - * user roles and propagated to an authenticated user's ID token. - * This is set via - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#setCustomUserClaims `setCustomUserClaims()`} - */ - customClaims?: Object; +declare namespace admin.messaging { + export import Message = _messaging.admin.messaging.Message; + export import MulticastMessage = _messaging.admin.messaging.MulticastMessage; + export import AndroidConfig = _messaging.admin.messaging.AndroidConfig; + export import AndroidNotification = _messaging.admin.messaging.AndroidNotification; + export import LightSettings = _messaging.admin.messaging.LightSettings; + export import AndroidFcmOptions = _messaging.admin.messaging.AndroidFcmOptions; + export import ApnsConfig = _messaging.admin.messaging.ApnsConfig; + export import ApnsPayload = _messaging.admin.messaging.ApnsPayload; + export import Aps = _messaging.admin.messaging.Aps; + export import ApsAlert = _messaging.admin.messaging.ApsAlert; + export import CriticalSound = _messaging.admin.messaging.CriticalSound; + export import ApnsFcmOptions = _messaging.admin.messaging.ApnsFcmOptions; + export import FcmOptions = _messaging.admin.messaging.FcmOptions; + export import Notification = _messaging.admin.messaging.Notification; + export import WebpushConfig = _messaging.admin.messaging.WebpushConfig; + export import WebpushFcmOptions = _messaging.admin.messaging.WebpushFcmOptions; + export import WebpushNotification = _messaging.admin.messaging.WebpushNotification; + export import MessagingTopicManagementResponse = _messaging.admin.messaging.MessagingTopicManagementResponse; + export import BatchResponse = _messaging.admin.messaging.BatchResponse; + export import SendResponse = _messaging.admin.messaging.SendResponse; + export import Messaging = _messaging.admin.messaging.Messaging; + + // Legacy API types. + export import DataMessagePayload = _messaging.admin.messaging.DataMessagePayload; + export import NotificationMessagePayload = _messaging.admin.messaging.NotificationMessagePayload; + export import MessagingPayload = _messaging.admin.messaging.MessagingPayload; + export import MessagingOptions = _messaging.admin.messaging.MessagingOptions; + export import MessagingDevicesResponse = _messaging.admin.messaging.MessagingDevicesResponse; + export import MessagingDeviceResult = _messaging.admin.messaging.MessagingDeviceResult; + export import MessagingDeviceGroupResponse = _messaging.admin.messaging.MessagingDeviceGroupResponse; + export import MessagingTopicResponse = _messaging.admin.messaging.MessagingTopicResponse; + export import MessagingConditionResponse = _messaging.admin.messaging.MessagingConditionResponse; +} - /** - * The date the user's tokens are valid after, formatted as a UTC string. - * This is updated every time the user's refresh token are revoked either - * from the {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#revokeRefreshTokens `revokeRefreshTokens()`} - * API or from the Firebase Auth backend on big account changes (password - * resets, password or email updates, etc). - */ - tokensValidAfterTime?: string; +declare namespace admin.storage { + /** + * The default `Storage` service if no + * app is provided or the `Storage` service associated with the provided + * app. + */ + interface Storage { /** - * The ID of the tenant the user belongs to, if available. + * Optional app whose `Storage` service to + * return. If not provided, the default `Storage` service will be returned. */ - tenantId?: string | null; - + app: admin.app.App; /** - * @return A JSON-serializable representation of this object. + * @returns A [Bucket](https://cloud.google.com/nodejs/docs/reference/storage/latest/Bucket) + * instance as defined in the `@google-cloud/storage` package. */ - toJSON(): Object; + bucket(name?: string): Bucket; } +} - /** - * Interface representing the properties to update on the provided user. - */ - interface UpdateRequest { +declare namespace admin.firestore { + export import v1beta1 = _firestore.v1beta1; + export import v1 = _firestore.v1; - /** - * Whether or not the user is disabled: `true` for disabled; - * `false` for enabled. - */ - disabled?: boolean; + export import CollectionReference = _firestore.CollectionReference; + export import DocumentData = _firestore.DocumentData; + export import DocumentReference = _firestore.DocumentReference; + export import DocumentSnapshot = _firestore.DocumentSnapshot; + export import FieldPath = _firestore.FieldPath; + export import FieldValue = _firestore.FieldValue; + export import Firestore = _firestore.Firestore; + export import GeoPoint = _firestore.GeoPoint; + export import Query = _firestore.Query; + export import QueryDocumentSnapshot = _firestore.QueryDocumentSnapshot; + export import QuerySnapshot = _firestore.QuerySnapshot; + export import Timestamp = _firestore.Timestamp; + export import Transaction = _firestore.Transaction; + export import WriteBatch = _firestore.WriteBatch; + export import WriteResult = _firestore.WriteResult; - /** - * The user's display name. - */ - displayName?: string | null; + export import setLogFunction = _firestore.setLogFunction; +} - /** - * The user's primary email. - */ - email?: string; +declare namespace admin.instanceId { + export import InstanceId = _instanceId.admin.instanceId.InstanceId; +} - /** - * Whether or not the user's primary email is verified. - */ - emailVerified?: boolean; - - /** - * The user's unhashed password. - */ - password?: string; - - /** - * The user's primary phone number. - */ - phoneNumber?: string | null; - - /** - * The user's photo URL. - */ - photoURL?: string | null; - } - - /** - * Interface representing the properties to set on a new user record to be - * created. - */ - interface CreateRequest extends UpdateRequest { - - /** - * The user's `uid`. - */ - uid?: string; - } - - /** - * Interface representing a decoded Firebase ID token, returned from the - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#verifyIdToken `verifyIdToken()`} method. - * - * Firebase ID tokens are OpenID Connect spec-compliant JSON Web Tokens (JWTs). - * See the - * [ID Token section of the OpenID Connect spec](http://openid.net/specs/openid-connect-core-1_0.html#IDToken) - * for more information about the specific properties below. - */ - interface DecodedIdToken { - - /** - * The audience for which this token is intended. - * - * This value is a string equal to your Firebase project ID, the unique - * identifier for your Firebase project, which can be found in [your project's - * settings](https://console.firebase.google.com/project/_/settings/general/android:com.random.android). - */ - aud: string; - - /** - * Time, in seconds since the Unix epoch, when the end-user authentication - * occurred. - * - * This value is not set when this particular ID token was created, but when the - * user initially logged in to this session. In a single session, the Firebase - * SDKs will refresh a user's ID tokens every hour. Each ID token will have a - * different [`iat`](#iat) value, but the same `auth_time` value. - */ - auth_time: number; - - /** - * The ID token's expiration time, in seconds since the Unix epoch. That is, the - * time at which this ID token expires and should no longer be considered valid. - * - * The Firebase SDKs transparently refresh ID tokens every hour, issuing a new - * ID token with up to a one hour expiration. - */ - exp: number; - - /** - * Information about the sign in event, including which sign in provider was - * used and provider-specific identity details. - * - * This data is provided by the Firebase Authentication service and is a - * reserved claim in the ID token. - */ - firebase: { - - /** - * Provider-specific identity details corresponding - * to the provider used to sign in the user. - */ - identities: { - [key: string]: any; - }; - - /** - * The ID of the provider used to sign in the user. - * One of `"anonymous"`, `"password"`, `"facebook.com"`, `"github.com"`, - * `"google.com"`, `"twitter.com"`, or `"custom"`. - */ - sign_in_provider: string; - - /** - * The ID of the tenant the user belongs to, if available. - */ - tenant?: string; - [key: string]: any; - }; - - /** - * The ID token's issued-at time, in seconds since the Unix epoch. That is, the - * time at which this ID token was issued and should start to be considered - * valid. - * - * The Firebase SDKs transparently refresh ID tokens every hour, issuing a new - * ID token with a new issued-at time. If you want to get the time at which the - * user session corresponding to the ID token initially occurred, see the - * [`auth_time`](#auth_time) property. - */ - iat: number; - - /** - * The issuer identifier for the issuer of the response. - * - * This value is a URL with the format - * `https://securetoken.google.com/`, where `` is the - * same project ID specified in the [`aud`](#aud) property. - */ - iss: string; - - /** - * The `uid` corresponding to the user who the ID token belonged to. - * - * As a convenience, this value is copied over to the [`uid`](#uid) property. - */ - sub: string; - - /** - * The `uid` corresponding to the user who the ID token belonged to. - * - * This value is not actually in the JWT token claims itself. It is added as a - * convenience, and is set as the value of the [`sub`](#sub) property. - */ - uid: string; - [key: string]: any; - } - - /** - * Interface representing the object returned from a - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listUsers `listUsers()`} operation. Contains the list - * of users for the current batch and the next page token if available. - */ - interface ListUsersResult { - - /** - * The list of {@link admin.auth.UserRecord `UserRecord`} objects for the - * current downloaded batch. - */ - users: admin.auth.UserRecord[]; - - /** - * The next page token if available. This is needed for the next batch download. - */ - pageToken?: string; - } - - type HashAlgorithmType = 'SCRYPT' | 'STANDARD_SCRYPT' | 'HMAC_SHA512' | - 'HMAC_SHA256' | 'HMAC_SHA1' | 'HMAC_MD5' | 'MD5' | 'PBKDF_SHA1' | 'BCRYPT' | - 'PBKDF2_SHA256' | 'SHA512' | 'SHA256' | 'SHA1'; - - /** - * Interface representing the user import options needed for - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#importUsers `importUsers()`} method. This is used to - * provide the password hashing algorithm information. - */ - interface UserImportOptions { - - /** - * The password hashing information. - */ - hash: { - - /** - * The password hashing algorithm identifier. The following algorithm - * identifiers are supported: - * `SCRYPT`, `STANDARD_SCRYPT`, `HMAC_SHA512`, `HMAC_SHA256`, `HMAC_SHA1`, - * `HMAC_MD5`, `MD5`, `PBKDF_SHA1`, `BCRYPT`, `PBKDF2_SHA256`, `SHA512`, - * `SHA256` and `SHA1`. - */ - algorithm: HashAlgorithmType; - - /** - * The signing key used in the hash algorithm in buffer bytes. - * Required by hashing algorithms `SCRYPT`, `HMAC_SHA512`, `HMAC_SHA256`, - * `HAMC_SHA1` and `HMAC_MD5`. - */ - key?: Buffer; - - /** - * The salt separator in buffer bytes which is appended to salt when - * verifying a password. This is only used by the `SCRYPT` algorithm. - */ - saltSeparator?: Buffer; - - /** - * The number of rounds for hashing calculation. - * Required for `SCRYPT`, `MD5`, `SHA512`, `SHA256`, `SHA1`, `PBKDF_SHA1` and - * `PBKDF2_SHA256`. - */ - rounds?: number; - - /** - * The memory cost required for `SCRYPT` algorithm, or the CPU/memory cost. - * Required for `STANDARD_SCRYPT` algorithm. - */ - memoryCost?: number; - - /** - * The parallelization of the hashing algorithm. Required for the - * `STANDARD_SCRYPT` algorithm. - */ - parallelization?: number; - - /** - * The block size (normally 8) of the hashing algorithm. Required for the - * `STANDARD_SCRYPT` algorithm. - */ - blockSize?: number; - /** - * The derived key length of the hashing algorithm. Required for the - * `STANDARD_SCRYPT` algorithm. - */ - derivedKeyLength?: number; - }; - } - - /** - * Interface representing the response from the - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#importUsers `importUsers()`} method for batch - * importing users to Firebase Auth. - */ - interface UserImportResult { - - /** - * The number of user records that failed to import to Firebase Auth. - */ - failureCount: number; - - /** - * The number of user records that successfully imported to Firebase Auth. - */ - successCount: number; - - /** - * An array of errors corresponding to the provided users to import. The - * length of this array is equal to [`failureCount`](#failureCount). - */ - errors: admin.FirebaseArrayIndexError[]; - } - - /** - * Interface representing a user to import to Firebase Auth via the - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#importUsers `importUsers()`} method. - */ - interface UserImportRecord { - - /** - * The user's `uid`. - */ - uid: string; - - /** - * The user's primary email, if set. - */ - email?: string; - - /** - * Whether or not the user's primary email is verified. - */ - emailVerified: boolean; - - /** - * The user's display name. - */ - displayName?: string; - - /** - * The user's primary phone number, if set. - */ - phoneNumber?: string; - - /** - * The user's photo URL. - */ - photoURL?: string; - - /** - * Whether or not the user is disabled: `true` for disabled; `false` for - * enabled. - */ - disabled: boolean; - - /** - * Additional metadata about the user. - */ - metadata: admin.auth.UserMetadata; - - /** - * An array of providers (for example, Google, Facebook) linked to the user. - */ - providerData?: admin.auth.UserInfo[]; - - /** - * The user's custom claims object if available, typically used to define - * user roles and propagated to an authenticated user's ID token. - */ - customClaims?: Object; - - /** - * The buffer of bytes representing the user's hashed password. - * When a user is to be imported with a password hash, - * {@link admin.auth.UserImportOptions `UserImportOptions`} are required to be - * specified to identify the hashing algorithm used to generate this hash. - */ - passwordHash?: Buffer; - - /** - * The buffer of bytes representing the user's password salt. - */ - passwordSalt?: Buffer; - - /** - * The identifier of the tenant where user is to be imported to. - * When not provided in an `admin.auth.Auth` context, the user is uploaded to - * the default parent project. - * When not provided in an `admin.auth.TenantAwareAuth` context, the user is uploaded - * to the tenant corresponding to that `TenantAwareAuth` instance's tenant ID. - */ - tenantId?: string | null; - } - - /** - * Interface representing the session cookie options needed for the - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createSessionCookie `createSessionCookie()`} method. - */ - interface SessionCookieOptions { - - /** - * The session cookie custom expiration in milliseconds. The minimum allowed is - * 5 minutes and the maxium allowed is 2 weeks. - */ - expiresIn: number; - } - - /** - * This is the interface that defines the required continue/state URL with - * optional Android and iOS bundle identifiers. - */ - interface ActionCodeSettings { - - /** - * Defines the link continue/state URL, which has different meanings in - * different contexts: - *
    - *
  • When the link is handled in the web action widgets, this is the deep - * link in the `continueUrl` query parameter.
    • - *
  • When the link is handled in the app directly, this is the `continueUrl` - * query parameter in the deep link of the Dynamic Link.
    • - *
- */ - url: string; - - /** - * Whether to open the link via a mobile app or a browser. - * The default is false. When set to true, the action code link is sent - * as a Universal Link or Android App Link and is opened by the app if - * installed. In the false case, the code is sent to the web widget first - * and then redirects to the app if installed. - */ - handleCodeInApp?: boolean; - - /** - * Defines the iOS bundle ID. This will try to open the link in an iOS app if it - * is installed. - */ - iOS?: { - - /** - * Defines the required iOS bundle ID of the app where the link should be - * handled if the application is already installed on the device. - */ - bundleId: string; - }; - - /** - * Defines the Android package name. This will try to open the link in an - * android app if it is installed. If `installApp` is passed, it specifies - * whether to install the Android app if the device supports it and the app is - * not already installed. If this field is provided without a `packageName`, an - * error is thrown explaining that the `packageName` must be provided in - * conjunction with this field. If `minimumVersion` is specified, and an older - * version of the app is installed, the user is taken to the Play Store to - * upgrade the app. - */ - android?: { - - /** - * Defines the required Android package name of the app where the link should be - * handled if the Android app is installed. - */ - packageName: string; - - /** - * Whether to install the Android app if the device supports it and the app is - * not already installed. - */ - installApp?: boolean; - - /** - * The Android minimum version if available. If the installed app is an older - * version, the user is taken to the GOogle Play Store to upgrade the app. - */ - minimumVersion?: string; - }; - - /** - * Defines the dynamic link domain to use for the current link if it is to be - * opened using Firebase Dynamic Links, as multiple dynamic link domains can be - * configured per project. This field provides the ability to explicitly choose - * configured per project. This fields provides the ability explicitly choose - * one. If none is provided, the oldest domain is used by default. - */ - dynamicLinkDomain?: string; - } - - /** - * Interface representing a tenant configuration. - * - * Multi-tenancy support requires Google Cloud's Identity Platform - * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform) - * - * Before multi-tenancy can be used on a Google Cloud Identity Platform project, - * tenants must be allowed on that project via the Cloud Console UI. - * - * A tenant configuration provides information such as the display name, tenant - * identifier and email authentication configuration. - * For OIDC/SAML provider configuration management, `TenantAwareAuth` instances should - * be used instead of a `Tenant` to retrieve the list of configured IdPs on a tenant. - * When configuring these providers, note that tenants will inherit - * whitelisted domains and authenticated redirect URIs of their parent project. - * - * All other settings of a tenant will also be inherited. These will need to be managed - * from the Cloud Console UI. - */ - interface Tenant { - - /** - * The tenant identifier. - */ - tenantId: string; - - /** - * The tenant display name. - */ - displayName?: string; - - /** - * The email sign in provider configuration. - */ - emailSignInConfig?: { - - /** - * Whether email provider is enabled. - */ - enabled: boolean; - - /** - * Whether password is required for email sign-in. When not required, - * email sign-in can be performed with password or via email link sign-in. - */ - passwordRequired?: boolean - }; - - /** - * @return A JSON-serializable representation of this object. - */ - toJSON(): Object; - } - - /** - * Interface representing the properties to update on the provided tenant. - */ - interface UpdateTenantRequest { - - /** - * The tenant display name. - */ - displayName?: string; - - /** - * The email sign in configuration. - */ - emailSignInConfig?: { - - /** - * Whether email provider is enabled. - */ - enabled: boolean; - - /** - * Whether password is required for email sign-in. When not required, - * email sign-in can be performed with password or via email link sign-in. - */ - passwordRequired?: boolean; - }; - } - - /** - * Interface representing the properties to set on a new tenant. - */ - interface CreateTenantRequest extends UpdateTenantRequest { - } - - /** - * Interface representing the object returned from a - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listTenants `listTenants()`} - * operation. - * Contains the list of tenants for the current batch and the next page token if available. - */ - interface ListTenantsResult { - - /** - * The list of {@link admin.auth.Tenant `Tenant`} objects for the downloaded batch. - */ - tenants: admin.auth.Tenant[]; - - /** - * The next page token if available. This is needed for the next batch download. - */ - pageToken?: string; - } - - /** - * The filter interface used for listing provider configurations. This is used - * when specifying how to list configured identity providers via - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listProviderConfigs `listProviderConfigs()`}. - */ - interface AuthProviderConfigFilter { - - /** - * The Auth provider configuration filter. This can be either `saml` or `oidc`. - * The former is used to look up SAML providers only, while the latter is used - * for OIDC providers. - */ - type: 'saml' | 'oidc'; - - /** - * The maximum number of results to return per page. The default and maximum is - * 100. - */ - maxResults?: number; - - /** - * The next page token. When not specified, the lookup starts from the beginning - * of the list. - */ - pageToken?: string; - } - - /** - * The base Auth provider configuration interface. - */ - interface AuthProviderConfig { - - /** - * The provider ID defined by the developer. - * For a SAML provider, this is always prefixed by `saml.`. - * For an OIDC provider, this is always prefixed by `oidc.`. - */ - providerId: string; - - /** - * The user-friendly display name to the current configuration. This name is - * also used as the provider label in the Cloud Console. - */ - displayName: string; - - /** - * Whether the provider configuration is enabled or disabled. A user - * cannot sign in using a disabled provider. - */ - enabled: boolean; - } - - /** - * The - * [SAML](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html) - * Auth provider configuration interface. A SAML provider can be created via - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createProviderConfig `createProviderConfig()`}. - */ - interface SAMLAuthProviderConfig extends admin.auth.AuthProviderConfig { - - /** - * The SAML IdP entity identifier. - */ - idpEntityId: string; - - /** - * The SAML IdP SSO URL. This must be a valid URL. - */ - ssoURL: string; - - /** - * The list of SAML IdP X.509 certificates issued by CA for this provider. - * Multiple certificates are accepted to prevent outages during - * IdP key rotation (for example ADFS rotates every 10 days). When the Auth - * server receives a SAML response, it will match the SAML response with the - * certificate on record. Otherwise the response is rejected. - * Developers are expected to manage the certificate updates as keys are - * rotated. - */ - x509Certificates: string[]; - - /** - * The SAML relying party (service provider) entity ID. - * This is defined by the developer but needs to be provided to the SAML IdP. - */ - rpEntityId: string; - - /** - * This is fixed and must always be the same as the OAuth redirect URL - * provisioned by Firebase Auth, - * `https://project-id.firebaseapp.com/__/auth/handler` unless a custom - * `authDomain` is used. - * The callback URL should also be provided to the SAML IdP during - * configuration. - */ - callbackURL?: string; - } - - /** - * The [OIDC](https://openid.net/specs/openid-connect-core-1_0-final.html) Auth - * provider configuration interface. An OIDC provider can be created via - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#createProviderConfig `createProviderConfig()`}. - */ - interface OIDCAuthProviderConfig extends admin.auth.AuthProviderConfig { - - /** - * This is the required client ID used to confirm the audience of an OIDC - * provider's - * [ID token](https://openid.net/specs/openid-connect-core-1_0-final.html#IDToken). - */ - clientId: string; - - /** - * This is the required provider issuer used to match the provider issuer of - * the ID token and to determine the corresponding OIDC discovery document, eg. - * [`/.well-known/openid-configuration`](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). - * This is needed for the following: - *
    - *
  • To verify the provided issuer.
    • - *
  • Determine the authentication/authorization endpoint during the OAuth - * `id_token` authentication flow.
    • - *
  • To retrieve the public signing keys via `jwks_uri` to verify the OIDC - * provider's ID token's signature.
    • - *
  • To determine the claims_supported to construct the user attributes to be - * returned in the additional user info response.
    • - *
- * ID token validation will be performed as defined in the - * [spec](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation). - */ - issuer: string; - } - - /** - * The request interface for updating a SAML Auth provider. This is used - * when updating a SAML provider's configuration via - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#updateProviderConfig `updateProviderConfig()`}. - */ - interface SAMLUpdateAuthProviderRequest { - - /** - * The SAML provider's updated display name. If not provided, the existing - * configuration's value is not modified. - */ - displayName?: string; - - /** - * Whether the SAML provider is enabled or not. If not provided, the existing - * configuration's setting is not modified. - */ - enabled?: boolean; - - /** - * The SAML provider's updated IdP entity ID. If not provided, the existing - * configuration's value is not modified. - */ - idpEntityId?: string; - - /** - * The SAML provider's updated SSO URL. If not provided, the existing - * configuration's value is not modified. - */ - ssoURL?: string; - - /** - * The SAML provider's updated list of X.509 certificated. If not provided, the - * existing configuration list is not modified. - */ - x509Certificates?: string[]; - - /** - * The SAML provider's updated RP entity ID. If not provided, the existing - * configuration's value is not modified. - */ - rpEntityId?: string; - - /** - * The SAML provider's callback URL. If not provided, the existing - * configuration's value is not modified. - */ - callbackURL?: string; - } - - /** - * The request interface for updating an OIDC Auth provider. This is used - * when updating an OIDC provider's configuration via - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#updateProviderConfig `updateProviderConfig()`}. - */ - interface OIDCUpdateAuthProviderRequest { - - /** - * The OIDC provider's updated display name. If not provided, the existing - * configuration's value is not modified. - */ - displayName?: string; - - /** - * Whether the OIDC provider is enabled or not. If not provided, the existing - * configuration's setting is not modified. - */ - enabled?: boolean; - - /** - * The OIDC provider's updated client ID. If not provided, the existing - * configuration's value is not modified. - */ - clientId?: string; - - /** - * The OIDC provider's updated issuer. If not provided, the existing - * configuration's value is not modified. - */ - issuer?: string; - } - - /** - * The response interface for listing provider configs. This is only available - * when listing all identity providers' configurations via - * {@link https://firebase.google.com/docs/reference/admin/node/admin.auth.Auth#listProviderConfigs `listProviderConfigs()`}. - */ - interface ListProviderConfigResults { - - /** - * The list of providers for the specified type in the current page. - */ - providerConfigs: admin.auth.AuthProviderConfig[]; - - /** - * The next page token, if available. - */ - pageToken?: string; - } - - - type UpdateAuthProviderRequest = - admin.auth.SAMLUpdateAuthProviderRequest | admin.auth.OIDCUpdateAuthProviderRequest; - - interface BaseAuth { - - /** - * Creates a new Firebase custom token (JWT) that can be sent back to a client - * device to use to sign in with the client SDKs' `signInWithCustomToken()` - * methods. (Tenant-aware instances will also embed the tenant ID in the - * token.) - * - * See [Create Custom Tokens](/docs/auth/admin/create-custom-tokens) for code - * samples and detailed documentation. - * - * @param uid The `uid` to use as the custom token's subject. - * @param developerClaims Optional additional claims to include - * in the custom token's payload. - * - * @return A promise fulfilled with a custom token for the - * provided `uid` and payload. - */ - createCustomToken(uid: string, developerClaims?: Object): Promise; - - /** - * Creates a new user. - * - * See [Create a user](/docs/auth/admin/manage-users#create_a_user) for code - * samples and detailed documentation. - * - * @param properties The properties to set on the - * new user record to be created. - * - * @return A promise fulfilled with the user - * data corresponding to the newly created user. - */ - createUser(properties: admin.auth.CreateRequest): Promise; - - /** - * Deletes an existing user. - * - * See [Delete a user](/docs/auth/admin/manage-users#delete_a_user) for code - * samples and detailed documentation. - * - * @param uid The `uid` corresponding to the user to delete. - * - * @return An empty promise fulfilled once the user has been - * deleted. - */ - deleteUser(uid: string): Promise; - - /** - * Gets the user data for the user corresponding to a given `uid`. - * - * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) - * for code samples and detailed documentation. - * - * @param uid The `uid` corresponding to the user whose data to fetch. - * - * @return A promise fulfilled with the user - * data corresponding to the provided `uid`. - */ - getUser(uid: string): Promise; - - /** - * Gets the user data for the user corresponding to a given email. - * - * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) - * for code samples and detailed documentation. - * - * @param email The email corresponding to the user whose data to - * fetch. - * - * @return A promise fulfilled with the user - * data corresponding to the provided email. - */ - getUserByEmail(email: string): Promise; - - /** - * Gets the user data for the user corresponding to a given phone number. The - * phone number has to conform to the E.164 specification. - * - * See [Retrieve user data](/docs/auth/admin/manage-users#retrieve_user_data) - * for code samples and detailed documentation. - * - * @param phoneNumber The phone number corresponding to the user whose - * data to fetch. - * - * @return A promise fulfilled with the user - * data corresponding to the provided phone number. - */ - getUserByPhoneNumber(phoneNumber: string): Promise; - - /** - * Retrieves a list of users (single batch only) with a size of `maxResults` - * starting from the offset as specified by `pageToken`. This is used to - * retrieve all the users of a specified project in batches. - * - * See [List all users](/docs/auth/admin/manage-users#list_all_users) - * for code samples and detailed documentation. - * - * @param maxResults The page size, 1000 if undefined. This is also - * the maximum allowed limit. - * @param pageToken The next page token. If not specified, returns - * users starting without any offset. - * @return A promise that resolves with - * the current batch of downloaded users and the next page token. - */ - listUsers(maxResults?: number, pageToken?: string): Promise; - - /** - * Updates an existing user. - * - * See [Update a user](/docs/auth/admin/manage-users#update_a_user) for code - * samples and detailed documentation. - * - * @param uid The `uid` corresponding to the user to delete. - * @param properties The properties to update on - * the provided user. - * - * @return A promise fulfilled with the - * updated user data. - */ - updateUser(uid: string, properties: admin.auth.UpdateRequest): Promise; - - /** - * Verifies a Firebase ID token (JWT). If the token is valid, the promise is - * fulfilled with the token's decoded claims; otherwise, the promise is - * rejected. - * An optional flag can be passed to additionally check whether the ID token - * was revoked. - * - * See [Verify ID Tokens](/docs/auth/admin/verify-id-tokens) for code samples - * and detailed documentation. - * - * @param idToken The ID token to verify. - * @param checkRevoked Whether to check if the ID token was revoked. - * This requires an extra request to the Firebase Auth backend to check - * the `tokensValidAfterTime` time for the corresponding user. - * When not specified, this additional check is not applied. - * - * @return A promise fulfilled with the - * token's decoded claims if the ID token is valid; otherwise, a rejected - * promise. - */ - verifyIdToken(idToken: string, checkRevoked?: boolean): Promise; - - /** - * Sets additional developer claims on an existing user identified by the - * provided `uid`, typically used to define user roles and levels of - * access. These claims should propagate to all devices where the user is - * already signed in (after token expiration or when token refresh is forced) - * and the next time the user signs in. If a reserved OIDC claim name - * is used (sub, iat, iss, etc), an error is thrown. They are set on the - * authenticated user's ID token JWT. - * - * See - * [Defining user roles and access levels](/docs/auth/admin/custom-claims) - * for code samples and detailed documentation. - * - * @param uid The `uid` of the user to edit. - * @param customUserClaims The developer claims to set. If null is - * passed, existing custom claims are deleted. Passing a custom claims payload - * larger than 1000 bytes will throw an error. Custom claims are added to the - * user's ID token which is transmitted on every authenticated request. - * For profile non-access related user attributes, use database or other - * separate storage systems. - * @return A promise that resolves when the operation completes - * successfully. - */ - setCustomUserClaims(uid: string, customUserClaims: Object | null): Promise; - - /** - * Revokes all refresh tokens for an existing user. - * - * This API will update the user's - * {@link admin.auth.UserRecord#tokensValidAfterTime `tokensValidAfterTime`} to - * the current UTC. It is important that the server on which this is called has - * its clock set correctly and synchronized. - * - * While this will revoke all sessions for a specified user and disable any - * new ID tokens for existing sessions from getting minted, existing ID tokens - * may remain active until their natural expiration (one hour). To verify that - * ID tokens are revoked, use - * {@link admin.auth.Auth#verifyIdToken `verifyIdToken(idToken, true)`} - * where `checkRevoked` is set to true. - * - * @param uid The `uid` corresponding to the user whose refresh tokens - * are to be revoked. - * - * @return An empty promise fulfilled once the user's refresh - * tokens have been revoked. - */ - revokeRefreshTokens(uid: string): Promise; - - /** - * Imports the provided list of users into Firebase Auth. - * A maximum of 1000 users are allowed to be imported one at a time. - * When importing users with passwords, - * {@link admin.auth.UserImportOptions `UserImportOptions`} are required to be - * specified. - * This operation is optimized for bulk imports and will ignore checks on `uid`, - * `email` and other identifier uniqueness which could result in duplications. - * - * @param users The list of user records to import to Firebase Auth. - * @param options The user import options, required when the users provided include - * password credentials. - * @return A promise that resolves when - * the operation completes with the result of the import. This includes the - * number of successful imports, the number of failed imports and their - * corresponding errors. - */ - importUsers( - users: admin.auth.UserImportRecord[], - options?: admin.auth.UserImportOptions, - ): Promise - - /** - * Creates a new Firebase session cookie with the specified options. The created - * JWT string can be set as a server-side session cookie with a custom cookie - * policy, and be used for session management. The session cookie JWT will have - * the same payload claims as the provided ID token. - * - * See [Manage Session Cookies](/docs/auth/admin/manage-cookies) for code - * samples and detailed documentation. - * - * @param idToken The Firebase ID token to exchange for a session - * cookie. - * @param sessionCookieOptions The session - * cookie options which includes custom session duration. - * - * @return A promise that resolves on success with the - * created session cookie. - */ - createSessionCookie( - idToken: string, - sessionCookieOptions: admin.auth.SessionCookieOptions, - ): Promise; - - /** - * Verifies a Firebase session cookie. Returns a Promise with the cookie claims. - * Rejects the promise if the cookie could not be verified. If `checkRevoked` is - * set to true, verifies if the session corresponding to the session cookie was - * revoked. If the corresponding user's session was revoked, an - * `auth/session-cookie-revoked` error is thrown. If not specified the check is - * not performed. - * - * See [Verify Session Cookies](/docs/auth/admin/manage-cookies#verify_session_cookie_and_check_permissions) - * for code samples and detailed documentation - * - * @param sessionCookie The session cookie to verify. - * @param checkForRevocation Whether to check if the session cookie was - * revoked. This requires an extra request to the Firebase Auth backend to - * check the `tokensValidAfterTime` time for the corresponding user. - * When not specified, this additional check is not performed. - * - * @return A promise fulfilled with the - * session cookie's decoded claims if the session cookie is valid; otherwise, - * a rejected promise. - */ - verifySessionCookie( - sessionCookie: string, - checkForRevocation?: boolean, - ): Promise; - - /** - * Generates the out of band email action link to reset a user's password. - * The link is generated for the user with the specified email address. The - * optional {@link admin.auth.ActionCodeSettings `ActionCodeSettings`} object - * defines whether the link is to be handled by a mobile app or browser and the - * additional state information to be passed in the deep link, etc. - * - * @example - * ```javascript - * var actionCodeSettings = { - * url: 'https://www.example.com/?email=user@example.com', - * iOS: { - * bundleId: 'com.example.ios' - * }, - * android: { - * packageName: 'com.example.android', - * installApp: true, - * minimumVersion: '12' - * }, - * handleCodeInApp: true, - * dynamicLinkDomain: 'custom.page.link' - * }; - * admin.auth() - * .generatePasswordResetLink('user@example.com', actionCodeSettings) - * .then(function(link) { - * // The link was successfully generated. - * }) - * .catch(function(error) { - * // Some error occurred, you can inspect the code: error.code - * }); - * ``` - * - * @param email The email address of the user whose password is to be - * reset. - * @param actionCodeSettings The action - * code settings. If specified, the state/continue URL is set as the - * "continueUrl" parameter in the password reset link. The default password - * reset landing page will use this to display a link to go back to the app - * if it is installed. - * If the actionCodeSettings is not specified, no URL is appended to the - * action URL. - * The state URL provided must belong to a domain that is whitelisted by the - * developer in the console. Otherwise an error is thrown. - * Mobile app redirects are only applicable if the developer configures - * and accepts the Firebase Dynamic Links terms of service. - * The Android package name and iOS bundle ID are respected only if they - * are configured in the same Firebase Auth project. - * @return A promise that resolves with the generated link. - */ - generatePasswordResetLink( - email: string, - actionCodeSettings?: admin.auth.ActionCodeSettings, - ): Promise; - - /** - * Generates the out of band email action link to verify the user's ownership - * of the specified email. The - * {@link admin.auth.ActionCodeSettings `ActionCodeSettings`} object provided - * as an argument to this method defines whether the link is to be handled by a - * mobile app or browser along with additional state information to be passed in - * the deep link, etc. - * - * @example - * ```javascript - * var actionCodeSettings = { - * url: 'https://www.example.com/cart?email=user@example.com&cartId=123', - * iOS: { - * bundleId: 'com.example.ios' - * }, - * android: { - * packageName: 'com.example.android', - * installApp: true, - * minimumVersion: '12' - * }, - * handleCodeInApp: true, - * dynamicLinkDomain: 'custom.page.link' - * }; - * admin.auth() - * .generateEmailVerificationLink('user@example.com', actionCodeSettings) - * .then(function(link) { - * // The link was successfully generated. - * }) - * .catch(function(error) { - * // Some error occurred, you can inspect the code: error.code - * }); - * ``` - * - * @param email The email account to verify. - * @param actionCodeSettings The action - * code settings. If specified, the state/continue URL is set as the - * "continueUrl" parameter in the email verification link. The default email - * verification landing page will use this to display a link to go back to - * the app if it is installed. - * If the actionCodeSettings is not specified, no URL is appended to the - * action URL. - * The state URL provided must belong to a domain that is whitelisted by the - * developer in the console. Otherwise an error is thrown. - * Mobile app redirects are only applicable if the developer configures - * and accepts the Firebase Dynamic Links terms of service. - * The Android package name and iOS bundle ID are respected only if they - * are configured in the same Firebase Auth project. - * @return A promise that resolves with the generated link. - */ - generateEmailVerificationLink( - email: string, - actionCodeSettings?: admin.auth.ActionCodeSettings, - ): Promise; - - /** - * Generates the out of band email action link to sign in or sign up the owner - * of the specified email. The - * {@link admin.auth.ActionCodeSettings `ActionCodeSettings`} object provided - * as an argument to this method defines whether the link is to be handled by a - * mobile app or browser along with additional state information to be passed in - * the deep link, etc. - * - * @example - * ```javascript - * var actionCodeSettings = { - * // The URL to redirect to for sign-in completion. This is also the deep - * // link for mobile redirects. The domain (www.example.com) for this URL - * // must be whitelisted in the Firebase Console. - * url: 'https://www.example.com/finishSignUp?cartId=1234', - * iOS: { - * bundleId: 'com.example.ios' - * }, - * android: { - * packageName: 'com.example.android', - * installApp: true, - * minimumVersion: '12' - * }, - * // This must be true. - * handleCodeInApp: true, - * dynamicLinkDomain: 'custom.page.link' - * }; - * admin.auth() - * .generateSignInWithEmailLink('user@example.com', actionCodeSettings) - * .then(function(link) { - * // The link was successfully generated. - * }) - * .catch(function(error) { - * // Some error occurred, you can inspect the code: error.code - * }); - * ``` - * - * @param email The email account to sign in with. - * @param actionCodeSettings The action - * code settings. These settings provide Firebase with instructions on how - * to construct the email link. This includes the sign in completion URL or - * the deep link for redirects and the mobile apps to use when the - * sign-in link is opened on an Android or iOS device. - * Mobile app redirects are only applicable if the developer configures - * and accepts the Firebase Dynamic Links terms of service. - * The Android package name and iOS bundle ID are respected only if they - * are configured in the same Firebase Auth project. - * @return A promise that resolves with the generated link. - */ - generateSignInWithEmailLink( - email: string, - actionCodeSettings: admin.auth.ActionCodeSettings, - ): Promise; - - /** - * Returns the list of existing provider configurations matching the filter - * provided. At most, 100 provider configs can be listed at a time. - * - * SAML and OIDC provider support requires Google Cloud's Identity Platform - * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). - * - * @param options The provider config filter to apply. - * @return A promise that resolves with the list of provider configs meeting the - * filter requirements. - */ - listProviderConfigs( - options: admin.auth.AuthProviderConfigFilter - ): Promise; - - /** - * Looks up an Auth provider configuration by the provided ID. - * Returns a promise that resolves with the provider configuration - * corresponding to the provider ID specified. If the specified ID does not - * exist, an `auth/configuration-not-found` error is thrown. - * - * SAML and OIDC provider support requires Google Cloud's Identity Platform - * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). - * - * @param providerId The provider ID corresponding to the provider - * config to return. - * @return A promise that resolves - * with the configuration corresponding to the provided ID. - */ - getProviderConfig(providerId: string): Promise; - - /** - * Deletes the provider configuration corresponding to the provider ID passed. - * If the specified ID does not exist, an `auth/configuration-not-found` error - * is thrown. - * - * SAML and OIDC provider support requires Google Cloud's Identity Platform - * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). - * - * @param providerId The provider ID corresponding to the provider - * config to delete. - * @return A promise that resolves on completion. - */ - deleteProviderConfig(providerId: string): Promise; - - /** - * Returns a promise that resolves with the updated `AuthProviderConfig` - * corresponding to the provider ID specified. - * If the specified ID does not exist, an `auth/configuration-not-found` error - * is thrown. - * - * SAML and OIDC provider support requires Google Cloud's Identity Platform - * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). - * - * @param providerId The provider ID corresponding to the provider - * config to update. - * @param updatedConfig The updated configuration. - * @return A promise that resolves with the updated provider configuration. - */ - updateProviderConfig( - providerId: string, updatedConfig: admin.auth.UpdateAuthProviderRequest - ): Promise; - - /** - * Returns a promise that resolves with the newly created `AuthProviderConfig` - * when the new provider configuration is created. - * - * SAML and OIDC provider support requires Google Cloud's Identity Platform - * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform). - * - * @param config The provider configuration to create. - * @return A promise that resolves with the created provider configuration. - */ - createProviderConfig( - config: admin.auth.AuthProviderConfig - ): Promise; - } - - /** - * Tenant-aware `Auth` interface used for managing users, configuring SAML/OIDC providers, - * generating email links for password reset, email verification, etc for specific tenants. - * - * Multi-tenancy support requires Google Cloud's Identity Platform - * (GCIP). To learn more about GCIP, including pricing and features, - * see the [GCIP documentation](https://cloud.google.com/identity-platform) - * - * Each tenant contains its own identity providers, settings and sets of users. - * Using `TenantAwareAuth`, users for a specific tenant and corresponding OIDC/SAML - * configurations can also be managed, ID tokens for users signed in to a specific tenant - * can be verified, and email action links can also be generated for users belonging to the - * tenant. - * - * `TenantAwareAuth` instances for a specific `tenantId` can be instantiated by calling - * `auth.tenantManager().authForTenant(tenantId)`. - */ - interface TenantAwareAuth extends BaseAuth { - - /** - * The tenant identifier corresponding to this `TenantAwareAuth` instance. - * All calls to the user management APIs, OIDC/SAML provider management APIs, email link - * generation APIs, etc will only be applied within the scope of this tenant. - */ - tenantId: string; - } - - interface Auth extends admin.auth.BaseAuth { - app: admin.app.App; - - /** - * @return The tenant manager instance associated with the current project. - */ - tenantManager(): admin.auth.TenantManager; - } - - /** - * Defines the tenant manager used to help manage tenant related operations. - * This includes: - *
    - *
  • The ability to create, update, list, get and delete tenants for the underlying - * project.
    • - *
  • Getting a `TenantAwareAuth` instance for running Auth related operations - * (user management, provider configuration management, token verification, - * email link generation, etc) in the context of a specified tenant.
    • - *
- */ - interface TenantManager { - /** - * @param tenantId The tenant ID whose `TenantAwareAuth` instance is to be returned. - * - * @return The `TenantAwareAuth` instance corresponding to this tenant identifier. - */ - authForTenant(tenantId: string): admin.auth.TenantAwareAuth; - - /** - * Gets the tenant configuration for the tenant corresponding to a given `tenantId`. - * - * @param tenantId The tenant identifier corresponding to the tenant whose data to fetch. - * - * @return A promise fulfilled with the tenant configuration to the provided `tenantId`. - */ - getTenant(tenantId: string): Promise; - - /** - * Retrieves a list of tenants (single batch only) with a size of `maxResults` - * starting from the offset as specified by `pageToken`. This is used to - * retrieve all the tenants of a specified project in batches. - * - * @param maxResults The page size, 1000 if undefined. This is also - * the maximum allowed limit. - * @param pageToken The next page token. If not specified, returns - * tenants starting without any offset. - * - * @return A promise that resolves with - * a batch of downloaded tenants and the next page token. - */ - listTenants(maxResults?: number, pageToken?: string): Promise; - - /** - * Deletes an existing tenant. - * - * @param tenantId The `tenantId` corresponding to the tenant to delete. - * - * @return An empty promise fulfilled once the tenant has been deleted. - */ - deleteTenant(tenantId: string): Promise; - - /** - * Creates a new tenant. - * When creating new tenants, tenants that use separate billing and quota will require their - * own project and must be defined as `full_service`. - * - * @param tenantOptions The properties to set on the new tenant configuration to be created. - * - * @return A promise fulfilled with the tenant configuration corresponding to the newly - * created tenant. - */ - createTenant(tenantOptions: admin.auth.CreateTenantRequest): Promise; - - /** - * Updates an existing tenant configuration. - * - * @param tenantId The `tenantId` corresponding to the tenant to delete. - * @param tenantOptions The properties to update on the provided tenant. - * - * @return A promise fulfilled with the update tenant data. - */ - updateTenant(tenantId: string, tenantOptions: admin.auth.UpdateTenantRequest): Promise; - } -} - -declare namespace admin.credential { - - /** - * 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 admin.credential `admin.credential`}. - */ - interface Credential { - - /** - * Returns a Google OAuth2 access token object used to authenticate with - * Firebase services. - * - * This object contains the following properties: - * * `access_token` (`string`): The actual Google OAuth2 access token. - * * `expires_in` (`number`): The number of seconds from when the token was - * issued that it expires. - * - * @return A Google OAuth2 access token object. - */ - getAccessToken(): Promise; - } - - - /** - * 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 - * admin.initializeApp({ - * credential: admin.credential.applicationDefault(), - * databaseURL: "https://.firebaseio.com" - * }); - * ``` - * - * @param {!Object=} 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 {!admin.credential.Credential} A credential authenticated via Google - * Application Default Credentials that can be used to initialize an app. - */ - function applicationDefault(httpAgent?: Agent): admin.credential.Credential; - - /** - * 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 - * var serviceAccount = require("path/to/serviceAccountKey.json"); - * admin.initializeApp({ - * credential: admin.credential.cert(serviceAccount), - * databaseURL: "https://.firebaseio.com" - * }); - * ``` - * - * @example - * ```javascript - * // Providing a service account object inline - * admin.initializeApp({ - * credential: admin.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. - */ - function cert(serviceAccountPathOrObject: string | admin.ServiceAccount, httpAgent?: Agent): admin.credential.Credential; - - /** - * 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 - * var refreshToken = require("path/to/refreshToken.json"); - * admin.initializeApp({ - * credential: admin.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. - */ - function refreshToken(refreshTokenPathOrObject: string | Object, httpAgent?: Agent): admin.credential.Credential; -} - -declare namespace admin.database { - - /** - * The Firebase Realtime Database service interface. - * - * Do not call this constructor directly. Instead, use - * [`admin.database()`](admin.database#database). - * - * See - * {@link - * https://firebase.google.com/docs/database/admin/start/ - * Introduction to the Admin Database API} - * for a full guide on how to use the Firebase Realtime Database service. - */ - interface Database { - app: admin.app.App; - - /** - * Disconnects from the server (all Database operations will be completed - * offline). - * - * The client automatically maintains a persistent connection to the Database - * server, which will remain active indefinitely and reconnect when - * disconnected. However, the `goOffline()` and `goOnline()` methods may be used - * to control the client connection in cases where a persistent connection is - * undesirable. - * - * While offline, the client will no longer receive data updates from the - * Database. However, all Database operations performed locally will continue to - * immediately fire events, allowing your application to continue behaving - * normally. Additionally, each operation performed locally will automatically - * be queued and retried upon reconnection to the Database server. - * - * To reconnect to the Database and begin receiving remote events, see - * `goOnline()`. - * - * @example - * ```javascript - * admin.database().goOffline(); - * ``` - */ - goOffline(): void; - - /** - * Reconnects to the server and synchronizes the offline Database state - * with the server state. - * - * This method should be used after disabling the active connection with - * `goOffline()`. Once reconnected, the client will transmit the proper data - * and fire the appropriate events so that your client "catches up" - * automatically. - * - * @example - * ```javascript - * admin.database().goOnline(); - * ``` - */ - goOnline(): void; - - /** - * Returns a `Reference` representing the location in the Database - * corresponding to the provided path. Also can be invoked with an existing - * `Reference` as the argument. In that case returns a new `Reference` - * pointing to the same location. If no path argument is - * provided, returns a `Reference` that represents the root of the Database. - * - * @example - * ```javascript - * // Get a reference to the root of the Database - * var rootRef = admin.database.ref(); - * ``` - * - * @example - * ```javascript - * // Get a reference to the /users/ada node - * var adaRef = admin.database().ref("users/ada"); - * // The above is shorthand for the following operations: - * //var rootRef = admin.database().ref(); - * //var adaRef = rootRef.child("users/ada"); - * ``` - * - * @example - * ```javascript - * var adaRef = admin.database().ref("users/ada"); - * // Get a new reference pointing to the same location. - * var anotherAdaRef = admin.database().ref(adaRef); - * ``` - * - * - * @param path Optional path representing - * the location the returned `Reference` will point. Alternatively, a - * `Reference` object to copy. If not provided, the returned `Reference` will - * point to the root of the Database. - * @return If a path is provided, a `Reference` - * pointing to the provided path. Otherwise, a `Reference` pointing to the - * root of the Database. - */ - ref(path?: string | admin.database.Reference): admin.database.Reference; - - /** - * Returns a `Reference` representing the location in the Database - * corresponding to the provided Firebase URL. - * - * An exception is thrown if the URL is not a valid Firebase Database URL or it - * has a different domain than the current `Database` instance. - * - * Note that all query parameters (`orderBy`, `limitToLast`, etc.) are ignored - * and are not applied to the returned `Reference`. - * - * @example - * ```javascript - * // Get a reference to the root of the Database - * var rootRef = admin.database().ref("https://.firebaseio.com"); - * ``` - * - * @example - * ```javascript - * // Get a reference to the /users/ada node - * var adaRef = admin.database().ref("https://.firebaseio.com/users/ada"); - * ``` - * - * @param url The Firebase URL at which the returned `Reference` will - * point. - * @return A `Reference` pointing to the provided Firebase URL. - */ - refFromURL(url: string): admin.database.Reference; - - /** - * Gets the currently applied security rules as a string. The return value consists of - * the rules source including comments. - * - * @return A promise fulfilled with the rules as a raw string. - */ - getRules(): Promise; - - /** - * Gets the currently applied security rules as a parsed JSON object. Any comments in - * the original source are stripped away. - * - * @return A promise fulfilled with the parsed rules object. - */ - getRulesJSON(): Promise; - - /** - * Sets the specified rules on the Firebase Realtime Database instance. If the rules source is - * specified as a string or a Buffer, it may include comments. - * - * @param source Source of the rules to apply. Must not be `null` or empty. - * @return Resolves when the rules are set on the Realtime Database. - */ - setRules(source: string | Buffer | object): Promise; - } - - /** - * A `DataSnapshot` contains data from a Database location. - * - * Any time you read data from the Database, you receive the data as a - * `DataSnapshot`. A `DataSnapshot` is passed to the event callbacks you attach - * with `on()` or `once()`. You can extract the contents of the snapshot as a - * JavaScript object by calling the `val()` method. Alternatively, you can - * traverse into the snapshot by calling `child()` to return child snapshots - * (which you could then call `val()` on). - * - * A `DataSnapshot` is an efficiently generated, immutable copy of the data at - * a Database location. It cannot be modified and will never change (to modify - * data, you always call the `set()` method on a `Reference` directly). - */ - interface DataSnapshot { - key: string | null; - ref: admin.database.Reference; - - /** - * Gets another `DataSnapshot` for the location at the specified relative path. - * - * Passing a relative path to the `child()` method of a DataSnapshot returns - * another `DataSnapshot` for the location at the specified relative path. The - * relative path can either be a simple child name (for example, "ada") or a - * deeper, slash-separated path (for example, "ada/name/first"). If the child - * location has no data, an empty `DataSnapshot` (that is, a `DataSnapshot` - * whose value is `null`) is returned. - * - * @example - * ```javascript - * // Assume we have the following data in the Database: - * { - * "name": { - * "first": "Ada", - * "last": "Lovelace" - * } - * } - * - * // Test for the existence of certain keys within a DataSnapshot - * var ref = admin.database().ref("users/ada"); - * ref.once("value") - * .then(function(snapshot) { - * var name = snapshot.child("name").val(); // {first:"Ada",last:"Lovelace"} - * var firstName = snapshot.child("name/first").val(); // "Ada" - * var lastName = snapshot.child("name").child("last").val(); // "Lovelace" - * var age = snapshot.child("age").val(); // null - * }); - * ``` - * - * @param path A relative path to the location of child data. - * @return `DataSnapshot` for the location at the specified relative path. - */ - child(path: string): admin.database.DataSnapshot; - - /** - * Returns true if this `DataSnapshot` contains any data. It is slightly more - * efficient than using `snapshot.val() !== null`. - * - * @example - * ```javascript - * // Assume we have the following data in the Database: - * { - * "name": { - * "first": "Ada", - * "last": "Lovelace" - * } - * } - * - * // Test for the existence of certain keys within a DataSnapshot - * var ref = admin.database().ref("users/ada"); - * ref.once("value") - * .then(function(snapshot) { - * var a = snapshot.exists(); // true - * var b = snapshot.child("name").exists(); // true - * var c = snapshot.child("name/first").exists(); // true - * var d = snapshot.child("name/middle").exists(); // false - * }); - * ``` - * - * @return Whether this `DataSnapshot` contains any data. - */ - exists(): boolean; - - /** - * Exports the entire contents of the DataSnapshot as a JavaScript object. - * - * The `exportVal()` method is similar to `val()`, except priority information - * is included (if available), making it suitable for backing up your data. - * - * @return The DataSnapshot's contents as a JavaScript value (Object, - * Array, string, number, boolean, or `null`). - */ - exportVal(): any; - - /** - * Enumerates the top-level children in the `DataSnapshot`. - * - * Because of the way JavaScript objects work, the ordering of data in the - * JavaScript object returned by `val()` is not guaranteed to match the ordering - * on the server nor the ordering of `child_added` events. That is where - * `forEach()` comes in handy. It guarantees the children of a `DataSnapshot` - * will be iterated in their query order. - * - * If no explicit `orderBy*()` method is used, results are returned - * ordered by key (unless priorities are used, in which case, results are - * returned by priority). - * - * @example - * ```javascript - * - * // Assume we have the following data in the Database: - * { - * "users": { - * "ada": { - * "first": "Ada", - * "last": "Lovelace" - * }, - * "alan": { - * "first": "Alan", - * "last": "Turing" - * } - * } - * } - * - * // Loop through users in order with the forEach() method. The callback - * // provided to forEach() will be called synchronously with a DataSnapshot - * // for each child: - * var query = admin.database().ref("users").orderByKey(); - * query.once("value") - * .then(function(snapshot) { - * snapshot.forEach(function(childSnapshot) { - * // key will be "ada" the first time and "alan" the second time - * var key = childSnapshot.key; - * // childData will be the actual contents of the child - * var childData = childSnapshot.val(); - * }); - * }); - * ``` - * - * @example - * ```javascript - * // You can cancel the enumeration at any point by having your callback - * // function return true. For example, the following code sample will only - * // fire the callback function one time: - * var query = admin.database().ref("users").orderByKey(); - * query.once("value") - * .then(function(snapshot) { - * snapshot.forEach(function(childSnapshot) { - * var key = childSnapshot.key; // "ada" - * - * // Cancel enumeration - * return true; - * }); - * }); - * ``` - * - * @param action A function - * that will be called for each child `DataSnapshot`. The callback can return - * true to cancel further enumeration. - * @return True if enumeration was canceled due to your callback - * returning true. - */ - forEach(action: (a: admin.database.DataSnapshot) => boolean | void): boolean; - - /** - * Gets the priority value of the data in this `DataSnapshot`. - * - * Applications need not use priority but can order collections by - * ordinary properties (see - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data - * Sorting and filtering data}). - * - * @return The the priority value of the data in this `DataSnapshot`. - */ - getPriority(): string | number | null; - - /** - * Returns true if the specified child path has (non-null) data. - * - * @example - * ```javascript - * // Assume we have the following data in the Database: - * { - * "name": { - * "first": "Ada", - * "last": "Lovelace" - * } - * } - * - * // Determine which child keys in DataSnapshot have data. - * var ref = admin.database().ref("users/ada"); - * ref.once("value") - * .then(function(snapshot) { - * var hasName = snapshot.hasChild("name"); // true - * var hasAge = snapshot.hasChild("age"); // false - * }); - * ``` - * - * @param path A relative path to the location of a potential child. - * @return `true` if data exists at the specified child path; else - * `false`. - */ - hasChild(path: string): boolean; - - /** - * Returns whether or not the `DataSnapshot` has any non-`null` child - * properties. - * - * You can use `hasChildren()` to determine if a `DataSnapshot` has any - * children. If it does, you can enumerate them using `forEach()`. If it - * doesn't, then either this snapshot contains a primitive value (which can be - * retrieved with `val()`) or it is empty (in which case, `val()` will return - * `null`). - * - * @example - * ```javascript - * // Assume we have the following data in the Database: - * { - * "name": { - * "first": "Ada", - * "last": "Lovelace" - * } - * } - * - * var ref = admin.database().ref("users/ada"); - * ref.once("value") - * .then(function(snapshot) { - * var a = snapshot.hasChildren(); // true - * var b = snapshot.child("name").hasChildren(); // true - * var c = snapshot.child("name/first").hasChildren(); // false - * }); - * ``` - * - * @return True if this snapshot has any children; else false. - */ - hasChildren(): boolean; - - /** - * Returns the number of child properties of this `DataSnapshot`. - * - * @example - * ```javascript - * // Assume we have the following data in the Database: - * { - * "name": { - * "first": "Ada", - * "last": "Lovelace" - * } - * } - * - * var ref = admin.database().ref("users/ada"); - * ref.once("value") - * .then(function(snapshot) { - * var a = snapshot.numChildren(); // 1 ("name") - * var b = snapshot.child("name").numChildren(); // 2 ("first", "last") - * var c = snapshot.child("name/first").numChildren(); // 0 - * }); - * ``` - * - * @return The number of child properties of this `DataSnapshot`. - */ - numChildren(): number; - - /** - * @return A JSON-serializable representation of this object. - */ - toJSON(): Object | null; - - /** - * Extracts a JavaScript value from a `DataSnapshot`. - * - * Depending on the data in a `DataSnapshot`, the `val()` method may return a - * scalar type (string, number, or boolean), an array, or an object. It may also - * return null, indicating that the `DataSnapshot` is empty (contains no data). - * - * @example - * ```javascript - * // Write and then read back a string from the Database. - * ref.set("hello") - * .then(function() { - * return ref.once("value"); - * }) - * .then(function(snapshot) { - * var data = snapshot.val(); // data === "hello" - * }); - * ``` - * - * @example - * ```javascript - * // Write and then read back a JavaScript object from the Database. - * ref.set({ name: "Ada", age: 36 }) - * .then(function() { - * return ref.once("value"); - * }) - * .then(function(snapshot) { - * var data = snapshot.val(); - * // data is { "name": "Ada", "age": 36 } - * // data.name === "Ada" - * // data.age === 36 - * }); - * ``` - * - * @return The DataSnapshot's contents as a JavaScript value (Object, - * Array, string, number, boolean, or `null`). - */ - val(): any; - } - - /** - * The `onDisconnect` class allows you to write or clear data when your client - * disconnects from the Database server. These updates occur whether your - * client disconnects cleanly or not, so you can rely on them to clean up data - * even if a connection is dropped or a client crashes. - * - * The `onDisconnect` class is most commonly used to manage presence in - * applications where it is useful to detect how many clients are connected and - * when other clients disconnect. See - * {@link - * https://firebase.google.com/docs/database/web/offline-capabilities - * Enabling Offline Capabilities in JavaScript} for more information. - * - * To avoid problems when a connection is dropped before the requests can be - * transferred to the Database server, these functions should be called before - * any data is written. - * - * Note that `onDisconnect` operations are only triggered once. If you want an - * operation to occur each time a disconnect occurs, you'll need to re-establish - * the `onDisconnect` operations each time you reconnect. - */ - interface OnDisconnect { - - /** - * Cancels all previously queued `onDisconnect()` set or update events for this - * location and all children. - * - * If a write has been queued for this location via a `set()` or `update()` at a - * parent location, the write at this location will be canceled, though all - * other siblings will still be written. - * - * @example - * ```javascript - * var ref = admin.database().ref("onlineState"); - * ref.onDisconnect().set(false); - * // ... sometime later - * ref.onDisconnect().cancel(); - * ``` - * - * @param onComplete An optional callback function that is - * called when synchronization to the server has completed. The callback - * will be passed a single parameter: null for success, or an Error object - * indicating a failure. - * @return Resolves when synchronization to the server is complete. - */ - cancel(onComplete?: (a: Error | null) => any): Promise; - - /** - * Ensures the data at this location is deleted when the client is disconnected - * (due to closing the browser, navigating to a new page, or network issues). - * - * @param onComplete An optional callback function that is - * called when synchronization to the server has completed. The callback - * will be passed a single parameter: null for success, or an Error object - * indicating a failure. - * @return Resolves when synchronization to the server is complete. - */ - remove(onComplete?: (a: Error | null) => any): Promise; - - /** - * Ensures the data at this location is set to the specified value when the - * client is disconnected (due to closing the browser, navigating to a new page, - * or network issues). - * - * `set()` is especially useful for implementing "presence" systems, where a - * value should be changed or cleared when a user disconnects so that they - * appear "offline" to other users. See - * {@link - * https://firebase.google.com/docs/database/web/offline-capabilities - * Enabling Offline Capabilities in JavaScript} for more information. - * - * Note that `onDisconnect` operations are only triggered once. If you want an - * operation to occur each time a disconnect occurs, you'll need to re-establish - * the `onDisconnect` operations each time. - * - * @example - * ```javascript - * var ref = admin.database().ref("users/ada/status"); - * ref.onDisconnect().set("I disconnected!"); - * ``` - * - * @param value The value to be written to this location on - * disconnect (can be an object, array, string, number, boolean, or null). - * @param onComplete An optional callback function that - * will be called when synchronization to the database server has completed. - * The callback will be passed a single parameter: null for success, or an - * `Error` object indicating a failure. - * @return A promise that resolves when synchronization to the database is complete. - */ - set(value: any, onComplete?: (a: Error | null) => any): Promise; - - /** - * Ensures the data at this location is set to the specified value and priority - * when the client is disconnected (due to closing the browser, navigating to a - * new page, or network issues). - * - * @param value The value to be written to this location on - * disconnect (can be an object, array, string, number, boolean, or null). - * @param priority - * @param onComplete An optional callback function that is - * called when synchronization to the server has completed. The callback - * will be passed a single parameter: null for success, or an Error object - * indicating a failure. - * @return A promise that resolves when synchronization to the database is complete. - */ - setWithPriority( - value: any, - priority: number | string | null, - onComplete?: (a: Error | null) => any - ): Promise; - - /** - * Writes multiple values at this location when the client is disconnected (due - * to closing the browser, navigating to a new page, or network issues). - * - * The `values` argument contains multiple property-value pairs that will be - * written to the Database together. Each child property can either be a simple - * property (for example, "name") or a relative path (for example, "name/first") - * from the current location to the data to update. - * - * As opposed to the `set()` method, `update()` can be use to selectively update - * only the referenced properties at the current location (instead of replacing - * all the child properties at the current location). - * - * See {@link https://firebase.google.com/docs/reference/admin/node/admin.database.Reference#update} - * for examples of using the connected version of `update`. - * - * @example - * ```javascript - * var ref = admin.database().ref("users/ada"); - * ref.update({ - * onlineState: true, - * status: "I'm online." - * }); - * ref.onDisconnect().update({ - * onlineState: false, - * status: "I'm offline." - * }); - * ``` - * - * @param values Object containing multiple values. - * @param onComplete An optional callback function that will - * be called when synchronization to the server has completed. The - * callback will be passed a single parameter: null for success, or an Error - * object indicating a failure. - * @return Resolves when synchronization to the - * Database is complete. - */ - update(values: Object, onComplete?: (a: Error | null) => any): Promise; - } - - type EventType = 'value' | 'child_added' | 'child_changed' | 'child_moved' | 'child_removed'; - - /** - * A `Query` sorts and filters the data at a Database location so only a subset - * of the child data is included. This can be used to order a collection of - * data by some attribute (for example, height of dinosaurs) as well as to - * restrict a large list of items (for example, chat messages) down to a number - * suitable for synchronizing to the client. Queries are created by chaining - * together one or more of the filter methods defined here. - * - * Just as with a `Reference`, you can receive data from a `Query` by using the - * `on()` method. You will only receive events and `DataSnapshot`s for the - * subset of the data that matches your query. - * - * See - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data - * Sorting and filtering data} for more information. - */ - interface Query { - ref: admin.database.Reference; - - /** - * Creates a `Query` with the specified ending point. - * - * Using `startAt()`, `endAt()`, and `equalTo()` allows you to choose arbitrary - * starting and ending points for your queries. - * - * The ending point is inclusive, so children with exactly the specified value - * will be included in the query. The optional key argument can be used to - * further limit the range of the query. If it is specified, then children that - * have exactly the specified value must also have a key name less than or equal - * to the specified key. - * - * You can read more about `endAt()` in - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data - * Filtering data}. - * - * @example - * ```javascript - * // Find all dinosaurs whose names come before Pterodactyl lexicographically. - * var ref = admin.database().ref("dinosaurs"); - * ref.orderByKey().endAt("pterodactyl").on("child_added", function(snapshot) { - * console.log(snapshot.key); - * }); - * ``` - * - * @param value The value to end at. The argument - * type depends on which `orderBy*()` function was used in this query. - * Specify a value that matches the `orderBy*()` type. When used in - * combination with `orderByKey()`, the value must be a string. - * @param key The child key to end at, among the children with the - * previously specified priority. This argument is only allowed if ordering by - * priority. - * @return A new `Query` object. - */ - endAt(value: number | string | boolean | null, key?: string): admin.database.Query; - - /** - * Creates a `Query` that includes children that match the specified value. - * - * Using `startAt()`, `endAt()`, and `equalTo()` allows us to choose arbitrary - * starting and ending points for our queries. - * - * The optional key argument can be used to further limit the range of the - * query. If it is specified, then children that have exactly the specified - * value must also have exactly the specified key as their key name. This can be - * used to filter result sets with many matches for the same value. - * - * You can read more about `equalTo()` in - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data - * Filtering data}. - * - * @example - * // Find all dinosaurs whose height is exactly 25 meters. - * var ref = admin.database().ref("dinosaurs"); - * ref.orderByChild("height").equalTo(25).on("child_added", function(snapshot) { - * console.log(snapshot.key); - * }); - * - * @param value The value to match for. The - * argument type depends on which `orderBy*()` function was used in this - * query. Specify a value that matches the `orderBy*()` type. When used in - * combination with `orderByKey()`, the value must be a string. - * @param key The child key to start at, among the children with the - * previously specified priority. This argument is only allowed if ordering by - * priority. - * @return A new `Query` object. - */ - equalTo(value: number | string | boolean | null, key?: string): admin.database.Query; - - /** - * Returns whether or not the current and provided queries represent the same - * location, have the same query parameters, and are from the same instance of - * `admin.app.App`. - * - * Two `Reference` objects are equivalent if they represent the same location - * and are from the same instance of `admin.app.App`. - * - * Two `Query` objects are equivalent if they represent the same location, have - * the same query parameters, and are from the same instance of `admin.app.App`. - * Equivalent queries share the same sort order, limits, and starting and - * ending points. - * - * @example - * ```javascript - * var rootRef = admin.database().ref(); - * var usersRef = rootRef.child("users"); - * - * usersRef.isEqual(rootRef); // false - * usersRef.isEqual(rootRef.child("users")); // true - * usersRef.parent.isEqual(rootRef); // true - * ``` - * - * @example - * ```javascript - * var rootRef = admin.database().ref(); - * var usersRef = rootRef.child("users"); - * var usersQuery = usersRef.limitToLast(10); - * - * usersQuery.isEqual(usersRef); // false - * usersQuery.isEqual(usersRef.limitToLast(10)); // true - * usersQuery.isEqual(rootRef.limitToLast(10)); // false - * usersQuery.isEqual(usersRef.orderByKey().limitToLast(10)); // false - * ``` - * - * @param other The query to compare against. - * @return Whether or not the current and provided queries are - * equivalent. - */ - isEqual(other: admin.database.Query | null): boolean; - - /** - * Generates a new `Query` limited to the first specific number of children. - * - * The `limitToFirst()` method is used to set a maximum number of children to be - * synced for a given callback. If we set a limit of 100, we will initially only - * receive up to 100 `child_added` events. If we have fewer than 100 messages - * stored in our Database, a `child_added` event will fire for each message. - * However, if we have over 100 messages, we will only receive a `child_added` - * event for the first 100 ordered messages. As items change, we will receive - * `child_removed` events for each item that drops out of the active list so - * that the total number stays at 100. - * - * You can read more about `limitToFirst()` in - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data - * Filtering data}. - * - * @example - * ```javascript - * // Find the two shortest dinosaurs. - * var ref = admin.database().ref("dinosaurs"); - * ref.orderByChild("height").limitToFirst(2).on("child_added", function(snapshot) { - * // This will be called exactly two times (unless there are less than two - * // dinosaurs in the Database). - * - * // It will also get fired again if one of the first two dinosaurs is - * // removed from the data set, as a new dinosaur will now be the second - * // shortest. - * console.log(snapshot.key); - * }); - * ``` - * - * @param limit The maximum number of nodes to include in this query. - * @return A `Query` object. - */ - limitToFirst(limit: number): admin.database.Query; - - /** - * Generates a new `Query` object limited to the last specific number of - * children. - * - * The `limitToLast()` method is used to set a maximum number of children to be - * synced for a given callback. If we set a limit of 100, we will initially only - * receive up to 100 `child_added` events. If we have fewer than 100 messages - * stored in our Database, a `child_added` event will fire for each message. - * However, if we have over 100 messages, we will only receive a `child_added` - * event for the last 100 ordered messages. As items change, we will receive - * `child_removed` events for each item that drops out of the active list so - * that the total number stays at 100. - * - * You can read more about `limitToLast()` in - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data - * Filtering data}. - * - * @example - * ```javascript - * // Find the two heaviest dinosaurs. - * var ref = admin.database().ref("dinosaurs"); - * ref.orderByChild("weight").limitToLast(2).on("child_added", function(snapshot) { - * // This callback will be triggered exactly two times, unless there are - * // fewer than two dinosaurs stored in the Database. It will also get fired - * // for every new, heavier dinosaur that gets added to the data set. - * console.log(snapshot.key); - * }); - * ``` - * - * @param limit The maximum number of nodes to include in this query. - * @return A `Query` object. - */ - limitToLast(limit: number): admin.database.Query; - - /** - * Detaches a callback previously attached with `on()`. - * - * Detach a callback previously attached with `on()`. Note that if `on()` was - * called multiple times with the same eventType and callback, the callback - * will be called multiple times for each event, and `off()` must be called - * multiple times to remove the callback. Calling `off()` on a parent listener - * will not automatically remove listeners registered on child nodes, `off()` - * must also be called on any child listeners to remove the callback. - * - * If a callback is not specified, all callbacks for the specified eventType - * will be removed. Similarly, if no eventType or callback is specified, all - * callbacks for the `Reference` will be removed. - * - * @example - * ```javascript - * var onValueChange = function(dataSnapshot) { ... }; - * ref.on('value', onValueChange); - * ref.child('meta-data').on('child_added', onChildAdded); - * // Sometime later... - * ref.off('value', onValueChange); - * - * // You must also call off() for any child listeners on ref - * // to cancel those callbacks - * ref.child('meta-data').off('child_added', onValueAdded); - * ``` - * - * @example - * ```javascript - * // Or you can save a line of code by using an inline function - * // and on()'s return value. - * var onValueChange = ref.on('value', function(dataSnapshot) { ... }); - * // Sometime later... - * ref.off('value', onValueChange); - * ``` - * - * @param eventType One of the following strings: "value", - * "child_added", "child_changed", "child_removed", or "child_moved." - * @param callback The callback function that was passed to `on()`. - * @param context The context that was passed to `on()`. - */ - off( - eventType?: admin.database.EventType, - callback?: (a: admin.database.DataSnapshot, b?: string | null) => any, - context?: Object | null - ): void; - - /** - * Listens for data changes at a particular location. - * - * This is the primary way to read data from a Database. Your callback - * will be triggered for the initial data and again whenever the data changes. - * Use `off( )` to stop receiving updates. See - * {@link https://firebase.google.com/docs/database/web/retrieve-data - * Retrieve Data on the Web} - * for more details. - * - *

value event

- * - * This event will trigger once with the initial data stored at this location, - * and then trigger again each time the data changes. The `DataSnapshot` passed - * to the callback will be for the location at which `on()` was called. It - * won't trigger until the entire contents has been synchronized. If the - * location has no data, it will be triggered with an empty `DataSnapshot` - * (`val()` will return `null`). - * - *

child_added event

- * - * This event will be triggered once for each initial child at this location, - * and it will be triggered again every time a new child is added. The - * `DataSnapshot` passed into the callback will reflect the data for the - * relevant child. For ordering purposes, it is passed a second argument which - * is a string containing the key of the previous sibling child by sort order - * (or `null` if it is the first child). - * - *

child_removed event

- * - * This event will be triggered once every time a child is removed. The - * `DataSnapshot` passed into the callback will be the old data for the child - * that was removed. A child will get removed when either: - * - * - a client explicitly calls `remove()` on that child or one of its ancestors - * - a client calls `set(null)` on that child or one of its ancestors - * - that child has all of its children removed - * - there is a query in effect which now filters out the child (because it's - * sort order changed or the max limit was hit) - * - *

child_changed event

- * - * This event will be triggered when the data stored in a child (or any of its - * descendants) changes. Note that a single `child_changed` event may represent - * multiple changes to the child. The `DataSnapshot` passed to the callback will - * contain the new child contents. For ordering purposes, the callback is also - * passed a second argument which is a string containing the key of the previous - * sibling child by sort order (or `null` if it is the first child). - * - *

child_moved event

- * - * This event will be triggered when a child's sort order changes such that its - * position relative to its siblings changes. The `DataSnapshot` passed to the - * callback will be for the data of the child that has moved. It is also passed - * a second argument which is a string containing the key of the previous - * sibling child by sort order (or `null` if it is the first child). - * - * @example - * ```javascript - * // Handle a new value. - * ref.on('value', function(dataSnapshot) { - * ... - * }); - * ``` - * - * @example - * ```javascript - * // Handle a new child. - * ref.on('child_added', function(childSnapshot, prevChildKey) { - * ... - * }); - * ``` - * - * @example - * ```javascript - * // Handle child removal. - * ref.on('child_removed', function(oldChildSnapshot) { - * ... - * }); - * ``` - * - * @example - * ```javascript - * // Handle child data changes. - * ref.on('child_changed', function(childSnapshot, prevChildKey) { - * ... - * }); - * ``` - * - * @example - * ```javascript - * // Handle child ordering changes. - * ref.on('child_moved', function(childSnapshot, prevChildKey) { - * ... - * }); - * ``` - * - * @param eventType One of the following strings: "value", - * "child_added", "child_changed", "child_removed", or "child_moved." - * @param callback A callback that fires when the specified event occurs. The callback is - * passed a DataSnapshot. For ordering purposes, "child_added", - * "child_changed", and "child_moved" will also be passed a string containing - * the key of the previous child, by sort order (or `null` if it is the - * first child). - * @param cancelCallbackOrContext An optional - * callback that will be notified if your event subscription is ever canceled - * because your client does not have permission to read this data (or it had - * permission but has now lost it). This callback will be passed an `Error` - * object indicating why the failure occurred. - * @param context If provided, this object will be used as `this` - * when calling your callback(s). - * @return The provided - * callback function is returned unmodified. This is just for convenience if - * you want to pass an inline function to `on()`, but store the callback - * function for later passing to `off()`. - */ - on( - eventType: admin.database.EventType, - callback: (a: admin.database.DataSnapshot | null, b?: string) => any, - cancelCallbackOrContext?: Object | null, - context?: Object | null - ): (a: admin.database.DataSnapshot | null, b?: string) => any; - - /** - * Listens for exactly one event of the specified event type, and then stops - * listening. - * - * This is equivalent to calling `on()`, and then calling `off()` inside the - * callback function. See `on()` for details on the event types. - * - * @example - * ```javascript - * // Basic usage of .once() to read the data located at ref. - * ref.once('value') - * .then(function(dataSnapshot) { - * // handle read data. - * }); - * ``` - * - * @param eventType One of the following strings: "value", - * "child_added", "child_changed", "child_removed", or "child_moved." - * @param successCallback A callback that fires when the specified event occurs. The callback is - * passed a `DataSnapshot`. For ordering purposes, "child_added", - * "child_changed", and "child_moved" will also be passed a string containing - * the key of the previous child by sort order (or `null` if it is the - * first child). - * @param failureCallbackOrContext An optional - * callback that will be notified if your client does not have permission to - * read the data. This callback will be passed an `Error` object indicating - * why the failure occurred. - * @param context If provided, this object will be used as `this` - * when calling your callback(s). - * @return {!Promise} - */ - once( - eventType: admin.database.EventType, - successCallback?: (a: admin.database.DataSnapshot, b?: string) => any, - failureCallbackOrContext?: Object | null, - context?: Object | null - ): Promise; - - /** - * Generates a new `Query` object ordered by the specified child key. - * - * Queries can only order by one key at a time. Calling `orderByChild()` - * multiple times on the same query is an error. - * - * Firebase queries allow you to order your data by any child key on the fly. - * However, if you know in advance what your indexes will be, you can define - * them via the .indexOn rule in your Security Rules for better performance. See - * the {@link https://firebase.google.com/docs/database/security/indexing-data - * .indexOn} rule for more information. - * - * You can read more about `orderByChild()` in - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#sort_data - * Sort data}. - * - * @example - * ```javascript - * var ref = admin.database().ref("dinosaurs"); - * ref.orderByChild("height").on("child_added", function(snapshot) { - * console.log(snapshot.key + " was " + snapshot.val().height + " m tall"); - * }); - * ``` - * - * @param path - * @return A new `Query` object. - */ - orderByChild(path: string): admin.database.Query; - - /** - * Generates a new `Query` object ordered by key. - * - * Sorts the results of a query by their (ascending) key values. - * - * You can read more about `orderByKey()` in - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#sort_data - * Sort data}. - * - * @example - * ```javascript - * var ref = admin.database().ref("dinosaurs"); - * ref.orderByKey().on("child_added", function(snapshot) { - * console.log(snapshot.key); - * }); - * ``` - * - * @return A new `Query` object. - */ - orderByKey(): admin.database.Query; - - /** - * Generates a new `Query` object ordered by priority. - * - * Applications need not use priority but can order collections by - * ordinary properties (see - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#sort_data - * Sort data} for alternatives to priority. - * - * @return A new `Query` object. - */ - orderByPriority(): admin.database.Query; - - /** - * Generates a new `Query` object ordered by value. - * - * If the children of a query are all scalar values (string, number, or - * boolean), you can order the results by their (ascending) values. - * - * You can read more about `orderByValue()` in - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#sort_data - * Sort data}. - * - * @example - * ```javascript - * var scoresRef = admin.database().ref("scores"); - * scoresRef.orderByValue().limitToLast(3).on("value", function(snapshot) { - * snapshot.forEach(function(data) { - * console.log("The " + data.key + " score is " + data.val()); - * }); - * }); - * ``` - * - * @return A new `Query` object. - */ - orderByValue(): admin.database.Query; - - /** - * Creates a `Query` with the specified starting point. - * - * Using `startAt()`, `endAt()`, and `equalTo()` allows you to choose arbitrary - * starting and ending points for your queries. - * - * The starting point is inclusive, so children with exactly the specified value - * will be included in the query. The optional key argument can be used to - * further limit the range of the query. If it is specified, then children that - * have exactly the specified value must also have a key name greater than or - * equal to the specified key. - * - * You can read more about `startAt()` in - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#filtering_data - * Filtering data}. - * - * @example - * ```javascript - * // Find all dinosaurs that are at least three meters tall. - * var ref = admin.database().ref("dinosaurs"); - * ref.orderByChild("height").startAt(3).on("child_added", function(snapshot) { - * console.log(snapshot.key) - * }); - * ``` - * - * @param value The value to start at. The argument - * type depends on which `orderBy*()` function was used in this query. - * Specify a value that matches the `orderBy*()` type. When used in - * combination with `orderByKey()`, the value must be a string. - * @param key The child key to start at. This argument is allowed if - * ordering by child, value, or priority. - * @return A new `Query` object. - */ - startAt(value: number | string | boolean | null, key?: string): admin.database.Query; - - /** - * @return A JSON-serializable representation of this object. - */ - toJSON(): Object; - - /** - * Gets the absolute URL for this location. - * - * The `toString()` method returns a URL that is ready to be put into a browser, - * curl command, or a `admin.database().refFromURL()` call. Since all of those - * expect the URL to be url-encoded, `toString()` returns an encoded URL. - * - * Append '.json' to the returned URL when typed into a browser to download - * JSON-formatted data. If the location is secured (that is, not publicly - * readable), you will get a permission-denied error. - * - * @example - * ```javascript - * // Calling toString() on a root Firebase reference returns the URL where its - * // data is stored within the Database: - * var rootRef = admin.database().ref(); - * var rootUrl = rootRef.toString(); - * // rootUrl === "https://sample-app.firebaseio.com/". - * - * // Calling toString() at a deeper Firebase reference returns the URL of that - * // deep path within the Database: - * var adaRef = rootRef.child('users/ada'); - * var adaURL = adaRef.toString(); - * // adaURL === "https://sample-app.firebaseio.com/users/ada". - * ``` - * - * @return The absolute URL for this location. - * @override - */ - toString(): string; - } - - /** - * A `Reference` represents a specific location in your Database and can be used - * for reading or writing data to that Database location. - * - * You can reference the root or child location in your Database by calling - * `admin.database().ref()` or `admin.database().ref("child/path")`. - * - * Writing is done with the `set()` method and reading can be done with the - * `on()` method. See - * {@link - * https://firebase.google.com/docs/database/web/read-and-write - * Read and Write Data on the Web} - */ - interface Reference extends admin.database.Query { - - /** - * The last part of the `Reference`'s path. - * - * For example, `"ada"` is the key for - * `https://.firebaseio.com/users/ada`. - * - * The key of a root `Reference` is `null`. - * - * @example - * ```javascript - * // The key of a root reference is null - * var rootRef = admin.database().ref(); - * var key = rootRef.key; // key === null - * ``` - * - * @example - * ```javascript - * // The key of any non-root reference is the last token in the path - * var adaRef = admin.database().ref("users/ada"); - * var key = adaRef.key; // key === "ada" - * key = adaRef.child("name/last").key; // key === "last" - * ``` - */ - key: string | null; - - /** - * The parent location of a `Reference`. - * - * The parent of a root `Reference` is `null`. - * - * @example - * ```javascript - * // The parent of a root reference is null - * var rootRef = admin.database().ref(); - * parent = rootRef.parent; // parent === null - * ``` - * - * @example - * ```javascript - * // The parent of any non-root reference is the parent location - * var usersRef = admin.database().ref("users"); - * var adaRef = admin.database().ref("users/ada"); - * // usersRef and adaRef.parent represent the same location - * ``` - */ - parent: admin.database.Reference | null; - - /** - * The root `Reference` of the Database. - * - * @example - * ```javascript - * // The root of a root reference is itself - * var rootRef = admin.database().ref(); - * // rootRef and rootRef.root represent the same location - * ``` - * - * @example - * ```javascript - * // The root of any non-root reference is the root location - * var adaRef = admin.database().ref("users/ada"); - * // rootRef and adaRef.root represent the same location - * ``` - */ - root: admin.database.Reference; - path: string; - - /** - * Gets a `Reference` for the location at the specified relative path. - * - * The relative path can either be a simple child name (for example, "ada") or - * a deeper slash-separated path (for example, "ada/name/first"). - * - * @example - * ```javascript - * var usersRef = admin.database().ref('users'); - * var adaRef = usersRef.child('ada'); - * var adaFirstNameRef = adaRef.child('name/first'); - * var path = adaFirstNameRef.toString(); - * // path is now 'https://sample-app.firebaseio.com/users/ada/name/first' - * ``` - * - * @param path A relative path from this location to the desired child - * location. - * @return The specified child location. - */ - child(path: string): admin.database.Reference; - - /** - * Returns an `OnDisconnect` object - see - * {@link - * https://firebase.google.com/docs/database/web/offline-capabilities - * Enabling Offline Capabilities in JavaScript} for more information on how - * to use it. - * - * @return An `OnDisconnect` object . - */ - onDisconnect(): admin.database.OnDisconnect; - - /** - * Generates a new child location using a unique key and returns its - * `Reference`. - * - * This is the most common pattern for adding data to a collection of items. - * - * If you provide a value to `push()`, the value will be written to the - * generated location. If you don't pass a value, nothing will be written to the - * Database and the child will remain empty (but you can use the `Reference` - * elsewhere). - * - * The unique key generated by `push()` are ordered by the current time, so the - * resulting list of items will be chronologically sorted. The keys are also - * designed to be unguessable (they contain 72 random bits of entropy). - * - * - * See - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data - * Append to a list of data} - *
See - * {@link - * https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html - * The 2^120 Ways to Ensure Unique Identifiers} - * - * @example - * ```javascript - * var messageListRef = admin.database().ref('message_list'); - * var newMessageRef = messageListRef.push(); - * newMessageRef.set({ - * user_id: 'ada', - * text: 'The Analytical Engine weaves algebraical patterns just as the Jacquard loom weaves flowers and leaves.' - * }); - * // We've appended a new message to the message_list location. - * var path = newMessageRef.toString(); - * // path will be something like - * // 'https://sample-app.firebaseio.com/message_list/-IKo28nwJLH0Nc5XeFmj' - * ``` - * - * @param value Optional value to be written at the generated location. - * @param onComplete Callback called when write to server is - * complete. - * @return Combined `Promise` and - * `Reference`; resolves when write is complete, but can be used immediately - * as the `Reference` to the child location. - */ - push(value?: any, onComplete?: (a: Error | null) => any): admin.database.ThenableReference; - - /** - * Removes the data at this Database location. - * - * Any data at child locations will also be deleted. - * - * The effect of the remove will be visible immediately and the corresponding - * event 'value' will be triggered. Synchronization of the remove to the - * Firebase servers will also be started, and the returned Promise will resolve - * when complete. If provided, the onComplete callback will be called - * asynchronously after synchronization has finished. - * - * @example - * ```javascript - * var adaRef = admin.database().ref('users/ada'); - * adaRef.remove() - * .then(function() { - * console.log("Remove succeeded.") - * }) - * .catch(function(error) { - * console.log("Remove failed: " + error.message) - * }); - * ``` - * - * @param onComplete Callback called when write to server is - * complete. - * @return Resolves when remove on server is complete. - */ - remove(onComplete?: (a: Error | null) => any): Promise; - - /** - * Writes data to this Database location. - * - * This will overwrite any data at this location and all child locations. - * - * The effect of the write will be visible immediately, and the corresponding - * events ("value", "child_added", etc.) will be triggered. Synchronization of - * the data to the Firebase servers will also be started, and the returned - * Promise will resolve when complete. If provided, the `onComplete` callback - * will be called asynchronously after synchronization has finished. - * - * Passing `null` for the new value is equivalent to calling `remove()`; namely, - * all data at this location and all child locations will be deleted. - * - * `set()` will remove any priority stored at this location, so if priority is - * meant to be preserved, you need to use `setWithPriority()` instead. - * - * Note that modifying data with `set()` will cancel any pending transactions - * at that location, so extreme care should be taken if mixing `set()` and - * `transaction()` to modify the same data. - * - * A single `set()` will generate a single "value" event at the location where - * the `set()` was performed. - * - * @example - * ```javascript - * var adaNameRef = admin.database().ref('users/ada/name'); - * adaNameRef.child('first').set('Ada'); - * adaNameRef.child('last').set('Lovelace'); - * // We've written 'Ada' to the Database location storing Ada's first name, - * // and 'Lovelace' to the location storing her last name. - * ``` - * - * @example - * ```javascript - * adaNameRef.set({ first: 'Ada', last: 'Lovelace' }); - * // Exact same effect as the previous example, except we've written - * // Ada's first and last name simultaneously. - * ``` - * - * @example - * ```javascript - * adaNameRef.set({ first: 'Ada', last: 'Lovelace' }) - * .then(function() { - * console.log('Synchronization succeeded'); - * }) - * .catch(function(error) { - * console.log('Synchronization failed'); - * }); - * // Same as the previous example, except we will also log a message - * // when the data has finished synchronizing. - * ``` - * - * @param value The value to be written (string, number, boolean, object, - * array, or null). - * @param onComplete Callback called when write to server is - * complete. - * @return Resolves when write to server is complete. - */ - set(value: any, onComplete?: (a: Error | null) => any): Promise; - - /** - * Sets a priority for the data at this Database location. - * - * Applications need not use priority but can order collections by - * ordinary properties (see - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data - * Sorting and filtering data}). - * - * @param priority - * @param onComplete - * @return - */ - setPriority( - priority: string | number | null, - onComplete: (a: Error | null) => any - ): Promise; - - /** - * Writes data the Database location. Like `set()` but also specifies the - * priority for that data. - * - * Applications need not use priority but can order collections by - * ordinary properties (see - * {@link - * https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data - * Sorting and filtering data}). - * - * @param newVal - * @param newPriority - * @param onComplete - * @return - */ - setWithPriority( - newVal: any, newPriority: string | number | null, - onComplete?: (a: Error | null) => any - ): Promise; - - /** - * Atomically modifies the data at this location. - * - * Atomically modify the data at this location. Unlike a normal `set()`, which - * just overwrites the data regardless of its previous value, `transaction()` is - * used to modify the existing value to a new value, ensuring there are no - * conflicts with other clients writing to the same location at the same time. - * - * To accomplish this, you pass `transaction()` an update function which is used - * to transform the current value into a new value. If another client writes to - * the location before your new value is successfully written, your update - * function will be called again with the new current value, and the write will - * be retried. This will happen repeatedly until your write succeeds without - * conflict or you abort the transaction by not returning a value from your - * update function. - * - * Note: Modifying data with `set()` will cancel any pending transactions at - * that location, so extreme care should be taken if mixing `set()` and - * `transaction()` to update the same data. - * - * Note: When using transactions with Security and Firebase Rules in place, be - * aware that a client needs `.read` access in addition to `.write` access in - * order to perform a transaction. This is because the client-side nature of - * transactions requires the client to read the data in order to transactionally - * update it. - * - * @example - * ```javascript - * // Increment Ada's rank by 1. - * var adaRankRef = admin.database().ref('users/ada/rank'); - * adaRankRef.transaction(function(currentRank) { - * // If users/ada/rank has never been set, currentRank will be `null`. - * return currentRank + 1; - * }); - * ``` - * - * @example - * ```javascript - * // Try to create a user for ada, but only if the user id 'ada' isn't - * // already taken - * var adaRef = admin.database().ref('users/ada'); - * adaRef.transaction(function(currentData) { - * if (currentData === null) { - * return { name: { first: 'Ada', last: 'Lovelace' } }; - * } else { - * console.log('User ada already exists.'); - * return; // Abort the transaction. - * } - * }, function(error, committed, snapshot) { - * if (error) { - * console.log('Transaction failed abnormally!', error); - * } else if (!committed) { - * console.log('We aborted the transaction (because ada already exists).'); - * } else { - * console.log('User ada added!'); - * } - * console.log("Ada's data: ", snapshot.val()); - * }); - * ``` - * - * @param transactionUpdate A developer-supplied function which - * will be passed the current data stored at this location (as a JavaScript - * object). The function should return the new value it would like written (as - * a JavaScript object). If `undefined` is returned (i.e. you return with no - * arguments) the transaction will be aborted and the data at this location - * will not be modified. - * @param onComplete A callback - * function that will be called when the transaction completes. The callback - * is passed three arguments: a possibly-null `Error`, a `boolean` indicating - * whether the transaction was committed, and a `DataSnapshot` indicating the - * final result. If the transaction failed abnormally, the first argument will - * be an `Error` object indicating the failure cause. If the transaction - * finished normally, but no data was committed because no data was returned - * from `transactionUpdate`, then second argument will be false. If the - * transaction completed and committed data to Firebase, the second argument - * will be true. Regardless, the third argument will be a `DataSnapshot` - * containing the resulting data in this location. - * @param applyLocally By default, events are raised each time the - * transaction update function runs. So if it is run multiple times, you may - * see intermediate states. You can set this to false to suppress these - * intermediate states and instead wait until the transaction has completed - * before events are raised. - * @return Returns a Promise that can optionally be used instead of the `onComplete` - * callback to handle success and failure. - */ - transaction( - transactionUpdate: (a: any) => any, - onComplete?: (a: Error | null, b: boolean, c: admin.database.DataSnapshot | null) => any, - applyLocally?: boolean - ): Promise<{ - committed: boolean, - snapshot: admin.database.DataSnapshot | null - }>; - - /** - * Writes multiple values to the Database at once. - * - * The `values` argument contains multiple property-value pairs that will be - * written to the Database together. Each child property can either be a simple - * property (for example, "name") or a relative path (for example, - * "name/first") from the current location to the data to update. - * - * As opposed to the `set()` method, `update()` can be use to selectively update - * only the referenced properties at the current location (instead of replacing - * all the child properties at the current location). - * - * The effect of the write will be visible immediately, and the corresponding - * events ('value', 'child_added', etc.) will be triggered. Synchronization of - * the data to the Firebase servers will also be started, and the returned - * Promise will resolve when complete. If provided, the `onComplete` callback - * will be called asynchronously after synchronization has finished. - * - * A single `update()` will generate a single "value" event at the location - * where the `update()` was performed, regardless of how many children were - * modified. - * - * Note that modifying data with `update()` will cancel any pending - * transactions at that location, so extreme care should be taken if mixing - * `update()` and `transaction()` to modify the same data. - * - * Passing `null` to `update()` will remove the data at this location. - * - * See - * {@link - * https://firebase.googleblog.com/2015/09/introducing-multi-location-updates-and_86.html - * Introducing multi-location updates and more}. - * - * @example - * ```javascript - * var adaNameRef = admin.database().ref('users/ada/name'); - * // Modify the 'first' and 'last' properties, but leave other data at - * // adaNameRef unchanged. - * adaNameRef.update({ first: 'Ada', last: 'Lovelace' }); - * ``` - * - * @param values Object containing multiple values. - * @param onComplete Callback called when write to server is - * complete. - * @return Resolves when update on server is complete. - */ - update(values: Object, onComplete?: (a: Error | null) => any): Promise; - } - - /** - * @extends {admin.database.Reference} - */ - interface ThenableReference extends admin.database.Reference, Promise { } - - function enableLogging(logger?: boolean | ((message: string) => any), persistent?: boolean): any; -} - -declare namespace admin.database.ServerValue { - var TIMESTAMP: number; -} - -type BaseMessage = { - data?: { [key: string]: string }; - notification?: admin.messaging.Notification; - android?: admin.messaging.AndroidConfig; - webpush?: admin.messaging.WebpushConfig; - apns?: admin.messaging.ApnsConfig; - fcmOptions?: admin.messaging.FcmOptions; -}; - -interface TokenMessage extends BaseMessage { - token: string; -} - -interface TopicMessage extends BaseMessage { - topic: string; -} - -interface ConditionMessage extends BaseMessage { - condition: string; -} - -declare namespace admin.messaging { - type Message = TokenMessage | TopicMessage | ConditionMessage; - - interface MulticastMessage extends BaseMessage { - tokens: string[]; - } - - /** - * Represents the Android-specific options that can be included in an - * {@link admin.messaging.Message}. - */ - interface AndroidConfig { - - /** - * Collapse key for the message. Collapse key serves as an identifier for a - * group of messages that can be collapsed, so that only the last message gets - * sent when delivery can be resumed. A maximum of four different collapse keys - * may be active at any given time. - */ - collapseKey?: string; - - /** - * Priority of the message. Must be either `normal` or `high`. - */ - priority?: ('high' | 'normal'); - - /** - * Time-to-live duration of the message in milliseconds. - */ - ttl?: number; - - /** - * Package name of the application where the registration tokens must match - * in order to receive the message. - */ - restrictedPackageName?: string; - - /** - * A collection of data fields to be included in the message. All values must - * be strings. When provided, overrides any data fields set on the top-level - * `admin.messaging.Message`.} - */ - data?: { [key: string]: string }; - - /** - * Android notification to be included in the message. - */ - notification?: AndroidNotification; - - /** - * Options for features provided by the FCM SDK for Android. - */ - fcmOptions?: AndroidFcmOptions; - } - - /** - * Represents the Android-specific notification options that can be included in - * {@link admin.messaging.AndroidConfig}. - */ - interface AndroidNotification { - - /** - * Title of the Android notification. When provided, overrides the title set via - * `admin.messaging.Notification`. - */ - title?: string; - - /** - * Body of the Android notification. When provided, overrides the body set via - * `admin.messaging.Notification`. - */ - body?: string; - - /** - * Icon resource for the Android notification. - */ - icon?: string; - - /** - * Notification icon color in `#rrggbb` format. - */ - color?: string; - - /** - * File name of the sound to be played when the device receives the - * notification. - */ - sound?: string; - - /** - * Notification tag. This is an identifier used to replace existing - * notifications in the notification drawer. If not specified, each request - * creates a new notification. - */ - tag?: string; - - /** - * URL of an image to be displayed in the notification. - */ - imageUrl?: string; - - /** - * Action associated with a user click on the notification. If specified, an - * activity with a matching Intent Filter is launched when a user clicks on the - * notification. - */ - clickAction?: string; - - /** - * Key of the body string in the app's string resource to use to localize the - * body text. - * - */ - bodyLocKey?: string; - - /** - * An array of resource keys that will be used in place of the format - * specifiers in `bodyLocKey`. - */ - bodyLocArgs?: string[]; - - /** - * Key of the title string in the app's string resource to use to localize the - * title text. - */ - titleLocKey?: string; - - /** - * An array of resource keys that will be used in place of the format - * specifiers in `titleLocKey`. - */ - titleLocArgs?: string[]; - - /** - * The Android notification channel ID (new in Android O). The app must create - * a channel with this channel ID before any notification with this channel ID - * can be received. If you don't send this channel ID in the request, or if the - * channel ID provided has not yet been created by the app, FCM uses the channel - * ID specified in the app manifest. - */ - channelId?: string; - - /** - * Sets the "ticker" text, which is sent to accessibility services. Prior to - * API level 21 (Lollipop), sets the text that is displayed in the status bar - * when the notification first arrives. - */ - ticker?: string; - - /** - * When set to `false` or unset, the notification is automatically dismissed when - * the user clicks it in the panel. When set to `true`, the notification persists - * even when the user clicks it. - */ - sticky?: boolean; - - /** - * For notifications that inform users about events with an absolute time reference, sets - * the time that the event in the notification occurred. Notifications - * in the panel are sorted by this time. - */ - eventTimestamp?: Date; - - /** - * Sets whether or not this notification is relevant only to the current device. - * Some notifications can be bridged to other devices for remote display, such as - * a Wear OS watch. This hint can be set to recommend this notification not be bridged. - * See [Wear OS guides](https://developer.android.com/training/wearables/notifications/bridger#existing-method-of-preventing-bridging) - */ - localOnly?: boolean; - - /** - * Sets the relative priority for this notification. Low-priority notifications - * may be hidden from the user in certain situations. Note this priority differs - * from `AndroidMessagePriority`. This priority is processed by the client after - * the message has been delivered. Whereas `AndroidMessagePriority` is an FCM concept - * that controls when the message is delivered. - */ - priority?: ('min' | 'low' | 'default' | 'high' | 'max'); - - /** - * Sets the vibration pattern to use. Pass in an array of milliseconds to - * turn the vibrator on or off. The first value indicates the duration to wait before - * turning the vibrator on. The next value indicates the duration to keep the - * vibrator on. Subsequent values alternate between duration to turn the vibrator - * off and to turn the vibrator on. If `vibrate_timings` is set and `default_vibrate_timings` - * is set to `true`, the default value is used instead of the user-specified `vibrate_timings`. - */ - vibrateTimingsMillis?: number[]; - - /** - * If set to `true`, use the Android framework's default vibrate pattern for the - * notification. Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). - * If `default_vibrate_timings` is set to `true` and `vibrate_timings` is also set, - * the default value is used instead of the user-specified `vibrate_timings`. - */ - defaultVibrateTimings?: boolean; - - /** - * If set to `true`, use the Android framework's default sound for the notification. - * Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). - */ - defaultSound?: boolean; - - /** - * Settings to control the notification's LED blinking rate and color if LED is - * available on the device. The total blinking time is controlled by the OS. - */ - lightSettings?: LightSettings; - - /** - * If set to `true`, use the Android framework's default LED light settings - * for the notification. Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). - * If `default_light_settings` is set to `true` and `light_settings` is also set, - * the user-specified `light_settings` is used instead of the default value. - */ - defaultLightSettings?: boolean; - - /** - * Sets the visibility of the notification. Must be either `private`, `public`, - * or `secret`. If unspecified, defaults to `private`. - */ - visibility?: ('private' | 'public' | 'secret'); - - /** - * Sets the number of items this notification represents. May be displayed as a - * badge count for Launchers that support badging. See [`NotificationBadge`(https://developer.android.com/training/notify-user/badges). - * For example, this might be useful if you're using just one notification to - * represent multiple new messages but you want the count here to represent - * the number of total new messages. If zero or unspecified, systems - * that support badging use the default, which is to increment a number - * displayed on the long-press menu each time a new notification arrives. - */ - notificationCount?: number; - } - - /** - * Represents settings to control notification LED that can be included in - * {@link admin.messaging.AndroidNotification}. - */ - interface LightSettings { - /** - * Required. Sets color of the LED in `#rrggbb` or `#rrggbbaa` format. - */ - color: string; - - /** - * Required. Along with `light_off_duration`, defines the blink rate of LED flashes. - */ - lightOnDurationMillis: number; - - /** - * Required. Along with `light_on_duration`, defines the blink rate of LED flashes. - */ - lightOffDurationMillis: number; - } - - /** - * Represents options for features provided by the FCM SDK for Android. - */ - interface AndroidFcmOptions { - - /** - * The label associated with the message's analytics data. - */ - analyticsLabel?: string; - } - - /** - * Represents the APNs-specific options that can be included in an - * {@link admin.messaging.Message}. Refer to - * [Apple documentation](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html) - * for various headers and payload fields supported by APNs. - */ - interface ApnsConfig { - - /** - * A collection of APNs headers. Header values must be strings. - */ - headers?: { [key: string]: string }; - - /** - * An APNs payload to be included in the message. - */ - payload?: ApnsPayload; - - /** - * Options for features provided by the FCM SDK for iOS. - */ - fcmOptions?: ApnsFcmOptions; - } - /** - * Represents the payload of an APNs message. Mainly consists of the `aps` - * dictionary. But may also contain other arbitrary custom keys. - */ - interface ApnsPayload { - - /** - * The `aps` dictionary to be included in the message. - */ - aps: Aps; - [customData: string]: object; - } - /** - * Represents the [aps dictionary](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * that is part of APNs messages. - */ - interface Aps { - - /** - * Alert to be included in the message. This may be a string or an object of - * type `admin.messaging.ApsAlert`. - */ - alert?: string | ApsAlert; - - /** - * Badge to be displayed with the message. Set to 0 to remove the badge. When - * not specified, the badge will remain unchanged. - */ - badge?: number; - - /** - * Sound to be played with the message. - */ - sound?: string | CriticalSound; - - /** - * Specifies whether to configure a background update notification. - */ - contentAvailable?: boolean; - - /** - * Specifies whether to set the `mutable-content` property on the message - * so the clients can modify the notification via app extensions. - */ - mutableContent?: boolean; - - /** - * Type of the notification. - */ - category?: string; - - /** - * An app-specific identifier for grouping notifications. - */ - threadId?: string; - [customData: string]: any; - } - - interface ApsAlert { - title?: string; - subtitle?: string; - body?: string; - locKey?: string; - locArgs?: string[]; - titleLocKey?: string; - titleLocArgs?: string[]; - subtitleLocKey?: string; - subtitleLocArgs?: string[]; - actionLocKey?: string; - launchImage?: string; - } - - /** - * Represents a critical sound configuration that can be included in the - * `aps` dictionary of an APNs payload. - */ - interface CriticalSound { - - /** - * The critical alert flag. Set to `true` to enable the critical alert. - */ - critical?: boolean; - - /** - * The name of a sound file in the app's main bundle or in the `Library/Sounds` - * folder of the app's container directory. Specify the string "default" to play - * the system sound. - */ - name: string; - - /** - * The volume for the critical alert's sound. Must be a value between 0.0 - * (silent) and 1.0 (full volume). - */ - volume?: number; - } - - /** - * Represents options for features provided by the FCM SDK for iOS. - */ - interface ApnsFcmOptions { - - /** - * The label associated with the message's analytics data. - */ - analyticsLabel?: string; - - /** - * URL of an image to be displayed in the notification. - */ - imageUrl?: string; - } - - /** - * Represents platform-independent options for features provided by the FCM SDKs. - */ - interface FcmOptions { - - /** - * The label associated with the message's analytics data. - */ - analyticsLabel?: string; - } - - - /** - * A notification that can be included in {@link admin.messaging.Message}. - */ - interface Notification { - /** - * The title of the notification. - */ - title?: string; - /** - * The notification body - */ - body?: string; - /** - * URL of an image to be displayed in the notification. - */ - imageUrl?: string; - } - /** - * Represents the WebPush protocol options that can be included in an - * {@link admin.messaging.Message}. - */ - interface WebpushConfig { - - /** - * A collection of WebPush headers. Header values must be strings. - * - * See [WebPush specification](https://tools.ietf.org/html/rfc8030#section-5) - * for supported headers. - */ - headers?: { [key: string]: string }; - - /** - * A collection of data fields. - */ - data?: { [key: string]: string }; - - /** - * A WebPush notification payload to be included in the message. - */ - notification?: WebpushNotification; - - /** - * Options for features provided by the FCM SDK for Web. - */ - fcmOptions?: WebpushFcmOptions; - } - - /** Represents options for features provided by the FCM SDK for Web - * (which are not part of the Webpush standard). - */ - interface WebpushFcmOptions { - - /** - * The link to open when the user clicks on the notification. - * For all URL values, HTTPS is required. - */ - link?: string; - } - - /** - * Represents the WebPush-specific notification options that can be included in - * {@link admin.messaging.WebpushConfig}. This supports most of the standard - * options as defined in the Web Notification - * [specification](https://developer.mozilla.org/en-US/docs/Web/API/notification/Notification). - */ - interface WebpushNotification { - - /** - * Title text of the notification. - */ - title?: string; - - /** - * An array of notification actions representing the actions - * available to the user when the notification is presented. - */ - actions?: Array<{ - - /** - * An action available to the user when the notification is presented - */ - action: string; - - /** - * Optional icon for a notification action. - */ - icon?: string; - - /** - * Title of the notification action. - */ - title: string; - }>; - - /** - * URL of the image used to represent the notification when there is - * not enough space to display the notification itself. - */ - badge?: string; - - /** - * Body text of the notification. - */ - body?: string; - - /** - * Arbitrary data that you want associated with the notification. - * This can be of any data type. - */ - data?: any; - - /** - * The direction in which to display the notification. Must be one - * of `auto`, `ltr` or `rtl`. - */ - dir?: 'auto' | 'ltr' | 'rtl'; - - /** - * URL to the notification icon. - */ - icon?: string; - - /** - * URL of an image to be displayed in the notification. - */ - image?: string; - - /** - * The notification's language as a BCP 47 language tag. - */ - lang?: string; - - /** - * A boolean specifying whether the user should be notified after a - * new notification replaces an old one. Defaults to false. - */ - renotify?: boolean; - - /** - * Indicates that a notification should remain active until the user - * clicks or dismisses it, rather than closing automatically. - * Defaults to false. - */ - requireInteraction?: boolean; - - /** - * A boolean specifying whether the notification should be silent. - * Defaults to false. - */ - silent?: boolean; - - /** - * An identifying tag for the notification. - */ - tag?: string; - - /** - * Timestamp of the notification. Refer to - * https://developer.mozilla.org/en-US/docs/Web/API/notification/timestamp - * for details. - */ - timestamp?: number; - - /** - * A vibration pattern for the device's vibration hardware to emit - * when the notification fires. - */ - vibrate?: number | number[]; - [key: string]: any; - } - /** - * Interface representing an FCM legacy API data message payload. Data - * messages let developers send up to 4KB of custom key-value pairs. The - * keys and values must both be strings. Keys can be any custom string, - * except for the following reserved strings: - * - * * `"from"` - * * Anything starting with `"google."`. - * - * See [Build send requests](/docs/cloud-messaging/send-message) - * for code samples and detailed documentation. - */ - interface DataMessagePayload { - [key: string]: string; - } - - /** - * Interface representing an FCM legacy API notification message payload. - * Notification messages let developers send up to 4KB of predefined - * key-value pairs. Accepted keys are outlined below. - * - * See [Build send requests](/docs/cloud-messaging/send-message) - * for code samples and detailed documentation. - */ - interface NotificationMessagePayload { - tag?: string; - - /** - * The notification's body text. - * - * **Platforms:** iOS, Android, Web - */ - body?: string; - - /** - * The notification's icon. - * - * **Android:** Sets the notification icon to `myicon` for drawable resource - * `myicon`. If you don't send this key in the request, FCM displays the - * launcher icon specified in your app manifest. - * - * **Web:** The URL to use for the notification's icon. - * - * **Platforms:** Android, Web - */ - icon?: string; - - /** - * The value of the badge on the home screen app icon. - * - * If not specified, the badge is not changed. - * - * If set to `0`, the badge is removed. - * - * **Platforms:** iOS - */ - badge?: string; - - /** - * The notification icon's color, expressed in `#rrggbb` format. - * - * **Platforms:** Android - */ - color?: string; - - /** - * Identifier used to replace existing notifications in the notification drawer. - * - * If not specified, each request creates a new notification. - * - * If specified and a notification with the same tag is already being shown, - * the new notification replaces the existing one in the notification drawer. - * - * **Platforms:** Android - */ - sound?: string; - - /** - * The notification's title. - * - * **Platforms:** iOS, Android, Web - */ - title?: string; - - /** - * The key to the body string in the app's string resources to use to localize - * the body text to the user's current localization. - * - * **iOS:** Corresponds to `loc-key` in the APNs payload. See - * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * and - * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) - * for more information. - * - * **Android:** See - * [String Resources](http://developer.android.com/guide/topics/resources/string-resource.html) * for more information. - * - * **Platforms:** iOS, Android - */ - bodyLocKey?: string; - - /** - * Variable string values to be used in place of the format specifiers in - * `body_loc_key` to use to localize the body text to the user's current - * localization. - * - * The value should be a stringified JSON array. - * - * **iOS:** Corresponds to `loc-args` in the APNs payload. See - * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * and - * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) - * for more information. - * - * **Android:** See - * [Formatting and Styling](http://developer.android.com/guide/topics/resources/string-resource.html#FormattingAndStyling) - * for more information. - * - * **Platforms:** iOS, Android - */ - bodyLocArgs?: string; - - /** - * Action associated with a user click on the notification. If specified, an - * activity with a matching Intent Filter is launched when a user clicks on the - * notification. - * - * * **Platforms:** Android - */ - clickAction?: string; - - /** - * The key to the title string in the app's string resources to use to localize - * the title text to the user's current localization. - * - * **iOS:** Corresponds to `title-loc-key` in the APNs payload. See - * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * and - * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) - * for more information. - * - * **Android:** See - * [String Resources](http://developer.android.com/guide/topics/resources/string-resource.html) - * for more information. - * - * **Platforms:** iOS, Android - */ - titleLocKey?: string; - - /** - * Variable string values to be used in place of the format specifiers in - * `title_loc_key` to use to localize the title text to the user's current - * localization. - * - * The value should be a stringified JSON array. - * - * **iOS:** Corresponds to `title-loc-args` in the APNs payload. See - * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) - * and - * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) - * for more information. - * - * **Android:** See - * [Formatting and Styling](http://developer.android.com/guide/topics/resources/string-resource.html#FormattingAndStyling) - * for more information. - * - * **Platforms:** iOS, Android - */ - titleLocArgs?: string; - [key: string]: string | undefined; - } - - /** - * Interface representing a Firebase Cloud Messaging message payload. One or - * both of the `data` and `notification` keys are required. - * - * See - * [Build send requests](/docs/cloud-messaging/send-message) - * for code samples and detailed documentation. - */ - interface MessagingPayload { - - /** - * The data message payload. - */ - data?: admin.messaging.DataMessagePayload; - - /** - * The notification message payload. - */ - notification?: admin.messaging.NotificationMessagePayload; - } - /** - * Interface representing the options that can be provided when sending a - * message via the FCM legacy APIs. - * - * See [Build send requests](/docs/cloud-messaging/send-message) - * for code samples and detailed documentation. - */ - interface MessagingOptions { - - /** - * Whether or not the message should actually be sent. When set to `true`, - * allows developers to test a request without actually sending a message. When - * set to `false`, the message will be sent. - * - * **Default value:** `false` - */ - dryRun?: boolean; - - /** - * The priority of the message. Valid values are `"normal"` and `"high".` On - * iOS, these correspond to APNs priorities `5` and `10`. - * - * By default, notification messages are sent with high priority, and data - * messages are sent with normal priority. Normal priority optimizes the client - * app's battery consumption and should be used unless immediate delivery is - * required. For messages with normal priority, the app may receive the message - * with unspecified delay. - * - * When a message is sent with high priority, it is sent immediately, and the - * app can wake a sleeping device and open a network connection to your server. - * - * For more information, see - * [Setting the priority of a message](/docs/cloud-messaging/concept-options#setting-the-priority-of-a-message). - * - * **Default value:** `"high"` for notification messages, `"normal"` for data - * messages - */ - priority?: string; - - /** - * How long (in seconds) the message should be kept in FCM storage if the device - * is offline. The maximum time to live supported is four weeks, and the default - * value is also four weeks. For more information, see - * [Setting the lifespan of a message](/docs/cloud-messaging/concept-options#ttl). - * - * **Default value:** `2419200` (representing four weeks, in seconds) - */ - timeToLive?: number; - - /** - * String identifying a group of messages (for example, "Updates Available") - * that can be collapsed, so that only the last message gets sent when delivery - * can be resumed. This is used to avoid sending too many of the same messages - * when the device comes back online or becomes active. - * - * There is no guarantee of the order in which messages get sent. - * - * A maximum of four different collapse keys is allowed at any given time. This - * means FCM server can simultaneously store four different - * send-to-sync messages per client app. If you exceed this number, there is no - * guarantee which four collapse keys the FCM server will keep. - * - * **Default value:** None - */ - collapseKey?: string; - - /** - * On iOS, use this field to represent `mutable-content` in the APNs payload. - * When a notification is sent and this is set to `true`, the content of the - * notification can be modified before it is displayed, using a - * [Notification Service app extension](https://developer.apple.com/reference/usernotifications/unnotificationserviceextension) - * - * On Android and Web, this parameter will be ignored. - * - * **Default value:** `false` - */ - mutableContent?: boolean; - - /** - * On iOS, use this field to represent `content-available` in the APNs payload. - * When a notification or data message is sent and this is set to `true`, an - * inactive client app is awoken. On Android, data messages wake the app by - * default. On Chrome, this flag is currently not supported. - * - * **Default value:** `false` - */ - contentAvailable?: boolean; - - /** - * The package name of the application which the registration tokens must match - * in order to receive the message. - * - * **Default value:** None - */ - restrictedPackageName?: string; - [key: string]: any | undefined; - } - - /** - * Interface representing the status of a message sent to an individual device - * via the FCM legacy APIs. - * - * See - * [Send to individual devices](/docs/cloud-messaging/admin/send-messages#send_to_individual_devices) - * for code samples and detailed documentation. - */ - interface MessagingDeviceResult { - - /** - * The error that occurred when processing the message for the recipient. - */ - error?: admin.FirebaseError; - - /** - * A unique ID for the successfully processed message. - */ - messageId?: string; - - /** - * The canonical registration token for the client app that the message was - * processed and sent to. You should use this value as the registration token - * for future requests. Otherwise, future messages might be rejected. - */ - canonicalRegistrationToken?: string; - } - - /** - * Interface representing the server response from the legacy - * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendToDevice `sendToDevice()`} method. - * - * See - * [Send to individual devices](/docs/cloud-messaging/admin/send-messages#send_to_individual_devices) - * for code samples and detailed documentation. - */ - interface MessagingDevicesResponse { - - /** - * The number of results that contain a canonical registration token. A - * canonical registration token is the registration token corresponding to the - * last registration requested by the client app. This is the token that you - * should use when sending future messages to the device. - * - * You can access the canonical registration tokens within the - * [`results`](#results) property. - */ - canonicalRegistrationTokenCount: number; - - /** - * The number of messages that could not be processed and resulted in an error. - */ - failureCount: number; - - /** - * The unique ID number identifying this multicast message. - */ - multicastId: number; - - /** - * An array of `MessagingDeviceResult` objects representing the status of the - * processed messages. The objects are listed in the same order as in the - * request. That is, for each registration token in the request, its result has - * the same index in this array. If only a single registration token is - * provided, this array will contain a single object. - */ - results: admin.messaging.MessagingDeviceResult[]; - - /** - * The number of messages that were successfully processed and sent. - */ - successCount: number; - } - /** - * Interface representing the server response from the - * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendToDeviceGroup `sendToDeviceGroup()`} - * method. - * - * See - * [Send messages to device groups](/docs/cloud-messaging/send-message?authuser=0#send_messages_to_device_groups) - * for code samples and detailed documentation. - */ - interface MessagingDeviceGroupResponse { - - /** - * The number of messages that could not be processed and resulted in an error. - */ - successCount: number; - - /** - * The number of messages that could not be processed and resulted in an error. - */ - failureCount: number; - - /** - * An array of registration tokens that failed to receive the message. - */ - failedRegistrationTokens: string[]; - } - - /** - * Interface representing the server response from the legacy - * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendToTopic `sendToTopic()`} method. - * - * See - * [Send to a topic](/docs/cloud-messaging/admin/send-messages#send_to_a_topic) - * for code samples and detailed documentation. - */ - interface MessagingTopicResponse { - - /** - * The message ID for a successfully received request which FCM will attempt to - * deliver to all subscribed devices. - */ - messageId: number; - } - - /** - * Interface representing the server response from the legacy - * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendToCondition `sendToCondition()`} method. - * - * See - * [Send to a condition](/docs/cloud-messaging/admin/send-messages#send_to_a_condition) - * for code samples and detailed documentation. - */ - interface MessagingConditionResponse { - - /** - * The message ID for a successfully received request which FCM will attempt to - * deliver to all subscribed devices. - */ - messageId: number; - } - - /** - * Interface representing the server response from the - * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#subscribeToTopic `subscribeToTopic()`} and - * {@link - * admin.messaging.Messaging#unsubscribeFromTopic - * `unsubscribeFromTopic()`} - * methods. - * - * See - * [Manage topics from the server](/docs/cloud-messaging/manage-topics) - * for code samples and detailed documentation. - */ - interface MessagingTopicManagementResponse { - - /** - * The number of registration tokens that could not be subscribed to the topic - * and resulted in an error. - */ - failureCount: number; - - /** - * The number of registration tokens that were successfully subscribed to the - * topic. - */ - successCount: number; - - /** - * An array of errors corresponding to the provided registration token(s). The - * length of this array will be equal to [`failureCount`](#failureCount). - */ - errors: admin.FirebaseArrayIndexError[]; - } - - /** - * Interface representing the server response from the - * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendAll `sendAll()`} and - * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendMulticast `sendMulticast()`} methods. - */ - interface BatchResponse { - - /** - * An array of responses, each corresponding to a message. - */ - responses: admin.messaging.SendResponse[]; - - /** - * The number of messages that were successfully handed off for sending. - */ - successCount: number; - - /** - * The number of messages that resulted in errors when sending. - */ - failureCount: number; - } - /** - * Interface representing the status of an individual message that was sent as - * part of a batch request. - */ - interface SendResponse { - - /** - * A boolean indicating if the message was successfully handed off to FCM or - * not. When true, the `messageId` attribute is guaranteed to be set. When - * false, the `error` attribute is guaranteed to be set. - */ - success: boolean; - - /** - * A unique message ID string, if the message was handed off to FCM for - * delivery. - * - */ - messageId?: string; - - /** - * An error, if the message was not handed off to FCM successfully. - */ - error?: admin.FirebaseError; - } - - /** - * Gets the {@link admin.messaging.Messaging `Messaging`} service for the - * current app. - * - * @example - * ```javascript - * var messaging = app.messaging(); - * // The above is shorthand for: - * // var messaging = admin.messaging(app); - * ``` - * - * @return The `Messaging` service for the current app. - */ - interface Messaging { - /** - * The {@link admin.app.App app} associated with the current `Messaging` service - * instance. - * - * @example - * ```javascript - * var app = messaging.app; - * ``` - */ - app: admin.app.App; - - /** - * Sends the given message via FCM. - * - * @param message The message payload. - * @param dryRun Whether to send the message in the dry-run - * (validation only) mode. - * @return A promise fulfilled with a unique message ID - * string after the message has been successfully handed off to the FCM - * service for delivery. - */ - send(message: admin.messaging.Message, dryRun?: boolean): Promise; - - /** - * Sends all the messages in the given array via Firebase Cloud Messaging. - * Employs batching to send the entire list as a single RPC call. Compared - * to the `send()` method, this method is a significantly more efficient way - * to send multiple messages. - * - * The responses list obtained from the return value - * corresponds to the order of tokens in the `MulticastMessage`. An error - * from this method indicates a total failure -- i.e. none of the messages in - * the list could be sent. Partial failures are indicated by a `BatchResponse` - * return value. - * - * @param messages A non-empty array - * containing up to 500 messages. - * @param dryRun Whether to send the messages in the dry-run - * (validation only) mode. - * @return A Promise fulfilled with an object representing the result of the - * send operation. - */ - sendAll( - messages: Array, - dryRun?: boolean - ): Promise; - - /** - * Sends the given multicast message to all the FCM registration tokens - * specified in it. - * - * This method uses the `sendAll()` API under the hood to send the given - * message to all the target recipients. The responses list obtained from the - * return value corresponds to the order of tokens in the `MulticastMessage`. - * An error from this method indicates a total failure -- i.e. the message was - * not sent to any of the tokens in the list. Partial failures are indicated by - * a `BatchResponse` return value. - * - * @param message A multicast message - * containing up to 500 tokens. - * @param dryRun Whether to send the message in the dry-run - * (validation only) mode. - * @return A Promise fulfilled with an object representing the result of the - * send operation. - */ - sendMulticast( - message: admin.messaging.MulticastMessage, - dryRun?: boolean - ): Promise; - - /** - * Sends an FCM message to a single device corresponding to the provided - * registration token. - * - * See - * [Send to individual devices](/docs/cloud-messaging/admin/legacy-fcm#send_to_individual_devices) - * for code samples and detailed documentation. Takes either a - * `registrationToken` to send to a single device or a - * `registrationTokens` parameter containing an array of tokens to send - * to multiple devices. - * - * @param registrationToken A device registration token or an array of - * device registration tokens to which the message should be sent. - * @param payload The message payload. - * @param options Optional options to - * alter the message. - * - * @return A promise fulfilled with the server's response after the message - * has been sent. - */ - sendToDevice( - registrationToken: string | string[], - payload: admin.messaging.MessagingPayload, - options?: admin.messaging.MessagingOptions - ): Promise; - - /** - * Sends an FCM message to a device group corresponding to the provided - * notification key. - * - * See - * [Send to a device group](/docs/cloud-messaging/admin/legacy-fcm#send_to_a_device_group) - * for code samples and detailed documentation. - * - * @param notificationKey The notification key for the device group to - * which to send the message. - * @param payload The message payload. - * @param options Optional options to - * alter the message. - * - * @return A promise fulfilled with the server's response after the message - * has been sent. - */ - sendToDeviceGroup( - notificationKey: string, - payload: admin.messaging.MessagingPayload, - options?: admin.messaging.MessagingOptions - ): Promise; - - /** - * Sends an FCM message to a topic. - * - * See - * [Send to a topic](/docs/cloud-messaging/admin/legacy-fcm#send_to_a_topic) - * for code samples and detailed documentation. - * - * @param topic The topic to which to send the message. - * @param payload The message payload. - * @param options Optional options to - * alter the message. - * - * @return A promise fulfilled with the server's response after the message - * has been sent. - */ - sendToTopic( - topic: string, - payload: admin.messaging.MessagingPayload, - options?: admin.messaging.MessagingOptions - ): Promise; - - /** - * Sends an FCM message to a condition. - * - * See - * [Send to a condition](/docs/cloud-messaging/admin/legacy-fcm#send_to_a_condition) - * for code samples and detailed documentation. - * - * @param condition The condition determining to which topics to send - * the message. - * @param payload The message payload. - * @param options Optional options to - * alter the message. - * - * @return A promise fulfilled with the server's response after the message - * has been sent. - */ - sendToCondition( - condition: string, - payload: admin.messaging.MessagingPayload, - options?: admin.messaging.MessagingOptions - ): Promise; - - /** - * Subscribes a device to an FCM topic. - * - * See [Subscribe to a - * topic](/docs/cloud-messaging/manage-topics#suscribe_and_unsubscribe_using_the) - * for code samples and detailed documentation. Optionally, you can provide an - * array of tokens to subscribe multiple devices. - * - * @param registrationTokens A token or array of registration tokens - * for the devices to subscribe to the topic. - * @param topic The topic to which to subscribe. - * - * @return A promise fulfilled with the server's response after the device has been - * subscribed to the topic. - */ - subscribeToTopic( - registrationTokens: string | string[], - topic: string - ): Promise; - - /** - * Unsubscribes a device from an FCM topic. - * - * See [Unsubscribe from a - * topic](/docs/cloud-messaging/admin/manage-topic-subscriptions#unsubscribe_from_a_topic) - * for code samples and detailed documentation. Optionally, you can provide an - * array of tokens to unsubscribe multiple devices. - * - * @param registrationTokens A device registration token or an array of - * device registration tokens to unsubscribe from the topic. - * @param topic The topic from which to unsubscribe. - * - * @return A promise fulfilled with the server's response after the device has been - * unsubscribed from the topic. - */ - unsubscribeFromTopic( - registrationTokens: string | string[], - topic: string - ): Promise; - } -} - -declare namespace admin.storage { - - /** - * The default `Storage` service if no - * app is provided or the `Storage` service associated with the provided - * app. - */ - interface Storage { - /** - * Optional app whose `Storage` service to - * return. If not provided, the default `Storage` service will be returned. - */ - app: admin.app.App; - /** - * @returns A [Bucket](https://cloud.google.com/nodejs/docs/reference/storage/latest/Bucket) - * instance as defined in the `@google-cloud/storage` package. - */ - bucket(name?: string): Bucket; - } -} - -declare namespace admin.firestore { - export import v1beta1 = _firestore.v1beta1; - export import v1 = _firestore.v1; - - export import CollectionReference = _firestore.CollectionReference; - export import DocumentData = _firestore.DocumentData; - export import DocumentReference = _firestore.DocumentReference; - export import DocumentSnapshot = _firestore.DocumentSnapshot; - export import FieldPath = _firestore.FieldPath; - export import FieldValue = _firestore.FieldValue; - export import Firestore = _firestore.Firestore; - export import GeoPoint = _firestore.GeoPoint; - export import Query = _firestore.Query; - export import QueryDocumentSnapshot = _firestore.QueryDocumentSnapshot; - export import QuerySnapshot = _firestore.QuerySnapshot; - export import Timestamp = _firestore.Timestamp; - export import Transaction = _firestore.Transaction; - export import WriteBatch = _firestore.WriteBatch; - export import WriteResult = _firestore.WriteResult; - - export import setLogFunction = _firestore.setLogFunction; -} - -declare namespace admin.instanceId { - /** - * Gets the {@link admin.instanceId.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. - */ - interface InstanceId { - app: admin.app.App; - - /** - * Deletes the specified instance ID and the associated data from Firebase. - * - * Note that Google Analytics for Firebase uses its own form of Instance ID to - * keep track of analytics data. Therefore deleting a Firebase Instance ID does - * not delete Analytics data. See - * [Delete an Instance ID](/support/privacy/manage-iids#delete_an_instance_id) - * for more information. - * - * @param instanceId The instance ID to be deleted. - * - * @return A promise fulfilled when the instance ID is deleted. - */ - deleteInstanceId(instanceId: string): Promise; - } -} - -declare namespace admin.projectManagement { - - /** - * A SHA-1 or SHA-256 certificate. - * - * Do not call this constructor directly. Instead, use - * [`projectManagement.shaCertificate()`](admin.projectManagement.ProjectManagement#shaCertificate). - */ - interface ShaCertificate { - - /** - * The SHA certificate type. - * - * @example - * ```javascript - * var certType = shaCertificate.certType; - * ``` - */ - certType: ('sha1' | 'sha256'); - - /** - * The SHA-1 or SHA-256 hash for this certificate. - * - * @example - * ```javascript - * var shaHash = shaCertificate.shaHash; - * ``` - */ - shaHash: string; - - /** - * The fully-qualified resource name that identifies this sha-key. - * - * This is useful when manually constructing requests for Firebase's public API. - * - * @example - * ```javascript - * var resourceName = shaCertificate.resourceName; - * ``` - */ - resourceName?: string; - } - - /** - * Metadata about a Firebase app. - */ - interface AppMetadata { - - /** - * The globally unique, Firebase-assigned identifier of the app. - * - * @example - * ```javascript - * var appId = appMetadata.appId; - * ``` - */ - appId: string; - - /** - * The optional user-assigned display name of the app. - * - * @example - * ```javascript - * var displayName = appMetadata.displayName; - * ``` - */ - displayName?: string; - - /** - * The development platform of the app. Supporting Android and iOS app platforms. - * - * @example - * ```javascript - * var platform = AppPlatform.ANDROID; - * ``` - */ - platform: AppPlatform; - - /** - * The globally unique, user-assigned ID of the parent project for the app. - * - * @example - * ```javascript - * var projectId = appMetadata.projectId; - * ``` - */ - projectId: string; - - /** - * The fully-qualified resource name that identifies this app. - * - * This is useful when manually constructing requests for Firebase's public API. - * - * @example - * ```javascript - * var resourceName = androidAppMetadata.resourceName; - * ``` - */ - resourceName: string; - } - - /** - * Platforms with which a Firebase App can be associated. - */ - enum AppPlatform { - - /** - * Unknown state. This is only used for distinguishing unset values. - */ - PLATFORM_UNKNOWN = 'PLATFORM_UNKNOWN', - - /** - * The Firebase App is associated with iOS. - */ - IOS = 'IOS', - - /** - * The Firebase App is associated with Android. - */ - ANDROID = 'ANDROID', - } - - /** - * Metadata about a Firebase Android App. - */ - interface AndroidAppMetadata extends AppMetadata { - - platform: AppPlatform.ANDROID; - - /** - * The canonical package name of the Android App, as would appear in the Google Play Developer - * Console. - * - * @example - * ```javascript - * var packageName = androidAppMetadata.packageName; - * ``` - */ - packageName: string; - } - - /** - * Metadata about a Firebase iOS App. - */ - interface IosAppMetadata extends AppMetadata { - platform: AppPlatform.IOS; - - /** - * The canonical bundle ID of the iOS App as it would appear in the iOS App Store. - * - * @example - * ```javascript - * var bundleId = iosAppMetadata.bundleId; - *``` - */ - bundleId: string; - } - - /** - * A reference to a Firebase Android app. - * - * Do not call this constructor directly. Instead, use - * [`projectManagement.androidApp()`](admin.projectManagement.ProjectManagement#androidApp). - */ - interface AndroidApp { - appId: string; - - /** - * Retrieves metadata about this Android app. - * - * @return A promise that resolves to the retrieved metadata about this Android app. - */ - getMetadata(): Promise; - - /** - * Sets the optional user-assigned display name of the app. - * - * @param newDisplayName The new display name to set. - * - * @return A promise that resolves when the display name has been set. - */ - setDisplayName(newDisplayName: string): Promise; - - /** - * Gets the list of SHA certificates associated with this Android app in Firebase. - * - * @return The list of SHA-1 and SHA-256 certificates associated with this Android app in - * Firebase. - */ - getShaCertificates(): Promise; - - /** - * Adds the given SHA certificate to this Android app. - * - * @param certificateToAdd The SHA certificate to add. - * - * @return A promise that resolves when the given certificate - * has been added to the Android app. - */ - addShaCertificate(certificateToAdd: ShaCertificate): Promise; - - /** - * Deletes the specified SHA certificate from this Android app. - * - * @param certificateToDelete The SHA certificate to delete. - * - * @return A promise that resolves when the specified - * certificate has been removed from the Android app. - */ - deleteShaCertificate(certificateToRemove: ShaCertificate): Promise; - - /** - * Gets the configuration artifact associated with this app. - * - * @return A promise that resolves to the Android app's - * Firebase config file, in UTF-8 string format. This string is typically - * intended to be written to a JSON file that gets shipped with your Android - * app. - */ - getConfig(): Promise; - } - - /** - * A reference to a Firebase iOS app. - * - * Do not call this constructor directly. Instead, use - * [`projectManagement.iosApp()`](admin.projectManagement.ProjectManagement#iosApp). - */ - interface IosApp { - appId: string; - - /** - * Retrieves metadata about this iOS app. - * - * @return {!Promise} A promise that - * resolves to the retrieved metadata about this iOS app. - */ - getMetadata(): Promise; - - /** - * Sets the optional user-assigned display name of the app. - * - * @param newDisplayName The new display name to set. - * - * @return A promise that resolves when the display name has - * been set. - */ - setDisplayName(newDisplayName: string): Promise; - - /** - * Gets the configuration artifact associated with this app. - * - * @return A promise that resolves to the iOS app's Firebase - * config file, in UTF-8 string format. This string is typically intended to - * be written to a plist file that gets shipped with your iOS app. - */ - getConfig(): Promise; - } - - /** - * The Firebase ProjectManagement service interface. - * - * Do not call this constructor directly. Instead, use - * [`admin.projectManagement()`](admin.projectManagement#projectManagement). - */ - interface ProjectManagement { - app: admin.app.App; - - /** - * Lists up to 100 Firebase apps associated with this Firebase project. - * - * @return A promise that resolves to the metadata list of the apps. - */ - listAppMetadata(): Promise; - - /** - * Lists up to 100 Firebase Android apps associated with this Firebase project. - * - * @return The list of Android apps. - */ - listAndroidApps(): Promise; - - /** - * Lists up to 100 Firebase iOS apps associated with this Firebase project. - * - * @return The list of iOS apps. - */ - listIosApps(): Promise; - - /** - * Creates an `AndroidApp` object, referencing the specified Android app within - * this Firebase project. - * - * This method does not perform an RPC. - * - * @param appId The `appId` of the Android app to reference. - * - * @return An `AndroidApp` object that references the specified Firebase Android app. - */ - androidApp(appId: string): admin.projectManagement.AndroidApp; - - /** - * Update the display name of this Firebase project. - * - * @param newDisplayName The new display name to be updated. - * - * @return A promise that resolves when the project display name has been updated. - */ - setDisplayName(newDisplayName: string): Promise; - - /** - * Creates an `iOSApp` object, referencing the specified iOS app within - * this Firebase project. - * - * This method does not perform an RPC. - * - * @param appId The `appId` of the iOS app to reference. - * - * @return An `iOSApp` object that references the specified Firebase iOS app. - */ - iosApp(appId: string): admin.projectManagement.IosApp; - - /** - * Creates a `ShaCertificate` object. - * - * This method does not perform an RPC. - * - * @param shaHash The SHA-1 or SHA-256 hash for this certificate. - * - * @return A `ShaCertificate` object contains the specified SHA hash. - */ - shaCertificate(shaHash: string): admin.projectManagement.ShaCertificate; - - /** - * Creates a new Firebase Android app associated with this Firebase project. - * - * @param packageName The canonical package name of the Android App, - * as would appear in the Google Play Developer Console. - * @param displayName An optional user-assigned display name for this - * new app. - * - * @return A promise that resolves to the newly created Android app. - */ - createAndroidApp( - packageName: string, displayName?: string): Promise; - - /** - * Creates a new Firebase iOS app associated with this Firebase project. - * - * @param bundleId The iOS app bundle ID to use for this new app. - * @param displayName An optional user-assigned display name for this - * new app. - * - * @return A promise that resolves to the newly created iOS app. - */ - createIosApp(bundleId: string, displayName?: string): Promise; - } +declare namespace admin.projectManagement { + export import ShaCertificate = _projectManagement.admin.projectManagement.ShaCertificate; + export import AppMetadata = _projectManagement.admin.projectManagement.AppMetadata; + export import AppPlatform = _projectManagement.admin.projectManagement.AppPlatform; + export import AndroidAppMetadata = _projectManagement.admin.projectManagement.AndroidAppMetadata; + export import IosAppMetadata = _projectManagement.admin.projectManagement.IosAppMetadata; + export import AndroidApp = _projectManagement.admin.projectManagement.AndroidApp; + export import IosApp = _projectManagement.admin.projectManagement.IosApp; + export import ProjectManagement = _projectManagement.admin.projectManagement.ProjectManagement; } declare namespace admin.securityRules { - /** - * A source file containing some Firebase security rules. The content includes raw - * source code including text formatting, indentation and comments. Use the - * [`securityRules.createRulesFileFromSource()`](admin.securityRules.SecurityRules#createRulesFileFromSource) - * method to create new instances of this type. - */ - interface RulesFile { - readonly name: string; - readonly content: string; - } - - /** - * Required metadata associated with a ruleset. - */ - interface RulesetMetadata { - /** - * Name of the `Ruleset` as a short string. This can be directly passed into APIs - * like [`securityRules.getRuleset()`](admin.securityRules.SecurityRules#getRuleset) - * and [`securityRules.deleteRuleset()`](admin.securityRules.SecurityRules#deleteRuleset). - */ - readonly name: string; - - /** - * Creation time of the `Ruleset` as a UTC timestamp string. - */ - readonly createTime: string; - } - - /** - * A set of Firebase security rules. - */ - interface Ruleset extends RulesetMetadata { - readonly source: RulesFile[]; - } - - interface RulesetMetadataList { - /** - * A batch of ruleset metadata. - */ - readonly rulesets: RulesetMetadata[]; - - /** - * The next page token if available. This is needed to retrieve the next batch. - */ - readonly nextPageToken?: string; - } - - /** - * The Firebase `SecurityRules` service interface. - * - * Do not call this constructor directly. Instead, use - * [`admin.securityRules()`](admin.securityRules#securityRules). - */ - interface SecurityRules { - app: admin.app.App; - - /** - * Creates a {@link admin.securityRules.RulesFile `RuleFile`} with the given name - * and source. Throws an error if any of the arguments are invalid. This is a local - * operation, and does not involve any network API calls. - * - * @example - * ```javascript - * const source = '// Some rules source'; - * const rulesFile = admin.securityRules().createRulesFileFromSource( - * 'firestore.rules', source); - * ``` - * - * @param name Name to assign to the rules file. This is usually a short file name that - * helps identify the file in a ruleset. - * @param source Contents of the rules file. - * @return A new rules file instance. - */ - createRulesFileFromSource(name: string, source: string | Buffer): RulesFile; - - /** - * Creates a new {@link admin.securityRules.Ruleset `Ruleset`} from the given - * {@link admin.securityRules.RulesFile `RuleFile`}. - * - * @param file Rules file to include in the new `Ruleset`. - * @returns A promise that fulfills with the newly created `Ruleset`. - */ - createRuleset(file: RulesFile): Promise; - - /** - * Gets the {@link admin.securityRules.Ruleset `Ruleset`} identified by the given - * name. The input name should be the short name string without the project ID - * prefix. For example, to retrieve the `projects/project-id/rulesets/my-ruleset`, - * pass the short name "my-ruleset". Rejects with a `not-found` error if the - * specified `Ruleset` cannot be found. - * - * @param name Name of the `Ruleset` to retrieve. - * @return A promise that fulfills with the specified `Ruleset`. - */ - getRuleset(name: string): Promise; - - /** - * Deletes the {@link admin.securityRules.Ruleset `Ruleset`} identified by the given - * name. The input name should be the short name string without the project ID - * prefix. For example, to delete the `projects/project-id/rulesets/my-ruleset`, - * pass the short name "my-ruleset". Rejects with a `not-found` error if the - * specified `Ruleset` cannot be found. - * - * @param name Name of the `Ruleset` to delete. - * @return A promise that fulfills when the `Ruleset` is deleted. - */ - deleteRuleset(name: string): Promise; - - /** - * Retrieves a page of ruleset metadata. - * - * @param pageSize The page size, 100 if undefined. This is also the maximum allowed - * limit. - * @param nextPageToken The next page token. If not specified, returns rulesets - * starting without any offset. - * @return A promise that fulfills with a page of rulesets. - */ - listRulesetMetadata( - pageSize?: number, nextPageToken?: string): Promise; - - /** - * Gets the {@link admin.securityRules.Ruleset `Ruleset`} currently applied to - * Cloud Firestore. Rejects with a `not-found` error if no ruleset is applied - * on Firestore. - * - * @return A promise that fulfills with the Firestore ruleset. - */ - getFirestoreRuleset(): Promise; - - /** - * Creates a new {@link admin.securityRules.Ruleset `Ruleset`} from the given - * source, and applies it to Cloud Firestore. - * - * @param source Rules source to apply. - * @return A promise that fulfills when the ruleset is created and released. - */ - releaseFirestoreRulesetFromSource(source: string | Buffer): Promise; - - /** - * Applies the specified {@link admin.securityRules.Ruleset `Ruleset`} ruleset - * to Cloud Firestore. - * - * @param ruleset Name of the ruleset to apply or a `RulesetMetadata` object - * containing the name. - * @return A promise that fulfills when the ruleset is released. - */ - releaseFirestoreRuleset(ruleset: string | RulesetMetadata): Promise; - - /** - * Gets the {@link admin.securityRules.Ruleset `Ruleset`} currently applied to a - * Cloud Storage bucket. Rejects with a `not-found` error if no ruleset is applied - * on the bucket. - * - * @param bucket Optional name of the Cloud Storage bucket to be retrieved. If not - * specified, retrieves the ruleset applied on the default bucket configured via - * `AppOptions`. - * @return A promise that fulfills with the Cloud Storage ruleset. - */ - getStorageRuleset(bucket?: string): Promise; - - /** - * Creates a new {@link admin.securityRules.Ruleset `Ruleset`} from the given - * source, and applies it to a Cloud Storage bucket. - * - * @param source Rules source to apply. - * @param bucket Optional name of the Cloud Storage bucket to apply the rules on. If - * not specified, applies the ruleset on the default bucket configured via - * {@link admin.AppOptions `AppOptions`}. - * @return A promise that fulfills when the ruleset is created and released. - */ - releaseStorageRulesetFromSource( - source: string | Buffer, bucket?: string): Promise; - - /** - * Applies the specified {@link admin.securityRules.Ruleset `Ruleset`} ruleset - * to a Cloud Storage bucket. - * - * @param ruleset Name of the ruleset to apply or a `RulesetMetadata` object - * containing the name. - * @param bucket Optional name of the Cloud Storage bucket to apply the rules on. If - * not specified, applies the ruleset on the default bucket configured via - * {@link admin.AppOptions `AppOptions`}. - * @return A promise that fulfills when the ruleset is released. - */ - releaseStorageRuleset( - ruleset: string | RulesetMetadata, bucket?: string): Promise; - } + export import RulesFile = _securityRules.admin.securityRules.RulesFile; + export import RulesetMetadata = _securityRules.admin.securityRules.RulesetMetadata; + export import Ruleset = _securityRules.admin.securityRules.Ruleset; + export import RulesetMetadataList = _securityRules.admin.securityRules.RulesetMetadataList; + export import SecurityRules = _securityRules.admin.securityRules.SecurityRules; } declare module 'firebase-admin' { diff --git a/src/instance-id.d.ts b/src/instance-id.d.ts new file mode 100644 index 0000000000..34269be5b0 --- /dev/null +++ b/src/instance-id.d.ts @@ -0,0 +1,36 @@ +import * as _admin from './index.d'; + +export namespace admin.instanceId { + /** + * 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. + */ + interface InstanceId { + app: _admin.app.App; + + /** + * Deletes the specified instance ID and the associated data from Firebase. + * + * Note that Google Analytics for Firebase uses its own form of Instance ID to + * keep track of analytics data. Therefore deleting a Firebase Instance ID does + * not delete Analytics data. See + * [Delete an Instance ID](/support/privacy/manage-iids#delete_an_instance_id) + * for more information. + * + * @param instanceId The instance ID to be deleted. + * + * @return A promise fulfilled when the instance ID is deleted. + */ + deleteInstanceId(instanceId: string): Promise; + } +} diff --git a/src/messaging.d.ts b/src/messaging.d.ts new file mode 100644 index 0000000000..da8b79e713 --- /dev/null +++ b/src/messaging.d.ts @@ -0,0 +1,1331 @@ +import * as _admin from './index.d'; + +type BaseMessage = { + data?: { [key: string]: string }; + notification?: admin.messaging.Notification; + android?: admin.messaging.AndroidConfig; + webpush?: admin.messaging.WebpushConfig; + apns?: admin.messaging.ApnsConfig; + fcmOptions?: admin.messaging.FcmOptions; +}; + +interface TokenMessage extends BaseMessage { + token: string; +} + +interface TopicMessage extends BaseMessage { + topic: string; +} + +interface ConditionMessage extends BaseMessage { + condition: string; +} + +export namespace admin.messaging { + type Message = TokenMessage | TopicMessage | ConditionMessage; + + interface MulticastMessage extends BaseMessage { + tokens: string[]; + } + + /** + * Represents the Android-specific options that can be included in an + * {@link admin.messaging.Message}. + */ + interface AndroidConfig { + + /** + * Collapse key for the message. Collapse key serves as an identifier for a + * group of messages that can be collapsed, so that only the last message gets + * sent when delivery can be resumed. A maximum of four different collapse keys + * may be active at any given time. + */ + collapseKey?: string; + + /** + * Priority of the message. Must be either `normal` or `high`. + */ + priority?: ('high' | 'normal'); + + /** + * Time-to-live duration of the message in milliseconds. + */ + ttl?: number; + + /** + * Package name of the application where the registration tokens must match + * in order to receive the message. + */ + restrictedPackageName?: string; + + /** + * A collection of data fields to be included in the message. All values must + * be strings. When provided, overrides any data fields set on the top-level + * `admin.messaging.Message`.} + */ + data?: { [key: string]: string }; + + /** + * Android notification to be included in the message. + */ + notification?: AndroidNotification; + + /** + * Options for features provided by the FCM SDK for Android. + */ + fcmOptions?: AndroidFcmOptions; + } + + /** + * Represents the Android-specific notification options that can be included in + * {@link admin.messaging.AndroidConfig}. + */ + interface AndroidNotification { + + /** + * Title of the Android notification. When provided, overrides the title set via + * `admin.messaging.Notification`. + */ + title?: string; + + /** + * Body of the Android notification. When provided, overrides the body set via + * `admin.messaging.Notification`. + */ + body?: string; + + /** + * Icon resource for the Android notification. + */ + icon?: string; + + /** + * Notification icon color in `#rrggbb` format. + */ + color?: string; + + /** + * File name of the sound to be played when the device receives the + * notification. + */ + sound?: string; + + /** + * Notification tag. This is an identifier used to replace existing + * notifications in the notification drawer. If not specified, each request + * creates a new notification. + */ + tag?: string; + + /** + * URL of an image to be displayed in the notification. + */ + imageUrl?: string; + + /** + * Action associated with a user click on the notification. If specified, an + * activity with a matching Intent Filter is launched when a user clicks on the + * notification. + */ + clickAction?: string; + + /** + * Key of the body string in the app's string resource to use to localize the + * body text. + * + */ + bodyLocKey?: string; + + /** + * An array of resource keys that will be used in place of the format + * specifiers in `bodyLocKey`. + */ + bodyLocArgs?: string[]; + + /** + * Key of the title string in the app's string resource to use to localize the + * title text. + */ + titleLocKey?: string; + + /** + * An array of resource keys that will be used in place of the format + * specifiers in `titleLocKey`. + */ + titleLocArgs?: string[]; + + /** + * The Android notification channel ID (new in Android O). The app must create + * a channel with this channel ID before any notification with this channel ID + * can be received. If you don't send this channel ID in the request, or if the + * channel ID provided has not yet been created by the app, FCM uses the channel + * ID specified in the app manifest. + */ + channelId?: string; + + /** + * Sets the "ticker" text, which is sent to accessibility services. Prior to + * API level 21 (Lollipop), sets the text that is displayed in the status bar + * when the notification first arrives. + */ + ticker?: string; + + /** + * When set to `false` or unset, the notification is automatically dismissed when + * the user clicks it in the panel. When set to `true`, the notification persists + * even when the user clicks it. + */ + sticky?: boolean; + + /** + * For notifications that inform users about events with an absolute time reference, sets + * the time that the event in the notification occurred. Notifications + * in the panel are sorted by this time. + */ + eventTimestamp?: Date; + + /** + * Sets whether or not this notification is relevant only to the current device. + * Some notifications can be bridged to other devices for remote display, such as + * a Wear OS watch. This hint can be set to recommend this notification not be bridged. + * See [Wear OS guides](https://developer.android.com/training/wearables/notifications/bridger#existing-method-of-preventing-bridging) + */ + localOnly?: boolean; + + /** + * Sets the relative priority for this notification. Low-priority notifications + * may be hidden from the user in certain situations. Note this priority differs + * from `AndroidMessagePriority`. This priority is processed by the client after + * the message has been delivered. Whereas `AndroidMessagePriority` is an FCM concept + * that controls when the message is delivered. + */ + priority?: ('min' | 'low' | 'default' | 'high' | 'max'); + + /** + * Sets the vibration pattern to use. Pass in an array of milliseconds to + * turn the vibrator on or off. The first value indicates the duration to wait before + * turning the vibrator on. The next value indicates the duration to keep the + * vibrator on. Subsequent values alternate between duration to turn the vibrator + * off and to turn the vibrator on. If `vibrate_timings` is set and `default_vibrate_timings` + * is set to `true`, the default value is used instead of the user-specified `vibrate_timings`. + */ + vibrateTimingsMillis?: number[]; + + /** + * If set to `true`, use the Android framework's default vibrate pattern for the + * notification. Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). + * If `default_vibrate_timings` is set to `true` and `vibrate_timings` is also set, + * the default value is used instead of the user-specified `vibrate_timings`. + */ + defaultVibrateTimings?: boolean; + + /** + * If set to `true`, use the Android framework's default sound for the notification. + * Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). + */ + defaultSound?: boolean; + + /** + * Settings to control the notification's LED blinking rate and color if LED is + * available on the device. The total blinking time is controlled by the OS. + */ + lightSettings?: LightSettings; + + /** + * If set to `true`, use the Android framework's default LED light settings + * for the notification. Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). + * If `default_light_settings` is set to `true` and `light_settings` is also set, + * the user-specified `light_settings` is used instead of the default value. + */ + defaultLightSettings?: boolean; + + /** + * Sets the visibility of the notification. Must be either `private`, `public`, + * or `secret`. If unspecified, defaults to `private`. + */ + visibility?: ('private' | 'public' | 'secret'); + + /** + * Sets the number of items this notification represents. May be displayed as a + * badge count for Launchers that support badging. See [`NotificationBadge`(https://developer.android.com/training/notify-user/badges). + * For example, this might be useful if you're using just one notification to + * represent multiple new messages but you want the count here to represent + * the number of total new messages. If zero or unspecified, systems + * that support badging use the default, which is to increment a number + * displayed on the long-press menu each time a new notification arrives. + */ + notificationCount?: number; + } + + /** + * Represents settings to control notification LED that can be included in + * {@link admin.messaging.AndroidNotification}. + */ + interface LightSettings { + /** + * Required. Sets color of the LED in `#rrggbb` or `#rrggbbaa` format. + */ + color: string; + + /** + * Required. Along with `light_off_duration`, defines the blink rate of LED flashes. + */ + lightOnDurationMillis: number; + + /** + * Required. Along with `light_on_duration`, defines the blink rate of LED flashes. + */ + lightOffDurationMillis: number; + } + + /** + * Represents options for features provided by the FCM SDK for Android. + */ + interface AndroidFcmOptions { + + /** + * The label associated with the message's analytics data. + */ + analyticsLabel?: string; + } + + /** + * Represents the APNs-specific options that can be included in an + * {@link admin.messaging.Message}. Refer to + * [Apple documentation](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html) + * for various headers and payload fields supported by APNs. + */ + interface ApnsConfig { + + /** + * A collection of APNs headers. Header values must be strings. + */ + headers?: { [key: string]: string }; + + /** + * An APNs payload to be included in the message. + */ + payload?: ApnsPayload; + + /** + * Options for features provided by the FCM SDK for iOS. + */ + fcmOptions?: ApnsFcmOptions; + } + /** + * Represents the payload of an APNs message. Mainly consists of the `aps` + * dictionary. But may also contain other arbitrary custom keys. + */ + interface ApnsPayload { + + /** + * The `aps` dictionary to be included in the message. + */ + aps: Aps; + [customData: string]: object; + } + /** + * Represents the [aps dictionary](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) + * that is part of APNs messages. + */ + interface Aps { + + /** + * Alert to be included in the message. This may be a string or an object of + * type `admin.messaging.ApsAlert`. + */ + alert?: string | ApsAlert; + + /** + * Badge to be displayed with the message. Set to 0 to remove the badge. When + * not specified, the badge will remain unchanged. + */ + badge?: number; + + /** + * Sound to be played with the message. + */ + sound?: string | CriticalSound; + + /** + * Specifies whether to configure a background update notification. + */ + contentAvailable?: boolean; + + /** + * Specifies whether to set the `mutable-content` property on the message + * so the clients can modify the notification via app extensions. + */ + mutableContent?: boolean; + + /** + * Type of the notification. + */ + category?: string; + + /** + * An app-specific identifier for grouping notifications. + */ + threadId?: string; + [customData: string]: any; + } + + interface ApsAlert { + title?: string; + subtitle?: string; + body?: string; + locKey?: string; + locArgs?: string[]; + titleLocKey?: string; + titleLocArgs?: string[]; + subtitleLocKey?: string; + subtitleLocArgs?: string[]; + actionLocKey?: string; + launchImage?: string; + } + + /** + * Represents a critical sound configuration that can be included in the + * `aps` dictionary of an APNs payload. + */ + interface CriticalSound { + + /** + * The critical alert flag. Set to `true` to enable the critical alert. + */ + critical?: boolean; + + /** + * The name of a sound file in the app's main bundle or in the `Library/Sounds` + * folder of the app's container directory. Specify the string "default" to play + * the system sound. + */ + name: string; + + /** + * The volume for the critical alert's sound. Must be a value between 0.0 + * (silent) and 1.0 (full volume). + */ + volume?: number; + } + + /** + * Represents options for features provided by the FCM SDK for iOS. + */ + interface ApnsFcmOptions { + + /** + * The label associated with the message's analytics data. + */ + analyticsLabel?: string; + + /** + * URL of an image to be displayed in the notification. + */ + imageUrl?: string; + } + + /** + * Represents platform-independent options for features provided by the FCM SDKs. + */ + interface FcmOptions { + + /** + * The label associated with the message's analytics data. + */ + analyticsLabel?: string; + } + + + /** + * A notification that can be included in {@link admin.messaging.Message}. + */ + interface Notification { + /** + * The title of the notification. + */ + title?: string; + /** + * The notification body + */ + body?: string; + /** + * URL of an image to be displayed in the notification. + */ + imageUrl?: string; + } + /** + * Represents the WebPush protocol options that can be included in an + * {@link admin.messaging.Message}. + */ + interface WebpushConfig { + + /** + * A collection of WebPush headers. Header values must be strings. + * + * See [WebPush specification](https://tools.ietf.org/html/rfc8030#section-5) + * for supported headers. + */ + headers?: { [key: string]: string }; + + /** + * A collection of data fields. + */ + data?: { [key: string]: string }; + + /** + * A WebPush notification payload to be included in the message. + */ + notification?: WebpushNotification; + + /** + * Options for features provided by the FCM SDK for Web. + */ + fcmOptions?: WebpushFcmOptions; + } + + /** Represents options for features provided by the FCM SDK for Web + * (which are not part of the Webpush standard). + */ + interface WebpushFcmOptions { + + /** + * The link to open when the user clicks on the notification. + * For all URL values, HTTPS is required. + */ + link?: string; + } + + /** + * Represents the WebPush-specific notification options that can be included in + * {@link admin.messaging.WebpushConfig}. This supports most of the standard + * options as defined in the Web Notification + * [specification](https://developer.mozilla.org/en-US/docs/Web/API/notification/Notification). + */ + interface WebpushNotification { + + /** + * Title text of the notification. + */ + title?: string; + + /** + * An array of notification actions representing the actions + * available to the user when the notification is presented. + */ + actions?: Array<{ + + /** + * An action available to the user when the notification is presented + */ + action: string; + + /** + * Optional icon for a notification action. + */ + icon?: string; + + /** + * Title of the notification action. + */ + title: string; + }>; + + /** + * URL of the image used to represent the notification when there is + * not enough space to display the notification itself. + */ + badge?: string; + + /** + * Body text of the notification. + */ + body?: string; + + /** + * Arbitrary data that you want associated with the notification. + * This can be of any data type. + */ + data?: any; + + /** + * The direction in which to display the notification. Must be one + * of `auto`, `ltr` or `rtl`. + */ + dir?: 'auto' | 'ltr' | 'rtl'; + + /** + * URL to the notification icon. + */ + icon?: string; + + /** + * URL of an image to be displayed in the notification. + */ + image?: string; + + /** + * The notification's language as a BCP 47 language tag. + */ + lang?: string; + + /** + * A boolean specifying whether the user should be notified after a + * new notification replaces an old one. Defaults to false. + */ + renotify?: boolean; + + /** + * Indicates that a notification should remain active until the user + * clicks or dismisses it, rather than closing automatically. + * Defaults to false. + */ + requireInteraction?: boolean; + + /** + * A boolean specifying whether the notification should be silent. + * Defaults to false. + */ + silent?: boolean; + + /** + * An identifying tag for the notification. + */ + tag?: string; + + /** + * Timestamp of the notification. Refer to + * https://developer.mozilla.org/en-US/docs/Web/API/notification/timestamp + * for details. + */ + timestamp?: number; + + /** + * A vibration pattern for the device's vibration hardware to emit + * when the notification fires. + */ + vibrate?: number | number[]; + [key: string]: any; + } + /** + * Interface representing an FCM legacy API data message payload. Data + * messages let developers send up to 4KB of custom key-value pairs. The + * keys and values must both be strings. Keys can be any custom string, + * except for the following reserved strings: + * + * * `"from"` + * * Anything starting with `"google."`. + * + * See [Build send requests](/docs/cloud-messaging/send-message) + * for code samples and detailed documentation. + */ + interface DataMessagePayload { + [key: string]: string; + } + + /** + * Interface representing an FCM legacy API notification message payload. + * Notification messages let developers send up to 4KB of predefined + * key-value pairs. Accepted keys are outlined below. + * + * See [Build send requests](/docs/cloud-messaging/send-message) + * for code samples and detailed documentation. + */ + interface NotificationMessagePayload { + tag?: string; + + /** + * The notification's body text. + * + * **Platforms:** iOS, Android, Web + */ + body?: string; + + /** + * The notification's icon. + * + * **Android:** Sets the notification icon to `myicon` for drawable resource + * `myicon`. If you don't send this key in the request, FCM displays the + * launcher icon specified in your app manifest. + * + * **Web:** The URL to use for the notification's icon. + * + * **Platforms:** Android, Web + */ + icon?: string; + + /** + * The value of the badge on the home screen app icon. + * + * If not specified, the badge is not changed. + * + * If set to `0`, the badge is removed. + * + * **Platforms:** iOS + */ + badge?: string; + + /** + * The notification icon's color, expressed in `#rrggbb` format. + * + * **Platforms:** Android + */ + color?: string; + + /** + * Identifier used to replace existing notifications in the notification drawer. + * + * If not specified, each request creates a new notification. + * + * If specified and a notification with the same tag is already being shown, + * the new notification replaces the existing one in the notification drawer. + * + * **Platforms:** Android + */ + sound?: string; + + /** + * The notification's title. + * + * **Platforms:** iOS, Android, Web + */ + title?: string; + + /** + * The key to the body string in the app's string resources to use to localize + * the body text to the user's current localization. + * + * **iOS:** Corresponds to `loc-key` in the APNs payload. See + * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) + * and + * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) + * for more information. + * + * **Android:** See + * [String Resources](http://developer.android.com/guide/topics/resources/string-resource.html) * for more information. + * + * **Platforms:** iOS, Android + */ + bodyLocKey?: string; + + /** + * Variable string values to be used in place of the format specifiers in + * `body_loc_key` to use to localize the body text to the user's current + * localization. + * + * The value should be a stringified JSON array. + * + * **iOS:** Corresponds to `loc-args` in the APNs payload. See + * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) + * and + * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) + * for more information. + * + * **Android:** See + * [Formatting and Styling](http://developer.android.com/guide/topics/resources/string-resource.html#FormattingAndStyling) + * for more information. + * + * **Platforms:** iOS, Android + */ + bodyLocArgs?: string; + + /** + * Action associated with a user click on the notification. If specified, an + * activity with a matching Intent Filter is launched when a user clicks on the + * notification. + * + * * **Platforms:** Android + */ + clickAction?: string; + + /** + * The key to the title string in the app's string resources to use to localize + * the title text to the user's current localization. + * + * **iOS:** Corresponds to `title-loc-key` in the APNs payload. See + * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) + * and + * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) + * for more information. + * + * **Android:** See + * [String Resources](http://developer.android.com/guide/topics/resources/string-resource.html) + * for more information. + * + * **Platforms:** iOS, Android + */ + titleLocKey?: string; + + /** + * Variable string values to be used in place of the format specifiers in + * `title_loc_key` to use to localize the title text to the user's current + * localization. + * + * The value should be a stringified JSON array. + * + * **iOS:** Corresponds to `title-loc-args` in the APNs payload. See + * [Payload Key Reference](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html) + * and + * [Localizing the Content of Your Remote Notifications](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html#//apple_ref/doc/uid/TP40008194-CH10-SW9) + * for more information. + * + * **Android:** See + * [Formatting and Styling](http://developer.android.com/guide/topics/resources/string-resource.html#FormattingAndStyling) + * for more information. + * + * **Platforms:** iOS, Android + */ + titleLocArgs?: string; + [key: string]: string | undefined; + } + + /** + * Interface representing a Firebase Cloud Messaging message payload. One or + * both of the `data` and `notification` keys are required. + * + * See + * [Build send requests](/docs/cloud-messaging/send-message) + * for code samples and detailed documentation. + */ + interface MessagingPayload { + + /** + * The data message payload. + */ + data?: admin.messaging.DataMessagePayload; + + /** + * The notification message payload. + */ + notification?: admin.messaging.NotificationMessagePayload; + } + /** + * Interface representing the options that can be provided when sending a + * message via the FCM legacy APIs. + * + * See [Build send requests](/docs/cloud-messaging/send-message) + * for code samples and detailed documentation. + */ + interface MessagingOptions { + + /** + * Whether or not the message should actually be sent. When set to `true`, + * allows developers to test a request without actually sending a message. When + * set to `false`, the message will be sent. + * + * **Default value:** `false` + */ + dryRun?: boolean; + + /** + * The priority of the message. Valid values are `"normal"` and `"high".` On + * iOS, these correspond to APNs priorities `5` and `10`. + * + * By default, notification messages are sent with high priority, and data + * messages are sent with normal priority. Normal priority optimizes the client + * app's battery consumption and should be used unless immediate delivery is + * required. For messages with normal priority, the app may receive the message + * with unspecified delay. + * + * When a message is sent with high priority, it is sent immediately, and the + * app can wake a sleeping device and open a network connection to your server. + * + * For more information, see + * [Setting the priority of a message](/docs/cloud-messaging/concept-options#setting-the-priority-of-a-message). + * + * **Default value:** `"high"` for notification messages, `"normal"` for data + * messages + */ + priority?: string; + + /** + * How long (in seconds) the message should be kept in FCM storage if the device + * is offline. The maximum time to live supported is four weeks, and the default + * value is also four weeks. For more information, see + * [Setting the lifespan of a message](/docs/cloud-messaging/concept-options#ttl). + * + * **Default value:** `2419200` (representing four weeks, in seconds) + */ + timeToLive?: number; + + /** + * String identifying a group of messages (for example, "Updates Available") + * that can be collapsed, so that only the last message gets sent when delivery + * can be resumed. This is used to avoid sending too many of the same messages + * when the device comes back online or becomes active. + * + * There is no guarantee of the order in which messages get sent. + * + * A maximum of four different collapse keys is allowed at any given time. This + * means FCM server can simultaneously store four different + * send-to-sync messages per client app. If you exceed this number, there is no + * guarantee which four collapse keys the FCM server will keep. + * + * **Default value:** None + */ + collapseKey?: string; + + /** + * On iOS, use this field to represent `mutable-content` in the APNs payload. + * When a notification is sent and this is set to `true`, the content of the + * notification can be modified before it is displayed, using a + * [Notification Service app extension](https://developer.apple.com/reference/usernotifications/unnotificationserviceextension) + * + * On Android and Web, this parameter will be ignored. + * + * **Default value:** `false` + */ + mutableContent?: boolean; + + /** + * On iOS, use this field to represent `content-available` in the APNs payload. + * When a notification or data message is sent and this is set to `true`, an + * inactive client app is awoken. On Android, data messages wake the app by + * default. On Chrome, this flag is currently not supported. + * + * **Default value:** `false` + */ + contentAvailable?: boolean; + + /** + * The package name of the application which the registration tokens must match + * in order to receive the message. + * + * **Default value:** None + */ + restrictedPackageName?: string; + [key: string]: any | undefined; + } + + /** + * Interface representing the status of a message sent to an individual device + * via the FCM legacy APIs. + * + * See + * [Send to individual devices](/docs/cloud-messaging/admin/send-messages#send_to_individual_devices) + * for code samples and detailed documentation. + */ + interface MessagingDeviceResult { + + /** + * The error that occurred when processing the message for the recipient. + */ + error?: _admin.FirebaseError; + + /** + * A unique ID for the successfully processed message. + */ + messageId?: string; + + /** + * The canonical registration token for the client app that the message was + * processed and sent to. You should use this value as the registration token + * for future requests. Otherwise, future messages might be rejected. + */ + canonicalRegistrationToken?: string; + } + + /** + * Interface representing the server response from the legacy + * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendToDevice `sendToDevice()`} method. + * + * See + * [Send to individual devices](/docs/cloud-messaging/admin/send-messages#send_to_individual_devices) + * for code samples and detailed documentation. + */ + interface MessagingDevicesResponse { + + /** + * The number of results that contain a canonical registration token. A + * canonical registration token is the registration token corresponding to the + * last registration requested by the client app. This is the token that you + * should use when sending future messages to the device. + * + * You can access the canonical registration tokens within the + * [`results`](#results) property. + */ + canonicalRegistrationTokenCount: number; + + /** + * The number of messages that could not be processed and resulted in an error. + */ + failureCount: number; + + /** + * The unique ID number identifying this multicast message. + */ + multicastId: number; + + /** + * An array of `MessagingDeviceResult` objects representing the status of the + * processed messages. The objects are listed in the same order as in the + * request. That is, for each registration token in the request, its result has + * the same index in this array. If only a single registration token is + * provided, this array will contain a single object. + */ + results: admin.messaging.MessagingDeviceResult[]; + + /** + * The number of messages that were successfully processed and sent. + */ + successCount: number; + } + /** + * Interface representing the server response from the + * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendToDeviceGroup `sendToDeviceGroup()`} + * method. + * + * See + * [Send messages to device groups](/docs/cloud-messaging/send-message?authuser=0#send_messages_to_device_groups) + * for code samples and detailed documentation. + */ + interface MessagingDeviceGroupResponse { + + /** + * The number of messages that could not be processed and resulted in an error. + */ + successCount: number; + + /** + * The number of messages that could not be processed and resulted in an error. + */ + failureCount: number; + + /** + * An array of registration tokens that failed to receive the message. + */ + failedRegistrationTokens: string[]; + } + + /** + * Interface representing the server response from the legacy + * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendToTopic `sendToTopic()`} method. + * + * See + * [Send to a topic](/docs/cloud-messaging/admin/send-messages#send_to_a_topic) + * for code samples and detailed documentation. + */ + interface MessagingTopicResponse { + + /** + * The message ID for a successfully received request which FCM will attempt to + * deliver to all subscribed devices. + */ + messageId: number; + } + + /** + * Interface representing the server response from the legacy + * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendToCondition `sendToCondition()`} method. + * + * See + * [Send to a condition](/docs/cloud-messaging/admin/send-messages#send_to_a_condition) + * for code samples and detailed documentation. + */ + interface MessagingConditionResponse { + + /** + * The message ID for a successfully received request which FCM will attempt to + * deliver to all subscribed devices. + */ + messageId: number; + } + + /** + * Interface representing the server response from the + * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#subscribeToTopic `subscribeToTopic()`} and + * {@link + * admin.messaging.Messaging#unsubscribeFromTopic + * `unsubscribeFromTopic()`} + * methods. + * + * See + * [Manage topics from the server](/docs/cloud-messaging/manage-topics) + * for code samples and detailed documentation. + */ + interface MessagingTopicManagementResponse { + + /** + * The number of registration tokens that could not be subscribed to the topic + * and resulted in an error. + */ + failureCount: number; + + /** + * The number of registration tokens that were successfully subscribed to the + * topic. + */ + successCount: number; + + /** + * An array of errors corresponding to the provided registration token(s). The + * length of this array will be equal to [`failureCount`](#failureCount). + */ + errors: _admin.FirebaseArrayIndexError[]; + } + + /** + * Interface representing the server response from the + * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendAll `sendAll()`} and + * {@link https://firebase.google.com/docs/reference/admin/node/admin.messaging.Messaging#sendMulticast `sendMulticast()`} methods. + */ + interface BatchResponse { + + /** + * An array of responses, each corresponding to a message. + */ + responses: admin.messaging.SendResponse[]; + + /** + * The number of messages that were successfully handed off for sending. + */ + successCount: number; + + /** + * The number of messages that resulted in errors when sending. + */ + failureCount: number; + } + /** + * Interface representing the status of an individual message that was sent as + * part of a batch request. + */ + interface SendResponse { + + /** + * A boolean indicating if the message was successfully handed off to FCM or + * not. When true, the `messageId` attribute is guaranteed to be set. When + * false, the `error` attribute is guaranteed to be set. + */ + success: boolean; + + /** + * A unique message ID string, if the message was handed off to FCM for + * delivery. + * + */ + messageId?: string; + + /** + * An error, if the message was not handed off to FCM successfully. + */ + error?: _admin.FirebaseError; + } + + /** + * Gets the {@link admin.messaging.Messaging `Messaging`} service for the + * current app. + * + * @example + * ```javascript + * var messaging = app.messaging(); + * // The above is shorthand for: + * // var messaging = admin.messaging(app); + * ``` + * + * @return The `Messaging` service for the current app. + */ + interface Messaging { + /** + * The {@link admin.app.App app} associated with the current `Messaging` service + * instance. + * + * @example + * ```javascript + * var app = messaging.app; + * ``` + */ + app: _admin.app.App; + + /** + * Sends the given message via FCM. + * + * @param message The message payload. + * @param dryRun Whether to send the message in the dry-run + * (validation only) mode. + * @return A promise fulfilled with a unique message ID + * string after the message has been successfully handed off to the FCM + * service for delivery. + */ + send(message: admin.messaging.Message, dryRun?: boolean): Promise; + + /** + * Sends all the messages in the given array via Firebase Cloud Messaging. + * Employs batching to send the entire list as a single RPC call. Compared + * to the `send()` method, this method is a significantly more efficient way + * to send multiple messages. + * + * The responses list obtained from the return value + * corresponds to the order of tokens in the `MulticastMessage`. An error + * from this method indicates a total failure -- i.e. none of the messages in + * the list could be sent. Partial failures are indicated by a `BatchResponse` + * return value. + * + * @param messages A non-empty array + * containing up to 500 messages. + * @param dryRun Whether to send the messages in the dry-run + * (validation only) mode. + * @return A Promise fulfilled with an object representing the result of the + * send operation. + */ + sendAll( + messages: Array, + dryRun?: boolean + ): Promise; + + /** + * Sends the given multicast message to all the FCM registration tokens + * specified in it. + * + * This method uses the `sendAll()` API under the hood to send the given + * message to all the target recipients. The responses list obtained from the + * return value corresponds to the order of tokens in the `MulticastMessage`. + * An error from this method indicates a total failure -- i.e. the message was + * not sent to any of the tokens in the list. Partial failures are indicated by + * a `BatchResponse` return value. + * + * @param message A multicast message + * containing up to 500 tokens. + * @param dryRun Whether to send the message in the dry-run + * (validation only) mode. + * @return A Promise fulfilled with an object representing the result of the + * send operation. + */ + sendMulticast( + message: admin.messaging.MulticastMessage, + dryRun?: boolean + ): Promise; + + /** + * Sends an FCM message to a single device corresponding to the provided + * registration token. + * + * See + * [Send to individual devices](/docs/cloud-messaging/admin/legacy-fcm#send_to_individual_devices) + * for code samples and detailed documentation. Takes either a + * `registrationToken` to send to a single device or a + * `registrationTokens` parameter containing an array of tokens to send + * to multiple devices. + * + * @param registrationToken A device registration token or an array of + * device registration tokens to which the message should be sent. + * @param payload The message payload. + * @param options Optional options to + * alter the message. + * + * @return A promise fulfilled with the server's response after the message + * has been sent. + */ + sendToDevice( + registrationToken: string | string[], + payload: admin.messaging.MessagingPayload, + options?: admin.messaging.MessagingOptions + ): Promise; + + /** + * Sends an FCM message to a device group corresponding to the provided + * notification key. + * + * See + * [Send to a device group](/docs/cloud-messaging/admin/legacy-fcm#send_to_a_device_group) + * for code samples and detailed documentation. + * + * @param notificationKey The notification key for the device group to + * which to send the message. + * @param payload The message payload. + * @param options Optional options to + * alter the message. + * + * @return A promise fulfilled with the server's response after the message + * has been sent. + */ + sendToDeviceGroup( + notificationKey: string, + payload: admin.messaging.MessagingPayload, + options?: admin.messaging.MessagingOptions + ): Promise; + + /** + * Sends an FCM message to a topic. + * + * See + * [Send to a topic](/docs/cloud-messaging/admin/legacy-fcm#send_to_a_topic) + * for code samples and detailed documentation. + * + * @param topic The topic to which to send the message. + * @param payload The message payload. + * @param options Optional options to + * alter the message. + * + * @return A promise fulfilled with the server's response after the message + * has been sent. + */ + sendToTopic( + topic: string, + payload: admin.messaging.MessagingPayload, + options?: admin.messaging.MessagingOptions + ): Promise; + + /** + * Sends an FCM message to a condition. + * + * See + * [Send to a condition](/docs/cloud-messaging/admin/legacy-fcm#send_to_a_condition) + * for code samples and detailed documentation. + * + * @param condition The condition determining to which topics to send + * the message. + * @param payload The message payload. + * @param options Optional options to + * alter the message. + * + * @return A promise fulfilled with the server's response after the message + * has been sent. + */ + sendToCondition( + condition: string, + payload: admin.messaging.MessagingPayload, + options?: admin.messaging.MessagingOptions + ): Promise; + + /** + * Subscribes a device to an FCM topic. + * + * See [Subscribe to a + * topic](/docs/cloud-messaging/manage-topics#suscribe_and_unsubscribe_using_the) + * for code samples and detailed documentation. Optionally, you can provide an + * array of tokens to subscribe multiple devices. + * + * @param registrationTokens A token or array of registration tokens + * for the devices to subscribe to the topic. + * @param topic The topic to which to subscribe. + * + * @return A promise fulfilled with the server's response after the device has been + * subscribed to the topic. + */ + subscribeToTopic( + registrationTokens: string | string[], + topic: string + ): Promise; + + /** + * Unsubscribes a device from an FCM topic. + * + * See [Unsubscribe from a + * topic](/docs/cloud-messaging/admin/manage-topic-subscriptions#unsubscribe_from_a_topic) + * for code samples and detailed documentation. Optionally, you can provide an + * array of tokens to unsubscribe multiple devices. + * + * @param registrationTokens A device registration token or an array of + * device registration tokens to unsubscribe from the topic. + * @param topic The topic from which to unsubscribe. + * + * @return A promise fulfilled with the server's response after the device has been + * unsubscribed from the topic. + */ + unsubscribeFromTopic( + registrationTokens: string | string[], + topic: string + ): Promise; + } +} diff --git a/src/project-management.d.ts b/src/project-management.d.ts new file mode 100644 index 0000000000..755f8c9e94 --- /dev/null +++ b/src/project-management.d.ts @@ -0,0 +1,360 @@ +import * as _admin from './index.d'; + +export namespace admin.projectManagement { + + /** + * A SHA-1 or SHA-256 certificate. + * + * Do not call this constructor directly. Instead, use + * [`projectManagement.shaCertificate()`](admin.projectManagement.ProjectManagement#shaCertificate). + */ + interface ShaCertificate { + + /** + * The SHA certificate type. + * + * @example + * ```javascript + * var certType = shaCertificate.certType; + * ``` + */ + certType: ('sha1' | 'sha256'); + + /** + * The SHA-1 or SHA-256 hash for this certificate. + * + * @example + * ```javascript + * var shaHash = shaCertificate.shaHash; + * ``` + */ + shaHash: string; + + /** + * The fully-qualified resource name that identifies this sha-key. + * + * This is useful when manually constructing requests for Firebase's public API. + * + * @example + * ```javascript + * var resourceName = shaCertificate.resourceName; + * ``` + */ + resourceName?: string; + } + + /** + * Metadata about a Firebase app. + */ + interface AppMetadata { + + /** + * The globally unique, Firebase-assigned identifier of the app. + * + * @example + * ```javascript + * var appId = appMetadata.appId; + * ``` + */ + appId: string; + + /** + * The optional user-assigned display name of the app. + * + * @example + * ```javascript + * var displayName = appMetadata.displayName; + * ``` + */ + displayName?: string; + + /** + * The development platform of the app. Supporting Android and iOS app platforms. + * + * @example + * ```javascript + * var platform = AppPlatform.ANDROID; + * ``` + */ + platform: AppPlatform; + + /** + * The globally unique, user-assigned ID of the parent project for the app. + * + * @example + * ```javascript + * var projectId = appMetadata.projectId; + * ``` + */ + projectId: string; + + /** + * The fully-qualified resource name that identifies this app. + * + * This is useful when manually constructing requests for Firebase's public API. + * + * @example + * ```javascript + * var resourceName = androidAppMetadata.resourceName; + * ``` + */ + resourceName: string; + } + + /** + * Platforms with which a Firebase App can be associated. + */ + enum AppPlatform { + + /** + * Unknown state. This is only used for distinguishing unset values. + */ + PLATFORM_UNKNOWN = 'PLATFORM_UNKNOWN', + + /** + * The Firebase App is associated with iOS. + */ + IOS = 'IOS', + + /** + * The Firebase App is associated with Android. + */ + ANDROID = 'ANDROID', + } + + /** + * Metadata about a Firebase Android App. + */ + interface AndroidAppMetadata extends AppMetadata { + + platform: AppPlatform.ANDROID; + + /** + * The canonical package name of the Android App, as would appear in the Google Play Developer + * Console. + * + * @example + * ```javascript + * var packageName = androidAppMetadata.packageName; + * ``` + */ + packageName: string; + } + + /** + * Metadata about a Firebase iOS App. + */ + interface IosAppMetadata extends AppMetadata { + platform: AppPlatform.IOS; + + /** + * The canonical bundle ID of the iOS App as it would appear in the iOS App Store. + * + * @example + * ```javascript + * var bundleId = iosAppMetadata.bundleId; + *``` + */ + bundleId: string; + } + + /** + * A reference to a Firebase Android app. + * + * Do not call this constructor directly. Instead, use + * [`projectManagement.androidApp()`](admin.projectManagement.ProjectManagement#androidApp). + */ + interface AndroidApp { + appId: string; + + /** + * Retrieves metadata about this Android app. + * + * @return A promise that resolves to the retrieved metadata about this Android app. + */ + getMetadata(): Promise; + + /** + * Sets the optional user-assigned display name of the app. + * + * @param newDisplayName The new display name to set. + * + * @return A promise that resolves when the display name has been set. + */ + setDisplayName(newDisplayName: string): Promise; + + /** + * Gets the list of SHA certificates associated with this Android app in Firebase. + * + * @return The list of SHA-1 and SHA-256 certificates associated with this Android app in + * Firebase. + */ + getShaCertificates(): Promise; + + /** + * Adds the given SHA certificate to this Android app. + * + * @param certificateToAdd The SHA certificate to add. + * + * @return A promise that resolves when the given certificate + * has been added to the Android app. + */ + addShaCertificate(certificateToAdd: ShaCertificate): Promise; + + /** + * Deletes the specified SHA certificate from this Android app. + * + * @param certificateToDelete The SHA certificate to delete. + * + * @return A promise that resolves when the specified + * certificate has been removed from the Android app. + */ + deleteShaCertificate(certificateToRemove: ShaCertificate): Promise; + + /** + * Gets the configuration artifact associated with this app. + * + * @return A promise that resolves to the Android app's + * Firebase config file, in UTF-8 string format. This string is typically + * intended to be written to a JSON file that gets shipped with your Android + * app. + */ + getConfig(): Promise; + } + + /** + * A reference to a Firebase iOS app. + * + * Do not call this constructor directly. Instead, use + * [`projectManagement.iosApp()`](admin.projectManagement.ProjectManagement#iosApp). + */ + interface IosApp { + appId: string; + + /** + * Retrieves metadata about this iOS app. + * + * @return {!Promise} A promise that + * resolves to the retrieved metadata about this iOS app. + */ + getMetadata(): Promise; + + /** + * Sets the optional user-assigned display name of the app. + * + * @param newDisplayName The new display name to set. + * + * @return A promise that resolves when the display name has + * been set. + */ + setDisplayName(newDisplayName: string): Promise; + + /** + * Gets the configuration artifact associated with this app. + * + * @return A promise that resolves to the iOS app's Firebase + * config file, in UTF-8 string format. This string is typically intended to + * be written to a plist file that gets shipped with your iOS app. + */ + getConfig(): Promise; + } + + /** + * The Firebase ProjectManagement service interface. + * + * Do not call this constructor directly. Instead, use + * [`admin.projectManagement()`](admin.projectManagement#projectManagement). + */ + interface ProjectManagement { + app: _admin.app.App; + + /** + * Lists up to 100 Firebase apps associated with this Firebase project. + * + * @return A promise that resolves to the metadata list of the apps. + */ + listAppMetadata(): Promise; + + /** + * Lists up to 100 Firebase Android apps associated with this Firebase project. + * + * @return The list of Android apps. + */ + listAndroidApps(): Promise; + + /** + * Lists up to 100 Firebase iOS apps associated with this Firebase project. + * + * @return The list of iOS apps. + */ + listIosApps(): Promise; + + /** + * Creates an `AndroidApp` object, referencing the specified Android app within + * this Firebase project. + * + * This method does not perform an RPC. + * + * @param appId The `appId` of the Android app to reference. + * + * @return An `AndroidApp` object that references the specified Firebase Android app. + */ + androidApp(appId: string): admin.projectManagement.AndroidApp; + + /** + * Update the display name of this Firebase project. + * + * @param newDisplayName The new display name to be updated. + * + * @return A promise that resolves when the project display name has been updated. + */ + setDisplayName(newDisplayName: string): Promise; + + /** + * Creates an `iOSApp` object, referencing the specified iOS app within + * this Firebase project. + * + * This method does not perform an RPC. + * + * @param appId The `appId` of the iOS app to reference. + * + * @return An `iOSApp` object that references the specified Firebase iOS app. + */ + iosApp(appId: string): admin.projectManagement.IosApp; + + /** + * Creates a `ShaCertificate` object. + * + * This method does not perform an RPC. + * + * @param shaHash The SHA-1 or SHA-256 hash for this certificate. + * + * @return A `ShaCertificate` object contains the specified SHA hash. + */ + shaCertificate(shaHash: string): admin.projectManagement.ShaCertificate; + + /** + * Creates a new Firebase Android app associated with this Firebase project. + * + * @param packageName The canonical package name of the Android App, + * as would appear in the Google Play Developer Console. + * @param displayName An optional user-assigned display name for this + * new app. + * + * @return A promise that resolves to the newly created Android app. + */ + createAndroidApp( + packageName: string, displayName?: string): Promise; + + /** + * Creates a new Firebase iOS app associated with this Firebase project. + * + * @param bundleId The iOS app bundle ID to use for this new app. + * @param displayName An optional user-assigned display name for this + * new app. + * + * @return A promise that resolves to the newly created iOS app. + */ + createIosApp(bundleId: string, displayName?: string): Promise; + } +} diff --git a/src/security-rules.d.ts b/src/security-rules.d.ts new file mode 100644 index 0000000000..a81d23634a --- /dev/null +++ b/src/security-rules.d.ts @@ -0,0 +1,191 @@ +import * as _admin from './index.d'; + +export namespace admin.securityRules { + /** + * A source file containing some Firebase security rules. The content includes raw + * source code including text formatting, indentation and comments. Use the + * [`securityRules.createRulesFileFromSource()`](admin.securityRules.SecurityRules#createRulesFileFromSource) + * method to create new instances of this type. + */ + interface RulesFile { + readonly name: string; + readonly content: string; + } + + /** + * Required metadata associated with a ruleset. + */ + interface RulesetMetadata { + /** + * Name of the `Ruleset` as a short string. This can be directly passed into APIs + * like [`securityRules.getRuleset()`](admin.securityRules.SecurityRules#getRuleset) + * and [`securityRules.deleteRuleset()`](admin.securityRules.SecurityRules#deleteRuleset). + */ + readonly name: string; + + /** + * Creation time of the `Ruleset` as a UTC timestamp string. + */ + readonly createTime: string; + } + + /** + * A set of Firebase security rules. + */ + interface Ruleset extends RulesetMetadata { + readonly source: RulesFile[]; + } + + interface RulesetMetadataList { + /** + * A batch of ruleset metadata. + */ + readonly rulesets: RulesetMetadata[]; + + /** + * The next page token if available. This is needed to retrieve the next batch. + */ + readonly nextPageToken?: string; + } + + /** + * The Firebase `SecurityRules` service interface. + * + * Do not call this constructor directly. Instead, use + * [`admin.securityRules()`](admin.securityRules#securityRules). + */ + interface SecurityRules { + app: _admin.app.App; + + /** + * Creates a {@link admin.securityRules.RulesFile `RuleFile`} with the given name + * and source. Throws an error if any of the arguments are invalid. This is a local + * operation, and does not involve any network API calls. + * + * @example + * ```javascript + * const source = '// Some rules source'; + * const rulesFile = admin.securityRules().createRulesFileFromSource( + * 'firestore.rules', source); + * ``` + * + * @param name Name to assign to the rules file. This is usually a short file name that + * helps identify the file in a ruleset. + * @param source Contents of the rules file. + * @return A new rules file instance. + */ + createRulesFileFromSource(name: string, source: string | Buffer): RulesFile; + + /** + * Creates a new {@link admin.securityRules.Ruleset `Ruleset`} from the given + * {@link admin.securityRules.RulesFile `RuleFile`}. + * + * @param file Rules file to include in the new `Ruleset`. + * @returns A promise that fulfills with the newly created `Ruleset`. + */ + createRuleset(file: RulesFile): Promise; + + /** + * Gets the {@link admin.securityRules.Ruleset `Ruleset`} identified by the given + * name. The input name should be the short name string without the project ID + * prefix. For example, to retrieve the `projects/project-id/rulesets/my-ruleset`, + * pass the short name "my-ruleset". Rejects with a `not-found` error if the + * specified `Ruleset` cannot be found. + * + * @param name Name of the `Ruleset` to retrieve. + * @return A promise that fulfills with the specified `Ruleset`. + */ + getRuleset(name: string): Promise; + + /** + * Deletes the {@link admin.securityRules.Ruleset `Ruleset`} identified by the given + * name. The input name should be the short name string without the project ID + * prefix. For example, to delete the `projects/project-id/rulesets/my-ruleset`, + * pass the short name "my-ruleset". Rejects with a `not-found` error if the + * specified `Ruleset` cannot be found. + * + * @param name Name of the `Ruleset` to delete. + * @return A promise that fulfills when the `Ruleset` is deleted. + */ + deleteRuleset(name: string): Promise; + + /** + * Retrieves a page of ruleset metadata. + * + * @param pageSize The page size, 100 if undefined. This is also the maximum allowed + * limit. + * @param nextPageToken The next page token. If not specified, returns rulesets + * starting without any offset. + * @return A promise that fulfills with a page of rulesets. + */ + listRulesetMetadata( + pageSize?: number, nextPageToken?: string): Promise; + + /** + * Gets the {@link admin.securityRules.Ruleset `Ruleset`} currently applied to + * Cloud Firestore. Rejects with a `not-found` error if no ruleset is applied + * on Firestore. + * + * @return A promise that fulfills with the Firestore ruleset. + */ + getFirestoreRuleset(): Promise; + + /** + * Creates a new {@link admin.securityRules.Ruleset `Ruleset`} from the given + * source, and applies it to Cloud Firestore. + * + * @param source Rules source to apply. + * @return A promise that fulfills when the ruleset is created and released. + */ + releaseFirestoreRulesetFromSource(source: string | Buffer): Promise; + + /** + * Applies the specified {@link admin.securityRules.Ruleset `Ruleset`} ruleset + * to Cloud Firestore. + * + * @param ruleset Name of the ruleset to apply or a `RulesetMetadata` object + * containing the name. + * @return A promise that fulfills when the ruleset is released. + */ + releaseFirestoreRuleset(ruleset: string | RulesetMetadata): Promise; + + /** + * Gets the {@link admin.securityRules.Ruleset `Ruleset`} currently applied to a + * Cloud Storage bucket. Rejects with a `not-found` error if no ruleset is applied + * on the bucket. + * + * @param bucket Optional name of the Cloud Storage bucket to be retrieved. If not + * specified, retrieves the ruleset applied on the default bucket configured via + * `AppOptions`. + * @return A promise that fulfills with the Cloud Storage ruleset. + */ + getStorageRuleset(bucket?: string): Promise; + + /** + * Creates a new {@link admin.securityRules.Ruleset `Ruleset`} from the given + * source, and applies it to a Cloud Storage bucket. + * + * @param source Rules source to apply. + * @param bucket Optional name of the Cloud Storage bucket to apply the rules on. If + * not specified, applies the ruleset on the default bucket configured via + * {@link admin.AppOptions `AppOptions`}. + * @return A promise that fulfills when the ruleset is created and released. + */ + releaseStorageRulesetFromSource( + source: string | Buffer, bucket?: string): Promise; + + /** + * Applies the specified {@link admin.securityRules.Ruleset `Ruleset`} ruleset + * to a Cloud Storage bucket. + * + * @param ruleset Name of the ruleset to apply or a `RulesetMetadata` object + * containing the name. + * @param bucket Optional name of the Cloud Storage bucket to apply the rules on. If + * not specified, applies the ruleset on the default bucket configured via + * {@link admin.AppOptions `AppOptions`}. + * @return A promise that fulfills when the ruleset is released. + */ + releaseStorageRuleset( + ruleset: string | RulesetMetadata, bucket?: string): Promise; + } +} diff --git a/test/integration/typescript/src/example.test.ts b/test/integration/typescript/src/example.test.ts index d630936e4e..f4e3800cf5 100644 --- a/test/integration/typescript/src/example.test.ts +++ b/test/integration/typescript/src/example.test.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import initApp from './example' +import initApp from './example'; import {expect} from 'chai'; import {Bucket} from '@google-cloud/storage'; import {Firestore} from '@google-cloud/firestore'; @@ -34,6 +34,26 @@ describe('Init App', () => { expect(app.name).to.equal('TestApp'); }); + it('Should return an Auth client', () => { + const client = admin.auth(app); + expect(client).to.be.instanceOf((admin.auth as any).Auth); + }); + + it('Should return a Messaging client', () => { + const client = admin.messaging(app); + expect(client).to.be.instanceOf((admin.messaging as any).Messaging); + }); + + it('Should return a ProjectManagement client', () => { + const client = admin.projectManagement(app); + expect(client).to.be.instanceOf((admin.projectManagement as any).ProjectManagement); + }); + + it('Should return a SecurityRules client', () => { + const client = admin.securityRules(app); + expect(client).to.be.instanceOf((admin.securityRules as any).SecurityRules); + }); + it('Should return a Database client', () => { const db = admin.database(app); expect(db).to.be.instanceOf((admin.database as any).Database); @@ -51,7 +71,7 @@ describe('Init App', () => { it('Should return a Cloud Storage client', () => { const bucket: Bucket = app.storage().bucket('TestBucket'); - expect(bucket.name).to.equal('TestBucket') + expect(bucket.name).to.equal('TestBucket'); }); it('Should return a Firestore client from the app', () => { From b17c999150420475c96d400a519570d615ca57b8 Mon Sep 17 00:00:00 2001 From: Hiranya Jayathilaka Date: Mon, 6 Jan 2020 14:06:37 -0800 Subject: [PATCH 2/2] Database return type fixed --- src/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/index.d.ts b/src/index.d.ts index a16d704b50..ca7335d5a5 100755 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -456,7 +456,7 @@ declare namespace admin.app { auth(): admin.auth.Auth; - database(url?: string): _database.admin.database.Database; + database(url?: string): admin.database.Database; firestore(): admin.firestore.Firestore; instanceId(): admin.instanceId.InstanceId; messaging(): admin.messaging.Messaging;