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
	// MaxAccountIndex is the highest derivation index ever recorded, counting
	// soft-deleted rows. Returns -1 when the table holds none.
	MaxAccountIndex(ctx context.Context) (int64, error)
	// EnsureAccountIndexIntegrity floors the sequence above both the recorded
	// high-water mark and the operator-supplied base, returning the index the
	// next allocation will hand out.
	EnsureAccountIndexIntegrity(ctx context.Context, base int64) (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 AirtelSummaryCursorRepository interface {
	// Get returns 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 AirtelTransactionRepository interface {
	// RecordCallback upserts an observation from a callback. A second
	// callback for the same transaction updates the existing row rather than
	// conflicting, which is what makes an intermediate-then-final pair one
	// payment instead of two.
	//
	// A row already confirmed by an enquiry is left untouched: the enquiry is
	// the authority, and a late callback must not walk a settled row back.
	RecordCallback(ctx context.Context, tx *models.AirtelTransaction) error

	// GetByPartnerID fetches one observation by the id we generated.
	GetByPartnerID(ctx context.Context, partnerTxnID string) (*models.AirtelTransaction, error)

	// GetByAirtelMoneyID fetches one observation by Airtel's receipt. Only
	// settled rows have one.
	GetByAirtelMoneyID(ctx context.Context, airtelMoneyID string) (*models.AirtelTransaction, error)

	// DuePoll returns unconfirmed observations whose NextPollAt has come due,
	// oldest first so a backlog drains in arrival order.
	DuePoll(ctx context.Context, limit int) ([]*models.AirtelTransaction, error)

	// Confirm marks an observation verified by an independent check and
	// records the receipt that check disclosed. Passing an empty
	// airtelMoneyID leaves the column alone rather than clearing it: a
	// confirmation of a failed transaction has no receipt to record, and
	// nulling one that a callback already supplied would lose the only key a
	// refund accepts.
	Confirm(ctx context.Context, partnerTxnID string, via models.AirtelTransactionConfirmVia, statusCode, airtelMoneyID, loanID string) error

	// UpdatePoll writes the next poll moment and counts the attempt.
	UpdatePoll(ctx context.Context, partnerTxnID string, at time.Time) error

	// StopPoll clears the poll moment, taking the observation out of the due
	// set for good.
	StopPoll(ctx context.Context, partnerTxnID string) error

	// UpsertFromSummary records a settled transaction the reconciliation
	// sweep found, or fills in what it learned about one already staged.
	// This is how a payment whose callback was lost is still credited.
	UpsertFromSummary(ctx context.Context, tx *models.AirtelTransaction) error

	// ListUnappliedConfirmed returns confirmed, loan-attributed observations
	// not yet converted toward a loan's repayment progress, oldest first.
	ListUnappliedConfirmed(ctx context.Context, limit int) ([]*models.AirtelTransaction, error)

	// SetAppliedStroops records the converted figure for one observation.
	SetAppliedStroops(ctx context.Context, id string, stroops int64) error

	// SumAppliedStroopsByLoan totals every observation already converted for
	// a loan.
	SumAppliedStroopsByLoan(ctx context.Context, loanID string) (int64, error)
}

type CounterpartyRepository interface {
	Create(ctx context.Context, cp *models.Counterparty) error
	GetByID(ctx context.Context, id string) (*models.Counterparty, error) // preloads Addresses
	List(ctx context.Context, kybStatus string, limit, offset int) ([]*models.Counterparty, error)
	Count(ctx context.Context, kybStatus string) (int64, error)
	ApproveKYB(ctx context.Context, id, actor string) error
	RejectKYB(ctx context.Context, id, actor string) error

	AddAddress(ctx context.Context, addr *models.CounterpartyAddress) error
	GetAddressByID(ctx context.Context, id string) (*models.CounterpartyAddress, error) // preloads Counterparty + LatestScreening
	ListAddressesByCounterparty(ctx context.Context, counterpartyID string) ([]*models.CounterpartyAddress, error)
	ListAddressesByStatus(ctx context.Context, statuses []string, limit, offset int) ([]*models.CounterpartyAddress, error)
	CountAddressesByStatus(ctx context.Context, statuses []string) (int64, error)
	ApproveAddress(ctx context.Context, id, actor, reason string) error
	RejectAddress(ctx context.Context, id, actor, reason string) error
	RevokeAddress(ctx context.Context, id, actor, reason string) error

	// ListScreeningsByAddress returns an address's full screening history,
	// newest first — the audit artefact the screening detail screen renders
	// from raw_payload, per the source design doc §14.
	ListScreeningsByAddress(ctx context.Context, addressID string) ([]*models.AddressScreening, error)

	// RecordScreening inserts the append-only screening row and updates the
	// parent address's last_screening_id/screened_at/expires_at in one
	// transaction. newAddressStatus and newOnchainState are each optional —
	// nil leaves that column untouched (a screening whose verdict didn't
	// resolve to anything new, e.g. still pending, must not silently
	// downgrade an address that was already approved).
	RecordScreening(ctx context.Context, screening *models.AddressScreening, newAddressStatus *models.CounterpartyAddressStatus, newOnchainState *models.CounterpartyAddressOnchainState, expiresAt *time.Time) error

	// ListAddressesNeedingOnchainAllow returns approved addresses whose
	// onchain_state is still "pending" — the on-chain writer's queue for
	// allow_depositor. See the source design doc §14 on why this write
	// stays a separate worker rather than something the admin web process
	// signs itself.
	ListAddressesNeedingOnchainAllow(ctx context.Context, limit int) ([]*models.CounterpartyAddress, error)

	// ListAddressesNeedingOnchainRevoke returns addresses with a recorded
	// revocation intent (RevokedAt set) whose onchain_state has not yet
	// been confirmed as revoked — the on-chain writer's queue for
	// disallow_depositor.
	ListAddressesNeedingOnchainRevoke(ctx context.Context, limit int) ([]*models.CounterpartyAddress, error)

	// SetOnchainState records what the on-chain writer actually observed
	// after submitting a transaction — the "observed state" half of the
	// intent/observed split described in RevokeAddress's doc comment.
	SetOnchainState(ctx context.Context, id string, state models.CounterpartyAddressOnchainState) error

	// MarkExpiredAddresses flips every approved address whose expires_at
	// has passed to AddressStatusExpired, and returns how many it touched.
	// One bulk statement rather than a per-row round trip, since this runs
	// on every rescreening-sweep tick. Per the source design doc §10:
	// "expired must actually be reachable — a status that can only ever be
	// set by a sweep that nobody scheduled is a status that never fires."
	MarkExpiredAddresses(ctx context.Context) (int64, 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

	// ListUnappliedConfirmed returns confirmed, loan-attributed observations
	// not yet converted toward a loan's repayment progress — the paybill
	// sweep's queue. Order is oldest first so a backlog drains in payment
	// order rather than newest-first.
	ListUnappliedConfirmed(ctx context.Context, limit int) ([]*models.MpesaTransaction, error)

	// SetAppliedStroops records the converted figure for one observation.
	// Idempotent to call twice with the same value; the sweep never calls it
	// a second time for a row that already has one, since ListUnappliedConfirmed
	// would no longer return it.
	SetAppliedStroops(ctx context.Context, id string, stroops int64) error

	// SumAppliedStroopsByLoan totals every observation already converted for
	// a loan — the authoritative "how much has this loan received toward its
	// payoff so far" figure. Safe to call repeatedly; it is a pure aggregate,
	// never a running total that could drift from the rows it is summing.
	SumAppliedStroopsByLoan(ctx context.Context, loanID string) (int64, error)
}

type Repositories struct {
	// Core repositories
	User                UserRepository
	Account             AccountRepository
	Transaction         TransactionRepository
	Mpesa               MpesaTransactionRepository
	MpesaValidation     MpesaNumberValidationRepository
	MpesaPullCursor     MpesaPullCursorRepository
	MpesaBalance        MpesaBalanceRepository
	Airtel              AirtelTransactionRepository
	AirtelSummaryCursor AirtelSummaryCursorRepository
	VaultWatchCursor    VaultWatchCursorRepository
	Counterparty        CounterpartyRepository
}

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
}

type VaultWatchCursorRepository interface {
	// Get returns the last ledger sequence the watcher has scanned through.
	Get(ctx context.Context) (uint32, error)
	// Advance moves the cursor forward to ledger.
	Advance(ctx context.Context, ledger uint32) error
}