@stevenkellner/team-conduct-api 1.0.35 → 2.0.1

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

@@ -1,15 +1,59 @@
-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 declare class FirebaseConfiguration {
+    /**
+     * Singleton instance of FirebaseConfiguration.
+     */
     static readonly shared: FirebaseConfiguration;
     private configured;
     private _baseFirestoreDocument;
     private _messaging;
+    /**
+     * 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
+     */
     configure(configuration: {
         baseFirestoreDocument: FirestoreScheme;
         messaging: Messaging;
     }): void;
+    /**
+     * Reconfigures the Firebase services.
+     *
+     * Allows updating the configuration with new services.
+     *
+     * @param configuration - New configuration object containing Firestore and Messaging services
+     */
+    reconfigure(configuration: {
+        baseFirestoreDocument: FirestoreScheme;
+        messaging: Messaging;
+    }): void;
+    /**
+     * Gets the base Firestore document reference.
+     *
+     * @returns The configured Firestore document scheme
+     * @throws Error if not yet configured
+     */
     get baseFirestoreDocument(): FirestoreScheme;
+    /**
+     * Gets the Firebase Cloud Messaging service.
+     *
+     * @returns The configured Messaging service
+     * @throws Error if not yet configured
+     */
     get messaging(): Messaging;
 }

package/lib/src/firebase/FirebaseConfiguration.js

@@ -1,12 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FirebaseConfiguration = void 0;
+/**
+ * Singleton configuration manager for Firebase services.
+ *
+ * Provides centralized access to Firestore document reference and Firebase Cloud Messaging.
+ * Must be configured once before accessing services.
+ */
 class FirebaseConfiguration {
+    /**
+     * Singleton instance of FirebaseConfiguration.
+     */
     static shared = new FirebaseConfiguration();
     configured = false;
     _baseFirestoreDocument = null;
     _messaging = null;
+    /**
+     * Private constructor to enforce singleton pattern.
+     */
     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
+     */
     configure(configuration) {
         if (this.configured)
             throw new Error('Configuration is already configured');
@@ -14,11 +35,34 @@ class FirebaseConfiguration {
         this._messaging = configuration.messaging;
         this.configured = true;
     }
+    /**
+     * Reconfigures the Firebase services.
+     *
+     * Allows updating the configuration with new services.
+     *
+     * @param configuration - New configuration object containing Firestore and Messaging services
+     */
+    reconfigure(configuration) {
+        this.configured = false;
+        this.configure(configuration);
+    }
+    /**
+     * Gets the base Firestore document reference.
+     *
+     * @returns The configured Firestore document scheme
+     * @throws Error if not yet configured
+     */
     get baseFirestoreDocument() {
         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
+     */
     get messaging() {
         if (!this.configured || !this._messaging)
             throw new Error('Configuration.messaging is not configured');

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

@@ -0,0 +1,196 @@
+import { FirestoreCollection, FirestoreDocument } from '@stevenkellner/firebase-function';
+import { Fine, FineTemplate, Invitation, Person, User, Team } from '../types';
+/**
+ * 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 declare 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;
+    /**
+     * 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);
+     * ```
+     */
+    static get shared(): Firestore;
+    /**
+     * 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();
+    /**
+     * 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();
+     * ```
+     */
+    team(id: Team.Id): 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();
+     * ```
+     */
+    user(id: User.Id): FirestoreDocument<User>;
+    /**
+     * 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();
+     * ```
+     */
+    invitation(id: Invitation.Id): FirestoreDocument<Invitation>;
+    /**
+     * 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();
+     * ```
+     */
+    persons(teamId: Team.Id): FirestoreCollection<{
+        [x: string]: FirestoreDocument<Person, never>;
+    }>;
+    /**
+     * 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();
+     * ```
+     */
+    person(teamId: Team.Id, id: Person.Id): FirestoreDocument<Person>;
+    /**
+     * 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();
+     * ```
+     */
+    fineTemplates(teamId: Team.Id): FirestoreCollection<{
+        [x: string]: FirestoreDocument<FineTemplate, never>;
+    }>;
+    /**
+     * 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();
+     * ```
+     */
+    fineTemplate(teamId: Team.Id, id: FineTemplate.Id): FirestoreDocument<FineTemplate>;
+    /**
+     * 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();
+     * ```
+     */
+    fines(teamId: Team.Id): FirestoreCollection<{
+        [x: string]: FirestoreDocument<Fine, never>;
+    }>;
+    /**
+     * 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();
+     * ```
+     */
+    fine(teamId: Team.Id, id: Fine.Id): FirestoreDocument<Fine>;
+}

package/lib/src/firebase/Firestore.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Firestore = void 0;
+const _1 = require(".");
+/**
+ * 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.
+ */
+class Firestore {
+    /**
+     * Protected constructor to enforce singleton pattern.
+     * Use {@link Firestore.shared} to get an instance.
+     */
+    constructor() { }
+    /**
+     * The singleton instance of the Firestore accessor.
+     *
+     * @private
+     */
+    static sharedInstance = 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);
+     * ```
+     */
+    static get shared() {
+        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
+     */
+    get base() {
+        return _1.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();
+     * ```
+     */
+    team(id) {
+        return this.base
+            .collection('teams')
+            .document(id.guidString);
+    }
+    /**
+     * 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();
+     * ```
+     */
+    user(id) {
+        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();
+     * ```
+     */
+    invitation(id) {
+        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();
+     * ```
+     */
+    persons(teamId) {
+        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();
+     * ```
+     */
+    person(teamId, id) {
+        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();
+     * ```
+     */
+    fineTemplates(teamId) {
+        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();
+     * ```
+     */
+    fineTemplate(teamId, id) {
+        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();
+     * ```
+     */
+    fines(teamId) {
+        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();
+     * ```
+     */
+    fine(teamId, id) {
+        return this.fines(teamId)
+            .document(id.guidString);
+    }
+}
+exports.Firestore = Firestore;

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

@@ -1,5 +1,19 @@
 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/lib/src/firebase/Messaging.d.ts

@@ -1,26 +1,90 @@
+/**
+ * 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>;
 }