milady-cima-api 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cba4eea16f1a7f12d7085606bdadee4927918c7f960d2bd95ee4b9f10909f0f
-  data.tar.gz: e0519d5dfa0eacecf95237a65669ec5b232d23eb334bf50b9349b501887f1bbb
+  metadata.gz: e7a0502a36b75c80c03711804558c9396a5e0b8bc28aa904ee4fbca86a7c28ba
+  data.tar.gz: 8a32eabd2e1a6d6157bdae2c1cb64428e6572aba4cb11a6ba4b4cf904b8d6e1f
 SHA512:
-  metadata.gz: e872f0ae20e5bb564e219625426e4f853cc65ff48ac20a36c73879b7e7dcc4351c22ff6ce5fdb0aee612e11f76fce8cf38588005f54777897c2257c162c630f6
-  data.tar.gz: 4aedb0de4d77fa84fc8d430fb4dfc3df3ca61e6279785a7dd4750490493ee1cfec2003e8b5583d5d5f7afef19a1a5007ed8b12a0a83fb786bfcb4cf2499f9201
+  metadata.gz: 74f6e46875750a10b53cf5051d2b1ba543fb9dcc7ab4f3ef2e5eb1c7bb7e85c3884aa3b51d5878bd850c0cdeb51fca57ea3be4277becac23ddec1d5c9facf33a
+  data.tar.gz: 9348229a5ff3940265d8afa641cb64fa1ba6b0c3fdd036cb17f3b9b02988c12c4a3e6fb45223b4f66494fc9105b21eaeac62fb023f6031f0b26cc0e2c32cfd61

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.4.0] - 2025-12-04
+
+### Added
+- Added `CourseLearners` resource under `Users` to support `GET /users/{id}/course_learners`.
+- Added `Users#find` method to retrieve a single user.
+
+### Changed
+- Updated `Users#list` to use explicit keyword arguments for better documentation and usability.
+- Removed custom `Users#list_by_organization` and `Users#list_learners_by_organization` methods in favor of standardized `list` with filters.
+
+## [0.3.0] - 2025-12-04
+
+### Added
+- Added `Learners` resource under `Courses` to support `GET /courses/{id}/learners` and `GET /courses/{id}/learners/{user_id}`.
+
+### Changed
+- Refactored `Courses`, `Assessments`, and `Learners` resources to inherit from a common `Base` class to share initialization and filter normalization logic.
+
 ## [0.2.1] - 2025-12-04
 
 ### Added

data/lib/milady_cima_api/resources/base.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module MiLadyCimaApi
+  module Resources
+    class Base
+      # @param client [MiLadyCimaApi::Client]
+      def initialize(client)
+        @client = client
+      end
+
+      protected
+
+      def normalize_filter(filter)
+        return filter if filter.is_a?(String)
+        return JSON.generate(filter) if filter.is_a?(Hash)
+
+        raise ArgumentError, 'filter must be a String (JSON) or a Hash'
+      end
+    end
+  end
+end

data/lib/milady_cima_api/resources/courses/assessments.rb

@@ -1,14 +1,12 @@
 # frozen_string_literal: true
 
+require_relative '../base'
+
 module MiLadyCimaApi
   module Resources
     class Courses
       # Assessments resource exposes endpoints under /courses/{id}/assessments
-      class Assessments
-        # @param client [MiLadyCimaApi::Client]
-        def initialize(client)
-          @client = client
-        end
+      class Assessments < Resources::Base
 
         # List assessments for a course
         #
@@ -50,14 +48,6 @@ module MiLadyCimaApi
           @client.get("/courses/#{course_id}/assessments/#{assessment_id}")
         end
 
-        private
-
-        def normalize_filter(filter)
-          return filter if filter.is_a?(String)
-          return JSON.generate(filter) if filter.is_a?(Hash)
-
-          raise ArgumentError, 'filter must be a String (JSON) or a Hash'
-        end
       end
     end
   end

data/lib/milady_cima_api/resources/courses/learners.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../base'
+
+module MiLadyCimaApi
+  module Resources
+    class Courses
+      # Learners resource exposes endpoints under /courses/{id}/learners
+      class Learners < Resources::Base
+
+        # List learners for a course
+        #
+        # GET /courses/{id}/learners
+        # @param course_id [Integer, String] ID of the course
+        # @param filter [Hash, String] Filter using JSON structure
+        # @param limit [Integer] Limit the number of returned objects (default 10, max 100)
+        # @param offset [Integer] Used for paging through a small dataset
+        # @param after [Integer] Used for fast paging
+        # @param count [Boolean] If true, just return the number of list items
+        # @param include [String] Comma separated list of relationships to include
+        # @return [Array, Hash] Parsed JSON response from the API
+        def list(course_id:, filter: nil, limit: nil, offset: nil, after: nil, count: nil, include: nil)
+          raise ArgumentError, 'course_id is required' if course_id.nil?
+
+          if limit && limit > 100
+            raise ArgumentError, 'limit cannot be greater than 100'
+          end
+
+          params = {}
+          params['$filter'] = normalize_filter(filter) if filter
+          params['$limit'] = limit if limit
+          params['$offset'] = offset if offset
+          params['$after'] = after if after
+          params['$count'] = count if count
+          params['$include'] = include if include
+
+          @client.get("/courses/#{course_id}/learners", params: params)
+        end
+
+        # Get a single learner
+        #
+        # GET /courses/{id}/learners/{user_id}
+        # @param course_id [Integer, String] ID of the course
+        # @param user_id [Integer, String] ID of the user
+        # @param include [String] Comma separated list of relationships to include
+        # @return [Hash] Parsed JSON response from the API
+        def find(course_id:, user_id:, include: nil)
+          raise ArgumentError, 'course_id is required' if course_id.nil?
+          raise ArgumentError, 'user_id is required' if user_id.nil?
+
+          params = {}
+          params['$include'] = include if include
+
+          @client.get("/courses/#{course_id}/learners/#{user_id}", params: params)
+        end
+
+      end
+    end
+  end
+end

data/lib/milady_cima_api/resources/courses.rb

@@ -1,23 +1,22 @@
 # frozen_string_literal: true
-
-require 'json'
-require_relative 'courses/assessments'
+require_relative 'base'
 
 module MiLadyCimaApi
   module Resources
     # Courses resource exposes endpoints under /courses
     # Provides convenience helpers for building $filter queries.
-    class Courses
-      # @param client [MiLadyCimaApi::Client]
-      def initialize(client)
-        @client = client
-      end
+    class Courses < Base
 
       # @return [MiLadyCimaApi::Resources::Courses::Assessments]
       def assessments
         @assessments ||= Assessments.new(@client)
       end
 
+      # @return [MiLadyCimaApi::Resources::Courses::Learners]
+      def learners
+        @learners ||= Learners.new(@client)
+      end
+
       # List courses
       #
       # GET /courses
@@ -91,14 +90,9 @@ module MiLadyCimaApi
         list(filter: filter, **extra_params)
       end
 
-      private
-
-      def normalize_filter(filter)
-        return filter if filter.is_a?(String)
-        return JSON.generate(filter) if filter.is_a?(Hash)
-
-        raise ArgumentError, 'filter must be a String (JSON) or a Hash'
-      end
     end
   end
 end
+
+require_relative 'courses/assessments'
+require_relative 'courses/learners'

data/lib/milady_cima_api/resources/users/course_learners.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative '../base'
+
+module MiLadyCimaApi
+  module Resources
+    class Users
+      # CourseLearners resource exposes endpoints under /users/{id}/course_learners
+      class CourseLearners < Resources::Base
+
+        # List user course learners
+        #
+        # GET /users/{id}/course_learners
+        # @param user_id [Integer, String] ID of the user
+        # @param after [Integer] Used for fast paging
+        # @param count [Boolean] If true, just return the number of list items
+        # @param filter [Hash, String] Filter using JSON structure
+        # @param include [String] Comma separated list of relationships to include
+        # @param limit [Integer] Limit the number of returned objects (default 10, max 100)
+        # @param offset [Integer] Used for paging through a small dataset
+        # @return [Array, Hash] Parsed JSON response from the API
+        def list(user_id:, after: nil, count: nil, filter: nil, include: nil, limit: nil, offset: nil)
+          raise ArgumentError, 'user_id is required' if user_id.nil?
+
+          if limit && limit > 100
+            raise ArgumentError, 'limit cannot be greater than 100'
+          end
+
+          params = {}
+          params['$after'] = after if after
+          params['$count'] = count if count
+          params['$filter'] = normalize_filter(filter) if filter
+          params['$include'] = include if include
+          params['$limit'] = limit if limit
+          params['$offset'] = offset if offset
+
+          @client.get("/users/#{user_id}/course_learners", params: params)
+        end
+
+      end
+    end
+  end
+end

data/lib/milady_cima_api/resources/users.rb

@@ -1,60 +1,62 @@
 # frozen_string_literal: true
 
+require_relative 'base'
+
 module MiLadyCimaApi
   module Resources
     # Users resource exposes endpoints under /users
-    class Users
-      # @param client [MiLadyCimaApi::Client]
-      def initialize(client)
-        @client = client
+    class Users < Base
+
+      # @return [MiLadyCimaApi::Resources::Users::CourseLearners]
+      def course_learners
+        @course_learners ||= CourseLearners.new(@client)
       end
 
-      # List users.
+      # List users
       #
       # GET /users
-      # @param params [Hash] Optional query params (e.g., pagination)
+      # @param after [Integer] Used for fast paging
+      # @param count [Boolean] If true, just return the number of list items
+      # @param filter [Hash, String] Filter using JSON structure
+      # @param include [String] Comma separated list of relationships to include
+      # @param limit [Integer] Limit the number of returned objects (default 10, max 100)
+      # @param offset [Integer] Used for paging through a small dataset
+      # @param order [String] Comma separated attribute names to sort by
       # @return [Array, Hash] Parsed JSON response from the API
-      # @raise [MiLadyCimaApi::UnauthorizedError, MiLadyCimaApi::NotFoundError, MiLadyCimaApi::ClientError, MiLadyCimaApi::ServerError]
-      def list(params = {})
-        @client.get('/users', params: params)
-      end
+      def list(after: nil, count: nil, filter: nil, include: nil, limit: nil, offset: nil, order: nil)
+        if limit && limit > 100
+          raise ArgumentError, 'limit cannot be greater than 100'
+        end
 
-      # List users by organization.
-      #
-      # GET /users with organization filter
-      # @param organization_id [String, Integer] Organization ID to filter by
-      # @param role [String, nil] Optional role to filter by (e.g., 'Learner')
-      # @param params [Hash] Optional additional query params (e.g., pagination)
-      # @return [Array, Hash] Parsed JSON response from the API
-      # @raise [MiLadyCimaApi::UnauthorizedError, MiLadyCimaApi::NotFoundError, MiLadyCimaApi::ClientError, MiLadyCimaApi::ServerError]
-      def list_by_organization(organization_id, role: nil, **params)
-        filter = build_organization_filter(organization_id, role: role)
-        @client.get('/users', params: params.merge('$filter': filter))
-      end
+        params = {}
+        params['$after'] = after if after
+        params['$count'] = count if count
+        params['$filter'] = normalize_filter(filter) if filter
+        params['$include'] = include if include
+        params['$limit'] = limit if limit
+        params['$offset'] = offset if offset
+        params['$order'] = order if order
 
-      # List learners by organization.
-      #
-      # GET /users with organization and Learner role filter
-      # @param organization_id [String, Integer] Organization ID to filter by
-      # @param params [Hash] Optional additional query params (e.g., pagination)
-      # @return [Array, Hash] Parsed JSON response from the API
-      # @raise [MiLadyCimaApi::UnauthorizedError, MiLadyCimaApi::NotFoundError, MiLadyCimaApi::ClientError, MiLadyCimaApi::ServerError]
-      def list_learners_by_organization(organization_id, **params)
-        list_by_organization(organization_id, role: 'Learner', **params)
+        @client.get('/users', params: params)
       end
 
-      private
+      # Get user
+      #
+      # GET /users/{id}
+      # @param id [Integer, String] ID of the user
+      # @param include [String] Comma separated list of relationships to include
+      # @return [Hash] Parsed JSON response from the API
+      def find(id:, include: nil)
+        raise ArgumentError, 'id is required' if id.nil?
 
-      # Build filter object for organization and optional role
-      # @param organization_id [String, Integer]
-      # @param role [String, nil]
-      # @return [Hash] Filter hash
-      def build_organization_filter(organization_id, role: nil)
-        conditions = [{ eq: { organization_id: organization_id } }]
-        conditions << { contains: { roles: role } } if role
+        params = {}
+        params['$include'] = include if include
 
-        { and: conditions }
+        @client.get("/users/#{id}", params: params)
       end
+
     end
   end
-end
+end
+
+require_relative 'users/course_learners'

data/lib/milady_cima_api/version.rb

@@ -2,5 +2,5 @@
 
 module MiLadyCimaApi
   # Gem version
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: milady-cima-api
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - marcus.salinas
@@ -27,10 +27,13 @@ files:
 - lib/milady_cima_api.rb
 - lib/milady_cima_api/client.rb
 - lib/milady_cima_api/errors.rb
+- lib/milady_cima_api/resources/base.rb
 - lib/milady_cima_api/resources/courses.rb
 - lib/milady_cima_api/resources/courses/assessments.rb
+- lib/milady_cima_api/resources/courses/learners.rb
 - lib/milady_cima_api/resources/organizations.rb
 - lib/milady_cima_api/resources/users.rb
+- lib/milady_cima_api/resources/users/course_learners.rb
 - lib/milady_cima_api/version.rb
 homepage: https://github.com/jippylong12/milady-cima-api
 licenses: