statsstore

type DefaultGeoIPResolver struct {
	Endpoint   string        // default: GeoIPEndpointDefault
	Timeout    time.Duration // default: GeoIPTimeoutDefault
	HTTPClient *http.Client  // injectable for testing; if nil, a default client is used
	CacheTTL   time.Duration // default: GeoIPCacheTTLDefault; set to 0 to disable caching
	// contains filtered or unexported fields
}

type GeoIPResolver interface {
	// Resolve returns an ISO2 country code (e.g. "US", "GB") for the given IP.
	// If the IP cannot be resolved, it returns CountryUnknown and nil error.
	// If the lookup itself fails (network error, bad response), it returns
	// an empty string and the error so the caller can leave the field empty
	// for a retry.
	Resolve(ctx context.Context, ip string) (string, error)
}

type NewStoreOptions struct {
	VisitorTableName     string
	SettingsTableName    string
	DB                   *sql.DB
	AutomigrateEnabled   bool
	DebugEnabled         bool
	BotFilterEnabled     bool
	ExcludedPathPrefixes []string
	ExcludedIPs          []string
	GeoIPResolver        GeoIPResolver // optional; enables VisitorEnhance for batch country enrichment
	EnhanceBatchSize     int           // number of records per VisitorEnhance call; default 10
}

type StoreInterface interface {
	// MigrateDown drops the stats store tables
	MigrateDown(ctx context.Context, tx ...*sql.Tx) error

	// MigrateUp creates the stats store tables
	MigrateUp(ctx context.Context, tx ...*sql.Tx) error

	EnableDebug(debug bool)
	GetDB() *sql.DB

	SetBotFilterEnabled(enabled bool)
	IsBotFilterEnabled() bool

	SetExcludedPathPrefixes(prefixes []string)
	GetExcludedPathPrefixes() []string

	SetExcludedIPs(ips []string)
	GetExcludedIPs() []string

	ExcludedIPList(ctx context.Context) ([]string, error)
	ExcludedIPAdd(ctx context.Context, ip string) error
	ExcludedIPRemove(ctx context.Context, ip string) error

	// SettingGet retrieves a setting value by key. Returns empty string and
	// nil error if the key does not exist.
	SettingGet(ctx context.Context, key string) (string, error)
	// SettingSet stores a setting value by key, using upsert semantics.
	SettingSet(ctx context.Context, key, value string) error
	// SettingDelete removes a setting by key. No error if the key is absent.
	SettingDelete(ctx context.Context, key string) error
	// SettingHas reports whether a setting key exists.
	SettingHas(ctx context.Context, key string) (bool, error)
	// SettingList returns all settings as a map of key to value.
	// Returns an empty map if the settings table does not exist or is empty.
	SettingList(ctx context.Context) (map[string]string, error)

	VisitorCount(ctx context.Context, query VisitorQueryInterface) (int64, error)
	VisitorCreate(ctx context.Context, user VisitorInterface) error
	VisitorDelete(ctx context.Context, user VisitorInterface) error
	VisitorDeleteByID(ctx context.Context, id string) error
	VisitorDeleteByIP(ctx context.Context, ip string) (int64, error)
	VisitorFindByID(ctx context.Context, userID string) (VisitorInterface, error)
	VisitorList(ctx context.Context, query VisitorQueryInterface) ([]VisitorInterface, error)
	VisitorRegister(ctx context.Context, r *http.Request) error
	VisitorSoftDelete(ctx context.Context, user VisitorInterface) error
	VisitorSoftDeleteByID(ctx context.Context, id string) error
	VisitorUpdate(ctx context.Context, user VisitorInterface) error

	// VisitorEnhance enriches visitor records that have an empty country field.
	// It parses the user agent (browser, OS, device type) and looks up the
	// country via the configured GeoIPResolver. UA fields are updated even if
	// the geo-IP lookup fails; the country stays empty for retry.
	// Returns the number of records fully processed (country + UA).
	// Call this from a background task/cron on whatever schedule suits your
	// traffic (e.g. every 5 minutes).
	//
	// If no GeoIPResolver was configured, it returns 0 and an error.
	VisitorEnhance(ctx context.Context) (int, error)
}

type UserAgentInfo struct {
	Browser        string
	BrowserVersion string
	Os             string
	OsVersion      string
	Device         string
	DeviceType     string
}

type VisitorInterface interface {
	// Methods
	FingerprintCalculate() string
	IsSoftDeleted() bool

	GetID() string
	SetID(id string) VisitorInterface

	GetPath() string
	SetPath(path string) VisitorInterface

	GetCountry() string
	SetCountry(country string) VisitorInterface

	GetCreatedAt() string
	GetCreatedAtCarbon() *carbon.Carbon
	SetCreatedAt(createdAt string) VisitorInterface

	GetSoftDeletedAt() string
	GetSoftDeletedAtCarbon() *carbon.Carbon
	SetSoftDeletedAt(deletedAt string) VisitorInterface

	GetFingerprint() string
	SetFingerprint(fingerprint string) VisitorInterface

	GetIpAddress() string
	SetIpAddress(ipAddress string) VisitorInterface

	GetUpdatedAt() string
	GetUpdatedAtCarbon() *carbon.Carbon
	SetUpdatedAt(updatedAt string) VisitorInterface

	GetUserAcceptLanguage() string
	SetUserAcceptLanguage(userAcceptLanguage string) VisitorInterface

	GetUserAcceptEncoding() string
	SetUserAcceptEncoding(userAcceptEncoding string) VisitorInterface

	GetUserAgent() string
	SetUserAgent(userAgent string) VisitorInterface

	GetUserBrowser() string
	SetUserBrowser(userBrowser string) VisitorInterface

	GetUserBrowserVersion() string
	SetUserBrowserVersion(userBrowserVersion string) VisitorInterface

	GetUserDevice() string
	SetUserDevice(userDevice string) VisitorInterface

	GetUserDeviceType() string
	SetUserDeviceType(userDeviceType string) VisitorInterface

	GetUserOs() string
	SetUserOs(userOs string) VisitorInterface

	GetUserOsVersion() string
	SetUserOsVersion(userOsVersion string) VisitorInterface

	GetUserReferrer() string
	SetUserReferrer(userReferrer string) VisitorInterface
}

type VisitorQueryInterface interface {
	Validate() error

	HasCountry() bool
	Country() string
	SetCountry(country string) VisitorQueryInterface

	HasCreatedAtGte() bool
	CreatedAtGte() string
	SetCreatedAtGte(createdAtGte string) VisitorQueryInterface

	HasCreatedAtLte() bool
	CreatedAtLte() string
	SetCreatedAtLte(createdAtLte string) VisitorQueryInterface

	HasDeviceType() bool
	DeviceType() string
	SetDeviceType(deviceType string) VisitorQueryInterface

	HasDistinct() bool
	Distinct() string
	SetDistinct(distinct string) VisitorQueryInterface

	HasID() bool
	ID() string
	SetID(id string) VisitorQueryInterface

	HasIDIn() bool
	IDIn() []string
	SetIDIn(idIn []string) VisitorQueryInterface

	HasLimit() bool
	Limit() int
	SetLimit(limit int) VisitorQueryInterface

	HasOffset() bool
	Offset() int
	SetOffset(offset int) VisitorQueryInterface

	HasOrderBy() bool
	OrderBy() string
	SetOrderBy(orderBy string) VisitorQueryInterface

	HasPathContains() bool
	PathContains() string
	SetPathContains(pathContains string) VisitorQueryInterface

	HasPathExact() bool
	PathExact() string
	SetPathExact(pathExact string) VisitorQueryInterface

	HasSortOrder() bool
	SortOrder() string
	SetSortOrder(sortOrder string) VisitorQueryInterface

	HasSoftDeletedIncluded() bool
	SoftDeletedIncluded() bool
	SetSoftDeletedIncluded(withSoftDeleted bool) VisitorQueryInterface
}