@stevenkellner/team-conduct-api 2.0.17 → 2.0.19

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

@@ -1,21 +1,21 @@
 import { Flattable, ITypeBuilder } from '@stevenkellner/typescript-common-functionality';
 
 /**
- * Represents the private properties of a person.
+ * Represents the personal properties of a person within a team.
  *
- * Contains personal information that is private to the person,
- * such as their name. The last name is optional.
+ * Contains identification information such as first and last name.
  */
 export class PersonProperties implements Flattable<PersonProperties.Flatten> {
 
     /**
-     * Creates new person private properties.
+     * Creates new person properties.
+     *
      * @param firstName - The first name of the person
      * @param lastName - The last name of the person (null if not provided)
      */
     constructor(
         public firstName: string,
-        public lastName: string | null
+        public lastName: string | null = null
     ) {}
 
     /**
@@ -32,7 +32,7 @@ export class PersonProperties implements Flattable<PersonProperties.Flatten> {
 export namespace PersonProperties {
 
     /**
-     * Flattened representation of person private properties for serialization.
+     * Flattened representation of person properties for serialization.
      */
     export type Flatten = {
         firstName: string;
@@ -46,7 +46,8 @@ export namespace PersonProperties {
 
         /**
          * Builds a PersonProperties instance from flattened data.
-         * @param value - The flattened person private properties data
+         *
+         * @param value - The flattened person properties data
          * @returns A new PersonProperties instance
          */
         public build(value: Flatten): PersonProperties {

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

@@ -1,28 +1,26 @@
 import { Flattable, ITypeBuilder, UtcDate } from '@stevenkellner/typescript-common-functionality';
-import { NotificationProperties } from './NotificationProperties';
-import { User } from './User';
-import { UserRole } from './UserRole';
+import { User } from '../user/User';
+import { TeamRole } from '../team/TeamRole';
 
 /**
  * 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.
+ * and assigned team 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 joinDate - The timestamp when the person joined the team
-     * @param notificationProperties - Optional notification preferences (defaults to new NotificationProperties)
-     * @param roles - Optional array of user roles for access control (defaults to empty array)
+     * @param roles - Optional array of team roles for access control (defaults to empty array)
      */
     public constructor(
         public userId: User.Id,
         public joinDate: UtcDate,
-        public notificationProperties: NotificationProperties = new NotificationProperties(),
-        public roles: UserRole[] = []
+        public roles: TeamRole[] = []
     ) {}
 
     /**
@@ -32,7 +30,6 @@ export class PersonSignInProperties implements Flattable<PersonSignInProperties.
         return {
             userId: this.userId.flatten,
             joinDate: this.joinDate.flatten,
-            notificationProperties: this.notificationProperties.flatten,
             roles: this.roles
         };
     }
@@ -46,8 +43,7 @@ export namespace PersonSignInProperties {
     export type Flatten = {
         userId: User.Id.Flatten
         joinDate: UtcDate.Flatten,
-        notificationProperties: NotificationProperties.Flatten,
-        roles: UserRole[]
+        roles: TeamRole[]
     }
 
     /**
@@ -57,11 +53,16 @@ export namespace 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.joinDate), NotificationProperties.builder.build(value.notificationProperties), value.roles);
+            return new PersonSignInProperties(
+                User.Id.builder.build(value.userId),
+                UtcDate.builder.build(value.joinDate),
+                value.roles
+            );
         }
     }
 

package/src/types/person/index.ts

@@ -0,0 +1,3 @@
+export * from './Person';
+export * from './PersonProperties';
+export * from './PersonSignInProperties';

package/src/types/{Invitation.ts → team/Invitation.ts}

@@ -1,6 +1,6 @@
 import { BytesCoder, Flattable, ITypeBuilder, OptionalTypeBuilder, Sha512, Tagged, ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
 import { Team } from './Team';
-import { Person } from './Person';
+import { Person } from '../person/Person';
 
 /**
  * Represents an invitation to join a team.

package/src/types/team/Team.ts

@@ -0,0 +1,204 @@
+import { Flattable, Guid, ITypeBuilder, Tagged } from '@stevenkellner/typescript-common-functionality';
+import { Locale } from '../localization/Locale';
+import { Currency } from '../Currency';
+
+/**
+ * Represents a team in the system with its basic information.
+ *
+ * A team is a group of people who can track fines and payments together.
+ */
+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 logoUrl - Optional URL for the team's logo (null if not set)
+     * @param sportCategory - Optional sport category label (null if not set)
+     * @param description - Optional description of the team (null if not set)
+     * @param settings - Team configuration settings
+     */
+    public constructor(
+        public id: Team.Id,
+        public name: string,
+        public logoUrl: string | null,
+        public sportCategory: string | null,
+        public description: string | null,
+        public settings: Team.Settings
+    ) {}
+
+    /**
+     * Gets the flattened representation of this team for serialization.
+     */
+    public get flatten(): Team.Flatten {
+        return {
+            id: this.id.flatten,
+            name: this.name,
+            logoUrl: this.logoUrl,
+            sportCategory: this.sportCategory,
+            description: this.description,
+            settings: this.settings.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);
+    }
+
+    /**
+     * Configurable settings for a team.
+     */
+    export class Settings implements Flattable<Settings.Flatten> {
+
+        /**
+         * Creates new team settings.
+         *
+         * @param paypalMeLink - Optional PayPal.Me link for payment collection (null if not set)
+         * @param allowMembersToAddFines - Whether regular members can add fines
+         * @param fineVisibility - Controls which fines are visible to members
+         * @param joinRequestType - Controls how new members can join the team
+         * @param currency - The currency used for monetary fines
+         * @param locale - The locale for localized output
+         */
+        public constructor(
+            public paypalMeLink: string | null,
+            public allowMembersToAddFines: boolean,
+            public fineVisibility: Settings.FineVisibility,
+            public joinRequestType: Settings.JoinRequestType,
+            public currency: Currency,
+            public locale: Locale
+        ) {}
+
+        /**
+         * Gets the flattened representation of these settings for serialization.
+         */
+        public get flatten(): Settings.Flatten {
+            return {
+                paypalMeLink: this.paypalMeLink,
+                allowMembersToAddFines: this.allowMembersToAddFines,
+                fineVisibility: this.fineVisibility,
+                joinRequestType: this.joinRequestType,
+                currency: this.currency,
+                locale: this.locale
+            };
+        }
+    }
+
+    export namespace Settings {
+
+        /**
+         * Controls which fines are visible to team members.
+         *
+         * - 'only-own-fines': Members can only see their own fines
+         * - 'all-fines': Members can see all fines in the team
+         */
+        export type FineVisibility = 'only-own-fines' | 'all-fines';
+
+        /**
+         * Controls how new members can join the team.
+         *
+         * - 'public-link-without-approval': Anyone with the link can join directly
+         * - 'public-link-with-approval': Anyone with the link can request to join (requires approval)
+         * - 'invite-only': Only invited people can join
+         */
+        export type JoinRequestType = 'public-link-without-approval' | 'public-link-with-approval' | 'invite-only';
+
+        /**
+         * Flattened representation of team settings for serialization.
+         */
+        export type Flatten = {
+            paypalMeLink: string | null,
+            allowMembersToAddFines: boolean,
+            fineVisibility: FineVisibility,
+            joinRequestType: JoinRequestType,
+            currency: Currency,
+            locale: Locale
+        }
+
+        /**
+         * Builder for constructing Settings instances from flattened data.
+         */
+        export class TypeBuilder implements ITypeBuilder<Flatten, Settings> {
+
+            /**
+             * Builds a Settings instance from flattened data.
+             *
+             * @param value - The flattened team settings data
+             * @returns A new Settings instance
+             */
+            public build(value: Flatten): Settings {
+                return new Settings(
+                    value.paypalMeLink,
+                    value.allowMembersToAddFines,
+                    value.fineVisibility,
+                    value.joinRequestType,
+                    value.currency,
+                    value.locale
+                );
+            }
+        }
+
+        /**
+         * Singleton builder instance for Settings.
+         */
+        export const builder = new TypeBuilder();
+    }
+
+    /**
+     * Flattened representation of a Team for serialization.
+     */
+    export type Flatten = {
+        id: Id.Flatten,
+        name: string,
+        logoUrl: string | null,
+        sportCategory: string | null,
+        description: string | null,
+        settings: Settings.Flatten
+    }
+
+    /**
+     * 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),
+                value.name,
+                value.logoUrl,
+                value.sportCategory,
+                value.description,
+                Settings.builder.build(value.settings)
+            );
+        }
+    }
+
+    /**
+     * Singleton builder instance for Team.
+     */
+    export const builder = new TypeBuilder();
+}

package/src/types/{UserRole.ts → team/TeamRole.ts}

@@ -1,11 +1,11 @@
 import { ValueTypeBuilder } from '@stevenkellner/typescript-common-functionality';
-import { Localization, localizations } from './Localization';
-import { Locale } from './Locale';
+import { Localization, localizations } from '../localization/Localization';
+import { Locale } from '../localization/Locale';
 
 /**
- * Array of all available user roles.
+ * Array of all available team roles.
  */
-const userRoles = [
+const teamRoles = [
     '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
@@ -14,36 +14,38 @@ const userRoles = [
 ] as const;
 
 /**
- * Represents user roles in the application.
+ * Represents team roles in the application.
  * Defines different levels of permissions for team members.
  */
-export type UserRole = typeof userRoles[number];
+export type TeamRole = typeof teamRoles[number];
+
+export namespace TeamRole {
 
-export namespace UserRole {
     /**
-     * Array of all available user roles.
+     * Array of all available team roles.
      */
-    export const all: readonly UserRole[] = userRoles;
+    export const all: readonly TeamRole[] = teamRoles;
 
     /**
-     * Returns the localized, human-readable name for a user role.
-     * @param role - The user role to format
+     * Returns the localized, human-readable name for a team role.
+     *
+     * @param role - The team 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']> = {
+    export function formatted(role: TeamRole, locale: Locale): string {
+        const localizationKeyMap: Record<TeamRole, keyof (typeof localizations)[keyof typeof localizations]['teamRole']> = {
             'person-manager': 'personManager',
             'fineTemplate-manager': 'fineTemplateManager',
             'fine-manager': 'fineManager',
             'fine-can-add': 'fineCanAdd',
             'team-manager': 'teamManager'
-        }
-        return Localization.shared(locale).userRole[localizationKeyMap[role]].value();
+        };
+        return Localization.shared(locale).teamRole[localizationKeyMap[role]].value();
     }
 
     /**
-     * Builder for constructing UserRole values.
+     * Builder for constructing TeamRole values.
      */
-    export const builder = new ValueTypeBuilder<UserRole>();
+    export const builder = new ValueTypeBuilder<TeamRole>();
 }

package/src/types/team/index.ts

@@ -0,0 +1,3 @@
+export * from './Invitation';
+export * from './Team';
+export * from './TeamRole';

package/src/types/{NotificationProperties.ts → user/NotificationProperties.ts}

@@ -10,6 +10,7 @@ export class NotificationProperties implements Flattable<NotificationProperties.
 
     /**
      * 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)
      */
@@ -42,6 +43,7 @@ export namespace NotificationProperties {
         /**
          * 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
          */
@@ -70,15 +72,18 @@ export namespace NotificationProperties {
      */
     const subscriptions = [
         'new-fine',
+        'fine-changed',
         'fine-reminder',
         'fine-state-change'
     ] as const;
 
     /**
      * Type representing the available notification subscription options.
+     *
      * - new-fine: Notifications when a new fine is created
+     * - fine-changed: Notifications when a fine is updated (non-payed-state change)
      * - fine-reminder: Reminder notifications for unpaid fines
-     * - fine-state-change: Notifications when a fine's status changes
+     * - fine-state-change: Notifications when a fine's payed status changes or is deleted
      */
     export type Subscription = typeof subscriptions[number];
 
@@ -87,7 +92,7 @@ export namespace NotificationProperties {
         /**
          * Readonly array of all available subscription types.
          */
-        export const all: readonly Subscription[] = subscriptions
+        export const all: readonly Subscription[] = subscriptions;
 
         /**
          * Builder for constructing Subscription values from strings.
@@ -110,11 +115,15 @@ export namespace NotificationProperties {
 
         /**
          * Builds a NotificationProperties instance from flattened data.
+         *
          * @param value - The flattened notification properties data
          * @returns A new NotificationProperties instance
          */
         public build(value: Flatten): NotificationProperties {
-            return new NotificationProperties(Dictionary.builder(TokenId.builder, new ValueTypeBuilder<string>()).build(value.tokens), value.subscriptions);
+            return new NotificationProperties(
+                Dictionary.builder(TokenId.builder, new ValueTypeBuilder<string>()).build(value.tokens),
+                value.subscriptions
+            );
         }
     }