resourcespace-ruby 0.1.0

data/lib/resourcespace/search.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module ResourceSpace
+  # Search interface for ResourceSpace API
+  #
+  # @example
+  #   search = client.search
+  #
+  #   # Basic search
+  #   results = search.do_search("cat")
+  #
+  #   # Advanced search with parameters
+  #   results = search.do_search("web assets", {
+  #     order_by: "date",
+  #     sort: "desc",
+  #     fetchrows: 20
+  #   })
+  #
+  #   # Search with previews
+  #   results = search.search_get_previews("images", {
+  #     getsizes: "col,thm,scr",
+  #     fetchrows: 10
+  #   })
+  class Search
+    # @return [Client] the ResourceSpace client
+    attr_reader :client
+
+    # Initialize the search interface
+    #
+    # @param client [Client] ResourceSpace client instance
+    def initialize(client)
+      @client = client
+    end
+
+    # Perform a basic search
+    #
+    # @param search_term [String] search term
+    # @param options [Hash] search options
+    # @option options [String] :restypes resource types to search (e.g., "1,2,3")
+    # @option options [String] :order_by field to order by ("relevance", "popularity", "date", "colour", "country", "title", "file_path", "resourceid", "extension", "user", "created")
+    # @option options [String] :sort sort direction ("asc" or "desc")
+    # @option options [Integer] :offset starting offset for results
+    # @option options [Integer] :fetchrows number of results to fetch
+    # @option options [String] :archive archive status ("0" = live resources, "1" = archived, "2" = both)
+    # @option options [Integer] :daylimit only return resources modified in the last X days
+    # @return [Hash] search results
+    def do_search(search_term, options = {})
+      params = build_search_params(search_term, options)
+      client.get("do_search", params)
+    end
+
+    # Search and get previews in one call
+    #
+    # @param search_term [String] search term
+    # @param options [Hash] search options
+    # @option options [String] :getsizes image sizes to include ("col,thm,scr,pre")
+    # @option options [String] :order_by field to order by
+    # @option options [String] :sort sort direction ("asc" or "desc")
+    # @option options [Integer] :fetchrows number of results to fetch
+    # @option options [String] :archive archive status
+    # @return [Hash] search results with preview data
+    def search_get_previews(search_term, options = {})
+      params = build_search_params(search_term, options)
+      params[:param6] = options[:getsizes] if options[:getsizes]
+
+      client.get("search_get_previews", params)
+    end
+
+    # Search for web assets (images, CSS, JS, fonts)
+    #
+    # @param asset_type [String] type of web asset ("image", "css", "javascript", "font", "icon")
+    # @param options [Hash] search options
+    # @return [Hash] search results filtered for web assets
+    def search_web_assets(asset_type = nil, options = {})
+      search_terms = []
+
+      case asset_type&.downcase
+      when "image", "images"
+        search_terms << "extension:jpg OR extension:jpeg OR extension:png OR extension:gif OR extension:svg OR extension:webp"
+      when "css", "stylesheet", "stylesheets"
+        search_terms << "extension:css"
+      when "javascript", "js"
+        search_terms << "extension:js"
+      when "font", "fonts"
+        search_terms << "extension:woff OR extension:woff2 OR extension:ttf OR extension:otf OR extension:eot"
+      when "icon", "icons"
+        search_terms << "extension:ico OR extension:svg"
+      else
+        # Search for all common web asset types
+        search_terms << "extension:jpg OR extension:jpeg OR extension:png OR extension:gif OR extension:svg OR extension:webp OR extension:css OR extension:js OR extension:woff OR extension:woff2 OR extension:ico"
+      end
+
+      search_term = search_terms.join(" OR ")
+      search_term += " #{options.delete(:query)}" if options[:query]
+
+      do_search(search_term, options)
+    end
+
+    # Search resources by file extension
+    #
+    # @param extensions [String, Array] file extension(s) to search for
+    # @param options [Hash] search options
+    # @return [Hash] search results
+    def search_by_extension(extensions, options = {})
+      extensions = Array(extensions).map(&:to_s)
+      search_term = extensions.map { |ext| "extension:#{ext.gsub(/^\./, '')}" }.join(" OR ")
+
+      do_search(search_term, options)
+    end
+
+    # Search resources by date range
+    #
+    # @param from_date [Date, String] start date (YYYY-MM-DD format)
+    # @param to_date [Date, String] end date (YYYY-MM-DD format)
+    # @param options [Hash] search options
+    # @return [Hash] search results
+    def search_by_date_range(from_date, to_date = nil, options = {})
+      from_str = format_date(from_date)
+      to_str = to_date ? format_date(to_date) : from_str
+
+      search_term = "created:#{from_str}"
+      search_term += ";#{to_str}" if to_date
+
+      do_search(search_term, options)
+    end
+
+    # Search resources by collection
+    #
+    # @param collection_id [Integer] collection ID
+    # @param options [Hash] search options
+    # @return [Hash] search results
+    def search_by_collection(collection_id, options = {})
+      search_term = "!collection#{collection_id}"
+      do_search(search_term, options)
+    end
+
+    # Search resources by resource IDs
+    #
+    # @param resource_ids [Array<Integer>] array of resource IDs
+    # @param options [Hash] search options
+    # @return [Hash] search results
+    def search_by_ids(resource_ids, options = {})
+      ids = Array(resource_ids).join(":")
+      search_term = "!list#{ids}"
+      do_search(search_term, options)
+    end
+
+    # Get recently added resources
+    #
+    # @param count [Integer] number of recent resources to return
+    # @param options [Hash] search options
+    # @return [Hash] search results
+    def recent_resources(count = 10, options = {})
+      search_term = "!last#{count}"
+      do_search(search_term, options)
+    end
+
+    # Search resources by tag
+    #
+    # @param tag [String] tag name
+    # @param options [Hash] search options
+    # @return [Hash] search results
+    def search_by_tag(tag, options = {})
+      search_term = "tag:#{tag}"
+      do_search(search_term, options)
+    end
+
+    # Search resources by user
+    #
+    # @param username [String] username
+    # @param options [Hash] search options
+    # @return [Hash] search results
+    def search_by_user(username, options = {})
+      search_term = "user:#{username}"
+      do_search(search_term, options)
+    end
+
+    # Search resources by title/name
+    #
+    # @param title [String] resource title
+    # @param options [Hash] search options
+    # @return [Hash] search results
+    def search_by_title(title, options = {})
+      search_term = "title:#{title}"
+      do_search(search_term, options)
+    end
+
+    # Advanced search with multiple criteria
+    #
+    # @param criteria [Hash] search criteria
+    # @option criteria [String] :title title search
+    # @option criteria [String] :tag tag search
+    # @option criteria [String] :user user search
+    # @option criteria [Array<String>] :extensions file extensions
+    # @option criteria [String] :from_date start date
+    # @option criteria [String] :to_date end date
+    # @param options [Hash] search options
+    # @return [Hash] search results
+    def advanced_search(criteria = {}, options = {})
+      search_parts = []
+
+      search_parts << "title:#{criteria[:title]}" if criteria[:title]
+      search_parts << "tag:#{criteria[:tag]}" if criteria[:tag]
+      search_parts << "user:#{criteria[:user]}" if criteria[:user]
+
+      if criteria[:extensions]
+        ext_search = Array(criteria[:extensions]).map { |ext| "extension:#{ext.gsub(/^\./, '')}" }.join(" OR ")
+        search_parts << "(#{ext_search})"
+      end
+
+      if criteria[:from_date]
+        date_search = "created:#{format_date(criteria[:from_date])}"
+        date_search += ";#{format_date(criteria[:to_date])}" if criteria[:to_date]
+        search_parts << date_search
+      end
+
+      search_term = search_parts.join(" AND ")
+      search_term = criteria[:query] if search_term.empty? && criteria[:query]
+
+      do_search(search_term, options)
+    end
+
+    private
+
+    # Build search parameters hash
+    #
+    # @param search_term [String] search term
+    # @param options [Hash] search options
+    # @return [Hash] parameters hash
+    def build_search_params(search_term, options = {})
+      params = { param1: search_term }
+
+      params[:param2] = options[:restypes] if options[:restypes]
+      params[:param3] = options[:order_by] if options[:order_by]
+      params[:param4] = options[:offset] if options[:offset]
+      params[:param5] = options[:fetchrows] if options[:fetchrows]
+      params[:param6] = options[:sort] if options[:sort]
+      params[:param7] = options[:archive] if options[:archive]
+      params[:param8] = options[:daylimit] if options[:daylimit]
+
+      params
+    end
+
+    # Format date for ResourceSpace API
+    #
+    # @param date [Date, String] date to format
+    # @return [String] formatted date string
+    def format_date(date)
+      case date
+      when Date
+        date.strftime("%Y-%m-%d")
+      when Time
+        date.strftime("%Y-%m-%d")
+      else
+        date.to_s
+      end
+    end
+  end
+end

data/lib/resourcespace/user.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module ResourceSpace
+  # User management interface for ResourceSpace API
+  #
+  # @example
+  #   users = client.users
+  #
+  #   # Get user list
+  #   all_users = users.get_users
+  #
+  #   # Check permissions
+  #   can_edit = users.check_permission("r")
+  class User
+    # @return [Client] the ResourceSpace client
+    attr_reader :client
+
+    # Initialize the user interface
+    #
+    # @param client [Client] ResourceSpace client instance
+    def initialize(client)
+      @client = client
+    end
+
+    # Get list of users
+    #
+    # @return [Array] array of user data
+    def get_users
+      client.get("get_users")
+    end
+
+    # Get users by permission
+    #
+    # @param permission [String] permission to check
+    # @return [Array] users with the specified permission
+    def get_users_by_permission(permission)
+      client.get("get_users_by_permission", { param1: permission })
+    end
+
+    # Check if current user has a permission
+    #
+    # @param permission [String] permission to check
+    # @return [Boolean] true if user has permission
+    def check_permission(permission)
+      response = client.get("checkperm", { param1: permission })
+      response == true || response == "true" || response == 1 || response == "1"
+    end
+
+    # Login and get a session key
+    #
+    # @param username [String] username
+    # @param password [String] password
+    # @return [String] session key for subsequent requests
+    def login(username, password)
+      response = client.get("login", {
+        param1: username,
+        param2: password
+      })
+
+      # The response should be a session key
+      response.is_a?(Hash) ? response["key"] || response["session_key"] : response
+    end
+
+    # Mark an email as invalid
+    #
+    # @param email [String] email address to mark as invalid
+    # @return [Hash] response
+    def mark_email_as_invalid(email)
+      client.post("mark_email_as_invalid", { param1: email })
+    end
+
+    # Get user message
+    #
+    # @param message_id [Integer] message ID
+    # @return [Hash] message details
+    def get_user_message(message_id)
+      client.get("get_user_message", { param1: message_id.to_s })
+    end
+
+    # Check if user can access a specific resource
+    #
+    # @param resource_id [Integer] resource ID
+    # @return [Boolean] true if user can access the resource
+    def can_access_resource?(resource_id)
+      begin
+        access_level = client.resources.get_resource_access(resource_id)
+        access_level >= 0 # 0 = open access, -1 = no access
+      rescue NotFoundError, AuthorizationError
+        false
+      end
+    end
+
+    # Check if user can edit a specific resource
+    #
+    # @param resource_id [Integer] resource ID
+    # @return [Boolean] true if user can edit the resource
+    def can_edit_resource?(resource_id)
+      client.resources.edit_access?(resource_id)
+    end
+
+    # Get current user information
+    #
+    # @return [Hash] current user data
+    def current_user
+      # Note: ResourceSpace API doesn't have a direct "current user" endpoint
+      # This would typically be implemented by getting user info based on the authenticated user
+      # For now, we'll use the username from configuration and search for it
+      users = get_users
+      users.find { |user| user["username"] == client.config.user }
+    end
+
+    # Check multiple permissions at once
+    #
+    # @param permissions [Array<String>] array of permissions to check
+    # @return [Hash] hash of permission => boolean pairs
+    def check_permissions(permissions)
+      result = {}
+      Array(permissions).each do |permission|
+        result[permission] = check_permission(permission)
+      end
+      result
+    end
+
+    # Get users with administrative privileges
+    #
+    # @return [Array] admin users
+    def get_admin_users
+      # Typically admin users have 'a' permission
+      get_users_by_permission("a")
+    end
+
+    # Check if current user is an admin
+    #
+    # @return [Boolean] true if user is admin
+    def admin?
+      check_permission("a")
+    end
+
+    # Check if current user can manage users
+    #
+    # @return [Boolean] true if user can manage users
+    def can_manage_users?
+      check_permission("u")
+    end
+
+    # Check if current user can manage collections
+    #
+    # @return [Boolean] true if user can manage collections
+    def can_manage_collections?
+      check_permission("k")
+    end
+
+    # Check if current user can upload files
+    #
+    # @return [Boolean] true if user can upload files
+    def can_upload?
+      check_permission("c")
+    end
+
+    # Check if current user can download files
+    #
+    # @return [Boolean] true if user can download files
+    def can_download?
+      check_permission("d")
+    end
+
+    # Check if current user can edit resources
+    #
+    # @return [Boolean] true if user can edit resources
+    def can_edit_resources?
+      check_permission("e")
+    end
+
+    # Get user capabilities summary
+    #
+    # @return [Hash] summary of user capabilities
+    def capabilities
+      {
+        admin: admin?,
+        manage_users: can_manage_users?,
+        manage_collections: can_manage_collections?,
+        upload: can_upload?,
+        download: can_download?,
+        edit_resources: can_edit_resources?
+      }
+    end
+  end
+end

data/lib/resourcespace/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ResourceSpace
+  # The current version of the ResourceSpace Ruby gem
+  VERSION = "0.1.0"
+end

data/lib/resourcespace.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "resourcespace/version"
+require_relative "resourcespace/client"
+require_relative "resourcespace/configuration"
+require_relative "resourcespace/errors"
+require_relative "resourcespace/resource"
+require_relative "resourcespace/collection"
+require_relative "resourcespace/search"
+require_relative "resourcespace/user"
+require_relative "resourcespace/metadata"
+
+# ResourceSpace Ruby client for interacting with ResourceSpace Digital Asset Management API
+#
+# @example Basic usage
+#   client = ResourceSpace::Client.new(
+#     url: "https://your-resourcespace.com/api/",
+#     user: "your_username",
+#     private_key: "your_private_key"
+#   )
+#
+#   # Search for resources
+#   results = client.search.do_search("cat")
+#
+#   # Upload a file
+#   resource = client.resources.create_resource(
+#     name: "My Image",
+#     file: File.open("path/to/image.jpg")
+#   )
+#
+# @see https://www.resourcespace.com/knowledge-base/api/
+module ResourceSpace
+  class << self
+    # Global configuration for the ResourceSpace gem
+    #
+    # @return [Configuration] the global configuration instance
+    attr_accessor :configuration
+
+    # Configure the ResourceSpace gem globally
+    #
+    # @yield [Configuration] the configuration instance
+    # @return [Configuration] the updated configuration
+    #
+    # @example
+    #   ResourceSpace.configure do |config|
+    #     config.url = "https://your-resourcespace.com/api/"
+    #     config.user = "your_username"
+    #     config.private_key = "your_private_key"
+    #     config.timeout = 30
+    #   end
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Get the current configuration or create a new one
+    #
+    # @return [Configuration] the configuration instance
+    def config
+      self.configuration ||= Configuration.new
+    end
+
+    # Reset the configuration to defaults
+    #
+    # @return [Configuration] a new configuration instance
+    def reset_config!
+      self.configuration = Configuration.new
+    end
+  end
+end

data/resourcespace-ruby.gemspec

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = "resourcespace-ruby"
+  spec.version       = "0.1.0"
+  spec.authors       = ["Survey Flunkie Team"]
+  spec.email         = ["info@surveyflunkie.com"]
+
+  spec.summary       = "Ruby client for ResourceSpace Digital Asset Management API"
+  spec.description   = "A comprehensive Ruby client library for interacting with ResourceSpace open-source Digital Asset Management system. Supports resource management, file uploads, searching, collections, and metadata operations."
+  spec.homepage      = "https://github.com/survey-flunkie/resourcespace-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/survey-flunkie/resourcespace-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/survey-flunkie/resourcespace-ruby/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/resourcespace-ruby"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", "~> 2.7"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+  spec.add_dependency "mime-types", "~> 3.4"
+  spec.add_dependency "json", "~> 2.6"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "webmock", "~> 3.18"
+  spec.add_development_dependency "vcr", "~> 6.1"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
+  spec.add_development_dependency "yard", "~> 0.9"
+end