@dereekb/firebase-server 13.10.9 → 13.11.0

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

@@ -37,6 +37,8 @@ export interface FirebaseAdminTestEnvironmentConfig {
  *
  * 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`.
  */
 export declare function isAdminEnvironmentInitialized(): boolean;
 /**
@@ -45,6 +47,8 @@ export declare function isAdminEnvironmentInitialized(): boolean;
  * 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();
@@ -66,6 +70,8 @@ export declare function rollNewGCloudProjectEnvironmentVariable(): string;
  * 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.
  */
 export declare function getGCloudProjectId(): string | undefined;
 /**
@@ -74,6 +80,8 @@ export declare function getGCloudProjectId(): string | undefined;
  * 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.
  */
 export declare function getGCloudTestProjectId(): string | undefined;
 /**
@@ -81,9 +89,14 @@ export declare function getGCloudTestProjectId(): string | undefined;
  *
  * 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).
  */
 export declare function applyFirebaseGCloudTestProjectIdToFirebaseConfigEnv(): string;
 /**
  * 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).
  */
 export declare function initFirebaseAdminTestEnvironment(config: FirebaseAdminTestEnvironmentConfig): void;

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

@@ -166,6 +166,9 @@ export interface FirebaseAdminCloudFunctionWrapper {
  * 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();
@@ -181,6 +184,10 @@ export declare function firebaseAdminCloudFunctionWrapper(instance: FeaturesList
  * 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);
@@ -196,6 +203,10 @@ export declare function wrapCloudFunctionV1ForTests<I, T extends WrapCloudFuncti
  * Re-wraps on every invocation so it always reflects the latest function reference,
  * which is important when the function under test is re-created between test cases.
  *
+ * @param wrapper - The cloud function wrapper providing gen 2 wrap support.
+ * @param getter - Lazy accessor for the gen 2 cloud function under test; re-evaluated on every getter call.
+ * @returns A getter that, when invoked, returns a freshly wrapped gen 2 cloud function ready for invocation in tests.
+ *
  * @example
  * ```ts
  * const getWrapped = wrapCloudFunctionV2ForTests(wrapper, () => myV2CloudFunction);
@@ -210,6 +221,10 @@ export declare function wrapCloudFunctionV2ForTests<E extends CloudEvent<unknown
  * This is the most general wrapper — use it when you do not need to distinguish between
  * function generations in your test setup.
  *
+ * @param wrapper - The cloud function wrapper providing the unified `wrapCloudFunction` accessor.
+ * @param getter - Lazy accessor for the cloud function under test (gen 1 or gen 2); re-evaluated on every getter call.
+ * @returns A getter that, when invoked, returns a freshly wrapped cloud function exposing the unified `WrappedCloudFunction` signature.
+ *
  * @example
  * ```ts
  * const getWrapped = wrapCloudFunctionTests(wrapper, () => myFunction);
@@ -223,6 +238,10 @@ export declare function wrapCloudFunctionTests<I extends object>(wrapper: Fireba
  * 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);

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

@@ -15,8 +15,8 @@ export declare class ExpectedHttpErrorWithSpecificServerErrorCode extends BaseEr
  * 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.
  */
 export declare function expectFailAssertHttpErrorServerErrorCode(expectedCode: string): ExpectFailAssertionFunction;
 /**

package/test/src/lib/firestore/firestore.d.ts

@@ -22,6 +22,7 @@ export type GoogleCloudTestFirestoreContext = TestFirestoreContext;
  *
  * @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.
  */
 export declare function makeGoogleFirestoreContext(drivers: TestingFirestoreDrivers, firestore: Firestore): TestFirestoreContext;
 /**

package/test/src/lib/oidc/oidc.test.fixture.d.ts

@@ -56,6 +56,9 @@ export declare class OAuthAuthorizedSuperTestInstance {
     /**
      * 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);
@@ -66,6 +69,10 @@ export declare class OAuthAuthorizedSuperTestInstance {
     /**
      * 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);
@@ -83,6 +90,9 @@ export declare class OAuthAuthorizedSuperTestFixture extends AbstractTestContext
     /**
      * 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);
@@ -92,6 +102,10 @@ export declare class OAuthAuthorizedSuperTestFixture extends AbstractTestContext
     /**
      * 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);
@@ -106,6 +120,9 @@ export declare class OAuthAuthorizedSuperTestFixture extends AbstractTestContext
  * 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/src/lib/oidc/oidc.test.flow.d.ts

@@ -28,16 +28,40 @@ export interface PerformFullOAuthFlowResult {
     readonly accessToken: string;
     readonly idToken: string;
 }
+/**
+ * Input for {@link performFullOAuthFlow}.
+ */
+export interface PerformFullOAuthFlowInput {
+    readonly server: ReturnType<INestApplication['getHttpServer']>;
+    readonly oidcClientService: OidcClientService;
+    readonly nestApp: INestApplication;
+    readonly uid: string;
+    readonly config?: OAuthTestFlowConfig;
+}
 /**
  * Performs the full OAuth authorization code flow with PKCE and returns tokens.
  *
  * Steps: create client → PKCE → auth redirect → login → consent → code exchange → token
+ *
+ * @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).
  */
-export declare function performFullOAuthFlow(server: ReturnType<INestApplication['getHttpServer']>, oidcClientService: OidcClientService, nestApp: INestApplication, uid: string, config?: OAuthTestFlowConfig): Promise<PerformFullOAuthFlowResult>;
+export declare function performFullOAuthFlow(input: PerformFullOAuthFlowInput): Promise<PerformFullOAuthFlowResult>;
 /**
  * Higher-level helper that resolves OIDC services from the NestJS DI container,
  * 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}.
  */
 export declare function setupAndPerformFullOAuthFlow(nestApp: INestApplication, uid: string, config?: OAuthTestFlowConfig): Promise<PerformFullOAuthFlowResult>;

package/test/src/lib/storage/storage.d.ts

@@ -22,6 +22,7 @@ export type GoogleCloudTestFirebaseStorageContext = TestFirebaseStorageContext;
  * @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.
  */
 export declare function makeGoogleFirebaseStorageContext(drivers: TestingFirebaseStorageDrivers, firebaseStorage: FirebaseStorage, defaultBucketId?: string): TestFirebaseStorageContext;
 /**

package/zoho/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.10.9",
+  "version": "13.11.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.10.9",
-    "@dereekb/date": "13.10.9",
-    "@dereekb/model": "13.10.9",
-    "@dereekb/nestjs": "13.10.9",
-    "@dereekb/rxjs": "13.10.9",
-    "@dereekb/firebase": "13.10.9",
-    "@dereekb/util": "13.10.9",
-    "@dereekb/zoho": "13.10.9"
+    "@dereekb/analytics": "13.11.0",
+    "@dereekb/date": "13.11.0",
+    "@dereekb/model": "13.11.0",
+    "@dereekb/nestjs": "13.11.0",
+    "@dereekb/rxjs": "13.11.0",
+    "@dereekb/firebase": "13.11.0",
+    "@dereekb/util": "13.11.0",
+    "@dereekb/zoho": "13.11.0"
   },
   "exports": {
     "./package.json": "./package.json",