funds_candles.go

// Package client includes types and methods to access the Funds / Candles endpoint. Retrieve historical price candles for any supported stock symbol.
//
// # Making Requests
//
// Use [FundCandlesRequest] to make requests to the endpoint using any of the three supported execution methods:
//
//	| Method     | Execution     | Return Type                 | Description                                                                                                |
//	|------------|---------------|-----------------------------|------------------------------------------------------------------------------------------------------------|
//	| **Get**    | Direct        | `[]Candle`                  | Directly returns a slice of `[]Candle`, facilitating individual access to each candle.                     |
//	| **Packed** | Intermediate  | `*FundCandlesResponse`     | Returns a packed `*FundCandlesResponse` object. Must be unpacked to access the `[]Candle` slice.          |
//	| **Raw**    | Low-level     | `*resty.Response`           | Provides the raw `*resty.Response` for maximum flexibility. Direct access to raw JSON or `*http.Response`. |
package client

import (
	"context"
	"fmt"

	"github.com/MarketDataApp/sdk-go/helpers/parameters"
	"github.com/MarketDataApp/sdk-go/models"
	"github.com/go-resty/resty/v2"
)

// FundCandlesRequest represents a request to the [/v1/funds/candles/] endpoint.
// It encapsulates parameters for resolution, symbol, date, and additional stock-specific parameters to be used in the request.
// This struct provides methods such as Resolution(), Symbol(), Date(), From(), To(), Countback(), AdjustSplits(), AdjustDividends(), Extended(), and Exchange() to set these parameters respectively.
//
// # Generated By
//
//   - FundCandles() *FundCandlesRequest: FundCandles creates a new *FundCandlesRequest and returns a pointer to the request allowing for method chaining.
//
// # Setter Methods
//
//   - Resolution(string) *FundCandlesRequest: Sets the resolution parameter for the request.
//   - Symbol(string) *FundCandlesRequest: Sets the symbol parameter for the request.
//   - Date(interface{}) *FundCandlesRequest: Sets the date parameter for the request.
//   - From(interface{}) *FundCandlesRequest: Sets the 'from' date parameter for the request.
//   - To(interface{}) *FundCandlesRequest: Sets the 'to' date parameter for the request.
//   - Countback(int) *FundCandlesRequest: Sets the countback parameter for the request.
//   - AdjustSplits(bool) *FundCandlesRequest: Sets the adjust splits parameter for the request.
//   - AdjustDividends(bool) *FundCandlesRequest: Sets the adjust dividends parameter for the request.
//   - Extended(bool) *FundCandlesRequest: Sets the extended hours data parameter for the request.
//   - Exchange(string) *FundCandlesRequest: Sets the exchange parameter for the request.
//
// # Execution Methods
//
// These methods are used to send the request in different formats or retrieve the data.
// They handle the actual communication with the API endpoint.
//
//   - Get() ([]Candle, error): Sends the request, unpacks the response, and returns the data in a user-friendly format.
//   - Packed() (*FundCandlesResponse, error): Returns a struct that contains equal-length slices of primitives. This packed response mirrors Market Data's JSON response.
//   - Raw() (*resty.Response, error): Sends the request as is and returns the raw HTTP response.
//
// [/v1/funds/candles/]: https://www.marketdata.app/docs/api/funds/candles
type FundCandlesRequest struct {
	*baseRequest
	stockCandleParams *parameters.StockCandleParams
	resolutionParams  *parameters.ResolutionParams
	symbolParams      *parameters.SymbolParams
	dateParams        *parameters.DateParams
}

// Resolution sets the resolution parameter for the FundCandlesRequest.
// This method is used to specify the granularity of the candle data to be retrieved.
//
// # Parameters
//
//   - string: A string representing the resolution to be set.
//
// # Returns
//
//   - *FundCandlesRequest: This method returns a pointer to the *FundCandlesRequest instance it was called on. This allows for method chaining.
func (cr *FundCandlesRequest) Resolution(q string) *FundCandlesRequest {
	if cr == nil {
		return nil
	}
	err := cr.resolutionParams.SetResolution(q)
	if err != nil {
		cr.Error = err
	}
	return cr
}

// Symbol sets the symbol parameter for the FundCandlesRequest.
// This method is used to specify the stock symbol for which candle data is requested.
//
// # Parameters
//
//   - string: A string representing the stock symbol to be set.
//
// # Returns
//
//   - *FundCandlesRequest: This method returns a pointer to the *FundCandlesRequest instance it was called on. This allows for method chaining.
func (fcr *FundCandlesRequest) Symbol(q string) *FundCandlesRequest {
	if fcr == nil {
		return nil
	}
	err := fcr.symbolParams.SetSymbol(q)
	if err != nil {
		fcr.Error = err
	}
	return fcr
}

// Date sets the date parameter for the FundCandlesRequest.
// This method is used to specify the date for which the stock candle data is requested.
//
// # Parameters
//
//   - interface{}: An interface{} representing the date to be set. It can be a string, a time.Time object, a Unix timestamp as an int, or any other type that the underlying dates package method can process.
//
// # Returns
//
//   - *FundCandlesRequest: This method returns a pointer to the *FundCandlesRequest instance it was called on. This allows for method chaining.
func (fcr *FundCandlesRequest) Date(q interface{}) *FundCandlesRequest {
	err := fcr.dateParams.SetDate(q)
	if err != nil {
		fcr.baseRequest.Error = err
	}
	return fcr
}

// From sets the 'from' date parameter for the FundCandlesRequest.
// This method is used to specify the starting point of the date range for which the stock candle data is requested.
//
// # Parameters
//
//   - interface{}: An interface{} representing the date to be set. It can be a string, a time.Time object, a Unix timestamp as an int, or any other type that the underlying dates package method can process.
//
// # Returns
//
//   - *FundCandlesRequest: This method returns a pointer to the *FundCandlesRequest instance it was called on. This allows for method chaining.
func (fcr *FundCandlesRequest) From(q interface{}) *FundCandlesRequest {
	err := fcr.dateParams.SetFrom(q)
	if err != nil {
		fcr.baseRequest.Error = err
	}
	return fcr
}

// To sets the 'to' date parameter for the FundCandlesRequest.
// This method is used to specify the ending point of the date range for which the stock candle data is requested.
//
// # Parameters
//
//   - interface{}: An interface{} representing the date to be set. It can be a string, a time.Time object, a Unix timestamp as an int, or any other type that the underlying dates package method can process.
//
// # Returns
//
//   - *FundCandlesRequest: This method returns a pointer to the *FundCandlesRequest instance it was called on
func (fcr *FundCandlesRequest) To(q interface{}) *FundCandlesRequest {
	err := fcr.dateParams.SetTo(q)
	if err != nil {
		fcr.baseRequest.Error = err
	}
	return fcr
}

// Countback sets the countback parameter for the FundCandlesRequest.
// This method specifies the number of candles to return, counting backwards from the 'to' date.
//
// # Parameters
//
//   - int: The number of candles to return.
//
// # Returns
//
//   - *FundCandlesRequest: This method returns a pointer to the *FundCandlesRequest instance it was called on. This allows for method chaining.
func (fcr *FundCandlesRequest) Countback(q int) *FundCandlesRequest {
	err := fcr.dateParams.SetCountback(q)
	if err != nil {
		fcr.baseRequest.Error = err
	}
	return fcr
}

// AdjustSplits sets the adjust splits parameter for the FundCandlesRequest.
// This method indicates whether the returned data should be adjusted for stock splits.
//
// # Parameters
//
//   - bool: Whether to adjust for splits.
//
// # Returns
//
//   - *FundCandlesRequest: This method returns a pointer to the *FundCandlesRequest instance it was called on. This allows for method chaining.
func (fcr *FundCandlesRequest) AdjustSplits(q bool) *FundCandlesRequest {
	if fcr == nil {
		return nil
	}
	fcr.stockCandleParams.SetAdjustSplits(q)
	return fcr
}

// getParams packs the CandlesRequest struct into a slice of interface{} and returns it.
func (fcr *FundCandlesRequest) getParams() ([]parameters.MarketDataParam, error) {
	if fcr == nil {
		return nil, fmt.Errorf("FundCandlesRequest is nil")
	}
	params := []parameters.MarketDataParam{fcr.dateParams, fcr.symbolParams, fcr.resolutionParams}
	return params, nil
}

// Raw executes the FundCandlesRequest with the provided context and returns the raw *resty.Response.
// This method returns the raw JSON or *http.Response for further processing without accepting an alternative MarketDataClient.
//
// # Parameters
//
//   - ctx context.Context: The context to use for the request execution.
//
// # Returns
//
//   - *resty.Response: The raw HTTP response from the executed request.
//   - error: An error object if the request fails due to execution errors.
func (fcr *FundCandlesRequest) Raw(ctx context.Context) (*resty.Response, error) {
	return fcr.baseRequest.Raw(ctx)
}

// Packed sends the FundCandlesRequest with the provided context and returns the FundCandlesResponse.
//
// # Parameters
//
//   - ctx context.Context: The context to use for the request execution.
//
// # Returns
//
//   - *FundCandlesResponse: A pointer to the FundCandlesResponse obtained from the request.
//   - error: An error object that indicates a failure in sending the request.
func (fcr *FundCandlesRequest) Packed(ctx context.Context) (*models.FundCandlesResponse, error) {
	if fcr == nil {
		return nil, fmt.Errorf("FundCandlesRequest is nil")
	}

	var fcrResp models.FundCandlesResponse
	_, err := fcr.baseRequest.client.getFromRequest(ctx, fcr.baseRequest, &fcrResp)
	if err != nil {
		return nil, err
	}

	return &fcrResp, nil
}

// Get sends the FundCandlesRequest with the provided context, unpacks the FundCandlesResponse, and returns a slice of StockCandle.
// It returns an error if the request or unpacking fails.
//
// # Parameters
//
//   - ctx context.Context: The context to use for the request execution.
//
// # Returns
//
//   - []Candle: A slice of []Candle containing the unpacked candle data from the response.
//   - error: An error object that indicates a failure in sending the request or unpacking the response.
func (fcr *FundCandlesRequest) Get(ctx context.Context) ([]models.Candle, error) {
	if fcr == nil {
		return nil, fmt.Errorf("FundCandlesRequest is nil")
	}

	// Use the Packed method to make the request
	fcrResp, err := fcr.Packed(ctx)
	if err != nil {
		return nil, err
	}

	// Unpack the data using the Unpack method in the response
	data, err := fcrResp.Unpack()
	if err != nil {
		return nil, err
	}

	return data, nil
}

// FundCandles initializes a new FundCandlesRequest with default parameters.
// This function prepares a request to fetch stock candle data. It sets up all necessary parameters
// and configurations to make the request ready to be sent.
//
// # Returns
//
//   - *FundCandlesRequest: A pointer to the newly created FundCandlesRequest instance. This instance contains all the necessary parameters set to their default values and is ready to have additional parameters set or to be sent.
func FundCandles() *FundCandlesRequest {
	baseReq := newBaseRequest()
	baseReq.path = endpoints[1]["funds"]["candles"]

	fcr := &FundCandlesRequest{
		baseRequest:      baseReq,
		dateParams:       &parameters.DateParams{},
		resolutionParams: &parameters.ResolutionParams{},
		symbolParams:     &parameters.SymbolParams{},
	}

	// Set the date to the current time
	baseReq.child = fcr

	return fcr
}