milady-cima-api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd05960749c0262fe3d556d454389a4183d248dc4a89b87828527ae343c77b6a
-  data.tar.gz: 00e6c1fc23a40ba8b5211e85f5fa2cf946bca67cc5086db91b5fc4ad557cf178
+  metadata.gz: 8e9fdba0b8e942edd14809c180519a39323e7110110b6c862a2006b331741206
+  data.tar.gz: d4c5eadceb6dc83739abab360ff44137c7d42b254d86c829d53c1e5aca0aabc0
 SHA512:
-  metadata.gz: 20976e6b55d286b1b422cbd7dfef4ed1492bcb434012a55986ac17df905d7dbcb4403f2756bb70437a8f41896d37d305501769c25a757df5b72163b7d4d52afb
-  data.tar.gz: 668252325045549f3ccc9329b8c9823bb13e1cec9031689cc63cc6852c5f028c72e06b3df563ade3245b6bb7bac16882f2f2b1f44b8106c6c3d8fce5caa956fe
+  metadata.gz: 49bbf4f1f574aa9b5d2b6b07f18a943bc2660cb265ccbac038b21ea08e40ae177d631ca0382411d68280a679d886a6fd9a8db8611ab77fc4cc52f70ef71c9fe6
+  data.tar.gz: be4ba9b6f41686c4a8acfcaa16a503e17d43b49a59cf6c6b0ea6c91fb5a3b94bf82e500a282f00aedbf0dbd7cb72e9d11869d06d1e908ac81045f4b33f10bfbe

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [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
+- Added `verify_ssl` option to `Client` initialization (defaults to `true`) to allow disabling SSL verification for testing or development.
+- Added `Courses#find` method to retrieve a single course.
+- Added live integration tests for `Courses` and `Assessments` filters (skipped by default).
+
+### Changed
+- Updated `Courses#list` to use explicit keyword arguments for better documentation and usability, matching `Assessments#list`.
+
 ## [0.2.0] - 2025-12-04
 
 ### Added

data/lib/milady_cima_api/client.rb

@@ -10,13 +10,15 @@ module MiLadyCimaApi
     API_PAGE_LIMIT = 100
 
     attr_reader :api_key, :base_url
+    attr_reader :api_key, :base_url, :verify_ssl
     attr_reader :users, :organizations, :courses
 
-    def initialize(api_key:, base_url: DEFAULT_BASE_URL)
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, verify_ssl: true)
       raise ArgumentError, 'api_key is required' if api_key.nil? || api_key.strip.empty?
 
       @api_key = api_key
       @base_url = base_url.chomp('/')
+      @verify_ssl = verify_ssl
       @users = MiLadyCimaApi::Resources::Users.new(self)
       @organizations = MiLadyCimaApi::Resources::Organizations.new(self)
       @courses = MiLadyCimaApi::Resources::Courses.new(self)
@@ -100,6 +102,7 @@ module MiLadyCimaApi
     def perform_request(uri, request)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == 'https'
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE unless verify_ssl
       response = http.request(request)
       handle_response(response)
     end

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,39 +1,65 @@
 # 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
-      # @param params [Hash] Optional query params. Supports the special key
-      #   "$filter" (String or Hash). If provided as a Hash, it will be JSON-encoded
-      #   to match the API expectation (e.g., {"organization_id" => 123} or
-      #   {"and" => [{"gt" => {"metadata.created_at" => "2025-01-01T00:00:00.000Z"}}]}).
-      # @option params [String, Hash] :$filter JSON string or Ruby Hash representing the filter
+      # @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 order [String] Comma separated attribute names to sort by
+      # @param include [String] Comma separated list of relationships to include
       # @return [Array, Hash] Parsed JSON response from the API
-      # @raise [MiLadyCimaApi::UnauthorizedError, MiLadyCimaApi::NotFoundError, MiLadyCimaApi::ClientError, MiLadyCimaApi::ServerError]
-      def list(params = {})
-        params = params.dup || {} || {}
-        normalize_filter_param!(params)
+      def list(filter: nil, limit: nil, offset: nil, after: nil, count: nil, order: nil, include: 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['$order'] = order if order
+        params['$include'] = include if include
+
         @client.get('/courses', params: params)
       end
 
+      # Get a single course
+      #
+      # GET /courses/{id}
+      # @param id [Integer, String] ID of the course
+      # @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?
+
+        params = {}
+        params['$include'] = include if include
+
+        @client.get("/courses/#{id}", params: params)
+      end
+
       # Convenience: List courses by organization
       # @param organization_id [Integer, String]
       # @param extra_params [Hash] Additional query params (e.g., pagination)
@@ -41,7 +67,7 @@ module MiLadyCimaApi
       def by_organization(organization_id:, **extra_params)
         raise ArgumentError, 'organization_id is required' if organization_id.nil?
         filter = { 'organization_id' => organization_id }
-        list({ '$filter' => filter }.merge(extra_params))
+        list(filter: filter, **extra_params)
       end
 
       # Convenience: List courses filtered by created_at with comparison operator
@@ -61,27 +87,12 @@ module MiLadyCimaApi
                    { 'and' => [time_filter, { 'organization_id' => organization_id }] }
                  end
 
-        list({ '$filter' => filter }.merge(extra_params))
+        list(filter: filter, **extra_params)
       end
 
-      private
-
-      # Mutates params hash to ensure $filter is a JSON string when provided as a Hash
-      def normalize_filter_param!(params)
-        # support both symbol and string keys
-        filter_key = params.key?(:$filter) ? :$filter : (params.key?("$filter") ? "$filter" : nil)
-        return unless filter_key
-
-        value = params[filter_key]
-        case value
-        when Hash
-          params[filter_key] = JSON.generate(value)
-        when String
-          # pass through
-        else
-          raise ArgumentError, "$filter must be a String (JSON) or a Hash"
-        end
-      end
     end
   end
 end
+
+require_relative 'courses/assessments'
+require_relative 'courses/learners'

data/lib/milady_cima_api/version.rb

@@ -2,5 +2,5 @@
 
 module MiLadyCimaApi
   # Gem version
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: milady-cima-api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - marcus.salinas
@@ -27,8 +27,10 @@ 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/version.rb