@stevenkellner/team-conduct-api 1.0.36 → 2.0.1

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

@@ -1,7 +1,20 @@
 import { FunctionsError } from '@stevenkellner/firebase-function';
-import { Person, Team, User, UserRole } from './types';
+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[]
@@ -9,6 +22,13 @@ type 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));
@@ -19,6 +39,24 @@ function hasUserRoles(userRoles: UserRole[], expectedRoles: ExpectedUserRoles):
 
 }
 
+/**
+ * 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 rawUserId - The raw user 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(rawUserId: string | null, teamId: Team.Id, roles: ExpectedUserRoles): Promise<User.Id> {
     if (rawUserId === null)
         throw new FunctionsError('unauthenticated', 'User is not authenticated');

package/src/firebase/index.ts

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

package/src/firebase/pushNotification.ts

@@ -0,0 +1,90 @@
+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);
+}

package/src/functions/fine/add.ts

@@ -1,24 +1,17 @@
-import { FirebaseFunction, FunctionsError } from '@stevenkellner/firebase-function';
+import { FirebaseFunction } from '@stevenkellner/firebase-function';
 import { Flattable, ObjectTypeBuilder, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
-import { Configuration, Fine, Localization, Person, Team } from '../../types';
-import { checkAuthentication } from '../../checkAuthentication';
-import { Firestore } from '../../Firestore';
-import { pushNotification } from '../../pushNotification';
+import { Configuration, Fine, Person, Team } from '../../types';
 
+export type FineAddFunctionParameters = {
+    teamId: Team.Id,
+    personId: Person.Id,
+    fine: Fine,
+    configuration: Configuration
+};
 
-export namespace FineAddFunction {
+export abstract class FineAddFunctionBase extends FirebaseFunction<FineAddFunctionParameters, void> {
 
-    export type Parameters = {
-        teamId: Team.Id,
-        personId: Person.Id,
-        fine: Fine,
-        configuration: Configuration
-    };
-}
-
-export class FineAddFunction extends FirebaseFunction<FineAddFunction.Parameters, void> {
-
-    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineAddFunction.Parameters>, FineAddFunction.Parameters>({
+    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineAddFunctionParameters>, FineAddFunctionParameters>({
         teamId: Team.Id.builder,
         personId: Person.Id.builder,
         fine: Fine.builder,
@@ -26,35 +19,4 @@ export class FineAddFunction extends FirebaseFunction<FineAddFunction.Parameters
     });
 
     public returnTypeBuilder = new ValueTypeBuilder<void>();
-
-    public async execute(parameters: FineAddFunction.Parameters): Promise<void> {
-
-        await checkAuthentication(this.userId, parameters.teamId, {
-            anyOf: ['fine-manager', 'fine-can-add']
-        });
-
-        const fineSnapshot = await Firestore.shared.fine(parameters.teamId, parameters.fine.id).snapshot();
-        if (fineSnapshot.exists)
-            throw new FunctionsError('already-exists', 'Fine already exists');
-
-        const personSnapshot = await Firestore.shared.person(parameters.teamId, parameters.personId).snapshot();
-        if (!personSnapshot.exists)
-            throw new FunctionsError('not-found', 'Person not found');
-        const person = Person.builder.build(personSnapshot.data);
-
-        await Firestore.shared.fine(parameters.teamId, parameters.fine.id).set(parameters.fine);
-
-        person.fineIds.push(parameters.fine.id);
-        await Firestore.shared.person(parameters.teamId, parameters.personId).set(person);
-
-        Localization.locale = parameters.configuration.locale;
-        await pushNotification(parameters.teamId, parameters.personId, 'new-fine', {
-            title: Localization.shared.notification.fine.new.title.value({
-                reason: parameters.fine.reason
-            }),
-            body: Localization.shared.notification.fine.new.body.value({
-                amount: parameters.fine.amount.formatted(parameters.configuration)
-            })
-        });
-    }
 }

package/src/functions/fine/delete.ts

@@ -1,23 +1,17 @@
-import { FirebaseFunction, FunctionsError } from '@stevenkellner/firebase-function';
-import { Configuration, Fine, FineAmount, Localization, Person, Team } from '../../types';
+import { FirebaseFunction } from '@stevenkellner/firebase-function';
+import { Configuration, Fine, Person, Team } from '../../types';
 import { Flattable, ObjectTypeBuilder, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
-import { checkAuthentication } from '../../checkAuthentication';
-import { Firestore } from '../../Firestore';
-import { pushNotification } from '../../pushNotification';
 
-export namespace FineDeleteFunction {
-
-    export type Parameters = {
-        teamId: Team.Id,
-        personId: Person.Id,
-        id: Fine.Id,
-        configuration: Configuration
-    }
+export type FineDeleteFunctionParameters = {
+    teamId: Team.Id,
+    personId: Person.Id,
+    id: Fine.Id,
+    configuration: Configuration
 }
 
-export class FineDeleteFunction extends FirebaseFunction<FineDeleteFunction.Parameters, void> {
+export abstract class FineDeleteFunctionBase extends FirebaseFunction<FineDeleteFunctionParameters, void> {
 
-    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineDeleteFunction.Parameters>, FineDeleteFunction.Parameters>({
+    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineDeleteFunctionParameters>, FineDeleteFunctionParameters>({
         teamId: Team.Id.builder,
         personId: Person.Id.builder,
         id: Fine.Id.builder,
@@ -25,32 +19,4 @@ export class FineDeleteFunction extends FirebaseFunction<FineDeleteFunction.Para
     });
 
     public returnTypeBuilder = new ValueTypeBuilder<void>();
-
-    public async execute(parameters: FineDeleteFunction.Parameters): Promise<void> {
-
-        await checkAuthentication(this.userId, parameters.teamId, 'fine-manager');
-
-        const fineSnapshot = await Firestore.shared.fine(parameters.teamId, parameters.id).snapshot();
-        if (!fineSnapshot.exists)
-            throw new FunctionsError('not-found', 'Fine not found');
-
-        const personSnapshot = await Firestore.shared.person(parameters.teamId, parameters.personId).snapshot();
-        if (!personSnapshot.exists)
-            throw new FunctionsError('not-found', 'Person not found');
-        const person = Person.builder.build(personSnapshot.data);
-
-        await Firestore.shared.fine(parameters.teamId, parameters.id).remove();
-
-        person.fineIds = person.fineIds.filter(id => id.guidString !== parameters.id.guidString);
-        await Firestore.shared.person(parameters.teamId, parameters.personId).set(person);
-
-        Localization.locale = parameters.configuration.locale;
-        await pushNotification(parameters.teamId, parameters.personId, 'fine-state-change', {
-            title: Localization.shared.notification.fine.stateChange.title.value(),
-            body: Localization.shared.notification.fine.stateChange.bodyDeleted.value({
-                amount: FineAmount.builder.build(fineSnapshot.data.amount).formatted(parameters.configuration),
-                reason: fineSnapshot.data.reason
-            })
-        });
-    }
 }

package/src/functions/fine/update.ts

@@ -1,24 +1,18 @@
 import { Configuration } from '../../types/Configuration';
-import { FirebaseFunction, FunctionsError } from '@stevenkellner/firebase-function';
-import { pushNotification } from '../../pushNotification';
-import { Fine, Localization, Person, Team, ValueLocalization } from '../../types';
+import { FirebaseFunction } from '@stevenkellner/firebase-function';
+import { Fine, Person, Team } from '../../types';
 import { Flattable, ObjectTypeBuilder, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
-import { checkAuthentication } from '../../checkAuthentication';
-import { Firestore } from '../../Firestore';
 
-export namespace FineUpdateFunction {
+export type FineUpdateFunctionParameters = {
+    teamId: Team.Id,
+    personId: Person.Id,
+    fine: Fine,
+    configuration: Configuration
+};
 
-    export type Parameters = {
-        teamId: Team.Id,
-        personId: Person.Id,
-        fine: Fine,
-        configuration: Configuration
-    };
-}
-
-export class FineUpdateFunction extends FirebaseFunction<FineUpdateFunction.Parameters, void> {
+export abstract class FineUpdateFunctionBase extends FirebaseFunction<FineUpdateFunctionParameters, void> {
 
-    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineUpdateFunction.Parameters>, FineUpdateFunction.Parameters>({
+    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineUpdateFunctionParameters>, FineUpdateFunctionParameters>({
         teamId: Team.Id.builder,
         personId: Person.Id.builder,
         fine: Fine.builder,
@@ -26,32 +20,4 @@ export class FineUpdateFunction extends FirebaseFunction<FineUpdateFunction.Para
     });
 
     public returnTypeBuilder = new ValueTypeBuilder<void>();
-
-    public async execute(parameters: FineUpdateFunction.Parameters): Promise<void> {
-
-        await checkAuthentication(this.userId, parameters.teamId, 'fine-manager');
-
-        const fineSnapshot = await Firestore.shared.fine(parameters.teamId, parameters.fine.id).snapshot();
-        if (!fineSnapshot.exists)
-            throw new FunctionsError('not-found', 'Fine not found');
-
-        await Firestore.shared.fine(parameters.teamId, parameters.fine.id).set(parameters.fine);
-
-        Localization.locale = parameters.configuration.locale;
-        if (parameters.fine.payedState !== fineSnapshot.data.payedState) {
-            let bodyLocalization: ValueLocalization;
-            if (parameters.fine.payedState === 'payed')
-                bodyLocalization = Localization.shared.notification.fine.stateChange.bodyPayed;
-            else
-                bodyLocalization = Localization.shared.notification.fine.stateChange.bodyUnpayed;
-            await pushNotification(parameters.teamId, parameters.personId, 'fine-state-change', {
-                title: Localization.shared.notification.fine.stateChange.title.value(),
-                body: bodyLocalization.value({
-                    reason: parameters.fine.reason,
-                    amount: parameters.fine.amount.formatted(parameters.configuration)
-                })
-            });
-
-        }
-    }
 }

package/src/functions/fineTemplate/add.ts

@@ -1,34 +1,18 @@
-import { FirebaseFunction, FunctionsError } from '@stevenkellner/firebase-function';
+import { FirebaseFunction } from '@stevenkellner/firebase-function';
 import { FineTemplate, Team } from '../../types';
 import { Flattable, ObjectTypeBuilder, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
-import { checkAuthentication } from '../../checkAuthentication';
-import { Firestore } from '../../Firestore';
 
-export namespace FineTemplateAddFunction {
+export type FineTemplateAddFunctionParameters = {
+    teamId: Team.Id,
+    fineTemplate: FineTemplate
+};
 
-    export type Parameters = {
-        teamId: Team.Id,
-        fineTemplate: FineTemplate
-    }
-}
-
-export class FineTemplateAddFunction extends FirebaseFunction<FineTemplateAddFunction.Parameters, void> {
+export abstract class FineTemplateAddFunctionBase extends FirebaseFunction<FineTemplateAddFunctionParameters, void> {
 
-    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineTemplateAddFunction.Parameters>, FineTemplateAddFunction.Parameters>({
+    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineTemplateAddFunctionParameters>, FineTemplateAddFunctionParameters>({
         teamId: Team.Id.builder,
         fineTemplate: FineTemplate.builder
     });
 
     public returnTypeBuilder = new ValueTypeBuilder<void>();
-
-    public async execute(parameters: FineTemplateAddFunction.Parameters): Promise<void> {
-
-        await checkAuthentication(this.userId, parameters.teamId, 'fineTemplate-manager');
-
-        const fineTemplateSnapshot = await Firestore.shared.fineTemplate(parameters.teamId, parameters.fineTemplate.id).snapshot();
-        if (fineTemplateSnapshot.exists)
-            throw new FunctionsError('already-exists', 'FineTemplate already exists');
-
-        await Firestore.shared.fineTemplate(parameters.teamId, parameters.fineTemplate.id).set(parameters.fineTemplate);
-    }
 }

package/src/functions/fineTemplate/delete.ts

@@ -1,34 +1,18 @@
-import { FirebaseFunction, FunctionsError } from '@stevenkellner/firebase-function';
+import { FirebaseFunction } from '@stevenkellner/firebase-function';
 import { FineTemplate, Team } from '../../types';
 import { Flattable, ObjectTypeBuilder, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
-import { checkAuthentication } from '../../checkAuthentication';
-import { Firestore } from '../../Firestore';
 
-export namespace FineTemplateDeleteFunction {
+export type FineTemplateDeleteFunctionParameters = {
+    teamId: Team.Id,
+    id: FineTemplate.Id
+};
 
-    export type Parameters = {
-        teamId: Team.Id,
-        id: FineTemplate.Id
-    }
-}
-
-export class FineTemplateDeleteFunction extends FirebaseFunction<FineTemplateDeleteFunction.Parameters, void> {
+export abstract class FineTemplateDeleteFunctionBase extends FirebaseFunction<FineTemplateDeleteFunctionParameters, void> {
 
-    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineTemplateDeleteFunction.Parameters>, FineTemplateDeleteFunction.Parameters>({
+    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineTemplateDeleteFunctionParameters>, FineTemplateDeleteFunctionParameters>({
         teamId: Team.Id.builder,
         id: FineTemplate.Id.builder
     });
 
     public returnTypeBuilder = new ValueTypeBuilder<void>();
-
-    public async execute(parameters: FineTemplateDeleteFunction.Parameters): Promise<void> {
-
-        await checkAuthentication(this.userId, parameters.teamId, 'fineTemplate-manager');
-
-        const fineTemplateSnapshot = await Firestore.shared.fineTemplate(parameters.teamId, parameters.id).snapshot();
-        if (!fineTemplateSnapshot.exists)
-            throw new FunctionsError('not-found', 'FineTemplate not found');
-
-        await Firestore.shared.fineTemplate(parameters.teamId, parameters.id).remove();
-    }
 }

package/src/functions/fineTemplate/update.ts

@@ -1,34 +1,17 @@
-import { FirebaseFunction, FunctionsError } from '@stevenkellner/firebase-function';
+import { FirebaseFunction } from '@stevenkellner/firebase-function';
 import { FineTemplate, Team } from '../../types';
 import { Flattable, ObjectTypeBuilder, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
-import { checkAuthentication } from '../../checkAuthentication';
-import { Firestore } from '../../Firestore';
 
-export namespace FineTemplateUpdateFunction {
+export type FineTemplateUpdateFunctionParameters = {
+    teamId: Team.Id,
+    fineTemplate: FineTemplate
+};
+export abstract class FineTemplateUpdateFunctionBase extends FirebaseFunction<FineTemplateUpdateFunctionParameters, void> {
 
-    export type Parameters = {
-        teamId: Team.Id,
-        fineTemplate: FineTemplate
-    };
-}
-
-export class FineTemplateUpdateFunction extends FirebaseFunction<FineTemplateUpdateFunction.Parameters, void> {
-
-    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineTemplateUpdateFunction.Parameters>, FineTemplateUpdateFunction.Parameters>({
+    public parametersBuilder = new ObjectTypeBuilder<Flattable.Flatten<FineTemplateUpdateFunctionParameters>, FineTemplateUpdateFunctionParameters>({
         teamId: Team.Id.builder,
         fineTemplate: FineTemplate.builder
     });
 
     public returnTypeBuilder = new ValueTypeBuilder<void>();
-
-    public async execute(parameters: FineTemplateUpdateFunction.Parameters): Promise<void> {
-
-        await checkAuthentication(this.userId, parameters.teamId, 'fineTemplate-manager');
-
-        const fineTemplateSnapshot = await Firestore.shared.fineTemplate(parameters.teamId, parameters.fineTemplate.id).snapshot();
-        if (!fineTemplateSnapshot.exists)
-            throw new FunctionsError('not-found', 'FineTemplate not found');
-
-        await Firestore.shared.fineTemplate(parameters.teamId, parameters.fineTemplate.id).set(parameters.fineTemplate);
-    }
 }

package/src/functions/index.ts

@@ -1,4 +1,3 @@
-
 export * from './team/new';
 export * from './user/login';
 export * from './user/roleEdit';