zod-backend/src/common/modules/notification/interfaces/notification-events.interface.ts

import { Transaction } from '~/card/entities/transaction.entity';
import { Card } from '~/card/entities/card.entity';
import { MoneyRequest } from '~/money-request/entities/money-request.entity';
import { Customer } from '~/customer/entities';
import { KycStatus } from '~/customer/enums';

/**
 * Event payload for when a transaction is created
 * Used to notify users about transactions (spending or top-ups)
 */
export interface ITransactionCreatedEvent {
  /** The transaction that was created */
  transaction: Transaction;
  
  /** The card used in the transaction (with all relations loaded) */
  card: Card;
  
  /** True if this is a top-up/load transaction, false if spending */
  isTopUp: boolean;
  
  /** True if this transaction was made by a child (requires parent notification) */
  isChildSpending: boolean;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for when a money request is created
 * Used to notify parents when their child requests money
 */
export interface IMoneyRequestCreatedEvent {
  /** The money request that was created */
  moneyRequest: MoneyRequest;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for when a money request is approved
 * Used to notify children when their money request is approved
 */
export interface IMoneyRequestApprovedEvent {
  /** The money request that was approved */
  moneyRequest: MoneyRequest;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for when a money request is declined
 * Used to notify children when their money request is declined
 */
export interface IMoneyRequestDeclinedEvent {
  /** The money request that was declined */
  moneyRequest: MoneyRequest;
  
  /** Rejection reason provided by parent */
  rejectionReason?: string;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for when KYC is approved
 * Used to notify users when their KYC verification is approved
 */
export interface IKycApprovedEvent {
  /** The customer whose KYC was approved */
  customer: Customer;
  
  /** Previous KYC status */
  previousStatus: KycStatus;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for when KYC is rejected
 * Used to notify users when their KYC verification is rejected
 */
export interface IKycRejectedEvent {
  /** The customer whose KYC was rejected */
  customer: Customer;
  
  /** Previous KYC status */
  previousStatus: KycStatus;
  
  /** Rejection reason (if provided) */
  rejectionReason?: string;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for when a card is created
 * Used to notify users when their card is successfully created
 */
export interface ICardCreatedEvent {
  /** The card that was created */
  card: Card;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for when a card is blocked
 * Used to notify users when their card is blocked
 */
export interface ICardBlockedEvent {
  /** The card that was blocked */
  card: Card;
  
  /** Previous card status */
  previousStatus: string;
  
  /** Block reason/description */
  blockReason?: string;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for when a card is reissued
 * Used to notify users when their card is reissued
 */
export interface ICardReissuedEvent {
  /** The new card that was issued */
  card: Card;
  
  /** The old card that was replaced */
  oldCardId?: string;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for when a user profile is updated
 * Used to notify users when their profile information is changed
 */
export interface IProfileUpdatedEvent {
  /** The user whose profile was updated */
  user: any;
  
  /** Fields that were updated */
  updatedFields: string[];
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for system maintenance alerts
 * Used to notify users about scheduled or unscheduled maintenance
 */
export interface IMaintenanceAlertEvent {
  /** User ID to notify (null for broadcast to all users) */
  userId: string | null;
  
  /** Maintenance message */
  message: string;
  
  /** Scheduled start time */
  startTime?: Date;
  
  /** Scheduled end time */
  endTime?: Date;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for failed transaction alerts
 * Used to notify users when a transaction fails
 */
export interface ITransactionFailedEvent {
  /** The user whose transaction failed */
  userId: string;
  
  /** Transaction details */
  transactionId?: string;
  
  /** Failure reason */
  reason: string;
  
  /** Transaction amount (if applicable) */
  amount?: number;
  
  /** When the event occurred */
  timestamp: Date;
}

/**
 * Event payload for suspicious login detection
 * Used to notify users about suspicious login attempts
 */
export interface ISuspiciousLoginEvent {
  /** The user whose account had suspicious activity */
  userId: string;
  
  /** IP address of the login attempt */
  ipAddress?: string;
  
  /** Location of the login attempt */
  location?: string;
  
  /** Device information */
  device?: string;
  
  /** When the event occurred */
  timestamp: Date;
}