api

type API struct {
	Client Client
	// contains filtered or unexported fields
}

type Afterable interface {
	// After returns the value of the "after" parameter that should be used for the next page of pagination. If this
	// returns nil, then it is assumed that pagination has finished.
	After() any
}

type Attr func(client Client) (string, any)

type Binding[ResT any, RetT any] interface {
	// Request constructs the Request that will be sent to the API using a Client. The function can take multiple
	// arguments that should be handled accordingly and passed to the Request. These are the same arguments passed in
	// from the Binding.Execute method.
	Request(args ...any) (request Request)
	// GetRequestMethod returns the BindingRequestMethod that is called when Binding.Request is called. This is useful
	// when you want to reuse a BindingRequestMethod for another Binding.
	GetRequestMethod() BindingRequestMethod[ResT, RetT]

	// ResponseWrapper should create a wrapper for the given response type (ResT) and return the pointer reflect.Value to
	// this wrapper. Client.Run will then unmarshal the response into this wrapper instance. This is useful for APIs
	// that return the actual resource (of type ResT) within a structure that is nested within the returned response.
	ResponseWrapper(args ...any) (responseWrapper reflect.Value, err error)
	// GetResponseWrapperMethod returns the BindingResponseWrapperMethod that is called when Binding.Response is called.
	// This is helpful when you want to reuse a BindingResponseWrapperMethod for another Binding.
	GetResponseWrapperMethod() BindingResponseWrapperMethod[ResT, RetT]
	// SetResponseWrapperMethod sets the BindingResponseWrapperMethod that is called when Binding.ResponseWrapper is
	// called. This enables chaining when creating a Binding through NewBindingChain.
	SetResponseWrapperMethod(method BindingResponseWrapperMethod[ResT, RetT]) Binding[ResT, RetT]

	// ResponseUnwrapped should unwrap the response that was made to the API after Client.Run. This should return an
	// instance of the ResT type.
	ResponseUnwrapped(responseWrapper reflect.Value, args ...any) (response ResT, err error)
	// GetResponseUnwrappedMethod returns the BindingResponseUnwrappedMethod that is called when
	// Binding.ResponseUnwrapped is called. This is useful when you want to reuse a BindingResponseUnwrappedMethod for
	// another Binding.
	GetResponseUnwrappedMethod() BindingResponseUnwrappedMethod[ResT, RetT]
	// SetResponseUnwrappedMethod sets the BindingResponseUnwrappedMethod that is called when Binding.ResponseWrapper is
	// called. This enables chaining when creating a Binding through NewBindingChain.
	SetResponseUnwrappedMethod(method BindingResponseUnwrappedMethod[ResT, RetT]) Binding[ResT, RetT]

	// Response converts the response from the API from the type ResT to the type RetT. It should also be passed
	// additional arguments from Execute.
	Response(response ResT, args ...any) RetT
	// GetResponseMethod returns the BindingResponseMethod that is called when Binding.Response is called. This is
	// useful when you want to reuse a BindingResponseMethod for another Binding.
	GetResponseMethod() BindingResponseMethod[ResT, RetT]
	// SetResponseMethod sets the BindingResponseMethod that is called when Binding.Response is called. This enables
	// chaining when creating a Binding through NewBindingChain.
	SetResponseMethod(method BindingResponseMethod[ResT, RetT]) Binding[ResT, RetT]

	// Params returns the BindingParam(s) that this Binding's Execute method takes. These BindingParam(s) are used for
	// type-checking each argument passed to Execute. If no BindingParam(s) are returned by Params, then no
	// type-checking will be performed in Execute.
	Params() []BindingParam
	// GetParamsMethod returns the BindingParamsMethod that is called when Binding.Params is called. This is useful when
	// you want to reuse a BindingParamsMethod for another Binding.
	GetParamsMethod() BindingParamsMethod[ResT, RetT]
	// SetParamsMethod sets the BindingParamsMethod that is called when Binding.Params is called. This enables chaining
	// when creating a Binding through NewBindingChain.
	SetParamsMethod(method BindingParamsMethod[ResT, RetT]) Binding[ResT, RetT]
	// ArgsFromStrings parses the given list of string arguments into their required types for the Params of the
	// Binding.
	ArgsFromStrings(args ...string) ([]any, error)

	// Execute will execute the BindingWrapper using the given Client and arguments. It returns the response converted to RetT
	// using the Response method, as well as an error that could have occurred.
	Execute(client Client, args ...any) (response RetT, err error)

	// Paginated returns whether the Binding is paginated.
	Paginated() bool
	// SetPaginated sets whether the Binding is paginated. It also returns the Binding so that this method can be
	// chained with others when creating a new Binding through NewBindingChain.
	SetPaginated(paginated bool) Binding[ResT, RetT]

	// Name returns the name of the Binding. When using NewBinding, NewBindingChain, or NewWrappedBinding, this will be
	// set to whatever is returned by the following line of code:
	//  fmt.Sprintf("%T", binding)
	// Where "binding" is the referred to Binding.
	Name() string
	// SetName sets the name of the Binding. This returns the Binding so it can be chained.
	SetName(name string) Binding[ResT, RetT]

	// Attrs returns the attributes for the Binding. These can be passed in when creating a Binding through the
	// NewBinding function. Attrs can be used in any of the implemented functions, and they are also passed to
	// Client.Run when Execute-ing the Binding.
	Attrs() map[string]any
	// AddAttrs adds the given Attr functions to the Binding. Each given Attr will attempt to be evaluated when AddAttrs
	// is called. However, when evaluating these Attr functions the Client param will be passed in as nil. If some of
	// these can't be evaluated, due to the lack of the Client param, then these unevaluated Attr functions will also be
	// evaluated at the start of the Binding.Execute method, this time with the Client that is passed to that method.
	AddAttrs(attrs ...Attr) Binding[ResT, RetT]
}

type BindingExecuteMethod[ResT any, RetT any] func(binding Binding[ResT, RetT], client Client, args ...any) (response RetT, err error)

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

type BindingParamsMethod[ResT any, RetT any] func(binding Binding[ResT, RetT]) []BindingParam

type BindingRequestMethod[ResT any, RetT any] func(binding Binding[ResT, RetT], args ...any) (request Request)

type BindingResponseMethod[ResT any, RetT any] func(binding Binding[ResT, RetT], response ResT, args ...any) RetT

type BindingResponseUnwrappedMethod[ResT any, RetT any] func(binding Binding[ResT, RetT], responseWrapper reflect.Value, args ...any) (response ResT, err error)

type BindingResponseWrapperMethod[ResT any, RetT any] func(binding Binding[ResT, RetT], args ...any) (responseWrapper reflect.Value, err error)

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

type Client interface {
	// Run should execute the given Request and unmarshal the response into the given response interface. It is usually
	// called from Binding.Execute to execute a Binding, hence why we also pass in the name of the Binding (from
	// Binding.Name).
	Run(ctx context.Context, bindingName string, attrs map[string]any, req Request, res any) error
}

type GraphQLRequest struct {
	*graphql.Request
}

type HTTPRequest struct {
	*http.Request
}

type Lenable interface {
	Len() int
}

type Mergeable interface {
	// Merge merges the given value into the Mergeable instance.
	Merge(similar any) error
	// HasMore returns true if there are more pages to fetch.
	HasMore() bool
}

type Paginator[ResT any, RetT any] interface {
	// Continue returns whether the Paginator can continue fetching more pages for the Binding. This will also return true
	// when the Paginator is on the first page.
	Continue() bool
	// Page fetches the current page of results.
	Page() RetT
	// Next fetches the next page from the Binding. The result can be fetched using the Page method.
	Next() error
	// All returns all the return values for the Binding at once.
	All() (RetT, error)
	// Pages fetches the given number of pages from the Binding whilst appending each response slice together.
	Pages(pages int) (RetT, error)
	// Until keeps fetching pages until there are no more pages, or the given predicate function returns false.
	Until(predicate func(paginator Paginator[ResT, RetT], pages RetT) bool) (RetT, error)
}

type RateLimit interface {
	// Reset returns the time at which the RateLimit resets.
	Reset() time.Time
	// Remaining returns the number of requests remaining/resources that can be fetched for this RateLimit.
	Remaining() int
	// Used returns the number of requests used/resources fetched so far for this RateLimit.
	Used() int
	// Type is the type of the RateLimit. See RateLimitType for documentation.
	Type() RateLimitType
}

type RateLimitType int

type RateLimitedClient interface {
	// Client should implement a Client.Run method that sets an internal sync.Map of RateLimit(s).
	Client
	// RateLimits returns the sync.Map of Binding names to RateLimit instances.
	RateLimits() *sync.Map
	// AddRateLimit should add a RateLimit to the internal sync.Map within the Client. It should check if the Binding of
	// the given name already has a RateLimit, and whether the RateLimit.Reset lies after the currently set RateLimit
	// for that Binding.
	AddRateLimit(bindingName string, rateLimit RateLimit)
	// LatestRateLimit should return the latest RateLimit for the Binding of the given name. If multiple Binding(s)
	// share the same RateLimit(s) then this can also be encoded into this method.
	LatestRateLimit(bindingName string) RateLimit
	// Log should be implemented for debugging purposes. If you do not require it then you can define it but have it do
	// nothing.
	Log(string)
}

type Request interface {
	// Header returns a reference to the http.Header for the underlying http.Request that can be modified in any way
	// necessary by Binding.Execute.
	Header() *http.Header
}

type Schema map[string]BindingWrapper