axm 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02ec17dcd1e6762bebf731dd97394f9fe87c75be604baed827f34106482d0caf
-  data.tar.gz: 4b480339114ab452ed36ce63ae9b843a95e548f5ccc38de034c4d85eb331e674
+  metadata.gz: 0d2f95c8bc2de0f7a2c7ea620d2f301980eb6c5a21243bc8ee878b0ae4ebb351
+  data.tar.gz: 59c698eebe7dbe7baf4b1378ca5a66b0045334a2d69c3441b0300ca5dc3de6a4
 SHA512:
-  metadata.gz: 28c69e287d78e9b120a75a3092294b1a7526d9b41301869c04c96921066dc34440423e28f06ccca208396dd24f98a5d460c5ab0c1e32e89ccbebb4f4ded09317
-  data.tar.gz: 0bfd98852076b669c53f02c3ddbcbdc3e60a1958125e2ef9d66af2ab8ec11207451245fd9fabe123583c24996703bb977990cba1e001950b5323696db38820d9
+  metadata.gz: 8e3fc06e2e51475d49a6d5612700046e9003967200d1234ca3aa52d4ead5f08827d8f4eb432a512af127cb01920befab0a3f4dd9f354a6705a4f3ca8d1d5d781
+  data.tar.gz: dac8b555c797f8b773de5c58cc0de9b35128df4251a5cfbe9c3260160c11f5b2178e010f3fe9d8126a63ad144c0db71e9abd452b020488bb6440bb239e1875fe

data/CHANGELOG.md

@@ -1,5 +1,34 @@
-## [Unreleased]
+## 1.0.0 - 2025-11-08
 
-## [0.1.0] - 2025-06-16
+### 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
+
+### Added
+
+- Get information about a specific device
+
+### Fixed
+
+- Fixed issue with incorrect endpoints being included
+
+## [0.1.1] - 2025-07-14
+
+- Updated README with more detailed usage instructions
+
+## [0.1.0] - 2025-07-14
 
 - Initial release
+
+### Added
+
+- Exchange credentials for an access token
+- List all devices in an organisation

data/README.md

@@ -26,10 +26,10 @@ With the credentials handy, you can create an instance of the client:
 
 ```ruby
 private_key = File.read('path/to/your/private_key.pem')
-issuer_id = 'your_issuer_id'
+client_id = 'your_client_id'
 key_id = 'your_key_id'
 
-client = Axm::Client.new(private_key:, issuer_id:, key_id:)
+client = Axm::Client.new(private_key:, client_id:, key_id:)
 ```
 
 You're now ready to make API requests.
@@ -48,6 +48,16 @@ client.get('/v1/some/endpoint', { limit: 10 })
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+If the credentials are stored in the `secrets/` directory, you can use the `Secret.read` method to load them:
+
+```ruby
+private_key = Secret.read('private_key.pem')
+client_id = Secret.read('client_id')
+key_id = Secret.read('key_id')
+
+client = Axm::Client.new(private_key:, client_id:, key_id:)
+```
+
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing

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

@@ -11,7 +11,63 @@ module Axm
       # See: https://developer.apple.com/documentation/applebusinessmanagerapi/get-org-devices
       # See: https://developer.apple.com/documentation/appleschoolmanagerapi/get-org-devices
       def list_org_devices(options = {})
-        get('/v1/organization/devices', options)
+        get("v1/orgDevices", options)
+      end
+
+      # Retrieves information about a specific device in the organization.
+      #
+      # @param options [Hash] Optional query parameters to filter or paginate results.
+      #   - fields: (Array) Array of fields to include in the response.
+      # @return [<Hash>] A device and its selected attributes.
+      #
+      # See: https://developer.apple.com/documentation/applebusinessmanagerapi/get-orgdevice-information
+      # See: https://developer.apple.com/documentation/appleschoolmanagerapi/get-orgdevice-information
+      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

data/lib/axm/client.rb

@@ -4,10 +4,16 @@ 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.
     #
     # @param private_key [String] The private key used for authentication.
@@ -83,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
 
@@ -112,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?
@@ -131,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)
 
@@ -153,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.1"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: axm
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  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