@stevenkellner/team-conduct-api 2.0.18 → 2.0.20

package/lib/src/firebase/Firestore.d.ts

@@ -1,201 +0,0 @@
-import { FirestoreBatch, FirestoreCollection, FirestoreDocument, UserAuthId } from '@stevenkellner/firebase-function';
-import { FirestoreScheme } from './FirestoreScheme';
-import { Fine, FineTemplate, Invitation, Person, User, Team } from '../types';
-/**
- * Accessor class for Firestore documents and collections.
- *
- * Provides type-safe access to Firestore database documents and collections
- * following the schema defined in {@link FirestoreScheme}.
- *
- * Uses a singleton pattern to ensure consistent access to the Firestore instance.
- * All methods return strongly-typed Firestore references that can be used for
- * database operations.
- *
- * @example
- * ```typescript
- * // Access a team document
- * const teamDoc = Firestore.shared.team(teamId);
- *
- * // Access a person in a team
- * const personDoc = Firestore.shared.person(teamId, personId);
- *
- * // Access all fines in a team
- * const finesCollection = Firestore.shared.fines(teamId);
- * ```
- *
- * @remarks
- * Requires {@link FirebaseConfiguration} to be configured before use.
- * All document and collection references are lazy and don't perform any
- * database operations until explicitly called.
- */
-export declare class Firestore {
-    /**
-     * Protected constructor to enforce singleton pattern.
-     * Use {@link Firestore.shared} to get an instance.
-     */
-    protected constructor();
-    /**
-     * The singleton instance of the Firestore accessor.
-     *
-     * @private
-     */
-    private static sharedInstance;
-    /**
-     * Gets the singleton instance of the Firestore accessor.
-     *
-     * Creates the instance on first access and returns the same instance
-     * on subsequent calls.
-     *
-     * @returns The singleton Firestore accessor instance
-     *
-     * @example
-     * ```typescript
-     * const firestore = Firestore.shared;
-     * const teamDoc = firestore.team(teamId);
-     * ```
-     */
-    static get shared(): Firestore;
-    /**
-     * Gets the base Firestore schema from the configured Firebase instance.
-     *
-     * Accesses the global FirebaseConfiguration to retrieve the root document
-     * reference for all database operations.
-     *
-     * @returns The base Firestore schema with typed collections
-     *
-     * @throws {Error} If FirebaseConfiguration has not been configured
-     *
-     * @private
-     */
-    protected get base(): FirestoreScheme;
-    batch(): FirestoreBatch;
-    /**
-     * Gets a reference to a team document.
-     *
-     * @param id - The unique identifier of the team
-     * @returns A typed Firestore document reference for the team
-     *
-     * @example
-     * ```typescript
-     * const teamDoc = Firestore.shared.team(teamId);
-     * const teamData = await teamDoc.get();
-     * ```
-     */
-    team(id: Team.Id): FirestoreDocument<Team>;
-    userAuth(userAuthId: UserAuthId): FirestoreDocument<{
-        userId: User.Id;
-    }>;
-    /**
-     * Gets a reference to a user document.
-     *
-     * @param id - The unique identifier of the user
-     * @returns A typed Firestore document reference for the user
-     *
-     * @example
-     * ```typescript
-     * const userDoc = Firestore.shared.user(userId);
-     * const userData = await userDoc.get();
-     * ```
-     */
-    user(id: User.Id): FirestoreDocument<User>;
-    /**
-     * Gets a reference to an invitation document.
-     *
-     * @param id - The unique identifier of the invitation
-     * @returns A typed Firestore document reference for the invitation
-     *
-     * @example
-     * ```typescript
-     * const invitationDoc = Firestore.shared.invitation(invitationId);
-     * const invitationData = await invitationDoc.get();
-     * ```
-     */
-    invitation(id: Invitation.Id): FirestoreDocument<Invitation>;
-    /**
-     * Gets a reference to the persons collection within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @returns A typed Firestore collection reference for persons in the team
-     *
-     * @example
-     * ```typescript
-     * const personsCollection = Firestore.shared.persons(teamId);
-     * const allPersons = await personsCollection.getAll();
-     * ```
-     */
-    persons(teamId: Team.Id): FirestoreCollection<{
-        [x: string]: FirestoreDocument<Person, never>;
-    }>;
-    /**
-     * Gets a reference to a specific person document within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @param id - The unique identifier of the person
-     * @returns A typed Firestore document reference for the person
-     *
-     * @example
-     * ```typescript
-     * const personDoc = Firestore.shared.person(teamId, personId);
-     * const personData = await personDoc.get();
-     * ```
-     */
-    person(teamId: Team.Id, id: Person.Id): FirestoreDocument<Person>;
-    /**
-     * Gets a reference to the fine templates collection within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @returns A typed Firestore collection reference for fine templates in the team
-     *
-     * @example
-     * ```typescript
-     * const templatesCollection = Firestore.shared.fineTemplates(teamId);
-     * const allTemplates = await templatesCollection.getAll();
-     * ```
-     */
-    fineTemplates(teamId: Team.Id): FirestoreCollection<{
-        [x: string]: FirestoreDocument<FineTemplate, never>;
-    }>;
-    /**
-     * Gets a reference to a specific fine template document within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @param id - The unique identifier of the fine template
-     * @returns A typed Firestore document reference for the fine template
-     *
-     * @example
-     * ```typescript
-     * const templateDoc = Firestore.shared.fineTemplate(teamId, templateId);
-     * const templateData = await templateDoc.get();
-     * ```
-     */
-    fineTemplate(teamId: Team.Id, id: FineTemplate.Id): FirestoreDocument<FineTemplate>;
-    /**
-     * Gets a reference to the fines collection within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @returns A typed Firestore collection reference for fines in the team
-     *
-     * @example
-     * ```typescript
-     * const finesCollection = Firestore.shared.fines(teamId);
-     * const allFines = await finesCollection.getAll();
-     * ```
-     */
-    fines(teamId: Team.Id): FirestoreCollection<{
-        [x: string]: FirestoreDocument<Fine, never>;
-    }>;
-    /**
-     * Gets a reference to a specific fine document within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @param id - The unique identifier of the fine
-     * @returns A typed Firestore document reference for the fine
-     *
-     * @example
-     * ```typescript
-     * const fineDoc = Firestore.shared.fine(teamId, fineId);
-     * const fineData = await fineDoc.get();
-     * ```
-     */
-    fine(teamId: Team.Id, id: Fine.Id): FirestoreDocument<Fine>;
-}

package/lib/src/firebase/Firestore.js

@@ -1,244 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Firestore = void 0;
-const firebase_function_1 = require("@stevenkellner/firebase-function");
-const _1 = require(".");
-/**
- * Accessor class for Firestore documents and collections.
- *
- * Provides type-safe access to Firestore database documents and collections
- * following the schema defined in {@link FirestoreScheme}.
- *
- * Uses a singleton pattern to ensure consistent access to the Firestore instance.
- * All methods return strongly-typed Firestore references that can be used for
- * database operations.
- *
- * @example
- * ```typescript
- * // Access a team document
- * const teamDoc = Firestore.shared.team(teamId);
- *
- * // Access a person in a team
- * const personDoc = Firestore.shared.person(teamId, personId);
- *
- * // Access all fines in a team
- * const finesCollection = Firestore.shared.fines(teamId);
- * ```
- *
- * @remarks
- * Requires {@link FirebaseConfiguration} to be configured before use.
- * All document and collection references are lazy and don't perform any
- * database operations until explicitly called.
- */
-class Firestore {
-    /**
-     * Protected constructor to enforce singleton pattern.
-     * Use {@link Firestore.shared} to get an instance.
-     */
-    constructor() { }
-    /**
-     * The singleton instance of the Firestore accessor.
-     *
-     * @private
-     */
-    static sharedInstance = null;
-    /**
-     * Gets the singleton instance of the Firestore accessor.
-     *
-     * Creates the instance on first access and returns the same instance
-     * on subsequent calls.
-     *
-     * @returns The singleton Firestore accessor instance
-     *
-     * @example
-     * ```typescript
-     * const firestore = Firestore.shared;
-     * const teamDoc = firestore.team(teamId);
-     * ```
-     */
-    static get shared() {
-        if (!Firestore.sharedInstance)
-            Firestore.sharedInstance = new Firestore();
-        return Firestore.sharedInstance;
-    }
-    /**
-     * Gets the base Firestore schema from the configured Firebase instance.
-     *
-     * Accesses the global FirebaseConfiguration to retrieve the root document
-     * reference for all database operations.
-     *
-     * @returns The base Firestore schema with typed collections
-     *
-     * @throws {Error} If FirebaseConfiguration has not been configured
-     *
-     * @private
-     */
-    get base() {
-        return _1.FirebaseConfiguration.shared.baseFirestoreDocument;
-    }
-    batch() {
-        return new firebase_function_1.FirestoreBatch(_1.FirebaseConfiguration.shared.firebaseFirestore);
-    }
-    /**
-     * Gets a reference to a team document.
-     *
-     * @param id - The unique identifier of the team
-     * @returns A typed Firestore document reference for the team
-     *
-     * @example
-     * ```typescript
-     * const teamDoc = Firestore.shared.team(teamId);
-     * const teamData = await teamDoc.get();
-     * ```
-     */
-    team(id) {
-        return this.base
-            .collection('teams')
-            .document(id.guidString);
-    }
-    userAuth(userAuthId) {
-        return this.base
-            .collection('userAuthIdDict')
-            .document(userAuthId.value);
-    }
-    /**
-     * Gets a reference to a user document.
-     *
-     * @param id - The unique identifier of the user
-     * @returns A typed Firestore document reference for the user
-     *
-     * @example
-     * ```typescript
-     * const userDoc = Firestore.shared.user(userId);
-     * const userData = await userDoc.get();
-     * ```
-     */
-    user(id) {
-        return this.base
-            .collection('users')
-            .document(id.value);
-    }
-    /**
-     * Gets a reference to an invitation document.
-     *
-     * @param id - The unique identifier of the invitation
-     * @returns A typed Firestore document reference for the invitation
-     *
-     * @example
-     * ```typescript
-     * const invitationDoc = Firestore.shared.invitation(invitationId);
-     * const invitationData = await invitationDoc.get();
-     * ```
-     */
-    invitation(id) {
-        return this.base
-            .collection('invitations')
-            .document(id.value);
-    }
-    /**
-     * Gets a reference to the persons collection within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @returns A typed Firestore collection reference for persons in the team
-     *
-     * @example
-     * ```typescript
-     * const personsCollection = Firestore.shared.persons(teamId);
-     * const allPersons = await personsCollection.getAll();
-     * ```
-     */
-    persons(teamId) {
-        return this.base
-            .collection('teams')
-            .document(teamId.guidString)
-            .collection('persons');
-    }
-    /**
-     * Gets a reference to a specific person document within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @param id - The unique identifier of the person
-     * @returns A typed Firestore document reference for the person
-     *
-     * @example
-     * ```typescript
-     * const personDoc = Firestore.shared.person(teamId, personId);
-     * const personData = await personDoc.get();
-     * ```
-     */
-    person(teamId, id) {
-        return this.persons(teamId)
-            .document(id.guidString);
-    }
-    /**
-     * Gets a reference to the fine templates collection within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @returns A typed Firestore collection reference for fine templates in the team
-     *
-     * @example
-     * ```typescript
-     * const templatesCollection = Firestore.shared.fineTemplates(teamId);
-     * const allTemplates = await templatesCollection.getAll();
-     * ```
-     */
-    fineTemplates(teamId) {
-        return this.base
-            .collection('teams')
-            .document(teamId.guidString)
-            .collection('fineTemplates');
-    }
-    /**
-     * Gets a reference to a specific fine template document within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @param id - The unique identifier of the fine template
-     * @returns A typed Firestore document reference for the fine template
-     *
-     * @example
-     * ```typescript
-     * const templateDoc = Firestore.shared.fineTemplate(teamId, templateId);
-     * const templateData = await templateDoc.get();
-     * ```
-     */
-    fineTemplate(teamId, id) {
-        return this.fineTemplates(teamId)
-            .document(id.guidString);
-    }
-    /**
-     * Gets a reference to the fines collection within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @returns A typed Firestore collection reference for fines in the team
-     *
-     * @example
-     * ```typescript
-     * const finesCollection = Firestore.shared.fines(teamId);
-     * const allFines = await finesCollection.getAll();
-     * ```
-     */
-    fines(teamId) {
-        return this.base
-            .collection('teams')
-            .document(teamId.guidString)
-            .collection('fines');
-    }
-    /**
-     * Gets a reference to a specific fine document within a team.
-     *
-     * @param teamId - The unique identifier of the team
-     * @param id - The unique identifier of the fine
-     * @returns A typed Firestore document reference for the fine
-     *
-     * @example
-     * ```typescript
-     * const fineDoc = Firestore.shared.fine(teamId, fineId);
-     * const fineData = await fineDoc.get();
-     * ```
-     */
-    fine(teamId, id) {
-        return this.fines(teamId)
-            .document(id.guidString);
-    }
-}
-exports.Firestore = Firestore;

package/lib/src/firebase/FirestoreScheme.d.ts

@@ -1,42 +0,0 @@
-import { FirestoreCollection, FirestoreDocument } from '@stevenkellner/firebase-function';
-import { Fine, FineTemplate, Invitation, Person, Team, User } from '../types';
-/**
- * Type definition for the Firestore database schema.
- *
- * Defines the hierarchical structure of the Firestore database:
- * - **users**: Collection of user documents indexed by User.Id
- * - **invitations**: Collection of invitation documents indexed by Invitation.Id
- * - **teams**: Collection of team documents indexed by Team.Id, each containing:
- *   - **persons**: Subcollection of person documents indexed by Person.Id
- *   - **fineTemplates**: Subcollection of fine template documents indexed by FineTemplate.Id
- *   - **fines**: Subcollection of fine documents indexed by Fine.Id
- *
- * This type ensures type-safe access to Firestore collections and documents
- * throughout the application.
- */
-export type FirestoreScheme = FirestoreDocument<never, {
-    userAuthIdDict: FirestoreCollection<{
-        [UserAuthId in string]: FirestoreDocument<{
-            userId: User.Id;
-        }>;
-    }>;
-    users: FirestoreCollection<{
-        [UserId in string]: FirestoreDocument<User>;
-    }>;
-    invitations: FirestoreCollection<{
-        [InvitationId in string]: FirestoreDocument<Invitation>;
-    }>;
-    teams: FirestoreCollection<{
-        [TeamId in string]: FirestoreDocument<Team, {
-            persons: FirestoreCollection<{
-                [PersonId in string]: FirestoreDocument<Person>;
-            }>;
-            fineTemplates: FirestoreCollection<{
-                [PersonId in string]: FirestoreDocument<FineTemplate>;
-            }>;
-            fines: FirestoreCollection<{
-                [PersonId in string]: FirestoreDocument<Fine>;
-            }>;
-        }>;
-    }>;
-}>;

package/lib/src/firebase/FirestoreScheme.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/lib/src/firebase/Messaging.d.ts

@@ -1,90 +0,0 @@
-/**
- * Represents a notification payload for Firebase Cloud Messaging.
- */
-export interface Notification {
-    /**
-     * The notification title.
-     */
-    title?: string;
-    /**
-     * The notification body text.
-     */
-    body?: string;
-    /**
-     * URL of an image to be displayed in the notification.
-     */
-    imageUrl?: string;
-}
-/**
- * Response from sending batch messages to multiple devices.
- */
-export interface BatchResponse {
-    /**
-     * Array of individual message responses.
-     */
-    responses: {
-        /**
-         * Whether the message was sent successfully.
-         */
-        success: boolean;
-        /**
-         * The message ID if successful.
-         */
-        messageId?: string;
-        /**
-         * Error information if the message failed to send.
-         */
-        error?: {
-            /**
-             * Error code identifier.
-             */
-            code: string;
-            /**
-             * Human-readable error message.
-             */
-            message: string;
-            /**
-             * Optional stack trace for debugging.
-             */
-            stack?: string;
-            /**
-             * Converts the error to a JSON object.
-             */
-            toJSON(): object;
-        };
-    }[];
-    /**
-     * Number of messages sent successfully.
-     */
-    successCount: number;
-    /**
-     * Number of messages that failed to send.
-     */
-    failureCount: number;
-}
-/**
- * Message to be sent to multiple device tokens.
- */
-export interface MulticastMessage {
-    /**
-     * Array of device registration tokens to send the message to.
-     */
-    tokens: string[];
-    /**
-     * Optional notification payload to include in the message.
-     */
-    notification?: Notification;
-}
-/**
- * Firebase Cloud Messaging service interface.
- */
-export interface Messaging {
-    /**
-     * Sends a multicast message to multiple devices.
-     *
-     * @param message - The multicast message containing tokens and notification
-     * @param dryRun - If true, validates the message without actually sending it
-     * @returns Promise resolving to batch response with success/failure details
-     */
-    sendEachForMulticast(message: MulticastMessage, dryRun?: boolean): Promise<BatchResponse>;
-}

package/lib/src/firebase/Messaging.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/lib/src/firebase/checkAuthentication.d.ts

@@ -1,38 +0,0 @@
-import { UserAuthId } from '@stevenkellner/firebase-function';
-import { Team, User, UserRole } from '../types';
-/**
- * Type representing expected user role requirements.
- *
- * Can be:
- * - A single `UserRole` (user must have this role)
- * - An array of `ExpectedUserRoles` (user must satisfy ALL requirements - logical AND)
- * - An object with `anyOf` property (user must satisfy AT LEAST ONE requirement - logical OR)
- *
- * Examples:
- * - `'admin'` - User must be admin
- * - `['member', 'treasurer']` - User must be both member AND treasurer
- * - `{ anyOf: ['admin', 'treasurer'] }` - User must be admin OR treasurer
- */
-type ExpectedUserRoles = UserRole | ExpectedUserRoles[] | {
-    anyOf: ExpectedUserRoles[];
-};
-/**
- * Validates that a user is authenticated and has the required roles for a specific team.
- *
- * Performs comprehensive authentication checks:
- * 1. Verifies the user is authenticated (rawUserId is not null)
- * 2. Checks that the user exists in the database
- * 3. Confirms the user is a member of the specified team
- * 4. Validates that the person associated with the user exists
- * 5. Ensures the person is signed in (has signInProperties)
- * 6. Verifies the person has the required roles
- *
- * @param userAuthId - The raw user authentication ID string from authentication context (null if not authenticated)
- * @param teamId - The ID of the team to check membership and roles for
- * @param roles - The expected role requirements (supports AND/OR logic via ExpectedUserRoles)
- * @returns The validated User.Id if all checks pass
- * @throws {FunctionsError} 'unauthenticated' - If rawUserId is null
- * @throws {FunctionsError} 'permission-denied' - If any validation check fails
- */
-export declare function checkAuthentication(userAuthId: UserAuthId | null, teamId: Team.Id, roles: ExpectedUserRoles): Promise<User.Id>;
-export {};

package/lib/src/firebase/checkAuthentication.js

@@ -1,64 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkAuthentication = checkAuthentication;
-const firebase_function_1 = require("@stevenkellner/firebase-function");
-const types_1 = require("../types");
-const Firestore_1 = require("./Firestore");
-/**
- * Checks if the user has the required roles according to the expected role requirements.
- *
- * @param userRoles - Array of roles the user currently has
- * @param expectedRoles - The role requirements to check against (supports AND/OR logic)
- * @returns `true` if the user satisfies the role requirements, `false` otherwise
- */
-function hasUserRoles(userRoles, expectedRoles) {
-    if (Array.isArray(expectedRoles))
-        return expectedRoles.every(expectedRole => hasUserRoles(userRoles, expectedRole));
-    else if (typeof expectedRoles === 'object' && 'anyOf' in expectedRoles)
-        return expectedRoles.anyOf.some(role => hasUserRoles(userRoles, role));
-    else
-        return userRoles.includes(expectedRoles);
-}
-/**
- * Validates that a user is authenticated and has the required roles for a specific team.
- *
- * Performs comprehensive authentication checks:
- * 1. Verifies the user is authenticated (rawUserId is not null)
- * 2. Checks that the user exists in the database
- * 3. Confirms the user is a member of the specified team
- * 4. Validates that the person associated with the user exists
- * 5. Ensures the person is signed in (has signInProperties)
- * 6. Verifies the person has the required roles
- *
- * @param userAuthId - The raw user authentication ID string from authentication context (null if not authenticated)
- * @param teamId - The ID of the team to check membership and roles for
- * @param roles - The expected role requirements (supports AND/OR logic via ExpectedUserRoles)
- * @returns The validated User.Id if all checks pass
- * @throws {FunctionsError} 'unauthenticated' - If rawUserId is null
- * @throws {FunctionsError} 'permission-denied' - If any validation check fails
- */
-async function checkAuthentication(userAuthId, teamId, roles) {
-    if (userAuthId === null)
-        throw new firebase_function_1.FunctionsError('unauthenticated', 'User is not authenticated');
-    const userAuthSnapshot = await Firestore_1.Firestore.shared.userAuth(userAuthId).snapshot();
-    if (!userAuthSnapshot.exists)
-        throw new firebase_function_1.FunctionsError('permission-denied', 'User authentication does not exist');
-    const userId = types_1.User.Id.builder.build(userAuthSnapshot.data.userId);
-    const userSnapshot = await Firestore_1.Firestore.shared.user(userId).snapshot();
-    if (!userSnapshot.exists)
-        throw new firebase_function_1.FunctionsError('permission-denied', 'User does not exist');
-    const user = types_1.User.builder.build(userSnapshot.data);
-    if (!user.teams.has(teamId))
-        throw new firebase_function_1.FunctionsError('permission-denied', 'User is not a member of the team');
-    const team = user.teams.get(teamId);
-    const personSnapshot = await Firestore_1.Firestore.shared.person(teamId, team.personId).snapshot();
-    if (!personSnapshot.exists)
-        throw new firebase_function_1.FunctionsError('permission-denied', 'Person does not exist');
-    const person = types_1.Person.builder.build(personSnapshot.data);
-    if (person.signInProperties === null)
-        throw new firebase_function_1.FunctionsError('permission-denied', 'Person is not signed in');
-    const userHasRoles = hasUserRoles(person.signInProperties.roles, roles);
-    if (!userHasRoles)
-        throw new firebase_function_1.FunctionsError('permission-denied', 'User does not have the required roles');
-    return userId;
-}

package/lib/src/firebase/index.d.ts

@@ -1,6 +0,0 @@
-export * from './FirebaseConfiguration';
-export * from './Messaging';
-export * from './checkAuthentication';
-export * from './Firestore';
-export * from './FirestoreScheme';
-export * from './pushNotification';