ninjaone 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69cf374dfc56664fdbbc61533fcffbc84cc8f378cc422641be286b5740d04d8f
-  data.tar.gz: e4f573f19bb88b7173a035622e65a86119ca20276806fa4df2ce40d2752adc29
+  metadata.gz: 14e3e9d7389ec68d56ab1289d050a76c4287c223dec960df4201f236c7d24632
+  data.tar.gz: b78f6990641e9782d5033f9b2c4940fcb8e0464ba8c89ab01c7905bd54aca54e
 SHA512:
-  metadata.gz: '0090ba275e371d7064dee5ca2f432eb239ef6d31aa0aba63849c740834cc0c2cb6456d4d7f588a99475cb9ffa1add1c1349973b61c6c34e5ae3a90ae95b2966f'
-  data.tar.gz: 7d07158ecb6ab23ea23587453dfdadaf35df8906c8f5fbefa0c51e220782a866955338ca4dd849e9b49142dfd6c0f428859f60fe8ead3b401c072354489d97e2
+  metadata.gz: 6ae0f84a5385fcff884d4de3830c9089bca742d8f8f8ba641e41d91231bb365cb9b800cb391ca7da2729c7be7bbbb265975dbbae11101b5bc74f69907ab828d0
+  data.tar.gz: df9bff698081312e3c1d11f4b319f554f3d091f02c34c5ad23eb20d4793f00883dec12269d55c3e3ec072ef5a4499263f8faea2b535c1ddcbe93fa4a88849824

data/CHANGELOG.md

@@ -12,3 +12,8 @@
 
 - Simplify api endpoint definition
 
+## [0.3.0] - 2026-1-19
+
+- Implement (cursor) paging
+- Support Group, Location, Queries, Users API
+

data/README.md

@@ -5,7 +5,7 @@
 This is a wrapper for the ninjaone API.
 You can see the [API endpoints](https://app.ninjarmm.com/apidocs/)
 
-Currently only the GET requests to endpoints 
+Currently only the GET requests to endpoints
 are implemented (readonly).
 
 ## Installation
@@ -73,93 +73,161 @@ client.login
 Core system Entities and Resources
 
 ```ruby
-subscriptions = client.subscriptions
+client.organizations
+client.devices
+client.contacts
 ```
 
-|Resource|API endpoint|
+|Method|Description|
 |:--|:--|
-|`contacts`, `contact(id)`|List contact and get contact details|
-|`organizations`|list organizations|
-|`policies`|list policies|
-|`jobs`|list active jobs|
-|`activities`|list activities|
-|`alerts`|List active alerts (triggered conditions)|
-|`automation_scripts`|List available automation scripts|
-|`device_custom_fields`|List device custom fields|
-|`devices`|List devices|
-|`devices_detailed`|List devices(deatiled)|
-|`notification_channels_enabled`|List enabled notification channels|
-|`notification_channels`|List all notification channels|
-|`notification_channels_detailed`|List all notification channels detailed|
-|`groups`|List all groups (saved searches)|
-|`locations`|List all locations|
-|`roles`|List device roles|
-|`tasks`|List scheduled tasks|
-|`software_products`|List supported 3rd party software|
-|`users`|List users|
-|`search_devices(query_string)`|Find devices|
-|`user_end_users`|End user list|
-|`user_technicians`|Technicians list|
-|`user_roles`|Get user roles|
+|`contacts(params = {})`|List all contacts|
+|`contact(id, params = {})`|Retrieve a specific contact by ID|
+|`organizations(params = {})`|List all organizations|
+|`organization(id, params = {})`|Retrieve a specific organization by ID|
+|`organizations_detailed(params = {})`|List all organizations with detailed information|
+|`policies(params = {})`|List all policies|
+|`jobs(params = {})`|List all active jobs|
+|`activities(params = {})`|List all activities|
+|`alerts(params = {})`|List all active alerts (triggered conditions)|
+|`automation_scripts(params = {})`|List available automation scripts|
+|`devices(params = {})`|List all devices|
+|`devices_detailed(params = {})`|List all devices with detailed information|
+|`notification_channels_enabled(params = {})`|List enabled notification channels|
+|`notification_channels(params = {})`|List all notification channels|
+|`groups(params = {})`|List all groups (saved searches)|
+|`locations(params = {})`|List all locations|
+|`roles(params = {})`|List device roles|
+|`tasks(params = {})`|List scheduled tasks|
+|`software_products(params = {})`|List supported 3rd party software|
+|`users(params = {})`|List all users|
+|`user_end_users(params = {})`|List end users|
+|`user_technicians(params = {})`|List technicians|
+|`user_roles(params = {})`|Get user roles|
+|`devices_search(params = {})`|Search devices by query parameter `q`|
+|`search_devices(query_string, options = {})`|Helper method to search devices (equivalent to `devices_search({q: query_string})`)|
 
 ### Organizations
 
-All apis related to organizations
+All APIs related to organizations
 
 ```ruby
-org = client.organizations.first
-org_devices = client.organization_devices(org.id)
-
+organizations = client.organizations
+org_id = organizations.first.id
+org_devices = client.organization_devices(org_id)
 ```
 
-|Resource|API endpoint|
+|Method|Description|
 |:--|:--|
-|`organizations`,`organization(id)`|List organizations or get one by id|
-|`organization_locations(id)`|Organization locations|
-|`organization_end_users(id)`|List users|
-|`organization_custom_fields(id)`|Organization custom fields|
-|`organization_devices(id)`|Organization devices|
-|`organization_locations_backup_usage(id)`|Organization location backup usage|
-|`organization_backup_usage_by_location(id, location_id)`|Organization locations backup usage|
+|`organization(id, params = {})`|Retrieve a specific organization by ID|
+|`organization_locations(id, params = {})`|List all locations for the specified organization|
+|`organization_end_users(id, params = {})`|List all end users in the specified organization|
+|`organization_custom_fields(id, params = {})`|Retrieve custom fields for the specified organization|
+|`organization_devices(id, params = {})`|List all devices in the specified organization|
+|`organization_locations_backup_usage(id, params = {})`|Retrieve backup usage for all locations in the specified organization|
+|`organization_backup_usage_by_location(id, location_id, params = {})`|Retrieve backup usage for a specific location in the specified organization|
+|`organization_location_custom_fields(id, location_id, params = {})`|Retrieve custom fields for a specific location in the specified organization|
 
 ### Backup
 
-All apis related to backup
+All APIs related to backup
 
 ```ruby
-# get failed jobs using status filter
-failed_jobs = client.backup_jobs(sf:'status = FAILED')
+# Get failed jobs using status filter
+failed_jobs = client.backup_jobs(sf: 'status = FAILED')
+integrity_jobs = client.backup_integrity_checks_jobs
 ```
 
-|Resource|API endpoint|
+|Method|Description|
 |:--|:--|
-|`backup_jobs(params)`|Returns list of backup jobs. Params is a hash for filtering the result|
-|`backup_integrity_check_jobs(params)`|Returns a list of integrity check jobs|
+|`backup_jobs(params = {})`|List all backup jobs. Supports filtering via `sf` (filter) and `sc` (sort) parameters|
+|`backup_integrity_checks_jobs(params = {})`|List all backup integrity check jobs. Supports filtering and sorting parameters|
 
 ### Devices
 
-All apis related to devices.
+All APIs related to devices
+
+```ruby
+device = client.device(12345)
+device_jobs = client.device_jobs(12345)
+device_activities = client.device_activities(12345, since: '2026-01-01T00:00:00Z')
+group_device_ids = client.group_device_ids(group_id)
+```
 
-| Resource | API endpoint |
+|Method|Description|
 |:--|:--|
-| `device(id, params = {})` | Retrieves the details of a single device by its device ID. |
-| `device_jobs(id, params = {})` | Retrieves all jobs associated with the specified device. |
-| `device_activities(id, params = {})` | Retrieves activities for the specified device (e.g. filtered using `since`). |
-| `device_alerts(id, params = {})` | Retrieves alerts related to the specified device. |
-| `device_disks(id, params = {})` | Retrieves disk information for the specified device. |
-| `device_processors(id, params = {})` | Retrieves processor information for the specified device. |
-| `device_software(id, params = {})` | Retrieves installed software for the specified device. |
-| `device_volumes(id, params = {})` | Retrieves volume information for the specified device. |
-| `device_windows_services(id, params = {})` | Retrieves Windows services for the specified device. |
-| `device_custom_fields(id, params = {})` | Retrieves custom fields associated with the specified device. |
-| `device_os_patch_installs(id, params = {})` | Retrieves operating system patch installation records for the specified device. |
-| `device_software_patch_installs(id, params = {})` | Retrieves software patch installation records for the specified device. |
-| `device_last_logged_on_user(id, params = {})` | Retrieves information about the last logged-on user of the device. |
-| `device_network_interfaces(id, params = {})` | Retrieves network interface information for the specified device. |
-| `device_os_patches(id, params = {})` | Retrieves available or installed operating system patches for the device. |
-| `device_software_patches(id, params = {})` | Retrieves available or installed software patches for the device. |
-| `device_policy_overrides(id, params = {})` | Retrieves policy overrides applied to the specified device. |
+|`device(id, params = {})`|Retrieve details of a single device by its device ID|
+|`device_policy_overrides(id, params = {})`|Retrieve policy overrides applied to the specified device|
+|`device_jobs(id, params = {})`|Retrieve all jobs associated with the specified device|
+|`device_activities(id, params = {})`|Retrieve activities for the specified device (supports `since` filtering)|
+|`device_alerts(id, params = {})`|Retrieve alerts related to the specified device|
+|`device_disks(id, params = {})`|Retrieve disk information for the specified device|
+|`device_processors(id, params = {})`|Retrieve processor information for the specified device|
+|`device_software(id, params = {})`|Retrieve installed software for the specified device|
+|`device_volumes(id, params = {})`|Retrieve volume information for the specified device|
+|`device_windows_services(id, params = {})`|Retrieve Windows services for the specified device|
+|`device_custom_fields(id, params = {})`|Retrieve custom fields associated with the specified device|
+|`device_os_patch_installs(id, params = {})`|Retrieve operating system patch installation records for the specified device|
+|`device_software_patch_installs(id, params = {})`|Retrieve software patch installation records for the specified device|
+|`device_last_logged_on_user(id, params = {})`|Retrieve information about the last logged-on user of the device|
+|`device_network_interfaces(id, params = {})`|Retrieve network interface information for the specified device|
+|`device_os_patches(id, params = {})`|Retrieve available or installed operating system patches for the device|
+|`device_software_patches(id, params = {})`|Retrieve available or installed software patches for the device|
+|`group_device_ids(id, params = {})`|Retrieve device IDs for all devices in the specified group|
+
+### Users
+
+All APIs related to user management
+
+```ruby
+end_user = client.user_end_user(end_user_id)
+end_user_custom_fields = client.user_end_user_custom_fields(end_user_id)
+technician = client.user_technician(technician_id)
+```
 
+|Method|Description|
+|:--|:--|
+|`user_end_user(id, params = {})`|Retrieve details of a specific end user|
+|`user_end_user_custom_fields(id, params = {})`|Retrieve custom fields for a specific end user|
+|`user_technician(id, params = {})`|Retrieve details of a specific technician|
+
+### Queries
+
+Query endpoints that support pagination for advanced data retrieval
+
+```ruby
+av_status = client.queries_antivirus_status
+device_health = client.queries_device_health
+software_list = client.queries_software
+```
+
+All query methods support pagination and filtering parameters. Query methods return paginated results.
+
+|Method|Description|
+|:--|:--|
+|`queries_antivirus_status(params = {})`|Query antivirus status across devices|
+|`queries_antivirus_threats(params = {})`|Query antivirus threats across devices|
+|`queries_computer_systems(params = {})`|Query computer system information|
+|`queries_custom_fields_detailed(params = {})`|Query custom fields with detailed information|
+|`queries_custom_fields(params = {})`|Query custom fields|
+|`queries_device_health(params = {})`|Query device health status|
+|`queries_backup_usage(params = {})`|Query backup usage across devices|
+|`queries_disks(params = {})`|Query disk information|
+|`queries_os_patch_installs(params = {})`|Query operating system patch installations|
+|`queries_software_patch_installs(params = {})`|Query software patch installations|
+|`queries_logged_on_users(params = {})`|Query currently logged-on users|
+|`queries_network_interfaces(params = {})`|Query network interface information|
+|`queries_operating_systems(params = {})`|Query operating system information|
+|`queries_os_patches(params = {})`|Query operating system patches|
+|`queries_software_patches(params = {})`|Query software patches|
+|`queries_policy_overrides(params = {})`|Query policy overrides|
+|`queries_processors(params = {})`|Query processor information|
+|`queries_raid_controllers(params = {})`|Query RAID controller information|
+|`queries_raid_drives(params = {})`|Query RAID drive information|
+|`queries_scoped_custom_fields_detailed(params = {})`|Query scoped custom fields with detailed information|
+|`queries_scoped_custom_fields(params = {})`|Query scoped custom fields|
+|`queries_software(params = {})`|Query software information|
+|`queries_volumes(params = {})`|Query volume information|
+|`queries_windows_services(params = {})`|Query Windows services|
 
 ## Contributing
 

data/lib/ninjaone/client/backup.rb

@@ -8,8 +8,8 @@ module NinjaOne
     module Backup
 
       # Backup endpoints (GET)
-      Client::define_endpoint('backup/jobs')
-      Client::define_endpoint('backup/integrity-check-jobs')
+      Client::define_endpoint('backup/jobs', nil, true)
+      Client::define_endpoint('backup/integrity-check-jobs', nil, true)
     end
   end
 end

data/lib/ninjaone/client/devices.rb

@@ -2,12 +2,14 @@
 
 module NinjaOne
   class Client
-    # Contains Device-related API calls for Ninja One.
+    # Contains Device and group related API calls for Ninja One.
     #
     # @see https://app.ninjarmm.com/apidocs/?links.active=core#/Devices Ninja One Developer Documentation - Device section
     module Devices
 
       Client::define_endpoint(:device, '')
+      Client::define_endpoint(:device, 'policy/overrides')
+      Client::define_endpoint(:group, 'device-ids')
 
       # Device-related GET endpoints.
       #
@@ -22,7 +24,6 @@ module NinjaOne
        :os_patch_installs, :software_patch_installs, :last_logged_on_user, :network_interfaces, :os_patches, :software_patches].each do |resource|
         Client::define_endpoint(:device, resource.to_s.gsub('_','-'))
       end
-      Client::define_endpoint(:device, 'policy/overrides')
     end
   end
 end

data/lib/ninjaone/client/organizations.rb

@@ -2,7 +2,7 @@
 
 module NinjaOne
   class Client
-    # Contains Organizations API calls for Ninja One.
+    # Contains Organizations and location API calls for Ninja One.
     #
     # @see https://app.ninjarmm.com/apidocs/?links.active=core#/organization Ninja One Developer Documentation
     module Organizations
@@ -20,6 +20,10 @@ module NinjaOne
         # it looks like a server error is thrown when no backup is available; fake it by returning an empty array
         []
       end
+      # Returns custom fields for an organization location
+      def organization_location_custom_fields(id, location_id, params={})
+        get(api_url("organization/#{id}/location/#{location_id}/custom-fields"), params)
+      end
     end
   end
 end

data/lib/ninjaone/client/queries.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module NinjaOne
+  class Client
+    # Contains Queries API calls for Ninja One.
+    #
+    # @see https://app.ninjarmm.com/apidocs/?links.active=core#/queries Ninja One Developer Documentation
+    module Queries
+      Client::define_endpoint('queries/antivirus-status', nil, true)
+      Client::define_endpoint('queries/antivirus-threats', nil, true)
+      Client::define_endpoint('queries/computer-systems', nil, true)
+      Client::define_endpoint('queries/custom-fields-detailed', nil, true)
+      Client::define_endpoint('queries/custom-fields', nil, true)
+      Client::define_endpoint('queries/device-health', nil, true)
+      Client::define_endpoint('queries/backup/usage', nil, true)
+      Client::define_endpoint('queries/disks', nil, true)
+      Client::define_endpoint('queries/os-patch-installs', nil, true)
+      Client::define_endpoint('queries/software-patch-installs', nil, true)
+      Client::define_endpoint('queries/logged-on-users', nil, true)
+      Client::define_endpoint('queries/network-interfaces', nil, true)
+      Client::define_endpoint('queries/operating-systems', nil, true)
+      Client::define_endpoint('queries/os-patches', nil, true)
+      Client::define_endpoint('queries/software-patches', nil, true)
+      Client::define_endpoint('queries/policy-overrides', nil, true)
+      Client::define_endpoint('queries/processors', nil, true)
+      Client::define_endpoint('queries/raid-controllers', nil, true)
+      Client::define_endpoint('queries/raid-drives', nil, true)
+      Client::define_endpoint('queries/scoped-custom-fields-detailed', nil, true)
+      Client::define_endpoint('queries/scoped-custom-fields', nil, true)
+      Client::define_endpoint('queries/software', nil, true)
+      Client::define_endpoint('queries/volumes', nil, true)
+      Client::define_endpoint('queries/windows-services', nil, true)
+    end
+  end
+end

data/lib/ninjaone/client/users.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module NinjaOne
+  class Client
+    # Contains Organizations API calls for Ninja One.
+    #
+    # @see https://app.ninjarmm.com/apidocs/?links.active=core#/users Ninja One Developer Documentation
+    module Users
+
+      Client::define_endpoint('user/end-user', '')
+      Client::define_endpoint('user/end-user', 'custom-fields')
+      Client::define_endpoint('user/technician', '')
+    end
+  end
+end

data/lib/ninjaone/client.rb

@@ -34,7 +34,7 @@ module NinjaOne
     #   # Defines:
     #   # - `companies(params = {})` to fetch all companies.
     #   # - `company(id, params = {})` to fetch a single company by ID.
-    def self.define_endpoint(scope, resource = nil)
+    def self.define_endpoint(scope, resource = nil, paged = false)
       if resource
         name = self.resource_to_name(scope)
         name = "#{name}_#{self.resource_to_name(resource)}" if resource && !resource.empty?
@@ -42,12 +42,14 @@ module NinjaOne
         # but also /scope/id without training / 
         resource = resource&.empty? ? nil : resource
         send(:define_method, name) do |id, params = {}|
-          get(api_url([scope, id, resource].compact.join('/')), params)
+          url = api_url([scope, id, resource].compact.join('/'))
+          paged ? get_paged(url, params) : get(url, params)
         end
       else
         name = self.resource_to_name(scope)
         send(:define_method, name) do |params = {}|
-          get(api_url(scope), params)
+          url = api_url(scope)
+          paged ? get_paged(url, params) : get(url, params)
         end
       end
     end
@@ -64,6 +66,8 @@ module NinjaOne
     include NinjaOne::Client::Organizations
     include NinjaOne::Client::Backup
     include NinjaOne::Client::Devices
+    include NinjaOne::Client::Users
+    include NinjaOne::Client::Queries
 
     # Constructs the full API URL for a given path.
     #

data/lib/ninjaone/cursor_pagination.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'json'
+
+module NinjaOne
+  # Defines HTTP request pagination methods for NinjOne API.
+  # This module handles the pagination strategy required when dealing with paginated
+  # API results. NinjaOne uses Cursor pagination, in combination with `cursor` and `pageSize` parameter
+  module RequestPagination
+    # Maintains pagination state for cursor-based endpoints.
+    #
+    # NinjaOne returns payloads like:
+    #   {
+    #     "cursor": { "name": "string", "offset": 0, "count": 0, "expires": 0 },
+    #     "results": []
+    #   }
+    #
+    # @example Pagination Initialization
+    #   paginator = NinjaOne::RequestPagination::CursorPagination.new(100)
+    #   options = paginator.page_options # => { pageSize: 100 }
+    #
+    # @see https://app.ninjarmm.com/apidocs/?links.active=core#/queries/getAntivirusStatusReport
+    class CursorPagination
+      attr_reader :offset, :limit, :total
+
+      # Initializes the pagination object with the specified page size.
+      # Assumes that pagination starts at the first page (offset 0).
+      #
+      # @param page_size [Integer] Number of results per page
+      def initialize(page_size)
+        @offset = 0
+        @cursor = nil
+        @limit = page_size
+        # Assume at least one page initially (used to short-circuit more_pages? after last page)
+        @total = @limit
+      end
+
+      # Returns the pagination options to be sent as query parameters.
+      # If a cursor is present, it will be included to fetch the next page.
+      #
+      # @return [Hash<Symbol, Integer|String>] Query parameters for pagination
+      def page_options
+        {
+          pageSize: @limit,
+          cursor: @cursor
+        }.compact
+      end
+
+      # Updates the pagination state for the next page based on the current page's data.
+      # The NinjaOne API does not allow skipping
+      #
+      # @param data [Hash] The data from the current page
+      def next_page!(data)
+        # Update the total number of results based on the size of the current data set.
+        if cursor = data['cursor']
+          @total = cursor['count']
+          @offset = cursor['offset']
+          @cursor = cursor['name']
+        else
+          # no cursor, then we're ready
+          @offset = @total
+        end
+      end
+
+      # Processes the API response body and returns it unchanged.
+      # This method can be overridden to handle specific response parsing needs.
+      #
+      # @param body [Hash, Array, String] The response body from the API
+      # @return [Hash, Array, String] Processed data (unchanged)
+      def self.data(body)
+        return body if body.is_a?(Array)
+        body['results'] || body
+      end
+
+      # Checks if more pages are available.
+      # More pages are available if the data has cursor records or if we just start with getting the first page.
+      #
+      # @return [Boolean] `true` if more pages are available, `false` otherwise
+      def more_pages?
+        @offset.zero? || @offset < @total
+      end
+    end
+  end
+end

data/lib/ninjaone/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NinjaOne
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/ninjaone.rb

@@ -2,6 +2,7 @@
 
 require 'wrapi'
 require File.expand_path('ninjaone/api', __dir__)
+require File.expand_path('ninjaone/cursor_pagination', __dir__)
 require File.expand_path('ninjaone/client', __dir__)
 require File.expand_path('ninjaone/version', __dir__)
 
@@ -15,6 +16,7 @@ module NinjaOne
 
   # Default User-Agent header sent with API requests, including gem version information.
   DEFAULT_UA = "NinjaOne Ruby API wrapper #{NinjaOne::VERSION}"
+  DEFAULT_PAGINATION = RequestPagination::CursorPagination
 
   # Creates and returns a new NinjaOne API client with the given options.
   #
@@ -30,7 +32,8 @@ module NinjaOne
   #   client = NinjaOne.client(endpoint: "https://api.custom-endpoint.com", user_agent: "Custom UA/1.0")
   def self.client(options = {})
     NinjaOne::Client.new({
-      user_agent: DEFAULT_UA
+      user_agent: DEFAULT_UA,
+      pagination_class: DEFAULT_PAGINATION
     }.merge(options))
   end
 
@@ -46,5 +49,6 @@ module NinjaOne
   def self.reset
     super
     self.user_agent = DEFAULT_UA
+    self.pagination_class = DEFAULT_PAGINATION
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ninjaone
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Janco Tanis
 bindir: exe
 cert_chain: []
-date: 2026-01-16 00:00:00.000000000 Z
+date: 2026-01-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -111,7 +111,10 @@ files:
 - lib/ninjaone/client/backup.rb
 - lib/ninjaone/client/devices.rb
 - lib/ninjaone/client/organizations.rb
+- lib/ninjaone/client/queries.rb
 - lib/ninjaone/client/system.rb
+- lib/ninjaone/client/users.rb
+- lib/ninjaone/cursor_pagination.rb
 - lib/ninjaone/error.rb
 - lib/ninjaone/version.rb
 - ninjaone.gemspec