@dereekb/firebase-server 13.10.9 → 13.11.0

package/test/index.esm.js

@@ -336,6 +336,9 @@ function _ts_generator$a(thisArg, body) {
  * where non-JSON-safe values (e.g., `Date` instances, `undefined` fields) are stripped
  * or transformed. Used internally by {@link AuthorizedUserTestContextInstance.callWrappedFunction}
  * to ensure test params match real-world serialization behavior.
+ *
+ * @param object - Arbitrary value to round-trip through `JSON.stringify` then `JSON.parse`.
+ * @returns The input value after a JSON serialize/parse cycle, with any non-JSON-safe fields stripped.
  */ function convertParamsToParsedJsonObjectAndBack(object) {
     var paramsAsJson = JSON.parse(JSON.stringify(object));
     return paramsAsJson;
@@ -419,9 +422,10 @@ function _ts_generator$a(thisArg, body) {
             /**
      * Calls a wrapped function with the input params and the context from makeContextOptions().
      *
-     * @param fn
-     * @param params
-     * @param skipJsonConversion
+     * @param fn - Wrapped gen 2 callable request to invoke.
+     * @param params - Request payload to pass to the callable, simulating the JSON body of an HTTP call.
+     * @param skipJsonConversion - When `true`, skip the JSON serialize/parse round-trip applied to `params` (default `false`).
+     * @returns A promise resolving to the callable's return value.
      */ key: "callWrappedFunction",
             value: function callWrappedFunction(fn, params, skipJsonConversion) {
                 // Parse to JSON then back to simulate sending JSON to the server, and the server parsing it as a POJO.
@@ -448,15 +452,19 @@ function _ts_generator$a(thisArg, body) {
             /**
      * Calls a wrapped gen 2 auth blocking function with the input params and context options from makeContextOptions().
      *
-     * @param fn
-     * @param userRecord
-     * @param eventType
-     * @param eventOverride
-     * @param skipJsonConversion
-     * @returns
+     * Synthesizes a minimal {@link AuthBlockingEvent} (filling in placeholder ip/user-agent/resource fields)
+     * from the supplied user record and event type, then dispatches it to the wrapped function.
+     *
+     * @param input - Options bag describing the blocking function invocation.
+     * @param input.fn - Wrapped gen 2 auth blocking function (e.g., from `beforeUserCreated`/`beforeUserSignedIn`) to invoke.
+     * @param input.userRecord - The Firebase Auth {@link UserRecord} that will be attached to the synthesized event's `data` field.
+     * @param input.eventType - Discriminator for the auth event being simulated (`google.firebase.auth.user.create` or `google.firebase.auth.user.delete`).
+     * @param input.eventOverride - Partial event fields used to override the default placeholder values (e.g., `ipAddress`, `userAgent`, `resource`).
+     * @param input.skipJsonConversion - When `true`, skip the JSON serialize/parse round-trip applied to the event payload (default `false`).
+     * @returns A promise that resolves once the blocking function has completed.
      */ key: "callAuthBlockingFunction",
-            value: function callAuthBlockingFunction(fn, userRecord, eventType, eventOverride) {
-                var skipJsonConversion = arguments.length > 4 && arguments[4] !== void 0 ? arguments[4] : false;
+            value: function callAuthBlockingFunction(input) {
+                var fn = input.fn, userRecord = input.userRecord, eventType = input.eventType, eventOverride = input.eventOverride, _input_skipJsonConversion = input.skipJsonConversion, skipJsonConversion = _input_skipJsonConversion === void 0 ? false : _input_skipJsonConversion;
                 var timestamp = new Date().toISOString();
                 var event = _object_spread_props$3(_object_spread$5({
                     ipAddress: '127.0.0.1',
@@ -484,7 +492,8 @@ function _ts_generator$a(thisArg, body) {
      * @param contextOptions
      * @param skipJsonConversion
      * @returns
-     */ key: "callEventCloudFunction",
+     */ // eslint-disable-next-line @typescript-eslint/max-params -- deprecated gen 1 signature kept for downstream compatibility
+            key: "callEventCloudFunction",
             value: function callEventCloudFunction(fn, params, contextOptions) {
                 var skipJsonConversion = arguments.length > 3 && arguments[3] !== void 0 ? arguments[3] : false;
                 var parsedParams = params == null || skipJsonConversion ? params : convertParamsToParsedJsonObjectAndBack(params);
@@ -498,6 +507,9 @@ function _ts_generator$a(thisArg, body) {
 }();
 /**
  * Convenience function for using authorizedUserContextFactory directly and passing buildTests.
+ *
+ * @param config - Test context parameters (parent fixture, optional uid/template, custom factories) used to create the authorized user context.
+ * @param buildTests - Callback invoked with the built {@link AuthorizedUserTestContextFixture}; should register `it(...)`/`describe(...)` blocks against it.
  */ function authorizedUserContext(config, buildTests) {
     authorizedUserContextFactory(config)({
         f: config.f
@@ -517,6 +529,13 @@ function _ts_generator$a(thisArg, body) {
  */ var AUTHORIZED_USER_RANDOM_PHONE_NUMBER_FACTORY = randomPhoneNumberFactory();
 /**
  * Creates a new Jest Context that has a random user for authorization for use in firebase server tests.
+ *
+ * The returned function, when called with runtime params and a `buildTests` callback, registers the
+ * `beforeEach`/`afterEach` lifecycle hooks that create the test user (with optional contact info,
+ * custom claims, and post-create initialization) and tear it down afterward.
+ *
+ * @param config - Factory configuration: optional uid generator, custom fixture/instance constructors, user-detail builder, and `initUser` hook.
+ * @returns A function that, given runtime params and a `buildTests` callback, wires the authorized-user fixture into the active test context.
  */ function authorizedUserContextFactory(config) {
     var uidGetter = config.uid, _config_makeInstance = config.makeInstance, makeInstance = _config_makeInstance === void 0 ? function(uid, testInstance) {
         return new AuthorizedUserTestContextInstance(uid, testInstance);
@@ -751,6 +770,9 @@ function _ts_generator$a(thisArg, body) {
  * in the JWT payload. This function flattens those claims onto the top-level decoded token to match
  * the structure of a real `DecodedIdToken`, and injects `auth_time` from the `iat` field.
  *
+ * @param token - Encoded JWT string produced by {@link createEncodedTestFirestoreTokenForUserRecord}.
+ * @returns A {@link DecodedIdToken}-shaped object with custom claims hoisted to the top level and `claims` removed.
+ *
  * @see {@link createEncodedTestFirestoreTokenForUserRecord} for creating the encoded token
  */ function decodeEncodedCreateCustomTokenResult(token) {
     var _ref;
@@ -770,6 +792,9 @@ function _ts_generator$a(thisArg, body) {
  * custom claims already set on the user record. The resulting object is used as the
  * custom claims parameter for `Auth.createCustomToken()` in test token generation.
  *
+ * @param userRecord - Firebase Auth user record whose identity fields and existing custom claims should be folded into the returned claims.
+ * @returns A plain claims object suitable for passing to `Auth.createCustomToken()` in tests.
+ *
  * @see {@link createEncodedTestFirestoreTokenForUserRecord}
  */ function testFirestoreClaimsFromUserRecord(userRecord) {
     var _userRecord_emailVerified;
@@ -1120,6 +1145,9 @@ function _ts_generator$9(thisArg, body) {
  * hooks that create a new document (or wrap an existing one via {@link ModelTestContextDocumentRefParams}),
  * build the test context instance, optionally initialize the document, and clean up after each test.
  *
+ * @param config - Factory configuration that resolves the collection, optionally produces document refs, builds fixtures/instances, and tears down state.
+ * @returns A function that, given runtime params and a `buildTests` callback, registers the model fixture hooks against the active test context.
+ *
  * @see {@link ModelTestContextFactoryParams} for configuration options
  */ function modelTestContextFactory(config) {
     var getCollection = config.getCollection, collectionForDocument = config.collectionForDocument, _config_makeRef = config.makeRef, makeRef = _config_makeRef === void 0 ? function(collection) {
@@ -1217,6 +1245,8 @@ var adminEnvironmentInitialized = false;
  *
  * Useful for guarding against double-initialization or verifying that setup has completed
  * before creating test contexts.
+ *
+ * @returns `true` once {@link initFirebaseAdminTestEnvironment} has run successfully; otherwise `false`.
  */ function isAdminEnvironmentInitialized() {
     return adminEnvironmentInitialized;
 }
@@ -1226,6 +1256,8 @@ var adminEnvironmentInitialized = false;
  * The generated ID has the format `firebase-test-<epoch-millis>`, ensuring each test run
  * operates against an isolated project namespace in the emulators.
  *
+ * @returns A new project ID string of the form `firebase-test-<epoch-millis>`.
+ *
  * @example
  * ```ts
  * const projectId = generateNewProjectId();
@@ -1253,6 +1285,8 @@ var adminEnvironmentInitialized = false;
  * Reads the current `GCLOUD_PROJECT` environment variable.
  *
  * This is the "active" project ID that the Firebase Admin SDK resolves at runtime.
+ *
+ * @returns The current value of `process.env.GCLOUD_PROJECT`, or `undefined` when unset.
  */ function getGCloudProjectId() {
     return process.env.GCLOUD_PROJECT;
 }
@@ -1262,6 +1296,8 @@ var adminEnvironmentInitialized = false;
  * This holds the canonical test project ID set during {@link rollNewGCloudProjectEnvironmentVariable},
  * and is used by {@link applyFirebaseGCloudTestProjectIdToFirebaseConfigEnv} as the source of truth
  * when re-applying the project ID after external libraries overwrite `FIREBASE_CONFIG`.
+ *
+ * @returns The current value of `process.env.GCLOUD_TEST_PROJECT`, or `undefined` when unset.
  */ function getGCloudTestProjectId() {
     return process.env.GCLOUD_TEST_PROJECT;
 }
@@ -1270,6 +1306,9 @@ var adminEnvironmentInitialized = false;
  *
  * This is done as some external testing libraries (firebase-functions-test) will overwrite but we want to enforce using our project id
  * so that each component can also
+ *
+ * @returns The test project ID that was re-applied to `FIREBASE_CONFIG`/`GCLOUD_PROJECT`.
+ * @throws Error when no test project ID is present in the environment (i.e., {@link initFirebaseAdminTestEnvironment} has not been called).
  */ function applyFirebaseGCloudTestProjectIdToFirebaseConfigEnv() {
     var _process_env_FIREBASE_CONFIG;
     // firebase-functions-test overwrites this each time.
@@ -1287,6 +1326,8 @@ var adminEnvironmentInitialized = false;
 }
 /**
  * Should be called before calling/using adminFirebaseTestBuilder(). This should only be called once.
+ *
+ * @param config - Emulator host configuration; each emulator entry must be either a host string or `null` (any `undefined` non-null value will throw).
  */ function initFirebaseAdminTestEnvironment(config) {
     function crashForEmulator(emulator) {
         throw new Error("Emulator for ".concat(emulator, " was not set null or to a host. Crashing to prevent contamination."));
@@ -1503,6 +1544,7 @@ function _ts_generator$8(thisArg, body) {
  *
  * @param drivers - Testing-aware Firestore driver set to attach to the context.
  * @param firestore - The `@google-cloud/firestore` Firestore instance (typically pointed at an emulator).
+ * @returns A {@link TestFirestoreContext} backed by the supplied Firestore client with `drivers` attached for test introspection.
  */ function makeGoogleFirestoreContext(drivers, firestore) {
     var context = firestoreContextFactory(drivers)(firestore);
     context.drivers = drivers;
@@ -1791,6 +1833,7 @@ function _ts_generator$7(thisArg, body) {
  * @param drivers - Testing-aware storage driver set to attach to the context.
  * @param firebaseStorage - The `@google-cloud/storage` Storage instance (typically pointed at an emulator).
  * @param defaultBucketId - Optional default bucket name; when provided, storage operations that omit a bucket will use this.
+ * @returns A {@link TestFirebaseStorageContext} backed by the supplied storage client with `drivers` attached for test introspection.
  */ function makeGoogleFirebaseStorageContext(drivers, firebaseStorage, defaultBucketId) {
     var context = firebaseStorageContextFactory(drivers)(firebaseStorage, {
         defaultBucketId: defaultBucketId
@@ -2616,6 +2659,9 @@ function _ts_generator$5(thisArg, body) {
  * callable requests, and blocking functions for use in integration tests. Each method delegates
  * to the underlying `FeaturesList.wrap()` with appropriate type coercion.
  *
+ * @param instance - The initialized `firebase-functions-test` features list whose `wrap()` is delegated to.
+ * @returns A wrapper object exposing typed `wrap*` helpers for gen 1, gen 2, callable, and blocking functions.
+ *
  * @example
  * ```ts
  * const testEnv = functionsTest();
@@ -2681,6 +2727,10 @@ function _ts_generator$5(thisArg, body) {
  * The returned getter re-wraps on every invocation, so it always reflects the latest function
  * reference from the provided getter — useful when the function under test is re-created between tests.
  *
+ * @param wrapper - The cloud function wrapper providing gen 1 wrap support.
+ * @param getter - Lazy accessor for the gen 1 cloud function under test; re-evaluated on every getter call.
+ * @returns A getter that, when invoked, returns a freshly wrapped gen 1 cloud function ready for invocation in tests.
+ *
  * @example
  * ```ts
  * const getWrapped = wrapCloudFunctionV1ForTests(wrapper, () => myV1Function);
@@ -2699,6 +2749,10 @@ function _ts_generator$5(thisArg, body) {
  * The wrapped callable accepts raw data and {@link CallableContextOptions} (e.g., auth context),
  * simulating an incoming HTTP callable request without needing a running server.
  *
+ * @param wrapper - The cloud function wrapper providing the `wrapCallableRequest` accessor.
+ * @param getter - Lazy accessor for the {@link CallableHttpFunction} under test; re-evaluated on every getter call.
+ * @returns A getter that, when invoked, returns a freshly wrapped callable that accepts raw `data` and {@link CallableContextOptions}.
+ *
  * @example
  * ```ts
  * const getWrapped = wrapCallableRequestForTests(wrapper, () => myCallable);
@@ -3122,6 +3176,8 @@ var functionsInitialized = false;
  * Globally sets whether new {@link FirebaseAdminFunctionTestConfig} instances default to
  * singleton mode. Primarily used in global test setup files.
  *
+ * @param use - When `true`, new function-test configs reuse the firebase-functions-test singleton; when `false`, each suite gets its own instance.
+ *
  * @example
  * ```ts
  * // in jest globalSetup
@@ -3834,6 +3890,9 @@ function _ts_generator$3(thisArg, body) {
  * {@link firebaseAdminTestContextFactory}. This is the simplest way to get a
  * fully configured Firebase Admin + NestJS test context.
  *
+ * @param config - NestJS module + provider configuration plus optional fixture/instance overrides.
+ * @returns A {@link FirebaseAdminNestTestContextFactory} that produces a configured fixture for each test suite.
+ *
  * @example
  * ```ts
  * const f = firebaseAdminNestContextFactory({
@@ -4078,6 +4137,7 @@ function _is_native_reflect_construct$2() {
  * @param config - NestJS module, provider, and fixture configuration.
  * @param f - The parent fixture that is already set up.
  * @param buildTests - Callback that receives the child fixture and registers test cases.
+ * @returns Whatever {@link firebaseAdminNestContextWithFixture} returns after registering the merged child fixture (typically `void`).
  */ function firebaseAdminFunctionNestContextWithFixture(config, f, buildTests) {
     var mergedConfig = _object_spread({
         makeFixture: function makeFixture(parent) {
@@ -4094,6 +4154,9 @@ function _is_native_reflect_construct$2() {
  * default {@link firebaseAdminFunctionTestContextFactory}. This is the simplest entry point
  * for tests that need both NestJS module access and Cloud Function wrapping.
  *
+ * @param config - NestJS module + provider configuration plus optional fixture/instance overrides.
+ * @returns A {@link FirebaseAdminFunctionNestTestContextFactory} that produces a configured fixture for each test suite.
+ *
  * @example
  * ```ts
  * const f = firebaseAdminFunctionNestContextFactory({
@@ -4119,6 +4182,9 @@ var CallableRequestTestMultipleFixtureSuffix = 'WrappedFn';
 /**
  * Type guard that distinguishes a {@link CallableRequestTestSingleConfig} from a
  * {@link CallableRequestTestMultipleConfig} by checking for the presence of the `fn` property.
+ *
+ * @param config - Either a single-function or multiple-function callable test config to inspect.
+ * @returns `true` when `config` carries a single `fn` (single-config variant); `false` when it carries `fns` (map variant).
  */ function isCallableRequestTestSingleConfig(config) {
     return Boolean(config.fn);
 }
@@ -4155,6 +4221,9 @@ function describeCallableRequestTest(label, config, buildTests) {
 /**
  * Type guard that distinguishes a {@link CloudFunctionTestSingleConfig} from a
  * {@link CloudFunctionTestMultipleConfig} by checking for the presence of the `fn` property.
+ *
+ * @param config - Either a single-function or multiple-function cloud function test config to inspect.
+ * @returns `true` when `config` carries a single `fn` (single-config variant); `false` when it carries `fns` (map variant).
  */ function isCloudFunctionTestSingleConfig(config) {
     return Boolean(config.fn);
 }
@@ -4500,8 +4569,8 @@ function _is_native_reflect_construct$1() {
  * Throws a ExpectedErrorOfSpecificTypeError if the input is not a HttpsError.
  * Throws a ExpectedHttpErrorWithSpecificServerErrorCode if the input's server error data has a different error code.
  *
- * @param expectedType
- * @returns
+ * @param expectedCode - The server error code (from the {@link ServerError} carried in `HttpsError.details`) that the caught error must match.
+ * @returns An assertion function suitable for use with `ExpectFailAssertionFunction` that verifies both the error type and its server error code.
  */ function expectFailAssertHttpErrorServerErrorCode(expectedCode) {
     return function(error) {
         if (_instanceof(error, HttpsError)) {
@@ -4736,6 +4805,10 @@ function _ts_generator$1(thisArg, body) {
  *
  * The Auth emulator accepts unsigned JWTs (alg: "none") as long as the audience
  * matches the project ID the Admin SDK was initialized with.
+ *
+ * @param nestApp - Initialized NestJS application used to resolve {@link OidcAccountService} for the project ID.
+ * @param uid - Firebase user ID to embed in the token's `sub`/`user_id` claims.
+ * @returns An unsigned JWT (`alg: "none"`) string suitable for use against the Firebase Auth emulator.
  */ function createTestIdToken(nestApp, uid) {
     return _async_to_generator$1(function() {
         var accountService, projectId, now, payload, header, body;
@@ -4770,6 +4843,9 @@ function _ts_generator$1(thisArg, body) {
 }
 /**
  * Extracts the interaction UID from a redirect to the login/consent frontend URL.
+ *
+ * @param res - Supertest response whose `Location` header points at the login/consent frontend, with `?uid=...` carrying the interaction UID.
+ * @returns The `uid` query parameter from the redirect URL (the interaction identifier issued by `oidc-provider`).
  */ function extractInteractionUid(res) {
     var location = res.headers['location'];
     var url = location.startsWith('/') ? new URL(location, 'http://localhost') : new URL(location);
@@ -4780,6 +4856,8 @@ function _ts_generator$1(thisArg, body) {
  *
  * oidc-provider scopes cookies to specific paths, so supertest.agent()
  * won't forward them between /oidc/* and /interaction/* controllers.
+ *
+ * @returns A pair of helpers — `collectCookies(res)` to absorb `Set-Cookie` headers from a response, and `cookieHeader()` to produce a combined `Cookie` header string for subsequent requests.
  */ function createCookieJar() {
     var cookieJar = new Map();
     function collectCookies(res) {
@@ -4823,6 +4901,10 @@ function _ts_generator$1(thisArg, body) {
 /**
  * Resolves the scopes string from config, or falls back to all registered scopes
  * from `OidcAccountService.allRegisteredScopes`.
+ *
+ * @param nestApp - Initialized NestJS application used to resolve {@link OidcAccountService} when no scopes override is given.
+ * @param config - Optional flow config; when `config.scopes` is set, it is returned verbatim.
+ * @returns The space-separated scope string to pass to the `/oidc/auth` endpoint.
  */ function resolveScopes(nestApp, config) {
     return _async_to_generator$1(function() {
         var accountService;
@@ -4841,17 +4923,26 @@ function _ts_generator$1(thisArg, body) {
         });
     })();
 }
-// MARK: Flow
 /**
  * Performs the full OAuth authorization code flow with PKCE and returns tokens.
  *
  * Steps: create client → PKCE → auth redirect → login → consent → code exchange → token
- */ function performFullOAuthFlow(server, oidcClientService, nestApp, uid, config) {
+ *
+ * @param input - Bag of services and overrides needed to drive the flow end-to-end.
+ * @param input.server - HTTP server returned by `nestApp.getHttpServer()` against which all supertest requests are issued.
+ * @param input.oidcClientService - Service used to create the OAuth client whose credentials drive the flow.
+ * @param input.nestApp - Initialized NestJS application; used to resolve {@link OidcAccountService} for project-id-derived ID tokens and default scopes.
+ * @param input.uid - Firebase user ID for whom the test ID token is minted and the OAuth flow is authorized.
+ * @param input.config - Optional flow overrides (scopes, redirect URI, client name, token endpoint auth method).
+ * @returns The exchanged access token and ID token from the OIDC `/token` endpoint.
+ * @throws Error when the token exchange step fails (the response body and status are included in the message).
+ */ function performFullOAuthFlow(input) {
     return _async_to_generator$1(function() {
-        var _ref, _ref1, _ref2, _createCookieJar, collectCookies, cookieHeader, redirectUri, clientName, tokenEndpointAuthMethod, scopes, _ref3, client_id, client_secret, codeVerifier, codeChallenge, authRes, loginUid, idToken, loginRes, resumeAfterLoginPath, consentRedirectRes, consentUid, consentRes, resumeAfterConsentPath, callbackRedirectRes, callbackUrl, authorizationCode, tokenRes;
+        var _ref, _ref1, _ref2, server, oidcClientService, nestApp, uid, config, _createCookieJar, collectCookies, cookieHeader, redirectUri, clientName, tokenEndpointAuthMethod, scopes, _ref3, client_id, client_secret, codeVerifier, codeChallenge, authRes, loginUid, idToken, loginRes, resumeAfterLoginPath, consentRedirectRes, consentUid, consentRes, resumeAfterConsentPath, callbackRedirectRes, callbackUrl, authorizationCode, tokenRes;
         return _ts_generator$1(this, function(_state) {
             switch(_state.label){
                 case 0:
+                    server = input.server, oidcClientService = input.oidcClientService, nestApp = input.nestApp, uid = input.uid, config = input.config;
                     _createCookieJar = createCookieJar(), collectCookies = _createCookieJar.collectCookies, cookieHeader = _createCookieJar.cookieHeader;
                     redirectUri = (_ref = config === null || config === void 0 ? void 0 : config.redirectUri) !== null && _ref !== void 0 ? _ref : 'https://example.com/callback';
                     clientName = (_ref1 = config === null || config === void 0 ? void 0 : config.clientName) !== null && _ref1 !== void 0 ? _ref1 : 'test-oauth-context';
@@ -4970,6 +5061,11 @@ function _ts_generator$1(thisArg, body) {
  * rotates JWKS keys, and then performs the full OAuth flow.
  *
  * This avoids callers needing to import from `@dereekb/firebase-server/oidc` directly.
+ *
+ * @param nestApp - Initialized NestJS application from which {@link JwksService} and {@link OidcClientService} are resolved.
+ * @param uid - Firebase user ID for whom the OAuth flow is authorized.
+ * @param config - Optional flow overrides (scopes, redirect URI, client name, token endpoint auth method).
+ * @returns The exchanged access token and ID token from {@link performFullOAuthFlow}.
  */ function setupAndPerformFullOAuthFlow(nestApp, uid, config) {
     return _async_to_generator$1(function() {
         var jwksService, oidcClientService, server;
@@ -4989,7 +5085,13 @@ function _ts_generator$1(thisArg, body) {
                     server = nestApp.getHttpServer();
                     return [
                         2,
-                        performFullOAuthFlow(server, oidcClientService, nestApp, uid, config)
+                        performFullOAuthFlow({
+                            server: server,
+                            oidcClientService: oidcClientService,
+                            nestApp: nestApp,
+                            uid: uid,
+                            config: config
+                        })
                     ];
             }
         });
@@ -5261,6 +5363,9 @@ function _ts_generator(thisArg, body) {
             /**
      * Apply Bearer auth to a supertest request.
      *
+     * @param test - An existing supertest request (e.g., `request(server).get(...)`) that should be authorized with this instance's access token.
+     * @returns The same supertest request with an `Authorization: Bearer <accessToken>` header applied for chaining.
+     *
      * @example
      * ```typescript
      * await oauth.withAuth(request(oauth.server).get('/oidc/me')).expect(200);
@@ -5275,6 +5380,10 @@ function _ts_generator(thisArg, body) {
             /**
      * Shorthand: create a supertest request with auth already applied.
      *
+     * @param method - HTTP verb to use for the supertest request (`get`, `post`, `put`, `patch`, or `delete`).
+     * @param path - The URL path on the wrapped server to issue the request against.
+     * @returns A supertest request pointed at `path` and pre-authorized with this instance's `Bearer` access token.
+     *
      * @example
      * ```typescript
      * await oauth.authRequest('get', '/oidc/me').expect(200);
@@ -5314,6 +5423,9 @@ function _ts_generator(thisArg, body) {
             /**
      * Apply Bearer auth to a supertest request.
      *
+     * @param test - An existing supertest request (e.g., `request(server).get(...)`) that should be authorized with the underlying instance's access token.
+     * @returns The same supertest request with an `Authorization: Bearer <accessToken>` header applied for chaining.
+     *
      * @example
      * ```typescript
      * await oauth.withAuth(request(oauth.server).get('/oidc/me')).expect(200);
@@ -5327,6 +5439,10 @@ function _ts_generator(thisArg, body) {
             /**
      * Shorthand: create a supertest request with auth already applied.
      *
+     * @param method - HTTP verb to use for the supertest request (`get`, `post`, `put`, `patch`, or `delete`).
+     * @param path - The URL path on the wrapped server to issue the request against.
+     * @returns A supertest request pointed at `path` and pre-authorized with the underlying instance's `Bearer` access token.
+     *
      * @example
      * ```typescript
      * await oauth.authRequest('get', '/oidc/me').expect(200);
@@ -5353,6 +5469,9 @@ function _ts_generator(thisArg, body) {
  * The returned factory function performs a full OAuth authorization code flow
  * and provides an authenticated supertest agent and helper methods.
  *
+ * @param config - Optional flow overrides (scopes, redirect URI, client name, timeout) and custom fixture/instance constructors.
+ * @returns A function that, given parent fixtures and a `buildTests` callback, registers a `describe('(oauth)', ...)` block which performs the full OAuth flow and exposes the authenticated supertest fixture.
+ *
  * @example
  * ```typescript
  * // In shared test setup (e.g. fixture.oidc.ts)

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.10.9",
+  "version": "13.11.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.10.9",
-    "@dereekb/date": "13.10.9",
-    "@dereekb/firebase": "13.10.9",
-    "@dereekb/firebase-server": "13.10.9",
-    "@dereekb/firebase-server/oidc": "13.10.9",
-    "@dereekb/model": "13.10.9",
-    "@dereekb/nestjs": "13.10.9",
-    "@dereekb/rxjs": "13.10.9",
-    "@dereekb/util": "13.10.9",
+    "@dereekb/analytics": "13.11.0",
+    "@dereekb/date": "13.11.0",
+    "@dereekb/firebase": "13.11.0",
+    "@dereekb/firebase-server": "13.11.0",
+    "@dereekb/firebase-server/oidc": "13.11.0",
+    "@dereekb/model": "13.11.0",
+    "@dereekb/nestjs": "13.11.0",
+    "@dereekb/rxjs": "13.11.0",
+    "@dereekb/util": "13.11.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",
@@ -23,7 +23,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.10.9"
+    "@dereekb/nestjs": "13.11.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/test/src/lib/firebase/firebase.admin.auth.d.ts

@@ -116,9 +116,10 @@ export declare class AuthorizedUserTestContextInstance<PI extends FirebaseAdminT
     /**
      * Calls a wrapped function with the input params and the context from makeContextOptions().
      *
-     * @param fn
-     * @param params
-     * @param skipJsonConversion
+     * @param fn - Wrapped gen 2 callable request to invoke.
+     * @param params - Request payload to pass to the callable, simulating the JSON body of an HTTP call.
+     * @param skipJsonConversion - When `true`, skip the JSON serialize/parse round-trip applied to `params` (default `false`).
+     * @returns A promise resolving to the callable's return value.
      */
     callWrappedFunction<F extends WrappedCallableRequest<any, any>>(fn: F, params: WrappedCallableRequestParams<F>, skipJsonConversion?: boolean): Promise<WrappedCallableRequestOutput<F>>;
     /**
@@ -136,14 +137,24 @@ export declare class AuthorizedUserTestContextInstance<PI extends FirebaseAdminT
     /**
      * Calls a wrapped gen 2 auth blocking function with the input params and context options from makeContextOptions().
      *
-     * @param fn
-     * @param userRecord
-     * @param eventType
-     * @param eventOverride
-     * @param skipJsonConversion
-     * @returns
+     * Synthesizes a minimal {@link AuthBlockingEvent} (filling in placeholder ip/user-agent/resource fields)
+     * from the supplied user record and event type, then dispatches it to the wrapped function.
+     *
+     * @param input - Options bag describing the blocking function invocation.
+     * @param input.fn - Wrapped gen 2 auth blocking function (e.g., from `beforeUserCreated`/`beforeUserSignedIn`) to invoke.
+     * @param input.userRecord - The Firebase Auth {@link UserRecord} that will be attached to the synthesized event's `data` field.
+     * @param input.eventType - Discriminator for the auth event being simulated (`google.firebase.auth.user.create` or `google.firebase.auth.user.delete`).
+     * @param input.eventOverride - Partial event fields used to override the default placeholder values (e.g., `ipAddress`, `userAgent`, `resource`).
+     * @param input.skipJsonConversion - When `true`, skip the JSON serialize/parse round-trip applied to the event payload (default `false`).
+     * @returns A promise that resolves once the blocking function has completed.
      */
-    callAuthBlockingFunction(fn: WrappedBlockingFunctionWithHandler<AuthBlockingEvent, void>, userRecord: UserRecord, eventType: 'google.firebase.auth.user.create' | 'google.firebase.auth.user.delete', eventOverride?: Partial<AuthBlockingEvent>, skipJsonConversion?: boolean): Promise<void>;
+    callAuthBlockingFunction(input: {
+        fn: WrappedBlockingFunctionWithHandler<AuthBlockingEvent, void>;
+        userRecord: UserRecord;
+        eventType: 'google.firebase.auth.user.create' | 'google.firebase.auth.user.delete';
+        eventOverride?: Partial<AuthBlockingEvent>;
+        skipJsonConversion?: boolean;
+    }): Promise<void>;
     /**
      * @deprecated gen 1
      *
@@ -202,6 +213,9 @@ export interface AuthorizedUserTestContextParams<PI extends FirebaseAdminTestCon
 }
 /**
  * Convenience function for using authorizedUserContextFactory directly and passing buildTests.
+ *
+ * @param config - Test context parameters (parent fixture, optional uid/template, custom factories) used to create the authorized user context.
+ * @param buildTests - Callback invoked with the built {@link AuthorizedUserTestContextFixture}; should register `it(...)`/`describe(...)` blocks against it.
  */
 export declare function authorizedUserContext<PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends AuthorizedUserTestContextInstance<PI> = AuthorizedUserTestContextInstance<PI>, F extends AuthorizedUserTestContextFixture<PI, PF, I> = AuthorizedUserTestContextFixture<PI, PF, I>>(config: AuthorizedUserTestContextParams<PI, PF, I, F>, buildTests: (u: F) => void): void;
 /**
@@ -242,6 +256,13 @@ export declare const AUTHORIZED_USER_RANDOM_EMAIL_FACTORY: import("@dereekb/util
 export declare const AUTHORIZED_USER_RANDOM_PHONE_NUMBER_FACTORY: import("@dereekb/util").RandomPhoneNumberFactory;
 /**
  * Creates a new Jest Context that has a random user for authorization for use in firebase server tests.
+ *
+ * The returned function, when called with runtime params and a `buildTests` callback, registers the
+ * `beforeEach`/`afterEach` lifecycle hooks that create the test user (with optional contact info,
+ * custom claims, and post-create initialization) and tear it down afterward.
+ *
+ * @param config - Factory configuration: optional uid generator, custom fixture/instance constructors, user-detail builder, and `initUser` hook.
+ * @returns A function that, given runtime params and a `buildTests` callback, wires the authorized-user fixture into the active test context.
  */
 export declare function authorizedUserContextFactory<PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends AuthorizedUserTestContextInstance<PI> = AuthorizedUserTestContextInstance<PI>, F extends AuthorizedUserTestContextFixture<PI, PF, I> = AuthorizedUserTestContextFixture<PI, PF, I>, C extends AuthorizedUserTestContextFactoryParams<PI, PF> = AuthorizedUserTestContextFactoryParams<PI, PF>>(config: AuthorizedUserTestContextFactoryConfig<PI, PF, I, F>): (params: C, buildTests: (u: F) => void) => void;
 /**
@@ -306,6 +327,9 @@ export declare function createEncodedTestFirestoreTokenForUserRecord(auth: Auth,
  * in the JWT payload. This function flattens those claims onto the top-level decoded token to match
  * the structure of a real `DecodedIdToken`, and injects `auth_time` from the `iat` field.
  *
+ * @param token - Encoded JWT string produced by {@link createEncodedTestFirestoreTokenForUserRecord}.
+ * @returns A {@link DecodedIdToken}-shaped object with custom claims hoisted to the top level and `claims` removed.
+ *
  * @see {@link createEncodedTestFirestoreTokenForUserRecord} for creating the encoded token
  */
 export declare function decodeEncodedCreateCustomTokenResult(token: TestEncodedFirestoreToken): DecodedIdToken;
@@ -316,6 +340,9 @@ export declare function decodeEncodedCreateCustomTokenResult(token: TestEncodedF
  * custom claims already set on the user record. The resulting object is used as the
  * custom claims parameter for `Auth.createCustomToken()` in test token generation.
  *
+ * @param userRecord - Firebase Auth user record whose identity fields and existing custom claims should be folded into the returned claims.
+ * @returns A plain claims object suitable for passing to `Auth.createCustomToken()` in tests.
+ *
  * @see {@link createEncodedTestFirestoreTokenForUserRecord}
  */
 export declare function testFirestoreClaimsFromUserRecord(userRecord: UserRecord): object;

package/test/src/lib/firebase/firebase.admin.collection.d.ts

@@ -132,6 +132,9 @@ export type ModelTestContextParams<C = any, PI extends FirebaseAdminTestContext
  * hooks that create a new document (or wrap an existing one via {@link ModelTestContextDocumentRefParams}),
  * build the test context instance, optionally initialize the document, and clean up after each test.
  *
+ * @param config - Factory configuration that resolves the collection, optionally produces document refs, builds fixtures/instances, and tears down state.
+ * @returns A function that, given runtime params and a `buildTests` callback, registers the model fixture hooks against the active test context.
+ *
  * @see {@link ModelTestContextFactoryParams} for configuration options
  */
 export declare function modelTestContextFactory<T, D extends FirestoreDocument<T> = FirestoreDocument<T>, C = any, PI extends FirebaseAdminTestContext = FirebaseAdminTestContext, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends ModelTestContextInstance<T, D, PI> = ModelTestContextInstance<T, D, PI>, F extends ModelTestContextFixture<T, D, PI, PF, I> = ModelTestContextFixture<T, D, PI, PF, I>, CL extends FirestoreCollectionLike<T, D> = FirestoreCollectionLike<T, D>>(config: ModelTestContextFactoryParams<T, D, C, PI, PF, I, F, CL>): (params: ModelTestContextParams<C, PI, PF>, buildTests: (u: F) => void) => void;

package/test/src/lib/firebase/firebase.admin.function.d.ts

@@ -100,6 +100,8 @@ export declare let DEFAULT_FIREBASE_ADMIN_FUNCTION_TEST_USE_FUNCTION_SINGLETON_C
  * Globally sets whether new {@link FirebaseAdminFunctionTestConfig} instances default to
  * singleton mode. Primarily used in global test setup files.
  *
+ * @param use - When `true`, new function-test configs reuse the firebase-functions-test singleton; when `false`, each suite gets its own instance.
+ *
  * @example
  * ```ts
  * // in jest globalSetup

package/test/src/lib/firebase/firebase.admin.nest.d.ts

@@ -179,6 +179,9 @@ export declare function firebaseAdminNestContextWithFixture<PI extends FirebaseA
  * {@link firebaseAdminTestContextFactory}. This is the simplest way to get a
  * fully configured Firebase Admin + NestJS test context.
  *
+ * @param config - NestJS module + provider configuration plus optional fixture/instance overrides.
+ * @returns A {@link FirebaseAdminNestTestContextFactory} that produces a configured fixture for each test suite.
+ *
  * @example
  * ```ts
  * const f = firebaseAdminNestContextFactory({

package/test/src/lib/firebase/firebase.admin.nest.function.callable.context.d.ts

@@ -67,6 +67,9 @@ export type CallableRequestTestMultipleFunction<T extends CallableRequestTestCon
 /**
  * Type guard that distinguishes a {@link CallableRequestTestSingleConfig} from a
  * {@link CallableRequestTestMultipleConfig} by checking for the presence of the `fn` property.
+ *
+ * @param config - Either a single-function or multiple-function callable test config to inspect.
+ * @returns `true` when `config` carries a single `fn` (single-config variant); `false` when it carries `fns` (map variant).
  */
 export declare function isCallableRequestTestSingleConfig<I, T extends CallableRequestTestConfigMapObject>(config: CallableRequestTestSingleConfig<I> | CallableRequestTestMultipleConfig<I, T>): config is CallableRequestTestSingleConfig<I>;
 /**

package/test/src/lib/firebase/firebase.admin.nest.function.cloud.context.d.ts

@@ -64,6 +64,9 @@ export type CloudFunctionTestMultipleFunction<T extends CloudFunctionTestConfigM
 /**
  * Type guard that distinguishes a {@link CloudFunctionTestSingleConfig} from a
  * {@link CloudFunctionTestMultipleConfig} by checking for the presence of the `fn` property.
+ *
+ * @param config - Either a single-function or multiple-function cloud function test config to inspect.
+ * @returns `true` when `config` carries a single `fn` (single-config variant); `false` when it carries `fns` (map variant).
  */
 export declare function isCloudFunctionTestSingleConfig<I extends object, T extends CloudFunctionTestConfigMapObject>(config: CloudFunctionTestSingleConfig<I> | CloudFunctionTestMultipleConfig<I, T>): config is CloudFunctionTestSingleConfig<I>;
 /**

package/test/src/lib/firebase/firebase.admin.nest.function.d.ts

@@ -106,6 +106,7 @@ export declare class FirebaseAdminFunctionNestRootModule {
  * @param config - NestJS module, provider, and fixture configuration.
  * @param f - The parent fixture that is already set up.
  * @param buildTests - Callback that receives the child fixture and registers test cases.
+ * @returns Whatever {@link firebaseAdminNestContextWithFixture} returns after registering the merged child fixture (typically `void`).
  */
 export declare function firebaseAdminFunctionNestContextWithFixture<PI extends FirebaseAdminFunctionTestContextInstance = FirebaseAdminFunctionTestContextInstance, PF extends TestContextFixture<PI> = TestContextFixture<PI>, I extends FirebaseAdminFunctionNestTestContextInstance<PI> = FirebaseAdminFunctionNestTestContextInstance<PI>, C extends FirebaseAdminFunctionNestTestContextFixture<PI, PF, I> = FirebaseAdminFunctionNestTestContextFixture<PI, PF, I>>(config: FirebaseAdminFunctionNestTestConfig<PI, PF, I, C>, f: PF, buildTests: BuildTestsWithContextFunction<C>): void;
 /**
@@ -113,6 +114,9 @@ export declare function firebaseAdminFunctionNestContextWithFixture<PI extends F
  * default {@link firebaseAdminFunctionTestContextFactory}. This is the simplest entry point
  * for tests that need both NestJS module access and Cloud Function wrapping.
  *
+ * @param config - NestJS module + provider configuration plus optional fixture/instance overrides.
+ * @returns A {@link FirebaseAdminFunctionNestTestContextFactory} that produces a configured fixture for each test suite.
+ *
  * @example
  * ```ts
  * const f = firebaseAdminFunctionNestContextFactory({