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: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultUserAgent = "go-api-sdk-apple/1.0.0"
	Version          = "1.0.0"
)

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

View Source 
const (
	DefaultBaseURL            = "https://api-business.apple.com"
	DefaultOAuthTokenEndpoint = "https://account.apple.com/auth/oauth2/v2/token"
	DefaultJWTAudience        = "appstoreconnect-v1"
	ScopeBusinessAPI          = "business.api"
	ScopeSchoolAPI            = "school.api"
)

The following constants are re-exported from the constants package so that existing code and tests in the client package can reference them without importing the constants package directly.

Variables

View Source 
var (
	ErrNoNextPage      = fmt.Errorf("no next page available")
	ErrInvalidCursor   = fmt.Errorf("invalid pagination cursor")
	ErrAuthFailed      = fmt.Errorf("authentication failed")
	ErrRateLimited     = fmt.Errorf("rate limit exceeded")
	ErrInvalidResponse = fmt.Errorf("invalid response format")
)

Common error types

Functions

func HasNextPage 

func HasNextPage(links *Links) bool

HasNextPage checks if there is a next page available.

func HasPrevPage 

func HasPrevPage(links *Links) bool

HasPrevPage checks if there is a previous page available.

func LoadPrivateKeyFromEnv 

func LoadPrivateKeyFromEnv() (any, error)

LoadPrivateKeyFromEnv loads a private key from the environment variable APPLE_PRIVATE_KEY_PATH

func LoadPrivateKeyFromFile 

func LoadPrivateKeyFromFile(filePath string) (any, error)

LoadPrivateKeyFromFile loads a private key (RSA or ECDSA) from a PEM file

func ParsePrivateKey 

func ParsePrivateKey(keyData []byte) (any, error)

ParsePrivateKey parses a private key (RSA or ECDSA) from PEM-encoded data

func ValidatePrivateKey 

func ValidatePrivateKey(privateKey any) error

ValidatePrivateKey validates that the private key is suitable for JWT signing

Types

type APIError 

type APIError struct {
	ID     string          `json:"id,omitempty"`
	Status string          `json:"status"`
	Code   string          `json:"code"`
	Title  string          `json:"title"`
	Detail string          `json:"detail"`
	Source *APIErrorSource `json:"source,omitempty"`
	Links  *ErrorLinks     `json:"links,omitempty"`
	Meta   *APIErrorMeta   `json:"meta,omitempty"`
}

APIError represents a single error from the Apple Business Manager API

func (*APIError) Error 

func (e *APIError) Error() string

type APIErrorMeta 

type APIErrorMeta struct {
	// Can contain any key-value pairs as specified in the API documentation
	AdditionalProperties map[string]any `json:"-"`
}

APIErrorMeta contains additional error metadata

func (*APIErrorMeta) MarshalJSON 

func (m *APIErrorMeta) MarshalJSON() ([]byte, error)

MarshalJSON implements custom marshaling for APIErrorMeta

func (*APIErrorMeta) UnmarshalJSON 

func (m *APIErrorMeta) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshaling for APIErrorMeta

type APIErrorResponse 

type APIErrorResponse struct {
	ErrorCode string         `json:"error_code"`
	Message   string         `json:"message"`
	Details   map[string]any `json:"details,omitempty"`
}

APIErrorResponse represents the legacy error structure (keeping for backward compatibility)

type APIErrorSource 

type APIErrorSource struct {
	JsonPointer *JsonPointer `json:"jsonPointer,omitempty"`
	Parameter   *Parameter   `json:"parameter,omitempty"`
}

APIErrorSource represents the source of an error (JsonPointer or Parameter)

type APIKeyAuth 

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

APIKeyAuth implements simple API key authentication

func NewAPIKeyAuth 

func NewAPIKeyAuth(apiKey, header string) *APIKeyAuth

NewAPIKeyAuth creates a new API key authentication provider

func (*APIKeyAuth) ApplyAuth 

func (a *APIKeyAuth) ApplyAuth(req *resty.Request) error

ApplyAuth applies API key authentication to the request

type APIResponse 

type APIResponse[T any] struct {
	Data  []T   `json:"data"`
	Meta  Meta  `json:"meta"`
	Links Links `json:"links"`
}

APIResponse represents the standard API response structure.

type AuthProvider 

type AuthProvider interface {
	ApplyAuth(req *resty.Request) error
}

AuthProvider interface for different authentication methods

type Client 

type Client interface {
	// NewRequest returns a RequestBuilder that the service layer uses to
	// construct a complete request — headers, body, query params, result
	// target — before executing it via Get/Post/Put/Patch/Delete/GetPaginated.
	// Auth, retry, and concurrency limiting are applied by the transport at
	// execution time.
	NewRequest(ctx context.Context) *RequestBuilder

	// QueryBuilder returns a new query parameter builder instance.
	// Use this to build complex query parameter sets before passing
	// them to SetQueryParams on the RequestBuilder.
	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 added in v0.3.1 

type ClientOption func(*Transport) error

ClientOption is a function type for configuring the Transport.

func WithAPIVersion added in v0.3.1 

func WithAPIVersion(version string) ClientOption

WithAPIVersion sets a custom API version if needed for future API versions.

func WithAudience added in v0.3.1 

func WithAudience(audience string) ClientOption

WithAudience sets a custom JWT audience (default: "appstoreconnect-v1").

func WithAuth 

func WithAuth(auth AuthProvider) ClientOption

WithAuth sets the authentication provider for the client.

func WithBaseURL 

func WithBaseURL(urlStr string) ClientOption

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

func WithClientCertificate added in v0.3.1 

func WithClientCertificate(certFile, keyFile string) ClientOption

WithClientCertificate sets a client certificate for mutual TLS authentication. Loads certificate from PEM-encoded files.

func WithClientCertificateFromString added in v0.3.1 

func WithClientCertificateFromString(certPEM, keyPEM string) ClientOption

WithClientCertificateFromString sets a client certificate from PEM-encoded strings.

func WithCustomAgent added in v0.3.1 

func WithCustomAgent(customAgent string) ClientOption

WithCustomAgent allows appending 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 WithErrorHandler 

func WithErrorHandler(handler *ErrorHandler) ClientOption

WithErrorHandler sets a custom error handler.

func WithGlobalHeader added in v0.3.1 

func WithGlobalHeader(key, value string) ClientOption

WithGlobalHeader sets a global header that will be included in all requests. Per-request headers will override global headers with the same key.

func WithGlobalHeaders added in v0.3.1 

func WithGlobalHeaders(headers map[string]string) ClientOption

WithGlobalHeaders sets multiple global headers at once.

func WithInsecureSkipVerify added in v0.3.1 

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 can be used to configure a custom logger.

func WithMinTLSVersion added in v0.3.1 

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. The wait time increases exponentially with each retry up to this maximum.

func WithRetryWaitTime 

func WithRetryWaitTime(retryWait time.Duration) ClientOption

WithRetryWaitTime sets the default wait time between retry attempts. This is the initial/minimum wait time before the first retry.

func WithRootCertificateFromString added in v0.3.1 

func WithRootCertificateFromString(pemContent string) ClientOption

WithRootCertificateFromString adds a custom root CA certificate from PEM string.

func WithRootCertificates added in v0.3.1 

func WithRootCertificates(pemFilePaths ...string) ClientOption

WithRootCertificates adds custom root CA certificates for server validation. Useful for private CAs or self-signed certificates.

func WithScope added in v0.3.1 

func WithScope(scope string) ClientOption

WithScope sets a custom JWT scope (default: "business.api" or "school.api").

func WithTLSClientConfig added in v0.3.1 

func WithTLSClientConfig(tlsConfig *tls.Config) ClientOption

WithTLSClientConfig sets custom TLS configuration. Use this for custom certificate validation, minimum TLS version, etc.

func WithTimeout 

func WithTimeout(timeout time.Duration) ClientOption

WithTimeout sets the timeout for all HTTP requests.

func WithTransport added in v0.3.1 

func WithTransport(transport http.RoundTripper) ClientOption

WithTransport sets a custom HTTP transport (http.RoundTripper). Use this for advanced transport customization beyond TLS/proxy.

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 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, errorResp *ErrorResponse) error

HandleError processes API error responses and returns structured errors 

type ErrorLinks struct {
	About      string                `json:"about,omitempty"`
	Associated *ErrorLinksAssociated `json:"associated,omitempty"`
}

ErrorLinks contains error-related links

type ErrorLinksAssociated 

type ErrorLinksAssociated struct {
	Href string                    `json:"href"`
	Meta *ErrorLinksAssociatedMeta `json:"meta,omitempty"`
}

ErrorLinksAssociated represents associated error links

type ErrorLinksAssociatedMeta 

type ErrorLinksAssociatedMeta struct {
	// Can contain any key-value pairs as specified in the API
	AdditionalProperties map[string]any `json:"-"`
}

ErrorLinksAssociatedMeta contains metadata for associated error links

func (*ErrorLinksAssociatedMeta) MarshalJSON 

func (m *ErrorLinksAssociatedMeta) MarshalJSON() ([]byte, error)

MarshalJSON implements custom marshaling for ErrorLinksAssociatedMeta

func (*ErrorLinksAssociatedMeta) UnmarshalJSON 

func (m *ErrorLinksAssociatedMeta) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshaling for ErrorLinksAssociatedMeta

type ErrorResponse 

type ErrorResponse struct {
	Errors []APIError `json:"errors"`
}

ErrorResponse represents the complete error response structure returned by the API

type JWTAuth 

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

JWTAuth implements OAuth 2.0 JWT-based authentication for Apple Business Manager API

func NewJWTAuth 

func NewJWTAuth(config JWTAuthConfig) *JWTAuth

NewJWTAuth creates a new OAuth 2.0 JWT authentication provider

func (*JWTAuth) ApplyAuth 

func (j *JWTAuth) ApplyAuth(req *resty.Request) error

ApplyAuth applies OAuth 2.0 authentication to the request

func (*JWTAuth) ForceRefresh 

func (j *JWTAuth) ForceRefresh()

ForceRefresh forces a token refresh on the next request

type JWTAuthConfig 

type JWTAuthConfig struct {
	KeyID      string
	IssuerID   string
	PrivateKey any    // Can be *rsa.PrivateKey or *ecdsa.PrivateKey
	Audience   string // Usually "appstoreconnect-v1"
	Scope      string // "business.api" or "school.api"
}

JWTAuthConfig holds configuration for JWT authentication

type JsonPointer 

type JsonPointer struct {
	Pointer string `json:"pointer"`
}

JsonPointer represents a JSON pointer source 

type Links struct {
	Self  string `json:"self,omitempty"`
	First string `json:"first,omitempty"`
	Next  string `json:"next,omitempty"`
	Prev  string `json:"prev,omitempty"`
	Last  string `json:"last,omitempty"`
}

Links contains pagination navigation links matching Apple's API format.

type Meta 

type Meta struct {
	Paging *Paging `json:"paging,omitempty"`
}

Meta contains pagination metadata matching Apple's API format.

type PaginationOptions 

type PaginationOptions struct {
	Limit  int    `json:"limit,omitempty"`
	Cursor string `json:"cursor,omitempty"`
}

PaginationOptions represents common pagination parameters for Apple's API.

func (*PaginationOptions) AddToQueryBuilder 

func (opts *PaginationOptions) AddToQueryBuilder(qb *QueryBuilder) *QueryBuilder

AddToQueryBuilder adds pagination options to a query builder.

type Paging 

type Paging struct {
	Total      int    `json:"total,omitempty"`
	Limit      int    `json:"limit,omitempty"`
	NextCursor string `json:"nextCursor,omitempty"`
}

Paging contains pagination information matching Apple's API format.

type Parameter 

type Parameter struct {
	Parameter string `json:"parameter"`
}

Parameter represents a query parameter source

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 the final map of query parameters.

func (*QueryBuilder) BuildString 

func (qb *QueryBuilder) BuildString() string

BuildString returns the query parameters as a URL-encoded string.

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 query builder or map.

func (*QueryBuilder) Remove 

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

Remove removes a parameter.

type RequestBuilder added in v0.3.1 

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

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

Usage: 

resp, err := s.client.NewRequest(ctx).
    SetHeader("Accept", constants.ApplicationJSON).
    SetHeader("Content-Type", constants.ApplicationJSON).
    SetBody(payload).
    SetResult(&result).
    Post(constants.EndpointOrgDeviceActivities)

func NewMockRequestBuilder added in v0.3.1 

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

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

func NewMockRequestBuilderWithQueryCapture added in v0.3.1 

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

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

func (*RequestBuilder) Delete added in v0.3.1 

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

Delete executes the request as DELETE against path.

func (*RequestBuilder) Get added in v0.3.1 

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

Get executes the request as GET against path.

func (*RequestBuilder) GetBytes added in v0.3.1 

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 files or exports.

func (*RequestBuilder) GetPaginated added in v0.3.1 

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

GetPaginated transparently fetches all pages of a cursor-based paginated Apple Business Manager API endpoint, calling mergePage with each page's raw JSON response. Query parameters already set on the builder (via SetQueryParam / SetQueryParams) are forwarded as the base params; cursor management is handled internally by the transport.

func (*RequestBuilder) Patch added in v0.3.1 

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

Patch executes the request as PATCH against path.

func (*RequestBuilder) Post added in v0.3.1 

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

Post executes the request as POST against path.

func (*RequestBuilder) Put added in v0.3.1 

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

Put executes the request as PUT against path.

func (*RequestBuilder) SetBody added in v0.3.1 

func (b *RequestBuilder) SetBody(body any) *RequestBuilder

SetBody sets the request body. Nil is ignored.

func (*RequestBuilder) SetHeader added in v0.3.1 

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

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

func (*RequestBuilder) SetMultipartFile added in v0.3.1 

func (b *RequestBuilder) SetMultipartFile(fileField, fileName string, fileReader io.Reader, fileSize int64) *RequestBuilder

SetMultipartFile configures the request for a multipart file upload. Content-Type is managed automatically by resty.

func (*RequestBuilder) SetMultipartFormData added in v0.3.1 

func (b *RequestBuilder) SetMultipartFormData(formFields map[string]string) *RequestBuilder

SetMultipartFormData adds additional form fields to a multipart request.

func (*RequestBuilder) SetQueryParam added in v0.3.1 

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

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

func (*RequestBuilder) SetQueryParams added in v0.3.1 

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

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

func (*RequestBuilder) SetResult added in v0.3.1 

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

SetResult sets the target for JSON unmarshaling of a successful response.

type TokenResponse 

type TokenResponse struct {
	AccessToken string `json:"access_token"`
	TokenType   string `json:"token_type"`
	ExpiresIn   int    `json:"expires_in"`
	Scope       string `json:"scope"`
}

TokenResponse represents the OAuth 2.0 token response from Apple

type Transport added in v0.3.1 

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

Transport represents the main Apple Business Manager API transport layer.

func NewTransport 

func NewTransport(keyID, issuerID string, privateKey any, options ...ClientOption) (*Transport, error)

NewTransport creates a new HTTP transport for Apple Business Manager API. This is an internal function - users should use axm.NewClient() instead.

func NewTransportFromEnv 

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

NewTransportFromEnv creates a transport using environment variables. Requires APPLE_KEY_ID and APPLE_ISSUER_ID plus exactly one of:

  • APPLE_PRIVATE_KEY_PEM — PEM-encoded private key supplied inline
  • APPLE_PRIVATE_KEY_PATH — path to a PEM private key file

func NewTransportFromFile 

func NewTransportFromFile(keyID, issuerID, privateKeyPath string, options ...ClientOption) (*Transport, error)

NewTransportFromFile creates a transport using credentials from files.

func (*Transport) Close added in v0.3.1 

func (t *Transport) Close() error

Close closes the HTTP client and cleans up resources.

func (*Transport) GetHTTPClient added in v0.3.1 

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

GetHTTPClient returns the underlying HTTP client for testing purposes.

func (*Transport) GetLogger added in v0.3.1 

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

GetLogger returns the configured logger.

func (*Transport) NewRequest added in v0.3.1 

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

NewRequest returns a new RequestBuilder for constructing API requests.

func (*Transport) QueryBuilder added in v0.3.1 

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.