@dereekb/firebase-server 13.10.9 → 13.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.10.9",
+  "version": "13.11.1",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -44,15 +44,15 @@
   "main": "./index.cjs.js",
   "types": "./src/index.d.ts",
   "peerDependencies": {
-    "@dereekb/analytics": "13.10.9",
-    "@dereekb/date": "13.10.9",
-    "@dereekb/dbx-core": "13.10.9",
-    "@dereekb/firebase": "13.10.9",
-    "@dereekb/model": "13.10.9",
-    "@dereekb/nestjs": "13.10.9",
-    "@dereekb/rxjs": "13.10.9",
-    "@dereekb/util": "13.10.9",
-    "@dereekb/zoho": "13.10.9",
+    "@dereekb/analytics": "13.11.1",
+    "@dereekb/date": "13.11.1",
+    "@dereekb/dbx-core": "13.11.1",
+    "@dereekb/firebase": "13.11.1",
+    "@dereekb/model": "13.11.1",
+    "@dereekb/nestjs": "13.11.1",
+    "@dereekb/rxjs": "13.11.1",
+    "@dereekb/util": "13.11.1",
+    "@dereekb/zoho": "13.11.1",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",

package/src/lib/nest/model/index.d.ts

@@ -2,6 +2,7 @@ export * from './analytics.details';
 export * from './analytics.emit';
 export * from './analytics.handler';
 export * from './api.details';
+export * from './crud.assert.function';
 export * from './permission.error';
 export * from './specifier.function';
 export * from './call.model.function';

package/test/index.cjs.js

@@ -337,6 +337,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;
@@ -420,9 +423,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.
@@ -449,15 +453,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',
@@ -485,7 +493,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);
@@ -499,6 +508,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
@@ -518,6 +530,13 @@ function _ts_generator$a(thisArg, body) {
  */ var AUTHORIZED_USER_RANDOM_PHONE_NUMBER_FACTORY = 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.
  */ function authorizedUserContextFactory(config) {
     var uidGetter = config.uid, _config_makeInstance = config.makeInstance, makeInstance = _config_makeInstance === void 0 ? function(uid, testInstance) {
         return new AuthorizedUserTestContextInstance(uid, testInstance);
@@ -752,6 +771,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;
@@ -771,6 +793,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;
@@ -1121,6 +1146,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) {
@@ -1218,6 +1246,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;
 }
@@ -1227,6 +1257,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();
@@ -1254,6 +1286,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;
 }
@@ -1263,6 +1297,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;
 }
@@ -1271,6 +1307,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.
@@ -1288,6 +1327,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."));
@@ -1504,6 +1545,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 = firebase.firestoreContextFactory(drivers)(firestore);
     context.drivers = drivers;
@@ -1792,6 +1834,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 = firebase.firebaseStorageContextFactory(drivers)(firebaseStorage, {
         defaultBucketId: defaultBucketId
@@ -2617,6 +2660,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();
@@ -2682,6 +2728,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);
@@ -2700,6 +2750,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);
@@ -3123,6 +3177,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
@@ -3835,6 +3891,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({
@@ -4079,6 +4138,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) {
@@ -4095,6 +4155,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({
@@ -4120,6 +4183,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);
 }
@@ -4156,6 +4222,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);
 }
@@ -4501,8 +4570,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, https.HttpsError)) {
@@ -4737,6 +4806,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;
@@ -4771,6 +4844,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);
@@ -4781,6 +4857,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) {
@@ -4824,6 +4902,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;
@@ -4842,17 +4924,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';
@@ -4971,6 +5062,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;
@@ -4990,7 +5086,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
+                        })
                     ];
             }
         });
@@ -5262,6 +5364,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);
@@ -5276,6 +5381,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);
@@ -5315,6 +5424,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);
@@ -5328,6 +5440,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);
@@ -5354,6 +5470,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)