contract

type AtlasDataType = string

type AtlasIndexes map[string]string

type AuthenticationResult struct {
	// Message is a descriptive message about the authentication result, written in Title Case.
	// example:Login Successful
	// readOnly:true
	Message string `json:"message,omitempty"`
	// User contains the authenticated user's details.
	// example:{"id":"123","name":"John Doe"}
	// readOnly:true
	User map[string]any `json:"user,omitempty"`
}

type AuthenticationResultOption func(*AuthenticationResult)

type Authorizable interface {
	Readers() []ID
	Writers() []ID
	Owners() []ID
}

type AuthorizationResult struct {
	// Code is the HTTP status code.
	// example:200
	// readOnly:true
	Code int `json:"code,omitempty"`
	// UnallowedEntities is the list of unauthorized entity IDs.
	// readOnly:true
	UnallowedEntities []ID `json:"unallowed_entities,omitempty"`
}

type AuthorizationResultOption func(*AuthorizationResult)

type BSONOperator = string

type Base64Decoder interface {
	DecodeString(enc *base64.Encoding, src string) ([]byte, error)
}

type BasisInt = int

type BasisInt32 = int32

type BasisInt64 = int64

type BasisOperator interface {
	BasisIntToMajor(b BasisInt, c ConversionFactor) MajorUnit
	BasisInt32ToMajor(b BasisInt32, c ConversionFactor) MajorUnit
	BasisInt64ToMajor(b BasisInt64, c ConversionFactor) MajorUnit
	MajorToBasis(m MajorUnit, c ConversionFactor) (BasisInt64, error)
}

type CacheHit struct {
	V string `json:"v"`
}

type CacheHitter interface {
	DecodeHit(c CacheHit, dst any) error
	HitFromValue(v any) (*CacheHit, error)
}

type CacheID string

type CacheIdentifier interface {
	CacheID(id string) (CacheID, error)
}

type CacheKey struct {
	ID           fmt.Stringer
	Microservice string
	Collection   string
	Multi        *CacheMulti
}

type CacheMulti struct {
	RawQuery string
}

type CacheOperator interface {
	CacheIdentifier
	CacheHitter
	Cacher
}

type Cacher interface {
	CloserWithCtx
	Get(ctx context.Context, c fmt.Stringer) (*CacheHit, error)
	Set(ctx context.Context, c fmt.Stringer, v CacheHit) error
	BatchGet(ctx context.Context, c []fmt.Stringer) ([]CacheHit, error)
	BatchSet(ctx context.Context, e map[fmt.Stringer]CacheHit) error
	Flush(ctx context.Context, c fmt.Stringer) error
	BatchFlush(ctx context.Context, c []fmt.Stringer) error
	FlushAll(ctx context.Context) error
	Exists(ctx context.Context, c fmt.Stringer) (bool, error)
}

type CertGenerator interface {
	X509KeyPair(certPEMBlock []byte, keyPEMBlock []byte) (tls.Certificate, error)
	AppendCertsFromPEM(pool *x509.CertPool, pemCerts []byte) (ok bool)
}

type ChangeEvent struct {
	OperationType string `json:"operation_type"`
	FullDocument  any    `json:"full_document"`
}

type Closer interface {
	Close() error
}

type CloserWithCtx interface {
	Close(ctx context.Context) error
}

type ComponentExtractor interface {
	GetComponent(skip int, withFuncPath, withFile, withFilePath, withLine bool) string
}

type ConversionFactor = int64

type CreateCollectionsOptions struct {
	Collections []string
}

type CreateIndexesOptions struct {
	Collection string
	Indexes    []IndexEntry
}

type CreateSearchIndexesOptions struct {
	Collection string
	Indexes    []SearchIndexEntry
}

type DBOperator interface {
	InsertOne(ctx context.Context, opts InsertOneOptions) error
	FindOne(ctx context.Context, opts FindOneOptions) error
	FindMany(ctx context.Context, opts FindManyOptions) ([]any, error)
	ReplaceOne(ctx context.Context, opts ReplaceOneOptions) error
	DeleteOne(ctx context.Context, opts DeleteOneOptions) error
	DeleteMany(ctx context.Context, opts DeleteManyOptions) error
	CloserWithCtx
}

type DateFilterOptions struct {
	YearField  string
	MonthField string
	DayField   string
	RefYear    uint
	RefMonth   uint
	RefDay     uint
	IncludeDay bool
}

type DecodeCursorOptions struct {
	Cursor   MongoCursor
	Receiver any
}

type DeleteManyOptions struct {
	Collection string
	Filter     bson.M
}

type DeleteOneOptions struct {
	Collection string
	IDKey      string
	ID         Identifier
}

type ElemMatchFilterOptions struct {
	ArrayField string
	Element    any
	PrependStr string
	AppendStr  string
}

type ElemsInArrayFilterOptions struct {
	ArrayField string
	Elements   []any
	PrependStr string
	AppendStr  string
}

type Entry struct {
	Handler HandlerFunc
	Weight  uint
}

type Env string

type FSysFileReader interface {
	FSysReadFile(fsys fs.ReadFileFS, path string) ([]byte, error)
}

type FactoryOperator interface {
	New(name string) (any, error)
}

type FieldInArrayFilterOptions struct {
	Field    string
	Elements []any
}

type FilterOptions struct {
	ConvertValues  bool
	QueryParams    map[string][]string
	MatchBehavior  MatchBehavior
	PrependStr     string
	AppendStr      string
	ExcludedFields []string
}

type FindManyInternalOptions struct {
	Filter        bson.M
	SortByKey     string
	SortDirection SortDirection
	Skip          int64
	Limit         int64
}

type FindManyOptions struct {
	FindManyInternalOptions
	Collection string
	Receiver   any
}

type FindOneOptions struct {
	Collection string
	Receiver   any
	IDKey      string
	ID         Identifier
}

type FirebaseOperator interface {
	GetFirebaseIDToken(ctx context.Context, email, password, firebaseAPIKey string) (string, error)
	InitFirebase(ctx context.Context, fsys fs.ReadFileFS, accountCredentialsPath string) (*firebase.App, error)
	GenerateMockFirebaseUID(length int) string
}

type Geocoder interface {
	TimezoneFromCoordinates(ctx context.Context, latitude, longitude float64) (string, error)
	CityFromCoordinates(ctx context.Context, latitude, longitude float64) (string, error)
	TimezoneDataFromCoordinates(ctx context.Context, latitude, longitude float64) (*maps.TimezoneResult, error)
	GeocodeCoordinates(ctx context.Context, latitude, longitude float64) ([]maps.GeocodingResult, error)
	SwapTimezone(t time.Time, tz string, toUTC, toMidnight bool) (time.Time, error)
	IsUTC(t time.Time) bool
}

type GoogleMaps interface {
	Timezone(ctx context.Context, r *maps.TimezoneRequest) (*maps.TimezoneResult, error)
	Geocode(ctx context.Context, r *maps.GeocodingRequest) ([]maps.GeocodingResult, error)
}

type GzipReader interface {
	Read(r io.Reader) (io.Reader, error)
}

type GzipUtil interface {
	WriteGzip(w *gzip.Writer, r io.Reader) error
	CloseGzipWriter(w *gzip.Writer) error
	ReadGzip(r io.Reader) ([]byte, error)
	NewGzipReader(r io.Reader) (*gzip.Reader, error)
	CopyToBuffer(r *gzip.Reader, buf *bytes.Buffer) error
	CloseGzipReader(r *gzip.Reader) error
}

type GzipWriter interface {
	Write(r io.Reader) (io.Reader, int64, error)
}

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type HTTPDoer interface {
	Do(ctx context.Context, r *http.Request) (*http.Response, error)
}

type HTTPHTML interface {
	ServeHTML(w http.ResponseWriter, body io.Reader, status int) error
}

type HTTPRequester interface {
	NewRequest(ctx context.Context, method, url string, opts RequestOptions) (*http.Request, error)
}

type HTTPResponder interface {
	RespondJSON(w http.ResponseWriter, v any, status int, escapeHTML bool)
}

type HTTPResponseWriter interface {
	Header() http.Header
	Write([]byte) (int, error)
	WriteHeader(statusCode int)
}

type HTTPServer interface {
	ListenAndServe() error
	ListenAndServeTLS(certFile string, keyFile string) error
	Shutdown(ctx context.Context) error
}

type HTTPUtil interface {
	QueryString(pairs ...string) string
	ValidateQueryParams(q map[string][]string, rules ...QueryParamRule) error
	CopyHeaders(dst, src *http.Request, headers ...string)
	GetHeaders(r *http.Request) http.Header
	DecodeBody(r *http.Request, v any) error
}

type HTTPWriter interface {
	Write(w http.ResponseWriter, b []byte) (int, error)
}

type HandlerFunc func(w http.ResponseWriter, r *http.Request) error

type ID struct {
	// V is a unique identifier.
	// example: 123e4567-e89b-12d3-a456-426655440000
	// required:true
	V *string `json:"id"`
}

type Identifiable interface {
	GetID() ID
}

type Identifier interface {
	GetV() string
	SetV(string)
	IsEmpty() bool
	fmt.Stringer
}

type IndexEntry struct {
	Name               string
	Field              string
	Type               int32
	ExpireAfterSeconds *int32
}

type InsertOneOptions struct {
	Collection string
	Document   Identifiable
}

type JSONOption func(*JSONOptions)

type JSONOptions struct {
	Indent     string // Enables indentation if non-empty.
	EscapeHTML bool   // Determines if HTML characters should be escaped.
	UseNumber  bool   // If true, decodes numbers as `json.Number` instead of `float64`.
}

type Level = slog.Level

type LibraryOperator interface {
	Svc() string
	Env() string
}

type LimiterInfo interface {
	GetMaxScore() uint
	GetHeaderKey() string
	GetRateLimitingMode() string
}

type LimiterOperator interface {
	Engage(next HandlerFunc) HandlerFunc
	LimiterInfo
}

type LogOperator interface {
	Log(ctx context.Context, l Level, v any, prefix string, msg ...string)
	Wrap(ctx context.Context, fn func() (any, error)) error
}

type MajorUnit = float64

type Marshaler interface {
	Marshal(v any, opts JSONOptions) ([]byte, error)
}

type MatchBehavior = string

type MiddlewareFunc func(HandlerFunc) HandlerFunc

type MiddlewareOperator interface {
	Chain(handlers ...MiddlewareFunc) MiddlewareFunc
	Gzip(next HandlerFunc) HandlerFunc
	EnforceHTTPS(next HandlerFunc) HandlerFunc
	CheckHeaders(next HandlerFunc) HandlerFunc
	CleanURLPath(next HandlerFunc) HandlerFunc
	IdempotentPOST(next HandlerFunc) HandlerFunc
	RequireReader(next HandlerFunc) HandlerFunc
	RequireWriter(next HandlerFunc) HandlerFunc
	RequireOwner(next HandlerFunc) HandlerFunc
	AuthenticateFirebaseIDToken(next HandlerFunc) HandlerFunc
	AuthenticateOIDCToken(next HandlerFunc) HandlerFunc
}

type MongoChangeStream interface {
	Close(ctx context.Context) error
	Next(ctx context.Context) bool
	Err() error
}

type MongoClient interface {
	Database(name string, opts ...options.Lister[options.DatabaseOptions]) *mongo.Database
	StartSession(opts ...options.Lister[options.SessionOptions]) (*mongo.Session, error)
	Disconnect(ctx context.Context) error
}

type MongoCollection interface {
	InsertOne(ctx context.Context, document any, opts ...options.Lister[options.InsertOneOptions]) (*mongo.InsertOneResult, error)
	FindOne(ctx context.Context, filter any, opts ...options.Lister[options.FindOneOptions]) *mongo.SingleResult
	Find(ctx context.Context, filter any, opts ...options.Lister[options.FindOptions]) (*mongo.Cursor, error)
	ReplaceOne(ctx context.Context, filter any, document any, opts ...options.Lister[options.ReplaceOptions]) (*mongo.UpdateResult, error)
	DeleteOne(ctx context.Context, filter any, opts ...options.Lister[options.DeleteOneOptions]) (*mongo.DeleteResult, error)
	DeleteMany(ctx context.Context, filter any, opts ...options.Lister[options.DeleteManyOptions]) (*mongo.DeleteResult, error)
	Aggregate(ctx context.Context, pipeline any, opts ...options.Lister[options.AggregateOptions]) (*mongo.Cursor, error)
	Watch(ctx context.Context, pipeline any, opts ...options.Lister[options.ChangeStreamOptions]) (*mongo.ChangeStream, error)
}

type MongoCursor interface {
	Next(ctx context.Context) bool
	Decode(receiver any) error
	Err() error
}

type MongoDatabase interface {
	Watch(ctx context.Context, pipeline any, opts ...options.Lister[options.ChangeStreamOptions]) (*mongo.ChangeStream, error)
}

type MongoFilter interface {
	Filter(opts FilterOptions) (bson.M, error)
	FilterByFieldInArray(opts FieldInArrayFilterOptions) bson.M
	FilterByElemMatch(opts ElemMatchFilterOptions) bson.M
	FilterByElemsInArray(opts ElemsInArrayFilterOptions) bson.M
	FilterByAllElemsInArray(opts ElemsInArrayFilterOptions) bson.M
	FilterByFutureDate(opts DateFilterOptions) bson.D
	FilterByPastDate(opts DateFilterOptions) bson.D
	FilterByExactDate(opts DateFilterOptions) bson.D
	CombineM(op BSONOperator, m ...bson.M) bson.M
}

type MongoLookupTarget = string

type MongoOperator interface {
	MongoUtil
	MongoFilter
	MongoSpecialized
	CloserWithCtx
}

type MongoOutCSChan = chan *ChangeEvent

type MongoPipeliner interface {
	Pipeline() mongo.Pipeline
}

type MongoSpecialized interface {
	Search(ctx context.Context, opts SearchOptions) (*SearchResult, error)
	WatchCollection(ctx context.Context, opts WatchCollectionOptions) error
	WatchDB(ctx context.Context, opts WatchDBOptions) error
	ProcessChangeStream(ctx context.Context, opts ProcessChangeStreamOptions) error
	RunPipeline(ctx context.Context, opts RunPipelineOptions) ([]any, error)
}

type MongoUtil interface {
	WithTransaction(ctx context.Context, fn func(ctx context.Context) error) error
	Collection(db, collection string) MongoCollection
	Database(db string) MongoDatabase
}

type MongoVerb = string

type OperationResult struct {
	// Message is the optional operation message.
	// example:Record Retrieved Successfully
	// readOnly:true
	Message string `json:"message,omitempty"`
	// ID is the optional resource identifier.
	// example:123e4567-e89b-12d3-a456-426655440000
	// readOnly:true
	ID *ID `json:"id,omitempty"`
	// Value is an optional result object.
	// readOnly:true
	Value any `json:"value,omitempty"`
}

type OperationResultOption func(*OperationResult)

type PaginationOptions struct {
	PageNumber int32
	PageSize   int32
}

type PeriodOperator interface {
	FirstPeriodStartDate(year int) time.Time
	LastDayOfLastPeriod(year int) time.Time
	FirstDayOfMonth(date time.Time) time.Time
	PeriodNumber(date time.Time) int
	TimeOfWeekday(date time.Time, weekday time.Weekday) time.Time
}

type PoolOperator interface {
	Acquire()
	Release()
	ActiveWorkers() int
	WaitAll()
	Shutdown()
}

type ProcessChangeStreamOptions struct {
	ChangeStream MongoChangeStream
	LookupKey    string
	Receiver     any
	Output       MongoOutCSChan
}

type PubSubMessage interface {
	GetData() []byte
	GetAttributes() map[string]string
	GetMessageID() string
	GetPublishTime() time.Time
}

type PubSubOperator interface {
	MockPubSubPayload(msg PubSubMessage, subscription string) (io.Reader, error)
	DecodePayload(r *http.Request) (PubSubMessage, error)
}

type QueryParamRule struct {
	Key                   string   // Name of the query parameter.
	DefaultValue          string   // Default value if not provided in the request.
	AcceptedValues        []string // Accepted values; nil allows any value.
	MultipleValuesAllowed bool     // Whether multiple values are permitted.
	Optional              bool     // Whether the parameter is optional.
}

type QueryParamRules []QueryParamRule

type Queryable interface {
	Rules() QueryParamRules
}

type RawCacheKey string

type Reader interface {
	Read(io.Reader) ([]byte, error)
}

type RedisClient interface {
	Closer
	Get(ctx context.Context, key string) *redis.StringCmd
	Set(ctx context.Context, key string, value any, expiration time.Duration) *redis.StatusCmd
	FlushAll(ctx context.Context) *redis.StatusCmd
	Scan(ctx context.Context, cursor uint64, match string, count int64) *redis.ScanCmd
	TxPipeline() redis.Pipeliner
	Exists(ctx context.Context, keys ...string) *redis.IntCmd
	Pipeline() redis.Pipeliner
}

type RedisOperator interface {
	Cacher
}

type ReflectOperator interface {
	FillNilPointers(to, from any) error
}

type RegisteredRoute struct {
	MethodMap map[string]Entry
}

type Registry map[*regexp.Regexp]*RegisteredRoute

type RegistryMutex struct {
	sync.RWMutex
}

type ReplaceOneOptions struct {
	Collection string
	Document   Identifiable
	IDKey      string
	ID         Identifier
}

type RequestOption func(*RequestOptions)

type RequestOptions struct {
	Header http.Header
	Body   io.Reader
}

type RequestWeight = uint

type Role int

type Route struct {
	Ressource   string
	Pairs       []string
	HandlerFunc HandlerFunc
	Weight      uint
	Methods     []string
}

type RouterOperator interface {
	RouterParser
	Run() error
	Mount(r []*Route) error
	Stop(ctx context.Context) error
	Vars(ctx context.Context) (*config.Vars, error)
	PKey() string
	AttachServer(s ServerOperator)
}

type RouterParser interface {
	ParsePath(r *http.Request, re *regexp.Regexp) map[string]string
	ParseQuery(r *http.Request) map[string][]string
}

type RunPipelineOptions struct {
	Collection string
	Receiver   any
	Pipeline   MongoPipeliner
}

type Scopable interface {
	Scope() Scope
}

type Scope struct {
	K  string
	ID ID
}

type SearchIndexEntry struct {
	Collection  string
	Fields      AtlasIndexes
	VectorField *VectorSearchField
}

type SearchInternalOptions struct {
	Filter    bson.M
	SortByKey string
	SortDir   SortDirection
}

type SearchOptions struct {
	SearchInternalOptions
	Collection string
	Receiver   any
	T          *TextOptions
	P          *PaginationOptions
}

type SearchResult struct {
	// Results is the list of search results.
	// example:[{"id":"1","name":"Item1"},{"id":"2","name":"Item2"}]
	// readOnly:true
	Results []any `json:"results,omitempty"`
	// TotalCount is the total number of matching results.
	// example:100
	// readOnly:true
	TotalCount int32 `json:"total_count,omitempty"`
	// LastPage is the last page number based on total results.
	// example:10
	// readOnly:true
	LastPage int32 `json:"last_page,omitempty"`
}

type SearchResultOption func(*SearchResult)

type Searchable interface {
	SearchIn() []string
}

type SecretInfo struct {
	ProjectID string
	SecretID  string
	VersionID string
}

type SecretManagerClient interface {
	AccessSecretVersion(ctx context.Context, req *secretmanagerpb.AccessSecretVersionRequest, opts ...gax.CallOption) (*secretmanagerpb.AccessSecretVersionResponse, error)
	Close() error
}

type SecretOperator interface {
	GetSecret(ctx context.Context, s SecretInfo) ([]byte, error)
	Close() error
}

type SemaphoreInfo interface {
	GetConcurrency() int
}

type SemaphoreOperator interface {
	Acquire()
	Release()
	WaitAll()
	SemaphoreInfo
}

type ServerInfo interface {
	GetUseHTTP2() bool
	GetUseH2C() bool
	GetBoundOn() string
	GetIdleTimeout() time.Duration
	GetReadTimeout() time.Duration
	GetWriteTimeout() time.Duration
}

type ServerOperator interface {
	http.Handler
	ServerRunner
	ServerInfo
}

type ServerRunner interface {
	Run() error
	Shutdown(ctx context.Context) error
}

type SortDirection int

type Sortable interface {
	SortBy() string
}

type TextOptions struct {
	Query  string
	Fields []string
}

type Tool[C any] struct {
	Client C
	Logger LogOperator
}

type ToolOption[C any] func(*ToolOptions[C])

type ToolOptions[C any] struct {
	Logger LogOperator
}

type Unmarshaler interface {
	Unmarshal(data io.Reader, v any, opts JSONOptions) error
}

type VectorSearchField struct {
	NumDimensions int
	Field         string
	Similarity    string
	Quantization  string
	Additionals   []string
}

type WatchCollectionOptions struct {
	Collection string
	Receiver   any
	Pipeline   MongoPipeliner
	Options    *options.ChangeStreamOptionsBuilder
	LookupKey  string
	Output     MongoOutCSChan
}

type WatchDBOptions struct {
	Receiver  any
	Pipeline  MongoPipeliner
	Options   *options.ChangeStreamOptionsBuilder
	LookupKey string
	Output    MongoOutCSChan
}