@valentine-efagene/qshelter-common 1.0.0

package/entities/TenantAwareRepository.ts

@@ -0,0 +1,100 @@
+import { Repository, FindManyOptions, FindOneOptions, FindOptionsWhere, DeepPartial } from 'typeorm';
+
+/**
+ * Base repository with automatic tenant scoping
+ * All queries automatically filter by tenantId
+ */
+export class TenantAwareRepository<Entity extends { tenantId: number }> extends Repository<Entity> {
+    /**
+     * Find entities with automatic tenant filtering
+     */
+    async findByTenant(tenantId: number, options?: FindManyOptions<Entity>): Promise<Entity[]> {
+        return this.find({
+            ...options,
+            where: {
+                ...options?.where,
+                tenantId,
+            } as FindOptionsWhere<Entity>,
+        });
+    }
+
+    /**
+     * Find one entity with automatic tenant filtering
+     */
+    async findOneByTenant(
+        tenantId: number,
+        options?: FindOneOptions<Entity>
+    ): Promise<Entity | null> {
+        return this.findOne({
+            ...options,
+            where: {
+                ...options?.where,
+                tenantId,
+            } as FindOptionsWhere<Entity>,
+        });
+    }
+
+    /**
+     * Count entities with automatic tenant filtering
+     */
+    async countByTenant(tenantId: number, options?: FindManyOptions<Entity>): Promise<number> {
+        return this.count({
+            ...options,
+            where: {
+                ...options?.where,
+                tenantId,
+            } as FindOptionsWhere<Entity>,
+        });
+    }
+
+    /**
+     * Create and save entity with automatic tenantId
+     */
+    async createForTenant(tenantId: number, entityData: DeepPartial<Entity>): Promise<Entity> {
+        const entity = this.create({
+            ...entityData,
+            tenantId,
+        } as DeepPartial<Entity>);
+        return this.save(entity);
+    }
+
+    /**
+     * Update entity with tenant validation
+     */
+    async updateForTenant(
+        tenantId: number,
+        id: number,
+        entityData: DeepPartial<Entity>
+    ): Promise<Entity> {
+        const entity = await this.findOneByTenant(tenantId, { where: { id } as any });
+        if (!entity) {
+            throw new Error(`Entity with ID ${id} not found for tenant ${tenantId}`);
+        }
+        Object.assign(entity, entityData);
+        return this.save(entity);
+    }
+
+    /**
+     * Delete entity with tenant validation
+     */
+    async deleteForTenant(tenantId: number, id: number): Promise<void> {
+        const entity = await this.findOneByTenant(tenantId, { where: { id } as any });
+        if (!entity) {
+            throw new Error(`Entity with ID ${id} not found for tenant ${tenantId}`);
+        }
+        await this.remove(entity);
+    }
+
+    /**
+     * Soft delete entity with tenant validation
+     */
+    async softDeleteForTenant(tenantId: number, id: number): Promise<void> {
+        const entity = await this.findOneByTenant(tenantId, { where: { id } as any });
+        if (!entity) {
+            throw new Error(`Entity with ID ${id} not found for tenant ${tenantId}`);
+        }
+        await this.softRemove(entity);
+    }
+}
+
+export default TenantAwareRepository;

package/entities/amenity.entity.ts

@@ -0,0 +1,10 @@
+import { Column, Entity } from 'typeorm';
+import { BaseEntity } from './BaseEntity';
+
+@Entity({ name: 'amenity' })
+export class Amenity extends BaseEntity {
+  @Column({
+    nullable: false
+  })
+  name: string
+}

package/entities/common.entity.ts

@@ -0,0 +1,46 @@
+import { User } from './user.entity';
+import {
+  ManyToOne,
+  JoinColumn,
+  Column,
+} from 'typeorm';
+import { DocumentStatus } from '../types/common.type';
+import { AbstractTenantAwareEntity } from './common.pure.entity';
+
+export abstract class AbstractBaseReviewableEntity extends AbstractTenantAwareEntity {
+  @ManyToOne(() => User, { eager: true })
+  @JoinColumn({ name: 'reviewed_by' })
+  reviewer: User;
+
+  @Column({ type: 'timestamp', nullable: true })
+  reviewedAt: string;
+}
+
+export abstract class AbstractBaseDocumentEntity extends AbstractBaseReviewableEntity {
+  @Column({
+    type: 'enum',
+    enum: DocumentStatus,
+    default: DocumentStatus.PENDING,
+  })
+  status: DocumentStatus;
+
+  @Column({ nullable: true })
+  comment: string;
+
+  @Column({ type: 'text', nullable: false })
+  url: string;
+
+  @Column({ nullable: true })
+  description: string;
+
+  @Column({ nullable: true })
+  name: string;
+
+  @Column({ nullable: false, comment: "In bytes" })
+  size: number
+}
+
+export abstract class AbstractBaseMediaEntity extends AbstractBaseDocumentEntity {
+  // @Column()
+  // mimeType: string;
+}

package/entities/common.pure.entity.ts

@@ -0,0 +1,36 @@
+
+import { CreateDateColumn, DeleteDateColumn, PrimaryGeneratedColumn, UpdateDateColumn, Column, Index, ManyToOne, JoinColumn } from "typeorm";
+import { Tenant } from "./tenant.entity";
+
+
+export abstract class AbstractBaseEntity {
+    @PrimaryGeneratedColumn()
+    id: number;
+
+    @CreateDateColumn({ type: 'timestamp', default: () => 'CURRENT_TIMESTAMP' })
+    createdAt: Date;
+
+    @UpdateDateColumn({
+        type: 'timestamp',
+        default: () => 'CURRENT_TIMESTAMP',
+        onUpdate: 'CURRENT_TIMESTAMP',
+    })
+    updatedAt: Date;
+
+    @DeleteDateColumn({ nullable: true, default: null })
+    deletedAt: Date;
+}
+
+/**
+ * Tenant-aware base entity
+ * All entities that need tenant isolation should extend this
+ */
+export abstract class AbstractTenantAwareEntity extends AbstractBaseEntity {
+    @ManyToOne(() => Tenant, { onDelete: 'CASCADE' })
+    @JoinColumn({ name: 'tenant_id' })
+    tenant: Tenant;
+
+    @Column({ name: 'tenant_id' })
+    @Index()
+    tenantId: number;
+}

package/entities/index.ts

@@ -0,0 +1,27 @@
+export * from './BaseEntity';
+export * from './TenantAwareEntity';
+export * from './TenantAwareRepository';
+export * from './amenity.entity';
+export * from './common.entity';
+export * from './common.pure.entity';
+export * from './mortgage-document.entity';
+export * from './mortgage-downpayment-installment.entity';
+export * from './mortgage-downpayment-payment.entity';
+export * from './mortgage-downpayment.entity';
+export * from './mortgage-step.entity';
+export * from './mortgage-type.entity';
+export * from './mortgage.entity';
+export * from './password_reset_tokens.entity';
+export * from './permission.entity';
+export * from './property-document.entity';
+export * from './property-media.entity';
+export * from './property.entity';
+export * from './refresh_token.entity';
+export * from './role.entity';
+export * from './settings.entity';
+export * from './social.entity';
+export * from './tenant.entity';
+export * from './transaction.entity';
+export * from './user.entity';
+export * from './user_suspensions.entity';
+export * from './wallet.entity';

package/entities/mortgage-document.entity.ts

@@ -0,0 +1,37 @@
+import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
+import { AbstractBaseReviewableEntity } from './common.entity';
+import { Mortgage } from './mortgage.entity';
+import { User } from './user.entity';
+
+@Entity({ name: 'mortgage_document' })
+export class MortgageDocument extends AbstractBaseReviewableEntity {
+    @ManyToOne(() => Mortgage, (mortgage) => mortgage.documents, { onDelete: 'CASCADE' })
+    @JoinColumn({ name: 'mortgage_id' })
+    mortgage: Mortgage;
+
+    @Column({ nullable: true })
+    mortgageId: number;
+
+    @Column()
+    fileName: string;
+
+    // Allow null URLs for template/placeholder documents created from mortgage type templates.
+    @Column({ nullable: true })
+    url: string;
+
+    // Flag to mark this document as a template/placeholder (not yet uploaded). Template docs typically have a name but no URL.
+    @Column({ default: false })
+    isTemplate: boolean;
+
+    @Column({ nullable: true })
+    mimeType: string;
+
+    @ManyToOne(() => User, { nullable: true })
+    @JoinColumn({ name: 'uploaded_by' })
+    uploadedBy: User;
+
+    @Column({ nullable: true })
+    uploadedById: number;
+}
+
+export default MortgageDocument;

package/entities/mortgage-downpayment-installment.entity.ts

@@ -0,0 +1,40 @@
+import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
+import { AbstractBaseEntity } from './common.pure.entity';
+import { MortgageDownpaymentPlan } from './mortgage-downpayment.entity';
+
+export enum InstallmentStatus {
+    PENDING = 'PENDING',
+    PARTIAL = 'PARTIAL',
+    PAID = 'PAID',
+    LATE = 'LATE',
+}
+
+@Entity({ name: 'mortgage_downpayment_installment' })
+export class MortgageDownpaymentInstallment extends AbstractBaseEntity {
+    @ManyToOne(() => MortgageDownpaymentPlan, (p) => p.installments, { onDelete: 'CASCADE' })
+    @JoinColumn({ name: 'plan_id' })
+    plan: MortgageDownpaymentPlan;
+
+    @Column({ nullable: true })
+    planId: number;
+
+    @Column({ type: 'int' })
+    sequence: number;
+
+    @Column({ type: 'date' })
+    dueDate: Date;
+
+    @Column({ type: 'double precision' })
+    amountDue: number;
+
+    @Column({ type: 'double precision', default: 0 })
+    amountPaid: number;
+
+    @Column({ type: 'timestamp', nullable: true })
+    paidAt: Date;
+
+    @Column({ type: 'enum', enum: InstallmentStatus, default: InstallmentStatus.PENDING })
+    status: InstallmentStatus;
+}
+
+export default MortgageDownpaymentInstallment;

package/entities/mortgage-downpayment-payment.entity.ts

@@ -0,0 +1,61 @@
+import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
+import { AbstractBaseEntity } from './common.pure.entity';
+import { MortgageDownpaymentPlan } from './mortgage-downpayment.entity';
+import { MortgageDownpaymentInstallment } from './mortgage-downpayment-installment.entity';
+import { User } from './user.entity';
+
+// Legacy enum - kept for backward compatibility
+export enum DownpaymentPaymentStatus {
+    PENDING = 'PENDING',
+    COMPLETED = 'COMPLETED',
+    FAILED = 'FAILED',
+}
+
+// Payment state for FSM tracking
+export enum PaymentState {
+    INITIATED = 'INITIATED',
+    COMPLETED = 'COMPLETED',
+    FAILED = 'FAILED',
+}
+
+@Entity({ name: 'mortgage_downpayment_payment' })
+export class MortgageDownpaymentPayment extends AbstractBaseEntity {
+    @ManyToOne(() => MortgageDownpaymentPlan, { onDelete: 'CASCADE' })
+    @JoinColumn({ name: 'plan_id' })
+    plan: MortgageDownpaymentPlan;
+
+    @Column({ nullable: true })
+    planId: number;
+
+    @ManyToOne(() => MortgageDownpaymentInstallment, { nullable: true })
+    @JoinColumn({ name: 'installment_id' })
+    installment: MortgageDownpaymentInstallment;
+
+    @Column({ nullable: true })
+    installmentId: number;
+
+    @ManyToOne(() => User, { nullable: true })
+    @JoinColumn({ name: 'payer_id' })
+    payer: User;
+
+    @Column({ nullable: true })
+    payerId: number;
+
+    @Column({ type: 'double precision' })
+    amount: number;
+
+    @Column({ nullable: true, unique: true })
+    providerReference: string;
+
+    @Column({ type: 'enum', enum: DownpaymentPaymentStatus, default: DownpaymentPaymentStatus.PENDING })
+    status: DownpaymentPaymentStatus;
+
+    // FSM state tracking
+    @Column({ type: 'enum', enum: PaymentState, default: PaymentState.INITIATED })
+    state: PaymentState;
+
+    @Column({ type: 'text', nullable: true })
+    stateMetadata: string; // JSON metadata for state transitions
+}
+
+export default MortgageDownpaymentPayment;

package/entities/mortgage-downpayment.entity.ts

@@ -0,0 +1,43 @@
+import { Column, Entity, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
+import { AbstractBaseEntity } from './common.pure.entity';
+import { Mortgage } from './mortgage.entity';
+import { MortgageDownpaymentInstallment } from './mortgage-downpayment-installment.entity';
+import { Frequency } from '../types/common.type';
+
+export enum DownpaymentPlanStatus {
+    PENDING = 'PENDING',
+    ACTIVE = 'ACTIVE',
+    COMPLETED = 'COMPLETED',
+    DEFAULTED = 'DEFAULTED',
+    CANCELLED = 'CANCELLED',
+}
+
+@Entity({ name: 'mortgage_downpayment_plan' })
+export class MortgageDownpaymentPlan extends AbstractBaseEntity {
+    @ManyToOne(() => Mortgage, { onDelete: 'CASCADE' })
+    @JoinColumn({ name: 'mortgage_id' })
+    mortgage: Mortgage;
+
+    @Column({ nullable: true })
+    mortgageId: number;
+
+    @Column({ type: 'double precision' })
+    totalAmount: number;
+
+    @Column({ type: 'int', nullable: true })
+    installmentCount: number;
+
+    @Column({ nullable: true, type: 'enum', enum: Frequency })
+    frequency: Frequency;
+
+    @Column({ type: 'date', nullable: true })
+    startDate: Date;
+
+    @Column({ type: 'enum', enum: DownpaymentPlanStatus, default: DownpaymentPlanStatus.PENDING })
+    status: DownpaymentPlanStatus;
+
+    @OneToMany(() => MortgageDownpaymentInstallment, (i) => i.plan, { cascade: true })
+    installments: MortgageDownpaymentInstallment[];
+}
+
+export default MortgageDownpaymentPlan;

package/entities/mortgage-step.entity.ts

@@ -0,0 +1,33 @@
+import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
+import { AbstractBaseReviewableEntity } from './common.entity';
+import { Mortgage } from './mortgage.entity';
+
+@Entity({ name: 'mortgage_step' })
+export class MortgageStep extends AbstractBaseReviewableEntity {
+    @ManyToOne(() => Mortgage, (mortgage) => mortgage.steps, { onDelete: 'CASCADE' })
+    @JoinColumn({ name: 'mortgage_id' })
+    mortgage: Mortgage;
+
+    @Column({ nullable: true })
+    mortgageId: number;
+
+    @Column()
+    title: string;
+
+    @Column({ type: 'text', nullable: true })
+    description: string;
+
+    // Sequence order - easier to query and reorder than relying purely on linked-list pointers
+    @Column({ type: 'int', default: 0 })
+    sequence: number;
+
+    // We use `sequence` for ordering. Removed linked-list pointer fields (nextStep/nextStepId) to reduce redundancy.
+
+    @Column({ default: false })
+    isOptional: boolean;
+
+    @Column({ nullable: true })
+    completedAt: Date;
+}
+
+export default MortgageStep;

package/entities/mortgage-type.entity.ts

@@ -0,0 +1,31 @@
+import { Column, Entity } from 'typeorm';
+import { AbstractBaseReviewableEntity } from './common.entity';
+
+/**
+ * MortgageType stores named mortgage configurations. Examples: 'Standard Fixed', 'Interest Only', 'Buy-to-Let'.
+ * - defaultSteps: array of step templates { title, description?, sequence?, isOptional? }
+ * - requiredDocuments: array of document templates { name, required: boolean }
+ * - config: free-form JSON for additional settings
+ */
+@Entity({ name: 'mortgage_type' })
+export class MortgageType extends AbstractBaseReviewableEntity {
+    @Column()
+    name: string;
+
+    @Column({ nullable: true })
+    slug: string;
+
+    @Column({ type: 'text', nullable: true })
+    description?: string;
+
+    @Column({ type: 'json', nullable: true })
+    defaultSteps?: any[];
+
+    @Column({ type: 'json', nullable: true })
+    requiredDocuments?: any[];
+
+    @Column({ type: 'json', nullable: true })
+    config?: any;
+}
+
+export default MortgageType;

package/entities/mortgage.entity.ts

@@ -0,0 +1,89 @@
+import { Column, Entity, JoinColumn, ManyToOne, OneToMany, OneToOne } from 'typeorm';
+import { AbstractBaseReviewableEntity } from './common.entity';
+import { Property } from './property.entity';
+import { User } from './user.entity';
+import MortgageDocument from './mortgage-document.entity';
+import MortgageStep from './mortgage-step.entity';
+import { MortgageType } from './mortgage-type.entity';
+import { MortgageDownpaymentPlan } from './mortgage-downpayment.entity';
+import { MortgageState } from '../types/mortgage-fsm.types';
+
+// Legacy enum - kept for backward compatibility
+export enum MortgageStatus {
+    DRAFT = 'DRAFT',
+    PENDING = 'PENDING',
+    ACTIVE = 'ACTIVE',
+    COMPLETED = 'COMPLETED',
+    CANCELLED = 'CANCELLED',
+}
+
+@Entity({ name: 'mortgage' })
+export class Mortgage extends AbstractBaseReviewableEntity {
+    @ManyToOne(() => Property, (property) => property.mortgages, { onDelete: 'CASCADE' })
+    @JoinColumn({ name: 'property_id' })
+    property: Property;
+
+    @Column({ nullable: true })
+    propertyId: number;
+
+    @ManyToOne(() => User, { nullable: true })
+    @JoinColumn({ name: 'borrower_id' })
+    borrower: User;
+
+    @Column({ nullable: true })
+    borrowerId: number;
+
+    @Column({ type: 'double precision', nullable: true })
+    principal: number;
+
+    @Column({ type: 'double precision', nullable: true })
+    downPayment: number;
+
+    @Column({ type: 'int', nullable: true })
+    termMonths: number;
+
+    @Column({ type: 'double precision', nullable: true })
+    interestRate: number;
+
+    @Column({ type: 'double precision', nullable: true })
+    monthlyPayment: number;
+
+    @Column({ type: 'enum', enum: MortgageStatus, default: MortgageStatus.DRAFT })
+    status: MortgageStatus;
+
+    // FSM State - Primary state tracking
+    @Column({ type: 'varchar', default: MortgageState.DRAFT })
+    state: string; // Using string to store MortgageState enum values
+
+    // FSM Metadata - Stores transition history and context
+    @Column({ type: 'text', nullable: true })
+    stateMetadata: string; // JSON string containing last transition info
+
+    @OneToMany(() => MortgageDocument, (doc) => doc.mortgage)
+    documents: MortgageDocument[];
+
+    @OneToMany(() => MortgageStep, (step) => step.mortgage, { cascade: true })
+    steps: MortgageStep[];
+
+    @ManyToOne(() => MortgageType, { nullable: true })
+    @JoinColumn({ name: 'mortgage_type_id' })
+    mortgageType: MortgageType;
+
+    @Column({ nullable: true })
+    mortgageTypeId: number;
+
+    @Column({ type: 'timestamp', nullable: true })
+    lastReminderSentAt: Date;
+
+    @OneToOne(() => MortgageDownpaymentPlan, { nullable: true })
+    @JoinColumn({ name: 'downpayment_plan_id' })
+    downpaymentPlan: MortgageDownpaymentPlan;
+
+    @Column({ nullable: true })
+    downpaymentPlanId: number;
+
+    @Column({ type: 'double precision', nullable: true })
+    downPaymentPaid: number;
+}
+
+export default Mortgage;

package/entities/password_reset_tokens.entity.ts

@@ -0,0 +1,25 @@
+import { Column, DeleteDateColumn, Entity, JoinColumn, OneToOne } from 'typeorm';
+import { User } from './user.entity';
+import { BaseEntity } from './BaseEntity';
+
+@Entity({ name: 'password_reset_token' })
+export class PasswordResetToken extends BaseEntity {
+  @OneToOne(() => User, {
+    //eager: true,
+    onDelete: 'CASCADE',
+    onUpdate: 'CASCADE',
+  })
+  @JoinColumn({ name: 'user_id' })
+  user: User;
+
+  @Column({
+    nullable: true
+  })
+  tokenHash: string
+
+  @DeleteDateColumn({
+    nullable: true,
+    default: null
+  })
+  expiresAt: Date;
+}

package/entities/permission.entity.ts

@@ -0,0 +1,12 @@
+import { Column, Entity, ManyToMany } from 'typeorm';
+import { BaseEntity } from './BaseEntity';
+import { Role } from './role.entity';
+
+@Entity({ name: 'permissions' })
+export class Permission extends BaseEntity {
+  @Column({ type: 'varchar', nullable: true })
+  name: string;
+
+  @ManyToMany(() => Role, role => role.permissions)
+  roles: Role[]
+}

package/entities/property-document.entity.ts

@@ -0,0 +1,21 @@
+import {
+  Column,
+  Entity,
+  JoinColumn,
+  ManyToOne,
+} from 'typeorm';
+import { Property } from './property.entity';
+import { AbstractBaseDocumentEntity } from './common.entity';
+
+@Entity({ name: 'property-document' })
+export class PropertyDocument extends AbstractBaseDocumentEntity {
+  @ManyToOne(() => Property, (property) => property.documents, {
+    onDelete: 'CASCADE',
+    onUpdate: 'CASCADE',
+  })
+  @JoinColumn({ name: 'property_id' })
+  property: Property;
+
+  @Column()
+  propertyId: number;
+}

package/entities/property-media.entity.ts

@@ -0,0 +1,23 @@
+import {
+  Column,
+  Entity,
+  JoinColumn,
+  ManyToOne,
+} from 'typeorm';
+import { Property } from './property.entity';
+import { AbstractBaseMediaEntity } from './common.entity';
+
+@Entity({ name: 'property_media' })
+export class PropertyMedia extends AbstractBaseMediaEntity {
+  @ManyToOne(() => Property, (property) => property.media, {
+    onDelete: 'CASCADE',
+    onUpdate: 'CASCADE',
+  })
+  @JoinColumn({ name: 'property_id' })
+  property: Property;
+
+  @Column({
+    nullable: false
+  })
+  propertyId: number
+}