@stevenkellner/team-conduct-api 2.0.18 → 2.0.20

package/src/types/fine/FineTemplate.ts

@@ -0,0 +1,219 @@
+import { Flattable, Guid, ITypeBuilder, Tagged, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
+import { Fine } from './Fine';
+import { Localization } from '../localization/Localization';
+import { Locale } from '../localization/Locale';
+
+/**
+ * Represents a template for creating fines with predefined reason, amount, and optional repetition rules.
+ *
+ * Fine templates allow teams to quickly create recurring or standard fines without entering
+ * the same information repeatedly.
+ */
+export class FineTemplate implements Flattable<FineTemplate.Flatten> {
+
+    /**
+     * Creates a new FineTemplate instance.
+     *
+     * @param id - Unique identifier for the fine template (GUID)
+     * @param reason - The reason or description for the fine
+     * @param amount - The monetary or item-based amount of the fine
+     * @param repetition - Optional repetition rules (null for non-recurring templates)
+     */
+    public constructor(
+        public id: FineTemplate.Id,
+        public reason: string,
+        public amount: Fine.Amount,
+        public repetition: FineTemplate.Repetition | null
+    ) {}
+
+    /**
+     * Returns the flattened representation for serialization.
+     */
+    public get flatten(): FineTemplate.Flatten {
+        return {
+            id: this.id.flatten,
+            reason: this.reason,
+            amount: this.amount.flatten,
+            repetition: this.repetition === null ? null : this.repetition.flatten
+        };
+    }
+}
+
+export namespace FineTemplate {
+
+    /**
+     * Tagged GUID type for fine template identifiers.
+     */
+    export type Id = Tagged<Guid, 'fineTemplate'>;
+
+    export namespace Id {
+
+        /**
+         * Flattened representation of a fine template ID (GUID string).
+         */
+        export type Flatten = string;
+
+        /**
+         * Type builder for FineTemplate.Id serialization/deserialization.
+         */
+        export const builder = Tagged.builder('fineTemplate' as const, Guid.builder);
+    }
+
+    /**
+     * Represents how a fine template repeats over time.
+     *
+     * Defines the repetition unit (minute, day, item, count) and optional maximum count for repetitions.
+     */
+    export class Repetition implements Flattable<Repetition.Flatten> {
+
+        /**
+         * Creates a new Repetition instance.
+         *
+         * @param item - The repetition unit type (minute, day, item, count)
+         * @param maxCount - Optional maximum number of repetitions (null for unlimited)
+         */
+        public constructor(
+            public item: Repetition.Item,
+            public maxCount: number | null
+        ) {}
+
+        /**
+         * Returns a localized formatted string including the count value.
+         *
+         * @param count - The number of repetitions
+         * @param locale - The locale to use for formatting
+         * @returns Formatted string (e.g., "every 5 minutes")
+         */
+        public formatted(count: number, locale: Locale): string {
+            return Localization.shared(locale).fineTemplateRepetition.item[this.item].withCount.value(count);
+        }
+
+        /**
+         * Returns a localized formatted string without explicitly showing the count.
+         *
+         * @param count - The number of repetitions
+         * @param locale - The locale to use for formatting
+         * @returns Formatted string without count display
+         */
+        public formattedWithoutCount(count: number, locale: Locale): string {
+            return Localization.shared(locale).fineTemplateRepetition.item[this.item].withoutCount.value(count);
+        }
+
+        /**
+         * Returns the flattened representation for serialization.
+         */
+        public get flatten(): Repetition.Flatten {
+            return {
+                item: this.item,
+                maxCount: this.maxCount
+            };
+        }
+    }
+
+    export namespace Repetition {
+
+        const repetitionItems = [
+            'minute',
+            'day',
+            'item',
+            'count'
+        ] as const;
+
+        /**
+         * Repetition unit type: 'minute', 'day', 'item', or 'count'.
+         */
+        export type Item = typeof repetitionItems[number];
+
+        export namespace Item {
+
+            /**
+             * Array containing all possible repetition item types.
+             */
+            export const all: readonly Item[] = repetitionItems;
+
+            /**
+             * Returns the localized name for a repetition item type.
+             *
+             * @param item - The repetition item type
+             * @param locale - The locale to use for formatting
+             * @returns Localized name string
+             */
+            export function formatted(item: Item, locale: Locale): string {
+                return Localization.shared(locale).fineTemplateRepetition.item[item].name.value();
+            }
+
+            /**
+             * Type builder for Item serialization/deserialization.
+             */
+            export const builder = new ValueTypeBuilder<Item>();
+        }
+
+        /**
+         * Flattened representation of Repetition for serialization.
+         */
+        export type Flatten = {
+            item: Item,
+            maxCount: number | null
+        }
+
+        /**
+         * Type builder for Repetition serialization/deserialization.
+         */
+        export class TypeBuilder implements ITypeBuilder<Flatten, Repetition> {
+
+            /**
+             * Builds a Repetition instance from flattened data.
+             *
+             * @param flatten - Flattened repetition data
+             * @returns Repetition instance
+             */
+            public build(flatten: Flatten): Repetition {
+                return new Repetition(
+                    flatten.item,
+                    flatten.maxCount
+                );
+            }
+        }
+
+        /**
+         * Singleton instance of TypeBuilder for Repetition.
+         */
+        export const builder = new TypeBuilder();
+    }
+
+    /**
+     * Flattened representation of a FineTemplate for serialization.
+     */
+    export type Flatten = {
+        id: Id.Flatten,
+        reason: string,
+        amount: Fine.Amount.Flatten,
+        repetition: Repetition.Flatten | null
+    };
+
+    /**
+     * Type builder for FineTemplate serialization/deserialization.
+     */
+    export class TypeBuilder implements ITypeBuilder<Flatten, FineTemplate> {
+
+        /**
+         * Builds a FineTemplate instance from flattened data.
+         *
+         * @param value - Flattened fine template data
+         * @returns FineTemplate instance
+         */
+        public build(value: Flatten): FineTemplate {
+            return new FineTemplate(
+                Id.builder.build(value.id),
+                value.reason,
+                Fine.Amount.builder.build(value.amount),
+                value.repetition === null ? null : Repetition.builder.build(value.repetition)
+            );
+        }
+    }
+
+    /**
+     * Singleton instance of TypeBuilder for FineTemplate.
+     */
+    export const builder = new TypeBuilder();
+}

package/src/types/{PayedState.ts → fine/PayedState.ts}

@@ -1,6 +1,6 @@
 import { ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
-import { Localization } from './Localization';
-import { Locale } from './Locale';
+import { Localization } from '../localization/Localization';
+import { Locale } from '../localization/Locale';
 
 const payedStates = ['payed', 'notPayed'] as const;
 

package/src/types/fine/index.ts

@@ -0,0 +1,3 @@
+export * from './Fine';
+export * from './FineTemplate';
+export * from './PayedState';

package/src/types/index.ts

@@ -1,19 +1,8 @@
-export * from './Configuration';
-export * from './Fine';
-export * from './FineAmount';
-export * from './FineTemplate';
-export * from './FineTemplateRepetition';
-export * from './Invitation';
-export * from './Localization';
-export * from './MoneyAmount';
-export * from './NotificationProperties';
-export * from './PayedState';
-export * from './Person';
-export * from './PersonProperties';
-export * from './PersonSignInProperties';
-export * from './Pluralization';
-export * from './Team';
-export * from './User';
-export * from './UserRole';
+export * from './fine';
+export * from './localization';
+export * from './notification';
+export * from './person';
+export * from './team';
+export * from './user';
 export * from './Currency';
-export * from './Locale';
+export * from './Money';

package/src/types/{Localization.ts → localization/Localization.ts}

@@ -1,8 +1,10 @@
 import { mapRecord } from '@stevenkellner/typescript-common-functionality';
-import { localizationEN } from '../locales/en';
-import { localizationDE } from '../locales/de';
+import { localizationEN } from '../../locales/en';
+import { localizationDE } from '../../locales/de';
 import { Pluralization } from './Pluralization';
 import { Locale } from './Locale';
+import { ValueLocalization } from './ValueLocalization';
+import { PluralLocalization } from './PluralLocalization';
 
 /**
  * Type representing the structure of a localization dictionary.
@@ -51,6 +53,7 @@ export class Localization {
     /**
      * Returns the localization structure for the specified locale.
      * Transforms the raw localization data into ValueLocalization and PluralLocalization instances.
+     *
      * @param locale - The locale to retrieve localizations for
      * @returns The complete localization structure with type-safe access
      */
@@ -60,11 +63,12 @@ export class Localization {
 
     /**
      * Recursively maps raw localization data to localization class instances.
+     *
      * @param localization - The raw localization value to transform
      * @returns The transformed localization with proper class instances
      */
     private static mapSubLocalization<T extends SubLocalizationType>(localization: T): SubLocalization<T> {
-        if (typeof localization === 'object' && ! (localization instanceof Pluralization))
+        if (typeof localization === 'object' && !(localization instanceof Pluralization))
             return mapRecord(localization as Record<string, SubLocalizationType>, subLocalization => Localization.mapSubLocalization(subLocalization)) as SubLocalization<T>;
         if (typeof localization === 'string')
             return new ValueLocalization(localization) as SubLocalization<T>;
@@ -74,65 +78,4 @@ export class Localization {
     }
 }
 
-/**
- * Handles localization strings with template variable substitution.
- * Supports {{variableName}} syntax for runtime value replacement.
- */
-export class ValueLocalization {
-
-    /**
-     * Creates a new ValueLocalization instance.
-     * @param rawValue - The template string with {{variable}} placeholders
-     */
-    constructor(private readonly rawValue: string) {}
-
-    /**
-     * Returns the localized string with variables substituted.
-     * Template variables in the format {{key}} are replaced with provided argument values.
-     * @param args - Record of variable names to their replacement values
-     * @returns The localized string with all variables replaced
-     * @throws Error if a required template variable is not provided in args
-     */
-    public value(args: Record<string, string> = {}): string {
-        let rawValue = this.rawValue;
-        const regex = /\{\{(?<key>.*?)\}\}/;
-        while (true) {
-            const match = regex.exec(rawValue);
-            if (!match)
-                break;
-            const key = match.groups!.key;
-            if (!(key in args))
-                throw new Error(`Missing argument for key: ${key}`);
-            rawValue = rawValue.replace(match[0], args[key]);
-        }
-        return rawValue;
-    }
-}
 
-/**
- * Handles pluralized localization strings that vary based on count.
- * Combines Pluralization logic with template variable substitution.
- */
-export class PluralLocalization {
-
-    /**
-     * Creates a new PluralLocalization instance.
-     * @param pluralization - The Pluralization instance containing plural forms
-     */
-    constructor(private readonly pluralization: Pluralization) {}
-
-    /**
-     * Returns the appropriate pluralized string for the given count with variables substituted.
-     * Automatically includes 'count' in the template variables.
-     * @param count - The count to determine which plural form to use
-     * @param args - Additional template variables to substitute (count is added automatically)
-     * @returns The localized plural string with all variables replaced
-     */
-    public value(count: number, args: Record<string, string> = {}): string {
-        const valueLocalization = new ValueLocalization(this.pluralization.get(count));
-        return valueLocalization.value({
-            count: `${count}`,
-            ...args
-        });
-    }
-}

package/src/types/localization/PluralLocalization.ts

@@ -0,0 +1,32 @@
+import { Pluralization } from './Pluralization';
+import { ValueLocalization } from './ValueLocalization';
+
+/**
+ * Handles pluralized localization strings that vary based on count.
+ * Combines Pluralization logic with template variable substitution.
+ */
+export class PluralLocalization {
+
+    /**
+     * Creates a new PluralLocalization instance.
+     *
+     * @param pluralization - The Pluralization instance containing plural forms
+     */
+    constructor(private readonly pluralization: Pluralization) {}
+
+    /**
+     * Returns the appropriate pluralized string for the given count with variables substituted.
+     * Automatically includes 'count' in the template variables.
+     *
+     * @param count - The count to determine which plural form to use
+     * @param args - Additional template variables to substitute (count is added automatically)
+     * @returns The localized plural string with all variables replaced
+     */
+    public value(count: number, args: Record<string, string> = {}): string {
+        const valueLocalization = new ValueLocalization(this.pluralization.get(count));
+        return valueLocalization.value({
+            count: `${count}`,
+            ...args
+        });
+    }
+}

package/src/types/{Pluralization.ts → localization/Pluralization.ts}

@@ -37,6 +37,7 @@ export class Pluralization {
 
     /**
      * 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

package/src/types/localization/ValueLocalization.ts

@@ -0,0 +1,36 @@
+/**
+ * Handles localization strings with template variable substitution.
+ * Supports {{variableName}} syntax for runtime value replacement.
+ */
+export class ValueLocalization {
+
+    /**
+     * Creates a new ValueLocalization instance.
+     *
+     * @param rawValue - The template string with {{variable}} placeholders
+     */
+    constructor(private readonly rawValue: string) {}
+
+    /**
+     * Returns the localized string with variables substituted.
+     * Template variables in the format {{key}} are replaced with provided argument values.
+     *
+     * @param args - Record of variable names to their replacement values
+     * @returns The localized string with all variables replaced
+     * @throws Error if a required template variable is not provided in args
+     */
+    public value(args: Record<string, string> = {}): string {
+        let rawValue = this.rawValue;
+        const regex = /\{\{(?<key>.*?)\}\}/;
+        while (true) {
+            const match = regex.exec(rawValue);
+            if (!match)
+                break;
+            const key = match.groups!.key;
+            if (!(key in args))
+                throw new Error(`Missing argument for key: ${key}`);
+            rawValue = rawValue.replace(match[0], args[key]);
+        }
+        return rawValue;
+    }
+}

package/src/types/localization/index.ts

@@ -0,0 +1,5 @@
+export * from './Locale';
+export * from './Localization';
+export * from './Pluralization';
+export * from './ValueLocalization';
+export * from './PluralLocalization';

package/src/types/notification/InAppNotification.ts

@@ -0,0 +1,184 @@
+import { Flattable, Guid, ITypeBuilder, Tagged, UtcDate } from '@stevenkellner/typescript-common-functionality';
+import { Fine } from '../fine/Fine';
+import { Team } from '../team/Team';
+
+/**
+ * Represents an in-app notification for a user.
+ *
+ * Stores information about team and fine events that are delivered
+ * as in-app notifications rather than push notifications.
+ */
+export class InAppNotification implements Flattable<InAppNotification.Flatten> {
+
+    /**
+     * Creates a new InAppNotification instance.
+     *
+     * @param id - Unique identifier for the notification
+     * @param date - The date and time the notification was created
+     * @param isRead - Whether the notification has been read by the user
+     * @param event - The event data describing what triggered the notification
+     */
+    public constructor(
+        public id: InAppNotification.Id,
+        public date: UtcDate,
+        public isRead: boolean,
+        public event: InAppNotification.Event
+    ) {}
+
+    /**
+     * Returns the flattened representation for serialization.
+     */
+    public get flatten(): InAppNotification.Flatten {
+        return {
+            id: this.id.flatten,
+            date: this.date.flatten,
+            isRead: this.isRead,
+            event: InAppNotification.Event.flatten(this.event)
+        };
+    }
+}
+
+export namespace InAppNotification {
+
+    /**
+     * Tagged GUID type for in-app notification identifiers.
+     */
+    export type Id = Tagged<Guid, 'inAppNotification'>;
+
+    export namespace Id {
+
+        /**
+         * Flattened representation of a notification ID (GUID string).
+         */
+        export type Flatten = string;
+
+        /**
+         * Type builder for InAppNotification.Id serialization/deserialization.
+         */
+        export const builder = Tagged.builder('inAppNotification' as const, Guid.builder);
+    }
+
+    /**
+     * Union type representing the different events that can trigger an in-app notification.
+     */
+    export type Event =
+        | { type: 'fine-added'; teamId: Team.Id; fineId: Fine.Id; reason: string; }
+        | { type: 'fine-updated'; teamId: Team.Id; fineId: Fine.Id; reason: string; }
+        | { type: 'fine-payed'; teamId: Team.Id; fineId: Fine.Id; reason: string; }
+        | { type: 'fine-deleted'; teamId: Team.Id; reason: string; }
+        | { type: 'person-role-changed'; teamId: Team.Id; }
+        | { type: 'team-kickout'; teamId: Team.Id; };
+
+    export namespace Event {
+
+        /**
+         * Flattened representation of an Event for serialization.
+         */
+        export type Flatten =
+            | { type: 'fine-added'; teamId: Team.Id.Flatten; fineId: Fine.Id.Flatten; reason: string; }
+            | { type: 'fine-updated'; teamId: Team.Id.Flatten; fineId: Fine.Id.Flatten; reason: string; }
+            | { type: 'fine-payed'; teamId: Team.Id.Flatten; fineId: Fine.Id.Flatten; reason: string; }
+            | { type: 'fine-deleted'; teamId: Team.Id.Flatten; reason: string; }
+            | { type: 'person-role-changed'; teamId: Team.Id.Flatten; }
+            | { type: 'team-kickout'; teamId: Team.Id.Flatten; };
+
+        /**
+         * Flattens an Event instance for serialization.
+         *
+         * @param event - The event to flatten
+         * @returns The flattened event representation
+         */
+        export function flatten(event: Event): Flatten {
+            switch (event.type) {
+            case 'fine-added':
+            case 'fine-updated':
+            case 'fine-payed':
+                return { type: event.type, teamId: event.teamId.flatten, fineId: event.fineId.flatten, reason: event.reason };
+            case 'fine-deleted':
+                return { type: event.type, teamId: event.teamId.flatten, reason: event.reason };
+            case 'person-role-changed':
+            case 'team-kickout':
+                return { type: event.type, teamId: event.teamId.flatten };
+            }
+        }
+
+        /**
+         * Type builder for Event serialization/deserialization.
+         */
+        export class TypeBuilder implements ITypeBuilder<Flatten, Event> {
+
+            /**
+             * Builds an Event instance from flattened data.
+             *
+             * @param value - The flattened event data
+             * @returns The appropriate Event instance based on the type discriminator
+             */
+            public build(value: Flatten): Event {
+                switch (value.type) {
+                case 'fine-added':
+                case 'fine-updated':
+                case 'fine-payed':
+                    return {
+                        type: value.type,
+                        teamId: Team.Id.builder.build(value.teamId),
+                        fineId: Fine.Id.builder.build(value.fineId),
+                        reason: value.reason
+                    };
+                case 'fine-deleted':
+                    return {
+                        type: value.type,
+                        teamId: Team.Id.builder.build(value.teamId),
+                        reason: value.reason
+                    };
+                case 'person-role-changed':
+                case 'team-kickout':
+                    return {
+                        type: value.type,
+                        teamId: Team.Id.builder.build(value.teamId)
+                    };
+                }
+            }
+        }
+
+        /**
+         * Singleton builder instance for Event.
+         */
+        export const builder = new TypeBuilder();
+    }
+
+    /**
+     * Flattened representation of an InAppNotification for serialization.
+     */
+    export type Flatten = {
+        id: Id.Flatten;
+        date: UtcDate.Flatten;
+        isRead: boolean;
+        event: Event.Flatten;
+    };
+
+    /**
+     * Type builder for InAppNotification serialization/deserialization.
+     */
+    export class TypeBuilder implements ITypeBuilder<Flatten, InAppNotification> {
+
+        /**
+         * Builds an InAppNotification instance from flattened data.
+         *
+         * @param value - The flattened notification data
+         * @returns A new InAppNotification instance
+         */
+        public build(value: Flatten): InAppNotification {
+            return new InAppNotification(
+                Id.builder.build(value.id),
+                UtcDate.builder.build(value.date),
+                value.isRead,
+                Event.builder.build(value.event)
+            );
+        }
+    }
+
+    /**
+     * Singleton builder instance for InAppNotification.
+     */
+    export const builder = new TypeBuilder();
+}

package/src/types/notification/index.ts

@@ -0,0 +1 @@
+export * from './InAppNotification';

package/src/types/{Person.ts → person/Person.ts}

@@ -1,7 +1,7 @@
+import { Flattable, Guid, ITypeBuilder, Tagged } from '@stevenkellner/typescript-common-functionality';
 import { PersonProperties } from './PersonProperties';
 import { PersonSignInProperties } from './PersonSignInProperties';
-import { Fine } from './Fine';
-import { Flattable, Guid, ITypeBuilder, Tagged } from '@stevenkellner/typescript-common-functionality';
+import { Fine } from '../fine/Fine';
 
 /**
  * Represents a person within a team, including their personal details, assigned fines, and optional sign-in properties.
@@ -14,7 +14,7 @@ export class Person implements Flattable<Person.Flatten> {
      * Creates a new Person instance.
      *
      * @param id - Unique identifier for the person (GUID)
-     * @param properties - Private properties including first name and optional last name
+     * @param properties - Personal properties including first name and last name
      * @param fineIds - Array of fine IDs assigned to this person (defaults to empty array)
      * @param signInProperties - Optional sign-in properties if the person has signed in (defaults to null)
      */