contracts

type AccountNotification struct {
	// UserID is the unique identifier of the user being notified.
	UserID string

	// PhoneNumber is the destination for SMS delivery (E.164 format).
	PhoneNumber string

	// FullName is used in registration welcome messages.
	FullName string

	// RemainingAttempts indicates how many PIN attempts remain before lockout.
	// Used by NotifyPINWrongAttempt.
	RemainingAttempts int

	// LockedUntil is a human-readable duration string (e.g. "15 minutes")
	// indicating how long until the lockout expires. Used by NotifyAccountLocked.
	LockedUntil string

	// Reason provides a human-readable explanation for failure notifications.
	Reason string
}

type AccountNotifier interface {
	// NotifyRegistrationSuccess informs a user that their account has been
	// created and their PIN is set.
	NotifyRegistrationSuccess(ctx context.Context, n AccountNotification) error

	// NotifyRegistrationFailed informs a user that their registration could
	// not be completed, along with a human-readable reason.
	NotifyRegistrationFailed(ctx context.Context, n AccountNotification) error

	// NotifyPINWrongAttempt warns a user that an incorrect PIN was entered
	// and includes the number of remaining attempts before lockout.
	NotifyPINWrongAttempt(ctx context.Context, n AccountNotification) error

	// NotifyAccountLocked informs a user that their account has been
	// temporarily locked due to repeated failed PIN attempts.
	NotifyAccountLocked(ctx context.Context, n AccountNotification) error

	// NotifyPINChanged confirms that the user's PIN was changed successfully.
	NotifyPINChanged(ctx context.Context, n AccountNotification) error

	// NotifyPINChangeFailed alerts a user that a PIN change attempt was
	// unsuccessful, along with the reason.
	NotifyPINChangeFailed(ctx context.Context, n AccountNotification) error

	// NotifyPINReset confirms that the user's PIN was reset successfully
	// via the recovery flow.
	NotifyPINReset(ctx context.Context, n AccountNotification) error

	// NotifyPINResetFailed alerts a user that a PIN reset attempt failed,
	// along with the reason.
	NotifyPINResetFailed(ctx context.Context, n AccountNotification) error
}

type CreateLoanRequest struct {
	UserID            string
	AccountID         string
	PrincipalAmount   int64  // In stroops
	PrincipalAsset    string // e.g. "USDC"
	InterestRateBps   int32  // Basis points
	DurationDays      int
	RepaymentSchedule string // "daily", "weekly", "bi_weekly", "monthly", "lump_sum"
}

type EligibilityRequest struct {
	UserID       string
	Amount       int64 // In stroops (USDC * 10^7)
	DurationDays int
}

type EligibilityResult struct {
	Approved     bool
	Reason       string
	MaxAmount    int64   // Maximum eligible amount in stroops
	InterestRate float64 // Annual interest rate as a decimal (e.g. 0.12 = 12%)
}

type Lender interface {
	AssessEligibility(ctx context.Context, req EligibilityRequest) (*EligibilityResult, error)
	CreateLoan(ctx context.Context, req CreateLoanRequest) (*LoanRecord, error)
	GetLoan(ctx context.Context, loanID string) (*LoanRecord, error)
	GetUserLoans(ctx context.Context, userID string) ([]*LoanRecord, error)
}

type LoanNotification struct {
	LoanID           string
	LoanNumber       string
	UserID           string
	PhoneNumber      string
	Amount           int64   // Raw amount (stroops/cents) for consumers that need it
	DisplayAmount    float64 // Display-ready (e.g. 5000.00)
	DisplayCurrency  string  // e.g. "KES", "USD"
	Status           string
	Reason           string     // For rejection notifications
	RemainingBalance float64    // For repayment confirmations
	DueDate          *time.Time // For repayment reminders
}

type LoanNotifier interface {
	NotifyLoanApproved(ctx context.Context, n LoanNotification) error
	NotifyLoanRejected(ctx context.Context, n LoanNotification) error
	NotifyLoanDisbursed(ctx context.Context, n LoanNotification) error
	NotifyLoanFailed(ctx context.Context, n LoanNotification) error
	NotifyRepaymentReceived(ctx context.Context, n LoanNotification) error
	NotifyRepaymentReminder(ctx context.Context, n LoanNotification) error
}

type LoanRecord struct {
	ID                 string
	LoanNumber         string
	UserID             string
	AccountID          string
	PrincipalAmount    int64
	PrincipalAsset     string
	InterestRateBps    int32
	TotalAmount        int64
	DurationDays       int
	RepaymentSchedule  string
	DueDate            *time.Time
	Status             string // "pending", "approved", "disbursed", "repaid", "defaulted", "cancelled"
	VaultTxHash        string
	RampProvider       string
	RampRequestID      string
	RampSequenceID     string
	RampFiatAmount     int64
	RampFiatCurrency   string
	SettlementMethod   string // "direct" or "fiat"
	DisbursementStatus string // "pending", "crypto_sent", "processing", "complete", "refund_pending", "failed"
	CreatedAt          time.Time
	UpdatedAt          time.Time
}