@stevenkellner/team-conduct-api 1.0.36 → 2.0.1

package/src/types/FineAmount.ts

@@ -2,27 +2,56 @@ import { Flattable, ITypeBuilder } from '@stevenkellner/typescript-common-functi
 import { MoneyAmount } from './MoneyAmount';
 import { Configuration } from './Configuration';
 import { Localization } from './Localization';
+import { Locale } from './Locale';
 
+/**
+ * Represents the amount of a fine, either as a monetary value or as items.
+ *
+ * Can be either FineAmount.Money (e.g., $10) or FineAmount.Item (e.g., 2 crates of beer).
+ */
 export type FineAmount =
     | FineAmount.Money
     | FineAmount.Item;
 
 export namespace FineAmount {
 
+    /**
+     * Represents a fine amount as a monetary value.
+     */
     export class Money implements Flattable<Money.Flatten> {
 
+        /**
+         * Creates a new Money fine amount.
+         *
+         * @param amount - The monetary amount
+         */
         public constructor(
             public amount: MoneyAmount
         ) {}
 
+        /**
+         * Returns a formatted string representation of the amount.
+         *
+         * @param configuration - Configuration containing currency and locale
+         * @returns Formatted currency string (e.g., "$10.50")
+         */
         public formatted(configuration: Configuration): string {
             return this.amount.formatted(configuration.currency, configuration);
         }
 
+        /**
+         * Returns a new Money instance with the amount multiplied by a factor.
+         *
+         * @param factor - The multiplication factor
+         * @returns New Money instance with multiplied amount
+         */
         public multiplied(factor: number): Money {
             return new Money(this.amount.multiplied(factor));
         }
 
+        /**
+         * Returns the flattened representation for serialization.
+         */
         public get flatten(): Money.Flatten {
             return {
                 type: 'money',
@@ -33,40 +62,94 @@ export namespace FineAmount {
 
     export namespace Money {
 
+        /**
+         * Flattened representation of Money for serialization.
+         */
         export type Flatten = {
             type: 'money',
             amount: MoneyAmount.Flatten
         }
 
+        /**
+         * Type builder for Money serialization/deserialization.
+         */
         export class TypeBuilder implements ITypeBuilder<Flatten, Money> {
 
+            /**
+             * Builds a Money instance from flattened data.
+             *
+             * @param value - Flattened money data
+             * @returns Money instance
+             */
             public build(value: Flatten): Money {
                 return new Money(MoneyAmount.builder.build(value.amount));
             }
         }
 
+        /**
+         * Singleton instance of TypeBuilder for Money.
+         */
         export const builder = new TypeBuilder();
     }
 
+    /**
+     * Represents a fine amount as a quantity of items.
+     */
     export class Item implements Flattable<Item.Flatten> {
 
+        /**
+         * Creates a new Item fine amount.
+         *
+         * @param item - The item type (e.g., 'crateOfBeer')
+         * @param count - The number of items
+         */
         public constructor(
             public item: Item.Type,
             public count: number
         ) {}
 
-        public formatted(): string {
-            return Localization.shared.fineAmount.item.type[this.item].withCount.value(this.count);
+        /**
+         * Returns a formatted string representation including count.
+         *
+         * @param locale - The locale for formatting
+         * @returns Formatted string (e.g., "2 crates of beer")
+         */
+        public formatted(locale: Locale): string;
+        /**
+         * Returns a formatted string representation including count.
+         *
+         * @param configuration - Configuration containing locale
+         * @returns Formatted string (e.g., "2 crates of beer")
+         */
+        public formatted(configuration: Configuration): string;
+        public formatted(configurationOrLocale: Configuration | Locale): string {
+            const locale = configurationOrLocale instanceof Configuration ? configurationOrLocale.locale : configurationOrLocale;
+            return Localization.shared(locale).fineAmount.item.type[this.item].withCount.value(this.count);
         }
 
-        public formattedWithoutCount(): string {
-            return Localization.shared.fineAmount.item.type[this.item].withoutCount.value(this.count);
+        /**
+         * Returns a formatted string representation without explicitly showing count.
+         *
+         * @param locale - The locale for formatting
+         * @returns Formatted string without count display
+         */
+        public formattedWithoutCount(locale: Locale): string {
+            return Localization.shared(locale).fineAmount.item.type[this.item].withoutCount.value(this.count);
         }
 
+        /**
+         * Returns a new Item instance with the count multiplied by a factor.
+         *
+         * @param factor - The multiplication factor
+         * @returns New Item instance with multiplied count
+         */
         public multiplied(factor: number): Item {
             return new Item(this.item, this.count * factor);
         }
 
+        /**
+         * Returns the flattened representation for serialization.
+         */
         public get flatten(): Item.Flatten {
             return {
                 type: 'item',
@@ -78,43 +161,94 @@ export namespace FineAmount {
 
     export namespace Item {
 
-        export type Type =
-            | 'crateOfBeer';
+        const itemTypes = ['crateOfBeer'] as const;
 
-        export namespace Type {
+        /**
+         * Item type: currently only 'crateOfBeer'.
+         */
+        export type Type = typeof itemTypes[number];
 
-            export const all: Type[] = ['crateOfBeer'];
+        export namespace Type {
 
-            export function formatted(type: Type): string {
-                return Localization.shared.fineAmount.item.type[type].name.value();
+            /**
+             * Array containing all possible item types.
+             */
+            export const all: readonly Type[] = itemTypes;
+
+            /**
+             * Returns the localized name for an item type.
+             *
+             * @param type - The item type
+             * @param locale - The locale to use for formatting
+             * @returns Localized item name
+             */
+            export function formatted(type: Type, locale: Locale): string {
+                return Localization.shared(locale).fineAmount.item.type[type].name.value();
             }
         }
 
+        /**
+         * Flattened representation of Item for serialization.
+         */
         export type Flatten = {
             type: 'item',
             item: Item.Type,
             count: number
         }
 
+        /**
+         * Type builder for Item serialization/deserialization.
+         */
         export class TypeBuilder implements ITypeBuilder<Flatten, Item> {
 
+            /**
+             * Builds an Item instance from flattened data.
+             *
+             * @param value - Flattened item data
+             * @returns Item instance
+             */
             public build(value: Flatten): Item {
                 return new Item(value.item, value.count);
             }
         }
 
+        /**
+         * Singleton instance of TypeBuilder for Item.
+         */
         export const builder = new TypeBuilder();
     }
 
-
+    /**
+     * Creates a Money fine amount.
+     *
+     * @param MoneyAmount - The monetary amount
+     * @returns Money instance
+     */
     export function money(MoneyAmount: MoneyAmount): Money {
         return new Money(MoneyAmount);
     }
 
+    /**
+     * Creates an Item fine amount.
+     *
+     * @param item - The item type
+     * @param count - The number of items
+     * @returns Item instance
+     */
     export function item(item: Item.Type, count: number): Item {
         return new Item(item, count);
     }
 
+    /**
+     * Compares two fine amounts and returns their relative ordering.
+     *
+     * Money amounts are considered greater than Item amounts.
+     * Within the same type, values are compared numerically.
+     *
+     * @param lhs - First fine amount to compare
+     * @param rhs - Second fine amount to compare
+     * @returns 'less' if lhs < rhs, 'equal' if lhs === rhs, 'greater' if lhs > rhs
+     */
     export function compare(lhs: FineAmount, rhs: FineAmount): 'less' | 'equal' | 'greater' {
         if (lhs instanceof Money) {
             if (!(rhs instanceof Money))
@@ -134,10 +268,24 @@ export namespace FineAmount {
         return 'equal';
     }
 
+    /**
+     * Flattened representation of FineAmount (union of Money.Flatten and Item.Flatten).
+     */
     export type Flatten = Money.Flatten | Item.Flatten;
 
+    /**
+     * Type builder for FineAmount serialization/deserialization.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, FineAmount> {
 
+        /**
+         * Builds a FineAmount instance from flattened data.
+         *
+         * Determines the type based on the 'type' discriminator field.
+         *
+         * @param value - Flattened fine amount data
+         * @returns FineAmount instance (Money or Item)
+         */
         public build(value: Flatten): FineAmount {
             switch (value.type) {
             case 'money':
@@ -148,5 +296,8 @@ export namespace FineAmount {
         }
     }
 
+    /**
+     * Singleton instance of TypeBuilder for FineAmount.
+     */
     export const builder = new TypeBuilder();
 }

package/src/types/FineTemplate.ts

@@ -2,8 +2,22 @@ import { Flattable, Guid, ITypeBuilder, Tagged } from '@stevenkellner/typescript
 import { FineAmount } from './FineAmount';
 import { FineTemplateRepetition } from './FineTemplateRepetition';
 
+/**
+ * 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,
@@ -11,6 +25,9 @@ export class FineTemplate implements Flattable<FineTemplate.Flatten> {
         public repetition: FineTemplateRepetition | null
     ) {}
 
+    /**
+     * Returns the flattened representation for serialization.
+     */
     public get flatten(): FineTemplate.Flatten {
         return {
             id: this.id.flatten,
@@ -23,15 +40,27 @@ export class FineTemplate implements Flattable<FineTemplate.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);
     }
 
+    /**
+     * Flattened representation of a FineTemplate for serialization.
+     */
     export type Flatten = {
         id: Id.Flatten,
         reason: string,
@@ -39,8 +68,17 @@ export namespace FineTemplate {
         repetition: FineTemplateRepetition.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),
@@ -51,5 +89,8 @@ export namespace FineTemplate {
         }
     }
 
+    /**
+     * Singleton instance of TypeBuilder for FineTemplate.
+     */
     export const builder = new TypeBuilder();
 }

package/src/types/FineTemplateRepetition.ts

@@ -1,21 +1,50 @@
 import { Flattable, ITypeBuilder, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
 import { Localization } from './Localization';
+import { Locale } from './Locale';
 
+/**
+ * Represents how a fine template repeats over time.
+ *
+ * Defines the repetition unit (minute, day, item, count) and optional maximum count for repetitions.
+ */
 export class FineTemplateRepetition implements Flattable<FineTemplateRepetition.Flatten> {
 
+    /**
+     * Creates a new FineTemplateRepetition 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: FineTemplateRepetition.Item,
         public maxCount: number | null
     ) {}
 
-    public formatted(count: number): string {
-        return Localization.shared.fineTemplateRepetition.item[this.item].withCount.value(count);
+    /**
+     * 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);
     }
 
-    public formattedWithoutCount(count: number): string {
-        return Localization.shared.fineTemplateRepetition.item[this.item].withoutCount.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(): FineTemplateRepetition.Flatten {
         return {
             item: this.item,
@@ -26,35 +55,61 @@ export class FineTemplateRepetition implements Flattable<FineTemplateRepetition.
 
 export namespace FineTemplateRepetition {
 
-    export type Item =
-        | 'minute'
-        | 'day'
-        | 'item'
-        | 'count';
+    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 {
 
-        export const all: Item[] = [
-            'minute',
-            'day',
-            'item',
-            'count'
-        ];
+        /**
+         * Array containing all possible repetition item types.
+         */
+        export const all: readonly Item[] = repetitionItems;
 
-        export function formatted(item: Item): string {
-            return Localization.shared.fineTemplateRepetition.item[item].name.value();
+        /**
+         * 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 FineTemplateRepetition for serialization.
+     */
     export type Flatten = {
         item: Item,
         maxCount: number | null
     }
 
+    /**
+     * Type builder for FineTemplateRepetition serialization/deserialization.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, FineTemplateRepetition> {
 
+        /**
+         * Builds a FineTemplateRepetition instance from flattened data.
+         *
+         * @param flatten - Flattened repetition data
+         * @returns FineTemplateRepetition instance
+         */
         public build(flatten: Flatten): FineTemplateRepetition {
             return new FineTemplateRepetition(
                 flatten.item,
@@ -63,5 +118,8 @@ export namespace FineTemplateRepetition {
         }
     }
 
+    /**
+     * Singleton instance of TypeBuilder for FineTemplateRepetition.
+     */
     export const builder = new TypeBuilder();
 }

package/src/types/Invitation.ts

@@ -2,13 +2,34 @@ import { BytesCoder, Flattable, ITypeBuilder, OptionalTypeBuilder, Sha512, Tagge
 import { Team } from './Team';
 import { Person } from './Person';
 
+/**
+ * Represents an invitation to join a team.
+ *
+ * An invitation can be team-wide (personId is null) or specific to a person.
+ * The invitation ID is generated by hashing the team ID and optional person ID.
+ */
 export class Invitation implements Flattable<Invitation.Flatten> {
 
+    /**
+     * Creates a new Invitation instance.
+     *
+     * @param teamId - The ID of the team for the invitation
+     * @param personId - Optional person ID for person-specific invitations (null for team-wide invitations)
+     */
     constructor(
         public teamId: Team.Id,
         public personId: Person.Id | null
     ) {}
 
+    /**
+     * Creates a unique invitation ID by hashing the team ID and optional person ID.
+     *
+     * Uses SHA-512 hashing and takes the first 12 characters of the hex representation.
+     * Team-wide invitations (personId null) hash only the team ID.
+     * Person-specific invitations hash both team ID and person ID concatenated.
+     *
+     * @returns Tagged invitation ID string (12 hex characters)
+     */
     public createId(): Invitation.Id {
         const hasher = new Sha512();
         const teamIdBytes = BytesCoder.fromUtf8(this.teamId.guidString);
@@ -22,6 +43,9 @@ export class Invitation implements Flattable<Invitation.Flatten> {
         return new Tagged(rawId, 'invitation');
     }
 
+    /**
+     * Returns the flattened representation for serialization.
+     */
     public get flatten(): Invitation.Flatten {
         return {
             teamId: this.teamId.flatten,
@@ -32,22 +56,43 @@ export class Invitation implements Flattable<Invitation.Flatten> {
 
 export namespace Invitation {
 
+    /**
+     * Tagged string type for invitation identifiers (12 hex characters).
+     */
     export type Id = Tagged<string, 'invitation'>;
 
     export namespace Id {
 
+        /**
+         * Flattened representation of an invitation ID (string).
+         */
         export type Flatten = string;
 
+        /**
+         * Type builder for Invitation.Id serialization/deserialization.
+         */
         export const builder = Tagged.builder('invitation' as const, new ValueTypeBuilder<string>());
     }
 
+    /**
+     * Flattened representation of an Invitation for serialization.
+     */
     export type Flatten = {
         teamId: Team.Id.Flatten,
         personId: Person.Id.Flatten | null
     };
 
+    /**
+     * Type builder for Invitation serialization/deserialization.
+     */
     export class TypeBuilder implements ITypeBuilder<Flatten, Invitation> {
 
+        /**
+         * Builds an Invitation instance from flattened data.
+         *
+         * @param value - Flattened invitation data
+         * @returns Invitation instance
+         */
         public build(value: Flatten): Invitation {
             return new Invitation(
                 Team.Id.builder.build(value.teamId),
@@ -56,5 +101,8 @@ export namespace Invitation {
         }
     }
 
+    /**
+     * Singleton instance of TypeBuilder for Invitation.
+     */
     export const builder = new TypeBuilder();
 }

package/src/types/Locale.ts

@@ -0,0 +1,20 @@
+import { keys, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
+import { localizations } from './Localization';
+
+/**
+ * Supported locale types, derived from available localizations.
+ */
+export type Locale = keyof typeof localizations;
+
+export namespace Locale {
+
+    /**
+     * Array of all available locales.
+     */
+    export const all: Locale[] = keys(localizations);
+
+    /**
+     * Builder for constructing Locale values.
+     */
+    export const builder = new ValueTypeBuilder<Locale>();
+}