axm 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b9cf51eb8d1e42d2ee6112d4bf1bc8d38408a56581f0ed0fcaafcb4358692a7
-  data.tar.gz: 48a58959848c13ff47d37dd9eb9cd104291bd66e422fc00ba8b3bfbdd3eea3b7
+  metadata.gz: 0d2f95c8bc2de0f7a2c7ea620d2f301980eb6c5a21243bc8ee878b0ae4ebb351
+  data.tar.gz: 59c698eebe7dbe7baf4b1378ca5a66b0045334a2d69c3441b0300ca5dc3de6a4
 SHA512:
-  metadata.gz: bd809519957cc388dff7f4c62ce718de7f0c3990c85056a24964de019b2c77338db9078c56b488a583e289ecde0378f40e965682bcd11beaa329bbab625dccbb
-  data.tar.gz: 8d4db509e738fe69a17265e718f8371a7c8c2d1e9a1ad7ca3c8471a5eebec62262c5d7f071c5040614fefc1568b75b47f59cd1bc331dae063b9f4ae5073812d1
+  metadata.gz: 8e3fc06e2e51475d49a6d5612700046e9003967200d1234ca3aa52d4ead5f08827d8f4eb432a512af127cb01920befab0a3f4dd9f354a6705a4f3ca8d1d5d781
+  data.tar.gz: dac8b555c797f8b773de5c58cc0de9b35128df4251a5cfbe9c3260160c11f5b2178e010f3fe9d8126a63ad144c0db71e9abd452b020488bb6440bb239e1875fe

data/CHANGELOG.md

@@ -1,4 +1,14 @@
-## [Unreleased]
+## 1.0.0 - 2025-11-08
+
+### Added
+
+- List all MDM servers in an organisation
+- Show all device IDs assigned to a specific MDM server
+- Show which MDM server a device is assigned to
+- Show the ID of the MDM server a device is assigned to
+- Show information about the MDM server a device is assigned to
+- Assign and unassign devices to MDM servers
+- Show AppleCare coverage information for devices
 
 ## 0.1.2 - 2025-07-14
 

data/lib/axm/client/mdm_servers.rb

@@ -0,0 +1,31 @@
+module Axm
+  class Client
+    module MdmServers
+      # Retrieves a list of MDM servers associated with the organization.
+      #
+      # @param options [Hash] Optional query parameters to filter fields or paginate results.
+      #   - fields: (Array) Array of fields to include in the response.
+      #   - limit: (Integer) Maximum number of devices to return per page (default: 100, maximum: 1000).
+      # @return [Array<Hash>] An array of MDM servers.
+      #
+      # See: https://developer.apple.com/documentation/applebusinessmanagerapi/get-mdm-servers
+      # See: https://developer.apple.com/documentation/appleschoolmanagerapi/get-mdm-servers
+      def list_mdm_servers(options = {})
+        get("v1/mdmServers", options)
+      end
+
+      # Retrieves a list of IDs for the devices assigned to a specific MDM server.
+      #
+      # @param mdm_server_id [String] The unique identifier of the MDM server.
+      # @param options [Hash] Optional query parameters to paginate results or increase number of returned results.
+      #   - limit: (Integer) Maximum number of devices to return per page (default: 100, maximum: 1000).
+      # @return [Array<Hash>] An array of device IDs assigned to the specified MDM server.
+      #
+      # See: https://developer.apple.com/documentation/applebusinessmanagerapi/get-all-device-ids-for-a-mdmserver
+      # See: https://developer.apple.com/documentation/appleschoolmanagerapi/get-all-device-ids-for-a-mdmserver
+      def devices_assigned_to_mdm_server(mdm_server_id, options = {})
+        get("v1/mdmServers/#{mdm_server_id}/relationships/devices", options)
+      end
+    end
+  end
+end

data/lib/axm/client/organization_device_activities.rb

@@ -0,0 +1,74 @@
+module Axm
+  class Client
+    module OrganizationDeviceActivities
+      # Get information for an organization device activity that a device management action, such as assign or unassign, creates.
+      #
+      # @param options [Hash] Optional query parameters to filter returned attributes.
+      #   - fields: (Array) Array of fields to include in the response.
+      # @return [<Hash>] A single organization device activity resource.
+      #
+      # See: https://developer.apple.com/documentation/applebusinessmanagerapi/get-orgdeviceactivity-information
+      # See: https://developer.apple.com/documentation/appleschoolmanagerapi/get-orgdeviceactivity-information
+      def org_device_activity(activity_id, options = {})
+        get("v1/orgDeviceActivities/#{activity_id}", options)
+      end
+
+      # Assigns a device to an MDM server.
+      #
+      # @param device_ids [Array<String>] Array of device IDs to be assigned.
+      # @param mdm_server_id [String] The unique identifier of the MDM server to which the device will be assigned.
+      # @return [Hash, Integer] The response from the POST method, containing details of the assignment and status code.
+      def assign(device_id, mdm_server_id)
+        assignment_change(device_id, mdm_server_id, "ASSIGN_DEVICES")
+      end
+
+      # Unassigns a device from an MDM server.
+      #
+      # @param device_ids [Array<String>] Array of device IDs to be unassigned.
+      # @param mdm_server_id [String] The unique identifier of the MDM server to which the device will be assigned.
+      # @return [Hash, Integer] The response from the POST method, containing details of the assignment and status code.
+      def unassign(device_id, mdm_server_id)
+        assignment_change(device_id, mdm_server_id, "UNASSIGN_DEVICES")
+      end
+
+      private
+
+      # Sends a request to change the assignment of a device to an MDM server.
+      #
+      # @param device_ids [Array<String>] Array of IDs of devices to be assigned or unassigned.
+      # @param mdm_server_id [String] The unique identifier of the MDM server.
+      # @param activity_type [String] The type of activity being performed ("ASSIGN_DEVICES" or "UNASSIGN_DEVICES").
+      # @return [Hash, Integer] The response from the POST request, containing details of the operation and status code.
+      def assignment_change(device_ids, mdm_server_id, activity_type)
+        devices = device_ids.map do |device_id|
+          {
+            type: "orgDevices",
+            id: device_id
+          }
+        end
+
+        request_body = {
+          data: {
+            type: "orgDeviceActivities",
+            attributes: {
+              activityType: activity_type
+            },
+            relationships: {
+              mdmServer: {
+                data: {
+                  type: "mdmServers",
+                  id: mdm_server_id
+                }
+              },
+              devices: {
+                data: devices
+              }
+            }
+          }
+        }
+
+        post("v1/orgDeviceActivities", request_body)
+      end
+    end
+  end
+end

data/lib/axm/client/organization_devices.rb

@@ -25,6 +25,50 @@ module Axm
       def device(id, options = {})
         get("/v1/orgDevices/#{id}", options)
       end
+
+      # Fetch the assigned device management service ID for a device.
+      #
+      # @param device_id [String] The unique identifier of the device.
+      # @param options [Hash] Optional query parameters to filter or paginate results.
+      # @return [<Hash>] Identifier of the device's assigned MDM server.
+      #
+      # See: https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-server-id-for-an-orgdevice
+      # See: https://developer.apple.com/documentation/appleschoolmanagerapi/get-the-assigned-server-id-for-an-orgdevice
+      def assigned_mdm_server_id(device_id, options = {})
+        get("v1/orgDevices/#{device_id}/relationships/assignedServer", options)
+      end
+
+      # Fetch the assigned device management service information for a device.
+      #
+      # @param device_id [String] The unique identifier of the device.
+      # @param options [Hash] Optional query parameters to filter or paginate results.
+      #   - id: (String) The unique identifier of the device.
+      #   - fields: (Array) Array of fields to include in the response.
+      # @return [<Hash>] A hash containing the identifier of the device's assigned MDM server.
+      #
+      # See: https://developer.apple.com/documentation/applebusinessmanagerapi/get-the-assigned-server-information-for-an-orgdevice
+      # See: https://developer.apple.com/documentation/appleschoolmanagerapi/get-the-assigned-server-information-for-an-orgdevice
+      def assigned_mdm_server(device_id, options = {})
+        options[:fields_key] = "mdmServers"
+
+        get("v1/orgDevices/#{device_id}/assignedServer", options)
+      end
+
+      # Fetch the AppleCare coverage information for a device.
+      #
+      # @param device_id [String] The unique identifier of the device.
+      # @param options [Hash] Optional query parameters to filter or paginate results.
+      #   - fields: (Array) Array of fields to include in the response.
+      #   - limit: (Integer) The number of included related resources to return (default: 100, maximum: 1000).
+      # @return [<Hash>] A hash containing the identifier of the device's assigned MDM server.
+      #
+      # See: https://developer.apple.com/documentation/applebusinessmanagerapi/get-all-apple-care-coverage-for-an-orgdevice
+      # See: https://developer.apple.com/documentation/appleschoolmanagerapi/get-all-apple-care-coverage-for-an-orgdevice
+      def applecare_coverage(device_id, options = {})
+        options[:fields_key] = "appleCareCoverage"
+
+        get("v1/orgDevices/#{device_id}/appleCareCoverage", options)
+      end
     end
   end
 end

data/lib/axm/client.rb

@@ -4,10 +4,14 @@ require 'net/http'
 require 'securerandom'
 require 'time'
 
+require 'axm/client/mdm_servers'
+require 'axm/client/organization_device_activities'
 require 'axm/client/organization_devices'
 
 module Axm
   class Client
+    include MdmServers
+    include OrganizationDeviceActivities
     include OrganizationDevices
 
     # Initializes a new instance of the AXM client.
@@ -85,15 +89,7 @@ module Axm
         return cached_access_token unless token_expired
       end
 
-      params = {
-        grant_type: 'client_credentials',
-        client_id: @client_id,
-        client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
-        client_assertion: client_assertion,
-        scope: "#{scope}.api"
-      }
-
-      response = post('https://account.apple.com/auth/oauth2/v2/token', params)
+      response = exchange_access_token_request
 
       response_body = response.first if response.last.to_i == 200
 
@@ -114,10 +110,14 @@ module Axm
     def get(path, options = {})
       options = options.dup
 
-      endpoint = path.split('/').last
+      # API endpoints are prefixed with 'v1', so we can extract the endpoint from the path.
+      endpoint = path.split('/')[1]
+
+      # For the cases where the fields_key is different to the path component, it can be overriden as an option.
+      fields_key = options.delete(:fields_key) || endpoint
 
       fields = options.delete(:fields)
-      options["fields[#{endpoint}]"] = fields.join(',') if fields
+      options["fields[#{fields_key}]"] = fields.join(',') if fields
 
       uri = URI("https://#{api_domain}/#{path}")
       uri.query = URI.encode_www_form(options) unless options.empty?
@@ -133,20 +133,27 @@ module Axm
       JSON.parse(res.body)
     end
 
-    # Sends a POST request to the specified URI with given parameters.
+    # Sends a POST request to exchange the credentials for an access token.
     #
-    # @param uri [String, URI] The endpoint URI.
-    # @param params [Hash] Parameters to include in the request body.
-    # @return [Net::HTTPResponse] The HTTP response object.
-    def post(uri, params = {})
-      uri = URI(uri) if uri.is_a?(String)
+    # @return [Net::HTTPResponse, integer] The HTTP response object and status code.
+    def exchange_access_token_request
+      uri = URI('https://account.apple.com/auth/oauth2/v2/token')
+
+      request_body = {
+        grant_type: 'client_credentials',
+        client_id: @client_id,
+        client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
+        client_assertion: client_assertion,
+        scope: "#{scope}.api"
+      }
+
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == 'https'
 
       request = Net::HTTP::Post.new(uri)
       request['Host'] = uri.host
       request['Content-Type'] = 'application/x-www-form-urlencoded'
-      request.body = URI.encode_www_form(params) unless params.empty?
+      request.body = URI.encode_www_form(request_body)
 
       response = http.request(request)
 
@@ -155,8 +162,34 @@ module Axm
       response_json = JSON.parse(response.body)
 
       raise 'Invalid request' if response_json['error'] == 'invalid_request'
+      raise 'Invalid client ID or key ID' if response_json['error'] == 'invalid_client'
 
       [response_json, response.code]
     end
+
+    # Sends a POST request to the specified URI with given parameters.
+    #
+    # @param uri [String, URI] The endpoint URI.
+    # @param request_body [Hash] Parameters to include in the request body.
+    # @return [Hash, Integer] The HTTP response object and status code.
+    def post(path, request_body = {})
+      uri = URI("https://#{api_domain}/#{path}")
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+
+      request = Net::HTTP::Post.new(uri)
+      request['Host'] = uri.host
+      request['Content-Type'] = 'application/json'
+      request['Authorization'] = "Bearer #{access_token['access_token']}"
+
+      request.body = request_body.to_json unless request_body.empty?
+
+      response = http.request(request)
+
+      response_body = JSON.parse(response.body)
+
+      [response_body, response.code]
+    end
   end
 end

data/lib/axm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axm
-  VERSION = "0.1.2"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axm
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.0
 platform: ruby
 authors:
 - nick-f
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-14 00:00:00.000000000 Z
+date: 2025-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -40,6 +40,8 @@ files:
 - Rakefile
 - lib/axm.rb
 - lib/axm/client.rb
+- lib/axm/client/mdm_servers.rb
+- lib/axm/client/organization_device_activities.rb
 - lib/axm/client/organization_devices.rb
 - lib/axm/secret.rb
 - lib/axm/version.rb
@@ -66,7 +68,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Gem to interact with the Apple Business Manager/Apple School Manager API