mgpoller

type AlertService interface {
	AlertOps(subject, message string) error
}

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 DisbursementUpdater interface {
	UpdateDisbursementStatus(sequenceID string, status string) error
	NotifyDisbursementComplete(sequenceID string) error
	NotifyDisbursementFailed(sequenceID string) error

	// NotifyCashPickupReady tells the borrower their cash is collectable and
	// quotes the MG reference number. Sent once, when MG reports
	// pending_user_transfer_complete.
	NotifyCashPickupReady(sequenceID string) error

	// NotifyRefundReceived tells the borrower their cash pickup was cancelled
	// and the funds returned. Distinct from NotifyDisbursementFailed because
	// the usual cause is the borrower cancelling in MoneyGram's own UI,
	// sometimes by mistake — the message has to say they can request again.
	NotifyRefundReceived(sequenceID string) error

	RepayVault(sequenceID string) error

	// RepayVaultAmount repays an explicit stroop amount rather than the loan
	// principal. Used for refunds, where MG may return less than we sent and
	// repaying the full principal would overdraw the treasury.
	RepayVaultAmount(sequenceID string, amountStroops int64) error
}

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
	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 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(loanID, reference string) error

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

	NotifyRepaymentReceived(loanID string) error
	NotifyRepaymentReminder(loanID string) error
	NotifyRepaymentExpired(loanID string) error
}

type RepaymentRecord struct {
	LoanID        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
}

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.
	Direction string
	Interval  time.Duration
	MaxBatch  int
	Fetcher   Fetcher[T]
	Driver    Driver[T]
	Logger    *slog.Logger
}

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