mgpoller

type AlertService = alerts.Service

type DepositDriver struct {
	// contains filtered or unexported fields
}

type DepositDriverDeps struct {
	Client   *moneygram.Client
	Fetcher  RepaymentFetcher
	Recorder RepaymentRecorder
	Vault    VaultRepayer
	Notifier RepaymentNotifier
	Alerts   AlertService
	Config   PollerConfig
	Logger   *slog.Logger
}

type Driver[T any] interface {
	Drive(ctx context.Context, rec T)
}

type FetchFunc[T any] func(ctx context.Context, limit int) ([]T, error)

type Fetcher[T any] interface {
	Fetch(ctx context.Context, limit int) ([]T, error)
}

type LoanFetcher interface {
	GetActiveMoneyGramLoans(ctx context.Context, limit int) ([]LoanRecord, error)
}

type LoanRecord struct {
	LoanID               string
	LoanReference        string
	SequenceID           string  // = loans.ramp_sequence_id
	MoneyGramTxID        string  // = loans.ramp_request_id
	ChildAccountIndex    uint32  // for SEP-10 memo re-derivation
	PrincipalStroops     int64   // USDC stroops to send to MG anchor
	RequestedLocalAmount float64 // KES the user typed in USSD; used for drift alerts
	HasStellarSend       bool    // true once MG.tx.stellar_transaction_id is observed
	DisbursementStatus   string
	PhoneNumber          string
	UserID               string
}

type LoanRecorder interface {
	// RecordTransactionUpdate persists the latest fields from a polled MG
	// transaction onto the loan row: amount_out, amount_out_asset, amount_fee,
	// external_transaction_id, more_info_url. Idempotent.
	RecordTransactionUpdate(ctx context.Context, loanID string, tx *stellaranchor.Transaction) error

	// RecordSendUSDC records the Stellar tx hash from a successful USDC
	// transfer to MG's anchor account, replacing the pending claim written by
	// RecordSendAttempt.
	RecordSendUSDC(ctx context.Context, loanID string, txHash string) error

	// RecordSendAttempt claims the send *before* the payment is submitted, so
	// a crash between submission and RecordSendUSDC cannot let the next tick
	// re-send. The claim makes LoanRecord.HasStellarSend true on reload.
	RecordSendAttempt(ctx context.Context, loanID string) error

	// ClearSendAttempt releases the claim. Only called when the payment
	// definitively did not move funds, so a later tick may safely retry.
	ClearSendAttempt(ctx context.Context, loanID string) error

	// RecordRefund persists the settled refund: the Stellar hash MG returned
	// the USDC in, the net stroops received, and any shortfall against the
	// principal we originally sent. Written before the vault repay so a crash
	// mid-repay leaves evidence of what came back.
	RecordRefund(ctx context.Context, loanID string, refund RefundRecord) error
}

type PaymentVerifier interface {
	TransactionSucceeded(ctx context.Context, txHash string) (bool, error)

	// PaymentsTo returns the payments in txHash addressed to destination in
	// the named asset. Direction and amount both come from the ledger: an
	// anchor's outbound refund and our own inbound payment to that anchor are
	// both "successful transactions", so success alone cannot tell them apart.
	PaymentsTo(ctx context.Context, txHash, destination, assetCode, assetIssuer string) ([]rpc.Payment, error)
}

type Poller struct {
	// contains filtered or unexported fields
}

type PollerConfig struct {
	// PollInterval is how often the ticker fires. Default 30s.
	PollInterval time.Duration

	// MaxBatch caps the number of loans evaluated per tick. Default 100.
	MaxBatch int

	// PayoutDriftAlertPct triggers an ops alert when the locked
	// amount_out diverges from RequestedLocalAmount by more than this
	// fraction (e.g. 0.02 = 2 %). Default 0.02. Set to 0 to disable.
	PayoutDriftAlertPct float64

	// RefundSettleMaxAttempts caps how many ticks a loan may sit in
	// refund_pending waiting for MoneyGram to publish the SEP-24 refunds
	// object before ops are alerted. Observed MG behaviour is that it may
	// never arrive, so without a ceiling the loan polls silently forever.
	// Default 20 (10 minutes at the default interval).
	RefundSettleMaxAttempts int

	// RefundDestination is the account MoneyGram returns funds to — the
	// wallet we withdraw from. Defaults to the client's SEP-10 account.
	RefundDestination string

	// RefundAssetIssuer is the USDC issuer a refund payment must carry.
	// Defaults to the anchor client's configured issuer.
	RefundAssetIssuer string

	// DepositPollInterval is how often the deposit runner asks for rows whose
	// next poll is due. Default 60s. This is not how often any one deposit is
	// polled — that is the backoff below.
	DepositPollInterval time.Duration

	// DepositMaxBatch caps repayments evaluated per tick. Default 100.
	DepositMaxBatch int

	// DepositActiveBackoff is the gap between polls once the borrower has
	// engaged — committed in the webview, or the transaction is moving through
	// MoneyGram. Default 2m.
	DepositActiveBackoff time.Duration

	// DepositIdleBackoff is the gap between polls while the borrower has not
	// opened the link. This is most of the window, and the reason cadence is
	// column-driven at all. Default 30m.
	DepositIdleBackoff time.Duration

	// DepositReminderBefore is how long before expiry the single reminder SMS
	// goes out. Default 24h. Zero disables the reminder.
	DepositReminderBefore time.Duration

	// DepositVaultMaxAttempts is how many times the treasury-to-vault leg may
	// fail before ops are alerted. Default 10. The borrower's USDC is already
	// on the treasury by this point, so the retry never stops — the ceiling
	// decides when a human is told, not when to give up.
	DepositVaultMaxAttempts int

	// DepositVaultRetryBackoff is the gap between vault-leg retries once the
	// ceiling has been passed. Default 1h. Slower than DepositActiveBackoff
	// because past the ceiling the cause is unlikely to clear on its own, and
	// hammering a broken RPC every two minutes helps nobody.
	DepositVaultRetryBackoff time.Duration
}

type PollerDeps struct {
	Client       *moneygram.Client
	Fetcher      LoanFetcher
	Recorder     LoanRecorder
	Disbursement contracts.DisbursementUpdater
	Treasury     offramp.TreasuryTransfer
	Verifier     PaymentVerifier
	Alerts       AlertService
	Config       PollerConfig
	Logger       *slog.Logger
}

type RefundRecord struct {
	// TxHash is the Stellar transaction the refund arrived in. When MG splits
	// a refund across several payments this is the last one; the amount is
	// always the total.
	TxHash string

	// NetStroops is what actually landed, summed from the refund payments as
	// they appear on-ledger rather than from the anchor's reported amounts.
	NetStroops int64

	// ShortfallStroops is PrincipalStroops - NetStroops when MG returned less
	// than we sent, otherwise zero. Non-zero means the treasury absorbed the
	// difference and the loan needs a human to settle it.
	ShortfallStroops int64
}

type RepaymentFetcher interface {
	GetDueRepayments(ctx context.Context, limit int) ([]RepaymentRecord, error)
}

type RepaymentNotifier interface {
	// NotifyRepaymentReference carries MoneyGram's deposit reference once the
	// borrower has committed in the webview. Without it they reach the counter
	// with nothing to quote.
	NotifyRepaymentReference(ctx context.Context, loanID, reference string) error

	// NotifyRepaymentMoreInfo carries MoneyGram's transaction page instead,
	// for the case where no reference has been issued. See sendPayInstructions.
	NotifyRepaymentMoreInfo(ctx context.Context, loanID string) error

	NotifyRepaymentReceived(ctx context.Context, loanID string) error
	NotifyRepaymentReminder(ctx context.Context, loanID string) error
	NotifyRepaymentExpired(ctx context.Context, loanID string) error

	// NotifyLoanRepaid confirms the treasury-to-vault leg confirmed and the
	// loan is closed — sent once, right after MarkSettled records it.
	NotifyLoanRepaid(ctx context.Context, loanID string) error
}

type RepaymentRecord struct {
	LoanID        string
	LoanReference string
	SequenceID    string // = loans.ramp_sequence_id; the handle notifications use
	MoneyGramTxID string // = loans.repayment_mg_tx_id

	// ChildAccountIndex re-derives the SEP-10 memo. The deposit was created
	// under a JWT scoped to this borrower, which is what attributes the
	// MoneyGram transaction to them — not any field on the transaction.
	ChildAccountIndex uint32

	// BorrowerAddress is the child account's Stellar address, carried onto the
	// vault's Repaid event by repay_for. Attribution only: the treasury is the
	// payer and the borrower authorizes nothing.
	BorrowerAddress string

	// PayoffStroops is the payoff quoted and locked at initiation. Borrow-index
	// movement since then does not change what the borrower owes.
	PayoffStroops int64

	// VaultAttempts is how many times the treasury-to-vault leg has already
	// failed for this loan. Durable, so a restart does not reset the ceiling.
	VaultAttempts int

	// ReferenceSent marks the one SMS carrying MoneyGram's deposit reference,
	// which is what the borrower quotes at the counter to pay in.
	ReferenceSent bool

	RepaymentStatus string
	ExpiresAt       time.Time
	ReminderSent    bool
	PhoneNumber     string
	UserID          string
}

type RepaymentRecorder interface {
	// RecordDepositUpdate persists the latest fields from a polled deposit
	// transaction. Idempotent.
	RecordDepositUpdate(ctx context.Context, loanID string, tx *stellaranchor.Transaction) error

	// MarkFundsReceived records the borrower's cash reaching the treasury as
	// USDC. loans.status deliberately does not move until the vault leg lands.
	MarkFundsReceived(ctx context.Context, loanID string, tx *stellaranchor.Transaction) error

	// MarkSettled records the confirmed treasury-to-vault leg. This is the
	// transition that flips loans.status to repaid.
	MarkSettled(ctx context.Context, loanID string, vaultTxHash string) error

	// MarkExpired releases the quote lock after the cash-in window elapsed
	// without the borrower paying, returning the loan to its prior status.
	MarkExpired(ctx context.Context, loanID string) error

	// MarkFailed ends the rail before any funds moved. Never used for a failed
	// vault leg: money already on the treasury stays at funds_received so
	// reconciliation keeps retrying.
	MarkFailed(ctx context.Context, loanID string, reason string) error

	// MarkReminderSent is written before the SMS, so a failed send is not
	// retried on every tick. It records a notification, not a movement of
	// money, which is why it needs its own marker.
	MarkReminderSent(ctx context.Context, loanID string) error

	// ScheduleNextPoll sets when this repayment should next be looked at.
	ScheduleNextPoll(ctx context.Context, loanID string, at time.Time) error

	// MarkReferenceSent stamps the deposit-reference SMS before it is sent, so
	// a failing provider is not retried on every tick for the rest of the
	// window. Same reasoning as MarkReminderSent.
	MarkReferenceSent(ctx context.Context, loanID string) error

	// RecordVaultAttempt increments the failed-vault-leg counter. Written
	// after each failure so the count survives a restart, which is what makes
	// the escalation ceiling meaningful.
	RecordVaultAttempt(ctx context.Context, loanID string, attempts int) error

	// MarkVaultOutcomeUnknown parks a repayment whose repay_for may have
	// landed, taking it out of the due set until ops verify it on-chain.
	MarkVaultOutcomeUnknown(ctx context.Context, loanID string) error
}

type Runner[T any] struct {
	// contains filtered or unexported fields
}

type RunnerDeps[T any] struct {
	// Direction names the runner in its logs, which is what tells two runners
	// in the same process apart. It also doubles as the advisory-lock key
	// when DB is set, so it must stay unique across every runner sharing that
	// database — which every runner in this package already needs regardless.
	Direction string
	Interval  time.Duration
	MaxBatch  int
	Fetcher   Fetcher[T]
	Driver    Driver[T]
	Logger    *slog.Logger

	// DB gates each tick on a Postgres advisory lock keyed by Direction, so a
	// second replica of the same runner skips its work instead of racing the
	// first. Nil (the default) runs unguarded, which is correct today — see
	// poll's doc comment — and is what every existing runner construction
	// site keeps doing unless it opts in.
	DB *sql.DB

	// LoanID names the loan a record belongs to. When set, each record is
	// driven under its own root span and a context carrying loan_id, so its
	// trace and log lines are findable by loan. Optional.
	LoanID func(T) string

	// LoanReference names the loan's human-facing reference, attached beside
	// loan_id so ops alerts can show it. Optional.
	LoanReference func(T) string
}

type VaultRepayer interface {
	RepayForBorrower(ctx context.Context, loanID, borrowerAddress string, amountStroops int64) (txHash string, err error)
}