@stevenkellner/team-conduct-api 1.0.36 → 2.0.1

package/src/types/PersonSignInProperties.ts

@@ -3,8 +3,21 @@ import { NotificationProperties } from './NotificationProperties';
 import { User } from './User';
 import { UserRole } from './UserRole';
 
+/**
+ * Represents the sign-in properties for a person in the system.
+ * 
+ * Contains authentication-related information including user ID, sign-in timestamp,
+ * notification preferences, and assigned user roles for access control.
+ */
 export class PersonSignInProperties implements Flattable<PersonSignInProperties.Flatten> {
 
+    /**
+     * Creates new person sign-in properties.
+     * @param userId - The unique identifier of the user associated with this person
+     * @param signInDate - The timestamp when the person signed in
+     * @param notificationProperties - Optional notification preferences (defaults to new NotificationProperties)
+     * @param roles - Optional array of user roles for access control (defaults to empty array)
+     */
     public constructor(
         public userId: User.Id,
         public signInDate: UtcDate,
@@ -12,6 +25,9 @@ export class PersonSignInProperties implements Flattable<PersonSignInProperties.
         public roles: UserRole[] = []
     ) {}
 
+    /**
+     * Gets the flattened representation of these sign-in properties for serialization.
+     */
     public get flatten(): PersonSignInProperties.Flatten {
         return {
             userId: this.userId.flatten,
@@ -24,6 +40,9 @@ export class PersonSignInProperties implements Flattable<PersonSignInProperties.
 
 export namespace PersonSignInProperties {
 
+    /**
+     * Flattened representation of person sign-in properties for serialization.
+     */
     export type Flatten = {
         userId: User.Id.Flatten
         signInDate: UtcDate.Flatten,
@@ -31,12 +50,23 @@ export namespace PersonSignInProperties {
         roles: UserRole[]
     }
 
+    /**
+     * Builder for constructing PersonSignInProperties from flattened data.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, PersonSignInProperties> {
 
+        /**
+         * Builds a PersonSignInProperties instance from flattened data.
+         * @param value - The flattened sign-in properties data
+         * @returns A new PersonSignInProperties instance
+         */
         public build(value: Flatten): PersonSignInProperties {
             return new PersonSignInProperties(User.Id.builder.build(value.userId), UtcDate.builder.build(value.signInDate), NotificationProperties.builder.build(value.notificationProperties), value.roles);
         }
     }
 
+    /**
+     * Singleton builder instance for PersonSignInProperties.
+     */
     export const builder = new TypeBuilder();
 }

package/src/types/Pluralization.ts

@@ -1,17 +1,50 @@
+/**
+ * Handles pluralization of strings based on count values.
+ * Supports different plural forms for various count categories (zero, one, two, few, many, other).
+ * This follows the Unicode CLDR plural rules for internationalization.
+ */
 export class Pluralization {
 
+    /**
+     * Plural form for count = 0 (optional).
+     */
     private readonly zero: string | null;
 
+    /**
+     * Plural form for count = 1 (optional).
+     */
     private readonly one: string | null;
 
+    /**
+     * Plural form for count = 2 (optional).
+     */
     private readonly two: string | null;
 
+    /**
+     * Plural form for count > 1 and < 5 (optional).
+     */
     private readonly few: string | null;
 
+    /**
+     * Plural form for count >= 5 and <= 20 (optional).
+     */
     private readonly many: string | null;
 
+    /**
+     * Default plural form used when no other category matches (required).
+     */
     private readonly other: string;
 
+    /**
+     * Creates a new Pluralization instance with specified plural forms.
+     * @param countLocals - Object containing plural forms for different count categories
+     * @param countLocals.zero - Optional form for zero items
+     * @param countLocals.one - Optional form for one item
+     * @param countLocals.two - Optional form for two items
+     * @param countLocals.few - Optional form for a few items (2-4)
+     * @param countLocals.many - Optional form for many items (5-20)
+     * @param countLocals.other - Required default form for all other counts
+     */
     public constructor(countLocals: {
         zero?: string,
         one?: string,
@@ -28,6 +61,19 @@ export class Pluralization {
         this.other = countLocals.other;
     }
 
+    /**
+     * Returns the appropriate plural form for the given count.
+     * Applies the following rules in order:
+     * - count = 0: returns 'zero' form if defined
+     * - count = 1: returns 'one' form if defined
+     * - count = 2: returns 'two' form if defined
+     * - 1 < count < 5: returns 'few' form if defined
+     * - 5 <= count <= 20: returns 'many' form if defined
+     * - Otherwise: returns 'other' form
+     *
+     * @param count - The number to determine the plural form for
+     * @returns The appropriate plural form string for the given count
+     */
     public get(count: number): string {
         if (count === 0 && this.zero)
             return this.zero;

package/src/types/Team.ts

@@ -1,13 +1,28 @@
 import { Flattable, Guid, ITypeBuilder, Tagged } from '@stevenkellner/typescript-common-functionality';
 
+/**
+ * Represents a team in the system with its basic information.
+ *
+ * A team is a group of people who can track fines and payments together.
+ * Teams can optionally have a PayPal.Me link for simplified payment collection.
+ */
 export class Team implements Flattable<Team.Flatten> {
 
+    /**
+     * Creates a new Team instance.
+     * @param id - The unique identifier for this team
+     * @param name - The display name of the team
+     * @param paypalMeLink - Optional PayPal.Me link for payment collection (null if not set)
+     */
     public constructor(
         public id: Team.Id,
         public name: string,
         public paypalMeLink: string | null
     ) {}
 
+    /**
+     * Gets the flattened representation of this team for serialization.
+     */
     public get flatten(): Team.Flatten {
         return {
             id: this.id.flatten,
@@ -19,23 +34,43 @@ export class Team implements Flattable<Team.Flatten> {
 
 export namespace Team {
 
+    /**
+     * Tagged type for team identifiers to prevent mixing with other GUID types.
+     */
     export type Id = Tagged<Guid, 'team'>;
 
     export namespace Id {
 
+        /**
+         * Flattened representation of a team ID (plain GUID string).
+         */
         export type Flatten = string;
 
+        /**
+         * Builder for constructing Team.Id instances from GUID strings.
+         */
         export const builder = Tagged.builder('team' as const, Guid.builder);
     }
 
+    /**
+     * Flattened representation of a Team for serialization.
+     */
     export type Flatten = {
         id: Id.Flatten,
         name: string,
         paypalMeLink: string | null
     }
 
+    /**
+     * Builder for constructing Team instances from flattened data.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, Team> {
 
+        /**
+         * Builds a Team instance from flattened data.
+         * @param value - The flattened team data
+         * @returns A new Team instance
+         */
         public build(value: Flatten): Team {
             return new Team(
                 Id.builder.build(value.id),
@@ -45,5 +80,8 @@ export namespace Team {
         }
     }
 
+    /**
+     * Singleton builder instance for Team.
+     */
     export const builder = new TypeBuilder();
 }

package/src/types/User.ts

@@ -2,13 +2,27 @@ import { Dictionary, Flattable, ITypeBuilder, Tagged, ValueTypeBuilder } from '@
 import { Team } from './Team';
 import { Person } from './Person';
 
+/**
+ * Represents a user in the system with associated team memberships.
+ *
+ * A user can be a member of multiple teams, and for each team, they have
+ * specific properties (team name and associated person ID).
+ */
 export class User implements Flattable<User.Flatten> {
 
+    /**
+     * Creates a new User instance.
+     * @param id - The unique identifier for this user
+     * @param teams - Dictionary mapping team IDs to team-specific user properties
+     */
     public constructor(
         public id: User.Id,
         public teams: Dictionary<Team.Id, User.TeamProperties> = new Dictionary(Team.Id.builder)
     ) {}
 
+    /**
+     * Gets the flattened representation of this user for serialization.
+     */
     public get flatten(): User.Flatten {
         return {
             id: this.id.flatten,
@@ -19,25 +33,48 @@ export class User implements Flattable<User.Flatten> {
 
 export namespace User {
 
+    /**
+     * Tagged type for user identifiers to prevent mixing with other string IDs.
+     */
     export type Id = Tagged<string, 'user'>;
 
     export namespace Id {
 
+        /**
+         * Flattened representation of a user ID (plain string).
+         */
         export type Flatten = string;
 
+        /**
+         * Builder for constructing User.Id instances from strings.
+         */
         export const builder = Tagged.builder('user' as const, new ValueTypeBuilder<string>());
     }
 
+    /**
+     * Properties that are specific to a user's membership in a particular team.
+     */
     export class TeamProperties implements Flattable<TeamProperties.Flatten> {
 
+        /**
+         * Creates new team-specific user properties.
+         * @param teamId - The ID of the team
+         * @param teamName - The display name of the team
+         * @param personId - The ID of the person associated with this user in this team
+         */
         public constructor(
-            public name: string,
+            public teamId: Team.Id,
+            public teamName: string,
             public personId: Person.Id
         ) {}
 
+        /**
+         * Gets the flattened representation of these team properties.
+         */
         public get flatten(): TeamProperties.Flatten {
             return {
-                name: this.name,
+                teamId: this.teamId.flatten,
+                teamName: this.teamName,
                 personId: this.personId.flatten
             };
         }
@@ -45,32 +82,61 @@ export namespace User {
 
     export namespace TeamProperties {
 
+        /**
+         * Flattened representation of team properties for serialization.
+         */
         export type Flatten = {
-            name: string,
+            teamId: Team.Id.Flatten,
+            teamName: string,
             personId: Person.Id.Flatten
         };
 
+        /**
+         * Builder for constructing TeamProperties from flattened data.
+         */
         export class TypeBuilder implements ITypeBuilder<Flatten, TeamProperties> {
 
+            /**
+             * Builds a TeamProperties instance from flattened data.
+             * @param value - The flattened team properties data
+             * @returns A new TeamProperties instance
+             */
             public build(value: Flatten): TeamProperties {
-                return new TeamProperties(value.name, Person.Id.builder.build(value.personId));
+                return new TeamProperties(Team.Id.builder.build(value.teamId), value.teamName, Person.Id.builder.build(value.personId));
             }
         }
 
+        /**
+         * Singleton builder instance for TeamProperties.
+         */
         export const builder = new TypeBuilder();
     }
 
+    /**
+     * Flattened representation of a User for serialization.
+     */
     export type Flatten = {
         id: Id.Flatten,
         teams: Dictionary.Flatten<TeamProperties>
     }
 
+    /**
+     * Builder for constructing User instances from flattened data.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, User> {
 
+        /**
+         * Builds a User instance from flattened data.
+         * @param value - The flattened user data
+         * @returns A new User instance with all teams reconstructed
+         */
         public build(value: Flatten): User {
             return new User(Id.builder.build(value.id), Dictionary.builder(Team.Id.builder, User.TeamProperties.builder).build(value.teams));
         }
     }
 
+    /**
+     * Singleton builder instance for User.
+     */
     export const builder = new TypeBuilder();
 }

package/src/types/UserRole.ts

@@ -1,24 +1,37 @@
 import { ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
 import { Localization, localizations } from './Localization';
+import { Locale } from './Locale';
 
-export type UserRole =
-    | 'person-manager'
-    | 'fineTemplate-manager'
-    | 'fine-manager'
-    | 'fine-can-add'
-    | 'team-manager';
+/**
+ * Array of all available user roles.
+ */
+const userRoles = [
+    'person-manager',       // Can manage persons, i.e. add/edit/remove persons of the team
+    'fineTemplate-manager', // Can manage fine templates, i.e. add/edit/remove fine templates
+    'fine-manager',         // Can manage fines, i.e. add/edit/remove fines
+    'fine-can-add',         // Can add fines, but not edit or remove them
+    'team-manager'          // Can manage team settings, i.e. invite/remove team members, change team name, etc.
+] as const;
 
-export namespace UserRole {
+/**
+ * Represents user roles in the application.
+ * Defines different levels of permissions for team members.
+ */
+export type UserRole = typeof userRoles[number];
 
-    export const all: UserRole[] = [
-        'person-manager',
-        'fineTemplate-manager',
-        'fine-manager',
-        'fine-can-add',
-        'team-manager'
-    ];
+export namespace UserRole {
+    /**
+     * Array of all available user roles.
+     */
+    export const all: readonly UserRole[] = userRoles;
 
-    export function formatted(role: UserRole): string {
+    /**
+     * Returns the localized, human-readable name for a user role.
+     * @param role - The user role to format
+     * @param locale - The locale to use for localization
+     * @returns The localized role name
+     */
+    export function formatted(role: UserRole, locale: Locale): string {
         const localizationKeyMap: Record<UserRole, keyof (typeof localizations)[keyof typeof localizations]['userRole']> = {
             'person-manager': 'personManager',
             'fineTemplate-manager': 'fineTemplateManager',
@@ -26,8 +39,11 @@ export namespace UserRole {
             'fine-can-add': 'fineCanAdd',
             'team-manager': 'teamManager'
         }
-        return Localization.shared.userRole[localizationKeyMap[role]].value();
+        return Localization.shared(locale).userRole[localizationKeyMap[role]].value();
     }
 
+    /**
+     * Builder for constructing UserRole values.
+     */
     export const builder = new ValueTypeBuilder<UserRole>();
 }

package/src/types/index.ts

@@ -15,3 +15,5 @@ export * from './Pluralization';
 export * from './Team';
 export * from './User';
 export * from './UserRole';
+export * from './Currency';
+export * from './Locale';

package/lib/src/Firestore.d.ts

@@ -1,24 +0,0 @@
-import { FirestoreCollection, FirestoreDocument } from '@stevenkellner/firebase-function';
-import { FirestoreScheme } from './FirestoreScheme';
-import { Fine, FineTemplate, Invitation, Person, User, Team } from './types';
-export declare class Firestore {
-    protected base: FirestoreScheme;
-    protected constructor();
-    private static sharedInstance;
-    static get shared(): Firestore;
-    team(id: Team.Id): FirestoreDocument<Team>;
-    user(id: User.Id): FirestoreDocument<User>;
-    invitation(id: Invitation.Id): FirestoreDocument<Invitation>;
-    persons(teamId: Team.Id): FirestoreCollection<{
-        [x: string]: FirestoreDocument<Person, never>;
-    }>;
-    person(teamId: Team.Id, id: Person.Id): FirestoreDocument<Person>;
-    fineTemplates(teamId: Team.Id): FirestoreCollection<{
-        [x: string]: FirestoreDocument<FineTemplate, never>;
-    }>;
-    fineTemplate(teamId: Team.Id, id: FineTemplate.Id): FirestoreDocument<FineTemplate>;
-    fines(teamId: Team.Id): FirestoreCollection<{
-        [x: string]: FirestoreDocument<Fine, never>;
-    }>;
-    fine(teamId: Team.Id, id: Fine.Id): FirestoreDocument<Fine>;
-}

package/lib/src/Firestore.js

@@ -1,62 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Firestore = void 0;
-const firebase_1 = require("./firebase");
-class Firestore {
-    base;
-    constructor() {
-        this.base = firebase_1.FirebaseConfiguration.shared.baseFirestoreDocument;
-    }
-    static sharedInstance = null;
-    static get shared() {
-        if (!Firestore.sharedInstance)
-            Firestore.sharedInstance = new Firestore();
-        return Firestore.sharedInstance;
-    }
-    team(id) {
-        return this.base
-            .collection('teams')
-            .document(id.guidString);
-    }
-    user(id) {
-        return this.base
-            .collection('users')
-            .document(id.value);
-    }
-    invitation(id) {
-        return this.base
-            .collection('invitations')
-            .document(id.value);
-    }
-    persons(teamId) {
-        return this.base
-            .collection('teams')
-            .document(teamId.guidString)
-            .collection('persons');
-    }
-    person(teamId, id) {
-        return this.persons(teamId)
-            .document(id.guidString);
-    }
-    fineTemplates(teamId) {
-        return this.base
-            .collection('teams')
-            .document(teamId.guidString)
-            .collection('fineTemplates');
-    }
-    fineTemplate(teamId, id) {
-        return this.fineTemplates(teamId)
-            .document(id.guidString);
-    }
-    fines(teamId) {
-        return this.base
-            .collection('teams')
-            .document(teamId.guidString)
-            .collection('fines');
-    }
-    fine(teamId, id) {
-        return this.fines(teamId)
-            .document(id.guidString);
-    }
-}
-exports.Firestore = Firestore;

package/lib/src/checkAuthentication.d.ts

@@ -1,6 +0,0 @@
-import { Team, User, UserRole } from './types';
-type ExpectedUserRoles = UserRole | ExpectedUserRoles[] | {
-    anyOf: ExpectedUserRoles[];
-};
-export declare function checkAuthentication(rawUserId: string | null, teamId: Team.Id, roles: ExpectedUserRoles): Promise<User.Id>;
-export {};

package/lib/src/firebaseFunctionsContext.d.ts

@@ -1,39 +0,0 @@
-import { TeamNewFunction, UserKickoutFunction, UserRoleEditFunction, PaypalMeEditFunction, NotificationRegisterFunction, NotificationSubscribeFunction, InvitationGetInvitationFunction, InvitationRegisterFunction, PersonAddFunction, PersonDeleteFunction, PersonUpdateFunction, FineTemplateAddFunction, FineTemplateDeleteFunction, FineTemplateUpdateFunction, FineAddFunction, FineDeleteFunction, FineUpdateFunction } from './functions';
-export declare const firebaseFunctionsContext: {
-    team: {
-        new: import("@stevenkellner/firebase-function").FirebaseFunctionContext<TeamNewFunction.Parameters, import("./types").User>;
-    };
-    user: {
-        kickout: import("@stevenkellner/firebase-function").FirebaseFunctionContext<UserKickoutFunction.Parameters, void>;
-        login: import("@stevenkellner/firebase-function").FirebaseFunctionContext<null, import("./types").User>;
-        roleEdit: import("@stevenkellner/firebase-function").FirebaseFunctionContext<UserRoleEditFunction.Parameters, void>;
-    };
-    paypalMe: {
-        edit: import("@stevenkellner/firebase-function").FirebaseFunctionContext<PaypalMeEditFunction.Parameters, void>;
-    };
-    notification: {
-        register: import("@stevenkellner/firebase-function").FirebaseFunctionContext<NotificationRegisterFunction.Parameters, void>;
-        subscribe: import("@stevenkellner/firebase-function").FirebaseFunctionContext<NotificationSubscribeFunction.Parameters, void>;
-    };
-    invitation: {
-        invite: import("@stevenkellner/firebase-function").FirebaseFunctionContext<import("./types").Invitation, import("./types").Invitation.Id>;
-        withdraw: import("@stevenkellner/firebase-function").FirebaseFunctionContext<import("./types").Invitation, void>;
-        getInvitation: import("@stevenkellner/firebase-function").FirebaseFunctionContext<import("./types").Invitation.Id, InvitationGetInvitationFunction.ReturnType>;
-        register: import("@stevenkellner/firebase-function").FirebaseFunctionContext<InvitationRegisterFunction.Parameters, import("./types").User>;
-    };
-    person: {
-        add: import("@stevenkellner/firebase-function").FirebaseFunctionContext<PersonAddFunction.Parameters, void>;
-        update: import("@stevenkellner/firebase-function").FirebaseFunctionContext<PersonUpdateFunction.Parameters, void>;
-        delete: import("@stevenkellner/firebase-function").FirebaseFunctionContext<PersonDeleteFunction.Parameters, void>;
-    };
-    fineTemplate: {
-        add: import("@stevenkellner/firebase-function").FirebaseFunctionContext<FineTemplateAddFunction.Parameters, void>;
-        update: import("@stevenkellner/firebase-function").FirebaseFunctionContext<FineTemplateUpdateFunction.Parameters, void>;
-        delete: import("@stevenkellner/firebase-function").FirebaseFunctionContext<FineTemplateDeleteFunction.Parameters, void>;
-    };
-    fine: {
-        add: import("@stevenkellner/firebase-function").FirebaseFunctionContext<FineAddFunction.Parameters, void>;
-        update: import("@stevenkellner/firebase-function").FirebaseFunctionContext<FineUpdateFunction.Parameters, void>;
-        delete: import("@stevenkellner/firebase-function").FirebaseFunctionContext<FineDeleteFunction.Parameters, void>;
-    };
-};

package/lib/src/firebaseFunctionsContext.js

@@ -1,43 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.firebaseFunctionsContext = void 0;
-const firebase_function_1 = require("@stevenkellner/firebase-function");
-const functions_1 = require("./functions");
-exports.firebaseFunctionsContext = firebase_function_1.FirebaseFunctionsContext.build(builder => ({
-    team: {
-        new: builder.function(functions_1.TeamNewFunction)
-    },
-    user: {
-        kickout: builder.function(functions_1.UserKickoutFunction),
-        login: builder.function(functions_1.UserLoginFunction),
-        roleEdit: builder.function(functions_1.UserRoleEditFunction)
-    },
-    paypalMe: {
-        edit: builder.function(functions_1.PaypalMeEditFunction)
-    },
-    notification: {
-        register: builder.function(functions_1.NotificationRegisterFunction),
-        subscribe: builder.function(functions_1.NotificationSubscribeFunction)
-    },
-    invitation: {
-        invite: builder.function(functions_1.InvitationInviteFunction),
-        withdraw: builder.function(functions_1.InvitationWithdrawFunction),
-        getInvitation: builder.function(functions_1.InvitationGetInvitationFunction),
-        register: builder.function(functions_1.InvitationRegisterFunction)
-    },
-    person: {
-        add: builder.function(functions_1.PersonAddFunction),
-        update: builder.function(functions_1.PersonUpdateFunction),
-        delete: builder.function(functions_1.PersonDeleteFunction)
-    },
-    fineTemplate: {
-        add: builder.function(functions_1.FineTemplateAddFunction),
-        update: builder.function(functions_1.FineTemplateUpdateFunction),
-        delete: builder.function(functions_1.FineTemplateDeleteFunction)
-    },
-    fine: {
-        add: builder.function(functions_1.FineAddFunction),
-        update: builder.function(functions_1.FineUpdateFunction),
-        delete: builder.function(functions_1.FineDeleteFunction)
-    }
-}));

package/lib/src/pushNotification.d.ts

@@ -1,3 +0,0 @@
-import { NotificationProperties, Person, Team } from './types';
-import { Notification } from './firebase';
-export declare function pushNotification(teamId: Team.Id, personId: Person.Id, topic: NotificationProperties.Subscription, notification: Notification): Promise<void>;

package/lib/src/pushNotification.js

@@ -1,35 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pushNotification = pushNotification;
-const typescript_common_functionality_1 = require("@stevenkellner/typescript-common-functionality");
-const Firestore_1 = require("./Firestore");
-const types_1 = require("./types");
-const firebase_1 = require("./firebase");
-function successfulTokens(response, tokens) {
-    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 typescript_common_functionality_1.Dictionary(types_1.NotificationProperties.TokenId.builder);
-    for (const token of successfulTokens)
-        tokenDict.set(types_1.NotificationProperties.TokenId.create(token), token);
-    return tokenDict;
-}
-async function pushNotification(teamId, personId, topic, notification) {
-    const personSnapshot = await Firestore_1.Firestore.shared.person(teamId, personId).snapshot();
-    if (!personSnapshot.exists)
-        return;
-    const person = types_1.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 firebase_1.FirebaseConfiguration.shared.messaging.sendEachForMulticast({
-        tokens: tokens,
-        notification: notification
-    });
-    person.signInProperties.notificationProperties.tokens = successfulTokens(response, tokens);
-    await Firestore_1.Firestore.shared.person(teamId, personId).set(person);
-}

package/lib/test/localization-utils.d.ts

@@ -1 +0,0 @@
-export declare function hasSameKeys(record1: Record<string, unknown>, record2: Record<string, unknown>): void;