@stevenkellner/team-conduct-api 1.0.36 → 2.0.1

package/lib/src/types/Localization.d.ts

@@ -1,4 +1,15 @@
+import { localizationEN } from '../locales/en';
 import { Pluralization } from './Pluralization';
+import { Locale } from './Locale';
+/**
+ * Type representing the structure of a localization dictionary.
+ * Derived from the English localization as the base template.
+ */
+export type LocalizationDict = typeof localizationEN;
+/**
+ * Record of all available localizations keyed by locale.
+ * Each localization must match the structure of LocalizationDict.
+ */
 export declare const localizations: {
     en: {
         notification: {
@@ -133,91 +144,80 @@ export declare const localizations: {
         };
     };
 };
+/**
+ * Recursive type definition for localization values.
+ * Can be nested objects, strings with template variables, or Pluralization instances.
+ */
 export type SubLocalizationType = {
     [Key in string]: SubLocalizationType;
 } | string | Pluralization;
+/**
+ * Mapped type that transforms SubLocalizationType into corresponding localization classes.
+ * - Objects become nested SubLocalization structures
+ * - Strings become ValueLocalization instances
+ * - Pluralization instances become PluralLocalization instances
+ */
 export type SubLocalization<T extends SubLocalizationType> = T extends {
     [Key in string]: SubLocalizationType;
 } ? {
     [Key in keyof T]: SubLocalization<T[Key]>;
 } : T extends string ? ValueLocalization : T extends Pluralization ? PluralLocalization : never;
+/**
+ * Main localization class that provides access to localized strings.
+ * Transforms raw localization data into type-safe localization objects.
+ */
+export declare 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
+     */
+    static shared(locale: Locale): SubLocalization<LocalizationDict>;
+    /**
+     * 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;
+}
+/**
+ * Handles localization strings with template variable substitution.
+ * Supports {{variableName}} syntax for runtime value replacement.
+ */
 export declare class ValueLocalization {
-    private readonly rawValues;
-    constructor(rawValues: Record<keyof typeof localizations, string>);
+    private readonly rawValue;
+    /**
+     * Creates a new ValueLocalization instance.
+     * @param rawValue - The template string with {{variable}} placeholders
+     */
+    constructor(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
+     */
     value(args?: Record<string, string>): string;
 }
+/**
+ * Handles pluralized localization strings that vary based on count.
+ * Combines Pluralization logic with template variable substitution.
+ */
 export declare class PluralLocalization {
-    private readonly pluralizations;
-    constructor(pluralizations: Record<keyof typeof localizations, Pluralization>);
+    private readonly pluralization;
+    /**
+     * Creates a new PluralLocalization instance.
+     * @param pluralization - The Pluralization instance containing plural forms
+     */
+    constructor(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
+     */
     value(count: number, args?: Record<string, string>): string;
 }
-export declare class Localization {
-    static locale: keyof typeof localizations;
-    static readonly shared: {
-        notification: {
-            fine: {
-                new: {
-                    title: ValueLocalization;
-                    body: ValueLocalization;
-                };
-                reminder: {
-                    title: ValueLocalization;
-                    body: ValueLocalization;
-                };
-                stateChange: {
-                    title: ValueLocalization;
-                    bodyPayed: ValueLocalization;
-                    bodyUnpayed: ValueLocalization;
-                    bodyDeleted: ValueLocalization;
-                };
-            };
-        };
-        fineAmount: {
-            item: {
-                type: {
-                    crateOfBeer: {
-                        name: ValueLocalization;
-                        withCount: PluralLocalization;
-                        withoutCount: PluralLocalization;
-                    };
-                };
-            };
-        };
-        fineTemplateRepetition: {
-            item: {
-                minute: {
-                    name: ValueLocalization;
-                    withCount: PluralLocalization;
-                    withoutCount: PluralLocalization;
-                };
-                day: {
-                    name: ValueLocalization;
-                    withCount: PluralLocalization;
-                    withoutCount: PluralLocalization;
-                };
-                item: {
-                    name: ValueLocalization;
-                    withCount: PluralLocalization;
-                    withoutCount: PluralLocalization;
-                };
-                count: {
-                    name: ValueLocalization;
-                    withCount: PluralLocalization;
-                    withoutCount: PluralLocalization;
-                };
-            };
-        };
-        payedState: {
-            payed: ValueLocalization;
-            notPayed: ValueLocalization;
-        };
-        userRole: {
-            personManager: ValueLocalization;
-            fineTemplateManager: ValueLocalization;
-            fineManager: ValueLocalization;
-            fineCanAdd: ValueLocalization;
-            teamManager: ValueLocalization;
-        };
-    };
-    private static getSubLocalization;
-}

package/lib/src/types/Localization.js

@@ -1,21 +1,75 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Localization = exports.PluralLocalization = exports.ValueLocalization = exports.localizations = void 0;
+exports.PluralLocalization = exports.ValueLocalization = exports.Localization = exports.localizations = void 0;
 const typescript_common_functionality_1 = require("@stevenkellner/typescript-common-functionality");
 const en_1 = require("../locales/en");
 const de_1 = require("../locales/de");
 const Pluralization_1 = require("./Pluralization");
-exports.localizations = {
+/**
+ * Helper function to ensure a record satisfies the localization structure
+ * while preserving its concrete type.
+ */
+const satisfiesLocalizationRecord = (value) => value;
+/**
+ * Record of all available localizations keyed by locale.
+ * Each localization must match the structure of LocalizationDict.
+ */
+exports.localizations = satisfiesLocalizationRecord({
     en: en_1.localizationEN,
     de: de_1.localizationDE
-};
+});
+/**
+ * Main localization class that provides access to localized strings.
+ * Transforms raw localization data into type-safe localization objects.
+ */
+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
+     */
+    static shared(locale) {
+        return Localization.mapSubLocalization(exports.localizations[locale]);
+    }
+    /**
+     * 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
+     */
+    static mapSubLocalization(localization) {
+        if (typeof localization === 'object' && !(localization instanceof Pluralization_1.Pluralization))
+            return (0, typescript_common_functionality_1.mapRecord)(localization, subLocalization => Localization.mapSubLocalization(subLocalization));
+        if (typeof localization === 'string')
+            return new ValueLocalization(localization);
+        if (localization instanceof Pluralization_1.Pluralization)
+            return new PluralLocalization(localization);
+        throw new Error('Invalid localization structure');
+    }
+}
+exports.Localization = Localization;
+/**
+ * Handles localization strings with template variable substitution.
+ * Supports {{variableName}} syntax for runtime value replacement.
+ */
 class ValueLocalization {
-    rawValues;
-    constructor(rawValues) {
-        this.rawValues = rawValues;
+    rawValue;
+    /**
+     * Creates a new ValueLocalization instance.
+     * @param rawValue - The template string with {{variable}} placeholders
+     */
+    constructor(rawValue) {
+        this.rawValue = rawValue;
     }
+    /**
+     * 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
+     */
     value(args = {}) {
-        let rawValue = this.rawValues[Localization.locale];
+        let rawValue = this.rawValue;
         const regex = /\{\{(?<key>.*?)\}\}/;
         while (true) {
             const match = regex.exec(rawValue);
@@ -30,13 +84,28 @@ class ValueLocalization {
     }
 }
 exports.ValueLocalization = ValueLocalization;
+/**
+ * Handles pluralized localization strings that vary based on count.
+ * Combines Pluralization logic with template variable substitution.
+ */
 class PluralLocalization {
-    pluralizations;
-    constructor(pluralizations) {
-        this.pluralizations = pluralizations;
+    pluralization;
+    /**
+     * Creates a new PluralLocalization instance.
+     * @param pluralization - The Pluralization instance containing plural forms
+     */
+    constructor(pluralization) {
+        this.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
+     */
     value(count, args = {}) {
-        const valueLocalization = new ValueLocalization((0, typescript_common_functionality_1.mapRecord)(this.pluralizations, pluralization => pluralization.get(count)));
+        const valueLocalization = new ValueLocalization(this.pluralization.get(count));
         return valueLocalization.value({
             count: `${count}`,
             ...args
@@ -44,33 +113,3 @@ class PluralLocalization {
     }
 }
 exports.PluralLocalization = PluralLocalization;
-function swap1stAnd2ndLevel(record) {
-    const swapped = {};
-    for (const key1 of (0, typescript_common_functionality_1.keys)(record)) {
-        for (const key2 of (0, typescript_common_functionality_1.keys)(record[key1])) {
-            if (!(key2 in swapped))
-                swapped[key2] = {};
-            swapped[key2][key1] = record[key1][key2];
-        }
-    }
-    return swapped;
-}
-class Localization {
-    static locale = 'en';
-    static shared = Localization.getSubLocalization(exports.localizations);
-    static getSubLocalization(_localizations) {
-        const _localizationValue = (0, typescript_common_functionality_1.values)(_localizations);
-        if (_localizationValue.length === 0)
-            return {};
-        if (typeof _localizationValue[0] === 'object' && !(_localizationValue[0] instanceof Pluralization_1.Pluralization)) {
-            const swapped = swap1stAnd2ndLevel(_localizations);
-            return (0, typescript_common_functionality_1.mapRecord)(swapped, subLocalization => Localization.getSubLocalization(subLocalization));
-        }
-        if (typeof _localizationValue[0] === 'string')
-            return new ValueLocalization(_localizations);
-        if (_localizationValue[0] instanceof Pluralization_1.Pluralization)
-            return new PluralLocalization(_localizations);
-        throw new Error('Invalid localization structure');
-    }
-}
-exports.Localization = Localization;

package/lib/src/types/MoneyAmount.d.ts

@@ -1,20 +1,86 @@
 import { Flattable, ITypeBuilder } from '@stevenkellner/typescript-common-functionality';
 import { Configuration } from './Configuration';
+import { Currency } from './Currency';
+/**
+ * Represents a monetary amount with integer value and subunit components.
+ *
+ * Stores money as two parts: main value (e.g., dollars) and subunit value (e.g., cents).
+ * This prevents floating-point precision issues in financial calculations.
+ */
 export declare class MoneyAmount implements Flattable<MoneyAmount.Flatten> {
     value: number;
     subunitValue: number;
+    /**
+     * Creates a new MoneyAmount instance.
+     *
+     * @param value - The main value (e.g., dollars, euros)
+     * @param subunitValue - The subunit value (e.g., cents), should be 0-99
+     */
     constructor(value: number, subunitValue: number);
+    /**
+     * Returns a MoneyAmount representing zero.
+     */
     static get zero(): MoneyAmount;
+    /**
+     * Adds another MoneyAmount to this one and returns the result.
+     *
+     * Properly handles subunit overflow (e.g., 50 cents + 60 cents = 1 dollar 10 cents).
+     *
+     * @param amount - The MoneyAmount to add
+     * @returns A new MoneyAmount representing the sum
+     */
     added(amount: MoneyAmount): MoneyAmount;
+    /**
+     * Multiplies this MoneyAmount by a factor and returns the result.
+     *
+     * Properly handles subunit calculations and overflow.
+     *
+     * @param factor - The multiplication factor
+     * @returns A new MoneyAmount representing the product
+     */
     multiplied(factor: number): MoneyAmount;
-    formatted(currency: Configuration.Currency, configuration: Configuration): string;
+    /**
+     * Returns a localized formatted string representation of the amount.
+     *
+     * Uses Intl.NumberFormat for proper currency formatting based on locale.
+     *
+     * @param currency - The currency code (e.g., 'USD', 'EUR')
+     * @param configuration - Configuration containing locale information
+     * @returns Formatted currency string (e.g., "$12.50", "12,50 €")
+     */
+    formatted(currency: Currency, configuration: Configuration): string;
+    /**
+     * Returns the complete monetary value as a decimal number.
+     *
+     * @returns The total value (e.g., 12.50 for 12 dollars and 50 cents)
+     */
     get completeValue(): number;
+    /**
+     * Returns the flattened representation as a decimal number.
+     */
     get flatten(): MoneyAmount.Flatten;
 }
 export declare namespace MoneyAmount {
+    /**
+     * Flattened representation of MoneyAmount as a decimal number.
+     */
     type Flatten = number;
+    /**
+     * Type builder for MoneyAmount serialization/deserialization.
+     */
     class TypeBuilder implements ITypeBuilder<Flatten, MoneyAmount> {
+        /**
+         * Builds a MoneyAmount instance from a flattened decimal value.
+         *
+         * Separates the decimal into integer and subunit parts.
+         *
+         * @param value - Decimal value (e.g., 12.50)
+         * @returns MoneyAmount instance
+         */
         build(value: Flatten): MoneyAmount;
     }
+    /**
+     * Singleton instance of TypeBuilder for MoneyAmount.
+     */
     const builder: TypeBuilder;
 }

package/lib/src/types/MoneyAmount.js

@@ -1,26 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MoneyAmount = void 0;
+/**
+ * Represents a monetary amount with integer value and subunit components.
+ *
+ * Stores money as two parts: main value (e.g., dollars) and subunit value (e.g., cents).
+ * This prevents floating-point precision issues in financial calculations.
+ */
 class MoneyAmount {
     value;
     subunitValue;
+    /**
+     * Creates a new MoneyAmount instance.
+     *
+     * @param value - The main value (e.g., dollars, euros)
+     * @param subunitValue - The subunit value (e.g., cents), should be 0-99
+     */
     constructor(value, subunitValue) {
         this.value = value;
         this.subunitValue = subunitValue;
     }
+    /**
+     * Returns a MoneyAmount representing zero.
+     */
     static get zero() {
         return new MoneyAmount(0, 0);
     }
+    /**
+     * Adds another MoneyAmount to this one and returns the result.
+     *
+     * Properly handles subunit overflow (e.g., 50 cents + 60 cents = 1 dollar 10 cents).
+     *
+     * @param amount - The MoneyAmount to add
+     * @returns A new MoneyAmount representing the sum
+     */
     added(amount) {
         const subunitValue = this.subunitValue + amount.subunitValue;
         const value = this.value + amount.value + Math.floor(subunitValue / 100);
         return new MoneyAmount(value, subunitValue % 100);
     }
+    /**
+     * Multiplies this MoneyAmount by a factor and returns the result.
+     *
+     * Properly handles subunit calculations and overflow.
+     *
+     * @param factor - The multiplication factor
+     * @returns A new MoneyAmount representing the product
+     */
     multiplied(factor) {
         const subunitValue = this.subunitValue * factor;
         const value = this.value * factor + Math.floor(subunitValue / 100);
         return new MoneyAmount(value, subunitValue % 100);
     }
+    /**
+     * Returns a localized formatted string representation of the amount.
+     *
+     * Uses Intl.NumberFormat for proper currency formatting based on locale.
+     *
+     * @param currency - The currency code (e.g., 'USD', 'EUR')
+     * @param configuration - Configuration containing locale information
+     * @returns Formatted currency string (e.g., "$12.50", "12,50 €")
+     */
     formatted(currency, configuration) {
         const numberFormat = Intl.NumberFormat(configuration.locale, {
             style: 'currency',
@@ -28,20 +68,42 @@ class MoneyAmount {
         });
         return numberFormat.format(this.value + this.subunitValue / 100);
     }
+    /**
+     * Returns the complete monetary value as a decimal number.
+     *
+     * @returns The total value (e.g., 12.50 for 12 dollars and 50 cents)
+     */
     get completeValue() {
         return this.value + this.subunitValue / 100;
     }
+    /**
+     * Returns the flattened representation as a decimal number.
+     */
     get flatten() {
         return this.value + this.subunitValue / 100;
     }
 }
 exports.MoneyAmount = MoneyAmount;
 (function (MoneyAmount) {
+    /**
+     * Type builder for MoneyAmount serialization/deserialization.
+     */
     class TypeBuilder {
+        /**
+         * Builds a MoneyAmount instance from a flattened decimal value.
+         *
+         * Separates the decimal into integer and subunit parts.
+         *
+         * @param value - Decimal value (e.g., 12.50)
+         * @returns MoneyAmount instance
+         */
         build(value) {
             return new MoneyAmount(Math.floor(value), Math.round((value - Math.floor(value)) * 100));
         }
     }
     MoneyAmount.TypeBuilder = TypeBuilder;
+    /**
+     * Singleton instance of TypeBuilder for MoneyAmount.
+     */
     MoneyAmount.builder = new MoneyAmount.TypeBuilder();
 })(MoneyAmount || (exports.MoneyAmount = MoneyAmount = {}));

package/lib/src/types/NotificationProperties.d.ts

@@ -1,28 +1,89 @@
 import { Dictionary, Flattable, ITypeBuilder, Tagged, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
+/**
+ * Represents notification properties for a user including device tokens and subscription preferences.
+ *
+ * Manages push notification device tokens (identified by hashed token IDs for security)
+ * and user preferences for which types of notifications they want to receive.
+ */
 export declare class NotificationProperties implements Flattable<NotificationProperties.Flatten> {
     tokens: Dictionary<NotificationProperties.TokenId, string>;
     subscriptions: NotificationProperties.Subscription[];
+    /**
+     * Creates new notification properties.
+     * @param tokens - Dictionary mapping token IDs to device tokens for push notifications (defaults to empty)
+     * @param subscriptions - Array of notification types the user is subscribed to (defaults to empty)
+     */
     constructor(tokens?: Dictionary<NotificationProperties.TokenId, string>, subscriptions?: NotificationProperties.Subscription[]);
+    /**
+     * Gets the flattened representation of these notification properties for serialization.
+     */
     get flatten(): NotificationProperties.Flatten;
 }
 export declare namespace NotificationProperties {
-    type TokenId = Tagged<string, 'notificationToken'>;
-    namespace TokenId {
+    /**
+     * Tagged type for notification token identifiers.
+     * Token IDs are derived from hashing the actual device tokens for security.
+     */
+    export type TokenId = Tagged<string, 'notificationToken'>;
+    export namespace TokenId {
+        /**
+         * Creates a token ID from a device token by hashing it with SHA-512.
+         * Only the first 16 characters of the hash are used as the identifier.
+         * @param token - The device push notification token
+         * @returns A hashed token ID for secure storage and lookup
+         */
         function create(token: string): TokenId;
+        /**
+         * Flattened representation of a token ID (plain string).
+         */
         type Flatten = string;
+        /**
+         * Builder for constructing TokenId instances from strings.
+         */
         const builder: Tagged.TypeBuilder<string, "notificationToken">;
     }
-    type Subscription = 'new-fine' | 'fine-reminder' | 'fine-state-change';
-    namespace Subscription {
-        const all: Subscription[];
-        const builder: ValueTypeBuilder<Subscription>;
+    /**
+     * Available notification subscription types.
+     */
+    const subscriptions: readonly ["new-fine", "fine-reminder", "fine-state-change"];
+    /**
+     * Type representing the available notification subscription options.
+     * - new-fine: Notifications when a new fine is created
+     * - fine-reminder: Reminder notifications for unpaid fines
+     * - fine-state-change: Notifications when a fine's status changes
+     */
+    export type Subscription = typeof subscriptions[number];
+    export namespace Subscription {
+        /**
+         * Readonly array of all available subscription types.
+         */
+        const all: readonly Subscription[];
+        /**
+         * Builder for constructing Subscription values from strings.
+         */
+        const builder: ValueTypeBuilder<"new-fine" | "fine-reminder" | "fine-state-change">;
     }
-    type Flatten = {
+    /**
+     * Flattened representation of notification properties for serialization.
+     */
+    export type Flatten = {
         tokens: Dictionary.Flatten<string>;
         subscriptions: Subscription[];
     };
-    class TypeBuilder implements ITypeBuilder<Flatten, NotificationProperties> {
+    /**
+     * Builder for constructing NotificationProperties from flattened data.
+     */
+    export class TypeBuilder implements ITypeBuilder<Flatten, NotificationProperties> {
+        /**
+         * Builds a NotificationProperties instance from flattened data.
+         * @param value - The flattened notification properties data
+         * @returns A new NotificationProperties instance
+         */
         build(value: Flatten): NotificationProperties;
     }
-    const builder: TypeBuilder;
+    /**
+     * Singleton builder instance for NotificationProperties.
+     */
+    export const builder: TypeBuilder;
+    export {};
 }