contract

type AtlasDataType = string

type BSONOperator = string

type Base64Decoder interface {
	DecodeString(enc *base64.Encoding, src string) ([]byte, 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 {
	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 Cacher interface {
	CacheIdentifier
	CacheHitter
	CacheOperator
}

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 CompOption[T any] func(*T)

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
}

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 MongoCollection
	Filter     bson.M
}

type DeleteOneOptions struct {
	Collection MongoCollection
	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 FSysFileReader interface {
	FSysReadFile(fsys fs.ReadFileFS, path string) ([]byte, 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 FindManyOptions struct {
	Collection    MongoCollection
	Filter        bson.M
	SortByKey     string
	SortDirection SortDirection
	Skip          int64
	Limit         int64
	Receiver      any
}

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

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)
}

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) error
	RespondError(w http.ResponseWriter, status int, escapeHTML bool)
	RespondGzipJSON(w http.ResponseWriter, v any, status int, escapeHTML bool) error
	RespondGzipError(w http.ResponseWriter, status int, escapeHTML bool)
}

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 ID struct {
	// V is a unique identifier.
	// example: 123e4567-e89b-12d3-a456-426655440000
	// required:true
	V *string `json:"id"`
}

type Identifiable interface {
	GetID() Identifier
}

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 MongoCollection
	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 Logger interface {
	Log(ctx context.Context, l Level, v any, prefix string, msg ...string)
	Wrap(ctx context.Context, fn func() (any, error)) error
}

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

type MatchBehavior = string

type MetaOption[T any] func(*T)

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)
}

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
	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
}

type MongoOutCSChan = chan *ChangeEvent

type MongoPipeliner interface {
	Pipeline() mongo.Pipeline
}

type MongoSpecialized interface {
	Search(ctx context.Context, opts SearchOptions) (*RespSearch, error)
	WatchCollection(ctx context.Context, opts WatchCollectionOptions) error
	WatchDB(ctx context.Context, opts WatchDBOptions) error
	ProcessChangeStream(ctx context.Context, opts ProcessChangeStreamOptions) error
}

type MongoUtil interface {
	CreateCollections(ctx context.Context, db string, collections ...string) error
	CreateIndexes(ctx context.Context, db, collection string, e []IndexEntry) error
	CreateSearchIndexes(ctx context.Context, db, collection string, e []SearchIndexEntry) error
	NewTransactionSession(ctx context.Context) (context.Context, error)
}

type MongoVerb = string

type PaginationOptions struct {
	PageNumber int32
	PageSize   int32
}

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 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 RawCacheKey string

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

type RedisClient interface {
	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
}

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

type RequestOption func(*RequestOptions)

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

type RespAuthorize struct {
	// Code is the HTTP status code.
	// example:200
	// readOnly:true
	Code int `json:"code"`
}

type RespAuthorizeMany struct {
	// UnallowedEntities is the list of unauthorized entity IDs.
	// readOnly:true
	UnallowedEntities []ID `json:"unallowed_entities"`
}

type RespErr struct {
	// Code is the HTTP status code or custom error code.
	// example:400
	// readOnly:true
	Code int `json:"code"`
	// Message describes the error, written in Title Case.
	// example:Internal Server Error
	// readOnly:true
	Message string `json:"message"`
}

type RespMsg struct {
	// Message is the response message, written in Title Case.
	// example:Operation Completed
	// readOnly:true
	Message string `json:"message"`
}

type RespOperation struct {
	// Message describes the result of the operation, written in Title Case.
	// example:Record Created Successfully
	// readOnly:true
	Message string `json:"message"`
	// ID is the identifier of the affected resource.
	// example:5f7b1b9b9b9b9b9b9b9b9b9b
	// readOnly:true
	ID string `json:"_id"`
}

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

type SearchIndexEntry struct {
	Name        string
	Database    string
	Collection  string
	Fields      map[string]string
	VectorField *VectorSearchField
}

type SearchOptions struct {
	Filter        bson.M
	T             *TextOptions
	P             *PaginationOptions
	SortByKey     string
	SortDirection SortDirection
	Collection    MongoCollection
	Receiver      any
}

type Semaphore interface {
	Acquire()
	Release()
	WaitAll()
}

type SortDirection int

type TextOptions struct {
	IndexName string
	Query     string
	Fields    []string
}

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

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

type ToolOptions[C any] struct {
	Logger Logger
}

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 MongoCollection
	Receiver   any
	Pipeline   MongoPipeliner
	Options    *options.ChangeStreamOptionsBuilder
	LookupKey  string
	Output     MongoOutCSChan
}

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