ussd

type BioUpdate struct {
	BirthDate  string // YYYY-MM-DD
	Address    string
	City       string
	PostalCode string
}

type CarrierRepaymentPrompter interface {
	// PromptRepaymentVia pushes a prompt for the full payoff on the named
	// cash-in provider. The provider id is the registry's own ("mpesa",
	// "airtel"); an unregistered one is an error, never a silent fallback.
	PromptRepaymentVia(ctx context.Context, loanID, phoneNumber, providerID string) error
}

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

type HandlerDeps struct {
	SessionManager  *SessionManager
	MenuRegistry    *MenuRegistry
	UserService     UserService
	LoanService     LoanService
	RateService     RateService
	PINService      PINService
	AccountNotifier contracts.AccountNotifier
	LoanNotifier    contracts.LoanNotifier

	// RepayPaybill is the mobile-money paybill number shown on the repay
	// screens — the configured M-Pesa collection shortcode. Blank hides the
	// mobile-money option entirely.
	RepayPaybill string

	// MpesaPrompter enables the STK prompt rail when the loan service
	// satisfies RepaymentPrompter.
	MpesaPrompter bool

	// AirtelPrompter enables the Airtel Money prompt rail when the loan
	// service satisfies CarrierRepaymentPrompter. Separate from
	// MpesaPrompter because the rails are enabled by separate integrations
	// and either can be live without the other.
	AirtelPrompter bool
}

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

type LoanApproval struct {
	Approved     bool
	Reason       string
	InterestRate float64
}

type LoanProductConfig struct {
	ProductID         string // UUID of the loan product record.
	MinAmountCents    int64  // Minimum loan in fiat cents (e.g. 50000 = KES 500).
	MaxAmountCents    int64  // Maximum auto-approved loan in fiat cents (e.g. 300000 = KES 3,000).
	Currency          string // ISO 4217 currency code (e.g. "KES").
	DurationDays      int    // Fixed loan term in days (e.g. 30).
	RepaymentSchedule string // Repayment cadence (e.g. "lump_sum").
	InterestRateBps   int32  // Fallback annual rate in basis points; vault APR takes precedence.
	OriginationFeeBps int32  // One-off fee in bps (1 bps = 0.01 %). Zero when product has none.
}

type LoanRequest struct {
	UserID          string
	AccountID       string // Database UUID of the user's account record.
	StellarAddress  string // Stellar public key for vault borrow recipient.
	ProductID       string // Loan product ID from LoanProductConfig.
	PhoneNumber     string
	RecipientName   string
	NationalID      string
	CountryCode     string
	NetworkCode     string
	NetworkName     string
	PrincipalAmount int64 // USDC amount in stroops (converted from local currency).
	PrincipalAsset  string
	DurationDays    int
	RepaymentSched  string
	LocalAmount     int64   // Local currency amount in cents (e.g. KES cents).
	LocalCurrency   string  // ISO 4217 currency code (e.g. "KES").
	ConversionRate  float64 // YellowCard buy rate at quote time (e.g. 153.50).

	// Off-ramp routing — selects the provider (mobile money vs cash pickup).
	// Empty defaults to mobile money for back-compat with menus that don't
	// expose the cash-pickup branch yet.
	PayoutMethod string

	// Cash-pickup-only KYC fields (MoneyGram). Ignored by mobile-money flows.
	FirstName          string
	LastName           string
	BirthDate          string // ISO-8601 (YYYY-MM-DD)
	Address            string
	PostalCode         string
	City               string
	AddressCountryCode string
	ChildAccountIndex  uint32 // per-user Stellar derivation index for SEP-10 memo
}

type LoanService interface {
	// GetUserLoans returns all loans for the given user, formatted for USSD display.
	GetUserLoans(ctx context.Context, userID string) ([]any, error)

	// RequestLoan orchestrates the full loan disbursement cycle.
	RequestLoan(ctx context.Context, req *LoanRequest) (any, error)

	// CheckLoanEligibility checks whether the user qualifies for the requested amount.
	CheckLoanEligibility(ctx context.Context, userID string, amount int64, duration int) (*LoanApproval, error)

	// GetProductConfig returns the active loan product parameters used by the
	// USSD flow (limits, duration, schedule). Returns nil when no product is configured.
	GetProductConfig() *LoanProductConfig

	// GetRepaymentQuote returns the amount currently owed on a loan, in both
	// USDC stroops and local currency cents. The USDC figure is derived from
	// the vault's current borrow_index relative to the index at origination;
	// the local figure applies the latest FX. Returns an error (hard-fail —
	// no stale fallback) when the vault or FX is unavailable.
	GetRepaymentQuote(ctx context.Context, loanID string) (*RepaymentQuote, error)

	// InitiateRepayment opens a MoneyGram cash deposit for the loan.
	//
	// It returns as soon as the request is accepted, not when the deposit
	// exists. Quoting, SEP-10 authentication, SEP-24 initiation, link
	// shortening and the SMS together took over fifteen seconds against the
	// sandbox — past the point Africa's Talking abandons a USSD session, so
	// waiting for them leaves the borrower's screen dead before it renders.
	//
	// Everything the borrower needs arrives by SMS: the interactive link on
	// success, a failure notice otherwise. Nothing on the USSD screen depends
	// on the outcome, which is what makes returning early honest rather than a
	// shortcut. An error here means the request was refused outright.
	InitiateRepayment(ctx context.Context, loanID, phoneNumber string) error
}

type Localizer interface {
	// Get retrieves a localized message.
	Get(language, key string) string

	// GetWithDefault retrieves a localized message with a default fallback.
	GetWithDefault(language, key, defaultMsg string) string

	// HasKey checks if a key exists.
	HasKey(key string) bool

	// AddTranslation adds a translation.
	AddTranslation(key, language, message string)
}

type Menu struct {
	ID         string
	Title      map[string]string // Language to Title
	Options    []MenuOption
	ParentMenu string
}

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

type MenuOption struct {
	Key        string
	Label      map[string]string // Language to Label
	TargetMenu string
}

type MenuPreset interface {
	// Initialize loads menus into the registry.
	Initialize(registry *MenuRegistry)

	// GetName returns the preset name.
	GetName() string
}

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

type NetworkMapper struct{}

type NetworkMapping struct {
	MobileNetworkCode string // Telco's mobile network code (MCC + MNC) (e.g., "63902")
	MomoNetworkCode   string // Momo network code (e.g., "MPESA")
	MomoNetworkName   string // Momo Display name (e.g., "M-Pesa")
	TelcoName         string // Telco name (e.g., "Safaricom Kenya")
	Country           string // ISO country code (e.g., "KE")
}

type PINService interface {
	// SetPIN creates a new PIN for a user (during registration).
	SetPIN(ctx context.Context, userID, pin string) error

	// VerifyPIN checks the supplied PIN against the stored hash.
	// Returns (true, nil) on success, (false, nil) on wrong PIN.
	VerifyPIN(ctx context.Context, userID, pin string) (bool, error)

	// ChangePIN verifies the old PIN and sets a new one.
	ChangePIN(ctx context.Context, userID, oldPin, newPin string) error

	// ResetPIN sets a new PIN after identity verification (security questions).
	ResetPIN(ctx context.Context, userID, newPin string) error

	// IsLocked reports whether the account is locked and when the lockout expires.
	IsLocked(ctx context.Context, userID string) (bool, time.Time, error)

	// HasPIN reports whether the user has a PIN set.
	HasPIN(ctx context.Context, userID string) (bool, error)

	// SetSecurityQuestions stores hashed answers for the given questions.
	SetSecurityQuestions(ctx context.Context, userID string, questions []pin.QuestionAnswer) error

	// VerifySecurityAnswers checks the supplied answers against stored hashes.
	VerifySecurityAnswers(ctx context.Context, userID string, answers []pin.QuestionAnswer) (bool, error)

	// GetUserQuestionIDs returns the predefined question IDs the user has configured.
	GetUserQuestionIDs(ctx context.Context, userID string) ([]int, error)

	// GetRemainingAttempts returns the number of PIN attempts left before lockout.
	GetRemainingAttempts(ctx context.Context, userID string) (int, error)
}

type RateService interface {
	// GetExchangeRate returns the current sell rate for the specified currency.
	GetExchangeRate(ctx context.Context, currency string) (sellRate float64, err error)
}

type RegisterUserRequest struct {
	MobileNumber      string
	MobileCountryCode string
	NetworkCode       string
	FullName          string
	NationalID        string
	PreferredLanguage string

	// PinHash is the pre-hashed PIN (from pin.HashPIN), written atomically with
	// the user so no PIN-less account is ever persisted. Empty only when the
	// deployment has no PIN service configured.
	PinHash  string
	PinSetAt *time.Time

	// Optional SEP-9 bio (MoneyGram cash-pickup prefill). Empty when the user
	// skips the bio step. BirthDate is YYYY-MM-DD.
	BirthDate  string
	Address    string
	City       string
	PostalCode string
}

type RepaymentPrompter interface {
	// PromptRepayment pushes a prompt at the borrower's handset for the full
	// payoff. It returns once the prompt is accepted for delivery, not when
	// it is paid; an error means the push was refused outright.
	PromptRepayment(ctx context.Context, loanID, phoneNumber string) error
}

type RepaymentQuote struct {
	LoanID             string
	AmountUSDCStroops  int64   // What the borrower owes in USDC, stroops.
	AmountLocalCents   int64   // Same, converted at the FX rate below.
	LocalCurrency      string  // ISO 4217 (e.g. "KES").
	BorrowIndexAtQuote int64   // WAD scale (1e18).
	FXRate             float64 // local-per-USD at quote time.
	QuoteSource        string  // "mg_primary" | "yc_fallback" | "stale_cache".
	AsOf               time.Time
}

type Session struct {
	SessionID     string         `json:"session_id"`
	PhoneNumber   string         `json:"phone_number"`
	ServiceCode   string         `json:"service_code"`
	NetworkCode   string         `json:"network_code"`
	UserID        string         `json:"user_id,omitempty"`
	CurrentMenu   string         `json:"current_menu"`
	PreviousMenus []string       `json:"previous_menus"`
	Language      string         `json:"language"`
	Data          map[string]any `json:"data"`
	CreatedAt     time.Time      `json:"created_at"`
	UpdatedAt     time.Time      `json:"updated_at"`
}

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

type SimplifiedMenuPreset struct{}

type StandardLoanMenuPreset struct{}

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

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

type USSDProvider interface {
	// ParseRequest parses the provider-specific HTTP request into a standardized USSDRequest.
	ParseRequest(ctx context.Context, data map[string]string) (*USSDRequest, error)

	// FormatResponse formats the USSDResponse into the provider-specific response format.
	FormatResponse(ctx context.Context, response *USSDResponse) (any, error)

	// GetProviderName returns the name of the USSD provider.
	GetProviderName() string

	// ValidateRequest validates the incoming request from the provider.
	ValidateRequest(ctx context.Context, data map[string]string) error
}

type USSDRequest struct {
	SessionID    string
	PhoneNumber  string
	Input        string
	ServiceCode  string
	NetworkCode  string
	ProviderData map[string]string // For provider-specific data
}

type USSDResponse struct {
	Type    string // "CON" for continue, "END" for terminate
	Message string
}

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

type UserService interface {
	// GetUserWithAccounts retrieves a user and their associated accounts.
	GetUserWithAccounts(ctx context.Context, userIDOrPhone string) (any, []any, error)
	// RegisterUser creates a new user account based on the provided registration request.
	RegisterUser(ctx context.Context, req *RegisterUserRequest) (any, []any, error)
	// NationalIDExists reports whether a user is already registered with the
	// given national ID, so registration can reject a duplicate up front rather
	// than at the final atomic insert (the DB unique constraint is the real
	// guard; this is the fast, friendly path).
	NationalIDExists(ctx context.Context, nationalID string) (bool, error)

	// UpdateBio sets the optional SEP-9 bio fields on an existing user (added
	// post-registration via the account menu for faster cash pickup). Empty
	// fields are left unchanged; birthDate is YYYY-MM-DD.
	UpdateBio(ctx context.Context, userID string, bio BioUpdate) error

	// GetUserIDByNationalID resolves the account behind a national ID. Used by
	// new-SIM recovery to find the existing account when registration hits the
	// duplicate-ID case. Returns "" when no user holds that ID.
	GetUserIDByNationalID(ctx context.Context, nationalID string) (string, error)

	// RebindMobileNumber moves an account to the dialing SIM. Only called after
	// the caller has verified ownership via security questions — it changes the
	// account's identity anchor.
	RebindMobileNumber(ctx context.Context, userID, mobileNumber string) error
}