client

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 29, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultUserAgent = "go-api-sdk-apple/1.0.0"
	Version          = "1.0.0"
	DefaultBaseURL   = "https://itunes.apple.com"
)

DefaultUserAgent is the default User-Agent header value for all requests.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client interface {
	// NewRequest returns a RequestBuilder for constructing API requests.
	// Auth, retry, and logging are applied by the transport at execution time.
	NewRequest(ctx context.Context) *RequestBuilder

	// QueryBuilder returns a new query parameter builder instance.
	QueryBuilder() *QueryBuilder

	// GetLogger returns the configured zap logger instance.
	GetLogger() *zap.Logger
}

Client is the interface service implementations depend on. The Transport struct in this package satisfies this interface.

type ClientOption 

type ClientOption func(*Transport) error

ClientOption is a function type for configuring the Transport.

func WithBaseURL 

func WithBaseURL(urlStr string) ClientOption

WithBaseURL sets the base URL for API requests to a custom endpoint.

func WithClientCertificate 

func WithClientCertificate(certFile, keyFile string) ClientOption

WithClientCertificate sets a client certificate for mutual TLS authentication.

func WithCustomAgent 

func WithCustomAgent(customAgent string) ClientOption

WithCustomAgent appends a custom identifier to the default user agent. Format: "go-api-sdk-apple/1.0.0; <customAgent>"

func WithDebug 

func WithDebug() ClientOption

WithDebug enables debug mode for the HTTP client.

func WithGlobalHeader 

func WithGlobalHeader(key, value string) ClientOption

WithGlobalHeader sets a global header that will be included in all requests.

func WithGlobalHeaders 

func WithGlobalHeaders(headers map[string]string) ClientOption

WithGlobalHeaders sets multiple global headers at once.

func WithInsecureSkipVerify 

func WithInsecureSkipVerify() ClientOption

WithInsecureSkipVerify disables TLS certificate verification (USE WITH CAUTION). This should ONLY be used for testing/development with self-signed certificates.

func WithLogger 

func WithLogger(logger *zap.Logger) ClientOption

WithLogger sets a custom zap logger. Returns an error if logger is nil.

func WithMinTLSVersion 

func WithMinTLSVersion(minVersion uint16) ClientOption

WithMinTLSVersion sets the minimum TLS version for connections. Common values: tls.VersionTLS12, tls.VersionTLS13

func WithProxy 

func WithProxy(proxyURL string) ClientOption

WithProxy sets an HTTP proxy for all requests. Example: "http://proxy.company.com:8080" or "socks5://127.0.0.1:1080"

func WithRetryCount 

func WithRetryCount(retryCount int) ClientOption

WithRetryCount sets the maximum number of retries for failed requests.

func WithRetryMaxWaitTime 

func WithRetryMaxWaitTime(maxWait time.Duration) ClientOption

WithRetryMaxWaitTime sets the maximum wait time between retry attempts.

func WithRetryWaitTime 

func WithRetryWaitTime(retryWait time.Duration) ClientOption

WithRetryWaitTime sets the default wait time between retry attempts.

func WithRootCertificates 

func WithRootCertificates(pemFilePaths ...string) ClientOption

WithRootCertificates adds custom root CA certificates for server validation.

func WithTLSClientConfig 

func WithTLSClientConfig(tlsConfig *tls.Config) ClientOption

WithTLSClientConfig sets custom TLS configuration.

func WithTimeout 

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets the timeout for all HTTP requests.

func WithTransport 

func WithTransport(transport http.RoundTripper) ClientOption

WithTransport sets a custom HTTP transport (http.RoundTripper).

func WithUserAgent 

func WithUserAgent(userAgent string) ClientOption

WithUserAgent sets a custom user agent string for all requests.

type ErrorHandler 

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

ErrorHandler centralizes error handling for all iTunes API requests.

func NewErrorHandler 

func NewErrorHandler(logger *zap.Logger) *ErrorHandler

NewErrorHandler creates a new error handler.

func (*ErrorHandler) HandleError 

func (eh *ErrorHandler) HandleError(resp *resty.Response) error

HandleError processes a failed HTTP response and returns a descriptive error. The iTunes Search API does not return structured JSON error bodies; errors are indicated solely by HTTP status codes.

type QueryBuilder 

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

QueryBuilder provides a fluent interface for building query parameters.

func NewQueryBuilder 

func NewQueryBuilder() *QueryBuilder

NewQueryBuilder creates a new query builder.

func (*QueryBuilder) AddBool 

func (qb *QueryBuilder) AddBool(key string, value bool) *QueryBuilder

AddBool adds a boolean parameter.

func (*QueryBuilder) AddCustom 

func (qb *QueryBuilder) AddCustom(key, value string) *QueryBuilder

AddCustom adds a custom parameter with any value.

func (*QueryBuilder) AddIfNotEmpty 

func (qb *QueryBuilder) AddIfNotEmpty(key, value string) *QueryBuilder

AddIfNotEmpty adds a parameter only if the value is not empty.

func (*QueryBuilder) AddIfTrue 

func (qb *QueryBuilder) AddIfTrue(condition bool, key, value string) *QueryBuilder

AddIfTrue adds a parameter only if the condition is true.

func (*QueryBuilder) AddInt 

func (qb *QueryBuilder) AddInt(key string, value int) *QueryBuilder

AddInt adds an integer parameter if the value is greater than 0.

func (*QueryBuilder) AddInt64 

func (qb *QueryBuilder) AddInt64(key string, value int64) *QueryBuilder

AddInt64 adds an int64 parameter if the value is greater than 0.

func (*QueryBuilder) AddIntSlice 

func (qb *QueryBuilder) AddIntSlice(key string, values []int) *QueryBuilder

AddIntSlice adds an integer slice parameter as comma-separated values.

func (*QueryBuilder) AddString 

func (qb *QueryBuilder) AddString(key, value string) *QueryBuilder

AddString adds a string parameter if the value is not empty.

func (*QueryBuilder) AddStringSlice 

func (qb *QueryBuilder) AddStringSlice(key string, values []string) *QueryBuilder

AddStringSlice adds a string slice parameter as comma-separated values.

func (*QueryBuilder) AddTime 

func (qb *QueryBuilder) AddTime(key string, value time.Time) *QueryBuilder

AddTime adds a time parameter in RFC3339 format if the time is not zero.

func (*QueryBuilder) Build 

func (qb *QueryBuilder) Build() map[string]string

Build returns a copy of the final query parameter map.

func (*QueryBuilder) Clear 

func (qb *QueryBuilder) Clear() *QueryBuilder

Clear removes all parameters.

func (*QueryBuilder) Count 

func (qb *QueryBuilder) Count() int

Count returns the number of parameters.

func (*QueryBuilder) Get 

func (qb *QueryBuilder) Get(key string) string

Get retrieves a parameter value.

func (*QueryBuilder) Has 

func (qb *QueryBuilder) Has(key string) bool

Has checks if a parameter exists.

func (*QueryBuilder) IsEmpty 

func (qb *QueryBuilder) IsEmpty() bool

IsEmpty returns true if no parameters are set.

func (*QueryBuilder) Merge 

func (qb *QueryBuilder) Merge(other map[string]string) *QueryBuilder

Merge merges parameters from another map.

func (*QueryBuilder) Remove 

func (qb *QueryBuilder) Remove(key string) *QueryBuilder

Remove removes a parameter.

type RequestBuilder 

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

RequestBuilder constructs a single API request. The service layer owns the full request shape — headers, query params, result target — before handing the completed request to the executor (transport) which handles retry and logging.

Usage: 

var result SearchResponse
resp, err := s.client.NewRequest(ctx).
    SetHeader("Accept", constants.ApplicationJSON).
    SetQueryParams(params.Build()).
    SetResult(&result).
    Get(constants.EndpointSearch)

func NewMockRequestBuilder 

func NewMockRequestBuilder(ctx context.Context, fn func(path string, result any) (*resty.Response, error)) *RequestBuilder

NewMockRequestBuilder returns a RequestBuilder suitable for unit tests. The fn callback receives the path and result pointer and returns a pre-programmed response.

func NewMockRequestBuilderWithQueryCapture 

func NewMockRequestBuilderWithQueryCapture(ctx context.Context, fn func(path string, result any) (*resty.Response, error), queryStore *map[string]string) *RequestBuilder

NewMockRequestBuilderWithQueryCapture returns a RequestBuilder for unit tests that also captures query parameters into the provided map pointer.

func (*RequestBuilder) Get 

func (b *RequestBuilder) Get(path string) (*resty.Response, error)

Get executes the request as GET against path.

func (*RequestBuilder) GetBytes 

func (b *RequestBuilder) GetBytes(path string) (*resty.Response, []byte, error)

GetBytes executes a GET request and returns raw response bytes without JSON unmarshaling. Use for binary responses such as image assets.

func (*RequestBuilder) SetHeader 

func (b *RequestBuilder) SetHeader(key, value string) *RequestBuilder

SetHeader sets a request-level header. Empty values are ignored.

func (*RequestBuilder) SetQueryParam 

func (b *RequestBuilder) SetQueryParam(key, value string) *RequestBuilder

SetQueryParam adds a URL query parameter. Empty values are ignored.

func (*RequestBuilder) SetQueryParams 

func (b *RequestBuilder) SetQueryParams(params map[string]string) *RequestBuilder

SetQueryParams adds multiple URL query parameters in bulk. Empty values are ignored.

func (*RequestBuilder) SetResult 

func (b *RequestBuilder) SetResult(result any) *RequestBuilder

SetResult sets the target for JSON unmarshaling of a successful response. The iTunes Search API returns Content-Type: text/javascript so resty's automatic unmarshaling is skipped; the transport handles decoding directly.

type Transport 

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

Transport represents the iTunes Search API HTTP transport layer.

func NewTransport 

func NewTransport(options ...ClientOption) (*Transport, error)

NewTransport creates a new HTTP transport for the iTunes Search API. This is an internal function — users should use itunes.NewClient() instead.

func (*Transport) Close 

func (t *Transport) Close() error

Close closes the HTTP client and cleans up resources.

func (*Transport) GetHTTPClient 

func (t *Transport) GetHTTPClient() *resty.Client

GetHTTPClient returns the underlying HTTP client for testing purposes.

func (*Transport) GetLogger 

func (t *Transport) GetLogger() *zap.Logger

GetLogger returns the configured logger.

func (*Transport) NewRequest 

func (t *Transport) NewRequest(ctx context.Context) *RequestBuilder

NewRequest returns a new RequestBuilder for constructing API requests.

func (*Transport) QueryBuilder 

func (t *Transport) QueryBuilder() *QueryBuilder

QueryBuilder returns a new query builder instance.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.