config

type AfricasTalkingConfig struct {
	Username  string
	APIKey    string
	BaseURL   string
	SenderID  string // from AT_SENDER_ID (alphanumeric or shortcode)
	Shortcode string // from AT_SHORTCODE (numeric shortcode)

	// HTTPTimeout bounds a single SMS send attempt. From AT_HTTP_TIMEOUT
	// (seconds); zero when unset, leaving the adapter to apply its default.
	HTTPTimeout time.Duration
}

type AirtelConfig struct {
	// ClientID and ClientSecret are the consumer key and secret from the
	// application's Keys section, issued per environment. A non-empty
	// ClientID is the gate every Airtel code path is wired behind.
	ClientID     string
	ClientSecret string

	// Environment selects the Airtel deployment: staging or production.
	Environment airtel.Environment

	// Country and Currency populate the X-Country and X-Currency headers.
	Country  string
	Currency string

	// SigningEnabled turns on Collection v2 message signing. It must match
	// the per-application toggle under Airtel's Settings, Security: signing
	// a payload the gateway does not expect fails exactly as loudly as not
	// signing one it does.
	SigningEnabled bool

	// CallbackHMACKey is the private key from Application Settings, used to
	// recompute a callback's hash. Empty disables verification, which is
	// only correct when callback authentication is off at Airtel's end.
	CallbackHMACKey string

	// CallbackBaseURL is the public base the callback URL is built from —
	// the bare host, with no path prefix.
	CallbackBaseURL string

	// CallbackSlug is the unguessable path segment the callback URL hangs
	// off. Unlike Daraja, Airtel can sign its callbacks, but the signature is
	// optional and configured at their end, so the slug remains a control
	// rather than a nicety.
	CallbackSlug string

	// CallbackAllowedCIDRs is Airtel's egress range, enforced on the callback
	// group in production. Log-only when empty.
	//
	// Airtel does not publish this list. Until their support supplies it,
	// production is blocked on it in the same way Daraja's is.
	CallbackAllowedCIDRs []string

	// EnquiryDelay is the wait after a payment before the first enquiry.
	// Airtel documents three minutes; see EnquiryDelayFloor.
	EnquiryDelay time.Duration

	// PollInterval is how often an unresolved observation is re-enquired
	// after the first attempt.
	PollInterval time.Duration

	// MaxAttempts is how many enquiry rounds an unresolved observation gets
	// before a human is told, not how long the payer has.
	MaxAttempts int

	// SummarySweepInterval is how often the Transactions Summary reconciler
	// walks the settled window.
	SummarySweepInterval time.Duration

	// ReferencePrefix is the loan-reference namespace, loaded from the same
	// LOAN_REFERENCE_PREFIX variable as the M-Pesa rail.
	ReferencePrefix string

	// PromptAmountKES overrides the USSD push amount with a fixed whole-KES
	// figure instead of the quoted payoff, for exercising the rail against a
	// real handset on staging. Zero means use the quoted payoff. Setting it
	// in production is a boot error.
	PromptAmountKES int

	// SettlementMode decides how KES collected in the Airtel merchant wallet
	// becomes USDC. Only "otc" is built, matching the M-Pesa rail.
	SettlementMode string
}

type AuthConfig struct {
	JWTSecret           string
	JWTExpiration       time.Duration
	JWTRefreshWindow    time.Duration
	ChallengeExpiration time.Duration
	PINLockoutDuration  time.Duration // from PIN_LOCKOUT_SECONDS (default 900 = 15min)
}

type ComplianceConfig struct {
	EllipticAPIKey    string
	EllipticAPISecret string
	// EllipticBaseURL overrides the client's default; empty uses it.
	EllipticBaseURL string
	// ScreeningValidity is how long a screening stays current before the
	// address counts as expired. Empty/zero uses the service's own default
	// (90 days, source design doc §17 Q9's estimate).
	ScreeningValidity time.Duration

	// ComplianceRoleSecretKey signs allow_depositor/disallow_depositor —
	// deliberately a distinct key from AdminSecretKey/TreasurySecretKey, per
	// the source design doc §9: "keeps the freeze key away from the
	// configuration key." Held by the credit backend's on-chain writer
	// worker only, never by cmd/admin — see pkg/services/compliance's
	// OnchainWriter doc comment.
	ComplianceRoleSecretKey string

	// OnchainWriterInterval is how often the on-chain writer worker polls
	// for approvals/revocations still waiting on a chain write. Empty/zero
	// uses a 1-minute default — this is the fast path (source design doc
	// §17 Q4: revocation cannot wait), so it ticks far more often than the
	// rescreening sweep.
	OnchainWriterInterval time.Duration

	// RescreenSweepInterval is how often the rescreening sweep looks for
	// lapsed approvals. Empty/zero uses a 1-hour default.
	RescreenSweepInterval time.Duration
}

type Config struct {
	Postgres   PostgresConfig
	Redis      RedisConfig
	Server     ServerConfig
	Stellar    StellarConfig
	Payments   PaymentsConfig
	Mobile     MobileConfig
	Auth       AuthConfig
	Shortener  ShortenerConfig
	Compliance ComplianceConfig
}

type FonbnkConfig struct {
	ClientID     string
	ClientSecret string
	BaseURL      string
}

type MobileConfig struct {
	AfricasTalking AfricasTalkingConfig
	// SessionTimeout is the Redis TTL for a USSD session, refreshed on each
	// request. From USSD_SESSION_TIMEOUT (seconds); defaults to 5 minutes.
	SessionTimeout time.Duration

	// USSDDialString is what a user dials to reach this deployment, stored
	// complete with prefix and terminator.
	USSDDialString string
}

type MoneyGramConfig struct {
	// SEP-1 / 9 / 10 / 24 — Stellar anchor protocol
	HomeDomain        string // e.g. "stellar.moneygram.com"
	ServerSigningKey  string // pinned from TOML, validated at boot
	NetworkPassphrase string // matches StellarConfig.NetworkPassphrase
	USDCIssuer        string // matches StellarConfig.USDCIssuer
	TransferServerURL string // override, otherwise resolved from TOML

	// REST API — OAuth 2.0 client_credentials (FX rates)
	ClientID     string
	ClientSecret string
	OAuthURL     string // token endpoint
	FXRateURL    string // GET /fx-rate/v1/rates

	// Entry-rate buffers applied by the FX orchestrator, as fractions
	// (0.01 = 1 %). Nil leaves the orchestrator's own defaults in place;
	// an explicit 0 quotes raw source rates with no buffer at all.
	// From MONEYGRAM_FX_ENTRY_BUFFER_PCT and
	// MONEYGRAM_FX_ENTRY_BUFFER_PCT_FALLBACK.
	FXEntryBufferPct         *float64
	FXEntryBufferPctFallback *float64

	// Custodial wallets. AuthSecret co-signs SEP-10; FundsSecret is the SEP-24
	// account and USDC send source. Both default to TREASURY_SECRET_KEY.
	AuthSecret  string
	FundsSecret string

	// Poller cadence. Zero leaves mgpoller.DefaultConfig's value in place
	// rather than config duplicating the defaults.
	PollInterval            time.Duration // MONEYGRAM_POLL_INTERVAL (seconds)
	PollMaxBatch            int           // MONEYGRAM_POLL_MAX_BATCH
	RefundSettleMaxAttempts int           // MONEYGRAM_REFUND_MAX_ATTEMPTS

	// Borrower repayment cash-in. Separate from the withdrawal cadence above
	// because the two directions wait on different things: a withdrawal is
	// ours to finish and is polled hard, a deposit is the borrower's and
	// spends most of its window idle.
	RepaymentWindow          time.Duration // REPAYMENT_WINDOW (seconds)
	RepaymentPollInterval    time.Duration // REPAYMENT_POLL_INTERVAL (seconds)
	RepaymentReminderBefore  time.Duration // REPAYMENT_REMINDER_BEFORE (seconds)
	RepaymentVaultMaxAttempt int           // REPAYMENT_VAULT_MAX_ATTEMPTS

	// Per-row poll schedule. These write repayment_next_poll_at, which is what
	// actually decides whether a row is returned — shortening
	// RepaymentPollInterval alone changes how often the runner asks, not what
	// it gets back, so a row parked 30 minutes out stays parked.
	//
	// Production wants them long: a deposit spends most of its window with the
	// borrower walking to an agent, and polling harder learns nothing. Set them
	// to a few seconds in development to watch a deposit move in real time.
	RepaymentActiveBackoff     time.Duration // REPAYMENT_ACTIVE_BACKOFF (seconds), default 2m
	RepaymentIdleBackoff       time.Duration // REPAYMENT_IDLE_BACKOFF (seconds), default 30m
	RepaymentVaultRetryBackoff time.Duration // REPAYMENT_VAULT_RETRY_BACKOFF (seconds), default 1h
}

type MpesaConfig struct {
	// ConsumerKey and ConsumerSecret sign the access-token mint.
	ConsumerKey    string
	ConsumerSecret string

	// CollectionShortcode receives C2B and M-Pesa Express payments.
	CollectionShortcode uint

	// DisbursementShortcode funds payouts and is the PartyA of balance and
	// reversal queries against the payout side.
	DisbursementShortcode uint

	// Passkey signs the M-Pesa Express password.
	Passkey string

	// InitiatorName and InitiatorPassword are the M-PESA API operator.
	InitiatorName     string
	InitiatorPassword string

	// CallbackBaseURL is the public base the result and validation URLs are
	// built from — the bare host, with no path prefix; the /api/v1 segment is
	// added where the URL is built. Through the OutRay tunnel on testnet; an
	// owned domain later.
	CallbackBaseURL string

	// CallbackSlug is the unguessable path segment the callback URLs hang off.
	// Daraja signs nothing, so an attacker who learns the path can post forged
	// confirmations; the slug is the only thing making that path non-obvious.
	CallbackSlug string

	// CallbackAllowedCIDRs is the Safaricom egress range, enforced on the
	// callback group in production. Log-only when empty.
	CallbackAllowedCIDRs []string

	// STKPollInterval bounds how often the poller asks Daraja about a pending
	// prompt.
	STKPollInterval time.Duration

	// STKMaxAttempts is how many poll rounds a pending prompt gets before a
	// human is told, not how long the borrower has.
	STKMaxAttempts int

	// ReferencePrefix is the loan-reference namespace the C2B validator checks
	// against. It must equal PaymentsConfig.LoanReferencePrefix, and it is
	// loaded from the same LOAN_REFERENCE_PREFIX variable.
	ReferencePrefix string

	// PromptAmountKES overrides the STK prompt amount with a fixed whole-KES
	// figure instead of the quoted payoff. Daraja's sandbox has no simulator,
	// so on a sandbox deployment a real handset must be charged a real
	// (tiny) amount to exercise the rail. From MPESA_PROMPT_AMOUNT_KES;
	// zero means use the quoted payoff. Setting it in production is a boot
	// error.
	PromptAmountKES int

	// SettlementMode decides how KES collected on the paybill becomes USDC.
	//
	// "otc" is the deployed model: the float is converted at a desk and
	// deposited to treasury by hand, and cmd/mpesa-settle writes the vault leg
	// once it lands. "provider_sweep" — B2B-sweeping the float to an on-ramp's
	// own paybill — is named here because the choice is real, but it is not
	// built, so it is rejected at boot rather than silently behaving as "otc".
	SettlementMode string

	// NumberValidationPolicy decides whether an STK payer's MSISDN is checked
	// against their national ID. Advisory records the verdict and blocks
	// nobody; enforcing is accepted here but not yet acted on.
	NumberValidationPolicy mpesa.ValidationPolicy

	// PullSweepInterval is how often the Pull reconciler walks the settled
	// window. Daraja keeps 48 hours, so anything well inside that is safe.
	PullSweepInterval time.Duration

	// BalancePollInterval is how often the shortcode balances are asked for.
	// An ops signal, not a latency-sensitive one.
	BalancePollInterval time.Duration

	// PaybillSweepInterval is how often the paybill repayment sweep converts
	// newly-confirmed mpesa_transactions rows into repayment progress. Short
	// by default — a borrower who just paid should not wait long to see it
	// reflected, matching the on-chain writer's own "fast path" reasoning.
	PaybillSweepInterval time.Duration

	// CollectionBalanceFloorKES and DisbursementBalanceFloorKES are the
	// whole-KES levels below which a parsed balance is alerted on. Optional;
	// zero disables the alert for that shortcode.
	CollectionBalanceFloorKES   int
	DisbursementBalanceFloorKES int

	// HakikishaUsername and HakikishaPassword are the client-credentials pair
	// Safaricom authenticates with to ask us to name an account. Plaintext
	// from the environment, as InitiatorPassword and ConsumerSecret already
	// are.
	HakikishaUsername string
	HakikishaPassword string

	// HakikishaSigningKey signs the short-lived token that endpoint issues. It
	// is deliberately not the admin JWT key: the two token families share no
	// claim shape and must not be interchangeable.
	HakikishaSigningKey string
}

type PaymentsConfig struct {
	YellowCard YellowCardConfig
	Fonbnk     FonbnkConfig
	MoneyGram  MoneyGramConfig
	Mpesa      MpesaConfig
	Airtel     AirtelConfig

	// EntryFXBufferPct is the flat safety margin the loan adapter applies when
	// it re-quotes the entry rate from a provider's own Quoter, as a fraction
	// (0.02 = 2 %). Nil leaves the adapter's default in place; an explicit 0
	// persists the quoted rate unbuffered. From LOAN_ENTRY_FX_BUFFER_PCT.
	//
	// Distinct from the MoneyGram orchestrator's buffers, which apply on the
	// cascade path and carry their own per-leg settings.
	EntryFXBufferPct *float64

	// EnableProviderRelaySwitch turns on per-transaction routing between
	// providers on effective post-fee rate. Off routes every transaction to
	// YellowCard, the default provider. From
	// ENABLE_PAYMENT_PROVIDER_RELAY_SWITCH; unset is off.
	EnableProviderRelaySwitch bool

	// RoundAnchorAmounts gates cent-rounding of mobile-money cash-out
	// principals (YellowCard and other non-MoneyGram rails). MoneyGram cash-out
	// and cash-in always round to whole cents regardless of this flag. Off (the
	// default) carries full 7-stroop precision on the non-MoneyGram rails; on
	// rounds their cash-out principals before they are stored, borrowed, or
	// sent on-chain. From ROUND_ANCHOR_AMOUNTS; unset is off.
	RoundAnchorAmounts bool

	// LoanReferencePrefix is the 2-character namespace prefix on generated loan
	// references, defaulting to loanref.DefaultPrefix. From
	// LOAN_REFERENCE_PREFIX. The check character is derived over the prefix, so
	// every component that validates or generates a reference must read the
	// same configured value.
	LoanReferencePrefix string
}

type PostgresConfig struct {
	Host     string
	User     string
	Password string
	DBName   string
	Port     string
	SSLMode  string
	TimeZone string
}

type RedisConfig struct {
	Host           string
	Port           string
	Password       string
	DBNumber       int
	IdempotencyTTL time.Duration
}

type ServerConfig struct {
	ServerEnvironment string
	ServerHost        string
	CoreServerPort    string
	CreditServerPort  string
	// PublicBaseURL is the externally-reachable origin used to build SMS
	// short-links (e.g. https://microvault.outray.app). No trailing slash.
	PublicBaseURL string

	// TrustedProxyCIDRs are the ingress hops whose X-Forwarded-For may be
	// believed. Both binaries sit behind the same tunnel, so both read the
	// same list.
	//
	// This is what makes the Daraja callback allowlist mean anything. Reading
	// the header without it lets anyone who can reach the port name their own
	// source address; leaving it empty makes c.IP() the tunnel's address, so
	// the allowlist matches the tunnel rather than Safaricom. Neither is a
	// half-measure of the other — the pair is the control.
	TrustedProxyCIDRs []string
}

type ShortenerConfig struct {
	// APIKey is the dub workspace API key (from DUB_API_KEY). Presence
	// enables the shortener.
	APIKey string
	// BaseURL is the dub API origin (from DUB_API_URL), set to point at a
	// self-hosted instance. Empty uses the SDK default, https://api.dub.co.
	BaseURL string
	// Domain is the short-link domain links are created under (from
	// DUB_DOMAIN). Optional; empty lets the workspace default apply.
	Domain string
	// PreviewTitle overrides the og:title in dub Custom Link Previews (from
	// DUB_PREVIEW_TITLE). Optional; empty derives it from the destination host.
	PreviewTitle string
	// PreviewDescription overrides the og:description (from
	// DUB_PREVIEW_DESCRIPTION). Optional; empty derives it from the
	// destination host and path.
	PreviewDescription string
	// ImagePreviewURL is the og:image shown in dub Custom Link Previews
	// (from DUB_IMAGE_PREVIEW_URL). Optional.
	ImagePreviewURL string
}

type StellarConfig struct {
	RpcURL string
	// AdminPublicKey is derived from AdminSecretKey at load, not read from the environment.
	AdminPublicKey          string
	AdminSecretKey          string
	TreasurySecretKey       string
	ServerSecretKey         string
	NetworkPassphrase       string
	EnableMultiSig          bool
	MultiSigLowThreshold    uint32
	MultiSigMediumThreshold uint32
	MultiSigHighThreshold   uint32
	USDCIssuer              string
	ContractID              string

	// AccountIndexBase advances account_index_seq at boot so a freshly rebuilt
	// (testnet) database hands out BIP44 derivation indices above any burned
	// on-chain. 0 (the default) leaves the sequence untouched. From
	// ACCOUNT_INDEX_BASE.
	AccountIndexBase int64

	// VaultWatchInterval is how often the vault watcher polls for new
	// contract events. From VAULT_WATCH_INTERVAL, default 5 minutes.
	VaultWatchInterval time.Duration
}

type YellowCardConfig struct {
	PublicKey    string
	SecretKey    string
	BaseURL      string
	BusinessID   string // Registered business ID with YellowCard
	BusinessName string // Registered business name with YellowCard
}