@stevenkellner/team-conduct-api 2.0.17 → 2.0.19

package/src/firebase/FirebaseConfiguration.ts

@@ -1,99 +0,0 @@
-import { FirestoreScheme } from './FirestoreScheme';
-import { Messaging } from './Messaging';
-import { Firestore as FirebaseFirestore } from 'firebase-admin/firestore';
-
-/**
- * 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;
-
-    private _firebaseFirestore: FirebaseFirestore | null = null;
-
-    private _baseFirestoreDocument: FirestoreScheme | null = null;
-
-    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: {
-        firebaseFirestore: FirebaseFirestore,
-        baseFirestoreDocument: FirestoreScheme,
-        messaging: Messaging
-    }) {
-        if (this.configured)
-            throw new Error('Configuration is already configured');
-        this._firebaseFirestore = configuration.firebaseFirestore;
-        this._baseFirestoreDocument = configuration.baseFirestoreDocument;
-        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
-     */
-    public reconfigure(configuration: {
-        firebaseFirestore: FirebaseFirestore,
-        baseFirestoreDocument: FirestoreScheme,
-        messaging: Messaging
-    }) {
-        this.configured = false;
-        this.configure(configuration);
-    }
-
-    public get firebaseFirestore(): FirebaseFirestore {
-        if (!this.configured || !this._firebaseFirestore)
-            throw new Error('Configuration.firebaseFirestore is not configured');
-        return this._firebaseFirestore;
-    }
-
-    /**
-     * 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');
-        return this._messaging;
-    }
-}
-

package/src/firebase/Firestore.ts

@@ -1,258 +0,0 @@
-import { FirestoreBatch, FirestoreCollection, FirestoreDocument, UserAuthId } 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
-     */
-    protected get base(): FirestoreScheme {
-        return FirebaseConfiguration.shared.baseFirestoreDocument;
-    }
-
-    public batch(): FirestoreBatch {
-        return new FirestoreBatch(FirebaseConfiguration.shared.firebaseFirestore);
-    }
-
-    /**
-     * 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>;
-    }
-
-    public userAuth(userAuthId: UserAuthId): FirestoreDocument<{ userId: User.Id }> {
-        return this.base
-            .collection('userAuthIdDict')
-            .document(userAuthId.value);
-    }
-
-    /**
-     * 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/firebase/FirestoreScheme.ts

@@ -1,41 +0,0 @@
-import { FirestoreCollection, FirestoreDocument } from '@stevenkellner/firebase-function';
-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, {
-    userAuthIdDict: FirestoreCollection<{
-        [UserAuthId in string]: FirestoreDocument<{ userId: User.Id }>
-    }>,
-    users: FirestoreCollection<{
-        [UserId in string]: FirestoreDocument<User>
-    }>
-    invitations: FirestoreCollection<{
-        [InvitationId in string]: FirestoreDocument<Invitation>
-    }>
-    teams: FirestoreCollection<{
-        [TeamId in string]: FirestoreDocument<Team, {
-            persons: FirestoreCollection<{
-                [PersonId in string]: FirestoreDocument<Person>
-            }>
-            fineTemplates: FirestoreCollection<{
-                [PersonId in string]: FirestoreDocument<FineTemplate>
-            }>
-            fines: FirestoreCollection<{
-                [PersonId in string]: FirestoreDocument<Fine>
-            }>
-        }>
-    }>
-}>;

package/src/firebase/Messaging.ts

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

package/src/firebase/checkAuthentication.ts

@@ -1,91 +0,0 @@
-import { FunctionsError, UserAuthId } from '@stevenkellner/firebase-function';
-import { Person, Team, User, UserRole } from '../types';
-import { Firestore } from './Firestore';
-
-/**
- * Type representing expected user role requirements.
- *
- * Can be:
- * - A single `UserRole` (user must have this role)
- * - An array of `ExpectedUserRoles` (user must satisfy ALL requirements - logical AND)
- * - An object with `anyOf` property (user must satisfy AT LEAST ONE requirement - logical OR)
- *
- * Examples:
- * - `'admin'` - User must be admin
- * - `['member', 'treasurer']` - User must be both member AND treasurer
- * - `{ anyOf: ['admin', 'treasurer'] }` - User must be admin OR treasurer
- */
-type ExpectedUserRoles =
-    | UserRole
-    | ExpectedUserRoles[]
-    | {
-        anyOf: ExpectedUserRoles[];
-    }
-
-/**
- * Checks if the user has the required roles according to the expected role requirements.
- *
- * @param userRoles - Array of roles the user currently has
- * @param expectedRoles - The role requirements to check against (supports AND/OR logic)
- * @returns `true` if the user satisfies the role requirements, `false` otherwise
- */
-function hasUserRoles(userRoles: UserRole[], expectedRoles: ExpectedUserRoles): boolean {
-    if (Array.isArray(expectedRoles))
-        return expectedRoles.every(expectedRole => hasUserRoles(userRoles, expectedRole));
-    else if (typeof expectedRoles === 'object' && 'anyOf' in expectedRoles)
-        return expectedRoles.anyOf.some(role => hasUserRoles(userRoles, role));
-    else
-        return userRoles.includes(expectedRoles);
-
-}
-
-/**
- * Validates that a user is authenticated and has the required roles for a specific team.
- *
- * Performs comprehensive authentication checks:
- * 1. Verifies the user is authenticated (rawUserId is not null)
- * 2. Checks that the user exists in the database
- * 3. Confirms the user is a member of the specified team
- * 4. Validates that the person associated with the user exists
- * 5. Ensures the person is signed in (has signInProperties)
- * 6. Verifies the person has the required roles
- *
- * @param userAuthId - The raw user authentication ID string from authentication context (null if not authenticated)
- * @param teamId - The ID of the team to check membership and roles for
- * @param roles - The expected role requirements (supports AND/OR logic via ExpectedUserRoles)
- * @returns The validated User.Id if all checks pass
- * @throws {FunctionsError} 'unauthenticated' - If rawUserId is null
- * @throws {FunctionsError} 'permission-denied' - If any validation check fails
- */
-export async function checkAuthentication(userAuthId: UserAuthId | null, teamId: Team.Id, roles: ExpectedUserRoles): Promise<User.Id> {
-    if (userAuthId === null)
-        throw new FunctionsError('unauthenticated', 'User is not authenticated');
-
-    const userAuthSnapshot = await Firestore.shared.userAuth(userAuthId).snapshot();
-    if (!userAuthSnapshot.exists)
-        throw new FunctionsError('permission-denied', 'User authentication does not exist');
-    const userId = User.Id.builder.build(userAuthSnapshot.data.userId);
-
-    const userSnapshot = await Firestore.shared.user(userId).snapshot();
-    if (!userSnapshot.exists)
-        throw new FunctionsError('permission-denied', 'User does not exist');
-    const user = User.builder.build(userSnapshot.data);
-
-    if (!user.teams.has(teamId))
-        throw new FunctionsError('permission-denied', 'User is not a member of the team');
-    const team = user.teams.get(teamId);
-
-    const personSnapshot = await Firestore.shared.person(teamId, team.personId).snapshot();
-    if (!personSnapshot.exists)
-        throw new FunctionsError('permission-denied', 'Person does not exist');
-    const person = Person.builder.build(personSnapshot.data);
-
-    if (person.signInProperties === null)
-        throw new FunctionsError('permission-denied', 'Person is not signed in');
-
-    const userHasRoles = hasUserRoles(person.signInProperties.roles, roles);
-    if (!userHasRoles)
-        throw new FunctionsError('permission-denied', 'User does not have the required roles');
-
-    return userId;
-}

package/src/firebase/index.ts

@@ -1,7 +0,0 @@
-export * from './FirebaseConfiguration';
-export * from './Messaging';
-export * from './checkAuthentication';
-export * from './Firestore';
-export * from './FirestoreScheme';
-export * from './pushNotification';
-

package/src/firebase/pushNotification.ts

@@ -1,90 +0,0 @@
-import { Dictionary } from '@stevenkellner/typescript-common-functionality';
-import { Firestore } from './Firestore';
-import { NotificationProperties, Person, Team } from '../types';
-import { FirebaseConfiguration, BatchResponse, Notification } from '.';
-
-/**
- * Filters successful tokens from a Firebase Cloud Messaging batch response.
- *
- * Removes tokens that failed due to invalid or unregistered registration tokens,
- * keeping only the tokens that successfully received the notification.
- *
- * @param response - The batch response from Firebase Cloud Messaging
- * @param tokens - The array of device tokens that were sent the notification
- * @returns A dictionary mapping token IDs to their corresponding device tokens for successful deliveries
- *
- * @remarks
- * Filters out tokens with the following error codes:
- * - `messaging/invalid-registration-token`: The token format is invalid
- * - `messaging/registration-token-not-registered`: The token is no longer registered
- *
- * @private
- */
-function successfulTokens(response: BatchResponse, tokens: string[]): Dictionary<NotificationProperties.TokenId, string> {
-    const successfulTokens = response.responses
-        .map((response, index) => ({
-            failed: response.error?.code ==='messaging/invalid-registration-token' || response.error?.code === 'messaging/registration-token-not-registered',
-            token: tokens[index]
-        }))
-        .filter(response => !response.failed)
-        .map(response => response.token);
-    const tokenDict = new Dictionary<NotificationProperties.TokenId, string>(NotificationProperties.TokenId.builder);
-    for (const token of successfulTokens)
-        tokenDict.set(NotificationProperties.TokenId.create(token), token);
-    return tokenDict;
-}
-
-/**
- * Sends a push notification to a person if they are subscribed to the topic.
- *
- * Retrieves the person's notification properties, checks their subscription status,
- * sends the notification to all their registered device tokens, and updates their
- * token list to remove any failed tokens.
- *
- * @param teamId - The unique identifier of the team
- * @param personId - The unique identifier of the person
- * @param topic - The notification subscription topic (e.g., 'new-fine', 'fine-reminder', 'fine-state-change')
- * @param notification - The notification content to send
- *
- * @returns A promise that resolves when the notification is sent and person data is updated
- *
- * @remarks
- * The function will silently return without sending if:
- * - The person does not exist in the database
- * - The person is not signed in (signInProperties is null)
- * - The person is not subscribed to the specified topic
- *
- * After sending, the person's token list is automatically updated to remove
- * any tokens that are invalid or unregistered, maintaining clean notification data.
- *
- * @example
- * ```typescript
- * await pushNotification(
- *   teamId,
- *   personId,
- *   'new-fine',
- *   {
- *     title: 'New Fine',
- *     body: 'You have received a new fine'
- *   }
- * );
- * ```
- */
-export async function pushNotification(teamId: Team.Id, personId: Person.Id, topic: NotificationProperties.Subscription, notification: Notification): Promise<void> {
-
-    const personSnapshot = await Firestore.shared.person(teamId, personId).snapshot();
-    if (!personSnapshot.exists)
-        return;
-    const person = Person.builder.build(personSnapshot.data);
-
-    if (person.signInProperties === null || !person.signInProperties.notificationProperties.subscriptions.includes(topic))
-        return;
-
-    const tokens = person.signInProperties.notificationProperties.tokens.values;
-    const response = await FirebaseConfiguration.shared.messaging.sendEachForMulticast({
-        tokens: tokens,
-        notification: notification
-    });
-    person.signInProperties.notificationProperties.tokens = successfulTokens(response, tokens);
-    await Firestore.shared.person(teamId, personId).set(person);
-}