feat: added func Get AppleCare Coverage Information for a Device with tests and examples

Author: ShocOne

axm/docs/architecture.svg

@@ -13,25 +13,25 @@ type (
 		// GetDeviceManagementServices retrieves a list of device management services (MDM servers) in an organization
 		//
 		// Apple Business Manager API docs:
-		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-mdm-servers
+		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-device-management-services
 		GetDeviceManagementServices(ctx context.Context, opts *RequestQueryOptions) (*ResponseMDMServers, error)
 
-		// GetMDMServerDeviceLinkages retrieves a list of device IDs assigned to an MDM server
+		// GetDeviceSerialNumbersForDeviceManagementService retrieves a list of device IDs assigned to an MDM server
 		//
 		// Apple Business Manager API docs:
-		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-all-device-ids-for-a-mdmserver
-		GetMDMServerDeviceLinkages(ctx context.Context, mdmServerID string, opts *RequestQueryOptions) (*ResponseMDMServerDevicesLinkages, error)
+		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-all-device-ids-for-a-device-management-service
+		GetDeviceSerialNumbersForDeviceManagementService(ctx context.Context, mdmServerID string, opts *RequestQueryOptions) (*ResponseMDMServerDevicesLinkages, error)
 
 		// GetAssignedDeviceManagementServiceIDForADevice retrieves the assigned device management service ID linkage for a device
 		//
 		// Apple Business Manager API docs:
-		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-server-id-for-an-orgdevice
+		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-device-management-service-id-for-an-orgdevice
 		GetAssignedDeviceManagementServiceIDForADevice(ctx context.Context, deviceID string) (*ResponseOrgDeviceAssignedServerLinkage, error)
 
 		// GetAssignedDeviceManagementServiceInformationByDeviceID retrieves the assigned device management service information for a device
 		//
 		// Apple Business Manager API docs:
-		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-server-information-for-an-orgdevice
+		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-device-management-service-information-for-an-orgdevice
 		GetAssignedDeviceManagementServiceInformationByDeviceID(ctx context.Context, deviceID string, opts *RequestQueryOptions) (*MDMServerResponse, error)
 
 		// AssignDevicesToServer assigns devices to an MDM server
@@ -67,7 +67,7 @@ func NewService(client interfaces.HTTPClient) *DeviceManagementService {
 
 // GetDeviceManagementServices retrieves a list of device management services (MDM servers) in an organization
 // URL: GET https://api-business.apple.com/v1/mdmServers
-// https://developer.apple.com/documentation/applebusinessmanagerapi/get-mdm-servers
+// https://developer.apple.com/documentation/applebusinessmanagerapi/get-device-management-services
 func (s *DeviceManagementService) GetDeviceManagementServices(ctx context.Context, opts *RequestQueryOptions) (*ResponseMDMServers, error) {
 	if opts == nil {
 		opts = &RequestQueryOptions{}
@@ -102,10 +102,10 @@ func (s *DeviceManagementService) GetDeviceManagementServices(ctx context.Contex
 	return &result, nil
 }
 
-// GetMDMServerDeviceLinkages retrieves a list of device IDs assigned to an MDM server
+// GetDeviceSerialNumbersForDeviceManagementService retrieves a list of device IDs assigned to an MDM server
 // URL: GET https://api-business.apple.com/v1/mdmServers/{id}/relationships/devices
-// https://developer.apple.com/documentation/applebusinessmanagerapi/get-all-device-ids-for-a-mdmserver
-func (s *DeviceManagementService) GetMDMServerDeviceLinkages(ctx context.Context, mdmServerID string, opts *RequestQueryOptions) (*ResponseMDMServerDevicesLinkages, error) {
+// https://developer.apple.com/documentation/applebusinessmanagerapi/get-all-device-ids-for-a-device-management-service
+func (s *DeviceManagementService) GetDeviceSerialNumbersForDeviceManagementService(ctx context.Context, mdmServerID string, opts *RequestQueryOptions) (*ResponseMDMServerDevicesLinkages, error) {
 	if mdmServerID == "" {
 		return nil, fmt.Errorf("MDM server ID is required")
 	}
@@ -142,7 +142,7 @@ func (s *DeviceManagementService) GetMDMServerDeviceLinkages(ctx context.Context
 
 // GetAssignedDeviceManagementServiceIDForADevice retrieves the assigned device management service ID linkage for a device
 // URL: GET https://api-business.apple.com/v1/orgDevices/{id}/relationships/assignedServer
-// https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-server-id-for-an-orgdevice
+// https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-device-management-service-id-for-an-orgdevice
 func (s *DeviceManagementService) GetAssignedDeviceManagementServiceIDForADevice(ctx context.Context, deviceID string) (*ResponseOrgDeviceAssignedServerLinkage, error) {
 	if deviceID == "" {
 		return nil, fmt.Errorf("device ID is required")
@@ -166,7 +166,7 @@ func (s *DeviceManagementService) GetAssignedDeviceManagementServiceIDForADevice
 
 // GetAssignedDeviceManagementServiceInformationByDeviceID retrieves the assigned device management service information for a device
 // URL: GET https://api-business.apple.com/v1/orgDevices/{id}/assignedServer
-// https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-server-information-for-an-orgdevice
+// https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-device-management-service-information-for-an-orgdevice
 func (s *DeviceManagementService) GetAssignedDeviceManagementServiceInformationByDeviceID(ctx context.Context, deviceID string, opts *RequestQueryOptions) (*MDMServerResponse, error) {
 	if deviceID == "" {
 		return nil, fmt.Errorf("device ID is required")

axm/services/devicemanagement/crud.go

@@ -152,7 +152,7 @@ func TestGetDeviceManagementServices_HTTPError(t *testing.T) {
 	assert.Equal(t, 4, httpmock.GetTotalCallCount()) // 1 original + 3 retries
 }
 
-func TestGetMDMServerDeviceLinkages_Success(t *testing.T) {
+func TestGetDeviceSerialNumbersForDeviceManagementService_Success(t *testing.T) {
 	client := setupMockClient(t)
 	mockHandler := &mocks.DeviceManagementMock{}
 	mockHandler.RegisterMocks()
@@ -164,7 +164,7 @@ func TestGetMDMServerDeviceLinkages_Success(t *testing.T) {
 		Limit: 100,
 	}
 
-	result, err := client.GetMDMServerDeviceLinkages(ctx, serverID, opts)
+	result, err := client.GetDeviceSerialNumbersForDeviceManagementService(ctx, serverID, opts)
 
 	require.NoError(t, err)
 	require.NotNil(t, result)
@@ -182,7 +182,7 @@ func TestGetMDMServerDeviceLinkages_Success(t *testing.T) {
 	assert.Equal(t, 1, httpmock.GetTotalCallCount())
 }
 
-func TestGetMDMServerDeviceLinkages_EmptyServerID(t *testing.T) {
+func TestGetDeviceSerialNumbersForDeviceManagementService_EmptyServerID(t *testing.T) {
 	client := setupMockClient(t)
 	mockHandler := &mocks.DeviceManagementMock{}
 	mockHandler.RegisterMocks()
@@ -191,7 +191,7 @@ func TestGetMDMServerDeviceLinkages_EmptyServerID(t *testing.T) {
 	ctx := context.Background()
 	opts := &RequestQueryOptions{}
 
-	result, err := client.GetMDMServerDeviceLinkages(ctx, "", opts)
+	result, err := client.GetDeviceSerialNumbersForDeviceManagementService(ctx, "", opts)
 
 	require.Error(t, err)
 	assert.Nil(t, result)
@@ -201,7 +201,7 @@ func TestGetMDMServerDeviceLinkages_EmptyServerID(t *testing.T) {
 	assert.Equal(t, 0, httpmock.GetTotalCallCount())
 }
 
-func TestGetMDMServerDeviceLinkages_WithNilOptions(t *testing.T) {
+func TestGetDeviceSerialNumbersForDeviceManagementService_WithNilOptions(t *testing.T) {
 	client := setupMockClient(t)
 	mockHandler := &mocks.DeviceManagementMock{}
 	mockHandler.RegisterMocks()
@@ -210,7 +210,7 @@ func TestGetMDMServerDeviceLinkages_WithNilOptions(t *testing.T) {
 	ctx := context.Background()
 	serverID := "1F97349736CF4614A94F624E705841AD"
 
-	result, err := client.GetMDMServerDeviceLinkages(ctx, serverID, nil)
+	result, err := client.GetDeviceSerialNumbersForDeviceManagementService(ctx, serverID, nil)
 
 	require.NoError(t, err)
 	require.NotNil(t, result)

axm/services/devicemanagement/crud_test.go

@@ -67,4 +67,31 @@ const (
 	ProductFamilyiPhone = "iPhone"
 	ProductFamilyiPad   = "iPad"
 	ProductFamilyMac    = "Mac"
-)
+)
+
+// AppleCare coverage field constants for field selection
+const (
+	FieldAppleCareStatus                 = "status"
+	FieldAppleCarePaymentType            = "paymentType"
+	FieldAppleCareDescription            = "description"
+	FieldAppleCareAgreementNumber        = "agreementNumber"
+	FieldAppleCareStartDateTime          = "startDateTime"
+	FieldAppleCareEndDateTime            = "endDateTime"
+	FieldAppleCareIsRenewable            = "isRenewable"
+	FieldAppleCareIsCanceled             = "isCanceled"
+	FieldAppleCareContractCancelDateTime = "contractCancelDateTime"
+)
+
+// AppleCare coverage status constants
+const (
+	AppleCareStatusActive   = "ACTIVE"
+	AppleCareStatusInactive = "INACTIVE"
+	AppleCareStatusExpired  = "EXPIRED"
+)
+
+// AppleCare payment type constants
+const (
+	PaymentTypeNone            = "NONE"
+	PaymentTypeSubscription    = "SUBSCRIPTION"
+	PaymentTypeABESubscription = "ABE_SUBSCRIPTION"
+)

axm/services/devices/constants.go

@@ -23,6 +23,13 @@ type (
 		// Apple Business Manager API docs:
 		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-orgdevice-information
 		GetDeviceInformationByDeviceID(ctx context.Context, deviceID string, opts *RequestQueryOptions) (*OrgDeviceResponse, error)
+
+		// GetAppleCareInformationByDeviceID retrieves AppleCare coverage information
+		// for a specific device.
+		//
+		// Apple Business Manager API docs:
+		// https://developer.apple.com/documentation/applebusinessmanagerapi/get-all-apple-care-coverage-for-an-orgdevice
+		GetAppleCareInformationByDeviceID(ctx context.Context, deviceID string, opts *RequestQueryOptions) (*AppleCareCoverageResponse, error)
 	}
 
 	// DevicetService handles communication with the device
@@ -115,3 +122,45 @@ func (s *DevicesService) GetDeviceInformationByDeviceID(ctx context.Context, dev
 
 	return &result, nil
 }
+
+// GetAppleCareInformationByDeviceID retrieves AppleCare coverage information for a specific device
+// URL: GET https://api-business.apple.com/v1/orgDevices/{id}/appleCareCoverage
+// https://developer.apple.com/documentation/applebusinessmanagerapi/get-all-apple-care-coverage-for-an-orgdevice
+func (s *DevicesService) GetAppleCareInformationByDeviceID(ctx context.Context, deviceID string, opts *RequestQueryOptions) (*AppleCareCoverageResponse, error) {
+	if deviceID == "" {
+		return nil, fmt.Errorf("device ID is required")
+	}
+
+	endpoint := "/orgDevices/" + deviceID + "/appleCareCoverage"
+
+	headers := map[string]string{
+		"Accept":       "application/json",
+		"Content-Type": "application/json",
+	}
+
+	if opts == nil {
+		opts = &RequestQueryOptions{}
+	}
+
+	queryParams := s.client.QueryBuilder()
+
+	if len(opts.Fields) > 0 {
+		queryParams.AddStringSlice("fields[appleCareCoverage]", opts.Fields)
+	}
+
+	if opts.Limit > 0 {
+		if opts.Limit > 1000 {
+			opts.Limit = 1000 // Enforce API maximum
+		}
+		queryParams.AddInt("limit", opts.Limit)
+	}
+
+	var result AppleCareCoverageResponse
+
+	err := s.client.GetPaginated(ctx, endpoint, queryParams.Build(), headers, &result)
+	if err != nil {
+		return nil, err
+	}
+
+	return &result, nil
+}