mangoapps-ex-sdk-ruby 0.15.2

data/lib/mangoapps/client.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "multi_json"
+require "ostruct"
+
+module MangoApps
+  class Client
+    attr_reader :config, :http, :oauth
+
+    def initialize(config)
+      @config = config
+      @oauth = OAuth.new(config)
+      @http = build_http_client
+    end
+
+    # ---- Authentication ----
+    def access_token
+      @access_token ||= load_access_token
+    end
+
+    def authenticated?
+      access_token && !token_expired?
+    end
+
+    def authenticate!(authorization_code:, code_verifier: nil)
+      @access_token = oauth.get_token(
+        authorization_code: authorization_code,
+        code_verifier: code_verifier
+      )
+    end
+
+    def refresh_token!
+      raise MangoApps::TokenExpiredError, "No refresh token available" unless access_token&.refresh_token
+
+      @access_token = oauth.refresh!(access_token)
+    end
+
+    # ---- HTTP Methods ----
+    def get(path, params: {}, headers: {})
+      request(:get, path, params: params, headers: headers)
+    end
+
+    def post(path, body: nil, headers: {})
+      request(:post, path, body: body, headers: headers)
+    end
+
+    def put(path, body: nil, headers: {})
+      request(:put, path, body: body, headers: headers)
+    end
+
+    def delete(path, headers: {})
+      request(:delete, path, headers: headers)
+    end
+
+    # ---- OAuth Helpers ----
+    def authorization_url(state:, code_challenge: nil, code_challenge_method: "S256", **extra_params)
+      oauth.authorization_url(
+        state: state,
+        code_challenge: code_challenge,
+        code_challenge_method: code_challenge_method,
+        extra_params: extra_params
+      )
+    end
+
+    def get_userinfo
+      case config.authentication_method
+      when :internal_api
+        # For internal API, we can't use OAuth userinfo endpoint
+        # Instead, we'll use the /me endpoint which provides user info
+        response = get("v2/me.json")
+        response.user_profile.minimal_profile
+      when :oauth
+        raise MangoApps::TokenExpiredError, "No access token available" unless access_token
+        
+        userinfo_data = oauth.get_userinfo(access_token.token)
+        MangoApps::Response.new(userinfo_data)
+      else
+        raise MangoApps::AuthenticationError, "No authentication method available"
+      end
+    end
+
+    private
+
+    def build_http_client
+      Faraday.new(url: config.api_base) do |f|
+        f.request :retry, retry_options
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.options.timeout = config.timeout
+        f.options.open_timeout = config.open_timeout
+        f.response :logger, config.logger if config.logger
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def retry_options
+      {
+        max: 3,
+        interval: 0.3,
+        backoff_factor: 2,
+        methods: %i[get post put delete],
+        exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed],
+      }
+    end
+
+    def request(method, path, params: nil, body: nil, headers: {})
+      ensure_authenticated!
+
+      # Store request details for error reporting
+      request_details = {
+        method: method.to_s.upcase,
+        url: "#{config.api_base}#{path}",
+        params: params,
+        body: body,
+        headers: auth_headers.merge(headers)
+      }
+
+      response = http.run_request(
+        method,
+        path,
+        (body.nil? ? nil : MultiJson.dump(body)),
+        auth_headers.merge(headers)
+      ) do |req|
+        req.params.update(params) if params
+      end
+
+      return wrap_response(response.body) if response.success?
+
+      handle_error_response(response, request_details)
+    end
+
+    def auth_headers
+      case config.authentication_method
+      when :internal_api
+        headers = {
+          "Internal-Api-Key" => config.internal_api_key,
+          "Internal-Api-Secret" => config.internal_api_secret
+        }
+        headers
+      when :oauth
+        { "Authorization" => "Bearer #{access_token.token}" }
+      else
+        {}
+      end
+    end
+
+    def ensure_authenticated!
+      return if authenticated? || config.has_internal_api_credentials?
+
+      raise MangoApps::AuthenticationError, "Not authenticated. Complete OAuth flow or provide internal API credentials."
+    end
+
+    def load_access_token
+      # First try to use stored token from .env
+      if config.has_valid_token?
+        # Create a simple token object from stored token
+        stored_token = OpenStruct.new(
+          token: config.access_token,
+          refresh_token: config.refresh_token,
+          expires_at: ENV["MANGOAPPS_TOKEN_EXPIRES_AT"]&.to_i
+        )
+        return stored_token
+      end
+      
+      # Fallback to oauth token store
+      oauth.load_token
+    end
+
+    def token_expired?
+      return true unless access_token
+
+      # Check if token expires within the next 5 minutes
+      if access_token.expires_at
+        expires_at = access_token.expires_at.is_a?(Integer) ? Time.at(access_token.expires_at) : access_token.expires_at
+        expires_at < (Time.now + 300)
+      else
+        false
+      end
+    end
+
+    def handle_error_response(response, request_details = nil)
+      error_class = case response.status
+                    when 400 then MangoApps::BadRequestError
+                    when 401 then MangoApps::UnauthorizedError
+                    when 403 then MangoApps::ForbiddenError
+                    when 404 then MangoApps::NotFoundError
+                    when 429 then MangoApps::RateLimitError
+                    when 500..599 then MangoApps::ServerError
+                    else MangoApps::APIError
+                    end
+
+      error_message = extract_error_message(response)
+      raise error_class.new(
+        error_message,
+        status_code: response.status,
+        response_body: response.body,
+        request_details: request_details
+      )
+    end
+
+    def wrap_response(data)
+      return data unless data.is_a?(Hash)
+      
+      MangoApps::Response.new(data)
+    end
+
+    def extract_error_message(response)
+      if response.body.is_a?(Hash) && response.body["error"]
+        response.body["error"]
+      elsif response.body.is_a?(Hash) && response.body["message"]
+        response.body["message"]
+      else
+        "MangoApps API error: #{response.status}"
+      end
+    end
+  end
+end

data/lib/mangoapps/config.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "dotenv"
+
+module MangoApps
+  class Config
+    attr_accessor :domain, :client_id, :client_secret, :redirect_uri, :scope,
+                  :token_store, :timeout, :open_timeout, :logger, :access_token, :refresh_token,
+                  :internal_api_key, :internal_api_secret, :test_header
+
+    def initialize(domain: nil, client_id: nil, client_secret: nil, redirect_uri: nil, scope: nil, # rubocop:disable Metrics/ParameterLists
+                   token_store: nil, timeout: 30, open_timeout: 10, logger: nil,
+                   internal_api_key: nil, internal_api_secret: nil, test_header: nil)
+      # Load environment variables from .env file
+      Dotenv.load if File.exist?(".env")
+
+      @domain        = domain || ENV.fetch("MANGOAPPS_DOMAIN", nil)
+      @client_id     = client_id || ENV.fetch("MANGOAPPS_CLIENT_ID", nil)
+      @client_secret = client_secret || ENV.fetch("MANGOAPPS_CLIENT_SECRET", nil)
+      @redirect_uri  = redirect_uri || ENV["MANGOAPPS_REDIRECT_URI"] || "https://localhost:3000/oauth/callback"
+      @scope         = scope || ENV["MANGOAPPS_SCOPE"] || "openid profile email"
+      @access_token  = ENV["MANGOAPPS_ACCESS_TOKEN"]
+      @refresh_token = ENV["MANGOAPPS_REFRESH_TOKEN"]
+      @internal_api_key = internal_api_key || ENV["MANGOAPPS_INTERNAL_API_KEY"]
+      @internal_api_secret = internal_api_secret || ENV["MANGOAPPS_INTERNAL_API_SECRET"]
+      @test_header = test_header || ENV["MANGOAPPS_TEST_HEADER"]
+      @token_store   = token_store
+      @timeout       = timeout
+      @open_timeout  = open_timeout
+      @logger        = logger
+
+      validate_required_fields!
+      
+      # Show authentication method being used
+      show_authentication_method
+    end
+
+    def base_url  = "https://#{domain}"
+    def api_base  = "#{base_url}/api/"
+    
+    def token_expired?
+      return true unless ENV["MANGOAPPS_TOKEN_EXPIRES_AT"]
+      Time.now.to_i >= ENV["MANGOAPPS_TOKEN_EXPIRES_AT"].to_i
+    end
+    
+    def has_valid_token?
+      @access_token && !token_expired?
+    end
+
+    def has_internal_api_credentials?
+      @internal_api_key && @internal_api_secret && !@internal_api_key.empty? && !@internal_api_secret.empty?
+    end
+
+    def authentication_method
+      if has_internal_api_credentials?
+        :internal_api
+      elsif has_valid_token?
+        :oauth
+      else
+        :none
+      end
+    end
+
+    def show_authentication_method
+      case authentication_method
+      when :internal_api
+        puts "🔑 Using Internal API authentication"
+        puts "   Domain: #{@domain}"
+        puts "   API Key: #{@internal_api_key[0..7]}..."
+      when :oauth
+        puts "🔐 Using OAuth2 authentication"
+        puts "   Domain: #{@domain}"
+        puts "   Client ID: #{@client_id[0..7]}..."
+        puts "   Redirect URI: #{@redirect_uri}"
+      end
+    end
+
+    private
+
+    def validate_required_fields!
+      missing_fields = []
+      missing_fields << "domain" if @domain.nil? || @domain.empty?
+
+      # Check if we have either OAuth or Internal API credentials
+      has_oauth = @client_id && @client_secret && !@client_id.empty? && !@client_secret.empty?
+      has_internal_api = has_internal_api_credentials?
+
+      unless has_oauth || has_internal_api
+        missing_fields << "authentication credentials (either OAuth client_id/client_secret or internal_api_key/internal_api_secret)"
+      end
+
+      if missing_fields.any?
+        raise ArgumentError, "Missing required configuration: #{missing_fields.join(', ')}. " \
+                             "Set environment variables or pass as parameters."
+      end
+    end
+  end
+end

data/lib/mangoapps/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MangoApps
+  # Base error class for all MangoApps SDK errors
+  class Error < StandardError; end
+
+  # Configuration related errors
+  class ConfigurationError < Error; end
+
+  # Authentication related errors
+  class AuthenticationError < Error; end
+  class TokenExpiredError < AuthenticationError; end
+  class InvalidCredentialsError < AuthenticationError; end
+
+  # OAuth/OIDC related errors
+  class OAuthError < Error; end
+  class DiscoveryError < OAuthError; end
+  class TokenExchangeError < OAuthError; end
+
+  # API related errors
+  class APIError < Error
+    attr_reader :status_code, :response_body, :request_details
+
+    def initialize(message, status_code: nil, response_body: nil, request_details: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+      @request_details = request_details
+    end
+  end
+
+  # HTTP related errors
+  class HTTPError < APIError; end
+  class BadRequestError < APIError; end
+  class UnauthorizedError < APIError; end
+  class ForbiddenError < APIError; end
+  class NotFoundError < APIError; end
+  class RateLimitError < APIError; end
+  class ServerError < APIError; end
+
+  # Client related errors
+  class ClientError < Error; end
+  class TimeoutError < ClientError; end
+  class ConnectionError < ClientError; end
+end

data/lib/mangoapps/modules/attachments/get_folder_files.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Attachments
+      module GetFolderFiles
+        def get_folder_files(folder_id, include_folders: "Y", page: 1, limit: 20, params: {})
+          params = params.merge(include_folders: include_folders, page: page, limit: limit)
+          get("folders/#{folder_id}/files.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/attachments/get_folders.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Attachments
+      module GetFolders
+        def get_folders(page: 1, limit: 20, params: {})
+          params = params.merge(page: page, limit: limit)
+          get("folders.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/attachments.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "attachments/get_folders"
+require_relative "attachments/get_folder_files"
+
+module MangoApps
+  class Client
+    module Attachments
+      # Include all attachments sub-modules
+      include MangoApps::Client::Attachments::GetFolders
+      include MangoApps::Client::Attachments::GetFolderFiles
+    end
+  end
+end

data/lib/mangoapps/modules/feeds/feeds.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Feeds
+      module Feeds
+        def feeds(page: 1, limit: 20, params: {})
+          params = params.merge(page: page, limit: limit)
+          get("feeds.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/feeds.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "feeds/feeds"
+
+module MangoApps
+  class Client
+    module Feeds
+      # Include all feeds sub-modules
+      include MangoApps::Client::Feeds::Feeds
+    end
+  end
+end

data/lib/mangoapps/modules/learn/course_catalog.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Learn
+      module CourseCatalog
+        # Get course catalog from MangoApps Learn API
+        # GET /api/v2/learn/course_catalog.json
+        def course_catalog(page: 1, limit: 20, params: {})
+          params = params.merge(page: page, limit: limit)
+          get("v2/learn/course_catalog.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/learn/course_categories.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Learn
+      module CourseCategories
+        # Get course categories from MangoApps Learn API
+        # GET /api/v2/learn/course_categories.json
+        def course_categories(page: 1, limit: 20, params: {})
+          params = params.merge(page: page, limit: limit)
+          get("v2/learn/course_categories.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/learn/course_details.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Learn
+      module CourseDetails
+        def course_details(course_id, params = {})
+          get("v2/learn/courses/#{course_id}.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/learn/my_learning.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Learn
+      module MyLearning
+        def my_learning(params = {})
+          get("v2/learn/my_learning.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/learn.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "learn/course_catalog"
+require_relative "learn/course_categories"
+require_relative "learn/course_details"
+require_relative "learn/my_learning"
+
+module MangoApps
+  class Client
+    module Learn
+      # Include all learn sub-modules
+      include MangoApps::Client::Learn::CourseCatalog
+      include MangoApps::Client::Learn::CourseCategories
+      include MangoApps::Client::Learn::CourseDetails
+      include MangoApps::Client::Learn::MyLearning
+    end
+  end
+end

data/lib/mangoapps/modules/libraries/get_libraries.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Libraries
+      module GetLibraries
+        def get_libraries(page: 1, limit: 20, params: {})
+          params = params.merge(page: page, limit: limit)
+          get("users/libraries/get_libraries.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/libraries/get_library_categories.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Libraries
+      module GetLibraryCategories
+        def get_library_categories(library_id, page: 1, limit: 20, params: {})
+          params = params.merge(page: page, limit: limit)
+          get("users/libraries/#{library_id}.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/libraries/get_library_items.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Libraries
+      module GetLibraryItems
+        def get_library_items(library_id, category_id, page: 1, limit: 20, params: {})
+          params = params.merge(page: page, limit: limit)
+          get("users/libraries/#{library_id}/categories/#{category_id}/library_items/get_library_items.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/libraries.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "libraries/get_libraries"
+require_relative "libraries/get_library_categories"
+require_relative "libraries/get_library_items"
+
+module MangoApps
+  class Client
+    module Libraries
+      # Include all libraries sub-modules
+      include MangoApps::Client::Libraries::GetLibraries
+      include MangoApps::Client::Libraries::GetLibraryCategories
+      include MangoApps::Client::Libraries::GetLibraryItems
+    end
+  end
+end

data/lib/mangoapps/modules/notifications/my_priority_items.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Notifications
+      module MyPriorityItems
+        def my_priority_items(params = {})
+          get("v2/uac.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/notifications/notifications.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Notifications
+      module Notifications
+        def notifications(page: 1, limit: 20, params: {})
+          params = params.merge(page: page, limit: limit)
+          get("users/notifications.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/notifications.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "notifications/my_priority_items"
+require_relative "notifications/notifications"
+
+module MangoApps
+  class Client
+    module Notifications
+      # Include all notifications sub-modules
+      include MangoApps::Client::Notifications::MyPriorityItems
+      include MangoApps::Client::Notifications::Notifications
+    end
+  end
+end

data/lib/mangoapps/modules/posts/get_all_posts.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Posts
+      module GetAllPosts
+        def get_all_posts(filter_by: "all", page: 1, limit: 20, params: {})
+          params = params.merge(filter_by: filter_by, page: page, limit: limit)
+          get("posts/get_all_posts.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/posts/get_post_by_id.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MangoApps
+  class Client
+    module Posts
+      module GetPostById
+        def get_post_by_id(post_id, params = {})
+          get("posts/#{post_id}.json", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/mangoapps/modules/posts.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "posts/get_all_posts"
+require_relative "posts/get_post_by_id"
+
+module MangoApps
+  class Client
+    module Posts
+      # Include all posts sub-modules
+      include MangoApps::Client::Posts::GetAllPosts
+      include MangoApps::Client::Posts::GetPostById
+    end
+  end
+end