options_quotes.go

// Package client provides functionalities to interact with the Options Quotes endpoint.
// Retrieve an option quote for a given option symbol.
//
// # Making Requests
//
// Utilize [OptionQuoteRequest] for querying the endpoint through one of the three available methods:
//
//	| Method     | Execution       | Return Type                  | Description                                                                                                                |
//	|------------|-----------------|------------------------------|----------------------------------------------------------------------------------------------------------------------------|
//	| **Get**    | Direct          | `[]OptionQuote`              | Immediately fetches a slice of `[]OptionQuote`, allowing direct access to the quote data.                                  |
//	| **Packed** | Intermediate    | `*OptionQuotesResponse`      | Delivers a `*OptionQuotesResponse` object containing the data, which requires unpacking to access the `OptionQuote` data.  |
//	| **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"
)

// OptionQuotesRequest represents a request to the [/v1/options/quotes/] endpoint for retrieving options quotes.
// It encapsulates parameters for symbol, expiration, and strike to be used in the request.
//
// # Generated By
//
//   - OptionQuotes() *OptionQuoteRequest: OptionQuotes creates a new *OptionQuoteRequest and returns a pointer to the request allowing for method chaining.
//
// # Setter Methods
//
//   - OptionSymbol(string) *OptionQuoteRequest: Sets the symbol parameter for the request.
//   - Date(interface{}) *OptionQuoteRequest: Sets the date parameter for the request, accepting flexible date input.
//   - From(interface{}) *OptionQuoteRequest: Sets the start date of a date range for the request, accepting flexible date input.
//   - To(interface{}) *OptionQuoteRequest: Sets the end date of a date range for the request, accepting flexible date input.
//
// # 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() ([]OptionQuote, error): Sends the request, unpacks the response, and returns the data in a user-friendly format.
//   - Packed() (*OptionQuotesResponse, 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/options/quotes/]: https://www.marketdata.app/docs/api/options/quotes
type OptionQuoteRequest struct {
	*baseRequest
	symbolParams *parameters.SymbolParams
	dateParams   *parameters.DateParams
}

// OptionSymbol sets the symbol parameter for the OptionQuotesRequest.
// This method is used to specify the symbol of the option for which the quote is requested.
//
// # Parameters
//
//   - string: A string representing the option symbol to be set.
//
// # Returns
//
//   - *OptionQuotesRequest: This method returns a pointer to the OptionQuotesRequest instance it was called on, allowing for method chaining.
func (oqr *OptionQuoteRequest) OptionSymbol(q string) *OptionQuoteRequest {
	if oqr == nil {
		return nil
	}
	err := oqr.symbolParams.SetSymbol(q)
	if err != nil {
		oqr.Error = err
	}
	return oqr
}

// Date sets the date parameter for the OptionQuotesRequest.
// This method is used to specify the date for which the option quote is requested.
// It allows for flexibility in the type of date input (e.g., string, time.Time) through the use of an interface{} parameter.
//
// # Parameters
//
//   - interface{}: The date to be set. The actual type accepted can vary (e.g., string, time.Time, int for Unix timestamp).
//
// # Returns
//
//   - *OptionQuotesRequest: This method returns a pointer to the OptionQuotesRequest instance it was called on, allowing for method chaining. If the receiver (*OptionQuotesRequest) is nil, it returns nil to prevent a panic.
func (oqr *OptionQuoteRequest) Date(q interface{}) *OptionQuoteRequest {
	if oqr.dateParams == nil {
		oqr.dateParams = &parameters.DateParams{}
	}
	err := oqr.dateParams.SetDate(q)
	if err != nil {
		oqr.Error = err
	}
	return oqr
}

// From sets the from parameter for the OptionQuotesRequest.
// This method is used to specify the start date of a date range for which the option quote is requested.
// Similar to the Date method, it accepts a flexible date input through an interface{} parameter.
//
// # Parameters
//
//   - interface{}: The start date of the range to be set. The actual type accepted can vary.
//
// # Returns
//
//   - *OptionQuotesRequest: This method returns a pointer to the OptionQuotesRequest instance it was called on, allowing for method chaining. If the receiver (*OptionQuotesRequest) is nil, it returns nil to prevent a panic.
func (oqr *OptionQuoteRequest) From(q interface{}) *OptionQuoteRequest {
	if oqr.dateParams == nil {
		oqr.dateParams = &parameters.DateParams{}
	}
	err := oqr.dateParams.SetFrom(q)
	if err != nil {
		oqr.Error = err
	}
	return oqr
}

// To sets the to parameter for the OptionQuotesRequest.
// This method is used to specify the end date of a date range for which the option quote is requested.
// It accepts a flexible date input through an interface{} parameter, similar to the From method.
//
// # Parameters
//
//   - interface{}: The end date of the range to be set. The actual type accepted can vary, depending on implementation.
//
// # Returns
//
//   - *OptionQuotesRequest: This method returns a pointer to the OptionQuotesRequest instance it was called on, allowing for method chaining. If the receiver (*OptionQuotesRequest) is nil, it returns nil to prevent a panic.
func (oqr *OptionQuoteRequest) To(q interface{}) *OptionQuoteRequest {
	if oqr.dateParams == nil {
		oqr.dateParams = &parameters.DateParams{}
	}
	err := oqr.dateParams.SetTo(q)
	if err != nil {
		oqr.Error = err
	}
	return oqr
}

// getParams packs the OptionQuotesRequest struct into a slice of interface{} and returns it.
// This method is used to gather all the parameters set in the OptionQuotesRequest into a single slice for easier manipulation and usage in subsequent requests.
//
// # Returns
//
//   - []parameters.MarketDataParam: A slice containing all the parameters set in the OptionQuotesRequest.
//   - error: An error object indicating failure to pack the parameters, nil if successful.
func (oqr *OptionQuoteRequest) getParams() ([]parameters.MarketDataParam, error) {
	if oqr == nil {
		return nil, fmt.Errorf("OptionQuoteRequest is nil")
	}
	params := []parameters.MarketDataParam{oqr.symbolParams, oqr.dateParams}
	return params, nil
}

// Raw executes the OptionQuoteRequest with the provided context and returns the raw *resty.Response.
// This method uses the default client for the request. The *resty.Response can be used to access the raw JSON or *http.Response directly.
//
// # 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 OptionQuoteRequest is nil or if an error occurs during the request execution.
func (oqr *OptionQuoteRequest) Raw(ctx context.Context) (*resty.Response, error) {
	return oqr.baseRequest.Raw(ctx)
}

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

	var oqrResp models.OptionQuotesResponse
	_, err := oqr.baseRequest.client.getFromRequest(ctx, oqr.baseRequest, &oqrResp)
	if err != nil {
		return nil, err
	}

	return &oqrResp, nil
}

// Get sends the OptionQuoteRequest with the provided context, unpacks the OptionQuotesResponse, and returns a slice of OptionQuote.
// It returns an error if the request or unpacking fails. This method uses the default client for the request.
//
// # Parameters
//
//   - ctx context.Context: The context to use for the request execution.
//
// # Returns
//
//   - []models.OptionQuote: A slice of OptionQuote containing the unpacked options quotes data from the response.
//   - error: An error object that indicates a failure in sending the request or unpacking the response.
func (oqr *OptionQuoteRequest) Get(ctx context.Context) ([]models.OptionQuote, error) {
	if oqr == nil {
		return nil, fmt.Errorf("OptionQuoteRequest is nil")
	}

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

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

	return data, nil
}

// OptionQuotes creates a new OptionQuotesRequest and uses the default client.
//
// # Returns
//
//   - *OptionQuotesRequest: A pointer to the newly created OptionQuotesRequest with default parameters.
func OptionQuote() *OptionQuoteRequest {
	baseReq := newBaseRequest()
	baseReq.path = endpoints[1]["options"]["quotes"]

	oqr := &OptionQuoteRequest{
		baseRequest:  baseReq,
		symbolParams: &parameters.SymbolParams{},
	}

	baseReq.child = oqr

	return oqr
}