insights

type APIError struct {
	StatusCode int
	Message    string
}

type APIMessage interface{}

type Alias struct {
	// This field is exported for serialization purposes and shouldn't be set by
	// the application, its value is always overwritten by the library.
	Type string
	// Uuid is optional. If not provided, a random UUID will be generated.
	Uuid string

	Alias        string
	DistinctId   string
	Timestamp    time.Time
	DisableGeoIP bool
}

type AliasInApi struct {
	Type           string    `json:"type"`
	Uuid           string    `json:"uuid"`
	Library        string    `json:"library"`
	LibraryVersion string    `json:"library_version"`
	Timestamp      time.Time `json:"timestamp"`

	Properties AliasInApiProperties `json:"properties"`

	Event string `json:"event"`
}

type AliasInApiProperties struct {
	DistinctId   string `json:"distinct_id"`
	Alias        string `json:"alias"`
	Lib          string `json:"$lib"`
	LibVersion   string `json:"$lib_version"`
	DisableGeoIP bool   `json:"$geoip_disable,omitempty"`
}

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

type Callback interface {

	// This method is called for every message that was successfully sent to
	// the API.
	Success(APIMessage)

	// This method is called for every message that failed to be sent to the
	// API and will be discarded by the client.
	Failure(APIMessage, error)
}

type Capture struct {
	// This field is exported for serialization purposes and shouldn't be set by
	// the application, its value is always overwritten by the library.
	Type string
	// You don't usually need to specify this field - Insights will generate it automatically.
	// Use it only when necessary - for example, to prevent duplicate events.
	Uuid             string
	DistinctId       string
	Event            string
	Timestamp        time.Time
	Properties       Properties
	Groups           Groups
	SendFeatureFlags SendFeatureFlagsValue
}

type CaptureInApi struct {
	Type           string    `json:"type"`
	Uuid           string    `json:"uuid"`
	Library        string    `json:"library"`
	LibraryVersion string    `json:"library_version"`
	Timestamp      time.Time `json:"timestamp"`

	DistinctId       string                `json:"distinct_id"`
	Event            string                `json:"event"`
	Properties       Properties            `json:"properties"`
	SendFeatureFlags SendFeatureFlagsValue `json:"send_feature_flags"`
}

type Client interface {
	io.Closer
	EnqueueClient

	// IsFeatureEnabled returns if a feature flag is on for a given user based on their distinct ID
	IsFeatureEnabled(FeatureFlagPayload) (interface{}, error)

	// GetFeatureFlag returns variant value if multivariant flag or otherwise a boolean indicating
	// if the given flag is on or off for the user
	GetFeatureFlag(FeatureFlagPayload) (interface{}, error)

	// GetFeatureFlagResult returns the flag value and payload together.
	// Use this instead of calling GetFeatureFlag and GetFeatureFlagPayload separately.
	// Returns an error if the flag cannot be evaluated (e.g., flag missing or cannot be computed
	// when using OnlyEvaluateLocally).
	GetFeatureFlagResult(FeatureFlagPayload) (*FeatureFlagResult, error)

	// GetFeatureFlagPayload returns feature flag's payload value matching key for user (supports multivariate flags).
	// Deprecated: Use GetFeatureFlagResult instead, which returns both
	// the flag value and payload while properly tracking feature flag usage.
	GetFeatureFlagPayload(FeatureFlagPayload) (string, error)

	// GetRemoteConfigPayload returns decrypted feature flag payload value for remote config flags.
	GetRemoteConfigPayload(string) (string, error)

	// GetAllFlags returns all flags for a user
	GetAllFlags(FeatureFlagPayloadNoKey) (map[string]interface{}, error)

	// ReloadFeatureFlags forces a reload of feature flags
	// NB: This is only available when using a PersonalApiKey
	ReloadFeatureFlags() error

	// GetFeatureFlags gets all feature flags, for testing only.
	// NB: This is only available when using a PersonalApiKey
	GetFeatureFlags() ([]FeatureFlag, error)

	// CloseWithContext gracefully shuts down the client with the provided context.
	// The context can be used to control the shutdown deadline.
	CloseWithContext(context.Context) error
}

type CommonResponseFields struct {
	QuotaLimited              []string `json:"quota_limited"`
	RequestId                 string   `json:"requestId"`
	EvaluatedAt               *int64   `json:"evaluatedAt"`
	ErrorsWhileComputingFlags bool     `json:"errorsWhileComputingFlags"`
}

type CompressionMode uint8

type Config struct {

	// The endpoint to which the client connect and send their messages, set to
	// `DefaultEndpoint` by default.
	Endpoint string

	// Specifying a Personal API key will make feature flag evaluation more performant,
	// but it's not required for feature flags.  If you don't have a personal API key,
	// you can leave this field empty, and all of the relevant feature flag evaluation
	// methods will still work.
	// Information on how to get a personal API key: https://insights.hanzo.ai/docs/api/overview
	PersonalApiKey string

	// DisableGeoIP will disable GeoIP lookup for events and when fetching feature flags
	DisableGeoIP *bool

	// The flushing interval of the client. Messages will be sent when they've
	// been queued up to the maximum batch size or when the flushing interval
	// timer triggers. If zero, defaults to 5 seconds.
	Interval time.Duration

	// Interval at which to fetch new feature flag definitions, 5min by default
	DefaultFeatureFlagsPollingInterval time.Duration

	// Timeout for fetching feature flags, 3 seconds by default
	FeatureFlagRequestTimeout time.Duration

	// Calculate when feature flag definitions should be polled next. Setting this property
	// will override DefaultFeatureFlagsPollingInterval.
	NextFeatureFlagsPollingTick func() time.Duration

	// Flag to enable historical migration
	// See more in our migration docs: https://insights.hanzo.ai/docs/migrate
	HistoricalMigration bool

	// The HTTP transport used by the client, this allows an application to
	// redefine how requests are being sent at the HTTP level (for example,
	// to change the connection pooling policy).
	// If none is specified the client uses `http.DefaultTransport`.
	Transport http.RoundTripper

	// Logger used by the client to output info or error messages when that
	// are generated by background operations.
	// If none is specified the client uses a standard logger that outputs to
	// `os.Stderr`. Override this to suppress log messages.
	Logger Logger

	// Properties that will be included in every event sent by the client.
	// This is useful for adding common metadata like service name or app version across all events.
	// If a property conflict occurs, the value from DefaultEventProperties will overwrite any existing value.
	DefaultEventProperties Properties

	// The callback object that will be used by the client to notify the
	// application when messages sends to the backend API succeeded or failed.
	Callback Callback

	// The maximum number of messages that will be sent in one API call.
	// Messages will be sent when they've been queued up to the maximum batch
	// size or when the flushing interval timer triggers. If zero, defaults to 250.
	// Note that the API will still enforce a 500KB limit on each HTTP request
	// which is independent from the number of embedded messages.
	BatchSize int

	// When set to true the client will send more frequent and detailed messages
	// to its logger.
	Verbose bool

	// The retry policy used by the client to resend requests that have failed.
	// The function is called with how many times the operation has been retried
	// and is expected to return how long the client should wait before trying
	// again.
	// If not set the client will fallback to use a default retry policy.
	RetryAfter func(int) time.Duration

	// MaxRetries is the maximum number of times a request is retried on failure.
	// Must be in range [0,9]. If nil, defaults to 9 (10 total attempts).
	MaxRetries *int

	// ShutdownTimeout is the maximum time to wait for in-flight messages
	// to be sent during Close(). If zero or negative, waits indefinitely
	// (preserving backward-compatible behavior). Set to a positive duration
	// to enable timeout-based shutdown.
	ShutdownTimeout time.Duration

	// BatchUploadTimeout is the timeout for uploading batched events to the
	// /batch/ endpoint. If zero, defaults to 10 seconds.
	BatchUploadTimeout time.Duration

	// BatchSubmitTimeout is the maximum time to wait when submitting a batch
	// to the worker pool if the queue is full. This provides backpressure
	// smoothing during transient backend latency spikes, reducing data loss.
	// If zero, defaults to 100ms. Set to a negative value for non-blocking
	// behavior (immediate drop when queue is full).
	BatchSubmitTimeout time.Duration

	// MaxEnqueuedRequests is the maximum number of batches that can be queued
	// for sending. When the queue is full, new batches are dropped and the
	// failure callback is invoked. If zero, defaults to 1000.
	MaxEnqueuedRequests int

	// Compression specifies the compression mode for batch payloads.
	// When set to CompressionGzip, payloads are GZIP compressed before
	// sending, and appropriate headers/query params are added.
	// Defaults to CompressionNone (no compression).
	Compression CompressionMode
	// contains filtered or unexported fields
}

type ConfigError struct {

	// A human-readable message explaining why the configuration field's value
	// is invalid.
	Reason string

	// The name of the configuration field that was carrying an invalid value.
	Field string

	// The value of the configuration field that caused the error.
	Value interface{}
}

type DecideRequestData struct {
	ApiKey           string                `json:"api_key"`
	DistinctId       string                `json:"distinct_id"`
	Groups           Groups                `json:"groups"`
	PersonProperties Properties            `json:"person_properties"`
	GroupProperties  map[string]Properties `json:"group_properties"`
}

type DecideResponse struct {
	FeatureFlags        map[string]interface{}     `json:"featureFlags"`
	FeatureFlagPayloads map[string]json.RawMessage `json:"featureFlagPayloads"`
}

type DefaultStackTraceExtractor struct {
	InAppDecider InAppDecider
}

type DescriptionExtractor interface {
	ExtractDescription(r slog.Record) string
}

type EnqueueClient interface {
	// Enqueue queues a message to be sent by the client when the conditions for a batch
	// upload are met.
	// This is the main method you'll be using, a typical flow would look like
	// this:
	//
	//	client := insights.New(apiKey)
	//	...
	//	client.Enqueue(insights.Capture{ ... })
	//	...
	//	client.Close()
	//
	// The method returns an error if the message queue could not be queued, which
	// happens if the client was already closed at the time the method was
	// called or if the message was malformed.
	Enqueue(Message) error
}

type ErrorExtractor struct {
	ErrorKeys []string
	Fallback  string
}

type Exception struct {
	// This field is exported for serialization purposes and shouldn't be set by
	// the application, its value is always overwritten by the library.
	Type string
	// Uuid is optional. If not provided, a random UUID will be generated.
	Uuid string

	DistinctId   string
	Timestamp    time.Time
	DisableGeoIP bool

	// Typed properties that end up in the API "properties" object:
	ExceptionList        []ExceptionItem
	ExceptionFingerprint *string
}

type ExceptionInApi struct {
	Type           string                   `json:"type"`
	Uuid           string                   `json:"uuid"`
	Library        string                   `json:"library"`
	LibraryVersion string                   `json:"library_version"`
	Timestamp      time.Time                `json:"timestamp"`
	Event          string                   `json:"event"`
	Properties     ExceptionInApiProperties `json:"properties"`
}

type ExceptionInApiProperties struct {
	Lib                  string          `json:"$lib"`
	LibVersion           string          `json:"$lib_version"`
	DistinctId           string          `json:"distinct_id"`
	DisableGeoIP         bool            `json:"$geoip_disable,omitempty"`
	ExceptionList        []ExceptionItem `json:"$exception_list"`
	ExceptionFingerprint *string         `json:"$exception_fingerprint,omitempty"`
}

type ExceptionItem struct {
	// Type will be rendered as title in the UI
	Type string `json:"type"`
	// Value will be rendered as description in the UI
	Value     string              `json:"value"`
	Mechanism *ExceptionMechanism `json:"mechanism,omitempty"`
	// Stacktrace can conveniently be generated through the use of StackTraceExtractor
	Stacktrace *ExceptionStacktrace `json:"stacktrace,omitempty"`
}

type ExceptionMechanism struct {
	Handled   *bool `json:"handled,omitempty"`
	Synthetic *bool `json:"synthetic,omitempty"`
}

type ExceptionStacktrace struct {
	Type   string       `json:"type"`
	Frames []StackFrame `json:"frames"`
}

type FeatureFlag struct {
	Key                        string   `json:"key"`
	RolloutPercentage          *float64 `json:"rollout_percentage"`
	Active                     bool     `json:"active"`
	Filters                    Filter   `json:"filters"`
	EnsureExperienceContinuity *bool    `json:"ensure_experience_continuity"`
	BucketingIdentifier        *string  `json:"bucketing_identifier"`
}

type FeatureFlagCondition struct {
	Properties        []FlagProperty `json:"properties"`
	RolloutPercentage *float64       `json:"rollout_percentage"`
	Variant           *string        `json:"variant"`
}

type FeatureFlagPayload struct {
	Key                   string
	DistinctId            string
	DeviceId              *string
	Groups                Groups
	PersonProperties      Properties
	GroupProperties       map[string]Properties
	OnlyEvaluateLocally   bool
	SendFeatureFlagEvents *bool
}

type FeatureFlagPayloadNoKey struct {
	DistinctId            string
	DeviceId              *string
	Groups                Groups
	PersonProperties      Properties
	GroupProperties       map[string]Properties
	OnlyEvaluateLocally   bool
	SendFeatureFlagEvents *bool
}

type FeatureFlagResult struct {
	// Key is the feature flag key that was evaluated
	Key string

	// Enabled indicates whether the feature flag evaluation determined
	// the flag to be in an enabled state.
	Enabled bool

	// RawPayload is the serialized JSON payload associated with the flag variant.
	// Nil if no payload is configured.
	// Use GetPayloadAs to unmarshal the payload into a specific type.
	RawPayload *string

	// Variant is the variant key if this is a multivariate flag.
	// Nil for boolean flags.
	Variant *string
}

type FeatureFlagsPoller struct {
	Logger   Logger
	Endpoint string
	// contains filtered or unexported fields
}

type FeatureFlagsResponse struct {
	Flags            []FeatureFlag            `json:"flags"`
	GroupTypeMapping *map[string]string       `json:"group_type_mapping"`
	Cohorts          map[string]PropertyGroup `json:"cohorts"`
}

type FieldError struct {

	// The human-readable representation of the type of structure that wasn't
	// initialized properly.
	Type string

	// The name of the field that wasn't properly initialized.
	Name string

	// The value of the field that wasn't properly initialized.
	Value interface{}
}

type Filter struct {
	AggregationGroupTypeIndex *uint8                     `json:"aggregation_group_type_index"`
	Groups                    []FeatureFlagCondition     `json:"groups"`
	Multivariate              *Variants                  `json:"multivariate"`
	Payloads                  map[string]json.RawMessage `json:"payloads"`
}

type FlagDetail struct {
	Key      string       `json:"key"`
	Enabled  bool         `json:"enabled"`
	Variant  *string      `json:"variant"`
	Reason   *FlagReason  `json:"reason"`
	Metadata FlagMetadata `json:"metadata"`
	Failed   *bool        `json:"failed,omitempty"`
}

type FlagMetadata struct {
	ID          int             `json:"id"`
	Version     int             `json:"version"`
	Payload     json.RawMessage `json:"payload"`
	Description *string         `json:"description,omitempty"`
}

type FlagProperty struct {
	Key             string      `json:"key"`
	Operator        string      `json:"operator"`
	Value           interface{} `json:"value"`
	Type            string      `json:"type"` // Supported types: "person", "group", "cohort", "flag"
	Negation        bool        `json:"negation"`
	DependencyChain []string    `json:"dependency_chain"` // For flag dependencies
}

type FlagReason struct {
	Code           string `json:"code"`
	Description    string `json:"description"`
	ConditionIndex *int   `json:"condition_index"`
}

type FlagVariant struct {
	Key               string   `json:"key"`
	Name              string   `json:"name"`
	RolloutPercentage *float64 `json:"rollout_percentage"`
}

type FlagVariantMeta struct {
	ValueMin float64
	ValueMax float64
	Key      string
}

type FlagsRequestData struct {
	ApiKey           string                `json:"api_key"`
	DistinctId       string                `json:"distinct_id"`
	DeviceId         *string               `json:"device_id,omitempty"`
	Groups           Groups                `json:"groups"`
	PersonProperties Properties            `json:"person_properties"`
	GroupProperties  map[string]Properties `json:"group_properties"`
	DisableGeoIP     bool                  `json:"geoip_disable,omitempty"`
}

type FlagsResponse struct {
	CommonResponseFields

	// v4 flags format
	Flags map[string]FlagDetail `json:"flags,omitempty"`

	// v3 legacy fields
	FeatureFlags        map[string]interface{}     `json:"featureFlags"`
	FeatureFlagPayloads map[string]json.RawMessage `json:"featureFlagPayloads"`
}

type GroupIdentify struct {
	Type string
	Key  string
	// Uuid is optional. If not provided, a random UUID will be generated.
	Uuid string

	DistinctId   string
	Timestamp    time.Time
	Properties   Properties
	DisableGeoIP bool
}

type GroupIdentifyInApi struct {
	Uuid           string    `json:"uuid"`
	Library        string    `json:"library"`
	LibraryVersion string    `json:"library_version"`
	Timestamp      time.Time `json:"timestamp"`

	Event      string     `json:"event"`
	DistinctId string     `json:"distinct_id"`
	Properties Properties `json:"properties"`
}

type Groups map[string]interface{}

type Identify struct {
	// This field is exported for serialization purposes and shouldn't be set by
	// the application, its value is always overwritten by the library.
	Type string
	// Uuid is optional. If not provided, a random UUID will be generated.
	Uuid string

	DistinctId   string
	Timestamp    time.Time
	Properties   Properties
	DisableGeoIP bool
}

type IdentifyInApi struct {
	Type           string    `json:"type"`
	Uuid           string    `json:"uuid"`
	Library        string    `json:"library"`
	LibraryVersion string    `json:"library_version"`
	Timestamp      time.Time `json:"timestamp"`

	Event      string     `json:"event"`
	DistinctId string     `json:"distinct_id"`
	Properties Properties `json:"properties"`
	Set        Properties `json:"$set"`
}

type InAppDecider func(frame runtime.Frame) bool

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

type Insights = Client

type InsightsConfig = Config

type Logger interface {
	// Debugf is called by the Insights client to log debug messages about the
	// operations it performs. Messages logged by this method are usually
	// tagged with a `DEBUG` log level in common logging libraries.
	Debugf(format string, args ...interface{})

	// Logf is called by the Insights client to log regular messages about the
	// operations it performs. Messages logged by this method are usually
	// tagged with an `INFO` log level in common logging libraries.
	Logf(format string, args ...interface{})

	// Warnf is called by the Insights client to log warning messages about
	// the operations it performs. Messages logged by this method are usually
	// tagged with a `WARN` log level in common logging libraries.
	Warnf(format string, args ...interface{})

	// Errorf is called by the Insights client to log errors encountered
	// while sending events to the backend servers.
	// Messages logged by this method are usually tagged with an `ERROR` log
	// level in common logging libraries.
	Errorf(format string, args ...interface{})
}

type Message interface {

	// Validate validates the internal structure of the message, the method must return
	// nil if the message is valid, or an error describing what went wrong.
	Validate() error
	APIfy() APIMessage
	// contains filtered or unexported methods
}

type Properties map[string]interface{}

type PropertyGroup struct {
	Type string `json:"type"`
	// []PropertyGroup or []FlagProperty
	Values []any `json:"values"`
}

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

type SendFeatureFlagsBool bool

type SendFeatureFlagsOptions struct {
	// OnlyEvaluateLocally forces evaluation to only use local flags and never make API requests
	OnlyEvaluateLocally bool
	// DeviceId provides a device_id for remote flag evaluation requests
	DeviceId *string
	// PersonProperties provides explicit person properties for local flag evaluation
	PersonProperties Properties
	// GroupProperties provides explicit group properties for local flag evaluation
	GroupProperties map[string]Properties
}

type SendFeatureFlagsValue interface {
	ShouldSend() bool
	GetOptions() *SendFeatureFlagsOptions
}

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

type SlogOption func(*captureConfig)

type StackFrame struct {
	Filename  string `json:"filename"`
	LineNo    int    `json:"lineno"`
	Function  string `json:"function"`
	InApp     bool   `json:"in_app"`
	Synthetic bool   `json:"synthetic"`
	Platform  string `json:"platform"`
}

type StackTraceExtractor interface {
	// GetStackTrace returns an Insights-compatible stack trace.
	//
	// The skip parameter controls how many leading frames to omit before
	// recording. Use it to drop extractor/logging internals and start at the
	// application call site. For example, a skip of 3–5 is typically enough to
	// hide wrapper layers when called from a slog handler.
	GetStackTrace(skip int) *ExceptionStacktrace
}

type Ticker struct {
	C <-chan time.Time
	// contains filtered or unexported fields
}

type Variants struct {
	Variants []FlagVariant `json:"variants"`
}