options_expirations.go

// Package client provides functionalities to interact with the Options Expirations endpoint.
// Get a list of current or historical option expiration dates for an underlying symbol.
//
// # Making Requests
//
// Utilize [OptionsExpirationsRequest] for querying the endpoint through one of the three available methods:
//
//	| Method     | Execution       | Return Type                   | Description                                                                                                                      |
//	|------------|-----------------|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
//	| **Get**    | Direct          | `[]time.Time`                 | Immediately fetches and returns a slice of `[]time.Time`, allowing direct access to each expiration date.                        |
//	| **Packed** | Intermediate    | `*OptionsExpirationsResponse` | Delivers a `*OptionsExpirationsResponse` object containing the data, which requires unpacking to access the `[]time.Time` 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"
	"time"

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

// OptionsExpirationsRequest represents a request for retrieving options expirations data from the [/v1/options/expirations/] endpoint.
// It encapsulates parameters for the underlying symbol and strike price to be used in the request.
// This struct provides methods such as UnderlyingSymbol() and Strike() to set these parameters respectively.
//
// # Generated By
//
//   - OptionsExpirations() *OptionsExpirationsRequest: OptionsExpirations creates a new *OptionsExpirationsRequest and returns a pointer to the request allowing for method chaining.
//
// # Setter Methods
//
//   - Strike(float64) *OptionsExpirationsRequest: Sets the strike price parameter for the options expirations request.
//   - UnderlyingSymbol(string) *OptionsExpirationsRequest: Sets the underlying symbol parameter for the options expirations 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() ([]time.Time, error): Sends the request, unpacks the response, and returns []time.Time allowing direct-access to the data.
//   - Packed() (*OptionsExpirationsResponse, 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/expirations/]: https://www.marketdata.app/docs/api/options/expirations
type OptionsExpirationsRequest struct {
	*baseRequest
	underlyingSymbol *parameters.SymbolParams
	strike           *parameters.OptionParams
	dateParams       *parameters.DateParams
}

// Date sets the date parameter for the OptionsExpirationsRequest.
// This method is used to specify the date for which the options expirations are requested.
// It modifies the dateParams field of the OptionsExpirationsRequest instance to store the date value.
//
// # Parameters
//
//   - interface{}: An interface{} that represents the starting date. It can be a string, a time.Time object, a Unix timestamp or any other type that the underlying dates package can process.
//
// # Returns
//
//   - *OptionsExpirationsRequest: This method returns a pointer to the OptionsExpirationsRequest instance it was called on. This allows for method chaining. If the receiver (*OptionsExpirationsRequest) is nil, it returns nil to prevent a panic.
func (oer *OptionsExpirationsRequest) Date(q interface{}) *OptionsExpirationsRequest {
	if oer.dateParams == nil {
		oer.dateParams = &parameters.DateParams{}
	}
	err := oer.dateParams.SetDate(q)
	if err != nil {
		oer.Error = err
	}
	return oer
}

// Strike sets the strike price parameter for the OptionsExpirationsRequest.
// This method is used to specify a particular strike price for filtering the options expirations.
//
// # Parameters
//
//   - float64: A float64 representing the strike price to be set.
//
// # Returns
//
//   - *OptionsExpirationsRequest: This method returns a pointer to the OptionsExpirationsRequest instance it was called on, allowing for method chaining.
func (o *OptionsExpirationsRequest) Strike(strike float64) *OptionsExpirationsRequest {
	if o.strike == nil {
		o.strike = &parameters.OptionParams{}
	}
	if err := o.strike.SetStrike(strike); err != nil {
		o.Error = err
	}
	return o
}

// UnderlyingSymbol sets the underlying symbol parameter for the OptionsExpirationsRequest.
// This method is used to specify the symbol of the underlying asset for which the options expirations are requested.
//
// # Parameters
//
//   - string: A string representing the underlying symbol to be set.
//
// # Returns
//
//   - *OptionsExpirationsRequest: This method returns a pointer to the OptionsExpirationsRequest instance it was called on, allowing for method chaining.
func (o *OptionsExpirationsRequest) UnderlyingSymbol(symbol string) *OptionsExpirationsRequest {
	if err := o.underlyingSymbol.SetSymbol(symbol); err != nil {
		o.Error = err
	}
	return o
}

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

// Raw executes the OptionsExpirationsRequest 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 directly access the raw JSON or *http.Response.
//
// # Parameters
//
//   - ctx context.Context: The context to use for the request execution.
//
// # Returns
//
//   - *resty.Response: The raw HTTP response from the executed OptionsExpirationsRequest.
//   - error: An error object if the OptionsExpirationsRequest is nil or if an error occurs during the request execution.
func (oer *OptionsExpirationsRequest) Raw(ctx context.Context) (*resty.Response, error) {
	return oer.baseRequest.Raw(ctx)
}

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

	var oResp models.OptionsExpirationsResponse
	_, err := o.baseRequest.client.getFromRequest(ctx, o.baseRequest, &oResp)
	if err != nil {
		return nil, err
	}

	return &oResp, nil
}

// Get sends the OptionsExpirationsRequest with the provided context, unpacks the OptionsExpirationsResponse, and returns a slice of time.Time.
// 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
//
//   - []time.Time: A slice of time.Time containing the unpacked options expirations data from the response.
//   - error: An error object that indicates a failure in sending the request or unpacking the response.
func (o *OptionsExpirationsRequest) Get(ctx context.Context) ([]time.Time, error) {
	if o == nil {
		return nil, fmt.Errorf("OptionsExpirationsRequest is nil")
	}

	oResp, err := o.Packed(ctx)
	if err != nil {
		return nil, err
	}

	data, err := oResp.Unpack()
	if err != nil {
		return nil, err
	}

	return data, nil
}

// OptionsExpirations creates a new OptionsExpirationsRequest with the default client.
//
// # Returns
//
//   - *OptionsExpirationsRequest: A pointer to the newly created OptionsExpirationsRequest with default parameters.
func OptionsExpirations() *OptionsExpirationsRequest {
	baseReq := newBaseRequest()
	baseReq.path = endpoints[1]["options"]["expirations"]

	oer := &OptionsExpirationsRequest{
		baseRequest:      baseReq,
		underlyingSymbol: &parameters.SymbolParams{},
		strike:           &parameters.OptionParams{},
		dateParams:       &parameters.DateParams{},
	}

	baseReq.child = oer

	return oer
}