@stevenkellner/team-conduct-api 1.0.35 → 2.0.1

package/lib/test/types/UserRole.test.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@assertive-ts/core");
+const UserRole_1 = require("../../src/types/UserRole");
+const Locale_1 = require("../../src/types/Locale");
+describe('UserRole', () => {
+    describe('UserRole type', () => {
+        it('should be valid user role types', () => {
+            const role1 = 'person-manager';
+            const role2 = 'fineTemplate-manager';
+            const role3 = 'fine-manager';
+            const role4 = 'fine-can-add';
+            const role5 = 'team-manager';
+            (0, core_1.expect)(role1).toBeEqual('person-manager');
+            (0, core_1.expect)(role2).toBeEqual('fineTemplate-manager');
+            (0, core_1.expect)(role3).toBeEqual('fine-manager');
+            (0, core_1.expect)(role4).toBeEqual('fine-can-add');
+            (0, core_1.expect)(role5).toBeEqual('team-manager');
+        });
+    });
+    describe('UserRole.all', () => {
+        it('should contain all user roles', () => {
+            (0, core_1.expect)(UserRole_1.UserRole.all).toBeEqual([
+                'person-manager',
+                'fineTemplate-manager',
+                'fine-manager',
+                'fine-can-add',
+                'team-manager'
+            ]);
+        });
+        it('should have exactly 5 roles', () => {
+            (0, core_1.expect)(UserRole_1.UserRole.all.length).toBeEqual(5);
+        });
+        it('should contain person-manager', () => {
+            (0, core_1.expect)(UserRole_1.UserRole.all.includes('person-manager')).toBeTrue();
+        });
+        it('should contain fineTemplate-manager', () => {
+            (0, core_1.expect)(UserRole_1.UserRole.all.includes('fineTemplate-manager')).toBeTrue();
+        });
+        it('should contain fine-manager', () => {
+            (0, core_1.expect)(UserRole_1.UserRole.all.includes('fine-manager')).toBeTrue();
+        });
+        it('should contain fine-can-add', () => {
+            (0, core_1.expect)(UserRole_1.UserRole.all.includes('fine-can-add')).toBeTrue();
+        });
+        it('should contain team-manager', () => {
+            (0, core_1.expect)(UserRole_1.UserRole.all.includes('team-manager')).toBeTrue();
+        });
+        it('should contain only valid string types', () => {
+            for (const role of UserRole_1.UserRole.all) {
+                (0, core_1.expect)(typeof role).toBeEqual('string');
+                (0, core_1.expect)(role.length).toBeGreaterThan(0);
+            }
+        });
+    });
+    describe('UserRole.formatted', () => {
+        describe('formatted with en locale', () => {
+            it('should format person-manager', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('person-manager', 'en')).toBeEqual('Person Manager');
+            });
+            it('should format fineTemplate-manager', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('fineTemplate-manager', 'en')).toBeEqual('Fine Template Manager');
+            });
+            it('should format fine-manager', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('fine-manager', 'en')).toBeEqual('Fine Manager');
+            });
+            it('should format fine-can-add', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('fine-can-add', 'en')).toBeEqual('Can add fines');
+            });
+            it('should format team-manager', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('team-manager', 'en')).toBeEqual('Team Manager');
+            });
+        });
+        describe('formatted with de locale', () => {
+            it('should format person-manager', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('person-manager', 'de')).toBeEqual('Personenmanager');
+            });
+            it('should format fineTemplate-manager', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('fineTemplate-manager', 'de')).toBeEqual('Strafvorlagenmanager');
+            });
+            it('should format fine-manager', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('fine-manager', 'de')).toBeEqual('Strafenmanager');
+            });
+            it('should format fine-can-add', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('fine-can-add', 'de')).toBeEqual('Kann Strafen hinzufügen');
+            });
+            it('should format team-manager', () => {
+                (0, core_1.expect)(UserRole_1.UserRole.formatted('team-manager', 'de')).toBeEqual('Teammanager');
+            });
+        });
+        describe('formatted for all roles and locales', () => {
+            it('should format all roles in all locales', () => {
+                for (const role of UserRole_1.UserRole.all) {
+                    for (const locale of Locale_1.Locale.all) {
+                        const formatted = UserRole_1.UserRole.formatted(role, locale);
+                        (0, core_1.expect)(typeof formatted).toBeEqual('string');
+                        (0, core_1.expect)(formatted.length).toBeGreaterThan(0);
+                    }
+                }
+            });
+            it('should return different values for different locales', () => {
+                for (const role of UserRole_1.UserRole.all) {
+                    const formattedEN = UserRole_1.UserRole.formatted(role, 'en');
+                    const formattedDE = UserRole_1.UserRole.formatted(role, 'de');
+                    // Most roles should have different translations
+                    // (though some might be similar, so we just check they're strings)
+                    (0, core_1.expect)(typeof formattedEN).toBeEqual('string');
+                    (0, core_1.expect)(typeof formattedDE).toBeEqual('string');
+                }
+            });
+        });
+    });
+    describe('UserRole.builder', () => {
+        it('should build valid user role from string', () => {
+            const role1 = UserRole_1.UserRole.builder.build('person-manager');
+            const role2 = UserRole_1.UserRole.builder.build('team-manager');
+            (0, core_1.expect)(role1).toBeEqual('person-manager');
+            (0, core_1.expect)(role2).toBeEqual('team-manager');
+        });
+        it('should preserve user role value', () => {
+            for (const role of UserRole_1.UserRole.all) {
+                const built = UserRole_1.UserRole.builder.build(role);
+                (0, core_1.expect)(built).toBeEqual(role);
+            }
+        });
+        it('should build all user roles', () => {
+            const roles = [
+                'person-manager',
+                'fineTemplate-manager',
+                'fine-manager',
+                'fine-can-add',
+                'team-manager'
+            ];
+            for (const role of roles) {
+                const built = UserRole_1.UserRole.builder.build(role);
+                (0, core_1.expect)(built).toBeEqual(role);
+            }
+        });
+    });
+});

package/lib/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../index.ts","../src/Firestore.ts","../src/FirestoreScheme.ts","../src/checkAuthentication.ts","../src/firebaseFunctionsContext.ts","../src/index.ts","../src/pushNotification.ts","../src/firebase/FirebaseConfiguration.ts","../src/firebase/Messaging.ts","../src/firebase/index.ts","../src/functions/index.ts","../src/functions/fine/add.ts","../src/functions/fine/delete.ts","../src/functions/fine/update.ts","../src/functions/fineTemplate/add.ts","../src/functions/fineTemplate/delete.ts","../src/functions/fineTemplate/update.ts","../src/functions/invitation/getInvitation.ts","../src/functions/invitation/invite.ts","../src/functions/invitation/register.ts","../src/functions/invitation/withdraw.ts","../src/functions/notification/register.ts","../src/functions/notification/subscribe.ts","../src/functions/paypalMe/edit.ts","../src/functions/person/add.ts","../src/functions/person/delete.ts","../src/functions/person/update.ts","../src/functions/team/new.ts","../src/functions/user/kickout.ts","../src/functions/user/login.ts","../src/functions/user/roleEdit.ts","../src/locales/de.ts","../src/locales/en.ts","../src/types/Configuration.ts","../src/types/Fine.ts","../src/types/FineAmount.ts","../src/types/FineTemplate.ts","../src/types/FineTemplateRepetition.ts","../src/types/Invitation.ts","../src/types/Localization.ts","../src/types/MoneyAmount.ts","../src/types/NotificationProperties.ts","../src/types/PayedState.ts","../src/types/Person.ts","../src/types/PersonPrivateProperties.ts","../src/types/PersonSignInProperties.ts","../src/types/Pluralization.ts","../src/types/Team.ts","../src/types/User.ts","../src/types/UserRole.ts","../src/types/index.ts","../test/localization-utils.ts","../test/localization.de.test.ts","../test/localization.en.test.ts"],"version":"5.8.3"}
+{"root":["../index.ts","../src/index.ts","../src/firebase/FirebaseConfiguration.ts","../src/firebase/Firestore.ts","../src/firebase/FirestoreScheme.ts","../src/firebase/Messaging.ts","../src/firebase/checkAuthentication.ts","../src/firebase/index.ts","../src/firebase/pushNotification.ts","../src/functions/index.ts","../src/functions/fine/add.ts","../src/functions/fine/delete.ts","../src/functions/fine/update.ts","../src/functions/fineTemplate/add.ts","../src/functions/fineTemplate/delete.ts","../src/functions/fineTemplate/update.ts","../src/functions/invitation/getInvitation.ts","../src/functions/invitation/invite.ts","../src/functions/invitation/register.ts","../src/functions/invitation/withdraw.ts","../src/functions/notification/register.ts","../src/functions/notification/subscribe.ts","../src/functions/paypalMe/edit.ts","../src/functions/person/add.ts","../src/functions/person/delete.ts","../src/functions/person/update.ts","../src/functions/team/new.ts","../src/functions/user/kickout.ts","../src/functions/user/login.ts","../src/functions/user/roleEdit.ts","../src/locales/de.ts","../src/locales/en.ts","../src/types/Configuration.ts","../src/types/Currency.ts","../src/types/Fine.ts","../src/types/FineAmount.ts","../src/types/FineTemplate.ts","../src/types/FineTemplateRepetition.ts","../src/types/Invitation.ts","../src/types/Locale.ts","../src/types/Localization.ts","../src/types/MoneyAmount.ts","../src/types/NotificationProperties.ts","../src/types/PayedState.ts","../src/types/Person.ts","../src/types/PersonPrivateProperties.ts","../src/types/PersonSignInProperties.ts","../src/types/Pluralization.ts","../src/types/Team.ts","../src/types/User.ts","../src/types/UserRole.ts","../src/types/index.ts","../test/firebase/FirebaseConfiguration.test.ts","../test/firebase/Firestore.test.ts","../test/firebase/checkAuthentication.test.ts","../test/firebase/firebase-utils.ts","../test/firebase/pushNotification.test.ts","../test/locales/localization.de.test.ts","../test/locales/localization.en.test.ts","../test/types/Configuration.test.ts","../test/types/Currency.test.ts","../test/types/Fine.test.ts","../test/types/FineAmount.test.ts","../test/types/FineTemplate.test.ts","../test/types/FineTemplateRepetition.test.ts","../test/types/Invitation.test.ts","../test/types/Locale.test.ts","../test/types/Localization.test.ts","../test/types/MoneyAmount.test.ts","../test/types/NotificationProperties.test.ts","../test/types/PayedState.test.ts","../test/types/Person.test.ts","../test/types/PersonPrivateProperties.test.ts","../test/types/PersonSignInProperties.test.ts","../test/types/Pluralization.test.ts","../test/types/Team.test.ts","../test/types/User.test.ts","../test/types/UserRole.test.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stevenkellner/team-conduct-api",
-    "version": "1.0.35",
+    "version": "2.0.1",
     "description": "Firebase API for Team Conduct",
     "license": "MIT",
     "author": "Steven Kellner",
@@ -27,17 +27,18 @@
     },
     "devDependencies": {
         "@assertive-ts/core": "^2.1.0",
-        "@eslint/compat": "^1.3.1",
-        "@eslint/eslintrc": "^3.3.1",
-        "@eslint/js": "^9.30.0",
+        "@eslint/compat": "^2.0.0",
+        "@eslint/eslintrc": "^3.3.3",
+        "@eslint/js": "^9.39.2",
         "@types/mocha": "^10.0.10",
-        "@typescript-eslint/eslint-plugin": "^8.35.0",
-        "@typescript-eslint/parser": "^8.35.0",
-        "eslint": "^9.30.0",
+        "@typescript-eslint/eslint-plugin": "^8.50.1",
+        "@typescript-eslint/parser": "^8.50.1",
+        "eslint": "^9.39.2",
         "eslint-config-google": "^0.14.0",
         "eslint-plugin-import": "^2.32.0",
-        "mocha": "^11.7.1",
+        "mocha": "^11.7.5",
+        "npm-check-updates": "^19.2.0",
         "ts-node": "^10.9.2",
-        "typescript": "^5.8.3"
+        "typescript": "^5.9.3"
     }
 }

package/src/firebase/FirebaseConfiguration.ts

@@ -1,8 +1,17 @@
-import { FirestoreScheme } from '../FirestoreScheme';
+import { FirestoreScheme } from './FirestoreScheme';
 import { Messaging } from './Messaging';
 
+/**
+ * Singleton configuration manager for Firebase services.
+ *
+ * Provides centralized access to Firestore document reference and Firebase Cloud Messaging.
+ * Must be configured once before accessing services.
+ */
 export class FirebaseConfiguration {
 
+    /**
+     * Singleton instance of FirebaseConfiguration.
+     */
     public static readonly shared = new FirebaseConfiguration();
 
     private configured: boolean = false;
@@ -11,8 +20,20 @@ export class FirebaseConfiguration {
 
     private _messaging: Messaging | null = null;
 
+    /**
+     * Private constructor to enforce singleton pattern.
+     */
     private constructor() {}
 
+    /**
+     * Configures the Firebase services.
+     *
+     * Must be called exactly once before accessing any Firebase services.
+     * Subsequent calls will throw an error.
+     *
+     * @param configuration - Configuration object containing Firestore and Messaging services
+     * @throws Error if already configured
+     */
     public configure(configuration: {
         baseFirestoreDocument: FirestoreScheme,
         messaging: Messaging
@@ -24,12 +45,39 @@ export class FirebaseConfiguration {
         this.configured = true;
     }
 
+    /**
+     * Reconfigures the Firebase services.
+     *
+     * Allows updating the configuration with new services.
+     *
+     * @param configuration - New configuration object containing Firestore and Messaging services
+     */
+    public reconfigure(configuration: {
+        baseFirestoreDocument: FirestoreScheme,
+        messaging: Messaging
+    }) {
+        this.configured = false;
+        this.configure(configuration);
+    }
+
+    /**
+     * Gets the base Firestore document reference.
+     *
+     * @returns The configured Firestore document scheme
+     * @throws Error if not yet configured
+     */
     public get baseFirestoreDocument(): FirestoreScheme {
         if (!this.configured || !this._baseFirestoreDocument)
             throw new Error('Configuration.baseFirestoreDocument is not configured');
         return this._baseFirestoreDocument;
     }
 
+    /**
+     * Gets the Firebase Cloud Messaging service.
+     *
+     * @returns The configured Messaging service
+     * @throws Error if not yet configured
+     */
     public get messaging(): Messaging {
         if (!this.configured || !this._messaging)
             throw new Error('Configuration.messaging is not configured');

package/src/firebase/Firestore.ts

@@ -0,0 +1,248 @@
+import { FirestoreCollection, FirestoreDocument } from '@stevenkellner/firebase-function';
+import { FirestoreScheme } from './FirestoreScheme';
+import { Fine, FineTemplate, Invitation, Person, User, Team } from '../types';
+import { FirebaseConfiguration } from '.';
+
+/**
+ * Accessor class for Firestore documents and collections.
+ * 
+ * Provides type-safe access to Firestore database documents and collections
+ * following the schema defined in {@link FirestoreScheme}.
+ * 
+ * Uses a singleton pattern to ensure consistent access to the Firestore instance.
+ * All methods return strongly-typed Firestore references that can be used for
+ * database operations.
+ * 
+ * @example
+ * ```typescript
+ * // Access a team document
+ * const teamDoc = Firestore.shared.team(teamId);
+ * 
+ * // Access a person in a team
+ * const personDoc = Firestore.shared.person(teamId, personId);
+ * 
+ * // Access all fines in a team
+ * const finesCollection = Firestore.shared.fines(teamId);
+ * ```
+ * 
+ * @remarks
+ * Requires {@link FirebaseConfiguration} to be configured before use.
+ * All document and collection references are lazy and don't perform any
+ * database operations until explicitly called.
+ */
+export class Firestore {
+
+    /**
+     * Protected constructor to enforce singleton pattern.
+     * Use {@link Firestore.shared} to get an instance.
+     */
+    protected constructor() {}
+
+    /**
+     * The singleton instance of the Firestore accessor.
+     * 
+     * @private
+     */
+    private static sharedInstance: Firestore | null = null;
+
+    /**
+     * Gets the singleton instance of the Firestore accessor.
+     * 
+     * Creates the instance on first access and returns the same instance
+     * on subsequent calls.
+     * 
+     * @returns The singleton Firestore accessor instance
+     * 
+     * @example
+     * ```typescript
+     * const firestore = Firestore.shared;
+     * const teamDoc = firestore.team(teamId);
+     * ```
+     */
+    public static get shared(): Firestore {
+        if (!Firestore.sharedInstance)
+            Firestore.sharedInstance = new Firestore();
+        return Firestore.sharedInstance;
+    }
+
+    /**
+     * Gets the base Firestore schema from the configured Firebase instance.
+     * 
+     * Accesses the global FirebaseConfiguration to retrieve the root document
+     * reference for all database operations.
+     * 
+     * @returns The base Firestore schema with typed collections
+     * 
+     * @throws {Error} If FirebaseConfiguration has not been configured
+     * 
+     * @private
+     */
+    private get base(): FirestoreScheme {
+        return FirebaseConfiguration.shared.baseFirestoreDocument;
+    }
+
+    /**
+     * Gets a reference to a team document.
+     * 
+     * @param id - The unique identifier of the team
+     * @returns A typed Firestore document reference for the team
+     * 
+     * @example
+     * ```typescript
+     * const teamDoc = Firestore.shared.team(teamId);
+     * const teamData = await teamDoc.get();
+     * ```
+     */
+    public team(id: Team.Id): FirestoreDocument<Team> {
+        return this.base
+            .collection('teams')
+            .document(id.guidString) as FirestoreDocument<Team>;
+    }
+
+    /**
+     * Gets a reference to a user document.
+     * 
+     * @param id - The unique identifier of the user
+     * @returns A typed Firestore document reference for the user
+     * 
+     * @example
+     * ```typescript
+     * const userDoc = Firestore.shared.user(userId);
+     * const userData = await userDoc.get();
+     * ```
+     */
+    public user(id: User.Id): FirestoreDocument<User> {
+        return this.base
+            .collection('users')
+            .document(id.value);
+    }
+
+    /**
+     * Gets a reference to an invitation document.
+     * 
+     * @param id - The unique identifier of the invitation
+     * @returns A typed Firestore document reference for the invitation
+     * 
+     * @example
+     * ```typescript
+     * const invitationDoc = Firestore.shared.invitation(invitationId);
+     * const invitationData = await invitationDoc.get();
+     * ```
+     */
+    public invitation(id: Invitation.Id): FirestoreDocument<Invitation> {
+        return this.base
+            .collection('invitations')
+            .document(id.value);
+    }
+
+    /**
+     * Gets a reference to the persons collection within a team.
+     * 
+     * @param teamId - The unique identifier of the team
+     * @returns A typed Firestore collection reference for persons in the team
+     * 
+     * @example
+     * ```typescript
+     * const personsCollection = Firestore.shared.persons(teamId);
+     * const allPersons = await personsCollection.getAll();
+     * ```
+     */
+    public persons(teamId: Team.Id): FirestoreCollection<{ [x: string]: FirestoreDocument<Person, never>; }> {
+        return this.base
+            .collection('teams')
+            .document(teamId.guidString)
+            .collection('persons');
+    }
+
+    /**
+     * Gets a reference to a specific person document within a team.
+     * 
+     * @param teamId - The unique identifier of the team
+     * @param id - The unique identifier of the person
+     * @returns A typed Firestore document reference for the person
+     * 
+     * @example
+     * ```typescript
+     * const personDoc = Firestore.shared.person(teamId, personId);
+     * const personData = await personDoc.get();
+     * ```
+     */
+    public person(teamId: Team.Id, id: Person.Id): FirestoreDocument<Person> {
+        return this.persons(teamId)
+            .document(id.guidString);
+    }
+
+    /**
+     * Gets a reference to the fine templates collection within a team.
+     * 
+     * @param teamId - The unique identifier of the team
+     * @returns A typed Firestore collection reference for fine templates in the team
+     * 
+     * @example
+     * ```typescript
+     * const templatesCollection = Firestore.shared.fineTemplates(teamId);
+     * const allTemplates = await templatesCollection.getAll();
+     * ```
+     */
+    public fineTemplates(teamId: Team.Id): FirestoreCollection<{ [x: string]: FirestoreDocument<FineTemplate, never>; }> {
+        return this.base
+            .collection('teams')
+            .document(teamId.guidString)
+            .collection('fineTemplates');
+    }
+
+    /**
+     * Gets a reference to a specific fine template document within a team.
+     * 
+     * @param teamId - The unique identifier of the team
+     * @param id - The unique identifier of the fine template
+     * @returns A typed Firestore document reference for the fine template
+     * 
+     * @example
+     * ```typescript
+     * const templateDoc = Firestore.shared.fineTemplate(teamId, templateId);
+     * const templateData = await templateDoc.get();
+     * ```
+     */
+    public fineTemplate(teamId: Team.Id, id: FineTemplate.Id): FirestoreDocument<FineTemplate> {
+        return this.fineTemplates(teamId)
+            .document(id.guidString);
+    }
+
+    /**
+     * Gets a reference to the fines collection within a team.
+     * 
+     * @param teamId - The unique identifier of the team
+     * @returns A typed Firestore collection reference for fines in the team
+     * 
+     * @example
+     * ```typescript
+     * const finesCollection = Firestore.shared.fines(teamId);
+     * const allFines = await finesCollection.getAll();
+     * ```
+     */
+    public fines(teamId: Team.Id): FirestoreCollection<{ [x: string]: FirestoreDocument<Fine, never>; }> {
+        return this.base
+            .collection('teams')
+            .document(teamId.guidString)
+            .collection('fines');
+    }
+
+    /**
+     * Gets a reference to a specific fine document within a team.
+     * 
+     * @param teamId - The unique identifier of the team
+     * @param id - The unique identifier of the fine
+     * @returns A typed Firestore document reference for the fine
+     * 
+     * @example
+     * ```typescript
+     * const fineDoc = Firestore.shared.fine(teamId, fineId);
+     * const fineData = await fineDoc.get();
+     * ```
+     */
+    public fine(teamId: Team.Id, id: Fine.Id): FirestoreDocument<Fine> {
+        return this.fines(teamId)
+            .document(id.guidString);
+    }
+}

package/src/{FirestoreScheme.ts → firebase/FirestoreScheme.ts}

@@ -1,6 +1,20 @@
 import { FirestoreCollection, FirestoreDocument } from '@stevenkellner/firebase-function';
-import { Fine, FineTemplate, Invitation, Person, Team, User } from './types';
+import { Fine, FineTemplate, Invitation, Person, Team, User } from '../types';
 
+/**
+ * Type definition for the Firestore database schema.
+ *
+ * Defines the hierarchical structure of the Firestore database:
+ * - **users**: Collection of user documents indexed by User.Id
+ * - **invitations**: Collection of invitation documents indexed by Invitation.Id
+ * - **teams**: Collection of team documents indexed by Team.Id, each containing:
+ *   - **persons**: Subcollection of person documents indexed by Person.Id
+ *   - **fineTemplates**: Subcollection of fine template documents indexed by FineTemplate.Id
+ *   - **fines**: Subcollection of fine documents indexed by Fine.Id
+ *
+ * This type ensures type-safe access to Firestore collections and documents
+ * throughout the application.
+ */
 export type FirestoreScheme = FirestoreDocument<never, {
     users: FirestoreCollection<{
         [UserId in string]: FirestoreDocument<User>

package/src/firebase/Messaging.ts

@@ -1,29 +1,93 @@
+/**
+ * Represents a notification payload for Firebase Cloud Messaging.
+ */
 export interface Notification {
+    /**
+     * The notification title.
+     */
     title?: string;
+    /**
+     * The notification body text.
+     */
     body?: string;
+    /**
+     * URL of an image to be displayed in the notification.
+     */
     imageUrl?: string;
 }
 
+/**
+ * Response from sending batch messages to multiple devices.
+ */
 export interface BatchResponse {
+    /**
+     * Array of individual message responses.
+     */
     responses: {
+        /**
+         * Whether the message was sent successfully.
+         */
         success: boolean;
+        /**
+         * The message ID if successful.
+         */
         messageId?: string;
+        /**
+         * Error information if the message failed to send.
+         */
         error?: {
+            /**
+             * Error code identifier.
+             */
             code: string;
+            /**
+             * Human-readable error message.
+             */
             message: string;
+            /**
+             * Optional stack trace for debugging.
+             */
             stack?: string;
+            /**
+             * Converts the error to a JSON object.
+             */
             toJSON(): object;
         };
     }[];
+    /**
+     * Number of messages sent successfully.
+     */
     successCount: number;
+    /**
+     * Number of messages that failed to send.
+     */
     failureCount: number;
 }
 
+/**
+ * Message to be sent to multiple device tokens.
+ */
 export interface MulticastMessage {
+    /**
+     * Array of device registration tokens to send the message to.
+     */
     tokens: string[];
+    /**
+     * Optional notification payload to include in the message.
+     */
     notification?: Notification;
 }
 
+/**
+ * Firebase Cloud Messaging service interface.
+ */
 export interface Messaging {
+    /**
+     * Sends a multicast message to multiple devices.
+     *
+     * @param message - The multicast message containing tokens and notification
+     * @param dryRun - If true, validates the message without actually sending it
+     * @returns Promise resolving to batch response with success/failure details
+     */
     sendEachForMulticast(message: MulticastMessage, dryRun?: boolean): Promise<BatchResponse>;
 }