stocks_bulkcandles.go

// Package client provides functionalities to interact with the Bulk Stock Candles endpoint.
// Get bulk historical price data for many stock symbols at once or even obtain a full market snapshot.
//
// # Making Requests
//
// Utilize the [BulkStockCandlesRequest] for querying the endpoint through one of the three available methods:
//
//	| Method     | Execution       | Return Type                 | Description                                                                                                             |
//	|------------|-----------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------|
//	| **Get**    | Direct          | `[]Candle`                  | Immediately fetches and returns a slice of `[]Candle`, allowing direct access to each candle's data.                    |
//	| **Packed** | Intermediate    | `*BulkStockCandlesResponse` | Delivers a `*StockCandlesResponse` object containing the data, which requires unpacking to access the `[]Candle` slice. |
//	| **Raw**    | Low-level       | `*resty.Response`           | Offers the unprocessed `*resty.Response` for those seeking full control and access to the 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"
)

// BulkStockCandlesRequest represents a request to the [/v1/stocks/bulkcandles/] 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
//
//   - BulkStockCandles() *BulkStockCandlesRequest: BulkStockCandles creates a new *BulkStockCandlesRequest and returns a pointer to the request allowing for method chaining.
//
// # Setter Methods
//
//   - Resolution(string) *BulkStockCandlesRequest: Sets the resolution parameter for the request.
//   - Symbol(string) *BulkStockCandlesRequest: Sets the symbol parameter for the request.
//   - Date(interface{}) *BulkStockCandlesRequest: Sets the date parameter for the request.
//   - AdjustSplits(bool) *BulkStockCandlesRequest: Sets the adjust splits parameter for the request.
//   - AdjustDividends(bool) *BulkStockCandlesRequest: Sets the adjust dividends parameter for the request.
//   - Extended(bool) *BulkStockCandlesRequest: Sets the extended hours data parameter for the request.
//   - Exchange(string) *BulkStockCandlesRequest: 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() (*BulkStockCandlesResponse, 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/stocks/bulkcandles/]: https://www.marketdata.app/docs/api/stocks/bulkcandles
type BulkStockCandlesRequest struct {
	*baseRequest
	stockCandleParams *parameters.StockCandleParams
	bulkStockParams   *parameters.BulkStockParams
	resolutionParams  *parameters.ResolutionParams
	dateParams        *parameters.DateParams
}

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

// Symbols sets the symbols parameter for the BulkStockCandlesRequest.
// This method is used to specify multiple stock symbols for which candle data is requested.
//
// # Parameters
//
//   - []string: A slice of []string representing the stock symbols to be set.
//
// # Returns
//
//   - *BulkStockCandlesRequest: This method returns a pointer to the *BulkStockCandlesRequest instance it was called on. This allows for method chaining.
func (cr *BulkStockCandlesRequest) Symbols(q []string) *BulkStockCandlesRequest {
	if cr == nil {
		return nil
	}
	err := cr.bulkStockParams.SetSymbols(q)
	if err != nil {
		cr.Error = err
	}
	return cr
}

// Date sets the date parameter for the BulkStockCandlesRequest.
// 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
//
//   - *BulkStockCandlesRequest: This method returns a pointer to the *BulkStockCandlesRequest instance it was called on. This allows for method chaining.
func (bscr *BulkStockCandlesRequest) Date(q interface{}) *BulkStockCandlesRequest {
	err := bscr.dateParams.SetDate(q)
	if err != nil {
		bscr.baseRequest.Error = err
	}
	return bscr
}

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

// Snapshot sets the snapshot parameter for the BulkStockCandlesRequest. This method is used to enable or disable the snapshot feature in the request and will result in all available tickers being returned in the response.
//
// # Parameters
//
//   - bool: A boolean value representing whether to enable or disable the snapshot feature.
//
// # Returns
//
//   - *BulkStockCandlesRequest: This method returns a pointer to the *BulkStockCandlesRequest instance it was called on. This allows for method chaining.
func (bscr *BulkStockCandlesRequest) Snapshot(q bool) *BulkStockCandlesRequest {
	if bscr == nil {
		return nil
	}
	bscr.bulkStockParams.SetSnapshot(q)
	return bscr
}

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

// Raw executes the request with the provided context and returns the raw *resty.Response.
// This method allows for obtaining the raw JSON or *http.Response directly from the executed request.
//
// # Parameters
//
//   - ctx context.Context: The context to use for the request execution.
//
// # Returns
//
//   - *resty.Response: The raw response from the executed request.
//   - error: An error object if the request is nil or if an error occurs during the request execution.
func (bscr *BulkStockCandlesRequest) Raw(ctx context.Context) (*resty.Response, error) {
	return bscr.baseRequest.Raw(ctx)
}

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

	var scrResp models.BulkStockCandlesResponse
	_, err := bscr.baseRequest.client.getFromRequest(ctx, bscr.baseRequest, &scrResp)
	if err != nil {
		return nil, err
	}

	return &scrResp, nil
}

// Get sends the BulkStockCandlesRequest with the provided context, unpacks the StockCandlesResponse, and returns a slice of []Candle.
// It returns an error if the request or unpacking fails.
//
// # Parameters
//
//   - ctx context.Context: The context to use for the request execution.
//
// # Returns
//
//   - []models.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 (bscr *BulkStockCandlesRequest) Get(ctx context.Context) ([]models.Candle, error) {
	if bscr == nil {
		return nil, fmt.Errorf("BulkStockCandlesRequest is nil")
	}

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

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

	return data, nil
}

// BulkStockCandles initializes a new BulkStockCandlesRequest with default parameters.
// This function prepares a request to fetch bulk stock candles data. It sets up all necessary parameters
// and configurations to make the request ready to be sent. The function accepts a variadic parameter
// that allows passing an optional MarketDataClient. If a client is provided, it will be used for the request;
// otherwise, a default client is initialized and used.
//
// # Parameters
//
//   - ...*MarketDataClient: A variadic parameter that can accept zero or one MarketDataClient pointer. This allows for the optional customization of the client used for the request. If no client is provided, a default client is initialized and used.
//
// # Returns
//
//   - *BulkStockCandlesRequest: A pointer to the newly created BulkStockCandlesRequest 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 BulkStockCandles(client ...*MarketDataClient) *BulkStockCandlesRequest {
	baseReq := newBaseRequest(client...)
	baseReq.path = endpoints[1]["stocks"]["bulkcandles"]

	bscr := &BulkStockCandlesRequest{
		baseRequest:       baseReq,
		dateParams:        &parameters.DateParams{},
		resolutionParams:  &parameters.ResolutionParams{},
		bulkStockParams:   &parameters.BulkStockParams{},
		stockCandleParams: &parameters.StockCandleParams{},
	}

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

	return bscr
}