feat: reorganised code

Author: ShocOne

README.md

@@ -56,34 +56,42 @@ Complete implementation of the [Apple Business Manager API](https://developer.ap
 - **Context Support**: Context-aware operations for timeouts and cancellation
 
 **Quick Start:**
-```go
-// Create JWT auth
-auth := client.NewJWTAuth(client.JWTAuthConfig{
-    KeyID:      "YOUR_KEY_ID",
-    IssuerID:   "YOUR_ISSUER_ID",
-    PrivateKey: privateKey,
-})
 
-// Create client
-appleClient, err := apple.NewClient(client.Config{
-    Auth:   auth,
-    Logger: logger,
-    Debug:  true,
-})
-defer appleClient.Close()
+Get started quickly with multiple client setup options:
 
-// Get devices with pagination
-devices, err := appleClient.Devices().GetOrganizationDevices(ctx, &devices.GetOrganizationDevicesOptions{
-    Model: devices.ModeliPhone,
-    PaginationOptions: client.PaginationOptions{Limit: 100},
+```go
+// Method 1: Simple setup with environment variables
+axmClient, err := axm.NewClientFromEnv()
+if err != nil {
+    log.Fatalf("Failed to create client: %v", err)
+}
+
+// Create service clients
+devicesClient := devices.NewClient(axmClient)
+deviceManagementClient := devicemanagement.NewClient(axmClient)
+
+// Get organization devices
+ctx := context.Background()
+response, err := devicesClient.GetOrganizationDevices(ctx, &devices.GetOrganizationDevicesOptions{
+    Fields: []string{
+        devices.FieldSerialNumber,
+        devices.FieldDeviceModel,
+        devices.FieldStatus,
+    },
+    Limit: 100,
 })
 
-// Iterate through all pages
-for result := range devices.Iterator(ctx) {
-    fmt.Printf("Device: %s\n", result.Item.SerialNumber)
+if err != nil {
+    log.Fatalf("Error getting devices: %v", err)
 }
+
+fmt.Printf("Found %d devices\n", len(response.Data))
 ```
 
+📖 **[Complete Quick Start Guide →](./examples/axm/quick_start.md)**
+
+The guide covers 6 different client setup methods, from simple environment variables to advanced builder patterns with full customization options.
+
 ### Apple Device Management API
 
 Integration with [Apple Device Management](https://developer.apple.com/documentation/devicemanagement) for:

client/axm/auth.go

@@ -239,18 +239,6 @@ type OAuth2TokenResponse struct {
 	Scope       string `json:"scope"`
 }
 
-// OAuth scope constants
-const (
-	ScopeBusinessAPI = "business.api"
-	ScopeSchoolAPI   = "school.api"
-)
-
-// Default OAuth endpoints
-const (
-	DefaultOAuthTokenURL = "https://account.apple.com/auth/oauth2/token"
-	DefaultOAuthAudience = "https://account.apple.com/auth/oauth2/v2/token"
-)
-
 // NewOAuth2Auth creates a new OAuth 2.0 authentication provider
 func NewOAuth2Auth(config OAuth2Config) (*OAuth2Auth, error) {
 	// Validate required fields

client/axm/client.go

@@ -38,7 +38,7 @@ type APIResponse[T any] struct {
 
 // NewClient creates a new Apple Business Manager API client
 func NewClient(config Config) (*Client, error) {
-	// Set defaults
+
 	if config.BaseURL == "" {
 		config.BaseURL = "https://api-business.apple.com/v1"
 	}
@@ -58,15 +58,12 @@ func NewClient(config Config) (*Client, error) {
 		config.Logger = zap.NewNop()
 	}
 
-	// Validate required fields
 	if config.Auth == nil {
 		return nil, fmt.Errorf("auth provider is required")
 	}
 
-	// Create Resty client with v3 best practices
 	httpClient := resty.New()
 
-	// Configure client settings
 	httpClient.
 		SetBaseURL(config.BaseURL).
 		SetTimeout(config.Timeout).
@@ -75,19 +72,15 @@ func NewClient(config Config) (*Client, error) {
 		SetRetryMaxWaitTime(config.RetryWait*10).
 		SetHeader("User-Agent", config.UserAgent)
 
-	// Enable debug mode if requested
 	if config.Debug {
 		httpClient.SetDebug(true)
 	}
 
-	// Add request middleware for logging and auth
 	httpClient.AddRequestMiddleware(func(c *resty.Client, req *resty.Request) error {
-		// Apply authentication
 		if err := config.Auth.ApplyAuth(req); err != nil {
 			return fmt.Errorf("auth failed: %w", err)
 		}
 
-		// Log request
 		config.Logger.Info("API request",
 			zap.String("method", req.Method),
 			zap.String("url", req.URL),
@@ -96,7 +89,6 @@ func NewClient(config Config) (*Client, error) {
 		return nil
 	})
 
-	// Add response middleware for logging and OAuth token refresh
 	httpClient.AddResponseMiddleware(func(c *resty.Client, resp *resty.Response) error {
 		config.Logger.Info("API response",
 			zap.String("method", resp.Request.Method),
@@ -105,7 +97,6 @@ func NewClient(config Config) (*Client, error) {
 			zap.String("status", resp.Status()),
 		)
 
-		// Handle 401 responses for OAuth2Auth by forcing token refresh
 		if resp.StatusCode() == 401 {
 			if oauth2Auth, ok := config.Auth.(*OAuth2Auth); ok {
 				config.Logger.Info("Received 401 response, forcing OAuth token refresh")

client/axm/client_builder.go

@@ -73,20 +73,6 @@ func (cb *ClientBuilder) WithJWTAuthFromEnv() *ClientBuilder {
 	return cb.WithJWTAuthFromFile(keyID, issuerID, privateKeyPath)
 }
 
-// WithAPIKeyAuth configures API key authentication
-func (cb *ClientBuilder) WithAPIKeyAuth(apiKey string) *ClientBuilder {
-	// Note: API key auth would be implemented here when supported
-	// For now, this is a placeholder for future implementation
-	return cb
-}
-
-// WithOAuth2Auth configures OAuth 2.0 authentication
-func (cb *ClientBuilder) WithOAuth2Auth(clientID, clientSecret string) *ClientBuilder {
-	// Note: OAuth2 auth would be implemented here when supported
-	// For now, this is a placeholder for future implementation
-	return cb
-}
-
 // WithBaseURL sets the base URL for the API (default: https://api-business.apple.com/v1)
 func (cb *ClientBuilder) WithBaseURL(baseURL string) *ClientBuilder {
 	cb.baseURL = baseURL

client/axm/constants.go

@@ -0,0 +1,13 @@
+package axm
+
+// OAuth scope constants
+const (
+	ScopeBusinessAPI = "business.api"
+	ScopeSchoolAPI   = "school.api"
+)
+
+// Default OAuth endpoints
+const (
+	DefaultOAuthTokenURL = "https://account.apple.com/auth/oauth2/token"
+	DefaultOAuthAudience = "https://account.apple.com/auth/oauth2/v2/token"
+)

client/axm/errors.go

@@ -116,9 +116,7 @@ func NewErrorHandler(logger *zap.Logger) *ErrorHandler {
 func (eh *ErrorHandler) HandleError(resp *resty.Response, errorResp *ErrorResponse) error {
 	statusCode := resp.StatusCode()
 
-	// Handle new ErrorResponse format with errors array
 	if len(errorResp.Errors) > 0 {
-		// Log all errors with enhanced information
 		for i, apiError := range errorResp.Errors {
 			logFields := []zap.Field{
 				zap.Int("error_index", i),
@@ -131,7 +129,6 @@ func (eh *ErrorHandler) HandleError(resp *resty.Response, errorResp *ErrorRespon
 				zap.String("method", resp.Request.Method),
 			}
 
-			// Add source information if available
 			if apiError.Source != nil {
 				if apiError.Source.JsonPointer != nil {
 					logFields = append(logFields, zap.String("source_json_pointer", apiError.Source.JsonPointer.Pointer))
@@ -141,7 +138,6 @@ func (eh *ErrorHandler) HandleError(resp *resty.Response, errorResp *ErrorRespon
 				}
 			}
 
-			// Add links information if available
 			if apiError.Links != nil {
 				if apiError.Links.About != "" {
 					logFields = append(logFields, zap.String("links_about", apiError.Links.About))
@@ -154,28 +150,24 @@ func (eh *ErrorHandler) HandleError(resp *resty.Response, errorResp *ErrorRespon
 				}
 			}
 
-			// Add meta information if available
 			if apiError.Meta != nil && apiError.Meta.AdditionalProperties != nil {
 				logFields = append(logFields, zap.Any("error_meta", apiError.Meta.AdditionalProperties))
 			}
 
 			eh.logger.Error("API request failed", logFields...)
 		}
 
-		// Return the first error
 		firstError := errorResp.Errors[0]
 		return &firstError
 	}
 
-	// Fallback for when no structured errors are provided
 	eh.logger.Error("API request failed (no structured error)",
 		zap.Int("status_code", statusCode),
 		zap.String("url", resp.Request.URL),
 		zap.String("method", resp.Request.Method),
 		zap.String("response_body", resp.String()),
 	)
 
-	// Return generic error
 	return &APIError{
 		Status: fmt.Sprintf("%d", statusCode),
 		Code:   fmt.Sprintf("HTTP_%d", statusCode),

client/axm/pagination.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"maps"
 	"net/url"
 )
 
@@ -56,13 +57,11 @@ func (c *Client) GetNextPage(ctx context.Context, nextURL string, headers map[st
 		return fmt.Errorf("no next page URL provided")
 	}
 
-	// Parse the next URL to extract path and query parameters
 	parsedURL, err := url.Parse(nextURL)
 	if err != nil {
 		return fmt.Errorf("failed to parse next URL: %w", err)
 	}
 
-	// Extract query parameters
 	queryParams := make(map[string]string)
 	for key, values := range parsedURL.Query() {
 		if len(values) > 0 {
@@ -87,46 +86,36 @@ func HasPrevPage(links *Links) bool {
 // GetAllPages retrieves all pages of results by following pagination links
 func (c *Client) GetAllPages(ctx context.Context, path string, queryParams map[string]string, headers map[string]string, processPage func([]byte) error) error {
 	currentParams := make(map[string]string)
-	for k, v := range queryParams {
-		currentParams[k] = v
-	}
+	maps.Copy(currentParams, queryParams)
 
 	for {
-		// Make request for current page
 		var rawResponse json.RawMessage
 		err := c.GetPaginated(ctx, path, currentParams, headers, &rawResponse)
 		if err != nil {
 			return err
 		}
 
-		// Process the page data
 		if err := processPage(rawResponse); err != nil {
 			return err
 		}
 
-		// Parse response to check for next page
 		var pageInfo struct {
 			Links *Links `json:"links,omitempty"`
 		}
 		if err := json.Unmarshal(rawResponse, &pageInfo); err != nil {
 			return fmt.Errorf("failed to parse pagination info: %w", err)
 		}
 
-		// Check if there's a next page
 		if !HasNextPage(pageInfo.Links) {
 			break
 		}
 
-		// Extract parameters from next URL
 		nextParams, err := extractParamsFromURL(pageInfo.Links.Next)
 		if err != nil {
 			return fmt.Errorf("failed to parse next URL: %w", err)
 		}
 
-		// Update parameters for next request
-		for k, v := range nextParams {
-			currentParams[k] = v
-		}
+		maps.Copy(currentParams, nextParams)
 	}
 
 	return nil