repository

type AccountRepository interface {
	// Create operations
	Create(ctx context.Context, account *models.Account) error
	CreateWithTx(ctx context.Context, tx *gorm.DB, account *models.Account) error

	// Read operations
	GetByID(ctx context.Context, id string) (*models.Account, error)
	GetByUserID(ctx context.Context, userID string) (*models.Account, error)
	GetByPublicKey(ctx context.Context, publicKey string) (*models.Account, error)
	GetNextAccountIndex(ctx context.Context, userID string) (int, error)
	GetNextAccountIndexWithTx(ctx context.Context, tx *gorm.DB) (int, error)
	// EnsureAccountIndexFloor advances account_index_seq so the next handed-out
	// index is >= floor. No-op when the sequence is already at or past floor.
	EnsureAccountIndexFloor(ctx context.Context, floor int64) error

	// Update operations
	Update(ctx context.Context, account *models.Account) error
	UpdateChainStatus(ctx context.Context, id string, chainStatus string) error
	Restore(ctx context.Context, id string) error

	// Delete operations
	Delete(ctx context.Context, id string) error
}

type MpesaBalanceRepository interface {
	// RecordQuery notes that a balance query for shortcode was sent, keyed on
	// the ack's OriginatorConversationID.
	RecordQuery(ctx context.Context, originatorConversationID string, shortcode uint) error
	// ResolveQuery returns the shortcode a landing result's
	// OriginatorConversationID was queried for, or ErrMpesaBalanceQueryNotFound.
	ResolveQuery(ctx context.Context, originatorConversationID string) (uint, error)
	// RecordBalance persists one parsed account balance snapshot.
	RecordBalance(ctx context.Context, shortcode uint, accountName, currency string, availableKES int64, observedAt time.Time) error
}

type MpesaNumberValidationRepository interface {
	// Get returns the cached verdict for a hash, or ErrMpesaValidationNotFound.
	Get(ctx context.Context, identityHash string) (*models.MpesaNumberValidation, error)
	// Upsert records a fresh verdict, replacing whatever was cached for the
	// same identity hash.
	Upsert(ctx context.Context, v *models.MpesaNumberValidation) error
}

type MpesaPullCursorRepository interface {
	// Get returns the cursor's current position — the exclusive start of the
	// next window to sweep.
	Get(ctx context.Context) (time.Time, error)
	// Advance moves the cursor forward to at.
	Advance(ctx context.Context, at time.Time) error
}

type MpesaTransactionRepository interface {
	// Record inserts a new observation. A duplicate TransID returns
	// ErrMpesaConflict, which is the idempotency check the controller relies
	// on.
	Record(ctx context.Context, tx *models.MpesaTransaction) error

	// GetByTransID fetches one observation by receipt, e.g. to confirm a
	// callback against.
	GetByTransID(ctx context.Context, transID string) (*models.MpesaTransaction, error)

	// GetByCheckoutID fetches one observation by its STK checkout request ID,
	// e.g. to tie a query-confirmed payment back to its callback row.
	GetByCheckoutID(ctx context.Context, checkoutID string) (*models.MpesaTransaction, error)

	// DuePoll returns unconfirmed observations whose NextPollAt has come due,
	// newest last so a stuck poll does not starve newer ones.
	DuePoll(ctx context.Context, limit int) ([]*models.MpesaTransaction, error)

	// Confirm marks an observation verified and stamps how, which is what
	// moves it out of the poller's due set.
	Confirm(ctx context.Context, transID string, via models.MpesaTransactionConfirmVia, loanID string) error

	// UpdatePoll writes the next poll moment — the cadence lives in a column,
	// not in in-memory timers, per the mgpoller reasoning.
	UpdatePoll(ctx context.Context, transID string, at time.Time) error

	// StopPoll clears the poll moment, taking the observation out of the due
	// set for good: the terminal-failure path, where re-asking Daraja can never
	// change the answer.
	StopPoll(ctx context.Context, transID string) error

	// GetLoanIDByReference resolves a loan reference to a loan ID on the shared
	// platform DB. Raw SQL rather than the credit module's repository because
	// importing the lending module would invert the layering — the same
	// reasoning mgpoller documents for its loan status constants. Returns ""
	// when the reference resolves to nothing.
	GetLoanIDByReference(ctx context.Context, reference string) (string, error)

	// SetReversalState writes the reversal lifecycle state.
	SetReversalState(ctx context.Context, transID string, state models.MpesaTransactionReversal) error

	// UpdateFields sets the mutable fields a Pull reconciler fills in —
	// unmasked MSISDN, loan attribution, confirmed status.
	UpdateFields(ctx context.Context, tx *models.MpesaTransaction) error

	// UpsertFromPull records tx if Pull is the first thing to see it — the
	// callback was lost — or updates the mutable fields on the existing row
	// when it was already recorded from a callback. This is the entry point
	// the Pull reconciler uses instead of choosing between Record and
	// UpdateFields itself.
	UpsertFromPull(ctx context.Context, tx *models.MpesaTransaction) error
}

type Repositories struct {
	// Core repositories
	User            UserRepository
	Account         AccountRepository
	Transaction     TransactionRepository
	Mpesa           MpesaTransactionRepository
	MpesaValidation MpesaNumberValidationRepository
	MpesaPullCursor MpesaPullCursorRepository
	MpesaBalance    MpesaBalanceRepository
}

type TransactionRepository interface {
	// Create operations
	Create(ctx context.Context, tx *models.Transaction) error
	BatchCreate(ctx context.Context, txs []*models.Transaction) error

	// Read operations
	GetByID(ctx context.Context, id string) (*models.Transaction, error)
	GetByStellarHash(ctx context.Context, txHash string) (*models.Transaction, error)
	ListByExternalID(ctx context.Context, externalID string) ([]*models.Transaction, error)
	GetByLoanIDAndType(ctx context.Context, loanID, txType string) (*models.Transaction, error)
	GetByLoanID(ctx context.Context, loanID string, limit, offset int) ([]*models.Transaction, error)
	GetByUserID(ctx context.Context, userID string, limit, offset int) ([]*models.Transaction, error)
	GetByStatus(ctx context.Context, status string, limit, offset int) ([]*models.Transaction, error)

	// List returns transactions newest first, filtered by status and/or type
	// when either is given. Empty filters return everything.
	List(ctx context.Context, status, txType string, limit, offset int) ([]*models.Transaction, error)

	// Count returns the number of transactions matching the same filters List applies.
	Count(ctx context.Context, status, txType string) (int64, error)

	// Update operations
	Update(ctx context.Context, tx *models.Transaction) error

	// UpdateFields writes only the supplied columns, validated against the same
	// allow-list Update uses. Preferred for partial changes to avoid rewriting
	// the text/jsonb columns and all indexes on every touch.
	UpdateFields(ctx context.Context, id string, fields map[string]any) error
}

type UserRepository interface {
	// Create operations
	Create(ctx context.Context, user *models.User) error
	CreateWithTx(ctx context.Context, tx *gorm.DB, user *models.User) error

	// Read operations
	GetByID(ctx context.Context, id string) (*models.User, error)
	GetByMobileNumber(ctx context.Context, mobileNumber string) (*models.User, error)
	GetByNationalID(ctx context.Context, nationalID string) (*models.User, error)
	GetByKYCStatus(ctx context.Context, kycStatus string, limit, offset int) ([]*models.User, error)
	GetByRole(ctx context.Context, role string, limit, offset int) ([]*models.User, error)
	List(ctx context.Context, limit, offset int) ([]*models.User, error)

	// ListFiltered returns users newest first, filtered by status and/or KYC
	// status when either is given. Empty filters return every non-deleted user.
	ListFiltered(ctx context.Context, status, kycStatus string, limit, offset int) ([]*models.User, error)

	// Count operations
	Count(ctx context.Context) (int64, error)

	// CountFiltered returns the number of users matching ListFiltered's filters.
	CountFiltered(ctx context.Context, status, kycStatus string) (int64, error)
	CountByKYCStatus(ctx context.Context, kycStatus string) (int64, error)
	CountByRole(ctx context.Context, role string) (int64, error)
	CountAdmins(ctx context.Context) (int, error)

	// Update operations
	Update(ctx context.Context, user *models.User) error

	// UpdateMobileNumber rebinds a user to a new MSISDN. Deliberately separate
	// from Update (which does not touch mobile_number) because this changes the
	// account's identity anchor — it is only used by new-SIM account recovery,
	// after the caller has verified ownership. The unique index on
	// mobile_number is the final guard against binding a number twice.
	UpdateMobileNumber(ctx context.Context, userID, mobileNumber string) error

	Restore(ctx context.Context, id string) error

	// Delete operations
	Delete(ctx context.Context, id string) error
}