datafetch

type GeocodeCache interface {
	// Get returns (result, true) for a cached success, (nil, true) for a cached
	// not_found, and (nil, false) when the key is absent.
	Get(key string) (*ReverseGeocodeResult, bool)
	// Set stores a success (non-nil r) or a not_found marker (nil r).
	Set(key string, r *ReverseGeocodeResult)
}

type GoogleMapsStoreData struct {
	ID   string
	Name string
}

type GoogleMapsStoreReview struct {
	Reviewer      string `json:"reviewer"`
	ReviewerID    string `json:"reviewer_id"`
	ReviewerState string `json:"reviewer_state"`
	ReviewerLevel int    `json:"reviewer_level"`
	ReviewTime    string `json:"review_time"`
	ReviewDate    string `json:"review_date"`
	Content       string `json:"content"`
	Rating        int    `json:"rating"`
}

type GoogleMapsStoreReviewSortBy uint8

type GoogleMapsStoreReviews []GoogleMapsStoreReview

type GoogleMapsStoreReviewsFetchingOptions struct {
	SortBy GoogleMapsStoreReviewSortBy
	// MaxWaitingInterval_Milliseconds is the maximum waiting interval in milliseconds between requests.
	MaxWaitingInterval_Milliseconds uint
}

type RateLimitError struct {
	Limit     int       // X-Ratelimit-Limit (requests per window)
	Remaining int       // X-Ratelimit-Remaining
	ResetAt   time.Time // X-Ratelimit-Reset, zero if the header was absent/unparseable
}

type ReverseGeocodeResult struct {
	Lat         float64 `json:"lat"`
	Lng         float64 `json:"lng"`
	VillCode    string  `json:"villcode"`
	CountyName  string  `json:"county_name"`
	TownName    string  `json:"town_name"`
	VillageName string  `json:"village_name"`
	VillageEng  string  `json:"village_eng"`
	CountyID    string  `json:"county_id"`
	CountyCode  string  `json:"county_code"`
	TownID      string  `json:"town_id"`
	TownCode    string  `json:"town_code"`
}

type TWGeocodingConfig struct {
	// Timeout is the per-request timeout. Default: 15s.
	Timeout time.Duration
	// Interval is the minimum spacing between requests (client-side throttle).
	// 0 disables throttling. Must be >= 0.
	Interval time.Duration
	// UserAgent is the HTTP User-Agent header. Default: a browser-like UA.
	UserAgent string
	// Retries is the number of retry attempts for transient failures. Must be >= 0.
	Retries int
	// RetryBackoff is the base backoff between retries. Must be >= 0. Default: 300ms.
	RetryBackoff time.Duration
	// BaseURL overrides the reverse-geocoding endpoint (for tests/mocks or a
	// future paid/self-hosted tier). Default: the official zuola endpoint.
	BaseURL string
	// Cache, when non-nil, serves and stores definitive results to conserve the
	// scarce request quota. Use NewMemoryGeocodeCache or NewFileGeocodeCache.
	Cache GeocodeCache
}

type YFFinancialStatementTables struct {
	Values *insyra.DataTable
	Items  *insyra.DataTable
	Meta   *insyra.DataTable
}

type YFHistoryParams = models.HistoryParams

type YFOptionChainTables struct {
	Calls      *insyra.DataTable
	Puts       *insyra.DataTable
	Underlying *insyra.DataTable
	Expiration time.Time
}

type YFPeriod string

type YFinanceConfig struct {
	// Timeout: 單次請求最多等待多久（避免卡死）
	Timeout time.Duration

	// Interval: 每次請求之間最少要隔多久（節流）
	// 0 表示不節流
	Interval time.Duration

	// UserAgent: HTTP User-Agent
	UserAgent string

	// Retries: 失敗時重試次數（0 表示不重試）
	Retries int

	// RetryBackoff: 每次重試前等待多久（0 表示用預設）
	RetryBackoff time.Duration

	// Concurrency: 多 ticker 並行抓取時的最大並行數（0 表示用預設）
	Concurrency int
}