axm 0.1.2 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b9cf51eb8d1e42d2ee6112d4bf1bc8d38408a56581f0ed0fcaafcb4358692a7
-  data.tar.gz: 48a58959848c13ff47d37dd9eb9cd104291bd66e422fc00ba8b3bfbdd3eea3b7
+  metadata.gz: 729a2e7795a94f807dc732928f6e704f42d4e93fdb712bde4083a04410fb1aa5
+  data.tar.gz: 8256543f1d81885b9ee2f6bae17f74506efaef554796b9ac2e03a415a3d50954
 SHA512:
-  metadata.gz: bd809519957cc388dff7f4c62ce718de7f0c3990c85056a24964de019b2c77338db9078c56b488a583e289ecde0378f40e965682bcd11beaa329bbab625dccbb
-  data.tar.gz: 8d4db509e738fe69a17265e718f8371a7c8c2d1e9a1ad7ca3c8471a5eebec62262c5d7f071c5040614fefc1568b75b47f59cd1bc331dae063b9f4ae5073812d1
+  metadata.gz: f3ae6ad5f92c66c84284011b9bb3ac2e5f3297df2662783807bf0893ec46efd337490185b6871a131b8a12e2fbfa2b59d581e213921510fadf16be5532ec563f
+  data.tar.gz: 5bcb9240a6aae5f17e9e872c0bf5a5796c8b9b0665e583a9063f6d42dafd59161656c1645ea8fa35deba31e8ae899d13993b031c61bddb5c193f7f5381b09bed

data/.rubocop.yml

@@ -11,9 +11,3 @@ Layout/LineLength:
 
 Style/Documentation:
   Enabled: false
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -1,4 +1,19 @@
-## [Unreleased]
+## 1.0.1 - 2025-11-13
+
+- Add OpenSSL as a dev dependency (<https://github.com/nick-f/axm/pull/26>)
+- Store the access token in memory (<https://github.com/nick-f/axm/pull/25>)
+
+## 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/README.md

@@ -58,7 +58,13 @@ 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).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Releasing
+
+1. Update the version number in [lib/axm/version.rb](./lib/axm/version.rb)
+2. Add release notes to [CHANGELOG.md](CHANGELOG.md)
+3. Run the "Release" Action
 
 ## Contributing
 
@@ -70,4 +76,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Axm project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/nick-f/axm/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting with the AXM codebase and issue tracker is expected to follow the [code of conduct](https://github.com/nick-f/axm/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/lib/axm/client/mdm_servers.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+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,78 @@
+# frozen_string_literal: true
+
+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.
+      # rubocop:disable Metrics/MethodLength
+      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
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end

data/lib/axm/client/organization_devices.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Axm
   class Client
     module OrganizationDevices
@@ -11,7 +13,7 @@ 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/orgDevices", options)
+        get('v1/orgDevices', options)
       end
 
       # Retrieves information about a specific device in the organization.
@@ -25,6 +27,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

@@ -1,13 +1,20 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'jwt'
 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
+  # rubocop: disable Metrics/ClassLength
   class Client
+    include MdmServers
+    include OrganizationDeviceActivities
     include OrganizationDevices
 
     # Initializes a new instance of the AXM client.
@@ -54,13 +61,14 @@ module Axm
       end
     end
 
+    # rubocop: disable Metrics/MethodLength
     def client_assertion
       @client_assertion ||= begin
         audience = 'https://account.apple.com/auth/oauth2/v2/token'
         algo = 'ES256'
 
         issued_at_timestamp = Time.now.utc.to_i
-        expiration_timestamp = issued_at_timestamp + 86_400 * 180 # 180 days
+        expiration_timestamp = issued_at_timestamp + (86_400 * 180) # 180 days
 
         payload = {
           sub: @client_id,
@@ -74,34 +82,23 @@ module Axm
         JWT.encode(payload, @private_key, algo, kid: @key_id)
       end
     end
+    # rubocop: enable Metrics/MethodLength
 
     def access_token
-      cached_access_token = JSON.parse(Secret.read('stub_access_token')) if File.exist?('secrets/stub_access_token')
-
-      if cached_access_token
-        token_expiration = Time.parse(cached_access_token['expires_at'])
+      if @cached_access_token
+        token_expiration = Time.parse(@cached_access_token['expires_at'])
         token_expired = Time.now.utc >= token_expiration
 
-        return cached_access_token unless token_expired
+        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
 
-      token = response_body.merge!({ 'expires_at' => Time.now.utc + response_body['expires_in'] })
-
-      Secret.write('stub_access_token', token.to_json)
+      @cached_access_token = response_body.merge({ 'expires_at' => Time.now.utc + response_body['expires_in'] })
 
-      response_body
+      @cached_access_token
     end
 
     # Sends a GET request to the specified API endpoint.
@@ -111,13 +108,18 @@ module Axm
     #   - :paginate [Boolean] Whether to paginate through all results (unused).
     #   - :fields [Array<String>] Optional fields to include as fields[orgDevices].
     # @return [Hash] The parsed JSON response.
+    # rubocop: disable Metrics/MethodLength, Metrics/AbcSize
     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?
@@ -132,21 +134,30 @@ module Axm
 
       JSON.parse(res.body)
     end
+    # rubocop: enable Metrics/MethodLength, Metrics/AbcSize
 
-    # 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.
+    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+    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 +166,45 @@ 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
+    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+    # 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, use_ssl: true)
+
+      request = add_post_headers(Net::HTTP::Post.new(uri))
+
+      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
+
+    private
+
+    # Adds necessary headers to a POST request.
+    #
+    # @return [Net::HTTP::Post] The modified request with added headers.
+    def add_post_headers(request)
+      request['Host'] = uri.host
+      request['Content-Type'] = 'application/json'
+      request['Authorization'] = "Bearer #{access_token['access_token']}"
+
+      request
+    end
   end
+  # rubocop: enable Metrics/ClassLength
 end

data/lib/axm/secret.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Secret
   def self.read(filename)
     File.read("secrets/#{filename}").strip

data/lib/axm/version.rb

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

data/lib/axm.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "axm/client"
-require_relative "axm/secret"
-require_relative "axm/version"
+require_relative 'axm/client'
+require_relative 'axm/secret'
+require_relative 'axm/version'
 
 module Axm
   class Error < StandardError; end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: axm
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.1
 platform: ruby
 authors:
 - nick-f
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-14 00:00:00.000000000 Z
+date: 2025-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -24,7 +23,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
-description:
 email:
 - nick@nickf.dev
 executables: []
@@ -40,6 +38,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
@@ -51,7 +51,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/nick-f/axm
   source_code_uri: https://github.com/nick-f/axm
-post_install_message:
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -66,8 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.5
 specification_version: 4
 summary: Gem to interact with the Apple Business Manager/Apple School Manager API
 test_files: []